Internationalization

Capsule is internationalized from a single canonical source. Every user-facing string — across the web, iOS/macOS, Android, desktop, the CLI, and the server’s errors — is authored once in the repo-root locales/ directory and compiled into each platform’s native localization format. A translator never touches application code.

Implemented in:

• locales/ — the canonical ICU MessageFormat catalogs (the source of truth) and the supported-locale configuration.
• xtask i18n (xtask/src/i18n.rs) — the build step that compiles the catalogs into each platform’s native files; --check is the CI drift gate.
• capsule-i18n — the Rust runtime (locale negotiation + message formatting) used by the server and CLI.
• Per-platform generated targets (web JSON, Android strings.xml, iOS .xcstrings) consumed by each client’s native i18n machinery.

This doc owns the i18n contract: the catalog format, the supported-locale set, locale resolution, and the server error-code scheme. It defers per-platform UI rendering to Clients, and closed-enum locale rejection to Threat Model — Schema Rules.

Canonical source

locales/ is the single source of truth (see the SSoT rule):

• locales/config.json — the supported-locale set: sourceLocale, the supportedLocales list, and per-locale fallbacks. This is the closed set of locales Capsule recognizes.
• locales/<locale>.json — one catalog per locale. Each entry maps a key to an ICU MessageFormat message plus optional translator context. en.json is the source catalog; every key is defined there first, and every translation carries the same key set.
• locales/schema/catalog.schema.json — the JSON Schema for a catalog (editor autocomplete and validation).

Keys use dotted namespaces (area.subarea.name). A handful of legacy UI keys inherited from the Android catalog keep their original flat names; codegen sanitizes any key into each platform’s native identifier rules.

ICU MessageFormat was chosen as the canonical format because it is the common substrate the client platforms already speak — the web (FormatJS/react-intl), iOS String Catalogs, and Android all compile it natively — so codegen to those targets is near-mechanical. The Rust runtime is the one target without a native ICU formatter and carries a small interpreter instead (see below).

Codegen

just i18n (cargo run -p xtask -- i18n) compiles the catalogs into:

Target	Output	Status
Rust runtime	capsule-i18n/src/bundles/<locale>.json + generated.rs	Implemented
Web (FormatJS)	capsule-web/src/i18n/messages/<locale>.json	Implemented
Android	capsule-android/.../res/values[-<qualifier>]/strings.xml	Implemented (literals)
iOS/macOS	capsule-swift/Generated/Localizable.xcstrings	Experimental

Every renderer is a pure function of the parsed catalogs, so the generated files are deterministic. just i18n-check (xtask i18n --check) re-renders in memory and fails if any committed file drifted from locales/ — it runs inside check-rust, so generated files can never silently fall out of sync. Generated files carry a “do not edit by hand” banner and are committed so a fresh checkout builds without running the generator.

Two honest limitations in the current generators, both tracked as follow-up:

• Android / iOS apps are not built in CI on this branch, so the generators are validated by snapshotting their string output rather than by compiling the apps. The iOS .xcstrings target is marked experimental and not yet wired into the Xcode project.
• ICU plural/select blocks do not yet map to Android <plurals>; such keys emit a TODO comment instead of a mistranslated <string>.

Runtime and locale resolution

capsule-i18n is the Rust runtime for the server and CLI:

• negotiate(accept_language, supported, source) picks the best supported locale for an Accept-Language-style request (exact tag, then primary subtag, then the source locale as the final fallback).
• Bundle::for_locale(locale) loads a locale’s messages with the source locale as a fallback, so an untranslated key still renders in the source language. A missing key returns the key itself, surfacing the gap rather than an empty string.

There is no production-grade pure-Rust ICU MessageFormat formatter crate, so the runtime ships a small interpreter over the same FormatJS grammar the web uses. It currently handles literal text and {name} interpolation — the subset the catalog exercises today; full plural/select/number/date formatting is follow-up. Native clients use their platform’s own ICU machinery, which already covers the full syntax.

Server error codes

APIs are typed, but error messages must be presentable in the user’s language. The contract:

• The server attaches a stable, machine-readable code to high-level errors — a key from the catalog’s error.* namespace (e.g. error.auth.invalid_credentials) — alongside an English detail message. The generic response shape is ApiError { error: String, code: Option<String> }; code is optional, so older clients ignore it (consistent with forward/backward compatibility).
• Clients localize the code, mapping it through their generated catalog to a localized high-level message. The English detail stays English — specific, developer-facing detail is not translated.
• The server references codes via generated capsule_i18n::error_codes constants, so a typo is a compile error and the codes stay in sync with the catalog. There is no second source of truth: error codes are catalog keys.

The server does not translate by Accept-Language; localization happens client-side off the code, which keeps it working offline and avoids coupling the client’s language to the server.

Contributing translations

Translators edit the JSON catalogs in locales/ and open a pull request — no code involved. locales/README.md documents the catalog format, key naming, and how to add a language; CONTRIBUTING.md covers the commit and review flow. A translation-management hub (Weblate or Crowdin) backed by these same files is planned so non-technical contributors can translate through a web UI; until then, the JSON-via-pull-request flow is the supported path.

Validation

See Validation Tiers.

• Codegen determinism (unit). Each renderer is a pure function; xtask i18n --check asserts the committed files match a fresh render. Catalog parsing rejects a malformed entry (missing message) and an unsupported sourceLocale.
• Locale negotiation + formatting (unit). capsule-i18n unit tests cover exact/primary-subtag/weighted matching, fallback to the source locale, message interpolation, and missing-key behavior, against fixed vectors.
• Bundle load (smoke). The embedded generated bundle parses and resolves keys (including an error.* code round-trip) end-to-end.

i18n adds no new case to the bounded E2E test surface: the contract is exercised entirely at the unit/smoke tier within capsule-i18n and xtask, and native-client consumption is verified per platform rather than as a cross-module integration test.

Future work

• Migrate existing hardcoded strings (web JSX, SwiftUI Text, Compose) onto catalog keys.
• Full ICU plural/select/number/date fidelity in the Rust runtime and the Android generator.
• Wire the iOS .xcstrings target into the Xcode project; add the desktop target once its framework is chosen.
• Retrofit the remaining server error variants with codes; regenerate the OpenAPI spec / SDK.
• Align the FFI CatalogError surface with the error-code scheme.
• Stand up a translation-management hub (Weblate/Crowdin) and localize the documentation site.