Duolith docs

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/, with index.json listing the locales, and the runtime loads the chosen one and the fallback.
  • Messages use ICU message syntax (arguments, plural and selectordinal through Intl.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() sets lang and dir on 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-* and right-* stay physical).
  • Formatting: formatNumber, formatDate and formatRelativeTime use Intl with the current locale.

Alternatives considered

OptionWhy 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 TypeScriptTranslators' tools exchange JSON; page scripts cannot import project TypeScript yet
Treat a key a locale lacks as a warningThe 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.