cmux Localization

Use this skill for any user-facing string change.

Normal contributor flow

After adding or changing user-facing copy, run ./scripts/localize-changes.

The command compares the current worktree with the mainline base, discovers changed Swift localization keys and English web messages, prepares simple new or changed macOS catalog entries with minimal edits, and writes a machine-readable translation packet under git metadata. Fill value for simple translations or localization for plural or variant entries, then run the same command again. When an existing translation is still correct after an English change, fill value with that same text; the packet remembers the confirmation so later runs do not mark it for review again. Completed macOS rows are imported through scripts/localization_catalog.py merge, and scripts/localization_catalog.py check remains the final authoritative validator.

Use --base <ref> for another comparison base and --work-file <path> when a translation helper needs a visible packet. The default packet stays outside the worktree. Ambiguous catalog ownership, a key whose Swift call sites (changed or not) disagree on defaultValue, count-like new strings, unsupported Swift literal forms, and invalid generated translations stop with a concrete human-attention item so the existing placeholder, plural, bidi, omission, identity-translation, copied-English, and catalog checks stay intact.

Hard rules

• Every user-facing string is localized. Never a bare string literal in SwiftUI Text(), Button(), alert titles, tooltips, menus, or dialogs.
• Swift/AppKit/SwiftUI: String(localized: "key.name", defaultValue: "English text"), with keys in Resources/Localizable.xcstrings. Every feature PR includes translated entries for all supported macOS languages required by scripts/localization_catalog.py (currently en, de, fr, ar, es, zh-Hant, zh-Hans, ko, ja), subject to the exact omission records below. English and Japanese entries are always required.
• defaultValue, English fallback text, schema descriptions, and copied English strings do not count as localization. Record deliberate invariant literals in scripts/localization-allowed-omissions.json, with the exact source and omission class. A correct translation that shares the English spelling needs a documented identityLocales exception for that key and locale; the translated entry remains required.
• Localized web/docs content updates every locale declared by web/i18n/routing.ts, with a matching web/messages/<locale>.json entry plus any localized data structures carrying inline translations.
• A localization audit is required for every user-facing change.