@intlayer/docs 9.2.0 → 9.3.1

package/docs/zh/bundle_optimization.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-11-25
-updatedAt: 2026-06-07
+updatedAt: 2026-08-09
 title: 优化 i18n 打包体积与性能
 description: 通过优化国际化（i18n）内容来减小应用程序包的大小。了解如何利用 Intlayer 实现字典的 tree shaking 和延迟加载（lazy loading）。
 keywords:
@@ -16,6 +16,12 @@ slugs:
   - concept
   - bundle-optimization
 history:
+  - version: 9.2.1
+    date: 2026-08-09
+    changes: "`purge` 和 `minify` 现在可通过 `@intlayer/swc` 在 Next.js 上工作 — 无需 `babel.config.js`"
+  - version: 8.12.0
+    date: 2026-06-24
+    changes: "在参考表中按所需的流水线顺序列出 Babel 插件（extract → purge → minify → optimize）"
   - version: 8.12.0
     date: 2026-06-07
     changes: "为 Babel/Webpack 引入了 `intlayerPurgeBabelPlugin` 和 `intlayerMinifyBabelPlugin`，明确了插件管线"
@@ -191,12 +197,14 @@ Intlayer 的构建优化被划分为若干个职责单一的插件。了解它
 
 这些被直接运用在基于 Webpack 设置的 `babel.config.js` 当中（比如使用了 Babel 的 Next.js、CRA，或是自定义的 Webpack 等）。
 
+下表按所需的流水线顺序列出它们（与它们必须在 `babel.config.js` 中出现的顺序相同）：
+
 | 插件                          | 功能说明                                                                                             |
 | :---------------------------- | :--------------------------------------------------------------------------------------------------- |
 | `intlayerExtractBabelPlugin`  | 扫描 `.content.ts` 文件并把编译好的字典写入 `.intlayer/`                                             |
-| `intlayerOptimizeBabelPlugin` | 将 `useIntlayer('key')` 重写为 `useDictionary(hash)` 并注入匹配对应字典的 `import` 语句              |
 | `intlayerPurgeBabelPlugin`    | 扫描所有源代码文件，从已编译的 `.intlayer/**/*.json` 字典文件中删除**未被使用的内容字段**            |
 | `intlayerMinifyBabelPlugin`   | **重命名内容字段的键（keys）** 为简短的字母别名（例如 `title` 变成 `a`），作用范围包括 JSON 与源代码 |
+| `intlayerOptimizeBabelPlugin` | 将 `useIntlayer('key')` 重写为 `useDictionary(hash)` 并注入匹配对应字典的 `import` 语句              |
 
 > **插件的执行顺序很重要。** 在你的 `babel.config.js` 里，purge 和 minify 的插件必须放置在 optimize 插件**之前**。优化步骤（optimize）会把 `useIntlayer('key')` 替换为模糊的 `useDictionary(hash)`，此举抹除了能够让 purge 和 minify 识别哪些字段被使用过的字典 key 信息。
 
@@ -205,9 +213,9 @@ Intlayer 的构建优化被划分为若干个职责单一的插件。了解它
 | 选项助手                     | 配套插件                      |
 | :--------------------------- | :---------------------------- |
 | `getExtractPluginOptions()`  | `intlayerExtractBabelPlugin`  |
-| `getOptimizePluginOptions()` | `intlayerOptimizeBabelPlugin` |
 | `getPurgePluginOptions()`    | `intlayerPurgeBabelPlugin`    |
 | `getMinifyPluginOptions()`   | `intlayerMinifyBabelPlugin`   |
+| `getOptimizePluginOptions()` | `intlayerOptimizeBabelPlugin` |
 
 ### Vite 插件 (`vite-intlayer`)
 
@@ -220,6 +228,20 @@ Vite 用户**不需要直接对它们进行配置**。当你在 `vite.config.ts`
 | Dictionary minify | 等同于 `intlayerMinifyBabelPlugin` 的 JSON 写入步骤                                 |
 | Babel transform   | 等同于 `intlayerMinifyBabelPlugin` 的代码重命名步骤 + `intlayerOptimizeBabelPlugin` |
 
