@intlayer/docs 8.4.7 → 8.4.9

package/docs/zh/configuration.md

@@ -0,0 +1,958 @@
+---
+createdAt: 2024-08-13
+updatedAt: 2026-03-20
+title: 配置
+description: 了解如何为您的应用程序配置 Intlayer。了解可用于根据您的需求自定义 Intlayer 的各种设置和选项。
+keywords:
+  - 配置
+  - 设置
+  - 自定义
+  - Intlayer
+  - 选项
+slugs:
+  - doc
+  - concept
+  - configuration
+history:
+  - version: 8.4.0
+    date: 2026-03-20
+    changes: "为 'compiler.output' 和 'dictionary.fill' 添加了按区域设置的路径定义支持"
+  - version: 8.3.0
+    date: 2026-03-11
+    changes: "将 'baseDir' 从 'content' 配置移至 'system' 配置"
+  - version: 8.2.0
+    date: 2026-03-09
+    changes: "更新了编译器选项，添加了对 'output' 和 'noMetadata' 的支持"
+  - version: 8.1.7
+    date: 2026-02-25
+    changes: "更新了编译器选项"
+  - version: 8.1.5
+    date: 2026-02-23
+    changes: "添加了 'build-only' 编译器选项和字典前缀"
+  - version: 8.0.6
+    date: 2026-02-12
+    changes: "添加了对 Open Router, Alibaba, Amazon, Google Vertex Bedrock, Fireworks, Groq, Hugging Face 和 Together AI 提供商的支持"
+  - version: 8.0.5
+    date: 2026-02-06
+    changes: "在 AI 配置中添加了 `dataSerialization`"
+  - version: 8.0.0
+    date: 2026-01-24
+    changes: "将 `live` 导入模式重命名为 `fetch`，以更好地描述底层机制。"
+  - version: 8.0.0
+    date: 2026-01-22
+    changes: "将构建配置 `importMode` 移至 `dictionary` 配置。"
+  - version: 8.0.0
+    date: 2026-01-22
+    changes: "在路由配置中添加了 `rewrite` 选项"
+  - version: 8.0.0
+    date: 2026-01-18
+    changes: "将系统配置从内容配置中分离。将内部路径移至 `system` 属性。添加了 `codeDir` 以将内容文件与代码转换分离。"
+  - version: 8.0.0
+    date: 2026-01-18
+    changes: "添加了字典选项 `location` 和 `schema`"
+  - version: 7.5.1
+    date: 2026-01-10
+    changes: "添加了对 JSON5 和 JSONC 文件格式的支持"
+  - version: 7.5.0
+    date: 2025-12-17
+    changes: "添加了 `buildMode` 选项"
+  - version: 7.0.0
+    date: 2025-10-25
+    changes: "添加了 `dictionary` 配置"
+  - version: 7.0.0
+    date: 2025-10-21
+    changes: "将 `middleware` 替换为 `routing` 配置"
+  - version: 7.0.0
+    date: 2025-10-12
+    changes: "添加了 `formatCommand` 选项"
+  - version: 6.2.0
+    date: 2025-10-12
+    changes: "更新了 `excludedPath` 选项"
+  - version: 6.0.2
+    date: 2025-09-23
+    changes: "添加了 `outputFormat` 选项"
+  - version: 6.0.0
+    date: 2025-09-21
+    changes: "删除了 `dictionaryOutput` 和 `i18nextResourcesDir` 字段"
+  - version: 6.0.0
+    date: 2025-09-16
+    changes: "添加了 `live` 导入模式"
+  - version: 6.0.0
+    date: 2025-09-04
+    changes: "将 `hotReload` 字段替换为 `liveSync` 并添加了 `liveSyncPort`、`liveSyncURL` 字段"
+  - version: 5.6.1
+    date: 2025-07-25
+    changes: "将 `activateDynamicImport` 替换为 `importMode` 选项"
+  - version: 5.6.0
+    date: 2025-07-13
+    changes: "将默认 `contentDir` 从 `['src']` 改为 `['.']`"
+  - version: 5.5.11
+    date: 2025-06-29
+    changes: "添加了 `docs` 命令"
+---
+
+# Intlayer 配置文档
+
+## 概述
+
+Intlayer 配置文件允许您自定义插件的各个方面，例如国际化 (i18n)、中间件和内容管理。本文档提供了配置中每个属性的详细说明。
+
+---
+
+## 目录
+
+<TOC/>
+
+---
+
+## 配置文件支持
+
+Intlayer 接受 JSON、JS、MJS 和 TS 配置文件格式：
+
+- `intlayer.config.ts`
+- `intlayer.config.js`
+- `intlayer.config.json`
+- `intlayer.config.json5`
+- `intlayer.config.jsonc`
+- `intlayer.config.cjs`
+- `intlayer.config.mjs`
+- `.intlayerrc`
+
+---
+
+## 配置文件示例
+
+````typescript fileName="intlayer.config.ts" codeFormat="typescript"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { nextjsRewrite } from "intlayer/routing";
+import { z } from "zod";
+
+/**
+ * 包含所有可用选项的 Intlayer 配置文件示例。
+ */
+const config: IntlayerConfig = {
+  /**
+   * 国际化设置配置。
+   */
+  internationalization: {
+    /**
+     * 应用程序中支持的区域设置列表。
+     * 默认值：[Locales.ENGLISH]
+     */
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+
+    /**
+     * 每个字典中必须定义的必需区域设置列表。
+     * 如果为空，则在 `strict` 模式下所有区域设置都是必需的。
+     * 默认值：[]
+     */
+    requiredLocales: [Locales.ENGLISH],
+
+    /**
+     * 国际化内容的严格级别。
+     * - "strict": 如果缺少已声明的区域设置或使用未声明的区域设置，则报错。
+     * - "inclusive": 如果缺少已声明的区域设置，则发出警告。
+     * - "loose": 接受任何现有的区域设置。
+     * 默认值："inclusive"
+     */
+    strictMode: "inclusive",
+
+    /**
+     * 如果请求的区域设置不可用，则用作回退的默认区域设置。
+     * 默认值：Locales.ENGLISH
+     */
+    defaultLocale: Locales.ENGLISH,
+  },
+
+  /**
+   * 控制字典操作和缺失内容行为的设置。
+   */
+  dictionary: {
+    /**
+     * 控制字典的导入方式。
+     * - "static": 构建时静态导入。
+     * - "dynamic": 使用 Suspense 进行动态导入。
+     * - "fetch": 通过 Live Sync API 进行动态获取。
+     * 默认值："static"
+     */
+    importMode: "static",
+
+    /**
+     * 使用 AI 自动填充缺失翻译的策略。
+     * 可以是布尔值或用于保存填充内容的路径模式。
+     * 默认值：true
+     */
+    fill: true,
+
+    /**
+     * 字典文件的物理位置。
+     * - "local": 存储在本地文件系统中。
+     * - "remote": 存储在 Intlayer CMS 中。
+     * - "hybrid": 同时存储在本地和 Intlayer CMS 中。
+     * - "plugin" (或任何自定义字符串): 由插件或自定义源提供。
+     * 默认值："local"
+     */
+    location: "local",
+
+    /**
+     * 是否自动转换内容（例如将 Markdown 转换为 HTML）。
+     * 默认值：false
+     */
+    contentAutoTransformation: false,
+  },
+
+  /**
+   * 路由和中间件配置。
+   */
+  routing: {
+    /**
+     * 区域设置路由策略。
+     * - "prefix-no-default": 除默认语言外所有语言都有前缀（例如 /dashboard, /fr/dashboard）。
+     * - "prefix-all": 所有语言都有前缀（例如 /en/dashboard, /fr/dashboard）。
+     * - "no-prefix": URL 中没有区域设置。
+     * - "search-params": 使用 ?locale=...
+     * 默认值："prefix-no-default"
+     */
+    mode: "prefix-no-default",
+
+    /**
+     * 用户选择的区域设置存储在哪里。
+     * 选项：'cookie', 'localStorage', 'sessionStorage', 'header' 或这些选项的数组。
+     * 默认值：['cookie', 'header']
+     */
+    storage: ["cookie", "header"],
+
+    /**
+     * 应用程序 URL 的基础路径。
+     * 默认值：""
+     */
+    basePath: "",
+
+    /**
+     * 特定区域设置路径的自定义 URL 重写规则。
+     */
+    rewrite: nextjsRewrite({
+      "/[locale]/about": {
+        en: "/[locale]/about",
+        fr: "/[locale]/a-propos",
+      },
+    }),
+  },
+
+  /**
+   * 用于发现和处理内容文件的设置。
+   */
+  content: {
+    /**
+     * 扫描字典的文件扩展名。
+     * 默认值：['.content.ts', '.content.js', '.content.json' 等]
+     */
+    fileExtensions: [".content.ts", ".content.js", ".content.json"],
+
+    /**
+     * .content 文件所在的目录。
+     * 默认值：["."]
+     */
+    contentDir: ["src"],
+
+    /**
+     * 源代码目录。
+     * 用于构建优化和代码转换。
+     * 默认值：["."]
+     */
+    codeDir: ["src"],
+
+    /**
+     * 扫描中排除的模式。
+     * 默认值：['node_modules', '.intlayer' 等]
+     */
+    excludedPath: ["node_modules"],
+
+    /**
+     * 是否在开发过程中监控更改并重新生成字典。
+     * 默认值：开发模式下为 true
+     */
+    watch: true,
+
+    /**
+     * 格式化新创建 / 更新的 .content 文件的命令。
+     */
+    formatCommand: 'npx prettier --write "{{file}}"',
+  },
+
+  /**
+   * 可视化编辑器配置。
+   */
+  editor: {
+    /**
+     * 是否启用可视化编辑器。
+     * 默认值：false
+     */
+    enabled: true,
+
+    /**
+     * 您的应用程序 URL，用于源验证。
+     * 默认值：""
+     */
+    applicationURL: "http://localhost:3000",
+
+    /**
+     * 本地编辑器服务器的端口。
+     * 默认值：8000
+     */
+    port: 8000,
+
+    /**
+     * 编辑器的公共 URL。
+     * 默认值："http://localhost:8000"
+     */
+    editorURL: "http://localhost:8000",
+
+    /**
+     * Intlayer CMS 的 URL。
+     * 默认值："https://app.intlayer.org"
+     */
+    cmsURL: "https://app.intlayer.org",
+
+    /**
+     * 后端 API 服务器的 URL。
+     * 默认值："https://back.intlayer.org"
+     */
+    backendURL: "https://back.intlayer.org",
+
+    /**
+     * 是否启用实时内容同步。
+     * 默认值：false
+     */
+    liveSync: true,
+  },
+
+  /**
+   * 使用 AI 进行翻译和生成的设置。
+   */
+  ai: {
+    /**
+     * 使用的 AI 提供商。
+     * 选项：'openai', 'anthropic', 'mistral', 'deepseek', 'gemini', 'ollama', 'openrouter', 'alibaba', 'fireworks', 'groq', 'huggingface', 'bedrock', 'googlevertex', 'togetherai'
+     * 默认值：'openai'
+     */
+    provider: "openai",
+
+    /**
+     * 所选提供商使用的模型。
+     */
+    model: "gpt-4o",
+
+    /**
+     * 提供商的 API 密钥。
+     */
+    apiKey: process.env.OPENAI_API_KEY,
+
+    /**
+     * 引导 AI 生成翻译时的全局上下文。
+     */
+    applicationContext: "这是一个旅游预订应用程序。",
+
+    /**
+     * AI API 的基础 URL。
+     */
+    baseURL: "http://localhost:3000",
+
+    /**
+     * 数据序列化方式
+     *
+     * 选项：
+     * - "json": 默认，可靠；使用更多 token。
+     * - "toon": 更快，更少 token，但不如 JSON 稳定。
+     *
+     * 默认值："json"
+     */
+    dataSerialization: "json",
+  },
+
+  /**
+   * 构建和优化设置。
+   */
+  build: {
+    /**
+     * 构建执行模式。
+     * - "auto": 应用程序构建期间自动构建。
+     * - "manual": 需要显式构建命令。
+     * 默认值："auto"
+     */
+    mode: "auto",
+
+    /**
+     * 是否通过删除未使用的字典来优化应用程序包。
+     * 默认值：生产环境中为 true
+     */
+    optimize: true,
+
+    /**
+     * 生成的字典文件的输出格式。
+     * 默认值：['cjs', 'esm']
+     */
+    outputFormat: ["cjs", "esm"],
+
+    /**
+     * 是否在构建期间执行 TypeScript 类型检查。
+     * 默认值：false
+     */
+    checkTypes: false,
+  },
+
+  /**
+   * 日志记录器配置。
+   */
+  log: {
+    /**
+     * 日志级别。
+     * - "default": 标准日志记录。
+     * - "verbose": 详细调试日志记录。
+     * - "disabled": 禁用日志记录。
+     * 默认值："default"
+     */
+    mode: "default",
+
+    /**
+     * 日志中所有消息的前缀。
+     * 默认值："[intlayer]"
+     */
+    prefix: "[intlayer]",
+  },
+
+  /**
+   * 系统配置（用于高级用法）
+   */
+  system: {
+    /**
+     * 存储本地化字典的目录。
+     */
+    dictionariesDir: ".intlayer/dictionary",
+
+    /**
+     * 模块扩充 (module augmentation) 的目录。
+     */
+    moduleAugmentationDir: ".intlayer/types",
+
+    /**
+     * 存储未合并字典的目录。
+     */
+    unmergedDictionariesDir: ".intlayer/unmerged_dictionary",
+
+    /**
+     * 存储字典类型的目录。
+     */
+    typesDir: ".intlayer/types",
+
+    /**
+     * 应用程序主文件所在的目录。
+     */
+    mainDir: ".intlayer/main",
+
+    /**
+     * 已编译配置文件的目录。
+     */
+    configDir: ".intlayer/config",
+
+    /**
+     * 缓存文件的目录。
+     */
+    cacheDir: ".intlayer/cache",
+  },
+
+  /**
+   * 编译器配置（用于高级用法）
+   */
+  compiler: {
+    /**
+     * 是否启用编译器。
+     *
+     * - false: 禁用编译器。
+     * - true: 启用编译器。
+     * - "build-only": 开发期间跳过编译器以加快启动速度。
+     *
+     * 默认值：false
+     */
+    enabled: true,
+
+    /**
+     * 确定输出文件路径。替换 `outputDir`。
+     *
+     * - 以 `./` 开头的路径相对于组件目录解析。
+     * - 以 `/` 开头的路径相对于项目基础目录 (`baseDir`) 解析。
+     *
+     * - 路径中存在 `{{locale}}` 变量时，会启用按区域设置生成字典。
+     *
+     * 示例：
+     * ```ts
+     * {
+     *   // 在组件旁边生成多语言 .content.ts 文件
+     *   output: ({ fileName, extension }) => `./${fileName}${extension}`,
+     *
+     *   // output: './{{fileName}}{{extension}}', // 通过模板字符串等效
+     * }
+     * ```
+     *
+     * ```ts
+     * {
+     *   // 在项目基础目录中生成按区域设置的集中式 JSON
+     *   output: ({ key, locale }) => `/locales/${locale}/${key}.content.json`,
+     *
+     *   // output: '/locales/{{locale}}/{{key}}.content.json', // 通过模板字符串等效
+     * }
+     * ```
+     *
+     * 变量列表：
+     *   - `fileName`: 文件名。
+     *   - `key`: 内容键。
+     *   - `locale`: 内容区域设置。
+     *   - `extension`: 文件扩展名。
+     *   - `componentFileName`: 组件文件名。
+     *   - `componentExtension`: 组件文件扩展名。
+     *   - `format`: 字典格式。
+     *   - `componentFormat`: 组件字典格式。
+     *   - `componentDirPath`: 组件目录路径。
+     */
+    output: ({ locale, key }) => `compiler/${locale}/${key}.json`,
+
+    /**
+     * 转换组件后是否保存它们。
+     * 这样，可以运行一次编译器来转换应用程序，然后将其删除。
+     */
+    saveComponents: false,
+
+    /**
+     * 生成的文件中仅保留内容。适用于按区域设置的 i18next 格式或 ICU MessageFormat JSON 输出。
+     */
+    noMetadata: false,
+
+    /**
+     * 字典键前缀
+     */
+    dictionaryKeyPrefix: "", // 为提取的字典键添加可选前缀
+  },
+
+  /**
+   * 用于字典内容验证的自定义架构。
+   */
+  schemas: {
+    "my-schema": z.object({
+      title: z.string(),
+    }),
+  },
+
+  /**
+   * 插件配置。
+   */
+  plugins: [],
+};
+
+export default config;
+````
+
+---
+
+## 配置参考指南
+
+以下是 Intlayer 中可用的各种配置参数的详细说明。
+
+---
+
+### 国际化配置 (Internationalization)
+
+定义国际化相关的设置，包括可用区域设置和默认区域设置。
+
+| 字段              | 说明                                                 | 类型       | 默认值              | 示例                 | 备注                                                                                                                                                                                                                               |
+| ----------------- | ---------------------------------------------------- | ---------- | ------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `locales`         | 应用程序中支持的区域设置列表。                       | `string[]` | `[Locales.ENGLISH]` | `['en', 'fr', 'es']` |                                                                                                                                                                                                                                    |
+| `requiredLocales` | 应用程序中必需的区域设置列表。                       | `string[]` | `[]`                | `[]`                 | • 如果为空，则在 `strict` 模式下所有区域设置都是必需的。<br/>• 请确保必需的区域设置也已在 `locales` 字段中定义。                                                                                                                   |
+| `strictMode`      | 使用 TypeScript 确保国际化内容的强实现。             | `string`   | `'inclusive'`       |                      | • 如果为 `"strict"`: 为 `t` 函数定义每个已声明的区域设置是强制性的——如缺少或未声明则报错。<br/>• 如果为 `"inclusive"`: 对缺少的区域设置发出警告，但允许使用未声明的现有区域设置。<br/>• 如果为 `"loose"`: 接受任何现有的区域设置。 |
+| `defaultLocale`   | 如果请求的区域设置不可用，则用作回退的默认区域设置。 | `string`   | `Locales.ENGLISH`   | `'en'`               | 如果 URL、cookie 或 header 中未指定区域设置，则用于确定区域设置。                                                                                                                                                                  |
+
+---
+
+### 编辑器配置 (Editor)
+
+定义可视化编辑器的设置，包括服务器端口和启用状态。
+
+| 字段                         | 说明                                                                                                                             | 类型                              | 默认值                              | 示例                                                                                            | 备注                                                                                                                                            |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `applicationURL`             | 您的应用程序 URL。                                                                                                               | `string`                          | `undefined`                         | `'http://localhost:3000'` <br/> `'https://example.com'` <br/> `process.env.INTLAYER_EDITOR_URL` | • 用于出于安全原因限制编辑器的源。<br/>• 如果设置为 `'*'`，则可以从任何源访问编辑器。                                                           |
+| `port`                       | 可视化编辑器服务器的端口。                                                                                                       | `number`                          | `8000`                              |                                                                                                 |                                                                                                                                                 |
+| `editorURL`                  | 编辑器服务器的 URL。                                                                                                             | `string`                          | `'http://localhost:8000'`           | `'http://localhost:3000'` <br/> `'https://example.com'` <br/> `process.env.INTLAYER_EDITOR_URL` | • 用于限制可以与应用程序通信的源。<br/>• 如果设置为 `'*'`，则可以从任何源访问。<br/>• 如果端口已更改或编辑器托管在其他域，则需要设置此项。      |
+| `cmsURL`                     | Intlayer CMS 的 URL。                                                                                                            | `string`                          | `'https://app.intlayer.org'`        | `'https://app.intlayer.org'`                                                                    |                                                                                                                                                 |
+| `backendURL`                 | 后端服务器的 URL。                                                                                                               | `string`                          | `https://back.intlayer.org`         | `http://localhost:4000`                                                                         |                                                                                                                                                 |
+| `enabled`                    | 应用程序是否应与可视化编辑器通信。                                                                                               | `boolean`                         | `false`                             | `process.env.NODE_ENV !== 'production'`                                                         | • 如果为 `false`，编辑器将无法与应用程序通信。<br/>• 在某些环境中禁用此项可提高安全性。                                                         |
+| `clientId`                   | 允许 intlayer 包通过 oAuth2 向后端进行身份验证。访问 [intlayer.org/project](https://app.intlayer.org/project) 获取您的访问令牌。 | `string` &#124; <br/> `undefined` | `undefined`                         |                                                                                                 | 应保持私密；使用环境变量。                                                                                                                      |
+| `clientSecret`               | 允许 intlayer 包通过 oAuth2 向后端进行身份验证。访问 [intlayer.org/project](https://app.intlayer.org/project) 获取您的访问令牌。 | `string` &#124; <br/> `undefined` | `undefined`                         |                                                                                                 | 应保持私密；使用环境变量。                                                                                                                      |
+| `dictionaryPriorityStrategy` | 当同时存在本地和远程字典时的字典优先级策略。                                                                                     | `string`                          | `'local_first'`                     | `'distant_first'`                                                                               | • `'distant_first'`: 远程字典优先于本地字典。<br/>• `'local_first'`: 本地字典优先于远程字典。                                                   |
+| `liveSync`                   | 当在 CMS <br/> 可视化编辑器 <br/> 后端服务器中检测到更改时，应用程序服务器是否立即构建内容重新加载。                             | `boolean`                         | `true`                              | `true`                                                                                          | • 添加/更新字典时刷新应用程序页面内容。<br/>• Live Sync 接受来自另一台服务器的内容，这可能会稍微影响性能。<br/>• 建议将两者托管在同一台机器上。 |
+| `liveSyncPort`               | Live Sync 服务器的端口。                                                                                                         | `number`                          | `4000`                              | `4000`                                                                                          |                                                                                                                                                 |
+| `liveSyncURL`                | Live Sync 服务器的 URL。                                                                                                         | `string`                          | `'http://localhost:{liveSyncPort}'` | `'https://example.com'`                                                                         | 默认指向本地主机；可以更改为指向远程实时同步服务器。                                                                                            |
+
+---
+
+### 路由配置 (Routing)
+
+控制路由行为的设置，包括 URL 结构、区域设置存储和中间件管理。
+
+| 字段       | 说明                                                                          | 类型                                                                                                                                                                                                         | 默认值                 | 示例                                                                                                                                                                                    | 备注                                                                                                                                                                                                                             |
+| ---------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mode`     | 区域设置管理的 URL 路由模式。                                                 | `'prefix-no-default'` &#124; <br/> `'prefix-all'` &#124; <br/> `'no-prefix'` &#124; <br/> `'search-params'`                                                                                                  | `'prefix-no-default'`  | `'prefix-no-default'`: `/dashboard` (en) 或 `/fr/dashboard` (fr)。 `'prefix-all'`: `/en/dashboard` 。 `'no-prefix'`: 区域设置以其他方式管理。 `'search-params'`: `/dashboard?locale=fr` | 不影响 cookie 管理或本地存储。                                                                                                                                                                                                   |
+| `storage`  | 客户端区域设置存储的配置。                                                    | `false` &#124; <br/> `'cookie'` &#124; <br/> `'localStorage'` &#124; <br/> `'sessionStorage'` &#124; <br/> `'header'` &#124; <br/> `CookiesAttributes` &#124; <br/> `StorageAttributes` &#124; <br/> `Array` | `['cookie', 'header']` | `'localStorage'` <br/> `[{ type: 'cookie', name: 'custom-locale', secure: true }]`                                                                                                      | 参阅下方的存储参数表。                                                                                                                                                                                                           |
+| `basePath` | 应用程序 URL 的基础路径。                                                     | `string`                                                                                                                                                                                                     | `''`                   | `'/my-app'`                                                                                                                                                                             | 如果您的应用程序位于 `https://example.com/my-app`，则 basePath 为 `'/my-app'`，指向 URL 为 `https://example.com/my-app/en` 。                                                                                                    |
+| `rewrite`  | 自定义 URL 重写规则，用于覆盖特定路径的默认路由模式。支持动态参数 `[param]`。 | `Record<string, StrictModeLocaleMap<string>>`                                                                                                                                                                | `undefined`            | 见下方示例                                                                                                                                                                              | • 重写规则优先级高于 `mode`。<br/>• 与 Next.js 和 Vite 配合。 <br/>• `getLocalizedUrl()` 自动应用适当的规则。<br/>• 见 [自定义 URL 重写](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/custom_url_rewrites.md)。 |
+
+**`rewrite` 示例**:
+
+```typescript
+routing: {
+  mode: "prefix-no-default", // 回退策略
+  rewrite: nextjsRewrite({
+    "/about": {
+      en: "/about",
+      fr: "/a-propos",
+    },
+    "/product/[slug]": {
+      en: "/product/[slug]",
+      fr: "/produit/[slug]",
+    },
+    "/blog/[category]/[id]": {
+      en: "/blog/[category]/[id]",
+      fr: "/journal/[category]/[id]",
+    },
+  }),
+}
+```
+
+#### 存储参数 (Storage)
+
+| 值                 | 备注                                                                                                                                                         | 说明                                                 |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------- |
+| `'cookie'`         | • 确保适当的用户同意以符合 GDPR 要求。<br/>• 通过 `CookiesAttributes` (`{ type: 'cookie', name: 'custom-locale', secure: true, httpOnly: false }`) 可配置。  | 将区域设置存储在 cookie 中——客户端和服务器均可访问。 |
+| `'localStorage'`   | • 除非明确删除，否则不会过期。<br/>• Intlayer Proxy 无法访问它。<br/>• 通过 `StorageAttributes` (`{ type: 'localStorage', name: 'custom-locale' }`) 可配置。 | 将区域设置存储在浏览器中，永不过期——仅限客户端。     |
+| `'sessionStorage'` | • 关闭标签页/窗口时删除。<br/>• Intlayer Proxy 无法访问它。<br/>• 通过 `StorageAttributes` (`{ type: 'sessionStorage', name: 'custom-locale' }`) 可配置。    | 在页面会话期间存储区域设置——仅限客户端。             |
+| `'header'`         | • 对于 API 调用很有用。<br/>• 客户端无法访问它。<br/>• 通过 `StorageAttributes` (`{ type: 'header', name: 'custom-locale' }`) 可配置。                       | 通过 HTTP header 存储或传递区域设置——仅限服务器。    |
+
+#### Cookie 属性 (Cookies Attributes)
+
+在 cookie 中使用存储时，可以设置额外属性：
+
+| 字段       | 说明                                     | 类型                                                  |
+| ---------- | ---------------------------------------- | ----------------------------------------------------- |
+| `name`     | Cookie 名称。默认值：`'INTLAYER_LOCALE'` | `string`                                              |
+| `domain`   | Cookie 域。默认值：`undefined`           | `string`                                              |
+| `path`     | Cookie 路径。默认值：`undefined`         | `string`                                              |
+| `secure`   | 需要 HTTPS。默认值：`undefined`          | `boolean`                                             |
+| `httpOnly` | HTTP-only 标志。默认值：`undefined`      | `boolean`                                             |
+| `sameSite` | SameSite 策略。                          | `'strict'` &#124; <br/> `'lax'` &#124; <br/> `'none'` |
+| `expires`  | 过期日期或天数。默认值：`undefined`      | `Date` &#124; <br/> `number`                          |
+
+#### 存储属性 (Storage Attributes)
+
+使用 localStorage 或 sessionStorage 时：
+
+| 字段   | 说明                                      | 类型                                             |
+| ------ | ----------------------------------------- | ------------------------------------------------ |
+| `type` | 存储类型。                                | `'localStorage'` &#124; <br/> `'sessionStorage'` |
+| `name` | 存储中的键名。默认值：`'INTLAYER_LOCALE'` | `string`                                         |
+
+#### 配置示例
+
+以下是新 v7 路由结构的一些常见配置示例：
+
+**基本配置（默认值）**:
+
+```typescript
+import { Locales, type IntlayerConfig } from "intlayer";
+// intlayer.config.ts
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: ["en", "fr", "es"],
+    defaultLocale: "en",
+  },
+  routing: {
+    mode: "prefix-no-default",
+    storage: "localStorage",
+    basePath: "",
+  },
+};
+
+export default config;
+```
+
+**符合 GDPR 的配置**:
+
+```typescript
+import { Locales, type IntlayerConfig } from "intlayer";
+// intlayer.config.ts
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: ["en", "fr", "es"],
+    defaultLocale: "en",
+  },
+  routing: {
+    mode: "prefix-no-default",
+    storage: [
+      {
+        type: "localStorage",
+        name: "user-locale",
+      },
+      {
+        type: "cookie",
+        name: "user-locale",
+        secure: true,
+        sameSite: "strict",
+        httpOnly: false,
+      },
+    ],
+    basePath: "",
+  },
+};
+
+export default config;
+```
+
+**搜索参数 (Search Params) 模式**:
+
+```typescript
+import { Locales, type IntlayerConfig } from "intlayer";
+// intlayer.config.ts
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: ["en", "fr", "es"],
+    defaultLocale: "en",
+  },
+  routing: {
+    mode: "search-params",
+    storage: "localStorage",
+    basePath: "",
+  },
+};
+
+export default config;
+```
+
+**具有自定义存储的无前缀模式**:
+
+```typescript
+import { Locales, type IntlayerConfig } from "intlayer";
+// intlayer.config.ts
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: ["en", "fr", "es"],
+    defaultLocale: "en",
+  },
+  routing: {
+    mode: "no-prefix",
+    storage: {
+      type: "sessionStorage",
+      name: "app-locale",
+    },
+    basePath: "/my-app",
+  },
+};
+
+export default config;
+```
+
+**具有动态路径的自定义 URL 重写**:
+
+```typescript
+// intlayer.config.ts
+import { nextjsRewrite } from "intlayer/routing";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: ["en", "fr"],
+    defaultLocale: "en",
+  },
+  routing: {
+    mode: "prefix-no-default", // 未重写路径的回退
+    storage: "cookie",
+    rewrite: nextjsRewrite({
+      "/about": {
+        en: "/about",
+        fr: "/a-propos",
+      },
+      "/product/[slug]": {
+        en: "/product/[slug]",
+        fr: "/produit/[slug]",
+      },
+      "/blog/[category]/[id]": {
+        en: "/blog/[category]/[id]",
+        fr: "/journal/[category]/[id]",
+      },
+    }),
+  },
+};
+
+export default config;
+```
+
+---
+
+### 内容配置 (Content)
+
+有关应用程序中如何管理内容、目录名称、文件扩展名以及派生配置的设置。
+
+| 字段             | 说明                                                         | 类型       | 默认值                                                                                                                                                                    | 示例                                                                                                                                                                                  | 备注                                                                                                      |
+| ---------------- | ------------------------------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `watch`          | 指示 Intlayer 是否应监控内容声明文件中的更改以重新生成字典。 | `boolean`  | `true`                                                                                                                                                                    |                                                                                                                                                                                       |                                                                                                           |
+| `fileExtensions` | 编译字典期间扫描的文件扩展名。                               | `string[]` | `['.content.ts', '.content.js', '.content.cjs', '.content.mjs', '.content.json', '.content.json5', '.content.jsonc', '.content.tsx', '.content.jsx']`                     | `['.data.ts', '.data.js', '.data.json']`                                                                                                                                              | 可帮助避免自定义冲突。                                                                                    |
+| `contentDir`     | 内容定义文件 (`.content.*`) 所在目录的路径。                 | `string[]` | `['.']`                                                                                                                                                                   | `['src', '../../ui-library', require.resolve("@my-package/content"), '@my-package/content']`                                                                                          | 用于内容文件跟踪和字典重新生成。                                                                          |
+| `codeDir`        | 代码所在的路径目录，相对于基础目录。                         | `string[]` | `['.']`                                                                                                                                                                   | `['src', '../../ui-library']`                                                                                                                                                         | • 用于跟踪代码文件转换（删除不必要的部分、优化）。<br/>• 与 `contentDir` 分离可提高性能。                 |
+| `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）。 |
+
+---
+
+### 字典配置 (Dictionary)
+
+控制字典操作的参数，包括自动填充行为和内容生成。
+
+| 字段                        | 说明                                                                                         | 类型                                                                                                            | 默认值      | 示例                                                                                        | 备注                                                                                                                                                                                                                                                                                                        |
+| --------------------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `fill`                      | 控制自动填充 (AI 翻译) 输出文件的生成方式。                                                  | `boolean` &#124; <br/> `FilePathPattern` &#124; <br/> `Partial<Record<Locale, boolean &#124; FilePathPattern>>` | `true`      | `{ en: '/locales/en/{{key}}.json', fr: ({ key }) => '/locales/fr/${key}.json', es: false }` | • `true`: 默认路径（与源文件相同）。<br/>• `false`: 禁用。<br/>• 模板字符串/函数启用按区域设置生成。<br/>• 按区域设置对象：每个区域设置对应其自己的模板；`false` 排除该区域设置。<br/>• 包含 `{{locale}}` 启用按区域设置生成。<br/>• 字典级别的 `fill` 始终优先于此全局设置。                               |
+| `description`               | 帮助编辑器和 CMS 理解字典的目的。也用作 AI 生成翻译的上下文。                                | `string`                                                                                                        | `undefined` | `'User profile section'`                                                                    |                                                                                                                                                                                                                                                                                                             |
+| `locale`                    | 将字典转换为特定区域设置格式。每个声明的字段变为一个翻译节点。如果缺少，则字典被视为多语言。 | `LocalesValues`                                                                                                 | `undefined` | `'en'`                                                                                      | 如果字典是针对特定区域设置而非包含多种翻译，请使用此项。                                                                                                                                                                                                                                                    |
+| `contentAutoTransformation` | 是否将内容字符串自动转换为类型化的节点（Markdown、HTML 或插入内容）。                        | `boolean` &#124; <br/> `{ markdown?: boolean; html?: boolean; insertion?: boolean }`                            | `false`     | `true`                                                                                      | • Markdown : `### Title` → `md('### Title')` 。<br/>• HTML : `<div>Title</div>` → `html('<div>Title</div>')` 。<br/>• 插入内容 : `Hello {{name}}` → `insert('Hello {{name}}')` 。                                                                                                                           |
+| `location`                  | 指出字典文件存储在哪里以及如何与 CMS 同步。                                                  | `'local'` &#124; <br/> `'remote'` &#124; <br/> `'hybrid'` &#124; <br/> `'plugin'` &#124; <br/> `string`         | `'local'`   | `'hybrid'`                                                                                  | • `'local'`: 仅本地管理。<br/>• `'remote'`: 仅远程管理 (CMS)。<br/>• `'hybrid'`: 本地和远程管理。<br/>• `'plugin'` 或自定义字符串：通过插件或自定义源管理。                                                                                                                                                 |
+| `importMode`                | 控制字典的导入方式。                                                                         | `'static'` &#124; <br/> `'dynamic'` &#124; <br/> `'fetch'`                                                      | `'static'`  | `'dynamic'`                                                                                 | • `'static'`: 静态导入。<br/>• `'dynamic'`: 通过 Suspense 动态导入。<br/>• `'fetch'`: 通过 Live Sync API 获取；失败后回退到 `'dynamic'`。<br/>• 需要 `@intlayer/babel` 和 `@intlayer/swc` 插件。<br/>• 键必须静态声明。<br/>• 如果 `optimize` 关闭则忽略。<br/>• 不影响 `getIntlayer`, `getDictionary` 等。 |
+| `priority`                  | 字典优先级。在解决字典之间的冲突时，较高的值比较低的值具有优先级。                           | `number`                                                                                                        | `undefined` | `1`                                                                                         |                                                                                                                                                                                                                                                                                                             |
+| `live`                      | 已弃用 — 请使用 `importMode: 'fetch'`。曾指示是否应通过 Live Sync API 动态获取字典内容。     | `boolean`                                                                                                       | `undefined` |                                                                                             | 在 v8.0.0 中重命名为 `importMode: 'fetch'`。                                                                                                                                                                                                                                                                |
+| `schema`                    | 由 Intlayer 自动生成，用于 JSON 架构验证。                                                   | `'https://intlayer.org/schema.json'`                                                                            | 自动生成    |                                                                                             | 请勿手动编辑。                                                                                                                                                                                                                                                                                              |
+| `title`                     | 帮助在编辑器和 CMS 中识别字典。                                                              | `string`                                                                                                        | `undefined` | `'User Profile'`                                                                            |                                                                                                                                                                                                                                                                                                             |
+| `tags`                      | 对字典进行分类并为编辑器和 AI 提供上下文或指令。                                             | `string[]`                                                                                                      | `undefined` | `['user', 'profile']`                                                                       |                                                                                                                                                                                                                                                                                                             |
+| `version`                   | 远程字典版本；帮助跟踪当前正在使用的版本。                                                   | `string`                                                                                                        | `undefined` | `'1.0.0'`                                                                                   | • 在 CMS 中管理。<br/>• 请勿本地编辑。                                                                                                                                                                                                                                                                      |
+
+**`fill` 示例**:
+
+```ts
+dictionary: {
+  fill: {
+    en: "/locales/en/{{key}}.content.json",
+    fr: ({ key }) => `/locales/fr/${key}.content.json`,
+    es: false,
+  },
+};
+```
+
+---
+
+### 日志记录器配置 (Log)
+
+自定义 Intlayer 日志输出的参数。
+
+| 字段     | 说明                   | 类型                                                           | 默认值          | 示例            | 备注                                                                       |
+| -------- | ---------------------- | -------------------------------------------------------------- | --------------- | --------------- | -------------------------------------------------------------------------- |
+| `mode`   | 指示日志记录器模式。   | `'default'` &#124; <br/> `'verbose'` &#124; <br/> `'disabled'` | `'default'`     | `'verbose'`     | • `'verbose'`: 记录更多调试信息。<br/>• `'disabled'`: 完全禁用日志记录器。 |
+| `prefix` | 日志中所有消息的前缀。 | `string`                                                       | `'[intlayer] '` | `'[我的前缀] '` |                                                                            |
+
+---
+
+### AI 配置 (AI)
+
+控制 Intlayer AI 功能的设置，包括提供商、模型和 API 密钥。
+
+如果您在 [Intlayer Dashboard](https://app.intlayer.org/project) 中注册访问密钥，则此配置是可选的。Intlayer 将根据您的需求自动为您管理最具成本效益且最高效的 AI 解决方案。使用默认选项可确保获得最佳的长期支持，因为 Intlayer 会不断更新以使用最新模型。
+
+如果您更喜欢使用自己的 API 密钥或特定模型，则可以定义自己的 AI 配置。
+此 AI 配置将在您的 Intlayer 环境中全局使用。CLI 命令（如 `fill`）将默认使用这些设置，同样 SDK、可视化编辑器和 CMS 也是如此。您可以通过命令参数在特定情况下覆盖这些默认值。
+
+Intlayer 支持多个 AI 提供商，以提供最大的灵活性。当前支持的提供商有：
+
+- **OpenAI** (默认)
+- **Anthropic Claude**
+- **Mistral AI**
+- **DeepSeek**
+- **Google Gemini**
+- **Google AI Studio**
+- **Google Vertex**
+- **Meta Llama**
+- **Ollama**
+- **OpenRouter**
+- **Alibaba Cloud**
+- **Fireworks**
+- **Hugging Face**
+- **Groq**
+- **Amazon Bedrock**
+- **Together.ai**
+
+| 字段                 | 说明                                                                                 | 类型                                                                                                                                                                                                                                                                                                                                                                                           | 默认值      | 示例                                                          | 备注                                                                                                                                              |
+| -------------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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'` | `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 等）传递给模型。 |
+
+---
+
+### 构建配置 (Build)
+
+控制 Intlayer 如何优化和编译应用程序国际化的参数。
+
+构建选项应用于 `@intlayer/babel` 和 `@intlayer/swc` 插件。
+
+> 在开发模式下，Intlayer 使用字典的静态导入以便于开发过程。
+
+> 在优化期间，Intlayer 将替换字典调用以优化分块 (chunking)，使生成的包仅导入实际使用的字典。
+
+| 字段              | 说明                                           | 类型                             | 默认值                                                                                                                                                                            | 示例                                                                          | 备注                                                                                                                                                                                                                              |
+| ----------------- | ---------------------------------------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mode`            | 控制构建模式。                                 | `'auto'` &#124; <br/> `'manual'` | `'auto'`                                                                                                                                                                          | `'manual'`                                                                    | • `'auto'`: 构建在应用程序构建期间自动启动。<br/>• `'manual'`: 仅通过显式构建命令触发。<br/>• 可用于防止字典构建（例如避免在 Node.js 环境中运行）。                                                                               |
+| `optimize`        | 控制是否应执行构建优化。                       | `boolean`                        | `undefined`                                                                                                                                                                       | `process.env.NODE_ENV === 'production'`                                       | • 如果未定义，则在框架构建 (Vite/Next.js) 期间启动优化。<br/>• `true` 在开发模式下也会强制执行优化。<br/>• `false` 将其禁用。<br/>• 如果启用，则会替换字典调用以优化分块。<br/>• 需要 `@intlayer/babel` 和 `@intlayer/swc` 插件。 |
+| `checkTypes`      | 指示构建是否应检查 TypeScript 类型并记录错误。 | `boolean`                        | `false`                                                                                                                                                                           |                                                                               | 可能会减慢构建过程。                                                                                                                                                                                                              |
+| `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 模式。                                                                                                                              |
+
+---
+
+### 系统配置 (System)
+
+这些设置面向高级用户和 Intlayer 内部配置。
+
+| 字段                      | 说明                        | 类型     | 默认值                            | 示例 | 备注 |
+| ------------------------- | --------------------------- | -------- | --------------------------------- | ---- | ---- |
+| `dictionariesDir`         | 已编译字典的目录。          | `string` | `'.intlayer/dictionary'`          |      |      |
+| `moduleAugmentationDir`   | TypeScript 模块扩充的目录。 | `string` | `'.intlayer/types'`               |      |      |
+| `unmergedDictionariesDir` | 存储未合并字典的目录。      | `string` | `'.intlayer/unmerged_dictionary'` |      |      |
+| `typesDir`                | 生成类型的目录。            | `string` | `'.intlayer/types'`               |      |      |
+| `mainDir`                 | Intlayer 主文件的目录。     | `string` | `'.intlayer/main'`                |      |      |
+| `configDir`               | 已编译配置文件的目录。      | `string` | `'.intlayer/config'`              |      |      |
+| `cacheDir`                | 缓存文件的目录。            | `string` | `'.intlayer/cache'`               |      |      |
+
+---
+
+### 编译器配置 (Compiler)
+
+控制 Intlayer 编译器的设置，该编译器直接从组件中收集字典。
+
+| 字段                  | 说明                                                                                                                                                                                                                                                                          | 类型                                                                                                            | 默认值      | 示例                                                                                                                                                     | 备注                                                                                                                                       |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `enabled`             | 指示编译器是否应处于活动状态以收集字典。                                                                                                                                                                                                                                      | `boolean` &#124; <br/> `'build-only'`                                                                           | `true`      | `'build-only'`                                                                                                                                           | `'build-only'` 在开发过程中跳过编译器以实现更快构建；仅在构建命令期间运行。                                                                |
+| `dictionaryKeyPrefix` | 收集的字典键的前缀。                                                                                                                                                                                                                                                          | `string`                                                                                                        | `''`        | `'my-prefix-'`                                                                                                                                           | 加在生成的键（基于文件名）之前以避免冲突。                                                                                                 |
+| `saveComponents`      | 转换组件后是否应将其保存。                                                                                                                                                                                                                                                    | `boolean`                                                                                                       | `false`     |                                                                                                                                                          | • 如果为 `true`，原始文件将被转换后的版本覆盖。<br/>• 允许运行一次编译器后将其删除。                                                       |
+| `output`              | 确定输出文件路径。替换 `outputDir`。支持模板变量：`{{fileName}}`, <br/> `{{key}}`, <br/> `{{locale}}`, <br/> `{{extension}}`, <br/> `{{componentFileName}}`, <br/> `{{componentExtension}}`, <br/> `{{format}}`, <br/> `{{componentFormat}}`, <br/> `{{componentDirPath}}` 。 | `boolean` &#124; <br/> `FilePathPattern` &#124; <br/> `Partial<Record<Locale, boolean &#124; FilePathPattern>>` | `undefined` | `'./{{fileName}}{{extension}}'` <br/> `'/locales/{{locale}}/{{key}}.json'` <br/> `{ en: ({ key }) => './locales/en/${key}.json', fr: '...', es: false }` | • `./` 路径相对于组件目录解析。<br/>• `/` 路径相对于项目基础。 <br/>• `{{locale}}` 启用按区域设置生成。<br/>• 支持按区域设置的对象表示法。 |
+| `noMetadata`          | 如果为 `true`，编译器会从输出中删除字典元数据（键、内容包装器）。                                                                                                                                                                                                             | `boolean`                                                                                                       | `false`     | `false` → `{"key":"my-key","content":{"key":"value"}}` <br/> `true` → `{"key":"value"}`                                                                  | • 对于 i18next 格式或 ICU MessageFormat JSON 输出非常有用。<br/>• 与 `loadJSON` 插件很好地配合。                                           |
+| `dictionaryKeyPrefix` | 字典键前缀                                                                                                                                                                                                                                                                    | `string`                                                                                                        | `''`        |                                                                                                                                                          | 为提取的字典键添加可选前缀                                                                                                                 |
+
+---
+
+### 自定义架构 (Custom Schemas)
+
+| 字段      | 说明                                    | 类型                        |
+| --------- | --------------------------------------- | --------------------------- |
+| `schemas` | 允许您定义 Zod 架构来验证您的字典结构。 | `Record<string, ZodSchema>` |
+
+---
+
+### 插件 (Plugins)
+
+| 字段      | 说明                         | 类型               |
+| --------- | ---------------------------- | ------------------ |
+| `plugins` | 要包含的 Intlayer 插件列表。 | `IntlayerPlugin[]` |