@intlayer/docs 8.4.5 → 8.4.7

package/docs/zh/configuration.md

@@ -1,1115 +0,0 @@
----
-createdAt: 2024-08-13
-updatedAt: 2026-03-12
-title: 配置
-description: 了解如何为您的应用程序配置 Intlayer。了解各种设置和选项，以根据您的需求自定义 Intlayer。
-keywords:
-  - 配置
-  - 设置
-  - 自定义
-  - Intlayer
-  - 选项
-slugs:
-  - doc
-  - concept
-  - configuration
-history:
-  - version: 8.3.0
-    date: 2026-03-11
-    changes: 将 'baseDir' 从 'content' 配置移动到 'system' 配置
-  - version: 8.2.0
-    date: 2026-03-10
-    changes: 更新编译器选项，增加 'output' 和 'noMetadata' 支持
-  - version: 8.1.7
-    date: 2026-02-25
-    changes: 更新编译器选项
-  - 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-22
-    changes: 将 importMode 构建配置移动到字典配置。
-  - 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: 6.0.0
-    date: 2025-09-16
-    changes: 添加 `live` 导入模式
-  - version: 6.0.0
-    date: 2025-09-16
-    changes: 添加 `live` 导入模式
-  - version: 6.0.0
-    date: 2025-09-04
-    changes: 用 `liveSync` 替换 `hotReload` 字段，并新增 `liveSyncPort` 和 `liveSyncURL` 字段
-  - version: 5.6.1
-    date: 2025-07-25
-    changes: 用 `importMode` 选项替换 `activateDynamicImport`
-  - version: 5.6.0
-    date: 2025-07-13
-    changes: 默认的 contentDir 从 `['src']` 改为 `['.']`
-  - version: 5.5.11
-    date: 2025-06-29
-    changes: 添加 `docs` 命令
----
-
-# Intlayer 配置文档
-
-## 概述
-
-Intlayer 配置文件允许自定义插件的各个方面，例如国际化、中间件和内容处理。本文档详细描述了配置中的每个属性。
-
----
-
-## 目录
-
-<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";
-
-/**
- * Example Intlayer configuration file showing all available options.
- */
-const config: IntlayerConfig = {
-  /**
-   * Configuration for internationalization settings.
-   */
-  internationalization: {
-    /**
-     * List of supported locales in the application.
-     * Default: [Locales.ENGLISH]
-     */
-    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
-
-    /**
-     * List of required locales that must be defined in every dictionary.
-     * If empty, all locales are required in `strict` mode.
-     * Default: []
-     */
-    requiredLocales: [Locales.ENGLISH],
-
-    /**
-     * Strictness level for internationalized content.
-     * - "strict": Errors if any declared locale is missing or undeclared.
-     * - "inclusive": Warnings if a declared locale is missing.
-     * - "loose": Accepts any existing locale.
-     * Default: "inclusive"
-     */
-    strictMode: "inclusive",
-
-    /**
-     * Default locale used as a fallback if the requested locale is not found.
-     * Default: Locales.ENGLISH
-     */
-    defaultLocale: Locales.ENGLISH,
-  },
-
-  /**
-   * Settings that control dictionary operations and fallback behavior.
-   */
-  dictionary: {
-    /**
-     * Controls how dictionaries are imported.
-     * - "static": Statically imported at build time.
-     * - "dynamic": Dynamically imported using Suspense.
-     * - "fetch": Fetched dynamically via the live sync API.
-     * Default: "static"
-     */
-    importMode: "static",
-
-    /**
-     * Strategy for auto-filling missing translations using AI.
-     * Can be a boolean or a path pattern to store filled content.
-     * Default: true
-     */
-    fill: true,
-
-    /**
-     * Physical location of the dictionary files.
-     * - "local": Stored in the local filesystem.
-     * - "remote": Stored in the Intlayer CMS.
-     * - "hybrid": Stored in the local filesystem and the Intlayer CMS.
-     * - "plugin" (or any custom string): Provided by a plugin or a custom source.
-     * Default: "local"
-     */
-    location: "local",
-
-    /**
-     * Whether to automatically transform content (e.g., Markdown to HTML).
-     * Default: false
-     */
-    contentAutoTransformation: false,
-  },
-
-  /**
-   * Routing and middleware configuration.
-   */
-  routing: {
-    /**
-     * Locale routing strategy.
-     * - "prefix-no-default": Prefix all except the default locale (e.g., /dashboard, /fr/dashboard).
-     * - "prefix-all": Prefix all locales (e.g., /en/dashboard, /fr/dashboard).
-     * - "no-prefix": No locale in the URL.
-     * - "search-params": Use ?locale=...
-     * Default: "prefix-no-default"
-     */
-    mode: "prefix-no-default",
-
-    /**
-     * Where to store the user's selected locale.
-     * Options: 'cookie', 'localStorage', 'sessionStorage', 'header', or an array of these.
-     * Default: ['cookie', 'header']
-     */
-    storage: ["cookie", "header"],
-
-    /**
-     * Base path for the application URLs.
-     * Default: ""
-     */
-    basePath: "",
-
-    /**
-     * Custom URL rewriting rules for locale-specific paths.
-     */
-    rewrite: nextjsRewrite({
-      "/[locale]/about": {
-        en: "/[locale]/about",
-        fr: "/[locale]/a-propos",
-      },
-    }),
-  },
-
-  /**
-   * Settings for finding and processing content files.
-   */
-  content: {
-    /**
-     * File extensions to scan for dictionaries.
-     * Default: ['.content.ts', '.content.js', '.content.json', etc.]
-     */
-    fileExtensions: [".content.ts", ".content.js", ".content.json"],
-
-    /**
-     * Directories where .content files are located.
-     * Default: ["."]
-     */
-    contentDir: ["src"],
-
-    /**
-     * Directories where source code is located.
-     * Used for build optimization and code transformation.
-     * Default: ["."]
-     */
-    codeDir: ["src"],
-
-    /**
-     * Patterns to exclude from scanning.
-     * Default: ['node_modules', '.intlayer', etc.]
-     */
-    excludedPath: ["node_modules"],
-
-    /**
-     * Whether to watch for changes and rebuild dictionaries in development.
-     * Default: true in development
-     */
-    watch: true,
-
-    /**
-     * Command to format newly created / updated .content files.
-     */
-    formatCommand: 'npx prettier --write "{{file}}"',
-  },
-
-  /**
-   * Visual Editor configuration.
-   */
-  editor: {
-    /**
-     * Whether the visual editor is enabled.
-     * Default: false
-     */
-    enabled: true,
-
-    /**
-     * URL of your application for origin validation.
-     * Default: ""
-     */
-    applicationURL: "http://localhost:3000",
-
-    /**
-     * Port for the local editor server.
-     * Default: 8000
-     */
-    port: 8000,
-
-    /**
-     * Public URL for the editor.
-     * Default: "http://localhost:8000"
-     */
-    editorURL: "http://localhost:8000",
-
-    /**
-     * Intlayer CMS URL.
-     * Default: "https://app.intlayer.org"
-     */
-    cmsURL: "https://app.intlayer.org",
-
-    /**
-     * Backend API URL.
-     * Default: "https://back.intlayer.org"
-     */
-    backendURL: "https://back.intlayer.org",
-
-    /**
-     * Whether to enable real-time content synchronization.
-     * Default: false
-     */
-    liveSync: true,
-  },
-
-  /**
-   * AI-powered translation and generation settings.
-   */
-  ai: {
-    /**
-     * AI provider to use.
-     * Options: 'openai', 'anthropic', 'mistral', 'deepseek', 'gemini', 'ollama', 'openrouter', 'alibaba', 'fireworks', 'groq', 'huggingface', 'bedrock', 'googlevertex', 'togetherai'
-     * Default: 'openai'
-     */
-    provider: "openai",
-
-    /**
-     * Model to use from the selected provider.
-     */
-    model: "gpt-4o",
-
-    /**
-     * Provider API key.
-     */
-    apiKey: process.env.OPENAI_API_KEY,
-
-    /**
-     * Global context to guide the AI in generating translations.
-     */
-    applicationContext: "This is a travel booking application.",
-
-    /**
-     * Base URL for the AI API.
-     */
-    baseURL: "http://localhost:3000",
-
-    /**
-     * 数据序列化
-     *
-     * 选项：
-     * - "json": 标准、可靠；使用更多 token。
-     * - "toon": 生成更少的 token，但不如 JSON 稳定。
-     *
-     * 默认值: "json"
-     */
-    dataSerialization: "json",
-  },
-
-  /**
-   * Build and optimization settings.
-   */
-  build: {
-    /**
-     * Build execution mode.
-     * - "auto": Automatic build during app build.
-     * - "manual": Requires explicit build command.
-     * Default: "auto"
-     */
-    mode: "auto",
-
-    /**
-     * Whether to optimize the final bundle by pruning unused dictionaries.
-     * Default: true in production
-     */
-    optimize: true,
-
-    /**
-     * Output format for generated dictionary files.
-     * Default: ['esm', 'cjs']
-     */
-    outputFormat: ["esm"],
-
-    /**
-     * Indicates if the build should check TypeScript types.
-     * Default: false
-     */
-    checkTypes: false,
-  },
-
-  /**
-   * Logger configuration.
-   */
-  log: {
-    /**
-     * Logging level.
-     * - "default": Standard logging.
-     * - "verbose": Detailed debug logging.
-     * - "disabled": No logging.
-     * Default: "default"
-     */
-    mode: "default",
-
-    /**
-     * Prefix for all log messages.
-     * Default: "[intlayer]"
-     */
-    prefix: "[intlayer]",
-  },
-
-  /**
-   * System configuration (Advanced use cases)
-   */
-  system: {
-    /**
-     * Directory for storing localization dictionaries.
-     */
-    dictionariesDir: ".intlayer/dictionary",
-
-    /**
-     * Directory for module augmentation.
-     */
-    moduleAugmentationDir: ".intlayer/types",
-
-    /**
-     * Directory for storing unmerged dictionaries.
-     */
-    unmergedDictionariesDir: ".intlayer/unmerged_dictionary",
-
-    /**
-     * Directory for storing dictionary types.
-     */
-    typesDir: ".intlayer/types",
-
-    /**
-     * Directory where main application files are stored.
-     */
-    mainDir: ".intlayer/main",
-
-    /**
-     * Directory where the configuration files are stored.
-     */
-    configDir: ".intlayer/config",
-
-    /**
-     * Directory where the cache files are stored.
-     */
-    cacheDir: ".intlayer/cache",
-  },
-
-  /**
-   * Compiler configuration (Advanced use cases)
-   */
-  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: "", // 为所有字典键设置前缀
-  },
-
-  /**
-   * Custom schemas to validate the dictionaries content.
-   */
-  schemas: {
-    "my-schema": z.object({
-      title: z.string(),
-    }),
-  },
-
-  /**
-   * Plugins configuration.
-   */
-  plugins: [],
-};
-
-export default config;
-````
-
-## 配置参考
-
-以下部分描述了 Intlayer 可用的各种配置设置。
-
----
-
-### 国际化配置
-
-定义与国际化相关的设置，包括可用的语言环境和应用的默认语言环境。
-
-#### 属性
-
-- **locales**：
-  - _类型_：`string[]`
-  - _默认值_：`['en']`
-  - _描述_：应用中支持的语言环境列表。
-  - _示例_：`['en', 'fr', 'es']`
-
-- **requiredLocales**：
-  - _类型_：`string[]`
-  - _默认值_：`[]`
-  - _描述_：应用中必需的语言环境列表。
-  - _示例_：`[]`
-  - _注意_：如果为空，则在 `strict` 模式下所有语言环境都是必需的。
-  - _注意_：确保必需的语言环境也在 `locales` 字段中定义。
-- **strictMode**：
-  - _类型_：`string`
-  - _默认值_：`inclusive`
-  - _描述_：确保使用 TypeScript 强化国际化内容的实现。
-  - _注意_：如果设置为 "strict"，翻译函数 `t` 将要求每个声明的语言环境都必须定义。如果缺少某个语言环境，或者配置中未声明某个语言环境，将抛出错误。
-  - _注意_：如果设置为 "inclusive"，翻译函数 `t` 将要求每个声明的语言环境都必须定义。如果缺少某个语言环境，将发出警告。但如果配置中未声明某个语言环境但该语言环境存在，则接受。
-  - _注意_: 如果设置为 "loose"，翻译函数 `t` 将接受任何存在的语言环境。
-
-- **defaultLocale**:
-  - _类型_: `string`
-  - _默认值_: `'en'`
-  - _描述_: 当请求的语言环境未找到时，使用的默认语言环境作为回退。
-  - _示例_: `'en'`
-  - _注意_: 用于在 URL、cookie 或请求头中未指定语言环境时确定语言环境。
-
----
-
-### 编辑器配置
-
-定义与集成编辑器相关的设置，包括服务器端口和激活状态。
-
-#### 属性
-
-- **applicationURL**:
-  - _类型_: `string`
-  - _默认值_: `http://localhost:3000`
-  - _描述_: 应用程序的 URL。用于出于安全原因限制编辑器的来源。
-  - _示例_:
-    - `'http://localhost:3000'`
-    - `'https://example.com'`
-- `process.env.INTLAYER_EDITOR_URL`
-  - _注意_: 应用程序的 URL。用于出于安全原因限制编辑器的来源。如果设置为 `'*'`，则编辑器可从任何来源访问。
-
-- **port**:
-  - _类型_: `number`
-  - _默认值_: `8000`
-  - _描述_: 可视化编辑器服务器使用的端口。
-
-- **editorURL**:
-  - _类型_: `string`
-  - _默认值_: `'http://localhost:8000'`
-  - _描述_: 编辑器服务器的 URL。用于出于安全原因限制编辑器的来源。
-    - `'http://localhost:3000'`
-    - `'https://example.com'`
-    - `process.env.INTLAYER_EDITOR_URL`
-  - _注意_：应用程序访问的编辑器服务器的 URL。用于限制可以与应用程序交互的来源以确保安全。如果设置为 `'*'`，编辑器可以从任何来源访问。如果端口更改或编辑器托管在不同域名上，应设置此项。
-
-- **cmsURL**：
-  - _类型_：`string`
-  - _默认值_：`'https://intlayer.org'`
-  - _描述_：Intlayer CMS 的 URL。
-  - _示例_：`'https://intlayer.org'`
-  - _注意_：Intlayer CMS 的 URL。
-
-- **backendURL**：
-  - _类型_：`string`
-  - _默认值_：`https://back.intlayer.org`
-  - _描述_：后端服务器的 URL。
-  - _示例_：`http://localhost:4000`
-
-- **enabled**：
-  - _类型_：`boolean`
-  - _默认值_：`true`
-  - _描述_：指示应用程序是否与可视化编辑器交互。
-  - _示例_：`process.env.NODE_ENV !== 'production'`
-  - _注意_：如果为 true，编辑器将能够与应用程序交互。如果为 false，编辑器将无法与应用程序交互。无论如何，编辑器只能由可视化编辑器启用。在特定环境中禁用编辑器是一种加强安全性的方式。
-
-- **clientId**:
-  - _类型_：`string` | `undefined`
-  - _默认值_：`undefined`
-  - _描述_: clientId 和 clientSecret 允许 intlayer 包使用 oAuth2 认证与后端进行身份验证。访问令牌用于验证与项目相关的用户。要获取访问令牌，请访问 https://app.intlayer.org/project 并创建一个账户。
-  - _示例_: `true`
-  - _注意_: 重要提示：clientId 和 clientSecret 应保持机密，不得公开共享。请确保将它们保存在安全的位置，例如环境变量中。
-
-- **clientSecret**:
-  - _类型_: `string` | `undefined`
-  - _默认值_: `undefined`
-  - _描述_: clientId 和 clientSecret 允许 intlayer 包使用 oAuth2 认证与后端进行身份验证。访问令牌用于验证与项目相关的用户。要获取访问令牌，请访问 https://app.intlayer.org/project 并创建一个账户。
-  - _示例_: `true`
-  - _注意_: 重要提示：clientId 和 clientSecret 应保持机密，不得公开共享。请确保将它们保存在安全的位置，例如环境变量中。
-
-- **dictionaryPriorityStrategy**:
-  - _类型_: `string`
-  - _默认值_: `'local_first'`
-  - _描述_: 当本地和远程词典同时存在时，优先使用词典的策略。如果设置为 `'distant_first'`，应用程序将优先使用远程词典而非本地词典。如果设置为 `'local_first'`，应用程序将优先使用本地词典而非远程词典。
-  - _示例_: `'distant_first'`
-
-- **liveSync**:
-  - _类型_: `boolean`
-  - _默认值_: `false`
-  - _描述_: 指示当检测到 CMS / 可视化编辑器 / 后端内容发生变化时，应用服务器是否应热重载应用内容。
-  - _示例_: `true`
-  - _备注_: 例如，当添加或更新新的词典时，应用程序会更新页面中显示的内容。
-  - _注意_: 实时同步需要将应用内容外部化到另一个服务器。这意味着它可能会稍微影响应用的性能。为限制这种影响，我们建议将应用和实时同步服务器托管在同一台机器上。此外，实时同步与 `optimize` 的组合可能会对实时同步服务器产生大量请求。根据您的基础设施，我们建议测试这两种选项及其组合。
-
-- **liveSyncPort**:
-  - _类型_: `number`
-  - _默认值_: `4000`
-  - _描述_: 实时同步服务器的端口。
-  - _示例_: `4000`
-  - _注意_: 实时同步服务器的端口。
-
-- **liveSyncURL**:
-  - _类型_: `string`
-  - _默认值_: `'http://localhost:{liveSyncPort}'`
-  - _描述_: 实时同步服务器的 URL。
-  - _示例_: `'https://example.com'`
-  - _备注_: 默认指向 localhost，但在远程实时同步服务器的情况下可以更改为任何 URL。
-
-### 中间件配置
-
-控制中间件行为的设置，包括应用如何处理 cookie、头信息以及用于区域管理的 URL 前缀。
-
-#### 属性
-
-- **headerName**:
-  - _类型_: `string`
-  - _默认值_: `'x-intlayer-locale'`
-  - _描述_: 用于确定区域的 HTTP 头名称。
-  - _示例_: `'x-custom-locale'`
-  - _备注_: 这对于基于 API 的区域确定非常有用。
-
-- **cookieName**:
-  - _类型_: `string`
-  - _默认值_: `'intlayer-locale'`
-  - _描述_: 用于存储区域的 cookie 名称。
-  - _示例_: `'custom-locale'`
-  - _说明_: 用于在会话之间保持语言环境。
-
-- **prefixDefault**:
-  - _类型_: `boolean`
-  - _默认值_: `false`
-  - _说明_: 是否在 URL 中包含默认语言环境。
-  - _示例_: `true`
-  - _说明_:
-    - 如果为 `true` 且 `defaultLocale = 'en'`：路径为 `/en/dashboard` 或 `/fr/dashboard`
-    - 如果为 `false` 且 `defaultLocale = 'en'`：路径为 `/dashboard` 或 `/fr/dashboard`
-
-- **basePath**:
-  - _类型_: `string`
-  - _默认值_: `''`
-  - _说明_: 应用程序 URL 的基础路径。
-  - _示例_: `'/my-app'`
-  - _说明_:
-    - 如果应用托管在 `https://example.com/my-app`
-    - 基础路径为 `'/my-app'`
-    - URL 将是 `https://example.com/my-app/en`
-    - 如果未设置基础路径，URL 将是 `https://example.com/en`
-
-- **rewrite**:
-  - _类型_: `Record<string, StrictModeLocaleMap<string>>`
-  - _默认值_: `undefined`
-  - _说明_: 自定义 URL 重写规则，用于覆盖特定路径的默认路由模式。允许定义与标准路由行为不同的特定语言路径。支持使用 `[param]` 语法的动态路由参数。
-  - _示例_:
-    ```typescript
-    routing: {
-      mode: "prefix-no-default", // 回退策略
-      rewrite: nextjsRewrite({
-        "/[locale]/about": {
-          en: "/[locale]/about",
-          fr: "/[locale]/a-propos",
-        },
-        "/[locale]/product/[slug]": {
-          en: "/[locale]/product/[slug]",
-          fr: "/[locale]/produit/[slug]",
-        },
-        "/[locale]/blog/[category]/[id]": {
-          en: "/[locale]/blog/[category]/[id]",
-          fr: "/[locale]/journal/[category]/[id]",
-        },
-      }),
-    }
-    ```
-  - _说明_: 重写规则优先于默认的 `mode` 行为。如果路径匹配重写规则，将使用重写配置中的本地化路径，而不是标准语言前缀。
-  - _说明_: 支持使用方括号表示法的动态路由参数（例如 `[slug]`、`[id]`）。参数值会自动从 URL 中提取并插入到重写的路径中。
-  - _说明_: 适用于 Next.js 和 Vite 应用程序。中间件/代理会自动重写传入的请求以匹配内部路由结构。
-  - _说明_: 使用 `getLocalizedUrl()` 生成 URL 时，如果重写规则与提供的路径匹配，将自动应用这些规则。
-  - _参考_: 有关更多信息，请参阅 [自定义 URL 重写](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/custom_url_rewrites.md)。
-
-- **serverSetCookie**：
-  - _类型_：`string`
-  - _默认值_：`'always'`
-  - _描述_：服务器端设置语言环境 Cookie 的规则。
-  - _选项_：`'always'`，`'never'`
-  - _示例_：`'never'`
-  - _说明_：控制是否在每次请求时设置语言环境 Cookie，或者从不设置。
-
-- **noPrefix**：
-  - _类型_：`boolean`
-  - _默认值_：`false`
-  - _描述_：是否在 URL 中省略语言环境前缀。
-  - _示例_：`true`
-  - _说明_：
-    - 如果为 `true`：URL 中无前缀
-    - 如果为 `false`：URL 中有前缀
-    - 以 `basePath = '/my-app'` 为例：
-      - 如果 `noPrefix = false`：URL 将是 `https://example.com/my-app/en`
-      - 如果 `noPrefix = true`：URL 将是 `https://example.com`
-
----
-
-### 内容配置
-
-与应用内内容处理相关的设置，包括目录名称、文件扩展名及派生配置。
-
-#### 属性
-
-- **autoFill**：
-  - _类型_：`boolean | string | FilePathPattern | { [key in Locales]?: string }`
-  - _默认值_：`undefined`
-  - _描述_：指示内容应如何使用 AI 自动填充。可以在 `intlayer.config.ts` 文件中全局声明。
-  - _示例_：true
-  - _示例_：'./{{fileName}}.content.json'
-  - _示例_：{ fr: './{{fileName}}.fr.content.json', es: './{{fileName}}.es.content.json' }
-  - _备注_：自动填充配置。它可以是：
-    - boolean：为所有语言启用自动填充
-    - string：单个文件路径或带变量的模板路径
-    - object：每个语言的文件路径
-
-- **watch**:
-  - _类型_：`boolean`
-  - _默认值_：`process.env.NODE_ENV === 'development'`
-  - _描述_：指示 Intlayer 是否应监视应用中内容声明文件的更改，以重建相关字典。
-
-- **fileExtensions**:
-  - _类型_：`string[]`
-  - _默认值_: `['.content.ts', '.content.js', '.content.cjs', '.content.mjs', '.content.json', '.content.tsx', '.content.jsx']`
-  - _描述_: 构建字典时要查找的文件扩展名。
-  - _示例_: `['.data.ts', '.data.js', '.data.json']`
-  - _备注_: 自定义文件扩展名可以帮助避免冲突。
-
-- **dictionaryOutput**:
-  - _类型_: `string[]`
-  - _默认值_: `['intlayer']`
-  - _描述_: 使用的字典输出类型，例如 `'intlayer'` 或 `'i18next'`。
-
-- **contentDir**:
-  - _类型_: `string[]`
-  - _默认值_: `['.']`
-  - _示例_: `['src', '../../ui-library', require.resolve("@my-package/content")]`
-  - _描述_: 存储内容定义文件（`.content.*`）的目录路径。
-  - _备注_: 用于监视内容文件以重建字典。
-
-- **codeDir**:
-  - _类型_: `string[]`
-  - _默认值_: `['.']`
-  - _示例_: `['src', '../../ui-library']`
-  - _描述_: 存储代码的目录路径，相对于基础目录。
-  - _备注_: 用于监视代码文件以进行转换（修剪、优化）。将此与 `contentDir` 分开可以提高构建性能，避免不必要地扫描内容文件。
-
----
-
-### 系统配置
-
-与 Intlayer 内部路径和输出结果相关的设置。这些设置通常是内部的，用户无需修改。
-
-#### 属性
-
-- **baseDir**:
-  - _类型_: `string`
-  - _默认值_: `process.cwd()`
-  - _描述_: 项目的基础目录。
-  - _示例_: `'/path/to/project'`
-  - _备注_: 用于解析所有与 Intlayer 相关的目录。
-
-- **dictionariesDir**:
-  - _类型_: `string`
-  - _默认值_: `'.intlayer/dictionary'`
-  - _描述_: 用于存储本地化词典的目录。
-  - _示例_: `'translations'`
-
-- **moduleAugmentationDir**:
-  - _类型_: `string`
-  - _默认_: `'.intlayer/types'`
-  - _描述_: 模块增强目录，允许更好的 IDE 提示和类型检查。
-  - _示例_: `'intlayer-types'`
-  - _注意_: 确保在 `tsconfig.json` 中包含此目录。
-
-- **unmergedDictionariesDir**:
-  - _类型_: `string`
-  - _默认_: `'.intlayer/unmerged_dictionary'`
-  - _描述_: 用于存储未合并字典的目录。
-  - _示例_: `'translations'`
-
-- **typesDir**:
-  - _类型_: `string`
-  - _默认值_: `'types'`
-  - _描述_: 用于存储词典类型的目录。
-  - _示例_: `'intlayer-types'`
-
-- **mainDir**:
-  - _类型_: `string`
-  - _默认值_: `'main'`
-  - _描述_: 存放主应用程序文件的目录。
-  - _示例_: `'intlayer-main'`
-
-- **excludedPath**:
-  - _类型_: `string[]`
-  - _默认值_: `['node_modules']`
-  - _描述_: 排除内容搜索的目录。
-  - _备注_: 此设置尚未使用，但计划在未来实现。
-
-### 字典配置
-
-控制字典操作的设置，包括自动填充行为和内容生成。
-
-此字典配置有两个主要目的：
-
-1. **默认值**：在创建内容声明文件时定义默认值
-2. **回退行为**：当未定义特定字段时提供回退值，允许您全局定义字典操作行为
-
-有关内容声明文件以及如何应用配置值的更多信息，请参阅[内容文件文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/content_file.md)。
-
-#### 属性
-
-- **fill**
-- **description**
-- **locale**
-- **location**
-- **importMode**:
-  - _注意_: **Deprecated**: Use `dictionary.importMode` instead.
-  - _类型_: `'static' | 'dynamic' | 'fetch'`
-  - _默认值_: `'static'`
-  - _描述_: Controls how dictionaries are imported.
-  - _示例_: `'dynamic'`
-- **priority**
-- **live**
-- **schema**
-- **title**
-- **tags**
-- **version**
-
----
-
-### 日志配置
-
-控制日志记录器的设置，包括使用的前缀。
-
-#### 属性
-
-- **mode**:
-  - _类型_: `string`
-  - _默认值_: `default`
-  - _描述_: 指示日志记录器的模式。
-  - _选项_: `default`，`verbose`，`disabled`
-  - _示例_: `default`
-  - _备注_: 日志记录器的模式。详细模式将记录更多信息，可用于调试。禁用模式将关闭日志记录器。
-
-- **prefix**:
-  - _类型_: `string`
-  - _默认值_: `'[intlayer] '`
-  - _描述_: 日志记录器的前缀。
-  - _示例_: `'[my custom prefix] '`
-  - _注释_: 日志器的前缀。
-
-### AI 配置
-
-控制 Intlayer AI 功能的设置，包括提供商、模型和 API 密钥。
-
-如果您已使用访问密钥在[Intlayer 控制面板](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**
-- **Meta Llama**
-- **Ollama**
-- **OpenRouter**
-- **Alibaba Cloud**
-- **Fireworks**
-- **Hugging Face**
-- **Groq**
-- **Amazon Bedrock**
-- **Google AI Studio**
-- **Google Vertex**
-- **Together.ai**
-- **ollama**
-
-#### 属性
-
-- **provider**：
-  - _类型_：`string`
-  - _默认值_：`'openai'`
-  - _描述_：用于 Intlayer AI 功能的提供商。
-  - _选项_：`'openai'`、`'anthropic'`、`'mistral'`、`'deepseek'`、`'gemini'`
-  - _示例_：`'anthropic'`
-  - _注意_: 不同的提供商可能需要不同的 API 密钥，并且有不同的定价模型。
-
-- **model**:
-  - _类型_: `string`
-  - _默认值_: 无
-  - _描述_: 用于 Intlayer AI 功能的模型。
-  - _示例_: `'gpt-4o-2024-11-20'`
-  - _注意_: 具体使用的模型因提供商而异。
-
-- **temperature**:
-  - _类型_: `number`
-  - _默认值_: 无
-  - _描述_: temperature 控制 AI 回答的随机性。
-  - _示例_: `0.1`
-  - _注意_: 较高的 temperature 会使 AI 更具创造性且不可预测。
-
-- **apiKey**:
-  - _类型_: `string`
-  - _默认值_: 无
-  - _描述_: 你为所选提供商提供的 API 密钥。
-  - _示例_: `process.env.OPENAI_API_KEY`
-  - _注意_: 重要提示：API 密钥应保密，切勿公开共享。请确保将其保存在安全的位置，例如环境变量中。
-
-- **applicationContext**:
-  - _类型_: `string`
-  - _默认值_: 无
-  - _描述_: 向 AI 模型提供有关您的应用程序的额外上下文，帮助其生成更准确且符合上下文的翻译。这可以包括您的应用领域、目标受众、语气或特定术语的信息。
-
-- **baseURL**:
-  - _类型_: `string`
-  - _默认值_: 无
-  - _描述_: AI API 的基础 URL。
-  - _示例_: `'https://api.openai.com/v1'`
-  - _注意_: 可用于指向本地或自定义的 AI API 端点。
-
-- **dataSerialization**:
-  - _类型_: `'json' | 'toon'`
-  - _默认值_: `'json'`
-  - _描述_: 用于 Intlayer AI 功能的数据序列化格式。
-  - _示例_: `'toon'`
-  - _注意_: `json`: 标准、可靠；使用更多令牌。`toon`: 令牌更少，但不如 JSON 一致。
-
-### 构建配置
-
-控制 Intlayer 如何优化和构建您的应用程序国际化的设置。
-
-构建选项适用于 `@intlayer/babel` 和 `@intlayer/swc` 插件。
-
-> 在开发模式下，Intlayer 使用静态导入字典，以简化开发体验。
-
-> 在优化模式下，Intlayer 会替换字典调用以优化代码分块，因此最终打包只会导入实际使用的字典。
-
-#### 属性
-
-- **mode**：
-  - _类型_：`'auto' | 'manual'`
-  - _默认值_：`'auto'`
-  - _描述_：控制构建的模式。
-  - _示例_：`'manual'`
-  - _注意_：如果为 'auto'，构建将在应用程序构建时自动启用。
-  - _注意_：如果为 'manual'，构建仅在执行构建命令时设置。
-  - _注意_：可用于禁用字典构建，例如当应避免在 Node.js 环境中执行时。
-
-- **checkTypes**:
-  - _类型_: `boolean`
-  - _默认值_: `false`
-  - _描述_: 指示构建是否应检查 TypeScript 类型并记录错误。
-  - _注意_: 这可能会减慢构建速度。
-
-- **optimize**：
-  - _类型_：`boolean`
-  - _默认值_：`process.env.NODE_ENV === 'production'`
-  - _描述_：控制构建是否应进行优化。
-  - _示例_：`true`
-  - _注意_：启用时，Intlayer 会替换所有字典调用以优化代码分块。这样最终打包只会导入被使用的字典。所有导入将保持为静态导入，以避免加载字典时的异步处理。
-  - _注意_: Intlayer 会根据 `importMode` 选项定义的模式替换所有 `useIntlayer` 的调用，并将 `getIntlayer` 替换为 `getDictionary`。
-  - _注意_: 此选项依赖于 `@intlayer/babel` 和 `@intlayer/swc` 插件。
-  - _注意_: 确保所有键在 `useIntlayer` 调用中是静态声明的。例如 `useIntlayer('navbar')`。
-
-- **outputFormat**：
-  - _类型_： `'esm' | 'cjs'`
-  - _默认值_： `'esm'`
-  - _描述_： 控制字典的输出格式。
-  - _示例_： `'cjs'`
-  - _注意_： 字典的输出格式。
-
-- **traversePattern**:
-  - _类型_: `string[]`
-  - _默认值_: `['**\/*.{js,ts,mjs,cjs,jsx,tsx}', '!**\/node_modules/**']`
-  - _描述_：定义在优化过程中应遍历哪些文件的模式。
-    - _示例_：`['src/**\/*.{ts,tsx}', '../ui-library/**\/*.{ts,tsx}', '!**/node_modules/**']`
-  - _注意_：使用此选项限制优化范围到相关代码文件，以提升构建性能。
-  - _注意_：如果禁用 `optimize`，此选项将被忽略。
-  - _注意_：使用 glob 模式。
-
----
-
-### 编译器配置
-
-控制 Intlayer 编译器的设置，该编译器直接从您的组件中提取字典。
-
-#### 属性
-
-- **enabled**:
-  - _类型_：`boolean | 'build-only'`
-  - _默认值_：`true`
-  - _描述_：指示是否应启用编译器以提取字典。
-  - _示例_：`'build-only'`
-  - _注意_：设置为 `'build-only'` 将在开发模式下跳过编译器，以加快启动速度。它仅在构建命令时运行。
-
-- **dictionaryKeyPrefix**:
-  - _类型_：`string`
-  - _默认值_：`''`
-  - _描述_：提取的字典键的前缀。
-  - _示例_：`'my-key-'`
-  - _注意_：提取字典时，键是根据文件名生成的。此前缀会添加到生成的键中，以防止冲突。
-
-- **saveComponents**:
-  - _类型_：`boolean`
-  - _默认值_：`false`
-  - _描述_：指示是否应在转换后保存组件。
-  - _注意_：如果为 true，编译器将用转换后的文件替换原始文件。这样，编译器只需运行一次来转换应用，然后即可移除。
-
-- **transformPattern**:
-  - _类型_：`string | string[]`
-  - _默认值_：`['**/*.{ts,tsx,jsx,js,cjs,mjs,svelte,vue}', '!**/node_modules/**']`
-  - _描述_：定义在优化过程中应遍历哪些文件的模式。
-  - _示例_：`['src/**/*.{ts,tsx}', '!**/node_modules/**']`
-  - _注意_：使用此选项限制优化范围到相关代码文件，以提升构建性能。
-
-- **excludePattern**:
-  - _类型_：`string | string[]`
-  - _默认值_：`['**/node_modules/**']`
-  - _描述_：定义在优化过程中应排除哪些文件的模式。
-  - _示例_：`['**/node_modules/**', '!**/node_modules/react/**']`
-
-- **output**:
-  - _类型_: `FilePathPattern`
-  - _默认值_: `undefined`
-  - _描述_: 定义输出文件路径。替换 `outputDir`。通过字符串模板或函数支持动态变量。支持的变量：`{{fileName}}`, `{{key}}`, `{{locale}}`, `{{extension}}`, `{{componentFileName}}`, `{{componentExtension}}`, `{{format}}`, `{{componentFormat}}`, `{{componentDirPath}}`。
-  - _注意_: 以 `./` 开头的路径相对于组件目录解析。以 `/` 开头的路径相对于项目根目录 (`baseDir`) 解析。
-  - _注意_: 在路径中包含 `{{locale}}` 变量将启用按语言环境分离开的字典生成。
-  - _示例_:
-    - **在组件旁边创建多语言文件**:
-    - 字符串: `'./{{fileName}}{{extension}}'`
-    - 函数: `({ fileName, extension }) => \`./${fileName}${extension}\``
-
-    - **输出按语言环境集中的 JSON**:
-    - 字符串: `'/locales/{{locale}}/{{key}}.content.json'`
-    - 函数: `({ key, locale }) => \`/locales/${locale}/${key}.content.json\``
-
-- **noMetadata**:
-  - _类型_: `boolean`
-  - _默认值_: `false`
-  - _描述_: 指示是否应在文件中保存元数据。如果为 true，编译器将不会保存字典的元数据（键、内容包装器）。
-  - _注意_: 如果与 `loadJSON` 插件一起使用，则非常有用。对于每种语言的 i18next 或 ICU MessageFormat JSON 输出非常有用。
-  - _示例_:
-    如果为 `true`：
-    ```json
-    {
-      "key": "value"
-    }
-    ```
-    如果为 `false`：
-    ```json
-    {
-      "key": "value",
-      "content": {
-        "key": "value"
-      }
-    }
-    ```