+### SWC 插件（`@intlayer/swc`）
+
+Next.js 用户同样**从不直接配置这些**。自 **v9.2.1** 起，`next.config.ts` 中的 `withIntlayer()` 仅凭 `build.purge` 和 `build.minify` 两个标志就会运行完整流水线 —— 清除、压缩和导入重写。
+
+工作被分成两部分，因为 SWC Wasm 插件一次只转换一个文件，且无法访问文件系统：
+
+| 阶段                               | 运行位置                       | 作用                                                         |
+| :--------------------------------- | :----------------------------- | :----------------------------------------------------------- |
+| 使用分析 + JSON 清除/压缩          | Node，位于 `withIntlayer()` 内 | 读取每个组件源文件，重写 `.intlayer/**/*.json`，生成重命名表 |
+| 源码重写（`content.title` → `.a`） | `@intlayer/swc`（Wasm）        | 将重命名表应用到你代码中对应的属性访问                       |
+| 导入重写（`useIntlayer` → dict）   | `@intlayer/swc`（Wasm）        | 与 `intlayerOptimizeBabelPlugin` 相同                        |
+
+判断_哪些_字段未被使用以及每个字段获得_什么_别名，需要跨文件状态和文件 I/O，因此这一半在 Node 中运行；SWC 插件只接收生成的表。
+
 ## 各平台配置指南
 
 <Tabs>
@@ -227,10 +249,12 @@ Vite 用户**不需要直接对它们进行配置**。当你在 `vite.config.ts`
 
 ### Next.js
 
-Next.js 需要依靠 `@intlayer/swc` 插件来进行优化步骤（导入重写），因为 Next.js 采用 SWC 作为编译器。
+Next.js 需要 `@intlayer/swc` 插件，因为 Next.js 使用 SWC 进行构建。自 **v9.2.1** 起，这一个包即可覆盖整条流水线 —— 优化（导入重写）、清除和压缩。
 
 > 该插件并未默认安装，因为 SWC 插件在 Next.js 当中目前仍处于实验阶段。未来这部分有可能会发生改变。
 
+> **Next.js 16.1.0 是最低版本。** 它是首个基于 SWC 向前兼容 Wasm 插件 ABI 构建的版本；更早的版本会拒绝该插件。`withIntlayer` 会读取你项目的 Next.js 版本，低于 16.1.0 时干脆不注册该插件 —— 这些构建仍会成功，只是在没有打包优化的情况下运行。
+
 <Tabs>
  <Tab value="npm">
 
@@ -265,33 +289,40 @@ intlayer-swc-plugin = "*"
 
 安装完毕后，Intlayer 将会自动侦测并使用该插件。
 
-至于**清除（purge）和最小化（minify）**步骤（即字段移除和字段重命名），请连同 `@intlayer/babel` 一并安装并加入 Babel 插件。由于 Next.js 依靠 SWC 处理代码转化，但仍会评估 `babel.config.js` 以决定插件配置，因此上述 Babel 插件能够在进入 SWC 前作为预处理步骤得以执行。
+**清除和压缩**阶段（字段移除与字段重命名）不需要额外的包，也不需要 `babel.config.js`。用 `withIntlayer` 包裹你的配置，并在 `intlayer.config.ts` 中开启相应标志：
 
-```bash packageManager="npm"
-npm install -D @intlayer/babel
+```typescript fileName="next.config.ts"
+import { withIntlayer } from "next-intlayer/server";
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {/* 你的配置 */};
+
+export default withIntlayer(nextConfig);
 ```
 
-```javascript fileName="babel.config.js"
-const {
-  intlayerPurgeBabelPlugin,
-  intlayerMinifyBabelPlugin,
-  getPurgePluginOptions,
-  getMinifyPluginOptions,
-} = require("@intlayer/babel");
+```typescript fileName="intlayer.config.ts"
+import type { IntlayerConfig } from "intlayer";
 
-module.exports = {
-  presets: ["next/babel"],
-  plugins: [
-    // Purge: 移除 .intlayer/**/*.json 里未被使用的内容字段
-    [intlayerPurgeBabelPlugin, getPurgePluginOptions()],
-    // Minify: 对 JSON 以及源代码里的内容字段的键（keys）进行重命名
-    [intlayerMinifyBabelPlugin, getMinifyPluginOptions()],
-    // 注意: 在这里不需要使用 intlayerOptimizeBabelPlugin，因为
-    // @intlayer/swc 已经处理了 useIntlayer → useDictionary 的重写过程。
-  ],
+const config: IntlayerConfig = {
+  build: {
+    purge: true, // 从打包的 JSON 中移除未使用的内容字段
+    minify: true, // 将内容字段键重命名为简短别名
+  },
 };
+
+export default config;
 ```
 
