I18N

Internationalization (i18n)

Internationalization is not translation — it is the engineering discipline of making an application locale-aware so translation is a content change, not a code change. Hardcoded strings, locale-blind formatting, and LTR-only layouts all become bugs the moment a second locale is needed. Build the scaffolding before the second locale arrives, not after.

When to use

• Preparing an application for multiple locales (message extraction, locale routing, formatting)
• Adding RTL support or locale-specific pluralization/gender rules
• Auditing an existing app for hardcoded strings or locale-blind formatting
• Triggers on "i18n", "localization", "l10n", "RTL", "国际化", "本地化", "多语言"

Not for: frontend visual design (use frontend-design); API contract design (use api-design). i18n is a cross-cutting implementation discipline touching frontend, backend, and build tooling.

Steps

1. Audit the locale surface

Before writing code, find every locale-sensitive surface in the application:

• Hardcoded user-facing strings (UI labels, error messages, email templates, push notifications)
• Formatted values: dates, times, numbers, currencies, percentages, units
• Pluralization and gender-dependent phrasing
• Layout assumptions: LTR-only CSS, fixed-width containers, text concatenation
• Locale-affecting config: timezone handling, first-day-of-week, calendar system

Verify: the audit produces a list of locale-sensitive surfaces grouped by type, not a vague "needs translation."

2. Extract messages

Replace every hardcoded string with a message ID resolved through an i18n library. Messages live in locale files keyed by ID, not inline:

• Use the framework's i18n library (react-intl, i18next, FormatJS, vue-i18n, or equivalent)
• Message IDs are descriptive (user.profile.edit_button), not positional (btn_3)
• Leave source-locale strings as the fallback; never leave a missing-key hole in production
• Extract programmatically (CLI extractors) where the framework supports it — manual extraction drifts

Verify: grep for user-facing literals in components returns only IDs; no hardcoded strings reach the user.

3. Choose message format and handle pluralization

Use ICU MessageFormat — it is the standard for handling the grammar that varies across locales (plurals, gender, select). Avoid string concatenation and naive plural rules (if count === 1); they fail across locales:

• Pluralization: ICU plural syntax handles the 6 CLDR plural categories (zero, one, two, few, many, other) — English needs two, Arabic needs all six
• Gender / select: ICU select syntax for gendered or context-dependent phrasing
• Interpolation: named placeholders, never positional — translators reorder sentences
• Rich text: embed component placeholders (links, bold) via ICU rich-text or the library's component-interpolation, not by splitting strings around tags (splitting breaks translation)

Verify: every message with a count uses ICU plural syntax; no count + " items" concatenation.

4. Set up locale routing and detection

Decide how a user's locale is determined and how it maps to routes:

• Detection order: explicit user preference (account setting) → URL path/query → cookie (last chosen locale) → Accept-Language header → geo (with caution — geo ≠ language) → default. See references/i18n-checklist.md §1 for the full 6-step ladder.
• Persistence: cookie covers logged-out users; account setting covers logged-in — both persist the choice across visits.
• Routing: locale-prefixed routes (/en/..., /ar/...) for SEO and shareability; or path-less with client detection for app-only surfaces — choose deliberately
• SSR / hydration: the server must render in the detected locale, not render a default then flash-correct on the client (hydration mismatch = broken UX)
• Server-side message loading (RSC): in App Router / RSC frameworks, load only the request's locale messages on the server (per-locale bundle split, not an all-locales bundle); bind locale per-request (setRequestLocale-style, never a module global); keep server-only messages out of the client bundle. See references/server-i18n.md for the full pattern.

Verify: locale detection follows the documented order; the initial server render matches the client locale (no flash).

5. Handle formatting and layout

Locale-aware formatting for every user-facing value:

• Dates/times: format via Intl.DateTimeFormat or the i18n library; honor timezone, calendar, and locale-specific ordering. Never hand-build date strings.
• Numbers/currencies: Intl.NumberFormat; currencies need the locale (symbol placement) AND the currency code (¥ in Japan vs. ¥ in China).
• RTL: CSS logical properties (margin-inline-start, not margin-left); dir attribute on the root; mirror icons and directional layouts. Test in an RTL locale, not by eyeballing.
• Text length: translated text is 30–50% longer than English (German) or shorter (Chinese); layouts must flex, not truncate. No fixed-width buttons.

Verify: dates/numbers render correctly in at least LTR + RTL locales; logical properties used; layout survives 140% text expansion.

6. Test across locales

Run the app in a non-source locale — preferably an RTL one (Arabic, Hebrew) — to surface the bugs that source-locale testing hides:

• Missing translations render as IDs or fallback (never blank)
• Pluralization correct for the locale's plural rules
• RTL layout mirrors correctly; no overflow or overlap
• Formatting (date, number, currency) matches the locale
• E2E tests parameterized by locale where feasible

Verify

• No hardcoded user-facing strings in components (grep confirms)
• All messages extracted to locale files with descriptive IDs
• Pluralization uses ICU MessageFormat; no concatenation
• Locale detection documented; SSR matches client locale (no flash)
• Only the request's locale messages ship to the client (no all-locales bundle); locale is request-scoped, not a module global
• Dates/numbers/currencies via Intl APIs; correct in LTR + RTL
• CSS uses logical properties; layout survives 140% text expansion
• App tested in at least one RTL locale; no overflow, overlap, or missing translations

Red flags: if (count === 1) "item" else "items"; string concatenation to build sentences; hand-built date formatting (day + "/" + month); margin-left in a layout that needs RTL; fixed-width containers with text; positional placeholders; splitting a string around an inline link; assuming Accept-Language is the right detection (users override); rendering a default locale server-side then correcting on the client; a module-level currentLocale variable under concurrent requests; import messages from './messages' where the index re-exports every locale (ships all locales to every client).

References

• ${CLAUDE_PLUGIN_ROOT}/references/engineering-principles.md — shared discipline (surface assumptions, surgical scope, verify don't assume)
• references/i18n-checklist.md — locale-surface audit template, ICU syntax reference, RTL conversion checklist, locale-detection patterns, test-locale matrix
• references/server-i18n.md — RSC / App Router message loading, per-locale bundle splitting, request-scoped locale, hydration alignment