---
createdAt: 2024-08-13
updatedAt: 2026-02-25
title: 配置
description: 了解如何为您的应用程序配置 Intlayer。了解各种设置和选项，以根据您的需求自定义 Intlayer。
keywords:
  - 配置
  - 设置
  - 自定义
  - Intlayer
  - 选项
slugs:
  - doc
  - concept
  - configuration
history:
  - version: 8.1.7
    date: 2026-02-25
    changes: 更新编译器选项
  - version: 8.0.6
    date: 2026-02-12
    changes: Add support for Open Router, Alibaba, Amazon, Google Vertex Bedrock, Fireworks, Groq, Hugging Face, and Together.ai providers
  - version: 8.0.5
    date: 2026-02-06
    changes: 在 AI 配置中添加 `dataSerialization`
  - version: 8.0.0
    date: 2026-01-22
    changes: Move `importMode` build configuration to `dictionary` configuration.
  - 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",

    /**
     * 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: true
     */
    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",
  },

  /**
   * 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: {
    /**
     * Indicates if the compiler should be enabled.
     */
    enabled: true,

    /**
     * Pattern to traverse the code to optimize.
     */
    transformPattern: [
      "**/*.{js,ts,mjs,cjs,jsx,tsx,vue,svelte}",
      "!**/node_modules/**",
    ],

    /**
     * Pattern to exclude from the optimization.
     */
    excludePattern: ["**/node_modules/**"],

    /**
     * Output directory for the optimized dictionaries.
     */
    outputDir: "compiler",

    /**
     * Dictionary key prefix
     */
    dictionaryKeyPrefix: "", // Remove base prefix

    /**
     * Indicates if the components should be saved after being transformed.
     * That way, the compiler can be run only once to transform the app, and then it can be removed.
     */
    saveComponents: false,
  },

  /**
   * 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 | { [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']`
  - _备注_: 自定义文件扩展名可以帮助避免冲突。

- **baseDir**:
  - _类型_: `string`
  - _默认值_: `process.cwd()`
  - _描述_: 项目的基础目录。
  - _示例_: `'/path/to/project'`
  - _备注_: 用于解析所有与 Intlayer 相关的目录。

- **dictionaryOutput**:
  - _类型_: `string[]`
  - _默认值_: `['intlayer']`
  - _描述_: 使用的字典输出类型，例如 `'intlayer'` 或 `'i18next'`。

- **contentDir**:
  - _类型_: `string[]`
  - _默认值_: `['.']`
  - _示例_: `['src', '../../ui-library', require.resolve("@my-package/content")]`
  - _描述_: 存储内容定义文件（`.content.*`）的目录路径。
  - _备注_: 用于监视内容文件以重建字典。

- **codeDir**:
  - _类型_: `string[]`
  - _默认值_: `['.']`
  - _示例_: `['src', '../../ui-library']`
  - _描述_: 存储代码的目录路径，相对于基础目录。
  - _备注_: 用于监视代码文件以进行转换（修剪、优化）。将此与 `contentDir` 分开可以提高构建性能，避免不必要地扫描内容文件。

- **dictionariesDir**:
  - _类型_: `string`
  - _默认_: `'.intlayer/dictionaries'`
  - _描述_: 用于存储中间结果或输出结果的目录路径。

- **moduleAugmentationDir**:
  - _类型_: `string`
  - _默认_: `'.intlayer/types'`
  - _描述_: 模块增强目录，允许更好的 IDE 提示和类型检查。
  - _示例_: `'intlayer-types'`
  - _注意_: 确保在 `tsconfig.json` 中包含此目录。

- **unmergedDictionariesDir**:
  - _类型_: `string`
  - _默认_: `'.intlayer/unmerged_dictionary'`
  - _描述_: 用于存储未合并字典的目录。
  - _示例_: `'translations'`

- **dictionariesDir**:
  - _类型_: `string`
  - _默认值_: `'.intlayer/dictionary'`
  - _描述_: 用于存储本地化词典的目录。
  - _示例_: `'translations'`

- **i18nextResourcesDir**:
  - _类型_: `string`
  - _默认值_: `'i18next_dictionary'`
  - _描述_: 用于存储 i18n 词典的目录。
  - _示例_: `'translations'`
  - _注意_: 确保该目录已为 i18next 输出类型进行配置。

- **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**:
  - _Note_: **Deprecated**: Use `dictionary.importMode` instead.
  - _Type_: `'static' | 'dynamic' | 'fetch'`
  - _Default_: `'static'`
  - _Description_: Controls how dictionaries are imported.
  - _Example_: `'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**:
  - _Type_: `boolean`
  - _Default_: `false`
  - _Description_: 指示构建是否应检查 TypeScript 类型并记录错误。
  - _Note_: 这可能会减慢构建速度。

- **optimize**：
  - _类型_：`boolean`
  - _默认值_：`process.env.NODE_ENV === 'production'`
  - _描述_：控制构建是否应进行优化。
  - _示例_：`true`
  - _注意_：启用时，Intlayer 会替换所有字典调用以优化代码分块。这样最终打包只会导入被使用的字典。所有导入将保持为静态导入，以避免加载字典时的异步处理。
  - _注意_: Intlayer 会根据 `importMode` 选项定义的模式替换所有 `useIntlayer` 的调用，并将 `getIntlayer` 替换为 `getDictionary`。
  - _注意_: 此选项依赖于 `@intlayer/babel` 和 `@intlayer/swc` 插件。
  - _注意_: 确保所有键在 `useIntlayer` 调用中是静态声明的。例如 `useIntlayer('navbar')`。

- **importMode**:
  - _Note_: **Deprecated**: Use `dictionary.importMode` instead.
  - _类型_: `'static' | 'dynamic' | 'fetch'`
  - _默认值_: `'static'`
  - _描述_: 控制字典的导入方式。
  - _示例_: `'dynamic'`
  - _注意_: 可用模式：
    - "static"：字典以静态方式导入。将 `useIntlayer` 替换为 `useDictionary`。
    - "dynamic"：字典通过 Suspense 动态导入。将 `useIntlayer` 替换为 `useDictionaryDynamic`。
  - "live"：字典通过实时同步 API 动态获取。将 `useIntlayer` 替换为 `useDictionaryFetch`。
  - _注意_：动态导入依赖 Suspense，可能会略微影响渲染性能。
  - _注意_：如果禁用，所有语言环境将一次性加载，即使未被使用。
  - _注意_：此选项依赖 `@intlayer/babel` 和 `@intlayer/swc` 插件。
  - _注意_：确保在 `useIntlayer` 调用中所有键都是静态声明的。例如 `useIntlayer('navbar')`。
  - _注意_：如果禁用 `optimize`，此选项将被忽略。
  - _注意_: 如果设置为 "live"，只有包含远程内容且标记为 "live" 的字典会被转换为实时模式。其他字典将以 "dynamic" 模式动态导入，以优化请求次数和加载性能。
  - _注意_: 实时模式将使用实时同步 API 来获取字典。如果 API 调用失败，字典将以 "dynamic" 模式动态导入。
  - _注意_: 此选项不会影响 `getIntlayer`、`getDictionary`、`useDictionary`、`useDictionaryAsync` 和 `useDictionaryDynamic` 函数。

- **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`
  - _默认值_：`'comp-'`
  - _描述_：提取的字典键的前缀。
  - _示例_：`'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/**']`

- **outputDir**:
  - _类型_：`string`
  - _默认值_： `'compiler'`
  - _描述_：存储提取字典的目录，相对于您的项目基准路径。
