@intlayer/docs 9.4.1 → 9.4.3

package/docs/zh/bundle_optimization.md

@@ -43,139 +43,6 @@ author: aymericzip
 
 <TOC />
 
-## 分析你的包大小
-
-分析你的打包结果是找出“臃肿”的 JSON 文件和考虑进行代码分割（code-splitting）的首要步骤。这些工具可以生成你应用程序编译代码的树状可视视图（treemap），让你能够清楚地看到究竟是哪些库占据了最多的空间。
-
-<Tabs>
- <Tab value="vite">
-
-### Vite / Rollup
-
-Vite 在底层使用了 Rollup。插件 `rollup-plugin-visualizer` 能够生成一个交互式 HTML 文件，展示依赖图（graph）中每个模块的体积。
-
-```bash
-npm install -D rollup-plugin-visualizer
-```
-
-```typescript fileName="vite.config.ts"
-import { defineConfig } from "vite";
-import { visualizer } from "rollup-plugin-visualizer";
-
-export default defineConfig({
-  plugins: [
-    visualizer({
-      open: true, // 自动在浏览器中打开报告
-      filename: "stats.html",
-      gzipSize: true,
-      brotliSize: true,
-    }),
-  ],
-});
-```
-
- </Tab>
- <Tab value="nextjs (turbopack)">
-
-### Next.js (Turbopack)
-
-对于使用了 App Router 和 Turbopack 的项目，Next.js 提供了一个内置的实验性分析器，它不需要额外的依赖。
-
-```bash packageManager='npm'
-npx next experimental-analyze
-```
-
-```bash packageManager='yarn'
-yarn next experimental-analyze
-```
-
-```bash packageManager='pnpm'
-pnpm next experimental-analyze
-```
-
-```bash packageManager='bun'
-bun next experimental-analyze
-```
-
- </Tab>
- <Tab value="nextjs (Webpack)">
-
-### Next.js (Webpack)
-
-如果你在 Next.js 中使用的是默认的 Webpack 打包器，请使用官方的 bundle analyzer。你可以通过在构建期间设置一个环境变量来触发它。
-
-```bash packageManager='npm'
-npm install -D @next/bundle-analyzer
-```
-
-```bash packageManager='yarn'
-yarn add -D @next/bundle-analyzer
-```
-
-```bash packageManager='pnpm'
-pnpm add -D @next/bundle-analyzer
-```
-
-```bash packageManager='bun'
-bun add -d @next/bundle-analyzer
-```
-
-```javascript fileName="next.config.js"
-const withBundleAnalyzer = require("@next/bundle-analyzer")({
-  enabled: process.env.ANALYZE === "true",
-});
-
-module.exports = withBundleAnalyzer({
-  // 你的 Next.js 配置
-});
-```
-
-**用法:**
-
-```bash
-ANALYZE=true npm run build
-```
-
- </Tab>
- <Tab value="Webpack (CRA / Angular / etc)">
-
-### 纯 Webpack
-
-针对 Create React App (ejected)、Angular 或是自定义 Webpack 的设置，使用业界标准的 `webpack-bundle-analyzer`。
-
-```bash packageManager='npm'
-npm install -D webpack-bundle-analyzer
-```
-
-```bash packageManager='yarn'
-yarn add -D webpack-bundle-analyzer
-```
-
-```bash packageManager='pnpm'
-pnpm add -D webpack-bundle-analyzer
-```
-
-```bash packageManager='bun'
-bun add -d webpack-bundle-analyzer
-```
-
-```typescript fileName="webpack.config.ts"
-import { BundleAnalyzerPlugin } from "webpack-bundle-analyzer";
-
-export default {
-  plugins: [
-    new BundleAnalyzerPlugin({
-      analyzerMode: "static",
-      reportFilename: "bundle-analyzer.html",
-      openAnalyzer: false,
-    }),
-  ],
-};
-```
-
- </Tab>
-</Tabs>
-
 ## 它是如何运作的
 
 Intlayer 使用一种**基于组件的方法（per-component approach）**。与全局 JSON 文件不同，你的内容会在组件旁边或是组件内部进行定义。在构建流程中，Intlayer 将会：
@@ -189,59 +56,6 @@ Intlayer 使用一种**基于组件的方法（per-component approach）**。与
 - 如果一个组件未被导入，它的内容将不会包含在打包产物中（Dead Code Elimination / 死代码消除）。
 - 如果一个组件被延迟加载，其内容同样会被延迟加载。
 