+在 `next build` 期间，`withIntlayer` 会分析你的源码、重写已编译的字典，并将生成的字段重命名表传给 `@intlayer/swc`，由它更新你代码中对应的属性访问。
+
+> 请使用异步的 `withIntlayer`，而不是 `withIntlayerSync`。同步版本不会运行分析流水线，因此清除和压缩对它没有效果。
+
+> 清除和压缩仅在 `next build` 时运行 —— 优化流水线在 `next dev` 期间是关闭的。
+
+> 当配置了兼容适配器调用方时它们也会被禁用（`swcExtraCallers`，由 `@intlayer/next-intl`、`@intlayer/react-i18next` 等兼容包设置）：这些调用点对使用分析器不可见，因此清除会移除代码仍在读取的字段。导入重写仍保持启用。
+
+**更早的版本（9.2.1 之前）** 需要 `@intlayer/babel` 以及一个声明 `intlayerPurgeBabelPlugin` 和 `intlayerMinifyBabelPlugin` 的 `babel.config.js`。该文件不再需要，可以删除。
+
  </Tab>
  <Tab value="vite">
 
@@ -447,6 +478,8 @@ export default config;
 
 > 如果在 `optimize` 被设为 `false`、又或是启用了可视化编辑器也就是当 `editor.enabled` 设定为了 `true` 时（由于编辑器需要保留字段名称以便做后续处理），重命名这个操作都将会被跳过。
 
+> 在 Next.js 上，当 `@intlayer/swc` 未安装或无法加载时（Next.js 低于 16.1.0），压缩同样会被跳过。重写源码访问的正是这个插件，因此在没有它的情况下重命名字典，会让你的代码读取已不存在的字段名。
+
 > 同理，如果是利用了 `importMode: 'fetch'` 来载入字段时此过程同样不适用。因为它们的内容会以原始命名由后端 API 所提供，对客户端内容随意重命名会破坏客户端与服务端的匹配契约。
 
 ### 字段清除 / Purging (去掉未被引用的字段内容)
