react-i18n

Implements react-i18next in a React 19 app (Vite/CRA, not Next.js): `useTranslation()` hook usage, the TypeScript Selector API (i18next ≥25.4) for type-safe translation keys, namespace organization for code splitting, pluralization with ICU MessageFormat, interpolation (variables, dates, numbers, currency), lazy-loaded translations, and browser/URL/cookie language detection.

Also covers React 19 Suspense integration, the Trans component for JSX inside translations, RTL language support, fallback strategies for missing keys, and unit-testing i18n setups. This skill is explicitly for React apps without Next.js — for Next.js App Router i18n use nextjs-i18n, and for Astro use astro-i18n.

react-i18next for React 19

Agent Workflow (MANDATORY)

Before ANY implementation, spawn 3 agents in parallel, one Agent call each with a name:

1. fuse-ai-pilot:explore-codebase - Analyze existing i18n setup and translation patterns
2. fuse-ai-pilot:research-expert - Verify latest react-i18next/i18next docs via Context7/Exa
3. mcp__context7__query-docs - Check TypeScript Selector API and React 19 Suspense patterns

After implementation, run fuse-ai-pilot:sniper for validation.

---

MANDATORY: SOLID Principles

ALWAYS apply SOLID principles from solid-react skill.

→ See ../solid-react/SKILL.md for complete rules

Key Rules:

• Files < 100 lines (split at 90)
• Interfaces in modules/[feature]/src/interfaces/
• JSDoc mandatory on all exports
• No business logic in components

---

Core Hooks

Hook	Purpose	Guide
useTranslation()	Access translations and i18n instance	references/i18next-basics.md
useTranslation(ns)	Load specific namespace	references/namespaces.md
useTranslation([ns])	Load multiple namespaces	references/namespaces.md

→ See references/i18next-basics.md for detailed usage

---

Key Packages

Package	Purpose	Size
i18next	Core library	~40KB
react-i18next	React bindings	~12KB
i18next-http-backend	Lazy loading	~5KB
i18next-browser-languagedetector	Auto-detection	~8KB

---

Key Features

TypeScript Selector API (i18next ≥25.4)

Type-safe translations with autocompletion. → See references/typescript-types.md

Namespaces

Organize translations by feature for code splitting. → See references/namespaces.md

Pluralization

Count-based rules with ICU MessageFormat support. → See references/pluralization.md

Interpolation

Variables, dates, numbers, and currency formatting. → See references/interpolation.md

Lazy Loading

Load translations on-demand per route. → See references/lazy-loading.md

Language Detection

Auto-detect from browser, URL, cookie, localStorage. → See references/language-detection.md

React 19 Integration

Suspense, useTransition, Concurrent Rendering. → See references/react-19-integration.md

Trans Component

JSX elements inside translations. → See references/trans-component.md

Testing

Mock i18n for unit tests. → See references/testing.md

RTL Support

Right-to-left languages (Arabic, Hebrew). → See references/rtl-support.md

Fallback Strategies

Handle missing keys gracefully. → See references/fallback-strategies.md

---

Templates

Template	Use Case
templates/basic-setup.md	Configuration with React 19
templates/language-switcher.md	Dropdown component
templates/typed-translations.md	TypeScript Selector API
templates/form-validation-i18n.md	Translated form errors
templates/lazy-loading-routes.md	Per-route loading
templates/date-number-formatter.md	Intl formatting
templates/plural-interpolation.md	Count-based messages
templates/trans-component-examples.md	JSX in translations
templates/testing-i18n.md	Unit test setup

---

Modular Architecture (SOLID)

src/
├── modules/cores/i18n/
│   ├── src/
│   │   ├── interfaces/
│   │   │   └── i18n.interface.ts
│   │   ├── services/
│   │   │   └── i18n.service.ts
│   │   ├── hooks/
│   │   │   └── useLanguage.ts
│   │   └── config/
│   │       └── i18n.config.ts
│   ├── components/
│   │   └── LanguageSwitcher.tsx
│   └── locales/
│       ├── en/
│       │   └── translation.json
│       └── es/
│           └── translation.json
└── main.tsx

---

Best Practices

1. Suspense: Wrap app with <Suspense> for loading states
2. Namespaces: One namespace per feature/module
3. TypeScript: Use Selector API for type-safe keys
4. Lazy Loading: Load namespaces on-demand
5. Detection: Configure language detection order
6. Fallback: Always set fallbackLng

---

Forbidden (Anti-Patterns)

• ❌ Hardcoded strings → use t('key')
• ❌ No Suspense → causes loading flicker
• ❌ All translations in one file → use namespaces
• ❌ No fallback language → broken UI
• ❌ String concatenation → use interpolation {{var}}
• ❌ Manual language state → use i18n.changeLanguage()