Internationalise and localise correctly
A hard-coded string or a hand-built plural is a bug that surfaces the day a second locale
ships. Externalise every user-visible string as a whole message with named arguments,
let CLDR data (through ICU MessageFormat and the Intl APIs or the language's
equivalents) decide plurals and formats, and build layouts that survive longer text and
right-to-left scripts.
Steps
- Use the repo's mechanism. Library (i18next, FormatJS/react-intl, vue-i18n,
Angular i18n, Lingui, gettext, ICU4J/ICU4X, .NET resources, Apple String Catalogs,
Android resources), message file layout, key scheme, locale detection and persistence.
Call
search_lore. Never add a second mechanism or a parallel strings file. - Externalise every string users can see or hear: labels, placeholders,
altandaria-labeltext, validation and error messages, emails, notifications, page titles. Keys describe meaning and location (ticket.actions.approve), never the English text. APIs return error codes and parameters; the client localises them. - Write translatable messages.
- Whole sentences with named arguments:
{name} approved {count, plural, one {# ticket} other {# tickets}}— never"Approved " + n + " ticket(s)". - Plurals use CLDR categories (
zero,one,two,few,many,other). English uses onlyone/other, but Polish needsfew/manyand Arabic all six, so never branch onn === 1in code.otheris always present.=0 {No tickets}is an exact match, distinct from thezerocategory. - Ordinals use
selectordinal("1st, 2nd"); gendered text usesselect. - Rich text uses the library's tag syntax (
<b>{name}</b>), not HTML concatenation. - Give translators a description for ambiguous short strings ("Open" verb or adjective?).
- Unicode MessageFormat 2 is stable in CLDR 47, but most libraries still use ICU MessageFormat 1 syntax; write what the repo's library parses.
- Whole sentences with named arguments:
- Format with the locale APIs.
Intl.DateTimeFormat(preferdateStyle/timeStyleover pattern strings),Intl.NumberFormat(includingstyle: 'currency'with an ISO 4217 code,'percent','unit',notation: 'compact'),Intl.RelativeTimeFormat,Intl.ListFormat,Intl.PluralRules,Intl.Collatorfor sorting,Intl.Segmenterfor truncating text by grapheme or word,Intl.DisplayNamesfor language/region names. Reuse formatter instances; they are costly to construct. - Money and time. Money is integer minor units plus the currency code; minor units
vary (JPY 0, USD 2, KWD 3) — take them from the formatter or ISO 4217, not a constant
- Past instants are stored as UTC and displayed in the user's IANA time zone
(
Europe/Berlin, not "CET" or an offset). A future local event (a 09:00 meeting) is stored as local date-time plus IANA zone, so a DST rule change does not move it. UseTemporalwhere the runtime supports it, else the repo's date library; never parse locale-formatted strings back into dates.
- Past instants are stored as UTC and displayed in the user's IANA time zone
(
- Locale selection. BCP 47 tags (
pt-BR,zh-Hant-TW); negotiate from the user's saved preference, thenAccept-Language/navigator.languages, then the default; fall back through the chain (de-AT→de→ default). Never infer language from IP or country. Set<html lang>anddir, andlangon inline passages in another language (WCAG 3.1.1, 3.1.2). - Layout for expansion and direction. Allow roughly 30–40% longer text (more for
short labels) without clipping; no fixed-width buttons around text. Use CSS logical
properties (
margin-inline-start,inset-inline-end,text-align: start) and flex/grid, which mirror automatically underdir="rtl". Mirror directional icons (back/forward arrows), not universal ones (play, checkmark, logos). Isolate user-generated text inside messages (<bdi>or the library's bidi isolation) so an Arabic name does not reorder the sentence. - Keep the catalogue honest. Add new keys to the source-locale file in the same change; run the repo's extraction and missing/unused-key check; remove keys you orphaned. Translations arrive through the repo's workflow — do not machine-translate into production catalogues unless the ticket says to.
- Test (the
frontend-testingskill), per AC:- render under a pseudo-locale (accented, ~40% longer, bracketed:
[Ţîçķéţš ~~]) or a long real locale (de, fi) → no raw keys, no untranslated literals, no clipping; - plurals at 0, 1, 2, 5, 21 and 22 in a locale with
few/many(pl or ru); - dates, numbers and currency snapshot for two locales and a non-UTC time zone
(set
TZin the test run); dir="rtl"renders mirrored where the repo supports RTL. Record per-AC evidence with therecord-evidenceskill, then stop.
- render under a pseudo-locale (accented, ~40% longer, bracketed:
Done when
No user-visible literal remains in the changed code; every new key exists in the source catalogue and the extraction check is clean; plural, date, number and currency output is produced by CLDR-backed APIs and tested in at least two locales.
Anti-patterns
- String concatenation or template literals building sentences;
n === 1 ? '' : 's'. - Hard-coded
$,,or.separators;toFixed(2)for money;MM/DD/YYYYpatterns. - Storing local wall-clock times without a zone; using fixed offsets for zones.
margin-leftfor spacing that should follow text direction; flipping every icon.- Keys named after the English text; one giant catalogue key reused in two meanings.
Capture lore
This skill is one of the places durable, reusable knowledge naturally surfaces:
While externalising strings you learn the i18n framework, the key scheme, how locale is detected and how far RTL support goes. That kind of fact is lore. Capture it via the lore-capture
protocol in your brief (CLAUDE.factory.md, step 11 "Memory contribution"):
call the Memory MCP suggest_lore once at the close of your work — reusable
conventions, gotchas, decisions, and boundaries only, never per-ticket trivia.
