@intlayer/docs 9.4.0-canary.0 → 9.4.1

package/docs/ja/intlayer_with_tanstack+solid.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-03-25
-updatedAt: 2026-06-23
+updatedAt: 2026-08-25
 title: "TanStack Start + Solid i18n - あなたのアプリを翻訳する完全ガイド"
 description: "i18nextはもう不要。2026年に多言語（i18n）TanStack Start + Solidアプリを構築するためのガイド。AIエージェントで翻訳し、バンドルサイズ、SEO、パフォーマンスを最適化します。"
 keywords:
@@ -22,6 +22,9 @@ applicationTemplate: https://github.com/aymericzip/intlayer-tanstack-start-solid
 applicationShowcase: https://intlayer-tanstack-start-solid.vercel.app
 youtubeVideo: https://www.youtube.com/watch?v=_XTdKVWaeqg
 history:
+  - version: 9.4.0
+    date: 2026-08-25
+    changes: "ルートの head 関数におけるメタデータ辞書の静的解決・動的解決・キャッシュ付き動的解決を比較"
   - version: 8.9.0
     date: 2026-05-04
     changes: "Solid の useIntlayer API の使用法を直接プロパティアクセスに更新"
@@ -43,12 +46,16 @@ author: aymericzip
 
 「react-i18next」や「i18next」などの主要なソリューションと比較して、Intlayer は次のような統合された最適化を備えたソリューションです。
 
+<AccordionGroup>
+
 **TanStack Start を完全にカバー**
 
 Intlayer は、**多言語ルーティング**、**サイトマップ**、および国際化の拡張 (i18n) に必要なすべての機能を提供することにより、TanStack Start および Solid と完全に連携するように最適化されています。
 
 **バンドルサイズ**
 
+<Accordion header="バンドルサイズ">
+
 大量の JSON ファイルをページにロードするのではなく、必要なコンテンツのみをロードします。 Intlayer は、**バンドルとページのサイズを最大 50% 削減**するのに役立ちます。
 
 **保守性**
@@ -57,20 +64,33 @@ Intlayer は、**多言語ルーティング**、**サイトマップ**、およ
 
 **AI エージェント**
 
+</Accordion>
+
+<Accordion header="AI Agent">
+
 コンテンツを同じ場所に配置すると、大規模言語モデル (LLM) によって **必要なコンテキストが削減**されます。 Intlayer には、翻訳の欠落をテストする **CLI**、**[LSP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/lsp.md)**、**[MCP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/mcp_server.md)** などのツール スイートも付属しています。および **[agent skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/agent_skills.md)** により、AI エージェントの開発者エクスペリエンス (DX) がさらにスムーズになります。
 
 **オートメーション**
 
+<Accordion header="自動化">
+
 AI プロバイダーの費用で、選択した LLM を使用して CI/CD パイプラインで自動化を変換します。 Intlayer は、コンテンツ抽出を自動化する **コンパイラー** と、**バックグラウンドでの翻訳**を支援する [Web プラットフォーム](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md) も提供します。
 
 **パフォーマンス**
 
+<Accordion header="パフォーマンス">
+
 大量の JSON ファイルをコンポーネントに接続すると、パフォーマンスと反応性の問題が発生する可能性があります。 Intlayer は、ビルド時のコンテンツの読み込みを最適化します。
 
 **非開発によるスケーリング**
 
+<Accordion header="none-dev でのスケーリング">
+
 Intlayer は単なる i18n ソリューションではなく、**自己ホスト型 [ビジュアル エディター](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_visual_editor.md)** と **[完全な CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md)** を提供します。 **リアルタイム**で多言語コンテンツを管理できるようになり、翻訳者、コピーライター、その他のチーム メンバーとのコラボレーションがシームレスになります。コンテンツはローカルおよび/またはリモートに保存できます。
 
+</Accordion>
+</AccordionGroup>
+
 ---
 
 ## Tanstack StartアプリケーションでIntlayerをセットアップするためのステップバイステップガイド
