Building Multi-Language React Apps at Scale: i18n Patterns That Work

Internationalisation is the kind of problem that looks solved right up until you have 50,000 strings in 12 languages and a translation team in a different time zone asking why the checkout button is broken in Arabic. The libraries handle the mechanics. The engineering discipline handles the scale.

Namespace Strategy: The Decision That Determines Maintainability

Flat key structures break at scale. A single en.json with 2,000 keys is unmaintainable by translators and breaks as feature ownership shifts between teams. We use a namespace-per-feature structure with strict boundaries.

• One namespace per route/feature: auth.json, checkout.json, dashboard.json, profile.json. Translators work on one file at a time and can see context.
• Shared namespace for common elements: common.json for buttons, form labels, error messages, navigation items used globally. Anything that appears in 3+ features goes in common.
• Never share keys across namespaces: Even if the text is identical today ('Save' in profile and checkout), keep them separate. They'll diverge in some language.
• Key naming convention: Flat dot-notation within namespaces. checkout.errors.cardDeclined is better than checkout.errors.card.declined because YAML/JSON deep nesting causes merge conflicts.

RTL Support: Do It From Day One

• Use logical CSS properties throughout: margin-inline-start instead of margin-left, padding-block instead of padding-top/bottom. These automatically flip for RTL without any CSS overrides.
• Flexbox direction just works: flex-direction: row reverses automatically in RTL. Don't manually flip icons or reverse arrays.
• Test with Urdu or Arabic from sprint 1: Not just placeholder text. Real Urdu text has different character joining rules and requires font support that reveals layout bugs early.