react-i18n

React 19 アプリ（Next.js ではなく Vite／CRA）に react-i18next を実装します。`useTranslation()` フックの使い方、型安全な翻訳キーを実現する TypeScript Selector API（i18next ≥25.4）、コード分割のための名前空間の整理、ICU MessageFormat を使った複数形、補間（変数、日付、数値、通貨）、翻訳の遅延読み込み、ブラウザー／URL／Cookie による言語検出を扱います。

さらに、React 19 の Suspense 連携、翻訳内の JSX に使う Trans コンポーネント、RTL 言語のサポート、キーが見つからない場合のフォールバック戦略、i18n のユニットテスト設定も扱います。このスキルは Next.js を使わない React アプリを対象としています。Next.js App Router の i18n には nextjs-i18n を、Astro には astro-i18n を使用してください。

React 19 向け react-i18next

エージェントのワークフロー（必須）

実装を始める前に、3 つのエージェントを並行して起動してください。各エージェントにつき、name を指定して Agent を 1 回呼び出します。

1. fuse-ai-pilot:explore-codebase - 既存の i18n 設定と翻訳パターンを分析します
2. fuse-ai-pilot:research-expert - Context7／Exa で react-i18next／i18next の最新ドキュメントを確認します
3. mcp__context7__query-docs - TypeScript Selector API と React 19 の Suspense パターンを確認します

実装後、検証のために fuse-ai-pilot:sniper を実行してください。

---

必須：SOLID 原則

常に solid-react スキルの SOLID 原則を適用してください。

→ 詳しいルールについては ../solid-react/SKILL.md を参照してください。

主なルール：

• ファイルは 100 行未満にします（90 行で分割します）
• インターフェースは modules/[feature]/src/interfaces/ に配置します
• すべてのエクスポートに JSDoc を必須とします
• コンポーネントにビジネスロジックを含めません

---

主なフック

フック	目的	ガイド
useTranslation()	翻訳と i18n インスタンスにアクセスします	references/i18next-basics.md
useTranslation(ns)	特定の名前空間を読み込みます	references/namespaces.md
useTranslation([ns])	複数の名前空間を読み込みます	references/namespaces.md

→ 詳しい使い方については references/i18next-basics.md を参照してください。

---

主なパッケージ

パッケージ	目的	サイズ
i18next	コアライブラリ	約 40KB
react-i18next	React バインディング	約 12KB
i18next-http-backend	遅延読み込み	約 5KB
i18next-browser-languagedetector	自動検出	約 8KB

---

主な機能

TypeScript Selector API（i18next ≥25.4）

自動補完に対応した型安全な翻訳です。 → references/typescript-types.md を参照してください。

名前空間

コード分割のため、翻訳を機能ごとに整理します。 → references/namespaces.md を参照してください。

複数形

ICU MessageFormat に対応した、数に基づくルールです。 → references/pluralization.md を参照してください。

補間

変数、日付、数値、通貨の書式設定です。 → references/interpolation.md を参照してください。

遅延読み込み

ルートごとに必要に応じて翻訳を読み込みます。 → references/lazy-loading.md を参照してください。

言語検出

ブラウザー、URL、Cookie、localStorage から言語を自動検出します。 → references/language-detection.md を参照してください。

React 19 との連携

Suspense、useTransition、同時レンダリングに対応します。 → references/react-19-integration.md を参照してください。

Trans コンポーネント

翻訳内の JSX 要素に使用します。 → references/trans-component.md を参照してください。

テスト

ユニットテスト用に i18n をモックします。 → references/testing.md を参照してください。

RTL サポート

右から左に記述する言語（アラビア語、ヘブライ語）に対応します。 → references/rtl-support.md を参照してください。

フォールバック戦略

キーが見つからない場合に適切に処理します。 → references/fallback-strategies.md を参照してください。

---

テンプレート

テンプレート	用途
templates/basic-setup.md	React 19 での設定
templates/language-switcher.md	ドロップダウンコンポーネント
templates/typed-translations.md	TypeScript Selector API
templates/form-validation-i18n.md	フォームエラーの翻訳
templates/lazy-loading-routes.md	ルートごとの読み込み
templates/date-number-formatter.md	Intl による書式設定
templates/plural-interpolation.md	数に基づくメッセージ
templates/trans-component-examples.md	翻訳内の JSX
templates/testing-i18n.md	ユニットテストの設定

---

モジュール式アーキテクチャ（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

---

ベストプラクティス

1. Suspense：読み込み状態に対応するため、アプリを<Suspense>でラップします
2. 名前空間：機能／モジュールごとに1つの名前空間を使用します
3. TypeScript：型安全なキーにはSelector APIを使用します
4. 遅延読み込み：名前空間を必要に応じて読み込みます
5. 検出：言語検出の順序を設定します
6. フォールバック：必ずfallbackLngを設定します

---

禁止事項（アンチパターン）

• ❌ 文字列のハードコード → t('key')を使用します
• ❌ Suspenseを使用しない → 読み込み時にちらつきが発生します
• ❌ すべての翻訳を1つのファイルにまとめる → 名前空間を使用します
• ❌ フォールバック言語を設定しない → UIが正しく表示されません
• ❌ 文字列連結 → 補間{{var}}を使用します
• ❌ 言語状態を手動で管理する → i18n.changeLanguage()を使用します