Skip to content

CamilleScholtz/swmpc / .agents/skills/localization

localization

Verified

Inspect and edit Xcode String Catalogs (.xcstrings) via bundled l10n.sh and find_unused_keys.sh scripts, and apply Apple localization conventions.

FileKindSize
SKILL.mdskill md4.7 KB
references/best-practices.mdmarkdown5.5 KB
scripts/find_unused_keys.shexecutablescript3.9 KB
scripts/l10n.shexecutablescript13.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.
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall