How to Design a Frontend Internationalisation System

Organize translation files by locale and namespace. Each namespace corresponds to a major section of the application such as common, checkout, dashboard, and settings. Store translations as nested JSON files with the locale code and namespace as the path. This structure allows lazy loading only the namespaces needed for the current page rather than loading all translations on initial load, significantly reducing the JavaScript bundle size for applications with large translation catalogs.

Simple key-value translation fails for strings that must change based on count, gender, or other variables. Use ICU Message Format syntax to express these variations within a single translation string. ICU handles plural forms which vary significantly across languages, ordinal numbers, select statements for gender agreement, and variable interpolation with locale-appropriate formatting. Libraries like react-intl and i18next support ICU format and handle the grammatical complexity that simple string interpolation cannot.

Determine the user's preferred locale from multiple signals in priority order. First check a user preference stored in their account profile. Then check a locale cookie from a previous session. Then check the Accept-Language header from the browser. Finally fall back to the application default locale. Persist the user's locale choice explicitly to their profile or a cookie so the correct locale loads immediately on return visits without requiring detection again.

Dates, times, numbers, and currencies must be formatted according to locale conventions, not hard-coded patterns. June 5 2025 is 06/05/2025 in the United States but 05/06/2025 in the United Kingdom and 2025/06/05 in Japan. Use the JavaScript Internationalization API Intl.DateTimeFormat, Intl.NumberFormat, and Intl.RelativeTimeFormat for all formatting. Never use manual string concatenation or hard-coded separators. Pass the active locale to all Intl constructors to ensure locale-correct output.

Languages like Arabic and Hebrew read from right to left, requiring a mirrored layout. Set the dir attribute on the HTML element to rtl when a RTL locale is active. Use CSS logical properties like margin-inline-start instead of margin-left throughout the component library so spacing and positioning automatically mirror with the document direction. Use CSS Flexbox and Grid which respect the document direction by default. Test all components in RTL mode as a standard part of the release process.

As the application grows, tracking which translation keys exist, which are unused, and which are missing translations in specific locales becomes unmanageable manually. Integrate a translation management platform that provides a web interface for translators, tracks translation completeness per locale, alerts on missing keys when new keys are added to the source locale, and automates the export of updated translation files. Implement a CI check that fails if any locale is missing translations for keys present in the default locale.

User-generated content cannot be translated through static translation files. For applications serving content globally, implement locale-scoped content storage where the same content entity stores separate versions for each supported locale. Detect the user's locale and serve the appropriate content version. When a translation for the user's locale is unavailable, fall back through a defined fallback chain before showing the default locale version. Clearly indicate to users when they are viewing content in a fallback locale.

Loading all locales upfront increases initial bundle size proportionally with the number of supported languages. Implement locale-based code splitting where only the translation files for the active locale are loaded. Use dynamic imports triggered after locale detection resolves. Cache translation files aggressively at the CDN with content hashing for cache busting on updates. For server-rendered applications, inject only the active locale's translations into the initial HTML payload to avoid a flash of untranslated content.