@intlayer/docs 8.3.0 → 8.3.2

package/docs/zh/configuration.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-13
-updatedAt: 2026-03-11
+updatedAt: 2026-03-12
 title: 配置
 description: 了解如何为您的应用程序配置 Intlayer。了解各种设置和选项，以根据您的需求自定义 Intlayer。
 keywords:
@@ -15,7 +15,7 @@ slugs:
   - configuration
 history:
   - version: 8.3.0
-    data: 2026-03-11
+    date: 2026-03-11
     changes: 将 'baseDir' 从 'content' 配置移动到 'system' 配置
   - version: 8.2.0
     date: 2026-03-10
@@ -95,7 +95,7 @@ Intlayer 支持 JSON、JS、MJS 和 TS 配置文件格式：
 
 ## 示例配置文件
 
-```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+````typescript fileName="intlayer.config.ts" codeFormat="typescript"
 import { Locales, type IntlayerConfig } from "intlayer";
 import { nextjsRewrite } from "intlayer/routing";
 import { z } from "zod";
@@ -193,7 +193,7 @@ const config: IntlayerConfig = {
      * Options: 'cookie', 'localStorage', 'sessionStorage', 'header', or an array of these.
      * Default: ['cookie', 'header']
      */
-    storage: "cookie",
+    storage: ["cookie", "header"],
 
     /**
      * Base path for the application URLs.
@@ -259,13 +259,13 @@ const config: IntlayerConfig = {
   editor: {
     /**
      * Whether the visual editor is enabled.
-     * Default: true
+     * Default: false
      */
     enabled: true,
 
     /**
      * URL of your application for origin validation.
-     * Default: "*"
+     * Default: ""
      */
     applicationURL: "http://localhost:3000",
 
@@ -330,6 +330,17 @@ const config: IntlayerConfig = {
      * Base URL for the AI API.
      */
     baseURL: "http://localhost:3000",
+
+    /**
+     * 数据序列化
+     *
+     * 选项：
+     * - "json": 标准、可靠；使用更多 token。
+     * - "toon": 生成更少的 token，但不如 JSON 稳定。
+     *
+     * 默认值: "json"
+     */
+    dataSerialization: "json",
   },
 
   /**
@@ -429,42 +440,70 @@ const config: IntlayerConfig = {
   compiler: {
     /**
      * 指示是否应启用编译器。
+     *
+     * - false : 禁用编译器。
+     * - true : 启用编译器。
+     * - "build-only" : 在开发期间跳过编译器以加快启动速度。
+     *
+     * 默认值 : false
      */
     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.
+     * 定义输出文件路径。替换 `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`: 组件目录路径。
      */
-    excludePattern: ["**/node_modules/**"],
+    output: ({ locale, key }) => `compiler/${locale}/${key}.json`,
 
     /**
-     * 优化字典的输出目录。
+     * 指示转换后是否应保存组件。
+     * 这样，编译器只需运行一次即可转换应用程序，然后即可将其删除。
      */
-    output: ({ locale, key }) => `compiler/${locale}/${key}.json`,
+    saveComponents: false,
 
     /**
-     * 仅在生成的文件中插入内容，不含键。
+     * 仅在生成的文件中插入内容。对于每种语言的 i18next 或 ICU MessageFormat JSON 输出非常有用。
      */
     noMetadata: false,
 
     /**
      * 字典键前缀
      */
-    dictionaryKeyPrefix: "", // Remove base prefix
-
-    /**
-     * 指示转换后是否应保存组件。
-     * 这样，编译器只需运行一次即可转换应用程序，然后即可将其删除。
-     */
-    saveComponents: false,
+    dictionaryKeyPrefix: "", // 为所有字典键设置前缀
   },
 
   /**
@@ -483,7 +522,7 @@ const config: IntlayerConfig = {
 };
 
 export default config;
-```
+````
 
 ## 配置参考
 
@@ -981,25 +1020,6 @@ Intlayer 支持多个 AI 提供商，以增强灵活性和选择。目前支持
   - _注意_: 此选项依赖于 `@intlayer/babel` 和 `@intlayer/swc` 插件。
   - _注意_: 确保所有键在 `useIntlayer` 调用中是静态声明的。例如 `useIntlayer('navbar')`。
 
-- **importMode**:
-  - _注意_: **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'`
@@ -1033,7 +1053,7 @@ Intlayer 支持多个 AI 提供商，以增强灵活性和选择。目前支持
 
 - **dictionaryKeyPrefix**:
   - _类型_：`string`
-  - _默认值_：`'comp-'`
+  - _默认值_：`''`
   - _描述_：提取的字典键的前缀。
   - _示例_：`'my-key-'`
   - _注意_：提取字典时，键是根据文件名生成的。此前缀会添加到生成的键中，以防止冲突。
@@ -1057,24 +1077,28 @@ Intlayer 支持多个 AI 提供商，以增强灵活性和选择。目前支持
   - _描述_：定义在优化过程中应排除哪些文件的模式。
   - _示例_：`['**/node_modules/**', '!**/node_modules/react/**']`
 
