react-i18n

React 19 アプリ（Vite/CRA、Next.js は対象外）で 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 つのエージェントを並行して起動してください。それぞれ 1 回の Agent 呼び出しで name を指定します。

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 を参照してください

主なルール：

• ソースファイルは FUSE_SOLID_MAX_LINES 以下に保ち、凝集性が低下したら責務ごとに分割します
• インターフェースは 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、Concurrent Rendering に対応します。 → 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() を使用します