@intlayer/docs 9.4.4 → 9.5.1

package/docs/zh/bundle_optimization.md

@@ -133,8 +133,6 @@ export default config;
 
 > 清除和压缩仅在 `next build` 时运行 —— 优化流水线在 `next dev` 期间是关闭的。
 
-> 当配置了兼容适配器调用方时它们也会被禁用（`swcExtraCallers`，由 `@intlayer/next-intl`、`@intlayer/react-i18next` 等兼容包设置）：这些调用点对使用分析器不可见，因此清除会移除代码仍在读取的字段。导入重写仍保持启用。
-
 **更早的版本（9.2.1 之前）** 需要 `@intlayer/babel` 以及一个声明 `intlayerPurgeBabelPlugin` 和 `intlayerMinifyBabelPlugin` 的 `babel.config.js`。该文件不再需要，可以删除。
 
  </Tab>

package/docs/zh/cli/index.md

@@ -70,14 +70,10 @@ author: aymericzip
 
 # Intlayer CLI - 适用于多语言网站的所有 Intlayer CLI 命令
 
----
-
 ## 目录
 
 <TOC/>
 
----
-
 ## 安装包
 
 使用 npm 安装必要的包：

package/docs/zh/cli/login.md

@@ -20,8 +20,6 @@ author: aymericzip
 
 # Intlayer CLI 登录命令
 
----
-
 ## 描述
 
 Intlayer CLI 的 `login` 命令允许您对 Intlayer CMS 进行身份验证。该命令会自动打开您的默认浏览器以完成身份验证流程，并接收使用 Intlayer 服务所需的凭证（Client ID 和 Client Secret）。

package/docs/zh/compiler.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-09-09
-updatedAt: 2026-06-23
+updatedAt: 2026-09-08
 title: Intlayer 编译器 | 用于 i18n 的自动内容提取
 description: 使用 Intlayer 编译器自动化您的国际化流程。直接从组件中提取内容，实现 Vite、Next.js 等框架中更快速、更高效的 i18n。
 keywords:
@@ -68,7 +68,7 @@ author: aymericzip
 
 ## 使用方法
 
-> The quickest way to wire the compiler in is the interactive setup: run `npx intlayer init --interactive` and select **Compiler**. On Vite there is nothing to configure — the compiler is plugged in directly through the `intlayerCompiler()` plugin. On Next.js the command scaffolds the `babel.config.js` shown below. The non-interactive `intlayer init` leaves the compiler setup untouched.
+> 接入编译器最快捷的方式是交互式设置：运行 `npx intlayer init --interactive` 并选择 **Compiler**。在 Next.js 和 Vite 中，一旦设置了 `compiler.enabled` 并配置了 `compiler.output` 路径，它就会自动激活。
 
 <Tabs>
  <Tab value='vite'>
