Frontend Internationalization (i18n)
Frontend internationalization designs UIs to adapt to many languages and regions without code changes by separating translatable text from logic and formatting per locale. Building it in early is far cheaper than retrofitting later.
Best Practice: Frontend Internationalization (i18n)
Internationalization (i18n) is the practice of designing and building a frontend so it can be adapted to different languages, regions, and cultural conventions without changing the code. Localization (l10n) is the later act of producing each specific adaptation. The W3C Internationalization Activity provides authoritative guidance. Good i18n separates user-facing text from logic, handles plurals, dates, numbers, and currencies per locale, and supports varied scripts and text directions such as right-to-left. Building it in from the start is far cheaper than retrofitting it after launch.
Step-by-Step Implementation Guidance
- Externalize all user-facing strings into resource files keyed by message ID.
- Use an i18n library to load locale bundles and format messages.
- Format dates, numbers, and currencies with the Intl API rather than hardcoding.
- Handle pluralization and gender with ICU MessageFormat, not string concatenation.
- Set the lang attribute and support right-to-left layouts with logical CSS properties.
- Allow flexible space for text expansion in different languages.
- Pseudo-localize early to catch hardcoded strings and layout breaks.
Common Mistakes Teams Make When Ignoring This Practice
- Hardcoding text in components, making translation impossible without code edits.
- Concatenating sentence fragments that cannot be translated correctly.
- Assuming Latin scripts and left-to-right layout everywhere.
- Formatting dates and numbers with fixed patterns.
- Designing fixed-width UI that breaks when translated text is longer.
Tools and Techniques That Support This Practice
- The ECMAScript Intl API for dates, numbers, and plurals.
- Libraries such as i18next, FormatJS/react-intl, and Vue I18n.
- ICU MessageFormat for plurals and selects.
- Translation management platforms like Crowdin or Lokalise.
How This Practice Applies to Different Migration Types
- Cloud Migration: Serve locale bundles from a CDN and route by region.
- Database Migration: Store content with locale and encoding metadata (UTF-8 throughout).
- SaaS Migration: Verify the new platform supports your target locales and RTL.
- Codebase Migration: Replace hardcoded strings with message catalogs during the port.
Checklist
- All user-facing strings externalized.
- Locale-aware date, number, and currency formatting.
- Plurals handled via ICU MessageFormat.
- lang attribute and RTL support in place.
- Layouts allow for text expansion.
- Pseudo-localization tested.
- UTF-8 used end to end.