# 0064. The UI is localised in English and Japanese with a typed dictionary and no library

Status: Superseded by 0070 · Date: 2026-10-26 · Design section: UI, Roadmap phase 10
Decided: The UI's fixed wording lives in two typed objects, `en` and `ja`, in `ui/src/lib/i18n.ts`, read through one `t()` function, with no i18n dependency; the language is the saved choice, else `navigator.languages`, else English, switched on screen and kept in `localStorage` with nothing on the server; names, field names, state words from Argo CD or the cluster, log lines and the body of apiserver or Talos errors are shown as received; dates and sizes go through `Intl` for the chosen language

## Context

Roadmap phase 10 lists "UI localisation". The users include Japanese speakers. The UI is Preact with
preactcn; React and `preact/compat` are not allowed (project rule), which rules out the React-based i18n
libraries (react-i18next, react-intl, LinguiJS's React bindings). The screens hold about 220 fixed strings.

## Decision

**1. No library.** `ui/src/lib/i18n.ts` has `en` (an `as const` object) and `ja`, typed
`Record<keyof typeof en, string>`. A key missing from `ja`, or only in `ja`, does not compile. `translate(lang,
key, params)` replaces `{name}` markers. A test also checks at run time that both have the same keys, that no
entry is empty, and that both fill the same placeholders, because a compiler check does not see a `ja` entry
that lost a `{n}`. There are no plural forms: the strings are written so a count is only ever a number in
a label ("Pending approval (3)"), which both languages can say without grammar. If a language with plural
rules is added, `Intl.PluralRules` is already in the platform and the cost is one function.

**2. Choosing the language.** `lang.ts` keeps the current language in a module variable. At first use it is
`localStorage["ichor-ui-lang"]` if that is `en` or `ja`, else the first tag of `navigator.languages` whose primary
subtag is `en` or `ja`, else English. A selector in the page header changes it, writes `localStorage`, sets
`<html lang>` and redraws. Each language is named in itself ("English", "日本語"). Storage and `navigator` are read
behind try/catch, so a blocked store only means the choice does not outlive the tab. Nothing is sent to the
server and no server setting exists: the language is a property of the person, not of the installation.
Components call `useT()`, which subscribes them to a change; plain functions (`describeError`, `formatBytes`,
`enumLabel`) read the current language directly.

**3. What is translated.** The screens' own fixed text: titles, column headings, buttons, hints, empty and
loading states, dialog text, the headline `describeError` puts above an error, and the display names of the proto
enums (`HandoverPhase`, `ConfigLayer`, ...). An enum value without a dictionary entry still falls back to its
title-cased proto name, so a value added to the API later shows up readable, not missing.

Not translated, on purpose:

- Names of custom resources, namespaces, hostnames, and Kubernetes, Talos and proto field names (`TalosConfigPatch`,
  `matchLabels`, `ichorUI.oidc`, the document kinds `SysctlConfig` and so on), which a person must be able to type
  or search for exactly.
- The body of an error from the apiserver, Talos or ichor-ui (ADR 0045). `describeError` translates only the
  headline; the detail is shown as received, so what is searched for in the docs or an issue is what the server said.
- State words that other systems return (Argo CD's `Synced`, `OutOfSync`, `Healthy`; condition `type` and `status`)
  and the log lines.
- The CLI. This ADR is about the UI; the CLI's output is what scripts and bug reports quote.

**4. Dates and numbers.** `formatTimestamp` and `formatBytes` take the language and use `Intl.DateTimeFormat`
(`dateStyle: medium`, `timeStyle: medium`) and `Intl.NumberFormat`. Sizes stay binary (1024) and keep the labels
`B KB MB GB TB` in both languages: the unit symbols are the same in Japanese usage, and changing the base or the
labels per language would make one number read as two sizes.

## Consequences

- No dependency, no build step, and no bundle growth beyond the strings (a few KB).
- Adding a language is one object and one entry in `langs` / `langNames`; the compiler lists what is missing.
- The English text is the source of truth. A change to an English string does not tell the translator; reviewers
  change both objects in one commit, which the key check enforces only for presence, not for meaning.
- Strings are translated whole, with placeholders, so word order differs by language where it has to.
  The one sentence with a link in it (the effective-config note) is stored in three pieces around the link.
- The Japanese is a first draft by the implementer and wants a read-through by a native speaker.
- Page components are still not unit-tested (ADR 0045); the language logic is, as pure functions in `ui/src/lib`.