Locale-aware i18n ルーティング（next-intl）

定義

Locale-aware routing（ロケール対応ルーティング）とは、ユーザーが選んだ言語（ko/en/ja）がすべての内部 URL とクライアントナビゲーションに一貫して反映されるルーティング方式です。

next-intl で localePrefix: "always" を使うと、URL は常に /ko/til、/en/knowledge/... の形になり、プレフィックスのない /til のようなパスはミドルウェアがデフォルト locale（例: /ko/til）へ 301 リダイレクトします。

なぜ必要か

コンテンツは en/ja に増えたのに、ヘッダー・サイトマップ・カードが plain な next/link で /til を指していると、/en からクリックするたびにミドルウェアが /ko/til に送り、言語選択が毎回リセットされます。翻訳品質の問題ではなく、ルーティング契約の違反です。

逆に @/i18n/navigation の Link・useRouter は現在の locale を href に自動で含めます。SSR HTML の href をサンプリングすれば、bare path の回帰を素早く検出できます。

動作の仕組み

1. ミドルウェア: localePrefix: "always" → bare pathname 検出時に default locale へ redirect。
2. i18n Link: href="/til" → レンダー時 /en/til（現在 locale 基準）。
3. plain next/link: href="/til" のまま → ミドルウェア 301 → /ko/til。
4. 言語選択 UI: routing.locales を単一ソースに Dropdown・sitemap・メッセージキーを同期。
5. programmatic nav: router.push、replace も i18n router を使用。startTransition・view transition と併用可能。
6. Markdown 本文リンク: remark 段階で locale prefix 変換（アプリ shell の Link とは別パイプライン）。

実務での適用

• content-nav・footer・リストカード・パンくずを grep し、next/link の内部利用を除去する。
• detail の未翻訳 fallback はページごとのコピペではなく getLocalizedDocumentOrRedirect ヘルパー + テスト。
• prod next start 後 curl で /en/... HTML の internal href が en-prefixed かカウント（bare 0 件を目標）。
• load-more・relations API にアクティブ locale のクエリパラメータまたはヘッダーを渡す。
• ESLint カスタムルールまたは codemod で src/ 内の from "next/link" 新規利用をレビュー。

トレードオフ

使うべきでない場合

• 外部サイト・mailto:・絶対 URL — plain <a> または full URL 付き next/link は locale と無関係。
• API route・静的 asset — locale segment なし。
• localePrefix: "never" ポリシー — この文書の always 前提と異なる。

よくある間違い

• ヘッダーだけ i18n Link に変え、content-nav 12 箇所は plain next/link のまま。
• クライアントだけ locale prefix を付け、SSR HTML は bare → SEO・no-JS 環境で ko に飛ぶ。
• router.back() に view transition を期待 — popstate は同期のため VT 非対応（明示 URL の push が必要）。
• markdown 本文の ../knowledge/... リンクを locale 変換パイプラインなしでデプロイ。

関連概念

• multilingual-content-locale-suffix — コンテンツ locale 軸
• hierarchical-document-navigation — 一覧→詳細の depth
• ssr-hydration-mismatch — SSR HTML とクライアント href の一致