@intlayer/docs 9.4.0-canary.0 → 9.4.1

package/docs/zh/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 用法以直接访问属性"
@@ -41,6 +44,10 @@ author: aymericzip
 
 ## 为什么选择 Inlayer 而不是替代品？
 
+与 `react-i18next` 或 `i18next` 等主要解决方案相比，Intlayer 是一个附带集成优化的解决方案，例如：
+
+<AccordionGroup>
+
 与“react-i18next”或“i18next”等主要解决方案相比，Intlayer是一个具有集成优化的解决方案，例如：
 
 **完整的 TanStack Start 覆盖**
@@ -51,26 +58,39 @@ Intlayer 经过优化，可与 TanStack Start 和 Solid 完美配合，提供**
 
 不要将大量 JSON 文件加载到页面中，而只需加载必要的内容。 Intlayer 有助于**将捆绑包和页面大小减少多达 50%**。
 
+</Accordion>
+
 **可维护性**
 
 确定应用程序内容的范围**有利于大型应用程序的维护**。您可以复制或删除单个功能文件夹，而无需承担检查整个内容代码库的精神负担。此外，Intlayer 具有**完全类型化 (fully typed)**，以确保您的内容的准确性。
 
 **人工智能代理**
 
+<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/zh/agent_skills.md)**，使 AI 代理的开发者体验 (DX) 更加流畅。
 
 **自动化**
 
+<Accordion header="自动化">
+
 使用您选择的法学硕士，通过自动化在 CI/CD 管道中进行翻译，而费用由您的 AI 提供商承担。 Intlayer 还提供了一个**编译器**来自动提取内容，以及一个[网络平台](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md)来帮助**在后台翻译**。
 
+</Accordion>
+
 **表现**
 
 将大量 JSON 文件连接到组件可能会导致性能和反应性问题。 Intlayer 可在构建时 (build time)优化您的内容加载。
 
 **无需开发即可扩展**
 
+<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 的分步指南
@@ -445,6 +465,8 @@ export const useLocalizedNavigate = () => {
 
 <Step number={8} title="在您的页面中使用 Intlayer">
 
+> 在组件中请默认使用 **`useIntlayer`**：这是读取内容的推荐方式，编译器会把它解析为当前渲染的语言环境。仅在 Solid 树之外（路由 `head`、loader 和服务端函数）才使用 `getIntlayer` / `getIntlayerAsync`。
+
 在整个应用程序中访问您的内容字典：
 
 #### 本地化主页
@@ -561,7 +583,7 @@ 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/zh/releases/v9.md)。
+> 从 Intlayer v9 开始，`intlayerProxy()` 直接捆绑到 `intlayer()` 插件中，并通过 `routing.enableProxy` 选项（默认为 `true`）默认启用。如下所示单独注册现在是可选的，为了向后兼容性以及需要控制插件顺序的设置而保留。设置 `routing.enableProxy: false` 以选择退出。参考 [v9 发布说明](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/releases/v9.md)。
 
 ```typescript fileName="vite.config.ts"
 import { tanstackStart } from "@tanstack/solid-start/plugin/vite";
@@ -595,34 +617,97 @@ export default defineConfig({
 
 <Step number={12} title="国际化您的元数据">
 
-您也可以使用 `getIntlayer` 函数在 `head` 加载器内访问您的内容字典以获取语言环境感知的元数据：
+<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 path = "/"; // 此路由的路径
+    const { locale = defaultLocale } = params;
+    const path = "/"; // The path for this route
 
     const metaContent = getIntlayer("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 },
+      ],
+    };
+  },
+});
+```
+
+适合较小的元数据字典、语言环境数量不多的项目，或原型开发阶段。
+
+</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：告知 Google 所有本地化版本
+        // Hreflang: Tell Google about all localized versions
         ...localeMap(({ locale: mapLocale }) => ({
           rel: "alternate",
           hrefLang: mapLocale,
           href: getLocalizedUrl(path, mapLocale),
         })),
 
-        // x-default：针对不匹配语言的用户
-        // 定义默认回退语言环境（通常是您的主要语言）
+        // x-default: For users in unmatched languages
+        // Define the default fallback locale (usually your primary language)
         {
           rel: "alternate",
           hrefLang: "x-default",
@@ -638,6 +723,89 @@ export const Route = createFileRoute("/{-$locale}/")({
 });
 ```
 
+> 如果一个 `head` 要读取多个字典，请用 `Promise.all` 一并解析；逐行 await 每个 `getIntlayerAsync` 会把请求串成链式调用，而不是并行执行。
+
+代价是：动态 import 会在 `head` 执行期间解析，处于文档渲染的关键路径上。在冷路由上这会让 `head` 延迟几毫秒，并可能略微拉低 **LCP**。
+
+</Tab>
+
+<Tab label="带缓存的动态解析" value="cached">
+
+改为在路由的 `loader` 中解析字典，再于 `head` 中通过 `loaderData` 读回。已匹配路由的 loader 会并行运行，而 `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` 可能在 loader 完成之前被调用，因此 `loaderData` 的类型可能为 `undefined`。请保留可选链，或返回一个兜底标题。
+
+你保留了按语言环境拆分的分块，却无需在 `head` 的关键路径上付出代价。代价在于开发体验：内容必须通过 `loaderData` 从 loader 显式传递到 `head`。
+
+</Tab>
+
+</Tabs>
+
+### 该选择哪种解析方式？
+
+|                | 静态解析             | 动态解析                    | 带缓存的动态解析                          |
+| -------------- | -------------------- | --------------------------- | ----------------------------------------- |
+| API            | `getIntlayer`        | `getIntlayerAsync`（v9.4+） | `loader` 中的 `getIntlayerAsync`（v9.4+） |
+| `head` 签名    | 同步                 | `async`                     | 同步，读取 `loaderData`                   |
+| 发送的语言环境 | 所有已声明的语言环境 | 仅请求的语言环境            | 仅请求的语言环境                          |
+| 客户端导航     | 无需解析             | 每次匹配都重新执行          | 由路由缓存提供                            |
+| 开发体验       | 最简单               | 一个 `await`                | 内容经由 `loaderData` 传递                |
+
 ---
 
 </Step>