/react-i18n

name: react-i18n
description: Use when implementing translations in a React app (not Next.js) with react-i18next — useTranslation, namespaces, pluralization, Suspense.
version: 1.0.0
user-invocable: true
references: references/i18next-basics.md, references/typescript-types.md, references/namespaces.md, references/pluralization.md, references/interpolation.md, references/lazy-loading.md, references/language-detection.md, references/react-19-integration.md, references/trans-component.md, references/testing.md, references/rtl-support.md, references/fallback-strategies.md, references/templates/basic-setup.md, references/templates/language-switcher.md, references/templates/typed-translations.md, references/templates/form-validation-i18n.md, references/templates/lazy-loading-routes.md, references/templates/date-number-formatter.md, references/templates/plural-interpolation.md, references/templates/trans-component-examples.md, references/templates/testing-i18n.md

<objective> 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. </objective>

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
│       └── fr/
│           └── 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 concatenat