@intlayer/docs 9.4.1 → 9.4.3

package/docs/zh/how_works_intlayer.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-12
-updatedAt: 2025-06-29
+updatedAt: 2026-08-30
 title: Intlayer 的工作原理
 description: 了解Intlayer的内部运作方式。理解使Intlayer强大的架构和组件。
 keywords:
@@ -259,3 +259,95 @@ Intlayer 由多个包组成，每个包在翻译过程中都有特定的角色
 ## 与我们的智能文档聊天
 
 - [向我们的智能文档提问](https://intlayer.org/doc/chat)
+
+## 常见问题
+
+<FAQ>
+
+<Question title="字典是在构建时构建还是在运行时构建？">
+
+在构建时构建。打包器插件或 `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)。
+
+如需全自动流程，[Intlayer Compiler](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/compiler.md) 可以在构建时对 JSX、TSX、Vue 和 Svelte 源码执行相同操作，在每次更改时自动生成字典，完全无需手动维护键名。它通过静态分析工作，因此仅在运行时存在的字符串无法被捕获，并且需要少量注解以区分用户文本和应用程序逻辑。
+
+</Question>
+
+<Question title="有哪些可用的编辑器和 AI 代理工具？">
+
+共有 5 个工具，均为可选：
+
+- **[VS Code 扩展](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/vs_code_extension.md)**：从 `useIntlayer` 键跳转到声明它的内容文件，从组件中提取内容，并从命令面板或专属的 Intlayer 选项卡运行 build、fill、test、push 和 pull。
+- **[LSP 服务器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/lsp.md)**：在任何支持 LSP 的编辑器中提供相同的感知能力，支持跳转到定义、查找所有引用、悬停预览翻译值、键和字段的自动补全，以及在键未声明时发出警告。它还可以解析 `i18next`、`react-i18next`、`next-intl` 和 `use-intl` 调用，助力平滑迁移。
+- **[MCP 服务器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/mcp_server.md)**：向 Cursor、VS Code、Claude Desktop、Claude Code 和 ChatGPT 公开 Intlayer 文档与 CLI，使 AI 助手能够基于最新文档进行准确回答，并能自行运行 `intlayer fill` 等命令。
+- **[Agent Skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/agent_skills.md)**：针对特定领域的技能（如 `intlayer-config`、`intlayer-cli` 和 `intlayer-content`，以及每个框架对应的专属技能），教导 AI 代理您的路由配置和内容节点类型。
+- **[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) 即可无需重新部署直接应用最新更新。
+
+</Question>
+
+</FAQ>

package/docs/zh/interest_of_intlayer.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-14
-updatedAt: 2026-05-31
+updatedAt: 2026-08-30
 title: Intlayer 的重要性
 description: 探索在项目中使用 Intlayer 的好处和优势。了解为什么 Intlayer 在其他框架中脱颖而出。
 keywords:
@@ -39,8 +39,7 @@ author: aymericzip
 与 `next-intl` 或 `i18next` 等主要解决方案相比，Intlayer 是一个自带集成优化的解决方案，例如：
 
 <AccordionGroup>
-
-**打包体积 (Bundle size)**
+<Accordion header="打包体积">
 
 无需在页面中加载庞大的 JSON 文件，只需加载必要的特定内容。Intlayer 可以帮助你**将打包体积和页面大小减少多达 50%**。
 
@@ -48,23 +47,23 @@ author: aymericzip
 
 <Accordion header="可维护性">
 
-**可维护性 (Maintainability)**
-
 对应用程序的内容进行组件级的范围限制，**大大简化了大型应用程序的维护工作**。你可以复制或删除单个功能文件夹，而无需承担审查整个内容代码库的精神负担。此外，Intlayer 是**完全类型化**的，以确保你内容的准确性。
 
-**AI 智能体支持 (AI Agent)**
+</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>
 
-**功能丰富 (Feature)**
+<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>
 
-**自动化 (Automation)**
+<Accordion header="自动化">
 
 使用自动化在你的 CI/CD 流程中翻译，可以使用你选择的任何 LLM，成本完全取决于你的 AI 提供商。Intlayer 还提供了一个**编译器**来自动提取内容，以及一个 [网页平台](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_CMS.md) 来帮助你**在后台进行翻译工作**。
 
@@ -72,17 +71,17 @@ Intlayer 提供了其他 i18n 解决方案所没有的一系列附加功能，
 
 <Accordion header="性能">
 
-**性能表现 (Performance)**
-
 将庞大的 JSON 文件连接到组件上可能会导致性能和响应性问题。Intlayer 在构建时优化了你的内容加载方式。
 
-**扩展至非开发团队 (Scaling with non-dev)**
+</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>
 
-**跨框架设计 (Cross framework design)**
+<Accordion header="跨框架设计">
 
 如果你在应用程序的不同部分使用不同的框架（例如 React、React-native、Vue、Angular、Svelte 等），Intlayer 提供了一种**在所有主流前端框架中使用通用语法和实现**的方法。你还可以跨设计系统、应用、后端等共享你的内容声明。
 
@@ -291,4 +290,100 @@ GitHub Star 数是衡量项目受欢迎程度、社区信任度以及长期相
 
 使用 `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)。
