I18N

Internationalization (i18n)

Internationalization across the stack: Rails API, React Native, ReactJS Vite SPA, Next.js App Router.

The decisions that outlive the strings

Translating is the easy part. These four are what you cannot cheaply undo later:

Decision: does the server or the client localize this?

The API returns codes, not sentences. A localized API string is a UI decision made in the wrong layer: you cannot re-word it without a backend deploy, and a second client gets whatever the first one needed. Where the server must localize (email), use the user's stored preference — Accept-Language is a hint from whatever browser they happened to open, not an identity.

Non-negotiables (every platform)

• If a human reads it, it is a key. No user-facing literal in a component, view, or serializer. i18n-checker.py warns on two of those three: it inspects .tsx/.jsx and .erb, so a hardcoded string in a Panko serializer (.rb) is not caught by anything — that one is on you, and it is the one that reaches the API consumer rather than the page. The rule lives in std-i18n.
• Keys are namespaced and hierarchical: orders.checkout.submit_button. Never use the English text as the key; that turns a copy edit into a code change in every locale.
• en is the fallback and the source of truth. Every other locale is a delta from it.
• Interpolate, never concatenate. t('greeting', { name }), not t('hello') + name — word order is not universal, so a concatenation cannot be translated at all.
• Pluralization is a library feature, not an if. Arabic has six plural forms; a count === 1 ? a : b is wrong in most of the world.
• Never delete a key that ships in a released mobile client. Old app versions still request it and will render blank. Deprecate, remove a release later.

RTL is a layout problem, not a text problem

The moment Arabic or Hebrew is plausible, stop writing left/right — everywhere.

• Web: CSS logical properties (margin-inline-start, padding-inline-end, text-align: start). Free, and no dir-specific stylesheet.
• React Native: start/end in styles. I18nManager.forceRTL requires an app restart, so it is a settings action, not a runtime toggle.
• Directional icons (arrows, chevrons) mirror; logos and media do not.

Retrofitting this later means auditing every style in the app. Deciding now costs nothing.

Where the locale lives

The URL (/ar/orders) on web — a shared link must open in the language it was shared in, and a cookie cannot survive being pasted into Slack. Persist the preference server-side for a signed-in user; the URL still wins for the current request.

CI is what keeps the locales honest

A missing key is invisible until a user sees a blank label or a raw key on screen. That must hold whether or not anyone reads this file — so it is a gate, not a rule:

• fail when a key exists in en but not in another locale (or the reverse);
• fail on an unused key — dead weight a translator is still being paid for;
• keep locale files sorted, so merges conflict on content rather than on line order.

Deep guides (read on demand, do not preload)

• Rails: locale file organization, lazy lookup, pluralization, API responses, date/number formatting → references/rails-i18n.md
• React Native: react-i18next setup, locale file structure, type-safe keys, and RTL including I18nManager and mirrored components → references/react-native-i18n.md
• Web: Vite SPA locale detection, Next.js Server vs Client Component i18n, locale routing, CSS logical properties → references/web-i18n.md
• Adding a locale, key rules, and the deprecation path → references/locale-workflow.md

Related, owned elsewhere — do not duplicate: the path-scoped conventions that apply when you edit a locale file or a component live in std-i18n; RTL's accessibility implications live in ../std-accessibility.