nextjs-i18n

next-intl（推奨 — Server Components の完全サポート、型安全なメッセージ、ICU MessageFormat、非同期メッセージ読み込み、proxy.ts 互換のルーティング）または動的インポートを用いた軽量な DIY 辞書アプローチの 2 つの方法で、Next.js 16 App Router アプリの国際化を実装します。

[locale] プレフィックス付きルーティング、ローカライズされたナビゲーションコンポーネント（Link、redirect、usePathname、useRouter）、日付・数値・通貨・相対時間のフォーマット、RTL 言語サポート、SEO の hreflang タグ、ローカライズされた特殊ファイル（[locale]/error.tsx、[locale]/not-found.tsx、global-error.tsx）を扱います。これは Next.js 固有の i18n スキルです（App Router ルーティング、proxy.ts 連携）— Next.js を使用しないプレーンな React アプリについては react-i18n を、Astro については astro-i18n を参照してください。

Next.js 16 の国際化

next-intl または DIY 辞書アプローチによる完全な i18n ソリューションです。

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

実装を行う前に、3 つのエージェントを並列で起動してください。それぞれ name を指定した Agent 呼び出しを 1 回ずつ行います。

1. fuse-ai-pilot:explore-codebase - 既存の i18n 設定とメッセージファイルを分析します
2. fuse-ai-pilot:research-expert - Context7/Exa 経由で最新の next-intl ドキュメントを検証します
3. mcp__context7__query-docs - ロケール設定とパターンを確認します

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

---

概要

使用する場面

• 多言語の Next.js 16 アプリケーションを構築する場合
• [locale] 動的セグメントを用いたロケールベースのルーティングが必要な場合
• 言語切り替えと URL のローカライズを実装する場合
• ロケールごとに日付、数値、通貨、相対時間をフォーマットする場合
• hreflang タグとローカライズされたメタデータによる SEO 最適化を行う場合
• 右から左（RTL）言語をサポートする場合

next-intl を選ぶ理由

機能	メリット
App Router ネイティブ	Server Components を完全サポート
型安全なメッセージ	キーに対する TypeScript のオートコンプリート
ICU MessageFormat	複数形、性別、select 式
非同期メッセージ読み込み	ロケールごとに翻訳をオンデマンドで読み込み
proxy.ts 互換	Next.js 16 の proxy パターンで動作
豊富なフォーマット	日付、数値、リスト、相対時間

---

2 つのアプローチ

1. next-intl（推奨）

ルーティング、フォーマット、型安全性を備えたフル機能のライブラリです。包括的な i18n サポートを必要とする本番アプリケーションに最適です。

2. DIY 辞書

シンプルな翻訳ニーズに対応する、動的インポートを用いた軽量なアプローチです。依存関係を最小限に抑えたいプロジェクトに適しています。

---

SOLID アーキテクチャ

モジュール構成

すべての i18n コードは modules/cores/i18n/ に整理します。

• config/ - ルーティング設定、ロケール定義
• interfaces/ - メッセージとロケールの TypeScript 型
• services/ - リクエストハンドラー、メッセージローダー
• messages/ - ロケールごとの JSON 翻訳ファイル

ファイルの配置

• src/modules/cores/i18n/src/config/routing.ts - ロケールルーティング設定
• src/modules/cores/i18n/messages/en.json - 英語の翻訳
• src/modules/cores/i18n/messages/es.json - スペイン語の翻訳
• proxy.ts - ロケール検出とリダイレクトのロジック

---

ルーティングパターン

ロケールセグメント

すべてのルートに [locale] 動的セグメントをプレフィックスとして付けます。

• /en/about → 英語の about ページ
• /es/about → スペイン語の about ページ
• / → デフォルトロケールへリダイレクト

ナビゲーションコンポーネント

next-intl のローカライズされたナビゲーションを使用して、ロケールを自動的に処理します。

• Link - ロケールを認識するアンカーリンク
• redirect - サーバーサイドのロケールリダイレクト
• usePathname - ロケールを除いた現在のパス
• useRouter - プログラムによるナビゲーション

---

リファレンスガイド

ニーズ	リファレンス
初期セットアップ	installation.md、routing-setup.md
ルート設定	routing-config.md、middleware-proxy.md
翻訳	translations.md、messages-validation.md
フォーマット	formatting.md
コンポーネント	server-components.md、client-components.md
ナビゲーション	navigation.md
TypeScript	typescript.md
SEO	seo.md
テスト	testing.md
DIY アプローチ	diy-dictionaries.md、diy-locale-detection.md

---

メッセージのフォーマット

ICU MessageFormat

• 複数形化 - {count, plural, one {# item} other {# items}}
• 選択 - {gender, select, male {He} female {She} other {They}}
• リッチテキスト - メッセージ内の太字、斜体、リンクをサポート

フォーマッター

• formatDate - ロケール対応の日付フォーマット
• formatNumber - 通貨、パーセンテージ、小数
• formatList - 結合/選言リスト
• formatRelativeTime - 「2時間前」、「3日後」

---

ベストプラクティス

1. 型安全なキー - メッセージキーの自動補完に TypeScript を使用する
2. メッセージの名前空間化 - 保守性のために機能/ページ単位で整理する
3. サーバーファースト - 翻訳はサーバーで読み込み、クライアントバンドルを避ける
4. SEO hreflang - すべてのロケールに代替リンクを追加する
5. RTL サポート - 右から左に記述する言語には dir 属性を使用する
6. フォールバックロケール - 翻訳が欠けている場合のデフォルトを設定する

---

エラーハンドリング

特殊ファイル

ローカライズされたエラー状態とローディング状態には、専用の対応が必要です：

• [locale]/error.tsx - ローカライズされたエラーバウンダリ
• [locale]/not-found.tsx - ローカライズされた 404 ページ
• global-error.tsx - ルートエラーのフォールバック

完全なパターンについては error-files.md を参照してください。