@@ -441,6 +461,8 @@ export const useLocalizedNavigate = () => {
 
 <Step number={9} title="ページでIntlayerを活用する">
 
+> コンポーネント内では既定で **`useIntlayer`** を使用してください。コンパイラがレンダリング対象のロケールへ解決してくれるため、これが推奨される方法です。`getIntlayer` / `getIntlayerAsync` は Solid ツリーの外側（ルートの `head`、ローダー、サーバー関数）でのみ使用します。
+
 アプリケーション全体でコンテンツ辞書にアクセスします：
 
 #### ローカライズされたホームページ
@@ -470,8 +492,6 @@ function RouteComponent() {
 }
 ```
 
-> コンテンツを `alt`、`title`、`href`、`aria-label` などの `string` 属性で使用したい場合は、関数の値を使用できます。例：
-
 > ```html
 > <img src="{content.image.src.value}" alt="{content.image.value}" />
 > <img src="{content.image.src.toString()}" alt="{content.image.toString()}" />
@@ -557,6 +577,8 @@ const RootComponent: ParentComponent = (props) => {
 
 > 本番環境で `intlayerProxy` を使用するには、`vite-intlayer` パッケージを `devDependencies` から `dependencies` に切り替える必要があることに注意してください。
 
+> Intlayer v9 以降、`intlayerProxy()` は `intlayer()` プラグインに直接バンドルされており、`routing.enableProxy` オプション（デフォルトは `true`）を通じてデフォルトで有効になります。以下に示すように個別に登録することはオプションになりました。これは後方互換性とプラグインの順序を制御する必要があるセットアップのために保持されています。`routing.enableProxy: false` に設定してオプトアウトできます。[v9 リリースノート](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/releases/v9.md)を参照してください。
+
 ```typescript fileName="vite.config.ts"
 import { tanstackStart } from "@tanstack/solid-start/plugin/vite";
 import solid from "vite-plugin-solid";
@@ -589,16 +611,25 @@ export default defineConfig({
 
 <Step number={12} title="メタデータの国際化">
 
-ロケール対応のメタデータのために、`head` ローダー内で `getIntlayer` 関数を使用してコンテンツ辞書にアクセスすることもできます：
+<Tabs>
+
+<Tab label="静的解決" value="static">
+
+`getIntlayer` は、宣言されたすべてのロケールを含む**統合**辞書に対して同期的に解決します。`head` は同期のままで待機も発生しませんが、多言語辞書全体がブラウザへ送られるルートチャンクに取り込まれます。
 
 ```tsx fileName="src/routes/{-$locale}/index.tsx"
 import { createFileRoute } from "@tanstack/solid-router";
-import { getIntlayer } from "intlayer";
+import {
+  defaultLocale,
+  getIntlayer,
+  getLocalizedUrl,
+  localeMap,
+} from "intlayer";
 
 export const Route = createFileRoute("/{-$locale}/")({
   component: RouteComponent,
   head: ({ params }) => {
-    const { locale } = params;
+    const { locale = defaultLocale } = params;
     const path = "/"; // The path for this route
 
     const metaContent = getIntlayer("app", locale);
@@ -632,6 +663,143 @@ export const Route = createFileRoute("/{-$locale}/")({
 });
 ```
 
+小さなメタデータ辞書、ロケール数が少ない場合、プロトタイピング時に適しています。
+
+</Tab>
+
+<Tab label="動的解決" value="dynamic">
+
+`getIntlayerAsync`（**v9.4** 以降で利用可能）は `getIntlayer` と同じ振る舞いをしますが、ビルドプラグインが統合辞書ではなく `.intlayer/dynamic_dictionaries/` 内のロケール別チャンクを参照させます。そのためページはレンダリングするロケールのみを配信します。このチャンクはオンデマンドで読み込まれるため、`head` は `async` になります。
+
+```tsx fileName="src/routes/{-$locale}/index.tsx"
+import { createFileRoute } from "@tanstack/solid-router";
+import {
+  defaultLocale,
+  getIntlayerAsync,
+  getLocalizedUrl,
+  localeMap,
+} from "intlayer";
+
+export const Route = createFileRoute("/{-$locale}/")({
+  component: RouteComponent,
+  head: async ({ params }) => {
+    const { locale = defaultLocale } = params;
+    const path = "/"; // The path for this route
+
+    const metaContent = await getIntlayerAsync("app", locale);
+
+    return {
+      links: [
+        // Canonical link: Points to the current localized page
+        { rel: "canonical", href: getLocalizedUrl(path, locale) },
+
+        // Hreflang: Tell Google about all localized versions
+        ...localeMap(({ locale: mapLocale }) => ({
+          rel: "alternate",
+          hrefLang: mapLocale,
+          href: getLocalizedUrl(path, mapLocale),
+        })),
+
+        // x-default: For users in unmatched languages
+        // Define the default fallback locale (usually your primary language)
+        {
+          rel: "alternate",
+          hrefLang: "x-default",
+          href: getLocalizedUrl(path, defaultLocale),
+        },
+      ],
+      meta: [
+        { title: metaContent.title },
+        { name: "description", content: metaContent.meta.description },
+      ],
+    };
+  },
+});
+```
+
+> 1 つの `head` で複数の辞書を読む場合は `Promise.all` でまとめて解決してください。`getIntlayerAsync` を 1 行ずつ await すると、リクエストが並列ではなく直列に連鎖してしまいます。
+
+トレードオフとして、動的インポートはドキュメントレンダリングのクリティカルパス上で `head` の実行中に解決されます。コールドなルートでは `head` が数ミリ秒遅れ、**LCP** がわずかに悪化する可能性があります。
+
+</Tab>
+
+<Tab label="キャッシュ付き動的解決" value="cached">
+
+辞書をルートの `loader` で解決し、`head` では `loaderData` から読み戻します。マッチしたルートのローダーは並行して実行され、`staleTime: Infinity` によって TanStack Router は結果が古くならないと判断します。つまりロケール別チャンクは一度だけ解決され、以降はルーターのキャッシュから提供されるため、`head` は同期のままです。
+
+```tsx fileName="src/routes/{-$locale}/index.tsx"
+import { createFileRoute } from "@tanstack/solid-router";
+import {
+  defaultLocale,
+  getIntlayerAsync,
+  getLocalizedUrl,
+  localeMap,
+} from "intlayer";
+
+export const Route = createFileRoute("/{-$locale}/")({
+  component: RouteComponent,
+  // Resolved in parallel with the other matched routes, off the head critical path
+  loader: async ({ params }) => {
+    const { locale = defaultLocale } = params;
+
+    return { metaContent: await getIntlayerAsync("app", locale) };
+  },
+  // The dictionary never changes for a given locale: resolve the chunk once
+  staleTime: Infinity,
+  head: ({ params, loaderData }) => {
+    const { locale = defaultLocale } = params;
+    const path = "/"; // The path for this route
+
+    return {
+      links: [
+        // Canonical link: Points to the current localized page
+        { rel: "canonical", href: getLocalizedUrl(path, locale) },
+
+        // Hreflang: Tell Google about all localized versions
+        ...localeMap(({ locale: mapLocale }) => ({
+          rel: "alternate",
+          hrefLang: mapLocale,
+          href: getLocalizedUrl(path, mapLocale),
+        })),
+
+        // x-default: For users in unmatched languages
+        // Define the default fallback locale (usually your primary language)
+        {
+          rel: "alternate",
+          hrefLang: "x-default",
+          href: getLocalizedUrl(path, defaultLocale),
+        },
+      ],
+      meta: [
+        { title: loaderData?.metaContent.title },
+        {
+          name: "description",
+          content: loaderData?.metaContent.meta.description,
+        },
+      ],
+    };
+  },
+});
+```
+
+> `head` はローダーの解決前に呼ばれることがあるため、`loaderData` は `undefined` の可能性がある型になります。オプショナルチェーンを残すか、フォールバックのタイトルを返してください。
+
+ロケール別チャンクの利点を保ちつつ、そのコストを `head` のクリティカルパスで支払わずに済みます。代償は DX です。コンテンツをローダーから `head` へ `loaderData` 経由で明示的に受け渡す必要があります。
+
+</Tab>
+
+</Tabs>
+
+### どの解決方法を選ぶべきか
+
+|                     | 静的解決                   | 動的解決                    | キャッシュ付き動的解決                    |
+| ------------------- | -------------------------- | --------------------------- | ----------------------------------------- |
+| API                 | `getIntlayer`              | `getIntlayerAsync`（v9.4+） | `loader` 内の `getIntlayerAsync`（v9.4+） |
+| `head` のシグネチャ | 同期                       | `async`                     | 同期、`loaderData` を読む                 |
+| 配信されるロケール  | 宣言されたすべてのロケール | 要求されたロケールのみ      | 要求されたロケールのみ                    |
+| クライアント遷移    | 解決するものなし           | マッチのたびに再実行        | ルーターのキャッシュから提供              |
+| DX                  | 最もシンプル               | `await` が 1 つ             | コンテンツを `loaderData` 経由で受け渡し  |
+
 ---
 
 </Step>
@@ -870,8 +1038,6 @@ bun run build # または bun run dev
 
 <Step number={16} title="サイトマップの生成">
 
-Intlayer には、アプリケーションのサイトマップを簡単に作成できるサイトマップ ジェネレーターが組み込まれています。ローカライズされたルートを処理し、検索エンジンに必要なメタデータを追加します。
-
 > Intlayer によって生成されたサイトマップは、`xhtml:link` 名前空間 (Hreflang XML Extensions) をサポートしています。生の URL のみを表示するデフォルトのサイトマップ ジェネレーターとは異なり、Intlayer はページのすべての言語バージョン (例: `/about`、`/about?lang=fr`、`/about?lang=es`) 間に必要な双方向リンクを自動的に作成します。これにより、検索エンジンが正しい言語バージョンを正しい対象者に正しくインデックス付けして提供できるようになります。
 
 > Intlayer によって生成されたサイトマップは、`xhtml:link` 名前空間 (Hreflang XML Extensions) をサポートしています。生の URL のみを表示するデフォルトのサイトマップ ジェネレーターとは異なり、Intlayer はページのすべての言語バージョン (例: `/about`、`/about?lang=fr`、`/about?lang=es`) 間に必要な双方向リンクを自動的に作成します。これにより、検索エンジンが正しい言語バージョンを正しい対象者に正しくインデックス付けして提供できるようになります。