-## 插件参考
-
-Intlayer 的构建优化被划分为若干个职责单一的插件。了解它们各自的用途可以防止在配置它们时产生困惑。
-
-### Babel 插件 (`@intlayer/babel`)
-
-这些被直接运用在基于 Webpack 设置的 `babel.config.js` 当中（比如使用了 Babel 的 Next.js、CRA，或是自定义的 Webpack 等）。
-
-下表按所需的流水线顺序列出它们（与它们必须在 `babel.config.js` 中出现的顺序相同）：
-
-| 插件                          | 功能说明                                                                                             |
-| :---------------------------- | :--------------------------------------------------------------------------------------------------- |
-| `intlayerExtractBabelPlugin`  | 扫描 `.content.ts` 文件并把编译好的字典写入 `.intlayer/`                                             |
-| `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 信息。
-
-每一个 Babel 插件都有对应的选项助手（options helper），该助手会在配置加载时读取一遍 `intlayer.config.ts`，并返回预解析的值：
-
-| 选项助手                     | 配套插件                      |
-| :--------------------------- | :---------------------------- |
-| `getExtractPluginOptions()`  | `intlayerExtractBabelPlugin`  |
-| `getPurgePluginOptions()`    | `intlayerPurgeBabelPlugin`    |
-| `getMinifyPluginOptions()`   | `intlayerMinifyBabelPlugin`   |
-| `getOptimizePluginOptions()` | `intlayerOptimizeBabelPlugin` |
-
-### Vite 插件 (`vite-intlayer`)
-
-Vite 用户**不需要直接对它们进行配置**。当你在 `vite.config.ts` 里调用 `withIntlayer()` 时，它们会自动生效。只需要在 `intlayer.config.ts` 中设定 `build.purge` 和 `build.minify`，即可开启相应的功能，且不需要额外的插件注册过程。
-
-| 内部 Vite 插件    | 等效行为                                                                            |
-| :---------------- | :---------------------------------------------------------------------------------- |
-| Usage analyzer    | 等同于 `intlayerPurgeBabelPlugin` 的分析步骤                                        |
-| Dictionary prune  | 等同于 `intlayerPurgeBabelPlugin` 的 JSON 写入步骤                                  |
-| 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>
@@ -405,6 +219,59 @@ module.exports = {
  </Tab>
 </Tabs>
 
+## 插件参考
+
+Intlayer 的构建优化被划分为若干个职责单一的插件。了解它们各自的用途可以防止在配置它们时产生困惑。
+
+### Babel 插件 (`@intlayer/babel`)
+
+这些被直接运用在基于 Webpack 设置的 `babel.config.js` 当中（比如使用了 Babel 的 Next.js、CRA，或是自定义的 Webpack 等）。
+
+下表按所需的流水线顺序列出它们（与它们必须在 `babel.config.js` 中出现的顺序相同）：
+
+| 插件                          | 功能说明                                                                                             |
+| :---------------------------- | :--------------------------------------------------------------------------------------------------- |
+| `intlayerExtractBabelPlugin`  | 扫描 `.content.ts` 文件并把编译好的字典写入 `.intlayer/`                                             |
+| `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 信息。
+
+每一个 Babel 插件都有对应的选项助手（options helper），该助手会在配置加载时读取一遍 `intlayer.config.ts`，并返回预解析的值：
+
+| 选项助手                     | 配套插件                      |
+| :--------------------------- | :---------------------------- |
+| `getExtractPluginOptions()`  | `intlayerExtractBabelPlugin`  |
+| `getPurgePluginOptions()`    | `intlayerPurgeBabelPlugin`    |
+| `getMinifyPluginOptions()`   | `intlayerMinifyBabelPlugin`   |
+| `getOptimizePluginOptions()` | `intlayerOptimizeBabelPlugin` |
+
+### Vite 插件 (`vite-intlayer`)
+
+Vite 用户**不需要直接对它们进行配置**。当你在 `vite.config.ts` 里调用 `withIntlayer()` 时，它们会自动生效。只需要在 `intlayer.config.ts` 中设定 `build.purge` 和 `build.minify`，即可开启相应的功能，且不需要额外的插件注册过程。
+
+| 内部 Vite 插件    | 等效行为                                                                            |
+| :---------------- | :---------------------------------------------------------------------------------- |
+| Usage analyzer    | 等同于 `intlayerPurgeBabelPlugin` 的分析步骤                                        |
+| Dictionary prune  | 等同于 `intlayerPurgeBabelPlugin` 的 JSON 写入步骤                                  |
+| 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 插件只接收生成的表。
+
 ## 配置选项
 
 你可通过在你的 `intlayer.config.ts` 里的 `build` 属性来控制 Intlayer 怎样去优化你的代码包。