-- **outputDir**:
-  - _类型_：`string`
-  - _默认值_： `'compiler'`
-  - _描述_：存储提取字典的目录，相对于您的项目基准路径。
-
 - **output**:
   - _类型_: `FilePathPattern`
-  - _默认值_: `({ key }) => 'compiler/${key}.content.json'`
-  - _描述_: 定义输出文件路径。替换 `outputDir`。处理动态变量，如 `{{locale}}`、`{{key}}`、`{{fileName}}`、`{{extension}}`、`{{format}}`、`{{dirPath}}`、`{{componentFileName}}`、`{{componentExtension}}`、`{{componentFormat}}`。可以设置为字符串（使用 `'my/{{var}}/path'` 格式）或函数。
-  - _注意_: `./**/*` 路径相对于组件解析。`/**/*` 路径相对于 Intlayer 的 `baseDir` 解析。
-  - _示例_: `output: ({ locale, key }) => 'compiler/${locale}/${key}.json'`
+  - _默认值_: `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` 插件一起使用，则非常有用。
-  - _示例_: 如果为 `true`：
+  - _注意_: 如果与 `loadJSON` 插件一起使用，则非常有用。对于每种语言的 i18next 或 ICU MessageFormat JSON 输出非常有用。
+  - _示例_:
+    如果为 `true`：
     ```json
     {
       "key": "value"

package/docs/zh/intlayer_with_adonisjs.md

@@ -44,7 +44,7 @@ history:
 <iframe
   src="https://stackblitz.com/github/aymericzip/intlayer-adonisjs-template?embed=1&ctl=1&file=intlayer.config.ts"
   className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
-  title="Demo CodeSandbox - How to Internationalize your application using Intlayer"
+  title="Demo CodeSandbox - 如何使用 Intlayer 实现应用国际化"
   sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
   loading="lazy"
 />

package/docs/zh/intlayer_with_analog.md

@@ -344,8 +344,8 @@ Intlayer 使用模块扩充 (module augmentation) 来利用 TypeScript 的优势
 
 为此，您可以将以下指令添加到 `.gitignore` 文件中：
 
-```plaintext
-# 忽略 Intlayer 生成的文件
+```bash
+#  忽略 Intlayer 生成的文件
 .intlayer
 ```
 

package/docs/zh/intlayer_with_angular.md

@@ -395,8 +395,8 @@ Intlayer 使用模块扩充来发挥 TypeScript 的优势并使你的代码库
 
 为此，你可以在 `.gitignore` 文件中添加以下指令：
 
-```plaintext
-# 忽略 Intlayer 生成的文件
+```bash
+#  忽略 Intlayer 生成的文件
 .intlayer
 ```
 

package/docs/zh/intlayer_with_astro.md

@@ -218,8 +218,8 @@ Intlayer 使用模块增强来利用 TypeScript 的优势，使您的代码库
 
 要做到这一点，您可以将以下指令添加到您的 `.gitignore` 文件中：
 
-```plaintext
-# 忽略 Intlayer 生成的文件
+```bash
+#  忽略 Intlayer 生成的文件
 .intlayer
 ```
 

package/docs/zh/intlayer_with_express.md

@@ -49,7 +49,7 @@ history:
 <iframe
   src="https://stackblitz.com/github/aymericzip/intlayer-express-template?embed=1&ctl=1&file=intlayer.config.ts"
   className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
-  title="Demo CodeSandbox - How to Internationalize your application using Intlayer"
+  title="Demo CodeSandbox - 如何使用 Intlayer 实现应用国际化"
   sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
   loading="lazy"
 />

package/docs/zh/intlayer_with_fastify.md

@@ -49,7 +49,7 @@ history:
 <iframe
   src="https://stackblitz.com/github/aymericzip/intlayer-fastify-template?embed=1&ctl=1&file=intlayer.config.ts"
   className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
-  title="Demo CodeSandbox - How to Internationalize your application using Intlayer"
+  title="Demo CodeSandbox - 如何使用 Intlayer 实现应用国际化"
   sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
   loading="lazy"
 />

package/docs/zh/intlayer_with_hono.md

@@ -47,7 +47,7 @@ history:
 <iframe
   src="https://stackblitz.com/github/aymericzip/intlayer-hono-template?embed=1&ctl=1&file=intlayer.config.ts"
   className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
-  title="Demo CodeSandbox - How to Internationalize your application using Intlayer"
+  title="Demo CodeSandbox - 如何使用 Intlayer 实现应用国际化"
   sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
   loading="lazy"
 />

package/docs/zh/intlayer_with_lynx+react.md

@@ -500,8 +500,8 @@ Intlayer 在一个隐藏文件夹中生成类型定义（默认是 `.intlayer`
 
 为了避免提交由 Intlayer 自动生成的文件，请将以下内容添加到您的 `.gitignore` 中：
 
