Software Localisation

Software Localisation - Quick Reference

Production patterns for internationalisation (i18n) and localisation (l10n) in modern web applications. Covers library selection, translation management, ICU message format, RTL support, and CI/CD workflows.

Snapshot (2026-01): i18next 25.x, react-i18next 16.x, react-intl 8.x, vue-i18n 11.x, next-intl 4.x, @angular/localize 21.x. Always verify current versions in the target repo (see Currency Check Protocol).

Authoritative References:

• i18next Documentation
• FormatJS/react-intl
• ICU Message Format
• MDN Intl API

Quick Reference

Decision Tree: Library Selection

Project requirements:
    │
    ├─ React/Next.js project?
    │   ├─ ICU-first message catalogs + FormatJS tooling?
    │   │   └─ react-intl (FormatJS)
    │   │
    │   ├─ Flexibility, plugins, lazy loading?
    │   │   └─ react-i18next
    │   │
    │   ├─ Bundle size critical?
    │   │   └─ LinguiJS (ICU syntax)
    │   │
    │   └─ TypeScript-first, compile-time safety?
    │       └─ typesafe-i18n
    │
    ├─ Vue/Nuxt project?
    │   └─ vue-i18n (Composition API)
    │
    ├─ Angular project?
    │   ├─ Built-in solution preferred?
    │   │   └─ @angular/localize (first-party, AOT support)
    │   │
    │   └─ Need i18next ecosystem?
    │       └─ angular-i18next (wrapper)
    │
    └─ Framework-agnostic / Node.js?
        └─ i18next core (works everywhere)

Library Comparison

Core Concepts

Character Encoding (Critical)

Always use UTF-8 across your entire stack to prevent text corruption:

PASS Required: UTF-8 everywhere
- Database: utf8mb4 (MySQL) or UTF-8 (PostgreSQL)
- HTML: <meta charset="UTF-8">
- HTTP headers: Content-Type: text/html; charset=utf-8
- File encoding: Save all source files as UTF-8
- API responses: JSON with UTF-8 encoding

UTF-8 supports all Unicode characters including emojis, mathematical symbols, and all language scripts. Inconsistent encoding causes: corrupted characters (�), failed searches for accented names, and rejected international input.

Translation Key Patterns

// Flat keys (simple)
"welcome": "Welcome to our app"
"user.greeting": "Hello, {name}"

// Nested keys (organised)
{
  "user": {
    "greeting": "Hello, {name}",
    "profile": {
      "title": "Your Profile"
    }
  }
}

// Namespace separation (scalable)
// common.json, auth.json, dashboard.json

ICU Message Format Essentials

// Simple interpolation
"Hello, {name}!"

// Pluralisation
"{count, plural, one {# item} other {# items}}"

// Select (gender, category)
"{gender, select, male {He} female {She} other {They}} liked your post"

// Number formatting
"Price: {price, number, currency}"

// Date formatting
"Posted: {date, date, medium}"

Locale Detection Strategy

Priority order:
1. User preference (stored in profile/localStorage)
2. URL parameter or path (/en/about, ?lang=de)
3. Cookie (NEXT_LOCALE, i18next)
4. Accept-Language header
5. Default locale fallback

Navigation

Resources (Deep Dives)

• references/framework-guides.md - React, Vue, Angular, Next.js implementation
• references/icu-message-format.md - Pluralisation, select, formatting
• references/translation-workflows.md - TMS, CI/CD, string extraction
• references/rtl-support.md - Right-to-left language support
• references/locale-handling.md - Dates, numbers, currencies

Templates (Production Starters)

• assets/react-i18next-setup.md - React + i18next complete setup
• assets/vue-i18n-setup.md - Vue 3 + vue-i18n setup
• assets/nextjs-i18n-setup.md - Next.js App Router i18n

Data

• data/sources.json - 60+ curated external references

Related Skills

• ../software-frontend/SKILL.md - Frontend architecture patterns (React, Vue, Angular, Next.js)
• ../marketing-seo-complete/SKILL.md - Hreflang, international SEO

Common Patterns

Namespace Organisation

locales/
├── en/
│   ├── common.json      # Shared: buttons, errors, nav
│   ├── auth.json        # Login, register, password
│   ├── dashboard.json   # Dashboard-specific
│   └── validation.json  # Form validation messages
├── de/
│   └── ... (same structure)
└── ar/
    └── ... (same structure)

Lazy Loading (Performance)

// i18next: Load namespaces on demand
i18n.loadNamespaces('dashboard').then(() => {
  // Dashboard translations now available
});

// React Suspense integration
<Suspense fallback={<Loading />}>
  <Dashboard />
</Suspense>

TypeScript Integration

// resources.d.ts - Type-safe keys
import common from './locales/en/common.json';

declare module 'i18next' {
  interface CustomTypeOptions {
    defaultNS: 'common';
    resources: {
      common: typeof common;
    };
  }
}

// Now t('nonexistent') shows TypeScript error

Anti-Patterns to Avoid

Operational Checklist

Initial Setup

• REQUIRED: Choose i18n library based on decision tree
• REQUIRED: Set up directory structure for translations
• REQUIRED: Configure fallback locale chain
• REQUIRED: Set up locale detection strategy
• REQUIRED: Add TypeScript types for translation keys
• REQUIRED: Configure lazy loading for namespaces

Translation Workflow

• REQUIRED: Set up string extraction (i18next-parser, formatjs, Lingui)
• REQUIRED: Integrate with a TMS when needed (Phrase, Lokalise, Crowdin, Locize)
• REQUIRED: Configure CI/CD for translation sync
• REQUIRED: Set up translation review process (glossary + style guide + QA gates)
• REQUIRED: Add missing key detection in development

RTL Support

• REQUIRED: Use CSS logical properties (margin-inline-start)
• REQUIRED: Set dir="rtl" for RTL locales
• REQUIRED: Test with real RTL content (Arabic, Hebrew)
• REQUIRED: Handle bidirectional text (BiDi) in mixed strings
• REQUIRED: Mirror directional icons and images where appropriate

Testing

• REQUIRED: Test pluralisation with 0, 1, 2, 5, 21 (language-specific)
• REQUIRED: Test date/number/currency formatting per locale
• REQUIRED: Test RTL layout in key screens/components
• REQUIRED: Test missing translation key handling (dev-only warnings)
• REQUIRED: Test locale switching and persistence (cookie/storage/url)

Currency Check Protocol

When recommending libraries, versions, or tooling, verify what is current for the target ecosystem and project constraints. Prefer package registries and release notes over stale hard-coded numbers.

Package versions (Node/npm)

npm view i18next version
npm view react-i18next version
npm view react-intl version
npm view vue-i18n version
npm view next-intl version
npm view @angular/localize version
npm view @lingui/core version
npm view typesafe-i18n version

"Is X still recommended?" checks

• Check the project's last release date, open issues, and maintenance activity (GitHub releases/issues).
• Check framework compatibility (Next.js App Router/RSC, React 19, Vue 3, Angular current major).
• For bundle concerns, measure in the real app with a bundle analyzer instead of relying on published size claims.