@@ -650,3 +517,136 @@ const content = useDictionaryAsync({
 | **附带发生的网络请求**     | 无，无需任何等待直接 0 次                                    | 取决字典请求次数（一次 Key 取出就是一回） |
 | **树抖动（Tree Shaking）** | 按单一组件的级别而做分割                                     | 依组件级别外加依据地区与语种去实施拆分    |
 | **最佳应用与方案环境**     | 普通交互式元件内容或单一界面的轻型程序等                     | 极其充满内容的纯文区块或极其繁多的语系    |
+
+## 分析你的包大小
+
+分析你的打包结果是找出“臃肿”的 JSON 文件和考虑进行代码分割（code-splitting）的最直接方式。这些工具可以生成你应用程序编译代码的树状可视视图（treemap），让你能够清楚地看到究竟是哪些库占据了最多的空间。
+
+<Tabs>
+ <Tab value="vite">
+
+### Vite / Rollup
+
+Vite 在底层使用了 Rollup。插件 `rollup-plugin-visualizer` 能够生成一个交互式 HTML 文件，展示依赖图（graph）中每个模块的体积。
+
+```bash
+npm install -D rollup-plugin-visualizer
+```
+
+```typescript fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import { visualizer } from "rollup-plugin-visualizer";
+
+export default defineConfig({
+  plugins: [
+    visualizer({
+      open: true, // 自动在浏览器中打开报告
+      filename: "stats.html",
+      gzipSize: true,
+      brotliSize: true,
+    }),
+  ],
+});
+```
+
+ </Tab>
+ <Tab value="nextjs (turbopack)">
+
+### Next.js (Turbopack)
+
+对于使用了 App Router 和 Turbopack 的项目，Next.js 提供了一个内置的实验性分析器，它不需要额外的依赖。
+
+```bash packageManager='npm'
+npx next experimental-analyze
+```
+
+```bash packageManager='yarn'
+yarn next experimental-analyze
+```
+
+```bash packageManager='pnpm'
+pnpm next experimental-analyze
+```
+
+```bash packageManager='bun'
+bun next experimental-analyze
+```
+
+ </Tab>
+ <Tab value="nextjs (Webpack)">
+
+### Next.js (Webpack)
+
+如果你在 Next.js 中使用的是默认的 Webpack 打包器，请使用官方的 bundle analyzer。你可以通过在构建期间设置一个环境变量来触发它。
+
+```bash packageManager='npm'
+npm install -D @next/bundle-analyzer
+```
+
+```bash packageManager='yarn'
+yarn add -D @next/bundle-analyzer
+```
+
+```bash packageManager='pnpm'
+pnpm add -D @next/bundle-analyzer
+```
+
+```bash packageManager='bun'
+bun add -d @next/bundle-analyzer
+```
+
+```javascript fileName="next.config.js"
+const withBundleAnalyzer = require("@next/bundle-analyzer")({
+  enabled: process.env.ANALYZE === "true",
+});
+
+module.exports = withBundleAnalyzer({
+  // 你的 Next.js 配置
+});
+```
+
+**用法:**
+
+```bash
+ANALYZE=true npm run build
+```
+
+ </Tab>
+ <Tab value="Webpack (CRA / Angular / etc)">
+
+### 纯 Webpack
+
+针对 Create React App (ejected)、Angular 或是自定义 Webpack 的设置，使用业界标准的 `webpack-bundle-analyzer`。
+
+```bash packageManager='npm'
+npm install -D webpack-bundle-analyzer
+```
+
+```bash packageManager='yarn'
+yarn add -D webpack-bundle-analyzer
+```
+
+```bash packageManager='pnpm'
+pnpm add -D webpack-bundle-analyzer
+```
+
+```bash packageManager='bun'
+bun add -d webpack-bundle-analyzer
+```
+
+```typescript fileName="webpack.config.ts"
+import { BundleAnalyzerPlugin } from "webpack-bundle-analyzer";
+
+export default {
+  plugins: [
+    new BundleAnalyzerPlugin({
+      analyzerMode: "static",
+      reportFilename: "bundle-analyzer.html",
+      openAnalyzer: false,
+    }),
+  ],
+};
+```
+
+ </Tab>
+</Tabs>

package/docs/zh/configuration.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-13
-updatedAt: 2026-08-22
+updatedAt: 2026-08-30
 title: 配置
 description: 了解如何为您的应用程序配置 Intlayer。了解可用于根据您的需求自定义 Intlayer 的各种设置和选项。
 keywords:
@@ -1118,3 +1118,101 @@ Intlayer 支持多个 AI 提供商，以提供最大的灵活性。当前支持
 | 字段      | 说明                         | 类型               |
 | --------- | ---------------------------- | ------------------ |
 | `plugins` | 要包含的 Intlayer 插件列表。 | `IntlayerPlugin[]` |
+
+## 常见问题
+
+<FAQ>
+
+<Question title="intlayer.config.ts 文件应该放在哪里？">
+
+放在项目的根目录下，与 `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)。
+
+如需全自动流程，[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="如何向我的应用添加新语言？">
+
+将新的语言环境添加到 `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` 本身：在保存时它会重新加载配置并重新准备字典，因此添加语言环境或更改路由模式会像修改内容一样被热更新捕获。不过，部分系统可能会对配置进行缓存，若遇到未生效的情况，重启应用是一个稳妥的解决办法。
+
+</Question>
+
+</FAQ>

package/docs/zh/dictionary/content_file.md

@@ -364,15 +364,15 @@ Intlayer 中的字典由 `Dictionary` 类型定义，包含多个控制其行为
 
 **示例：**
 
-```json
+```jsonc
 // 按语言环境字典
 {
   "key": "about-page",
   "locale": "en",
   "content": {
     "title": "关于我们", // 这将成为 'en' 的翻译节点
-    "description": "了解更多关于我们公司的信息"
-  }
+    "description": "了解更多关于我们公司的信息",
+  },
 }
 ```
 
@@ -441,7 +441,7 @@ export default aboutPageMetaContent;
 
 **示例：**
 
-```json
+```jsonc
 // 为所有语言启用
 {
   "autoFill": true

package/docs/zh/dictionary/markdown.md

@@ -51,6 +51,7 @@ Intlayer 支持使用 Markdown 语法定义的富文本内容。这使您可以
 
 <Tabs>
   <Tab label=".content.md" value=".content.md">
+
     从 `8.10.0` 版本开始，您可以在 `.content.md` 文件中直接声明 Markdown 内容。Intlayer 会自动检测并解析 Markdown 内容。
 
     ```md fileName="markdown-file.en.content.md"
@@ -96,6 +97,7 @@ Intlayer 支持使用 Markdown 语法定义的富文本内容。这使您可以
     ```
 
   </Tab>
+
   <Tab label="外部文件" value="external-files">
     使用 `file` 函数直接导入 `.md` 文件。
 
@@ -129,6 +131,7 @@ Intlayer 支持使用 Markdown 语法定义的富文本内容。这使您可以
     ```
 
   </Tab>
+
 </Tabs>
 
 ## 渲染 Markdown
@@ -957,7 +960,21 @@ Markdown 渲染支持 **MDX** — 在您的 Markdown 中直接按名称使用任
   </Tab>
   <Tab label="Angular" value="angular">
 
-> 支持 MDX — 任何在 Markdown 中使用的组件名称（例如 `<MyCustomJSXComponent />`）都会根据 `components` map 进行解析。
+    ```typescript fileName="app.config.ts"
+    import { createIntlayerMarkdownProvider } from "angular-intlayer/markdown";
+
+    export const appConfig: ApplicationConfig = {
+      providers: [
+        createIntlayerMarkdownProvider({
+          components: {
+            h1: { class: "text-2xl font-bold" },
+          },
+        }),
+      ],
+    };
+    ```
+
+    > 支持 MDX — 任何在 Markdown 中使用的组件名称（例如 `<MyCustomJSXComponent />`）都会根据 `components` map 进行解析。
 
 你也可以使用自己的 markdown 渲染器：
 

package/docs/zh/dictionary/plurial.md

@@ -33,11 +33,14 @@ author: aymericzip
 
 与 [`enu`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/enumeration.md) 不同，`enu` 是根据您自己定义的数值范围选择内容的，而 `plural` 将选择权交给 CLDR 规则。这使得它能够扩展到具有复杂复数规则的语言（如俄语、波兰语、阿拉伯语或威尔士语），而无需手动编写求余逻辑。
 
-## 何时使用 `plural` vs `enu`
+## 何时使用 `plural` 与 `enu`
 
-To use plural content inside a React component, retrieve it via the `useIntlayer` hook and call it with a count. The active locale and the count are combined to pick the matching CLDR category.
+| 用例                                            | 辅助函数 |
+| ----------------------------------------------- | -------- |
+| 语言相关的语法复数形式 (one apple / two apples) | `plural` |
+| 自定义数值范围 (`<5`, `>=10`) 或非 CLDR 分类    | `enu`    |
 
-To use plural content in Next.js Client Components, retrieve it via the `useIntlayer` hook and call it with a count. Here's an example:
+如果您仅针对英语（只有 `one` / `other`），两者皆可。对于具有 `few` / `many` / `two` 区分的语言，推荐使用 `plural`。
 
 ## 设置复数内容