0072. Translation is t() with ICU messages in locales/<locale>.json, checked at build time
- Status: Accepted (Mik, 17 Nov 2026)
- Date: 2026-11-14
- Decided by: production adapters agent, pending the integrator and Mik
- Planning item: Roadmap milestone 3, "string extraction and platform formatting" (D34)
Context
Version 1 promises string extraction and platform formatting (D34); shipped translations and language switching are listed after version 1 (post-v1, item 19). An app still needs one way to write its text so that adding a language later changes data, not pages, and the build must catch a key a locale lacks.
Decision
- **Text is
t("key", values)**, a function from@duolith/adapters, not new markup syntax. Expressions already re-render when the locale's state changes, so{t("home.title")}in markup follows the locale with no compiler change. - **Catalogues are
locales/<locale>.json** at the project root, named by language tag. Nested objects are dotted keys. The build writes them to/_duolith/locales/, withindex.jsonlisting the locales, and the runtime loads the chosen one and the fallback. - Messages use ICU message syntax (arguments,
pluralandselectordinalthroughIntl.PluralRules,select,number,date,time,'quoting), the format translators' tools already read. The build and the runtime accept the same grammar. - The build checks catalogues (E0280 to E0283): every key passed to
t()as text, and every key any catalogue has, must be in every locale; each catalogue must be an object of messages named by a locale; each message must parse. - The locale is the one chosen earlier on the device, else the person's preferred languages (exact, then by language), else the fallback.
startTranslation()setslanganddiron the document; the styling utilities use flex and logical padding, so a right-to-left locale flips rows and inline padding (text-left,text-right,left-*andright-*stay physical). - Formatting:
formatNumber,formatDateandformatRelativeTimeuseIntlwith the current locale.
Alternatives considered
| Option | Why not |
|---|---|
A markup syntax such as <t key="..."> | A language change for what a function already does; attributes would still need a function |
| Catalogues in TypeScript | Translators' tools exchange JSON; page scripts cannot import project TypeScript yet |
| Treat a key a locale lacks as a warning | The build has no warnings yet; a missing key shows the fallback or the raw key to real people |
Consequences
translation().setLocale(locale)exists and remembers the choice. Mik decided on 17 Nov 2026 that switching ships in version 1: it is documented and supported, not experimental.- Keys built at run time (
t(name)) are not checked; the catalogues' cross-check still catches keys one locale lacks.