ADR-0002: Every user-facing string lives in both locales
Status: Accepted
Date: 2026-05-30
Scope: core (any frontend app shipping more than one locale)
Context
Frontend apps here ship two locales — en.json (English) and pt.json
(Portuguese pt-BR) — under src/i18n/locales/ (in Expenses: both the customer expenses-web and admin expenses-admin apps). react-i18next falls back to the key string at runtime
when a translation is missing, so a key present in en.json but absent from pt.json does not fail the build and is invisible in English testing. It only
surfaces as a raw key (e.g. shell.menu) to a Portuguese user in production.
Decision
Every user-facing string must:
be wrapped in t('namespace.key') (never hardcoded UI text), and
exist in bothen.jsonandpt.json, added in the same change,
for every app that renders it.
Validation messages are translated too: schemas are i18n-aware via createSchema(t).
What stays literal (these are identifiers/values, not prose, and must not be
translated): UPPER_SNAKE role names (SUPER_ADMIN), plan tiers (free/pro/ pro+), environment names (dev/prod), ISO-8601 timestamps, UUIDs, and
monetary amounts (their formatting differs by locale, but the value doesn’t get
“translated”).
Consequences
A missing translation is a defect, caught early rather than by a user.
Enforced mechanically by the handbook:i18n-parity skill, which diffs the
leaf keys of en.json vs pt.json across every app declared in the workspace
manifest and exits non-zero on any gap — so it is part of “definition of done” and hook-able pre-merge.
Slightly more bookkeeping per string (two files), accepted as the cost of not
shipping untranslated UI.
Example
Real code from the repos — optional
Agents: safe to skip. The Decision above is the specification; everything below is
illustration. Skipping this block costs you nothing normative and saves tokens. Expand it
when you need the shape rather than the rule — porting the pattern to a new project, or
answering “what does this actually look like”.
const savedLanguage = localStorage.getItem(LANGUAGE_KEY) ?? 'en';i18n.use(initReactI18next).init({ resources: { en: { translation: en }, pt: { translation: pt } }, lng: savedLanguage, fallbackLng: 'pt', interpolation: { escapeValue: false },});/** Keep <html lang> in step so screen readers and Chrome's translate bar behave. */i18n.on('languageChanged', syncHtmlLang);
Note the default differs per app, deliberately. Expenses defaults to pt — its
audience is Brazilian. The AllSensis site defaults to en, because a link shared with
someone abroad has to land on a page they can read. Each app documents its reason next
to the line.
fallbackLng is the opposite language in both cases, so a missing key surfaces as the
other locale rather than as a raw key path — visibly wrong to the author, still readable
to the visitor.
The rule is machine-checked, not remembered. The handbook’s Stop hook runs handbook:i18n-parity after every turn:
✓ src/i18n/locales: 128 keys, in parity
And the consequence shows up in layout, not just in text: Portuguese runs 20–30% longer,
which is what broke the AllSensis header — see 0006-frontends-are-mobile-first.