react-i18next for React 19

Agent Workflow (MANDATORY)

Before ANY implementation, launch in parallel:

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

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

Key Packages

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

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 concatenation → use interpolation {{var}}
• ❌ Manual language state → use i18n.changeLanguage()