@@ -475,7 +508,7 @@ export default config;
 { "title": "…", "subtitle": "…" }
 ```
 
-> 与前边提到的类似，当 `optimize` 是 `false` 或是开启了可视化编辑器(`editor.enabled` 取值 `true`) 时，它会选择跳过对数据的清除操作。
+> 与前边提到的类似，当 `optimize` 是 `false` 或是开启了可视化编辑器(`editor.enabled` 取值 `true`) 时，它会选择跳过对数据的清除操作。 在 Next.js 上，当 `@intlayer/swc` 不可用以及配置了兼容适配器调用方时，还会被额外跳过。
 
 > 当检测到某份代码因为异常无法顺利解析、又或者当把由 `useIntlayer` 输出的值以静态解析器难以预测分析的模式在不同组件中来回丢（比如被打包成对象传入等而未被进行解构）的时候，它同样会跳过，以此保守地保留整部字典的全部信息，避免意外发生。
 

package/docs/zh/configuration.md

@@ -403,7 +403,7 @@ const config: IntlayerConfig = {
   ai: {
     /**
      * 使用的 AI 提供商。
-     * 选项：'openai', 'anthropic', 'mistral', 'deepseek', 'gemini', 'ollama', 'openrouter', 'alibaba', 'fireworks', 'groq', 'huggingface', 'bedrock', 'googlevertex', 'togetherai', 'lmstudio'
+     * 选项：'openai', 'anthropic', 'mistral', 'deepseek', 'gemini', 'ollama', 'openrouter', 'alibaba', 'fireworks', 'groq', 'huggingface', 'bedrock', 'googlevertex', 'togetherai', 'lmstudio', 'moonshotai'
      * 默认值：'openai'
      */
     provider: "openai",
@@ -1034,15 +1034,15 @@ Intlayer 支持多个 AI 提供商，以提供最大的灵活性。当前支持
 - **Together.ai**
 - **LM Studio**
 
-| 字段                 | 说明                                                                                 | 类型                                                                                                                                                                                                                                                                                                                                                                                                                     | 默认值      | 示例                                                          | 备注                                                                                                                                              |
-| -------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `provider`           | 要为 Intlayer AI 功能使用的提供商。                                                  | `'openai'` &#124; <br/> `'anthropic'` &#124; <br/> `'mistral'` &#124; <br/> `'deepseek'` &#124; <br/> `'gemini'` &#124; <br/> `'ollama'` &#124; <br/> `'openrouter'` &#124; <br/> `'alibaba'` &#124; <br/> `'fireworks'` &#124; <br/> `'groq'` &#124; <br/> `'huggingface'` &#124; <br/> `'bedrock'` &#124; <br/> `'googleaistudio'` &#124; <br/> `'googlevertex'` &#124; <br/> `'togetherai'` &#124; <br/> `'lmstudio'` | `undefined` | `'anthropic'`                                                 | 不同的提供商需要不同的 API 密钥，且价格不同。                                                                                                     |
-| `model`              | 要为 AI 功能使用的 AI 模型。                                                         | `string`                                                                                                                                                                                                                                                                                                                                                                                                                 | 无          | `'gpt-4o-2024-11-20'`                                         | 具体模型取决于提供商。                                                                                                                            |
-| `temperature`        | 控制 AI 响应的随机性。                                                               | `number`                                                                                                                                                                                                                                                                                                                                                                                                                 | 无          | `0.1`                                                         | 温度越高 = 越具创造力且越不可靠。                                                                                                                 |
-| `apiKey`             | 所选提供商的您的 API 密钥。                                                          | `string`                                                                                                                                                                                                                                                                                                                                                                                                                 | 无          | `process.env.OPENAI_API_KEY`                                  | 应保持私密；使用环境变量。                                                                                                                        |
-| `applicationContext` | 有关应用程序的其他上下文，以帮助 AI 生成更准确的翻译（领域、目标受众、语气、术语）。 | `string`                                                                                                                                                                                                                                                                                                                                                                                                                 | 无          | `'我的自定义应用程序上下文'`                                  | 可用于添加规则（例如：`"您不应转换您的 URL"` ）。                                                                                                 |
-| `baseURL`            | AI API 的基础 URL。                                                                  | `string`                                                                                                                                                                                                                                                                                                                                                                                                                 | 无          | `'https://api.openai.com/v1'` <br/> `'http://localhost:5000'` | 可以指向本地或自定义的 AI API 端点。                                                                                                              |
-| `dataSerialization`  | AI 功能的数据序列化格式。                                                            | `'json'` &#124; <br/> `'toon'`                                                                                                                                                                                                                                                                                                                                                                                           | `undefined` | `'toon'`                                                      | • `'json'`: 默认，可靠；使用更多 token。<br/>• `'toon'`: token 更少，但也更不稳定。<br/>• 将上下文作为额外参数（reasoning effort 等）传递给模型。 |
+| 字段                 | 说明                                                                                 | 类型                                                                                                                                                                                                                                                                                                                                                                                                                                                 | 默认值      | 示例                                                          | 备注                                                                                                                                              |
+| -------------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `provider`           | 要为 Intlayer AI 功能使用的提供商。                                                  | `'openai'` &#124; <br/> `'anthropic'` &#124; <br/> `'mistral'` &#124; <br/> `'deepseek'` &#124; <br/> `'gemini'` &#124; <br/> `'ollama'` &#124; <br/> `'openrouter'` &#124; <br/> `'alibaba'` &#124; <br/> `'fireworks'` &#124; <br/> `'groq'` &#124; <br/> `'huggingface'` &#124; <br/> `'bedrock'` &#124; <br/> `'googleaistudio'` &#124; <br/> `'googlevertex'` &#124; <br/> `'togetherai'` &#124; <br/> `'lmstudio'` &#124; <br/> `'moonshotai'` | `undefined` | `'anthropic'`                                                 | 不同的提供商需要不同的 API 密钥，且价格不同。                                                                                                     |
+| `model`              | 要为 AI 功能使用的 AI 模型。                                                         | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                             | 无          | `'gpt-4o-2024-11-20'`                                         | 具体模型取决于提供商。                                                                                                                            |
+| `temperature`        | 控制 AI 响应的随机性。                                                               | `number`                                                                                                                                                                                                                                                                                                                                                                                                                                             | 无          | `0.1`                                                         | 温度越高 = 越具创造力且越不可靠。                                                                                                                 |
+| `apiKey`             | 所选提供商的您的 API 密钥。                                                          | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                             | 无          | `process.env.OPENAI_API_KEY`                                  | 应保持私密；使用环境变量。                                                                                                                        |
+| `applicationContext` | 有关应用程序的其他上下文，以帮助 AI 生成更准确的翻译（领域、目标受众、语气、术语）。 | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                             | 无          | `'我的自定义应用程序上下文'`                                  | 可用于添加规则（例如：`"您不应转换您的 URL"` ）。                                                                                                 |
+| `baseURL`            | AI API 的基础 URL。                                                                  | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                             | 无          | `'https://api.openai.com/v1'` <br/> `'http://localhost:5000'` | 可以指向本地或自定义的 AI API 端点。                                                                                                              |
+| `dataSerialization`  | AI 功能的数据序列化格式。                                                            | `'json'` &#124; <br/> `'toon'`                                                                                                                                                                                                                                                                                                                                                                                                                       | `undefined` | `'toon'`                                                      | • `'json'`: 默认，可靠；使用更多 token。<br/>• `'toon'`: token 更少，但也更不稳定。<br/>• 将上下文作为额外参数（reasoning effort 等）传递给模型。 |
 
 ---
 

package/docs/zh/interest_of_intlayer.md

@@ -188,7 +188,7 @@ export const ComponentExample = () => {
 这种方法允许你：
 
 1. **提高开发速度**
-   - 可以使用 VSCode 插件创建 `.content.{{ts|mjs|cjs|json}}` 文件
+   - 可以使用 VSCode 插件创建 `.content.{ts|js|mjs|cjs|json|tsx|jsx|md|mdx|yaml|yml}` 文件
    - IDE 中的 AI 自动补全工具（例如 GitHub Copilot）可以帮助你声明内容，减少复制/粘贴
 
 2. **保持代码库的整洁**
@@ -212,27 +212,27 @@ export const ComponentExample = () => {
 
 ## Intlayer 附加功能
 
-| 功能                                                                                                                      | 描述                                                                                                                                                                                                                                                                                                                                                      |
-| ------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/frameworks.png?raw=true)                          | **跨框架支持**<br><br>Intlayer 兼容所有主流框架和库，包括 Next.js、React、Vite、Vue.js、Nuxt、Preact、Express 等。                                                                                                                                                                                                                                        |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/javascript_content_management.jpg?raw=true)       | **JavaScript 驱动的内容管理**<br><br>利用 JavaScript 的灵活性来高效地定义和管理你的内容。<br><br> - [内容声明](https://intlayer.org/doc/concept/content)                                                                                                                                                                                                  |
-| <img src="https://github.com/aymericzip/intlayer/blob/main/docs/assets/compiler.jpg?raw=true" alt="Feature" width="700">  | **编译器**<br><br>Intlayer 编译器可自动从组件中提取内容并生成字典文件。<br><br> - [编译器](https://intlayer.org/doc/compiler)                                                                                                                                                                                                                             |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/per_locale_content_declaration_file.png?raw=true) | **单语言内容声明文件**<br><br>在自动生成前，通过仅声明一次你的内容来加速开发。<br><br> - [单语言内容声明文件](https://intlayer.org/doc/concept/per-locale-file)                                                                                                                                                                                           |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/autocompletion.png?raw=true)                      | **类型安全环境**<br><br>利用 TypeScript 确保你的内容定义和代码没有错误，同时还能享受 IDE 的自动补全功能。<br><br> - [TypeScript 配置](https://intlayer.org/doc/environment/vite-and-react#configure-typescript)                                                                                                                                           |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/config_file.png?raw=true)                         | **简易配置**<br><br>仅需极简的配置即可快速启动并运行。轻松调整国际化、路由、AI、构建以及内容处理的设置。<br><br> - [探索 Next.js 集成](https://intlayer.org/doc/environment/nextjs)                                                                                                                                                                       |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/content_retrieval.png?raw=true)                   | **简化内容检索**<br><br>无需为每一小段内容调用 `t` 函数。使用单一的 hook 即可直接检索你的所有内容。<br><br> - [React 集成](https://intlayer.org/doc/environment/create-react-app)                                                                                                                                                                         |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/server_component.png?raw=true)                    | **一致的服务器组件实现**<br><br>完美适合 Next.js 服务器组件，客户端和服务器组件使用相同的实现，无需跨每个服务器组件传递你的 `t` 函数。<br><br> - [服务器组件](https://intlayer.org/doc/environment/nextjs#step-7-utilize-content-in-your-code)                                                                                                            |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/file_tree.png?raw=true)                           | **有条理的代码库**<br><br>保持代码库更有条理：1 组件 = 在同一文件夹下的 1 个字典。靠近其各自组件的翻译有助于提高可维护性和清晰度。<br><br> - [Intlayer 运行机制](https://intlayer.org/doc/concept/how-works-intlayer)                                                                                                                                     |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/url_routing.png?raw=true)                         | **增强的路由功能**<br><br>完全支持应用路由，无缝适应复杂的应用结构，适用于 Next.js、React、Vite、Vue.js 等。<br><br> - [探索 Next.js 集成](https://intlayer.org/doc/environment/nextjs)                                                                                                                                                                   |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/markdown.png?raw=true)                            | **Markdown 支持**<br><br>导入并解译本地文件以及远程 Markdown，以获得隐私政策、文档等多语言内容。解译并在你的代码中使 Markdown 元数据可被访问。<br><br> - [内容文件](https://intlayer.org/doc/concept/content/file)                                                                                                                                        |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/visual_editor.png?raw=true)                       | **免费的可视化编辑器与 CMS**<br><br>可视化编辑器和 CMS 免费向内容创作者开放，消除了对第三方本地化平台的依赖。使用 Git 保持内容同步，或使用 CMS 彻底或部分外置管理它。<br><br> - [Intlayer 编辑器](https://intlayer.org/doc/concept/editor) <br> - [Intlayer CMS](https://intlayer.org/doc/concept/cms)                                                    |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/bundle.png?raw=true)                              | **构建时摇树优化 (Tree-shakable) 内容**<br><br>构建时摇树优化内容，减小最终包的体积。按组件加载内容，并从打包体积中排除任何未使用的内容。支持懒加载以提高应用加载效率。<br><br> - [应用构建优化](https://intlayer.org/doc/concept/how-works-intlayer#app-build-optimization)                                                                              |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/static_rendering.png?raw=true)                    | **静态渲染**<br><br>不阻碍静态渲染（Static Rendering）。<br><br> - [Next.js 集成](https://intlayer.org/doc/environment/nextjs)                                                                                                                                                                                                                            |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/AI_translation.png?raw=true)                      | **AI 驱动翻译**<br><br>使用您自己的 AI 提供商/API 密钥，点击一下即可将您的网站翻译成 231 种语言，得益于 Intlayer 先进的 AI 翻译工具。<br><br> - [CI/CD 集成](https://intlayer.org/doc/concept/ci-cd) <br> - [Intlayer CLI](https://intlayer.org/doc/concept/cli) <br> - [自动填充](https://intlayer.org/doc/concept/auto-fill)                            |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/mcp.png?raw=true)                                 | **MCP 服务器集成**<br><br>提供用于 IDE 自动化的 MCP（Model Context Protocol）服务器，能够直接在你的开发环境中实现无缝的内容管理和 i18n 工作流。<br><br> - [MCP 服务器](https://github.com/aymericzip/intlayer/blob/main/docs/zh/mcp_server.md)                                                                                                            |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/vscode_extension.png?raw=true)                    | **VSCode 插件**<br><br>Intlayer 提供 VSCode 插件协助管理你的内容和翻译，构建你的字典，翻译你的内容等。<br><br> - [VSCode 插件](https://intlayer.org/doc/vs-code-extension)                                                                                                                                                                                |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/interoperability.png?raw=true)                    | **互操作性**<br><br>允许与 react-i18next、next-i18next、next-intl 和 react-intl 互操作。<br><br> - [Intlayer 与 react-intl](https://intlayer.org/blog/intlayer-with-react-intl) <br> - [Intlayer 与 next-intl](https://intlayer.org/blog/intlayer-with-next-intl) <br> - [Intlayer 与 next-i18next](https://intlayer.org/blog/intlayer-with-next-i18next) |
-| 测试缺失翻译 (CLI/CI)                                                                                                     | ✅ CLI: npx intlayer content test (对 CI 友好的审计)                                                                                                                                                                                                                                                                                                      |
+| 功能                                                                                                                      | 描述                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/frameworks.png?raw=true)                          | **跨框架支持**<br><br>Intlayer 兼容所有主流框架和库，包括 Next.js、React、Vite、Vue.js、Nuxt、Preact、Express 等。                                                                                                                                                                                                                                                                                                             |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/javascript_content_management.jpg?raw=true)       | **JavaScript 驱动的内容管理**<br><br>利用 JavaScript 的灵活性来高效地定义和管理你的内容。<br><br> - [内容声明](https://intlayer.org/doc/concept/content)                                                                                                                                                                                                                                                                       |
+| <img src="https://github.com/aymericzip/intlayer/blob/main/docs/assets/compiler.jpg?raw=true" alt="Feature" width="700">  | **编译器**<br><br>Intlayer 编译器可自动从组件中提取内容并生成字典文件。<br><br> - [编译器](https://intlayer.org/doc/compiler)                                                                                                                                                                                                                                                                                                  |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/per_locale_content_declaration_file.png?raw=true) | **单语言内容声明文件**<br><br>在自动生成前，通过仅声明一次你的内容来加速开发。<br><br> - [单语言内容声明文件](https://intlayer.org/doc/concept/per-locale-file)                                                                                                                                                                                                                                                                |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/autocompletion.png?raw=true)                      | **类型安全环境**<br><br>利用 TypeScript 确保你的内容定义和代码没有错误，同时还能享受 IDE 的自动补全功能。<br><br> - [TypeScript 配置](https://intlayer.org/doc/environment/vite-and-react#configure-typescript)                                                                                                                                                                                                                |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/config_file.png?raw=true)                         | **简易配置**<br><br>仅需极简的配置即可快速启动并运行。轻松调整国际化、路由、AI、构建以及内容处理的设置。<br><br> - [探索 Next.js 集成](https://intlayer.org/doc/environment/nextjs)                                                                                                                                                                                                                                            |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/content_retrieval.png?raw=true)                   | **简化内容检索**<br><br>无需为每一小段内容调用 `t` 函数。使用单一的 hook 即可直接检索你的所有内容。<br><br> - [React 集成](https://intlayer.org/doc/environment/create-react-app)                                                                                                                                                                                                                                              |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/server_component.png?raw=true)                    | **一致的服务器组件实现**<br><br>完美适合 Next.js 服务器组件，客户端和服务器组件使用相同的实现，无需跨每个服务器组件传递你的 `t` 函数。<br><br> - [服务器组件](https://intlayer.org/doc/environment/nextjs#step-7-utilize-content-in-your-code)                                                                                                                                                                                 |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/file_tree.png?raw=true)                           | **有条理的代码库**<br><br>保持代码库更有条理：1 组件 = 在同一文件夹下的 1 个字典。靠近其各自组件的翻译有助于提高可维护性和清晰度。<br><br> - [Intlayer 运行机制](https://intlayer.org/doc/concept/how-works-intlayer)                                                                                                                                                                                                          |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/url_routing.png?raw=true)                         | **增强的路由功能**<br><br>完全支持应用路由，无缝适应复杂的应用结构，适用于 Next.js、React、Vite、Vue.js 等。<br><br> - [探索 Next.js 集成](https://intlayer.org/doc/environment/nextjs)                                                                                                                                                                                                                                        |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/markdown.png?raw=true)                            | **Markdown 支持**<br><br>导入并解译本地文件以及远程 Markdown，以获得隐私政策、文档等多语言内容。解译并在你的代码中使 Markdown 元数据可被访问。<br><br> - [内容文件](https://intlayer.org/doc/concept/content/file)                                                                                                                                                                                                             |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/visual_editor.png?raw=true)                       | **免费的可视化编辑器与 CMS**<br><br>可视化编辑器和 CMS 免费向内容创作者开放，消除了对第三方本地化平台的依赖。使用 Git 保持内容同步，或使用 CMS 彻底或部分外置管理它。<br><br> - [Intlayer 编辑器](https://intlayer.org/doc/concept/editor) <br> - [Intlayer CMS](https://intlayer.org/doc/concept/cms)                                                                                                                         |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/bundle.png?raw=true)                              | **构建时摇树优化 (Tree-shakable) 内容**<br><br>构建时摇树优化内容，减小最终包的体积。按组件加载内容，并从打包体积中排除任何未使用的内容。支持懒加载以提高应用加载效率。<br><br> - [应用构建优化](https://intlayer.org/doc/concept/how-works-intlayer#app-build-optimization)                                                                                                                                                   |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/static_rendering.png?raw=true)                    | **静态渲染**<br><br>不阻碍静态渲染（Static Rendering）。<br><br> - [Next.js 集成](https://intlayer.org/doc/environment/nextjs)                                                                                                                                                                                                                                                                                                 |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/AI_translation.png?raw=true)                      | **AI 驱动翻译**<br><br>使用您自己的 AI 提供商/API 密钥，点击一下即可将您的网站翻译成 231 种语言，得益于 Intlayer 先进的 AI 翻译工具。<br><br> - [CI/CD 集成](https://intlayer.org/doc/concept/ci-cd) <br> - [Intlayer CLI](https://intlayer.org/doc/concept/cli) <br> - [自动填充](https://intlayer.org/doc/concept/auto-fill)                                                                                                 |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/mcp.png?raw=true)                                 | **MCP 服务器集成**<br><br>提供用于 IDE 自动化的 MCP（Model Context Protocol）服务器，能够直接在你的开发环境中实现无缝的内容管理和 i18n 工作流。<br><br> - [MCP 服务器](https://github.com/aymericzip/intlayer/blob/main/docs/zh/mcp_server.md)                                                                                                                                                                                 |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/vscode_extension.png?raw=true)                    | **VSCode 插件**<br><br>Intlayer 提供 VSCode 插件协助管理你的内容和翻译，构建你的字典，翻译你的内容等。<br><br> - [VSCode 插件](https://intlayer.org/doc/vs-code-extension)                                                                                                                                                                                                                                                     |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/interoperability.png?raw=true)                    | **互操作性**<br><br>允许与 react-i18next、next-i18next、next-intl 和 react-intl 互操作。<br><br> - [Intlayer 与 react-intl](https://intlayer.org/blog/intlayer-with-react-intl) <br> - [Intlayer 与 next-intl](https://intlayer.org/blog/intlayer-with-next-intl) <br> - [Intlayer 与 next-i18next](https://intlayer.org/blog/intlayer-with-next-i18next) <br> - [Intlayer 兼容适配器](https://intlayer.org/doc/compatibility) |
+| 测试缺失翻译 (CLI/CI)                                                                                                     | ✅ CLI: npx intlayer content test (对 CI 友好的审计)                                                                                                                                                                                                                                                                                                                                                                           |
 
 ## Intlayer 与其他解决方案的比较
 
@@ -271,3 +271,5 @@ GitHub Star 数是衡量项目受欢迎程度、社区信任度以及长期相
 `intlayer` 还可以帮助管理你的 `react-intl`、`react-i18next`、`next-intl`、`next-i18next` 以及 `vue-i18n` 命名空间。
 
 使用 `intlayer`，你可以声明你喜欢的 i18n 库格式的内容，并且 intlayer 将在你想指定的路径下生成命名空间（例如：`/messages/{{locale}}/{{namespace}}.json`）。
+
+如果你想继续使用当前 i18n 库的 API，`intlayer` 还提供了 **兼容适配器（compat adapters）**：这些包暴露与 `react-i18next`、`next-intl`、`react-intl`、`vue-i18n` 等完全相同的 API，但内容由 Intlayer 词典提供。这样你就可以逐步迁移，而无需重写代码。参见[兼容适配器文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compat/index.md)。

package/docs/zh/intlayer_with_svelte_kit.md

@@ -392,7 +392,7 @@ export const getLocale = (event: RequestEvent): Locale => {
 };
 ```
 
