Localization

Locales, default, fallback, selection, and browser detection interact: each catalog, route, and formatter reads the same contract, so the team writes it once before building any of them. Without the contract, each part guesses a different fallback and the product answers each missing translation differently.

Reviewed forThe locale decision lists supported locales, default locale, fallback chain, user selection, and browser detection.

Marked guidance: a reviewer answers this question.

A catalog file proves only that someone wrote translations; it says nothing about routes, fallback, selection, or detection. A product that counts locales by counting files announces a language its routes cannot serve and its fallback never reaches.

Reviewed forShipped locales come from the locale decision, with catalog files as translations only.

Marked guidance: a reviewer answers this question.

Users, links, crawlers, and caches all address a localized page, and one route shape gives each language one predictable address. A path segment is the default shape: it gives every localized page a distinct address that links, crawlers, and cache entries can each name. A cookie or header shape serves every locale from one address instead, so a shared cache and a search index each see only one of them. A product with no public pages, whose locale belongs to the signed-in account, documents one of those shapes instead of inventing a fourth.

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

Reviewed forThe application routes every locale through one documented route shape.

Marked guidance: a reviewer answers this question.

Readers mistype addresses and follow stale links, so a locale segment can name a language the product never shipped or omit the segment entirely. Without a documented policy, each route answers differently: one shows the default language, another shows an error, and a crawler indexes both as content.

Reviewed forUnsupported or missing locale segments redirect under the documented product policy.

Marked guidance: a reviewer answers this question.

When two addresses serve the same language, search engines split the page's rank between them and canonical links point two ways. One indexable address per language keeps search, sharing, and caching pointed at the same page.

Reviewed forEach localized content item serves from one indexable URL.

Marked guidance: a reviewer answers this question.

Copy in source code reaches translators only through developers, and each wording change becomes a code change with a review, a build, and a deployment. Catalogs hold every user-facing sentence in one place per locale, so translators edit wording while developers edit behavior.

Reviewed forUser-facing copy sits in the locale catalogs rather than in source code.

Marked guidance: a reviewer answers this question.

A key that copies the English sentence breaks its meaning the day English rewords it: every other language still points at the old sentence. A semantic key names the intent instead, citing the glossary term that holds the word's labels per language, so wording changes in any language without disturbing the key.

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

Reviewed forCatalog keys use semantic names citing glossary terms, with no source-language sentences as keys.

Marked guidance: a reviewer answers this question.

A missing translation with no declared fallback becomes a runtime surprise: the interface shows a key, an empty string, or the wrong language, and nobody chose which. 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.

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

Reviewed forEach locale holds its required keys or resolves them through its declared fallback.

Marked guidance: a reviewer answers this question.

A validation message that names the field, the fault, and the accepted input tells the reader how to fix the entry in any language, while a message with only one of the three leaves the reader guessing. The three-part shape holds across languages; each language's sentence pattern lives in the labels of the field's glossary term and the language's writing page.

The glossary term for a field carries the sentence pattern for each supported language.

Reviewed forEach validation message states field label, fault, and accepted input without technical wording.

Marked guidance: a reviewer answers this question.

A code such as a refusal ground or a billing state is a contract value built for systems, while the glossary label beside it is copy built for readers. A screen that renders the raw code shows one untranslated fragment in an otherwise translated page and forces the reader to decode it. Resolving every shown code keeps the whole screen in the reader's language, except reference numbers the reader quotes back.

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

Reviewed forShown codes render glossary labels, with raw codes absent except user-facing reference numbers.

Marked guidance: a reviewer answers this question.

Dates, numbers, currency, plurals, lists, and relative time each follow the reader's conventions, and a date the reader misreads becomes a missed appointment or a wrong payment. 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.

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

Reviewed forDates, numbers, currency, plurals, lists, and relative time render through active-locale formatters.

Marked guidance: a reviewer answers this question.

An expense state or a price stored in Dutch breaks the moment an English speaker opens it, and an API contract that shifts per language forces every consumer to negotiate wording before reading data. Business values and wire contracts stay in one neutral form, and only the interface translates them for display. A use case that genuinely exchanges localized content, such as a product description the merchant writes per language, names that exchange explicitly.

Reviewed forDomain values and API contracts stay locale-neutral outside explicitly localized exchanges.

Marked guidance: a reviewer answers this question.

A Dutch page with an English title, English form labels, or an English error tells the reader the translation stopped halfway and tells a search engine the page serves two languages. Metadata, labels, validation messages, and user-safe errors follow the active locale with the page around them.

Reviewed forPublic metadata, form labels, validation messages, and user-safe errors render in the active locale.

Marked guidance: a reviewer answers this question.

Integrations and support tools match on the error code, and a code that changes per language forces every consumer to list every translation before handling one failure. The code stays fixed while the human-readable message beside it translates.

Reviewed forEach stable API error code stays identical across locales.

Marked guidance: a reviewer answers this question.