+如果想继续使用当前 i18n 库的 API，`intlayer` 还提供了 **兼容适配器（compat adapters）**：这些包暴露与 `react-i18next`、`next-intl`、`react-intl`、`vue-i18n` 等完全相同的 API，但内容由 Intlayer 词典提供。这样你就可以逐步迁移，而无需重写代码。参见[兼容适配器文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/compat/index.md)。
+
+## 常见问题
+
+<FAQ>
+
+<Question title="国际化 JavaScript 应用有哪些不同的解决方案？">
+
+三代方案共存：
+
+- **运行时目录库**：`i18next`、`react-i18next`、`next-i18next`、`vue-i18n`、`ngx-translate`、`svelte-i18n`。在运行时加载 JSON 命名空间。成熟且与框架无关，但没有强类型定义，并且整包分发到页面中。
+- **编译时消息库**：`Lingui`、`Paraglide`，以及带有提取步骤的 `next-intl` 或 `react-intl`。具有更好的 bundle 行为和部分类型支持，但仍采用集中式目录。
+- **内容层库**：`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)。
+
+如需全自动流程，[Intlayer Compiler](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/compiler.md) 可以在构建时对 JSX、TSX、Vue 和 Svelte 源码执行相同操作，在每次更改时自动生成字典，完全无需手动维护键名。它通过静态分析工作，因此仅在运行时存在的字符串无法被捕获，并且需要少量注解以区分用户文本和应用程序逻辑。
+
+</Question>
+
+<Question title="有哪些可用的编辑器和 AI 代理工具？">
+
+共有 5 个工具，均为可选：
+
+- **[VS Code 扩展](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/vs_code_extension.md)**：从 `useIntlayer` 键跳转到声明它的内容文件，从组件中提取内容，并从命令面板或专属的 Intlayer 选项卡运行 build、fill、test、push 和 pull。
+- **[LSP 服务器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/lsp.md)**：在任何支持 LSP 的编辑器中提供相同的感知能力，支持跳转到定义、查找所有引用、悬停预览翻译值、键和字段的自动补全，以及在键未声明时发出警告。它还可以解析 `i18next`、`react-i18next`、`next-intl` 和 `use-intl` 调用，助力平滑迁移。
+- **[MCP 服务器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/mcp_server.md)**：向 Cursor、VS Code、Claude Desktop、Claude Code 和 ChatGPT 公开 Intlayer 文档与 CLI，使 AI 助手能够基于最新文档进行准确回答，并能自行运行 `intlayer fill` 等命令。
+- **[Agent Skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/agent_skills.md)**：针对特定领域的技能（如 `intlayer-config`、`intlayer-cli` 和 `intlayer-content`，以及每个框架对应的专属技能），教导 AI 代理您的路由配置和内容节点类型。
+- **[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)。
+
+</Question>
+
+</FAQ>

package/docs/zh/intlayer_CMS.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-08-23
-updatedAt: 2026-07-08
+updatedAt: 2026-08-30
 title: Intlayer CMS | 将您的内容外部化到 Intlayer CMS
 description: 将您的内容外部化到 Intlayer CMS，以将内容管理委托给您的团队。
 keywords:
@@ -428,3 +428,95 @@ curl -fsSL https://intlayer.org/install.sh | sh
 - 确保项目配置已推送到 Intlayer CMS。
 
 - 可视化编辑器使用 iframe 来显示您的网站。确保您的网站的内容安全策略 (CSP) 允许 CMS URL 作为 `frame-ancestors`（默认为 'https://app.intlayer.org'）。检查编辑器控制台中的任何错误。
+
+## 常见问题
+
+<FAQ>
+
+<Question title="Intlayer CMS 与可视化编辑器有什么区别？">
+
+[可视化编辑器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_visual_editor.md) 编辑的是本地字典，并将修改直接写回您的代码库中，因此应用需要重新构建，并且更改需要走正常的代码审查和部署流程。而 CMS 编辑的是远程字典：修改完全不触碰您的代码库，运行中的站点无需重新部署即可直接生效。团队通常两者搭配使用：开发者维护的内容使用编辑器，市场团队每周频繁更新的内容使用 CMS。
+
+</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)。
+
+如需全自动流程，[Intlayer Compiler](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/compiler.md) 可以在构建时对 JSX、TSX、Vue 和 Svelte 源码执行相同操作，在每次更改时自动生成字典，完全无需手动维护键名。它通过静态分析工作，因此仅在运行时存在的字符串无法被捕获，并且需要少量注解以区分用户文本和应用程序逻辑。
+
+</Question>
+
+<Question title="有哪些可用的编辑器和 AI 代理工具？">
+
+共有 5 个工具，均为可选：
+
+- **[VS Code 扩展](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/vs_code_extension.md)**：从 `useIntlayer` 键跳转到声明它的内容文件，从组件中提取内容，并从命令面板或专属的 Intlayer 选项卡运行 build、fill、test、push 和 pull。
+- **[LSP 服务器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/lsp.md)**：在任何支持 LSP 的编辑器中提供相同的感知能力，支持跳转到定义、查找所有引用、悬停预览翻译值、键和字段的自动补全，以及在键未声明时发出警告。它还可以解析 `i18next`、`react-i18next`、`next-intl` 和 `use-intl` 调用，助力平滑迁移。
+- **[MCP 服务器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/mcp_server.md)**：向 Cursor、VS Code、Claude Desktop、Claude Code 和 ChatGPT 公开 Intlayer 文档与 CLI，使 AI 助手能够基于最新文档进行准确回答，并能自行运行 `intlayer fill` 等命令。
+- **[Agent Skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/agent_skills.md)**：针对特定领域的技能（如 `intlayer-config`、`intlayer-cli` 和 `intlayer-content`，以及每个框架对应的专属技能），教导 AI 代理您的路由配置和内容节点类型。
+- **[ESLint 插件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/eslint.md)**：`no-raw-text` 规则标记硬编码字符串，并提供针对静态字典键和未使用内容的额外规则。
+
+</Question>
+
+<Question title="哪些内容应该迁移到 CMS 中？">
+
+经常变化且不属于版本发布周期的一部分的内容：落地页文案、定价方案措辞、活动公告等任何由市场团队负责的内容。而作为界面核心组成部分的内容（如按钮标签和表单验证错误信息）更适合作为本地字典保留在代码库中，以便与使用它的代码一同进行代码审查。
+
+</Question>
+
+<Question title="如果 CMS 无法访问会发生什么？">
+
+应用程序会自动回退到字典的本地声明，因此网络故障或外部中断只会降级为使用构建时打包的本地内容，绝不会渲染出空白页面。这正是为每个远程字典保留本地声明至关重要的原因。
+
+</Question>
+
+<Question title="我可以自托管 CMS 吗？">
+
+可以。CMS 完全可以在您自己的基础设施上运行，这非常适合内容不能离开内部网络的私有化合规场景。请参阅 [自托管 Intlayer 指南](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/self_hosting.md)。
+
+</Question>
+
+<Question title="内容编辑人员发布更改需要开发者介入吗？">
+
+不需要。这正是远程字典的核心价值：编辑人员在 CMS 中修改文案，线上站点便会直接反映更新，通过 [实时同步 (live sync)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/live.md) 在运行时即时应用更新，无需等待构建和发布流水线。
+
+</Question>
+
+<Question title="除了使用图形界面外，我可以对 CMS 进行自动化操作吗？">
+
+可以。`@intlayer/api` SDK 公开了与图形界面完全相同的 API 端点，因此您可以通过脚本或 CI/CD 流水线拉取项目、读取字典并推送更新。上方章节展示了身份认证及各端点的调用方法。
+
+</Question>
+
+<Question title="CMS 是否支持 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) 会报告每个变体的曝光数据，使文案效果能够通过数据直接衡量，而无需无谓争论。
+
+</Question>
+
+<Question title="CMS 是免费的吗？">
+
+Intlayer 的核心库、CLI、编译器和可视化编辑器均在 Apache 2.0 许可证下完全开源免费。云端托管版 CMS 是一项可选的付费服务，您也可以选择完全免费的 [自托管方案](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/self_hosting.md)。
+
+</Question>
+
+</FAQ>

package/docs/zh/intlayer_visual_editor.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-11
-updatedAt: 2025-06-29
+updatedAt: 2026-08-30
 title: Intlayer 可视编辑器 | 使用可视编辑器编辑您的内容
 description: 发现如何使用 Intlayer 编辑器来管理您的多语言网站。按照本在线文档中的步骤，在几分钟内设置您的项目。
 keywords:
@@ -210,4 +210,90 @@ pnpm intlayer-editor start -e development
   - 必需字段：
     - 应用程序 URL 应与您在编辑器配置中设置的 URL (`applicationURL`) 匹配。
 
-- 可视化编辑器使用 iframe 来显示您的网站。请确保您网站的内容安全策略（CSP）允许将 CMS URL 作为 `frame-ancestors`（默认值为 'http://localhost:8000'）。如有错误，请检查编辑器控制台。
+- 可视化编辑器使用 iframe 来显示您的网站。请确保您网站的内容安全策略（CSP）允许将 CMS URL 作为 `frame-ancestors`（默认值为 `http://localhost:8000`）。如有错误，请检查编辑器控制台。
+
+## 常见问题
+
+<FAQ>
+
+<Question title="可视化编辑器与 CMS 有什么区别？">
+
+可视化编辑器编辑的是本地字典，并将修改直接写回您的代码库中，因此会走常规的代码审查和部署流水线。而 [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_CMS.md) 编辑的是远程字典，可在运行中的线上站点直接生效而无需重新部署。编辑器适合开发者掌控的内容；CMS 适合市场团队掌控的内容。
+
+</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)。
+
+如需全自动流程，[Intlayer Compiler](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/compiler.md) 可以在构建时对 JSX、TSX、Vue 和 Svelte 源码执行相同操作，在每次更改时自动生成字典，完全无需手动维护键名。它通过静态分析工作，因此仅在运行时存在的字符串无法被捕获，并且需要少量注解以区分用户文本和应用程序逻辑。
+
+</Question>
+
+<Question title="有哪些可用的编辑器和 AI 代理工具？">
+
+共有 5 个工具，均为可选：
+
+- **[VS Code 扩展](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/vs_code_extension.md)**：从 `useIntlayer` 键跳转到声明它的内容文件，从组件中提取内容，并从命令面板或专属的 Intlayer 选项卡运行 build、fill、test、push 和 pull。
+- **[LSP 服务器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/lsp.md)**：在任何支持 LSP 的编辑器中提供相同的感知能力，支持跳转到定义、查找所有引用、悬停预览翻译值、键和字段的自动补全，以及在键未声明时发出警告。它还可以解析 `i18next`、`react-i18next`、`next-intl` 和 `use-intl` 调用，助力平滑迁移。
+- **[MCP 服务器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/mcp_server.md)**：向 Cursor、VS Code、Claude Desktop、Claude Code 和 ChatGPT 公开 Intlayer 文档与 CLI，使 AI 助手能够基于最新文档进行准确回答，并能自行运行 `intlayer fill` 等命令。
+- **[Agent Skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/agent_skills.md)**：针对特定领域的技能（如 `intlayer-config`、`intlayer-cli` 和 `intlayer-content`，以及每个框架对应的专属技能），教导 AI 代理您的路由配置和内容节点类型。
+- **[ESLint 插件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/eslint.md)**：`no-raw-text` 规则标记硬编码字符串，并提供针对静态字典键和未使用内容的额外规则。
+
+</Question>
+
+<Question title="可视化编辑器运行在哪里？">
+
+运行在您自己的基础设施上。它在 iframe 中加载您的应用程序并与本地编辑器服务器通信，因此您的内容永远不会离开您的本地环境。这使得无法将文案发送到第三方托管服务的敏感项目也能放心使用。
+
+</Question>
+
+<Question title="内容编辑人员需要懂编程吗？">
+
+不需要。他们只需打开站点，点击任意文本块即可在页面上就地修改。编辑器会自动解析是哪个字典条目支撑了该文本，并将更改准确写回正确的内容文件中，因此翻译人员无需知道文件路径或键名。
+
+</Question>
+
+<Question title="通过可视化编辑器修改会更改我的源代码文件吗？">
+
+是的，这正是其设计目的。更改会直接写入您代码库中的内容声明文件，因此它会作为正常的代码 diff 展示供您审查和提交，并且应用会重新构建以呈现最新修改。
+
+</Question>
+
+<Question title="编辑器显示空白页或拒绝加载我的网站，我应该检查什么？">
+
+编辑器通过 iframe 展示您的应用程序，因此您的内容安全策略 (CSP) 必须将编辑器的来源允许为 `frame-ancestors`（默认为 `http://localhost:8000`）。同时请确认编辑器配置中的 `applicationURL` 与您应用的实际服务地址完全一致。编辑器控制台会详细报告这两类错误。
+
+</Question>
+
+<Question title="我可以在生产环境中使用可视化编辑器吗？">
+
+它是专为开发和预发布 (staging) 环境设计的，在这类环境中编辑后触发重新构建是可以接受的。若要在无需重新部署的情况下直接修改线上运行中的内容，请使用 [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_CMS.md) 及其远程字典功能。
+
+</Question>
+
+<Question title="可视化编辑器是免费的吗？">
+
+是的。可视化编辑器是开源项目的一部分，基于 Apache 2.0 许可证授权，包含商业用途。仅托管版 [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_CMS.md) 属于付费服务，并且 CMS 也完全支持 [自托管](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/self_hosting.md)。
+
+</Question>
+
+</FAQ>