i18n

Internationalization (i18n)

This skill covers the practical patterns for shipping a multi-language web application. It focuses on the JavaScript ecosystem (i18next, react-i18next, next-i18next) — for native Apple platforms see swift-localization.

When to Use

• Adding a second language to an existing web application
• Setting up i18n from scratch in a new project
• Reviewing i18n implementation for correctness (pluralization, interpolation, locale routing)
• A language is displaying incorrectly (wrong pluralization, hardcoded strings, locale mismatch)

When NOT to Use

• iOS/macOS/SwiftUI apps — use swift-localization
• Backend-only services where user-facing strings are not generated (API error codes are not translated — only client-facing text is)

Core Principles

No Strings in Components

Every user-visible string lives in a translation file. A hardcoded string in a component is a bug, not a shortcut. This includes: button labels, error messages, placeholder text, aria-label values, and <title> tags.

Translation Keys are Contracts

A translation key is a stable identifier. Renaming a key breaks all translations for that key in every language. Keys are kebab-case, descriptive, and namespaced to their feature.

ICU Format for Complex Messages

Use ICU message format (supported natively by i18next-icu) for plurals, selects, and interpolated values. Do not concatenate translated strings — word order differs between languages.

Setup

Install:

pnpm add i18next react-i18next i18next-resources-to-backend
# For Next.js App Router:
pnpm add next-i18next
# ICU message format:
pnpm add i18next-icu

i18n configuration:

// src/i18n/config.ts
import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
import resourcesToBackend from 'i18next-resources-to-backend';
import ICU from 'i18next-icu';

i18n
  .use(ICU)
  .use(resourcesToBackend((language: string, namespace: string) =>
    import(`../locales/${language}/${namespace}.json`)
  ))
  .use(initReactI18next)
  .init({
    lng: 'en',
    fallbackLng: 'en',
    supportedLngs: ['en', 'pl', 'de'],
    defaultNS: 'common',
    interpolation: { escapeValue: false }, // React escapes by default
    missingKeyHandler: (lng, ns, key) => {
      // Log missing keys in dev, silently fall back in prod
      if (process.env.NODE_ENV === 'development') {
        console.warn(`Missing translation: ${lng}/${ns}/${key}`);
      }
    },
  });

export default i18n;