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).

Supported Languages

The committed official language set is English (the source) plus twelve translations: zh-Hans, zh-Hant, ja, ko, fr, de, es, pt-BR, it, ru, hi, and ar. Including Arabic puts RTL layout support in scope for every client (web dir handling, native mirroring). Fallbacks are direct to the source locale — in particular zh-Hant falls back to en, never to zh-Hans: showing auto-Simplified text to Traditional-script readers is worse than showing English.

This section owns the decision; locales/config.json stays the mechanical truth of what ships — a locale is supported in a build exactly when its catalog lands and its tag enters supportedLocales. Today that is en only; the twelve catalogs are the rollout slice S-I2 in the repo-root SLICES.md. Everything that enumerates languages (per-platform catalogs, README translations) derives from config.json, so the set is never declared twice.

Codegen

mise run 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. mise run 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.

This contract covers the refuse-by-default surface too: every structured rejection in Threat Model — Validation carries an error.* code alongside its transport status (HTTP or gRPC — the cross-transport carriage is owned by API Surfaces, and the code, not the status, is what clients switch on). Flagship codes referenced across the design docs: error.protocol.version_unsupported (the 426 class), error.quota.exceeded, error.moderation.account_suspended, error.auth.invalid_credentials.

README Translation

The repo-root README.md ships translated as README.<lang>.md for every non-source locale in locales/config.json — the language list is never declared outside that file. Generation is xtask translate-readme (slice S-I3), structure-aware rather than whole-document:

• The markdown is segmented by block (headings, paragraphs, list items, tables); code blocks, link targets, and badge/image URLs pass through untouched.
• Each translatable segment goes through an LLM translation API with a pinned project glossary (product terms — “Capsule”, “sidecar”, “album”, “drop” — and their per-language renderings), so terminology stays consistent across regenerations.
• Output files are committed with the same do-not-edit banner as the other generated i18n artifacts, and xtask translate-readme --check is the CI drift gate: it re-segments the source and fails when a committed translation’s segment structure no longer matches README.md — the same pattern as i18n --check. (The check is structural, not semantic — it needs no API key in CI.)

American English (README.md) is the base version; translations are regenerated, never hand-edited (hand improvements go into the glossary or the source).

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

Items with a slice are indexed in the repo-root SLICES.md; the rest remain unowned future work.

• Hardcoded-string migration (web JSX, SwiftUI Text, Compose → catalog keys): slice S-I1.
• The twelve-locale catalog rollout + RTL support: slice S-I2.
• README translation pipeline: slice S-I3 (see README Translation).
• 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.