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.

Modern Best Practices (Dec 2025): react-i18next 15.x (2.1M weekly downloads), react-intl 7.x (FormatJS), vue-i18n 10.x (Vue 3 Composition API), @angular/localize 19.x, LinguiJS 5.x (smallest bundle). ICU MessageFormat 2.0 draft, CLDR 46. TMS leaders: Phrase, Lokalise, Crowdin.

Authoritative References:

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

Quick Reference

When to Use This Skill

Use this skill when the user requests:

• Setting up i18n/l10n in a React, Vue, Angular, or Next.js project
• Choosing between i18n libraries (i18next vs react-intl vs LinguiJS)
• Implementing pluralisation, interpolation, or ICU message format
• Adding RTL (right-to-left) language support
• Integrating with translation management systems (TMS)
• Setting up CI/CD pipelines for translation workflows
• Handling dates, numbers, currencies across locales
• Lazy loading translations for performance
• TypeScript integration with i18n

Decision Tree: Library Selection

Project requirements:
    │
    ├─ React/Next.js project?
    │   ├─ Enterprise, ICU/CLDR standards, TMS-first?
    │   │   └─ react-intl (FormatJS) — 17.8 kB, native ICU
    │   │
    │   ├─ Flexibility, plugins, lazy loading?
    │   │   └─ react-i18next — 22.2 kB, most popular
    │   │
    │   ├─ Bundle size critical (<15 kB)?
    │   │   └─ LinguiJS — 10.4 kB, ICU syntax
    │   │
    │   └─ TypeScript-first, compile-time safety?
    │       └─ typesafe-i18n — 2 kB runtime
    │
    ├─ Vue/Nuxt project?
    │   └─ vue-i18n — Native Vue integration, Composition API
    │
    ├─ Angular project?
    │   ├─ Built-in solution preferred?
    │   │   └─ @angular/localize — First-party, AOT support
    │   │
    │   └─ Need i18next ecosystem?
    │       └─ angular-i18next — Plugin wrapper
    │
    └─ Framework-agnostic / Node.js?
        └─ i18next core — Works everywhere

Library Comparison

Core Concepts

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)

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

Templates (Production Starters)

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

Data

• data/sources.json — 50+ curated external references

Related Skills

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

Quick Setup Examples

React + i18next (5 minutes)

npm install i18next react-i18next i18next-http-backend i18next-browser-languagedetector

// src/i18n.ts
import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
import Backend from 'i18next-http-backend';
import LanguageDetector from 'i18next-browser-languagedetector';

i18n
  .use(Backend)
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    fallbackLng: 'en',
    debug: process.env.NODE_ENV === 'development',
    ns: ['common', 'auth', 'dashboard'],
    defaultNS: 'common',
    interpolation: { escapeValue: false },
    backend: { loadPath: '/locales/{{lng}}/{{ns}}.json' }
  });

export default i18n;

// Usage in component
import { useTranslation } from 'react-i18next';

function Welcome() {
  const { t } = useTranslation();
  return <h1>{t('welcome')}</h1>;
}

Vue 3 + vue-i18n (5 minutes)

npm install vue-i18n

// src/i18n.ts
import { createI18n } from 'vue-i18n';

export const i18n = createI18n({
  legacy: false, // Composition API
  locale: 'en',
  fallbackLocale: 'en',
  messages: {
    en: { welcome: 'Welcome' },
    de: { welcome: 'Willkommen' }
  }
});

<script setup lang="ts">
import { useI18n } from 'vue-i18n';
const { t } = useI18n();
</script>

<template>
  <h1>{{ t('welcome') }}</h1>
</template>

Next.js App Router + next-intl (5 minutes)

npm install next-intl

// i18n/request.ts
import { getRequestConfig } from 'next-intl/server';

export default getRequestConfig(async ({ locale }) => ({
  messages: (await import(`../messages/${locale}.json`)).default
}));

// app/[locale]/page.tsx
import { useTranslations } from 'next-intl';

export default function Home() {
  const t = useTranslations('Home');
  return <h1>{t('welcome')}</h1>;
}

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

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

Translation Workflow

• Set up string extraction (i18next-parser, formatjs)
• Integrate with TMS (Phrase, Lokalise, Crowdin)
• Configure CI/CD for translation sync
• Set up translation review process
• Add missing key detection in development

RTL Support

• Use CSS logical properties (margin-inline-start)
• Add dir="rtl" to html/body for RTL locales
• Test with actual RTL content (Arabic, Hebrew)
• Handle bidirectional text (BiDi)
• Mirror icons and images where appropriate

Testing

• Test pluralisation with 0, 1, 2, 5, 21 (language-specific)
• Test date/number formatting per locale
• Test RTL layout in all components
• Test missing translation key handling
• Test locale switching without page reload