--- name: principle-i18n description: Internationalization (i18n) & localization (l10n) principles — locale-aware date, time, number, and currency formatting, time-zone correctness (persist UTC in DB, render local), CLDR plural rules, message catalogs (ICU MessageFormat, gettext), translatable string composition (no concatenation), bidirectional & right-to-left layout, character-encoding hygiene, sortable date formats (ISO 8601). Auto-load when adding a new locale, formatting dates/times/numbers/currency for display, persisting timestamps, building message catalogs, composing user-facing strings from variables, designing pluralized copy, working with right-to-left scripts, choosing between backend and frontend locale negotiation, or auditing existing UI strings for translation readiness. --- # Internationalization & Localization Principles i18n bugs are latent — they survive review unnoticed and only surface when the product expands to a new locale. ## Locale-Aware Formatting *Use platform APIs that accept a locale tag; never hand-roll date or number rendering.* - Use `Intl.DateTimeFormat(locale, options)` and `Intl.NumberFormat(locale, options)` — not `Date.toString()`, `toLocaleDateString()` without a locale argument, or manual template strings. - Pass BCP 47 locale tags (`en-US`, `fr-FR`, `ar-EG`); rely on CLDR data in the runtime rather than custom format maps. - Never hard-code `MM/DD/YYYY` — format order, separator, and calendar system (Gregorian vs. Hijri vs. Buddhist Era) vary by locale. - Currency: let `Intl.NumberFormat(locale, { style: 'currency', currency: 'USD' })` place the symbol and decide sign position — never concatenate `"$" + amount`. - For backend rendering, thread the `Accept-Language` header or a persisted locale preference down to the formatting layer. ## Time Zones: Persist UTC, Render Local *Timestamps recorded in local time become ambiguous at DST boundaries and when users cross time zones.* - Persist all timestamps as `TIMESTAMP WITH TIME ZONE` in UTC in the database; never persist local time without an offset. - Convert to the user's local zone at the display edge (UI component or API response serialiser), not in business logic or queries. - Account for DST gaps and folds: `America/New_York` can produce two instants for the same clock time during the fall-back hour. - Prefer named IANA zones (`Asia/Kolkata`) over fixed offsets (`+05:30`) — offsets do not encode DST history. - When comparing or sorting, always compare UTC epoch values; wall-clock comparisons are incorrect across DST changes. ## Plural & Grammatical Rules *English has two plural forms; Arabic has six; Russian has four (one/few/many/other) — selection depends on the last digit, with a special-case exclusion for 11–14.* - Use CLDR plural categories (`zero`, `one`, `two`, `few`, `many`, `other`) via your i18n framework — never branch on `count === 1`. - Every message with a numeric value needs all applicable CLDR forms supplied in the message catalog, even if the current locale only uses two. - Where the framework supports it, handle grammatical gender and case agreement for languages that require them (German, Slavic, Romance). - String templates like `"You have " + count + " messages"` break for Arabic, Polish, and Russian — use ICU `{count, plural, one{# message} other{# messages}}`. ## Message Catalogs & String Composition *Translatable strings must be atomic, reorderable units — not assembled at runtime.* - Use ICU MessageFormat or gettext-style catalogs: `t("greeting.user", { name })` not `"Hello " + name + "!"`. - Never concatenate translatable fragments: `t("prefix") + value + t("suffix")` produces ungrammatical output for SOV/VSO word-order languages. - Placeholders must be positional or named so translators can reorder them: `{0} added {1} to the cart` → translator may need `{1} wurde von {0} in den Warenkorb gelegt`. - Keep translatable strings in source control alongside code; treat missing translation keys as build errors, not silent fallbacks. - Separate presentation (HTML/Markdown within the translated string) from translation only when the framework handles it safely — raw HTML interpolation is an XSS vector. ## Bidirectional & Locale-Sensitive Layout *Arabic, Hebrew, Persian, and Urdu are right-to-left; layouts that assume LTR break visually and semantically for these locales.* - Set `dir="rtl"` on the `` element (or the nearest container) when serving RTL locales; do not rely on CSS alone. - Use logical CSS properties (`margin-inline-start`, `padding-inline-end`, `text-align: start`) instead of physical ones (`margin-left`, `text-align: left`) in shared layout styles. - Mirror directional icons (back/forward arrows, progress indicators) in RTL — decorative icons and logos typically do not need mirroring. - Wrap user-supplied content (names, addresses, product titles) in `` or apply `unicode-bidi: isolate` to prevent bidi algorithm spillover into surrounding UI text. - Test layout with a real RTL locale string, not just `dir="rtl"` on placeholder text. ## Encoding, Collation & Sortable Formats *Encoding mismatches and locale-insensitive sort orders corrupt data and produce wrong results.* - Use UTF-8 end-to-end: database columns, file storage, HTTP responses (`Content-Type: text/html; charset=utf-8`), and source files. Never introduce `latin1` or `iso-8859-1`. - Sort user-visible strings with `Intl.Collator(locale, { sensitivity: 'base' })` — `Array.prototype.sort()` uses Unicode code-point order, which is wrong for most locales. - Use ISO 8601 (`YYYY-MM-DDTHH:mm:ssZ`) for machine-readable timestamps in logs, filenames, and APIs — it sorts correctly as a plain string and is unambiguous across locales. - Never sort `MM/DD/YYYY` date strings lexicographically — alphabetical order is not chronological order for that format. ## When i18n Engineering is Overkill - Internal CLI tools or admin dashboards with a documented single-locale user population. - Throwaway prototypes that will never reach end users. - English-locked tooling where internationalisation is explicitly out of scope and that decision is documented. - Any public-facing or multi-locale UI: never overkill regardless of timeline or team size. ## Red Flags | Flag | Problem | |------|---------| | `new Date().toString()` or `toLocaleString()` without a locale argument | Output is runtime-locale-dependent; differs across servers and user machines | | `if (count === 1) "1 item" else count + " items"` | Breaks for Arabic (6 forms), Russian (4 forms: one/few/many/other), Polish (3 integer forms) | | `"Welcome " + name + "!"` as a translatable unit | Concatenation prevents word-order reordering for SOV/VSO languages | | Persisting timestamps in a DB column without time-zone info | Ambiguous at DST boundaries; breaks when users move time zones | | `padding-left` / `text-align: left` in shared layout styles | Breaks RTL locales; use logical properties instead | | Hardcoded currency symbol position (`"$" + amount`) | Symbol placement and spacing vary by locale | | Sorting date strings in `MM/DD/YYYY` format lexicographically | Alphabetical ≠ chronological for that format | | `latin1` or `iso-8859-1` anywhere in the stack | Corrupts multibyte characters; breaks emoji and CJK text | | Hand-rolled plural map keyed by language name | Misses CLDR-defined forms; fails for newly added locales | | Translatable string assembled from separately-translated fragments | Produces ungrammatical output for languages with different word order |