software-localisation

name

software-localisation

description

Production-grade i18n/l10n patterns for React, Vue, Angular, Next.js, and Node.js. Covers library selection (i18next/react-i18next, FormatJS/react-intl, next-intl, vue-i18n, @angular/localize, Lingui, typesafe-i18n), ICU message format, RTL support, locale routing/detection, TMS integration, string extraction, and CI/CD translation workflows. Use when setting up or debugging localisation in a codebase.

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

Task	Tool/Library	Command	When to Use
React i18n	react-i18next	npm i i18next react-i18next	Most React apps, flexibility
React i18n (ICU)	react-intl (FormatJS)	npm i react-intl	ICU-first message catalog + tooling
Vue i18n	vue-i18n	npm i vue-i18n	Vue 3 apps
Angular i18n	@angular/localize	ng add @angular/localize	Angular apps
Next.js i18n	next-intl	npm i next-intl	Next.js App Router
Minimal bundle	LinguiJS	npm i @lingui/core @lingui/react	Bundle size critical
Type-safe	typesafe-i18n	npm i typesafe-i18n	TypeScript-first projects
String extraction	i18next-parser	npx i18next-parser	Extract keys from code
ICU linting	@formatjs/cli	npx formatjs extract	Validate ICU messages

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

Library	ICU Support	Lazy Loading	TypeScript	Best For
react-i18next	Plugin/optional	Native	Good	Flexible, popular React choice
react-intl	Native	Manual	Good	ICU-first catalogs + tooling
LinguiJS	Native	Native	Excellent	Bundle-conscious apps
typesafe-i18n	Limited	Manual	Excellent	Compile-time key safety
vue-i18n	Native	Native	Good	Vue 3 apps
@angular/localize	Native	AOT	Native	Angular apps

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

Anti-Pattern	Problem	Fix
Hardcoded strings	Not translatable	Extract all user-facing text
String concatenation	Breaks translation context	Use interpolation {name}
Manual pluralisation	Wrong for many languages	Use ICU plural rules
Inline styles for RTL	Doesn't scale	Use CSS logical properties
Storing locale in URL only	Lost on navigation	Also persist to cookie/storage
No fallback locale	Blank text for missing keys	Always set fallbackLng
Loading all locales upfront	Slow initial load	Lazy load per namespace/locale

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.