-```plaintext
-# 忽略由 Intlayer 生成的文件
+```bash
+#  忽略由 Intlayer 生成的文件
 .intlayer
 ```
 

package/docs/zh/intlayer_with_nestjs.md

@@ -52,7 +52,7 @@ history:
 <iframe
   src="https://stackblitz.com/github/aymericzip/intlayer-nestjs-template?embed=1&ctl=1&file=intlayer.config.ts"
   className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
-  title="Demo CodeSandbox - How to Internationalize your application using Intlayer"
+  title="Demo CodeSandbox - 如何使用 Intlayer 实现应用国际化"
   sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
   loading="lazy"
 />

package/docs/zh/intlayer_with_nextjs_16.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-12-06
-updatedAt: 2025-12-30
+updatedAt: 2026-03-12
 title: Next.js i18n - 如何翻译Next.js 16 应用 2026
 description: 了解如何让您的 Next.js 16 网站支持多语言。按照文档进行国际化 (i18n) 并对其进行翻译。
 keywords:
@@ -1691,6 +1691,179 @@ Intlayer 使用模块扩充来利用 TypeScript 的优势，并使您的代码
 
 有关如何使用该扩展的更多详细信息，请参阅 [Intlayer VS Code 扩展文档](https://intlayer.org/doc/vs-code-extension)。
 
+### (可选) 步骤 1 : 提取组件内容
+
+如果您有现有的代码库，转换数千个文件可能会非常耗时。
+
+为了简化此过程，Intlayer 提出了 [编译器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/compiler.md) / [提取器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/extract.md) 来转换您的组件并提取内容。
+
+要进行设置，您可以在 `intlayer.config.ts` 文件中添加 `compiler` 部分：
+
+```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+import { type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  // ... 您的其他配置
+  compiler: {
+    /**
+     * 指示是否应启用编译器。
+     */
+    enabled: true,
+
+    /**
+     * 定义输出文件路径
+     */
+    output: ({ fileName, extension }) => `./${fileName}${extension}`,
+
+    /**
+     * 指示在转换后是否应保存组件。这样，编译器只需运行一次即可转换应用程序，然后即可将其删除。
+     */
+    saveComponents: false,
+
+    /**
+     * 字典键前缀
+     */
+    dictionaryKeyPrefix: "",
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.mjs" codeFormat="esm"
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  // ... 您的其他配置
+  compiler: {
+    /**
+     * 指示是否应启用编译器。
+     */
+    enabled: true,
+
+    /**
+     * 定义输出文件路径
+     */
+    output: ({ fileName, extension }) => `./${fileName}${extension}`,
+
+    /**
+     * 指示在转换后是否应保存组件。这样，编译器只需运行一次即可转换应用程序，然后即可将其删除。
+     */
+    saveComponents: false,
+
+    /**
+     * 字典键前缀
+     */
+    dictionaryKeyPrefix: "",
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  // ... 您的其他配置
+  compiler: {
+    /**
+     * 指示是否应启用编译器。
+     */
+    enabled: true,
+
+    /**
+     * 定义输出文件路径
+     */
+    output: ({ fileName, extension }) => `./${fileName}${extension}`,
+
+    /**
+     * 指示在转换后是否应保存组件。这样，编译器只需运行一次即可转换应用程序，然后即可将其删除。
+     */
+    saveComponents: false,
+
+    /**
+     * 字典键前缀
+     */
+    dictionaryKeyPrefix: "",
+  },
+};
+
+module.exports = config;
+```
+
+<Tabs>
+ <Tab value='提取命令'>
+
+运行提取器以转换组件并提取内容
+
+```bash packageManager="npm"
+npx intlayer extract
+```
+
+```bash packageManager="pnpm"
+pnpm intlayer extract
+```
+
+```bash packageManager="yarn"
+yarn intlayer extract
+```
+
+```bash packageManager="bun"
+bunx intlayer extract
+```
+
+ </Tab>
+ <Tab value='Babel 编译器'>
+
+```bash packageManager="npm"
+npm install @intlayer/babel --save-dev
+```
+
+```bash packageManager="pnpm"
+pnpm add @intlayer/babel --save-dev
+```
+
+```bash packageManager="yarn"
+yarn add @intlayer/babel --save-dev
+```
+
+```bash packageManager="bun"
+bun add @intlayer/babel --dev
+```
+
+```js fileName="babel.config.js"
+const {
+  intlayerExtractBabelPlugin,
+  getExtractPluginOptions,
+} = require("@intlayer/babel");
+
+module.exports = {
+  presets: ["next/babel"],
+  plugins: [
+    // 将组件内容提取到字典中
+    [intlayerExtractBabelPlugin, getExtractPluginOptions()],
+  ],
+};
+```
+
+```bash packageManager="npm"
+npm run build # 或 npm run dev
+```
+
+```bash packageManager="pnpm"
+pnpm run build # 或 pnpm run dev
+```
+
+```bash packageManager="yarn"
+yarn build # 或 yarn dev
+```
+
+```bash packageManager="bun"
+bun run build # Or bun run dev
+```
+
+ </Tab>
+</Tabs>
+
 ### 深入了解
 
 要深入了解，您可以实现[可视化编辑器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_visual_editor.md)或使用 [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_CMS.md) 外化您的内容。