@@ -92,19 +92,13 @@ import { defineConfig } from "vite";
 import { intlayer } from "vite-intlayer";
 
 export default defineConfig({
-  plugins: [
-    intlayer({
-      proxy: {
-        ignore: (req) => req.url?.startsWith("/api"),
-      },
-    }),
-  ],
+  plugins: [intlayer()],
 });
 ```
 
 > 独立的 `intlayerCompiler()` 插件仍然为高级设置导出。与 `intlayer()` 一起注册是安全的——编译器会自行去重并且只运行一次。
 
-See complete tutorial: [Intlayer Compiler with Vite+React](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_vite+react_compiler.md)
+See complete tutorial: [Translate Vite and React with Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_vite+react.md)
 
 #### 框架支持
 
@@ -131,7 +125,33 @@ npm install @intlayer/svelte-compiler
  </Tab>
  <Tab value='nextjs'>
 
-### Next.js（Babel）
+### Next.js
+
+在 Next.js 中，编译器作为打包器加载器 `next-intlayer/extractor-loader` 运行。`withIntlayer` 会在 Turbopack 和 webpack **两者**中自动为您注册，无需编写 `babel.config.js`。
+
+#### 安装
+
+```bash
+npm install @intlayer/babel
+```
+
+#### 配置
+
+无需任何配置。只要您的 `next.config.ts` 经过 `withIntlayer`，安装 `@intlayer/babel` 就足以注册该加载器：
+
+```ts fileName="next.config.ts"
+import { withIntlayer } from "next-intlayer/server";
+
+export default withIntlayer({});
+```
+
+加载器在 `next-swc-loader` 之前运行于 `.tsx` 和 `.jsx` 文件上，因此它读取的是您原始的 JSX。组件中声明的内容会被提取到 `.content` 文件中，并在文件编译时构建到 `.intlayer` 中。
+
+</Tab>
+
+ <Tab value="Babel">
+
+### Babel
 
 对于使用 Babel 的 Next.js 或其他基于 Webpack 的应用，可以通过 `@intlayer/babel` 插件配置编译器。
 
@@ -166,8 +186,6 @@ module.exports = {
 
 此配置确保在构建过程中，组件中声明的内容会被自动提取并用于生成字典。
 
-See complete tutorial: [Intlayer Compiler with Next.js](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_nextjs_compiler.md)
-
  </Tab>
 </Tabs>
 

package/docs/zh/configuration.md

@@ -122,14 +122,10 @@ author: aymericzip
 
 Intlayer 配置文件允许您自定义插件的各个方面，例如国际化 (i18n)、中间件和内容管理。本文档提供了配置中每个属性的详细说明。
 
----
-
 ## 目录
 
 <TOC/>
 
----
-
 ## 配置文件支持
 
 Intlayer 接受 JSON、JS、MJS 和 TS 配置文件格式：
@@ -143,8 +139,6 @@ Intlayer 接受 JSON、JS、MJS 和 TS 配置文件格式：
 - `intlayer.config.mjs`
 - `.intlayerrc`
 
----
-
 ## 配置文件示例
 
 ````typescript fileName="intlayer.config.ts" codeFormat="typescript"
@@ -692,14 +686,10 @@ const config: IntlayerConfig = {
 export default config;
 ````
 
----
-
 ## 配置参考指南
 
 以下是 Intlayer 中可用的各种配置参数的详细说明。
 
----
-
 ### 国际化配置 (Internationalization)
 
 定义国际化相关的设置，包括可用区域设置和默认区域设置。
@@ -711,8 +701,6 @@ export default config;
 | `strictMode`      | 使用 TypeScript 确保国际化内容的强实现。             | `string`   | `'inclusive'`       |                      | • 如果为 `"strict"`: 为 `t` 函数定义每个已声明的区域设置是强制性的--如缺少或未声明则报错。<br/>• 如果为 `"inclusive"`: 对缺少的区域设置发出警告，但允许使用未声明的现有区域设置。<br/>• 如果为 `"loose"`: 接受任何现有的区域设置。 |
 | `defaultLocale`   | 如果请求的区域设置不可用，则用作回退的默认区域设置。 | `string`   | `Locales.ENGLISH`   | `'en'`               | 如果 URL、cookie 或 header 中未指定区域设置，则用于确定区域设置。                                                                                                                                                                  |
 
----
-
 ### 编辑器配置 (Editor)
 
 定义可视化编辑器的设置，包括服务器端口和启用状态。
@@ -744,8 +732,6 @@ export default config;
 | `flushInterval` | 自动批量发送到后端之间的毫秒数。                       | `number`  | `20000` | `10000` |                                                                                                                            |
 | `sampleRate`    | 要记录的会话比例，从 `0`（不记录）到 `1`（全部记录）。 | `number`  | `1`     | `0.5`   | 采样按会话确定性进行，因此被记录的会话会报告其所有事件（不会出现部分漏斗）。                                               |
 
----
-
 ### 路由配置 (Routing)
 
 控制路由行为的设置，包括 URL 结构、区域设置存储和中间件管理。
@@ -947,8 +933,6 @@ const config: IntlayerConfig = {
 export default config;
 ```
 
----
-
 ### 内容配置 (Content)
 
 有关应用程序中如何管理内容、目录名称、文件扩展名以及派生配置的设置。
@@ -962,8 +946,6 @@ export default config;
 | `excludedPath`   | 要从内容扫描中排除的目录。                                   | `string[]` | `['**/node_modules/**', '**/dist/**', '**/build/**', '**/.intlayer/**', '**/.next/**', '**/.nuxt/**', '**/.expo/**', '**/.vercel/**', '**/.turbo/**', '**/.tanstack/**']` |                                                                                                                                                                                       | 目前未使用；计划在未来使用。                                                                              |
 | `formatCommand`  | Intlayer 本地写入内容文件时对其进行格式化的命令。            | `string`   | `undefined`                                                                                                                                                               | `'npx prettier --write "{{file}}" --log-level silent'` (Prettier), `'npx biome format "{{file}}" --write --log-level none'` (Biome), `'npx eslint --fix "{{file}}" --quiet'` (ESLint) | • `{{file}}` 将被替换为文件路径。<br/>• 如果未定义，Intlayer 会尝试推断（测试 prettier, biome, eslint）。 |
 
----
-
 ### 系统配置
 
 与 Intlayer 的内部路径和输出结果相关的设置。这些设置通常是内部的，用户通常不需要修改。
