intlayer

Intlayer

Intlayer の i18n に関する作業では、このスキルを使用してください。特に TanStack Start（@tanstack/react-start）と intlayer + react-intlayer + vite-intlayer を使用する Intlayer 9.6（[email protected]。API は 9.5 系と同じ）が対象です。

intlayer / react-intlayer / vite-intlayer（およびすべての @intlayer/* / *-intlayer パッケージ）は、同じ正確なバージョンに固定してください（このスナップショットでは 9.6.0）。9.0～9.4 のドキュメントやパッケージを、9.5 以降の API（useExperiment、build.chunkGrouping、build.dictionariesPreload、CLI の --ci、vite-intlayer/nitro-handler）と混在させないでください。bunx intlayer upgrade（9.5.8 以降）でまとめてアップグレードしてください。

スナップショット：2026-10-01。バージョンが異なる場合は、source-map.md を参照して最新情報に更新してください。

ワークフロー

1. コードを変更する前に、ローカル環境の Intlayer と Start の構成を確認してください。
   • intlayer、react-intlayer、vite-intlayer、@tanstack/react-start、@tanstack/react-router のパッケージバージョン（すべての Intlayer パッケージのバージョンを一致させてください）。
   • 設定：intlayer.config.ts のロケール、routing.mode、routing.enableProxy、routing.storage、content.contentDir、dictionary.importMode、dictionary.fill、compiler.enabled、build.optimize / minify / purge / chunkGrouping / dictionariesPreload、editor、analytics、ai、plugins。
   • Vite：intlayer() プラグイン（proxy.ignore、任意の compatCallers）、tanstackStart({ router: { routeFileIgnorePattern } })、Nitro プラグイン。
   • ルート：src/routes/__root.tsx のシェルと IntlayerProvider、validatePrefix を含む src/routes/{-$locale}/ のレイアウト。
   • コンテンツ：*.content.{ts,tsx,js,json,...} のディクショナリーと生成された .intlayer/ の出力。
   • ナビゲーション：LocalizedLink、useLocalizedNavigate、その他の Link / navigate ラッパーは使用せず、ネイティブの TanStack Router API のみを使用してください。
2. 最新の挙動、9.5 の API、CMS / エディター / アナリティクス、またはパッケージの不整合にタスクが関係する場合は、ドキュメントを最新情報に更新してください。source-map.md から確認を始めてください。
3. インストール、設定、Vite プラグイン、プロバイダー、Nitro ハンドラー、TypeScript の include 設定については、setup-tanstack-start.md を使用してください。
4. intlayer.config.ts の設定項目（routing、dictionary、compiler、build、editor、analytics、AI、plugins）については、configuration.md を使用してください。
5. コンテンツ宣言、ノードヘルパー、コレクション / バリアント、フォーマッター、useIntlayer については、content-dictionaries.md を使用してください。
6. ロケールルーティング、ネイティブのリンク / navigate、SSR の getLocale / getIntlayerAsync、SEO の head、サイトマップ、404 については、routing-ssr-seo.md を使用してください。
7. CLI、fill、--ci、CMS、ビジュアルエディター、ライブ同期、MCP、@intlayer/analytics については、cli-cms-ai.md を使用してください。
8. コンパイラーによる抽出、バンドルの optimize / minify / purge、チャンクのグループ化 / プリロード、import モード、互換アダプター、syncJSON については、compiler-compat.md を使用してください。
9. コマンド例では bun / bunx を優先してください。Next.js や Solid Start のドキュメントよりも公式の Start ガイドを優先してください。ただし、Intlayer の LocalizedLink / useLocalizedNavigate の例はコピーせず、代わりにネイティブの TanStack Router Link / useNavigate を使用してください。

実装時の判断

• TanStack Start では intlayer + react-intlayer + vite-intlayer を使用します。next-intlayer／next-intlayer/server または solid-intlayer の API をインストールしたり、コピーしたりしないでください。tanstack-intlayer パッケージはありません。Start では react-intlayer/server の IntlayerServerProvider を使用しないでください。
• Next.js 9.4+ では、IntlayerClientProvider／IntlayerServerProvider は IntlayerProvider に統合されています。Start ではすでに react-intlayer の IntlayerProvider を使用しています。
• ロケール検出／リダイレクトには、TanStack Router のミドルウェア API ではなく、Vite の intlayer() プロキシを使用します。現在の設定型では routing.enableProxy のデフォルトは **undefined（自動）**です。プロキシが実行され、開発／プレビューでは URL 主導（保存済みロケールを無視）となり、本番環境ではストレージ主導の完全なリダイレクトが行われます。どの環境でもストレージ主導のリダイレクトを強制するには true を設定し、プロキシを無効にするには false を設定します。
• 本番環境の SSR プロキシは vite-intlayer/nitro-handler（h3 v2 Web Fetch）です。intlayer()／intlayerProxy は、nitro/vite が挿入する .nitro プロパティ経由で自動登録します。Bun／Deno では fromNodeMiddleware(createIntlayerProxyHandler(...)) を設定しないでください。これはクラッシュします（event.node が未定義です）。本番環境でプロキシを実行する場合は、vite-intlayer をランタイムの dependencies に含めてください。
• Link／navigate ラッパーは使用しないでください。 ロケールを注入するために TanStack の Link／useNavigate をラップする LocalizedLink、useLocalizedNavigate、またはコンポーネント／フックを作成、維持、推奨しないでください。ネイティブの Link と useNavigate を、完全な to パス（/{-$locale}/...）および getPrefix(locale).localePrefix の params.locale とともに使用します。レビュー／移行時には、既存のラッパーを削除し、呼び出し箇所を書き換えてください。公式の Start ドキュメントと Start テンプレートにはまだラッパーが含まれていますが、これらのサンプルは無視してください。
• コンテンツファイルがルートとして扱われないよう、常に .content.* に対して routeFileIgnorePattern を設定してください。
• ロケールのルートスロットは routing.mode に合わせてください。prefix-no-default では {-$locale}、prefix-all では $locale を優先し、no-prefix／search-params ではスロットを削除します。
• クライアント UI：react-intlayer の useIntlayer／useLocale。ロケール対応のフォーマッター：react-intlayer/format。A/B：react-intlayer（または react-intlayer/analytics）の useExperiment。サーバー関数、head、ローダー、React 以外のコード：intlayer の getIntlayerAsync／getLocale。全ロケールを統合した辞書を使用しても問題ない場合に限り、同期版の getIntlayer を使用してください。Start では常にロケールを明示的に渡してください。9.5.12 以降、省略したロケールはリクエストのロケール（Next.js のヘッダー／Cookie のみ）、次に保存済みロケール、最後にデフォルトの順に解決されるため、プロバイダー外では SSR とハイドレーションで不一致が生じる可能性があります。
• ルートの head には 3 つの解決モードがあります（ルーティングのリファレンスを参照）。getIntlayerAsync を優先してください。LCP に影響するメタデータは、staleTime: Infinity を指定して loader で解決し、同期型の head から loaderData を読み取ります。辞書が非常に小さい場合を除き、9.4+ の head で同期版の getIntlayer を使用しないでください。
• beforeLoad では、Cookie／ヘッダーではなく、params.locale から validatePrefix を使ってロケールを検証してください（リクエストのロケールはすでにプロキシが処理しています）。
• .content.* は機能ごとに配置してください。src 配下にある Start アプリでは、content.contentDir を明示的に設定してください（設定のデフォルトは ["."] であり、Next.js 形式の ./app ではありません）。
• compiler.enabled のデフォルトは false です。値は false | true | "build-only"（開発時はスキップ）です。バンドルされたプロキシ／コンパイラー／チャンク／プリロードは intlayer() 内に含まれます。プラグインの順序上必要な場合を除き、個別に intlayerProxy()／intlayerCompiler()／intlayerChunk()／intlayerPreload() を要求しないでください。
• HTML 属性（alt、title、aria-label）には、コンテンツノードの .value、.toString()、または String(...) を使用してください。
• 識別子：plural／enu（数量）、cond（ブール値）、gender、select（その他の任意の文字列、9.1）。実行時キー（node[status]）を使ってコンテンツオブジェクトにインデックスアクセスしないでください。代わりに node(status) を呼び出すと、コンパイラーが圧縮／削除できます。
• コレクションは key と item を共有します。バリアントには variant: string | object を使用します（9.1 では、従来の動的レコードがオブジェクトのバリアントに統合されています）。セレクター：{ locale, item, variant }。解決順序：variant → item。
• editor.enabled が true の場合、build.minify を有効にしないでください（フィールド名の変更がスキップされます）。importMode／minify／purge／chunkGrouping／dictionariesPreload には build.optimize が必要です（デフォルトの undefined は本番環境のみを意味します）。
• dictionary.importMode: "dynamic" は 9.5 の Start で使用できます。chunkGrouping（デフォルトは true）と dictionariesPreload（デフォルトは true）によって、辞書ごとのウォーターフォールが解消されます。コレクション／バリアントは引き続き必要に応じて読み込まれます。
• CLI：9.5.2 以降、intlayer ci <cmd> は廃止されています。INTLAYER_PROJECT_CREDENTIALS を設定し、bunx intlayer <cmd> --ci を使用してください。エージェント／CI からは bunx intlayer init と、非対話型のサブコマンド（init skills、init mcp、…）を使用してください。ターミナルがない場合、--interactive は失敗します（9.6）。
• 設定値の読み取りには、直接インポート（import { defaultLocale, locales } from "intlayer"）を使用してください。getConfiguration() は非推奨です（9.5.9）。

検証

リポジトリに既存のチェックがある場合は、そちらを優先してください。Intlayer と Start に関する重要な作業では、関連するチェックを含めてください。

• .intlayer/**/*.ts を含めて型チェックし、ルートツリーを再生成します。
• ロケールのスモークテスト：デフォルトロケール（プレフィックスなし、またはプレフィックス付き）、別のロケール、無効なプレフィックス → 404 リダイレクト、ロケールスイッチャー。
• ナビゲーションのスモークテスト：アプリ内リンクとプログラムによるナビゲーションで現在のロケールを維持します。ラッパーコンポーネントを使わずに、スイッチャーで params.locale を更新します。
• SSR のスモークテスト：最初の HTML の lang／dir、Cookie／Accept-Language によるプロキシリダイレクト、サーバー関数の getLocale と getIntlayerAsync。本番環境のプロキシを、対象の Nitro プリセットでテストします（Node と Bun の両方を使う場合は両方）。
• Head／メタデータのスモークテスト：getIntlayerAsync を使い、要求されたロケールのチャンクだけが読み込まれることを確認します。ローダーキャッシュパターンを使う場合は、loaderData のオプショナルチェーンと staleTime を確認します。
• コンテンツのスモークテスト：キーの欠落、属性の文字列レンダリング、使用している場合はコレクション／バリアント／plural／enu／select。
• importMode: "dynamic" の場合の動的インポートのスモークテスト：ルート境界ごとにコンテンツリクエストが 1 回だけ発生すること、ウォームナビゲーションで Suspense によるちらつきが発生しないこと。
• CLI：辞書を変更した場合は bunx intlayer build と bunx intlayer test（content test のエイリアス）を実行します。モノレポ CMS では bunx intlayer fill --ci を使います（intlayer ci fill は使いません）。
• ローカライズされた SEO ルートを変更する場合は、サイトマップ／プリレンダーのスモークテストを実施します。
• CMS／エディター／分析機能が対象の場合：ライブ同期、push／pull、useExperiment／useConversion、分析のアトリビューションに使う editor.clientId を確認します。

実行したチェックと実行しなかったチェック、および残っているバージョン依存の前提条件を報告してください。