Cmux Localization

cmux Localization

Use this skill for any user-facing string change.

Hard rules

• All user-facing strings must be localized.
• Use String(localized: "key.name", defaultValue: "English text") for Swift/AppKit/SwiftUI strings.
• Keys go in Resources/Localizable.xcstrings with translations for all supported languages, currently English and Japanese.
• Never use bare string literals in SwiftUI Text(), Button(), alert titles, tooltips, menus, or dialogs.
• Localization audit is required for every user-facing change.
• defaultValue, English fallback text, schema descriptions, or copied English strings do not count as localization.
• For localized web/docs content, update every supported message catalog, currently web/messages/en.json and web/messages/ja.json, plus any localized data structures carrying inline translations.

Audit checklist

Before finishing a task that changes UI, Settings rows, menus, shortcut metadata, schema/config text, docs, command/help text, alerts, or tooltips:

1. Enumerate the changed user-facing surfaces. 2. Verify each surface has entries for every supported locale. 3. Parse touched localization files. 4. Compare changed message keys across locales. 5. Use rg over changed Swift/TS/TSX/docs files for newly introduced bare English. 6. State the localization audit in the final handoff, or explicitly say what could not be verified.

Related shortcut rule

Every new cmux-owned keyboard shortcut must be added to KeyboardShortcutSettings, visible/editable in Settings, supported in ~/.config/cmux/cmux.json, and documented in the keyboard shortcut and configuration docs.

Detailed reference

• Read references/audit-workflow.md for a deeper audit process, common false positives, and examples of surfaces that count as user-facing.

Localization Audit Workflow

This reference expands the localization rules for cmux.

What counts as user-facing

Treat text as user-facing if it can appear in:

• SwiftUI views
• AppKit menus and dialogs
• alerts and confirmation sheets
• tooltips and accessibility labels
• Settings rows and descriptions
• command palette entries
• keyboard shortcut metadata
• CLI help or command output
• JSON schema descriptions shown in docs or editors
• docs pages
• web UI
• generated configuration examples shown to users

Internal debug-only labels may still deserve localization if they are visible in the Debug menu or a debug window used by contributors.

Swift and AppKit

Use:

String(localized: "key.name", defaultValue: "English text")

Update Resources/Localizable.xcstrings for all supported languages. Currently that means English and Japanese.

Do not rely on defaultValue as the English localization. It is a fallback and development convenience, not a completed localization entry.

Web and docs

For localized web/docs content, update:

• web/messages/en.json
• web/messages/ja.json
• any localized data structures with inline translations

Keep keys aligned across locales. A key added only to English is incomplete even if the UI falls back at runtime.

Bare English search

After changing Swift, TS, TSX, or docs files, search the changed files for newly introduced user-facing English. Useful patterns include:

git diff --name-only -- '*.swift' '*.ts' '*.tsx' '*.md'
rg 'Text\\("[A-Z][^"]+"' -- '*.swift'
rg 'Button\\("[A-Z][^"]+"' -- '*.swift'
rg 'tooltip|alert|title|description|label' -- '*.swift' '*.ts' '*.tsx'

These searches are not proof by themselves. They are prompts to inspect likely user-facing strings.

Final handoff

Every UI/text-affecting final handoff should state:

• which surfaces changed
• which localization files were updated
• which audit commands or manual checks were run
• anything that could not be verified

If no user-facing strings changed, say that clearly.