@@ -1018,8 +1000,6 @@ dictionary: {
 };
 ```
 
----
-
 ### 日志记录器配置 (Log)
 
 自定义 Intlayer 日志输出的参数。
@@ -1090,8 +1070,6 @@ Intlayer 支持多个 AI 提供商，以提供最大的灵活性。当前支持
 | `outputFormat`        | 控制字典的输出格式。                                           | `('esm' &#124; 'cjs')[]`         | `['esm', 'cjs']`                                                                                                                                                                  | `['cjs']`                                                                     |                                                                                                                                                                                                                                                                                                                                 |
 | `traversePattern`     | 优化期间指定要扫描的文件的模式。                               | `string[]`                       | `['**/*.{tsx,ts,js,mjs,cjs,jsx,vue,svelte,svte}', '!**/node_modules/**', '!**/dist/**', '!**/.intlayer/**', '!**/*.config.*', '!**/*.test.*', '!**/*.spec.*', '!**/*.stories.*']` | `['src/**/*.{ts,tsx}', '../ui-library/**/*.{ts,tsx}', '!**/node_modules/**']` | • 通过将优化限制在相关文件来提高构建性能。<br/>• 如果 `optimize` 关闭则忽略。<br/>• 使用 glob 模式。                                                                                                                                                                                                                            |
 
----
-
 ### 编译器配置 (Compiler)
 
 控制 Intlayer 编译器的设置，该编译器直接从组件中收集字典。
@@ -1111,8 +1089,6 @@ Intlayer 支持多个 AI 提供商，以提供最大的灵活性。当前支持
 | --------- | --------------------------------------- | --------------------------- |
 | `schemas` | 允许您定义 Zod 架构来验证您的字典结构。 | `Record<string, ZodSchema>` |
 
----
-
 ### 插件 (Plugins)
 
 | 字段      | 说明                         | 类型               |
@@ -1128,25 +1104,21 @@ Intlayer 支持多个 AI 提供商，以提供最大的灵活性。当前支持
 放在项目的根目录下，与 `package.json` 同级。Intlayer 还支持 `intlayer.config.js`、`intlayer.config.mjs`、`intlayer.config.cjs` 以及 JSON 格式，因此您可以根据项目使用的模块系统自由选择。
 
 </Question>
-
 <Question title="i18n 会给我的 bundle 体积增加多少？">
 
 远少于基于命名空间的方案，因为页面永远不会下载它不渲染的语言目录。服务端渲染的标记在服务端直接解析内容，而构建时编译器将 `useIntlayer` 调用替换为组件使用的确切字典条目，因此未使用的键和未使用的语言都会被自动丢弃。[动态字典](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dynamic_dictionaries/index.md) 会按语言环境拆分剩余内容。与常规替代方案相比，Intlayer 可将 bundle 和页面体积减少高达 50%。请参阅 [Bundle 体积优化](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/bundle_optimization.md) 和 [性能基准](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/benchmark/index.md)。
 
 </Question>
-
 <Question title="我可以从 i18next、next-intl 或 react-i18next 迁移而无需重写组件吗？">
 
 可以，有两条迁移路径。您可以使用 [i18next 迁移指南](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/migration_from_i18next_to_intlayer.md) 或 [next-intl 迁移指南](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/migration_from_next-intl_to_intlayer.md) 逐步迁移内容。或者，您可以完全保留当前的 API：[兼容性适配器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/compat/index.md) 公开与 `i18next`、`react-i18next`、`next-intl`、`next-i18next`、`react-intl`、`use-intl`、`vue-i18n` 和 `Lingui` 完全相同的 API，但底层由 Intlayer 字典驱动，因此只需更改导入语句，组件代码无需修改。
 
 </Question>
-
 <Question title="我可以保留现有的 JSON 翻译文件吗？">
 
 可以。[JSON 同步插件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/plugins/sync-json.md) 将您的 `/messages/{locale}/{namespace}.json` 文件作为单一真实来源（source of truth），并双向生成 Intlayer 字典。[PO 同步插件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/plugins/sync-po.md) 对 gettext 目录执行相同的操作，而 [按语言环境组织的文件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/per_locale_file.md) 允许您按语言拆分内容，而不是将所有语言打包到一个文件中。
 
 </Question>
-
 <Question title="我必须逐个键迁移我的内容吗？">
 
 不需要。运行 `npx intlayer extract`，Intlayer 会读取您的源码文件，提取面向用户的字符串，并在每个组件旁边生成 `.content` 文件，这样您只需审查 diff，而无需手动逐一复制字符串到语言目录中。请参阅 [extract 命令](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/extract.md)。
@@ -1154,7 +1126,6 @@ Intlayer 支持多个 AI 提供商，以提供最大的灵活性。当前支持
 如需全自动流程，[Intlayer Compiler](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/compiler.md) 可以在构建时对 JSX、TSX、Vue 和 Svelte 源码执行相同操作，在每次更改时自动生成字典，完全无需手动维护键名。它通过静态分析工作，因此仅在运行时存在的字符串无法被捕获，并且需要少量注解以区分用户文本和应用程序逻辑。
 
 </Question>
-
 <Question title="有哪些可用的编辑器和 AI 代理工具？">
 
 共有 5 个工具，均为可选：
@@ -1166,49 +1137,41 @@ Intlayer 支持多个 AI 提供商，以提供最大的灵活性。当前支持
 - **[ESLint 插件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/eslint.md)**：`no-raw-text` 规则标记硬编码字符串，并提供针对静态字典键和未使用内容的额外规则。
 
 </Question>
-
 <Question title="如何向我的应用添加新语言？">
 
 将新的语言环境添加到 `internationalization.locales` 中，然后运行 `npx intlayer fill` 将现有内容翻译为该语言。生成的类型定义会同步更新，因此任何缺少新语言环境的内容文件都会触发编译类型错误，而不是静默回退。
 
 </Question>
-
 <Question title="如何从 URL 中移除语言环境前缀？">
 
 设置 `routing.mode` 选项。默认值 `"prefix-no-default"` 会为默认语言生成 `/about`，为其他语言生成 `/zh/about`。`"prefix-all"` 会为所有语言添加前缀。`"no-prefix"` 则完全不在路径中添加语言环境，而是通过 Cookie、请求头或域名进行解析。`"search-params"` 则将其作为查询参数放入 URL 中，如 `/about?locale=zh`。
 
 </Question>
-
 <Question title="我可以为每种语言配置独立的域名吗？">
 
 可以。`routing.domains` 可以将语言环境映射到具体的主机名，例如 `{ zh: 'example.cn', en: 'example.com' }`。域名直接标识了语言环境，因此路径中无需添加任何前缀，并且 `getLocalizedUrl` 会返回对应正确域名的绝对 URL。
 
 </Question>
-
 <Question title="如何检测用户的语言？">
 
 通过 `routing.storage` 进行检测，它会按顺序依次尝试列出的来源，通常首先是 URL，其次是 Cookie，最后是 `Accept-Language` 请求头。用户明确选择的语言会被持久化保存，从而在下次访问时优先采用。
 
 </Question>
-
 <Question title="routing.enableProxy 有什么作用？">
 
 它控制语言路由代理，即处理路径前缀和重定向的中间件。若未显式设置，代理仍会运行，但开发和预览服务器会忽略持久化的存储语言作为重定向源，从而避免将您强制重定向到当前并未在测试的语言；在生产环境中其行为则等同于 `true`。若您希望自行处理多语言路由，可以将其显式设置为 `false`。
 
 </Question>
-
 <Question title="importMode 中的 static、dynamic 和 fetch 有什么区别？">
 
 默认的 `"static"` 会以静态方式导入字典，因此字典会被打包在一起并同步读取。`"dynamic"` 会通过 Suspense 异步导入字典，因此仅当组件渲染该语言时才会下载对应语言包，非常适合庞大的内容集合。`"fetch"` 则从实时同步 API 获取字典，并在获取失败时回退到 `"dynamic"`。请参阅 [Bundle 体积优化](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/bundle_optimization.md) 和 [动态字典](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dynamic_dictionaries/index.md)。
 
 </Question>
-
 <Question title="在哪里配置用于自动翻译的 AI 提供商和 API 密钥？">
 
 可以在配置文件中设置，或者直接在命令行中使用 `--provider`、`--model` 和 `--api-key` 进行指定。密钥始终由您掌控：翻译请求直接从您的本地机器或 CI 执行器发送给您指定的模型提供商，不经过任何第三方中转。请参阅 [fill 命令](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/fill.md)。
 
 </Question>
-
 <Question title="修改配置后需要重启开发服务器吗？">
 
 通常不需要。Intlayer 监听器会自动监视 `intlayer.config.ts` 本身：在保存时它会重新加载配置并重新准备字典，因此添加语言环境或更改路由模式会像修改内容一样被热更新捕获。不过，部分系统可能会对配置进行缓存，若遇到未生效的情况，重启应用是一个稳妥的解决办法。

package/docs/zh/dictionary/html.md

@@ -119,8 +119,6 @@ const myContent = html(
 
 在 HTML 节点上使用 `.use()` 方法时，你提供的组件将根据 `html()` 函数中提供的定义（如果可用）进行检查。
 
----
-
 ## 渲染 HTML
 
 渲染可以由 Intlayer 的内容系统自动处理，也可以使用专用工具手动完成。
@@ -474,8 +472,6 @@ const myContent = html(
   </Tab>
 </Tabs>
 
----
-
 ### 手动渲染与高级工具
 
 如果你需要渲染原始 HTML 字符串或对组件映射有更多控制，请使用以下工具。
@@ -648,8 +644,6 @@ const myContent = html(
   </Tab>
 </Tabs>
 
----
-
 ## 选项参考
 
 这些选项可以传递给 `HTMLProvider`、`HTMLRenderer`、`useHTMLRenderer` 和 `renderHTML`。

package/docs/zh/dictionary/markdown.md

@@ -1172,8 +1172,6 @@ export class MyComponent {
   </Tab>
 </Tabs>
 
----
-
 ## 服务端渲染 (SSR) 与 注水 (Hydration)
 
 与其他 Markdown 解析器（如 remark / rehype）相比，Intlayer Markdown 无依赖关系，且既可以在客户端运行，也可以在服务端运行。

package/docs/zh/how_works_intlayer.md

@@ -269,25 +269,21 @@ Intlayer 由多个包组成，每个包在翻译过程中都有特定的角色
 在构建时构建。打包器插件或 `npx intlayer build` 会扫描您的 `.content.ts` 文件，将它们解析为 `.intlayer` 文件夹中的字典，并生成匹配的 TypeScript 类型。在运行时，您的组件仅读取生成的结果，因此在请求处理路径上不会发生任何文件读取或解析操作。
 
 </Question>
-
 <Question title="i18n 会给我的 bundle 体积增加多少？">
 
 远少于基于命名空间的方案，因为页面永远不会下载它不渲染的语言目录。服务端渲染的标记在服务端直接解析内容，而构建时编译器将 `useIntlayer` 调用替换为组件使用的确切字典条目，因此未使用的键和未使用的语言都会被自动丢弃。[动态字典](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dynamic_dictionaries/index.md) 会按语言环境拆分剩余内容。与常规替代方案相比，Intlayer 可将 bundle 和页面体积减少高达 50%。请参阅 [Bundle 体积优化](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/bundle_optimization.md) 和 [性能基准](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/benchmark/index.md)。
 
 </Question>
-
 <Question title="我可以从 i18next、next-intl 或 react-i18next 迁移而无需重写组件吗？">
 
 可以，有两条迁移路径。您可以使用 [i18next 迁移指南](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/migration_from_i18next_to_intlayer.md) 或 [next-intl 迁移指南](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/migration_from_next-intl_to_intlayer.md) 逐步迁移内容。或者，您可以完全保留当前的 API：[兼容性适配器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/compat/index.md) 公开与 `i18next`、`react-i18next`、`next-intl`、`next-i18next`、`react-intl`、`use-intl`、`vue-i18n` 和 `Lingui` 完全相同的 API，但底层由 Intlayer 字典驱动，因此只需更改导入语句，组件代码无需修改。
 
 </Question>
-
 <Question title="我可以保留现有的 JSON 翻译文件吗？">
 
 可以。[JSON 同步插件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/plugins/sync-json.md) 将您的 `/messages/{locale}/{namespace}.json` 文件作为单一真实来源（source of truth），并双向生成 Intlayer 字典。[PO 同步插件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/plugins/sync-po.md) 对 gettext 目录执行相同的操作，而 [按语言环境组织的文件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/per_locale_file.md) 允许您按语言拆分内容，而不是将所有语言打包到一个文件中。
 
 </Question>
-
 <Question title="我必须逐个键迁移我的内容吗？">
 
 不需要。运行 `npx intlayer extract`，Intlayer 会读取您的源码文件，提取面向用户的字符串，并在每个组件旁边生成 `.content` 文件，这样您只需审查 diff，而无需手动逐一复制字符串到语言目录中。请参阅 [extract 命令](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/extract.md)。
@@ -295,7 +291,6 @@ Intlayer 由多个包组成，每个包在翻译过程中都有特定的角色
 如需全自动流程，[Intlayer Compiler](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/compiler.md) 可以在构建时对 JSX、TSX、Vue 和 Svelte 源码执行相同操作，在每次更改时自动生成字典，完全无需手动维护键名。它通过静态分析工作，因此仅在运行时存在的字符串无法被捕获，并且需要少量注解以区分用户文本和应用程序逻辑。
 
 </Question>
-
 <Question title="有哪些可用的编辑器和 AI 代理工具？">
 
 共有 5 个工具，均为可选：
@@ -307,43 +302,36 @@ Intlayer 由多个包组成，每个包在翻译过程中都有特定的角色
 - **[ESLint 插件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/eslint.md)**：`no-raw-text` 规则标记硬编码字符串，并提供针对静态字典键和未使用内容的额外规则。
 
 </Question>
-
 <Question title="什么是 .intlayer 文件夹，我应该提交它吗？">
 
 它是构建生成的产物目录：包含编译后的字典和生成的类型。它是从您的内容文件中派生生成的，因此应将其列入 `.gitignore` 中，并像对待 `dist` 目录一样在构建步骤中重新生成，不建议提交到版本控制中。
 
 </Question>
-
 <Question title="活动语言环境是如何确定的？">
 
 通过 `routing.storage` 中列出的来源按顺序解析：当 `routing.mode` 启用前缀时首先读取 URL 前缀，其次是 Cookie，然后是 `Accept-Language` 请求头，最后回退到您的默认语言环境。用户明确选择的语言环境会被持久化，因此在下次访问时依然有效。请参阅 [配置参考](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md)。
 
 </Question>
-
 <Question title="本地字典和远程字典有什么区别？">
 
 本地字典在您的代码库中声明，并随应用程序一起编译打包。远程字典在 [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_CMS.md) 中管理并在运行时进行解析，因此可以在无需重新部署的情况下随时修改。两者通过相同的 Hook 进行读取，并且当远程内容不可用时，会自动回退到本地声明的内容。
 
 </Question>
-
 <Question title="Intlayer 是否可以在不使用 TypeScript 的情况下运行？">
 
 可以。内容文件可以使用 TypeScript、JavaScript、ESM、CommonJS 或 JSON 编写。TypeScript 能够为您带来自动类型生成和完整的自动补全体验，因此是我们推荐的配置方式，但它并非强制要求。
 
 </Question>
-
 <Question title="服务端渲染和客户端渲染如何共享相同的内容？">
 
 服务端会直接解析服务端渲染组件的内容，因此无需为这部分 HTML 向客户端发送字典。客户端组件通过 Provider 读取相同的字典，Provider 接收在服务端解析出的语言环境，因此客户端的首次渲染与服务端 HTML 完全匹配，不会出现语言闪烁。
 
 </Question>
-
 <Question title="Intlayer 如何避免语言环境的水合不匹配 (hydration mismatch)？">
 
 语言环境在服务端仅解析一次并传递给 Provider，而不是在浏览器中重新检测。因为客户端以服务端渲染所用的相同语言环境作为初始状态，所以生成的标记完全匹配，从而避免了客户端单独检测语言时常出现的水合不匹配问题。
 
 </Question>
-
 <Question title="添加翻译后需要重新构建吗？">
 
 在开发环境下不需要：插件会监视您的内容文件并在保存时自动重新构建受影响的字典。在生产环境中，字典是构建产物的一部分；除非内容配置为远程管理，此时通过 [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_CMS.md) 和 [实时同步 (live sync)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/live.md) 即可无需重新部署直接应用最新更新。

package/docs/zh/interest_of_intlayer.md

@@ -44,43 +44,36 @@ author: aymericzip
 无需在页面中加载庞大的 JSON 文件，只需加载必要的特定内容。Intlayer 可以帮助你**将打包体积和页面大小减少多达 50%**。
 
 </Accordion>
-
 <Accordion header="可维护性">
 
 对应用程序的内容进行组件级的范围限制，**大大简化了大型应用程序的维护工作**。你可以复制或删除单个功能文件夹，而无需承担审查整个内容代码库的精神负担。此外，Intlayer 是**完全类型化**的，以确保你内容的准确性。
 
 </Accordion>
-
 <Accordion header="AI 智能体支持">
 
 将内容与组件共同放置（Co-location）**减少了大型语言模型（LLMs）所需的上下文**。Intlayer 还提供了一套工具，例如用于测试缺失翻译的 **CLI**、**[LSP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/lsp.md)**、**[MCP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/mcp_server.md)** 以及 **[Agent Skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/agent_skills.md)**，使 AI 智能体的开发体验（DX）更加流畅。
 
 </Accordion>
-
 <Accordion header="功能丰富">
 
 Intlayer 提供了其他 i18n 解决方案所没有的一系列附加功能，例如 [Markdown 支持](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/markdown.md)、[外部内容获取](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/function_fetching.md)、[文件内容加载](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/file.md)、[实时内容更新](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/live.md)、[可视化编辑器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_visual_editor.md)等。
 
 </Accordion>
-
 <Accordion header="自动化">
 
 使用自动化在你的 CI/CD 流程中翻译，可以使用你选择的任何 LLM，成本完全取决于你的 AI 提供商。Intlayer 还提供了一个**编译器**来自动提取内容，以及一个 [网页平台](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_CMS.md) 来帮助你**在后台进行翻译工作**。
 
 </Accordion>
-
 <Accordion header="性能">
 
 将庞大的 JSON 文件连接到组件上可能会导致性能和响应性问题。Intlayer 在构建时优化了你的内容加载方式。
 
 </Accordion>
-
 <Accordion header="扩展至非开发团队">
 
 不仅仅是一个 i18n 解决方案，Intlayer 还提供了一个**自主托管的[可视化编辑器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_visual_editor.md)**和一个**[功能完备的 CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_CMS.md)**，帮助你**实时**管理多语言内容，使与翻译人员、文案人员和其他团队成员的协作变得无缝衔接。内容可以存储在本地和/或远程。
 
 </Accordion>
-
 <Accordion header="跨框架设计">
 
 如果你在应用程序的不同部分使用不同的框架（例如 React、React-native、Vue、Angular、Svelte 等），Intlayer 提供了一种**在所有主流前端框架中使用通用语法和实现**的方法。你还可以跨设计系统、应用、后端等共享你的内容声明。
@@ -282,8 +275,6 @@ GitHub Star 数是衡量项目受欢迎程度、社区信任度以及长期相
 
 [![Star History Chart](https://api.star-history.com/chart?repos=aymericzip/intlayer%2Cformatjs/formatjs%2Ci18next/react-i18next%2Ci18next/i18next%2Ci18next/next-i18next%2Clingui/js-lingui%2Camannn/next-intl%2Cintlify/vue-i18n%2Ccodingcommons/typesafe-i18n%2Copral/paraglide-js&type=date&legend=top-left)](https://www.star-history.com/#aymericzip/intlayer&formatjs/formatjs&i18next/react-i18next&i18next/i18next&i18next/next-i18next&lingui/js-lingui&amannn/next-intl&intlify/vue-i18n&codingcommons/typesafe-i18n&opral/paraglide-js)
 
----
-
 ## 互操作性
 
 `intlayer` 还可以帮助管理你的 `react-intl`、`react-i18next`、`next-intl`、`next-i18next` 以及 `vue-i18n` 命名空间。
@@ -305,25 +296,21 @@ GitHub Star 数是衡量项目受欢迎程度、社区信任度以及长期相
 - **内容层库**：`Intlayer`。内容按组件声明并按组件编译，因此类型安全、代码摇树优化 (tree-shaking)、编辑工具和 AI 翻译均源自同一套声明。
 
 </Question>
-
 <Question title="i18n 会给我的 bundle 体积增加多少？">
 
 远少于基于命名空间的方案，因为页面永远不会下载它不渲染的语言目录。服务端渲染的标记在服务端直接解析内容，而构建时编译器将 `useIntlayer` 调用替换为组件使用的确切字典条目，因此未使用的键和未使用的语言都会被自动丢弃。[动态字典](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dynamic_dictionaries/index.md) 会按语言环境拆分剩余内容。与常规替代方案相比，Intlayer 可将 bundle 和页面体积减少高达 50%。请参阅 [Bundle 体积优化](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/bundle_optimization.md) 和 [性能基准](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/benchmark/index.md)。
 
 </Question>
-
 <Question title="我可以从 i18next、next-intl 或 react-i18next 迁移而无需重写组件吗？">
 
 可以，有两条迁移路径。您可以使用 [i18next 迁移指南](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/migration_from_i18next_to_intlayer.md) 或 [next-intl 迁移指南](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/migration_from_next-intl_to_intlayer.md) 逐步迁移内容。或者，您可以完全保留当前的 API：[兼容性适配器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/compat/index.md) 公开与 `i18next`、`react-i18next`、`next-intl`、`next-i18next`、`react-intl`、`use-intl`、`vue-i18n` 和 `Lingui` 完全相同的 API，但底层由 Intlayer 字典驱动，因此只需更改导入语句，组件代码无需修改。
 
 </Question>
-
 <Question title="我可以保留现有的 JSON 翻译文件吗？">
 
 可以。[JSON 同步插件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/plugins/sync-json.md) 将您的 `/messages/{locale}/{namespace}.json` 文件作为单一真实来源（source of truth），并双向生成 Intlayer 字典。[PO 同步插件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/plugins/sync-po.md) 对 gettext 目录执行相同的操作，而 [按语言环境组织的文件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/per_locale_file.md) 允许您按语言拆分内容，而不是将所有语言打包到一个文件中。
 
 </Question>
-
 <Question title="我必须逐个键迁移我的内容吗？">
 
 不需要。运行 `npx intlayer extract`，Intlayer 会读取您的源码文件，提取面向用户的字符串，并在每个组件旁边生成 `.content` 文件，这样您只需审查 diff，而无需手动逐一复制字符串到语言目录中。请参阅 [extract 命令](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/extract.md)。
@@ -331,7 +318,6 @@ GitHub Star 数是衡量项目受欢迎程度、社区信任度以及长期相
 如需全自动流程，[Intlayer Compiler](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/compiler.md) 可以在构建时对 JSX、TSX、Vue 和 Svelte 源码执行相同操作，在每次更改时自动生成字典，完全无需手动维护键名。它通过静态分析工作，因此仅在运行时存在的字符串无法被捕获，并且需要少量注解以区分用户文本和应用程序逻辑。
 
 </Question>
-
 <Question title="有哪些可用的编辑器和 AI 代理工具？">
 
 共有 5 个工具，均为可选：
@@ -343,43 +329,36 @@ GitHub Star 数是衡量项目受欢迎程度、社区信任度以及长期相
 - **[ESLint 插件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/eslint.md)**：`no-raw-text` 规则标记硬编码字符串，并提供针对静态字典键和未使用内容的额外规则。
 
 </Question>
-
 <Question title="Intlayer 与 next-intl 有什么区别？">
 
 `next-intl` 是面向 Next.js 的消息层：您为每个语言环境维护一个 JSON 消息文件，并通过 `useTranslations` 读取它们。Intlayer 是内容层：内容声明与组件紧密相邻，类型直接由声明本身推导，并且按组件编译，因此页面仅打包其渲染的内容。Intlayer 还涵盖了 `next-intl` 留给您自行解决的功能，即 AI 翻译、可视化编辑器、CMS 以及在 CI 中的缺失翻译检查。如果您想保留 `next-intl` 的 API，可以通过 [兼容性适配器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/compat/index.md) 直接由 Intlayer 字典提供支持。
 
 </Question>
-
 <Question title="Intlayer 与 i18next 和 react-i18next 有什么区别？">
 
 `i18next` 在运行时根据命名空间解析字符串键，这意味着重命名或拼写错误的键会静默失败，并且页面涉及的每个命名空间都会被全量下载。Intlayer 在构建时根据生成的类型解析内容，因此错误的键会直接产生编译报错，且仅组件渲染的条目才会进入 bundle。`i18next` 拥有更庞大的插件生态和更久远的历史沉淀；而 Intlayer 则具有强类型安全、显著优化的 bundle 体积，以及完善的内容编辑与自动化工具链。请参阅 [i18next 迁移指南](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/migration_from_i18next_to_intlayer.md) 或 [兼容性适配器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/compat/index.md)。
 
 </Question>
-
 <Question title="Intlayer 是否比替代方案更快或更轻量？">
 
 在 bundle 和页面体积方面，确实如此：避免加载页面未渲染的语言目录相比基于命名空间的方案可将 bundle 和页面体积减少高达 50%。[性能基准测试](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/benchmark/index.md) 公布了测试方法以及各框架的具体数据，包括 [Next.js](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/benchmark/nextjs.md)、[TanStack Start](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/benchmark/tanstack.md)、[Vue](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/benchmark/vue.md) 和 [Svelte](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/benchmark/svelte.md)，以便您可以自行复现验证，而无需盲从宣传。
 
 </Question>
-
 <Question title="迁移现有应用值得吗？">
 
 这取决于您当前的痛点是什么。如果您的痛点在于 bundle 体积过大、缺失翻译静默失效，或者翻译人员无法独立开展工作而必须依赖开发者，那么迁移的回报非常显著。如果您的目录较小且内容稳定，收益相对较小。无论哪种情况，迁移都不需要重写整个应用：[兼容性适配器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/compat/index.md) 能保留您当前的 API，而 [JSON 同步插件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/plugins/sync-json.md) 可以在两层共存期间将现有的 JSON 文件继续作为单一真实来源（source of truth）。
 
 </Question>
-
 <Question title="Intlayer 提供了哪些其他 i18n 库所没有的功能？">
 
 [Markdown 内容](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/markdown.md)、[从外部源获取内容](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/content_file.md)、文件内容加载、[实时内容更新 (live sync)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/live.md)、[可视化编辑器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_visual_editor.md)、[CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_CMS.md)、从现有组件自动提取内容的 [编译器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/compiler.md)、用于 A/B 测试的 [内容变体 (variants)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dynamic_dictionaries/variants.md)、关于内容曝光率的 [数据分析 (analytics)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/analytics.md)、[MCP 服务器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/mcp_server.md)、[LSP 服务器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/lsp.md) 以及 [Agent Skills 代理技能](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/agent_skills.md)。
 
 </Question>
-
 <Question title="我可以仅将 Intlayer 用作翻译管理器并保留当前的 i18n 库吗？">
 
 可以。Intlayer 可以按照您当前库所期望的格式和路径生成命名空间（例如 `/messages/{locale}/{namespace}.json`），这样您可以在应用代码继续使用现有 i18n 库的同时，享受到 AI 翻译、可视化编辑器和 CI 检查带来的便利。
 
 </Question>
-
 <Question title="Intlayer 是免费且开源的吗？">
 
 是的，基于 Apache 2.0 许可证开源，包含商业用途。托管版 CMS 是可选的付费服务，同时完全支持 [自托管](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/self_hosting.md)。