Localization and Internationalization Support in cmux: Architecture and Implementation

cmux implements comprehensive localization and internationalization support using Apple's String(localized:defaultValue:) API, storing all translations in Resources/Localizable.xcstrings and enforcing a strict policy that prohibits raw string literals in user-facing code.

The cmux terminal multiplexer from manaflow-ai demonstrates modern macOS internationalization practices. Every piece of user-facing text—from menu items to error dialogs—is localized using Xcode string catalogs and Swift's localization APIs. This architecture ensures the application automatically adapts system locales while providing a maintainable workflow for adding new languages.

Core Architecture

The localization system in cmux follows Apple's contemporary i18n framework, separating translation data from presentation logic through a centralized string catalog approach.

Localization API Pattern

All user-facing strings utilize the String(localized:defaultValue:) initializer. In Sources/cmuxApp.swift, menu items declare both a semantic key and an English fallback:

Button(String(localized: "menu.file.newWindow", defaultValue: "New Window")) {
    // Action implementation
}

This pattern ensures that if a translation is missing for the user's locale, the interface gracefully degrades to the explicit default value rather than displaying a raw key identifier.

String Catalog Structure

Translations reside in Resources/Localizable.xcstrings, an Xcode string catalog file that compiles into the app bundle for efficient runtime lookup. This JSON-based format maps localization keys to their translated values across multiple languages. Info.plist-specific strings (such as CFBundleDisplayName) are stored separately in Resources/InfoPlist.xcstrings, maintaining a clear boundary between UI text and system metadata.

Development Policy Enforcement

The repository's CLAUDE.md explicitly mandates that all user-facing strings must use the localization API. Raw string literals are prohibited in UI code, ensuring comprehensive coverage and preventing untranslated text from reaching users. This policy is enforced during code review and is documented as a hard requirement for contributors.

Supported Languages

The Localizable.xcstrings file currently contains translations for 19 languages, including:

• en – English (default)
• ja – Japanese
• zh-Hans – Simplified Chinese
• zh-Hant – Traditional Chinese
• ko – Korean
• de – German
• es – Spanish
• fr – French
• it – Italian
• da – Danish
• pl – Polish
• ru – Russian
• bs – Bosnian
• ar – Arabic
• nb – Norwegian Bokmål
• pt-BR – Portuguese (Brazil)
• th – Thai
• tr – Turkish
• uk – Ukrainian

Adding a new language involves inserting entries under the "localizations" map for each key, or using Xcode's Export for Localization workflow to generate .xliff files for translation services.

Implementation Examples

SwiftUI Integration

cmux leverages SwiftUI's native string handling to keep view bodies language-agnostic. In Sources/ContentView.swift and Sources/SidebarSelectionState.swift, views consume localized strings directly:

Text(String(localized: "sidebar.title.sessions", defaultValue: "Sessions"))

Buttons, labels, and alerts throughout the SwiftUI layer follow this consistent pattern, ensuring that text rendering always passes through the localization framework.

Programmatic Error Handling

Non-UI components also utilize the API for user-facing messages. In Sources/TerminalController.swift, error alerts are constructed using localized keys:

let errorMessage = String(
    localized: "applescript.error.failedToCreateWindow",
    defaultValue: "Failed to create window."
)
showAlert(message: errorMessage)

This approach guarantees that even programmatically generated error messages respect the user's locale settings.

Adding New Translations

To add Italian support for the "New Window" menu item, developers edit Resources/Localizable.xcstrings:

"menu.file.newWindow": {
  "extractionState": "manual",
  "localizations": {
    "en": { "stringUnit": { "state": "translated", "value": "New Window" } },
    "it": { "stringUnit": { "state": "translated", "value": "Nuova Finestra" } }
  }
}

After rebuilding the application, macOS automatically displays "Nuova Finestra" when the system locale is set to Italian.

Runtime Behavior

When cmux launches, macOS determines the user's preferred locale and loads the corresponding translations from the compiled string catalog. The runtime lookup follows this sequence:

1. Key Lookup: The system searches for the key (e.g., "menu.file.newWindow") in the active locale's dictionary.
2. Fallback Chain: If the translation is missing, the framework returns the defaultValue specified in code.
3. Display: SwiftUI renders the resolved string in menus, dialogs, and interface elements.

Because keys are string literals, the compiler cannot verify their existence at build time. The CLAUDE.md policy mitigates this risk by requiring that every key exist in Localizable.xcstrings, treating the catalog as the single source of truth.

Summary

• cmux uses String(localized:defaultValue:) throughout Sources/cmuxApp.swift and UI components for all user-facing text.
• Translations are stored centrally in Resources/Localizable.xcstrings, with Info.plist strings in Resources/InfoPlist.xcstrings.
• The codebase supports 19 languages including Japanese, Chinese variants, European languages, and Arabic.
• CLAUDE.md enforces a strict policy prohibiting raw string literals in UI code, ensuring complete localization coverage.
• The runtime automatically falls back to English defaults when translations are missing, preventing broken UI experiences.

Frequently Asked Questions

How does cmux handle missing translations?

When a key is missing from the current locale's translation set, cmux falls back to the defaultValue parameter provided in the String(localized:defaultValue:) initializer. This ensures users always see readable English text rather than raw localization keys or empty strings.

Where are the translation files located in the cmux repository?

All UI translations reside in Resources/Localizable.xcstrings, while Info.plist-specific strings (like the app display name) are stored in Resources/InfoPlist.xcstrings. Both files use Xcode's JSON-based string catalog format and are compiled into the application bundle at build time.

What is the development policy regarding hardcoded strings in cmux?

According to CLAUDE.md, raw string literals are prohibited in any user-facing code. All text must use the String(localized:defaultValue:) API with appropriate keys defined in the string catalog. This policy ensures comprehensive localization coverage and prevents untranslated content from reaching production.

How many languages does cmux currently support?

As of the current implementation in Resources/Localizable.xcstrings, cmux supports 19 languages. These include English, Japanese, Simplified and Traditional Chinese, Korean, German, Spanish, French, Italian, Danish, Polish, Russian, Bosnian, Arabic, Norwegian Bokmål, Brazilian Portuguese, Thai, Turkish, and Ukrainian.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}