CamilleScholtz/swmpc / .agents/skills/localization
localization
VerifiedInspect and edit Xcode String Catalogs (.xcstrings) via bundled l10n.sh and find_unused_keys.sh scripts, and apply Apple localization conventions.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.7 KB |
| references/best-practices.md | markdown | 5.5 KB |
| scripts/find_unused_keys.shexecutable | script | 3.9 KB |
| scripts/l10n.shexecutable | script | 13.3 KB |
references/best-practices.md
View on GitHub# Localization best practices (Apple)
Distilled from Apple's Xcode localization documentation: *Localizing and varying
text with a string catalog*, *Preparing your app's text for translation*, and
*Preparing dates, currencies, and numbers for translation*.
## Making text localizable
- **SwiftUI views**: string literals passed to `Text`, `Label`, `Button`, etc.
are `LocalizedStringKey` and automatically localizable — Xcode extracts them
into the string catalog at build time. No wrapping needed.
- **Non-view code**: use `String(localized:)` / `AttributedString(localized:)`,
never a bare literal, for any user-facing text.
- **Passing strings around**: declare parameters and properties as
`LocalizedStringResource` (Apple's recommended type), not `String`. It keeps
the string localizable at the point of display and supports comments, table
names, and default values. A plain `String` parameter freezes the text in
whatever language it was created in.
- **Separate key and value** when the source text is a poor key:
`String(localized: "LIGHTING_KEY", defaultValue: "Lightbulbs")`.
- **Frameworks / Swift packages**: strings living outside the main bundle must
pass their bundle: `String(localized: "Songs", bundle: #bundle)` (or
`Bundle(for: SomeClass.self)`). Never look up strings from bundles you don't
own — it breaks automatic extraction.
- **Multiple catalogs**: large projects can split strings into tables —
`Text("Explore", tableName: "Navigation")`, `String(localized:table:)` — one
`.xcstrings` file per table.
- **`NSLocalizedString`** is only for targets that predate `String(localized:)`.
## Comments for translators
Every string should carry context: what UI element it labels, where it appears,
and what each placeholder stands for. Translators (human or machine) only see
key + comment.
```swift
Text("Edit", comment: "The text label on a button to switch to editor mode.")
String(localized: "North America", comment: "The name of a continent.")
```
Comments can also be set directly in the catalog (`l10n.sh comment <key> <text>`).
Xcode can auto-generate comments (marked `isCommentAutoGenerated` in the JSON);
a hand-written comment is better and replaces the flag.
## Composing strings
- **Never concatenate sentence fragments** — word order differs across
languages. Keep the whole sentence in one key and interpolate:
`Text("\(name) added \(count) songs")`, not `Text(name) + Text(" added ")`.
- **Positional specifiers** (`%1$@`, `%2$lld`) let translators reorder
placeholders; multi-placeholder strings get them automatically on export.
- **Don't reuse one key** for different meanings/contexts ("Play" the verb vs.
a noun); give each context its own key with `defaultValue:` if needed.
- **Exclude non-translatable strings** (brand names, separators, symbols) with
`shouldTranslate: false` in the catalog rather than deleting them.
## Plurals and variants
- Never branch on count in code (`count == 1 ? "song" : "songs"`) — languages
have different plural categories. Use plural variations on the key: English
needs *one/other*; Russian needs *one/few/many/other*; some languages also
use *zero/two*. When adding a language, fill every category that language
requires (`l10n.sh set-plural <key> <lang> <category> <value>`).
- The catalog stores variants under
`localizations.<lang>.variations.plural.<category>.stringUnit`; a
localization has either a flat `stringUnit` **or** `variations`, never both.
- **Device variants** (`variations.device.<iphone|ipad|mac|…>`) handle
"Tap"/"Click"-style differences without `#if os()` in strings; width variants
adapt to available space.
## Dates, numbers, currencies, measurements
Never hand-format user-visible data — locale rules for separators, order, and
symbols differ. Use Foundation format styles; they localize automatically:
- Dates: `date.formatted()`, `date.formatted(date: .abbreviated, time: .omitted)`,
`date.formatted(.dateTime.year().month(.wide).day())`; in SwiftUI,
`Text(date, format: .dateTime…)`.
- Numbers/percentages: `value.formatted()`, `0.25.formatted(.percent)`.
- Currency: `amount.formatted(.currency(code: "EUR"))` — and represent money as
`Decimal`, never `Float`/`Double`.
- Durations: `Duration.seconds(2000).formatted(.time(pattern: .minuteSecond))`.
- Measurements: `Measurement(value:unit:).formatted()` converts units per
locale (miles vs. kilometers).
- Lists: `["a", "b", "c"].formatted(.list(type: .and))` — never
`joined(separator: ", ")` for display text.
Exception: machine-readable strings (log lines, filenames, ISO 8601
timestamps) should *not* be localized — use `.iso8601` or fixed formats.
## Catalog state discipline
- A translation unit's `state` is `new`, `translated`, or `needs_review`; only
`translated` counts as done. Mark unreviewed machine translations
`needs_review` so they're auditable.
- `extractionState: "stale"` means Xcode no longer finds the key in code —
review and delete these (`l10n.sh stale`).
- Xcode re-populates the catalog on every build: renaming a key here without
updating the code re-adds the old key on the next build.
## Testing localizations
- Preview per-locale in SwiftUI:
`#Preview { ContentView().environment(\.locale, Locale(identifier: "fr_FR")) }`.
- Run the app in another language via the scheme's App Language setting, or
test formatters directly with `.locale(Locale(identifier: "fr_FR"))`.
- Use Xcode's pseudolanguages (Double-Length, Right-to-Left) to catch clipped
layouts and hard-coded directionality before translating.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |