Localization

Requirement A localization decision MUST list supported locales, default locale, fallback chain, user selection, browser detection, owner, and status.

Rationale One decision defines the product's locale contract before catalogs and routes appear. A draft names its decider and decide-by date.

Requirement A product MUST NOT infer supported locales from catalog files alone.

Rationale Catalog presence cannot define routing, fallback, selection, or browser-detection behavior.

Requirement A localized application MUST define one documented locale route shape.

Rationale One shape gives users, crawlers, and links a predictable localized address. A path segment is the default shape. It gives every localized page a distinct address for links, crawlers, and cache entries. A cookie or header shape serves several locales from one address, so a shared cache and a search index see one of them. An application with no public pages, whose locale is a property of the signed-in account, documents one of those shapes instead.

Example /nl/orders/42 places the locale in the documented path segment, so a crawler and a shared cache each address one language.

Requirement A localized application MUST redirect unsupported or missing locale segments according to product policy.

Rationale The policy identifies the fallback or error behavior for an unavailable route locale.

Requirement A localized application MUST NOT publish multiple indexable URLs for the same localized content.

Rationale Duplicate indexable locations split search and canonical-link behavior.

Requirement A localized application MUST store user-facing copy in locale catalogs.

Rationale Catalogs separate translated wording from application behavior and source code.

Requirement A locale catalog MUST use semantic keys that cite Term records rather than source-language sentences.

Rationale A meaning-based key remains stable when one language changes wording.

Example orders.cancel.confirmation identifies intent without copying the English sentence.

Requirement Each supported locale MUST contain required keys or use its declared fallback.

Rationale A declared fallback prevents missing copy from becoming an unreviewed runtime behavior.

The declaration states the fallback locale and what a missing key does at build time. A key missing from the default locale fails the build. No fallback exists for it, and the interface renders its identifier. A key missing from a non-default locale reports a warning and falls back. Shipping one untranslated string costs less than blocking a release on it.

Example A catalog check runs in the frontend lint gate. The two outcomes are visible before review, not in a browser.

Requirement A validation catalog MUST state the field label, what is wrong, and what is accepted, without technical wording.

Rationale The shape holds in every language. Each language's sentence pattern lives on the field's Term labels and the language's writing page.

Example The Term record for a field carries the sentence pattern for each supported language.

Requirement A screen MUST resolve every closed-set code it renders to its Term record label and never render the raw code, excluding user-facing reference numbers.

Rationale The code is a contract value. The Term label is copy. A resolution value, a refusal ground, a role code, or a billing state carries its label beside the rest of the screen's copy.

Example A shipment row shows the Term label for shipment-delayed in the active locale.

Requirement A localized interface MUST format dates, times, numbers, currency, plurals, lists, and relative time by active locale.

Rationale User-facing formatted values need the selected locale's conventions.

The platform supplies all of them. The Intl namespace has DateTimeFormat, NumberFormat, PluralRules, ListFormat, and RelativeTimeFormat. Each one carries the locale data the browser already ships. A project-written formatter for any of these is a second locale database that no one updates. Its plural rules are wrong for the first language with more than two forms.

Example Create one formatter instance per locale and reuse it. Construction is the expensive part.

Requirement Domain values and API contracts MUST remain locale-neutral unless a use case explicitly exchanges localized content.

Rationale Stable business values and wire contracts do not change with interface language.

Requirement Public metadata, form labels, validation messages, and user-safe errors MUST follow the active locale.

Rationale Visible content needs the same locale behavior as the page that presents it.

Requirement A stable API error code MUST NOT change by locale.

Rationale Programmatic consumers need one code regardless of the caller's presentation locale.