-> `getLocaleFromStorage` 将根据你的配置从 header 或 cookie 检查语言环境。有关更多详情，请参阅[配置](https://intlayer.org/doc/configuration)。
+> `getLocaleFromStorage` 将根据你的配置从 header 或 cookie 检查语言环境。有关更多详情，请参阅[配置](https://intlayer.org/doc/concept/configuration)。
 
 > `localeDetector` 函数将处理 `Accept-Language` header 并返回最佳匹配。
 

package/docs/zh/intlayer_with_tanstack+solid.md

@@ -237,19 +237,21 @@ import {
   HeadContent,
   Scripts,
   createRootRouteWithContext,
+  getRouteApi,
 } from "@tanstack/solid-router";
 import { HydrationScript } from "solid-js/web";
 import { Suspense, type ParentComponent } from "solid-js";
 import { IntlayerProvider } from "solid-intlayer";
 import { defaultLocale, getHTMLTextDir } from "intlayer";
-import { Route as LocaleRoute } from "./{-$locale}/route";
+
+const localeRoute = getRouteApi("/{-$locale}");
 
 export const Route = createRootRouteWithContext()({
   shellComponent: RootComponent,
 });
 
 const RootComponent: ParentComponent = (props) => {
-  const params = LocaleRoute.useParams();
+  const params = localeRoute.useParams();
   const locale = params()?.locale ?? defaultLocale;
 
   return (
@@ -538,7 +540,7 @@ export default LocaleSwitcher;
 
 ```tsx fileName="src/routes/__root.tsx"
 const RootComponent: ParentComponent = (props) => {
-  const params = LocaleRoute.useParams();
+  const params = localeRoute.useParams();
   const locale = params()?.locale ?? defaultLocale;
 
   return (

package/docs/zh/intlayer_with_tanstack.md

@@ -254,13 +254,15 @@ export default config;
 ```tsx fileName="src/routes/__root.tsx"
 import {
   createRootRouteWithContext,
+  getRouteApi,
   HeadContent,
   Scripts,
 } from "@tanstack/react-router";
 import { defaultLocale, getHTMLTextDir } from "intlayer";
 import { type ReactNode } from "react";
 import { IntlayerProvider } from "react-intlayer";
-import { Route as LocaleRoute } from "./{-$locale}/route";
+
+const localeRoute = getRouteApi("/{-$locale}");
 
 export const Route = createRootRouteWithContext<{}>()({
   head: () => ({
@@ -282,7 +284,7 @@ export const Route = createRootRouteWithContext<{}>()({
 });
 
 function RootDocument({ children }: { children: ReactNode }) {
-  const params = LocaleRoute.useParams();
+  const params = localeRoute.useParams();
   const locale = params?.locale ?? defaultLocale;
 
   return (
@@ -619,7 +621,7 @@ export const LocaleSwitcher: FC = () => {
 
 ```tsx fileName="src/routes/__root.tsx"
 function RootDocument({ children }: { children: ReactNode }) {
-  const params = LocaleRoute.useParams();
+  const params = localeRoute.useParams();
   const locale = params?.locale ?? defaultLocale;
 
   return (

package/docs/zh/live-sync.md

@@ -13,6 +13,10 @@ keywords:
   - Intlayer
   - Next.js
   - Vite
+slugs:
+  - doc
+  - concept
+  - live-sync
 history:
   - version: 9.0.0
     date: 2026-07-08