# Localization and Internationalization Support in cmux: Architecture and Implementation

> Discover cmux localization and internationalization support. Learn how cmux uses String(localized:defaultValue:) and Localizable.xcstrings to ensure seamless global user experiences.

- Repository: [manaflow-ai/cmux](https://github.com/manaflow-ai/cmux)
- Tags: architecture
- Published: 2026-03-29

---

**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`](https://github.com/manaflow-ai/cmux/blob/main/Sources/cmuxApp.swift), menu items declare both a semantic key and an English fallback:

```swift
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`](https://github.com/manaflow-ai/cmux/blob/main/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`](https://github.com/manaflow-ai/cmux/blob/main/Sources/ContentView.swift) and [`Sources/SidebarSelectionState.swift`](https://github.com/manaflow-ai/cmux/blob/main/Sources/SidebarSelectionState.swift), views consume localized strings directly:

```swift
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`](https://github.com/manaflow-ai/cmux/blob/main/Sources/TerminalController.swift), error alerts are constructed using localized keys:

```swift
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`:

```json
"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`](https://github.com/manaflow-ai/cmux/blob/main/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`](https://github.com/manaflow-ai/cmux/blob/main/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`](https://github.com/manaflow-ai/cmux/blob/main/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`](https://github.com/manaflow-ai/cmux/blob/main/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.