fusengine/react-i18n

react-i18next for React 19

Agent Workflow (MANDATORY)

Before ANY implementation, use TeamCreate to spawn 3 agents:

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