@intlayer/docs 8.12.5-canary.0 → 9.0.0-canary.11

package/docs/zh/compat/polyglot.md

@@ -0,0 +1,45 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "从 Polyglot.js 迁移到 Intlayer"
+description: "了解如何使用兼容适配器从 Polyglot.js 迁移到 Intlayer。"
+keywords:
+  - polyglot
+  - airbnb
+  - intlayer
+  - 迁移
+  - 兼容
+slugs:
+  - doc
+  - compatibility
+  - polyglot
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# 从 Polyglot.js 迁移到 Intlayer
+
+如果您正在使用 Airbnb 的 Polyglot.js，使用兼容层迁移到 Intlayer 非常简单直接。
+
+## 操作步骤
+
+只需在您的项目中运行初始化命令：
+
+```bash
+npx intlayer init
+```
+
+这将生成 `intlayer.config.ts`。然后，您可以使用 bundler 插件别名将 Polyglot 导入透明地重定向到 `@intlayer/polyglot`。
+
+## 底层原理
+
+Polyglot.js 语法通常依赖于 `polyglot.t('key', {name})`，使用 `%{name}` 插值和以 `"singular |||| plural"` 分隔的 `smart_count` 复数。
+
+底层实现：
+
+- **插值：** 兼容层原生处理 `%{var}` 占位符。
+- **复数：** 字符串在 `||||` 处被分割，并根据活动语言环境针对原生 `Intl.PluralRules` 进行求值，按照 Polyglot 自身的每语言环境桶顺序进行处理。
+- **字典：** 您无需向 `new Polyglot()` 提供大型 JSON 配置——Intlayer 动态处理字典并自动进行修剪。

package/docs/zh/compat/react-i18next.md

@@ -0,0 +1,58 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "从 react-i18next 迁移到 Intlayer"
+description: "了解如何使用兼容适配器将您的 React 应用程序从 react-i18next 迁移到 Intlayer。"
+keywords:
+  - react-i18next
+  - i18next
+  - intlayer
+  - 迁移
+  - 兼容
+slugs:
+  - doc
+  - compatibility
+  - react-i18next
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# 从 react-i18next 迁移到 Intlayer
+
+有关完整详细的分步教程，请参阅我们完整的 [react-i18next 迁移指南](../migration_from_react-i18next_to_intlayer.md)。
+
+使用 Intlayer 的兼容适配器，您可以从 `react-i18next` 迁移，而无需对源代码导入进行任何更改。
+
+## 操作步骤
+
+要初始化项目，运行：
+
+```bash
+npx intlayer init
+```
+
+在初始化期间，Intlayer 将安装 `@intlayer/react-i18next` 并创建 `intlayer.config.ts`。在您的 bundler（如 Vite）中，应用 Intlayer 插件：
+
+```typescript fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import { reactI18nextVitePlugin } from "@intlayer/react-i18next/plugin";
+
+export default defineConfig({
+  plugins: [react(), reactI18nextVitePlugin()],
+});
+```
+
+## 底层原理
+
+`reactI18nextVitePlugin` 包装了核心 `vite-intlayer` 插件，并为 `react-i18next` 和 `i18next` 注入解析别名，将它们重定向到 `@intlayer/react-i18next` 和 `@intlayer/i18next`。
+
+底层实现：
+
+- **`useTranslation` 和 `withTranslation`：** 重写为使用 Intlayer 的原生 hook，为您的字典键提供自动 TypeScript 补全。无缝支持命名空间（例如 `t('namespace:key')`）。
+- **复数与上下文：** 使用原生 `Intl.PluralRules` 和上下文后缀（`key_male`）处理 i18next 基于后缀的复数化（`key_one`、`key_other`）。
+- **`<Trans>` 组件：** 重新实现以支持 `components` prop、对象和数组形式，以及编号标签 `<1>...</1>` 直接映射到您的 React 节点。
+- **`i18n` 实例：** 直接从 Intlayer 解析键值，无需获取大型 JSON 文件，从而显著降低 bundle 体积。

package/docs/zh/compat/react-intl.md

@@ -0,0 +1,55 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "从 React Intl 迁移到 Intlayer"
+description: "了解如何使用兼容适配器将您的 React 应用程序从 react-intl 迁移到 Intlayer。"
+keywords:
+  - react-intl
+  - formatjs
+  - intlayer
+  - 迁移
+  - 兼容
+slugs:
+  - doc
+  - compatibility
+  - react-intl
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# 从 React Intl 迁移到 Intlayer
+
+如果您的 React 应用程序使用 `react-intl`（FormatJS），迁移到 Intlayer 轻而易举。我们的兼容层无缝处理 ICU MessageFormat 和所有现有的 `Formatted*` 组件。
+
+## 操作步骤
+
+首先在您的项目中运行初始化命令：
+
+```bash
+npx intlayer init
+```
+
+然后，在您的配置中设置 Intlayer Vite 或 Next.js 插件。该插件注入构建时别名，将 `react-intl` 导入重定向到 `@intlayer/react-intl`。
+
+```typescript fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import reactIntlVitePlugin from "@intlayer/react-intl/plugin";
+
+export default defineConfig({
+  plugins: [react(), reactIntlVitePlugin()],
+});
+```
+
+## 底层原理
+
+bundler 插件将 `react-intl` 别名为 `@intlayer/react-intl`。Intlayer 插件在运行时静态提取键值并使用 Intlayer 字典，而不是手动解析大型 JSON 文件并将应用程序包装在 `IntlProvider` 中。
+
+底层实现：
+
+- **ICU MessageFormat：** Intlayer 使用 `resolveMessage(..., 'icu')` 解析器，原生完全支持 ICU 复数化、selection、日期/数字格式化和富文本标签。
+- **方法和 JSX 调用者：** `intl.formatMessage({ id: 'a.b' })` 和 `<FormattedMessage id="a.b">` 由 Intlayer 编译器插件（`@intlayer/babel` / `@intlayer/swc`）识别，转换扁平点分键，使第一个段正确解析为 Intlayer 字典键。
+- **格式化器：** `<FormattedNumber>`、`<FormattedDate>` 等，使用 `Intl` 桥接到核心原生 `core/formatters`。

package/docs/zh/compat/svelte-i18n.md

@@ -0,0 +1,47 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "从 Svelte I18n 迁移到 Intlayer"
+description: "了解如何使用兼容适配器将您的 Svelte 应用程序从 svelte-i18n 迁移到 Intlayer。"
+keywords:
+  - svelte-i18n
+  - svelte
+  - intlayer
+  - 迁移
+  - 兼容
+slugs:
+  - doc
+  - compatibility
+  - svelte-i18n
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# 从 Svelte I18n 迁移到 Intlayer
+
+使用兼容适配器，将您的 Svelte 应用程序从 `svelte-i18n` 迁移到 Intlayer 只需片刻。
+
+## 操作步骤
+
+只需在您的项目中运行初始化命令：
+
+```bash
+npx intlayer init
+```
+
+这将生成 `intlayer.config.ts`。确保您的 SvelteKit / Vite 插件与 Intlayer 的别名插件封装在一起，以无缝地将 `svelte-i18n` 映射到 `@intlayer/svelte-i18n`。
+
+## 底层原理
+
+Svelte-i18n 依赖于大量使用的 store（`$_`、`$t`、`$format` 等）和 ICU MessageFormat。
+
+底层实现：
+
+- **Store：** Intlayer 代理 `svelte-i18n` store。`$_` 成为当前语言环境的派生 store，返回 Intlayer 解析器。
+- **键值：** 您的扁平键（例如 `$_('home.title')`）被求值，使得第一个路径段代表 Intlayer 字典。
+- **ICU 语法：** 由共享 ICU 解析器（等效于 `intl-messageformat` 解析）完全处理。
+- **格式化器：** `$date`、`$time`、`$number` 调用安全地重定向到 Intlayer 的原生核心格式化器。
+- **Babel/SWC 分析：** Intlayer 分析器在编译之前读取您的 `.svelte` 源文件中的 Svelte store 调用者（`$_`），以自动构建相关字典 chunk。

package/docs/zh/compat/transloco.md

@@ -0,0 +1,45 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "从 Transloco 迁移到 Intlayer"
+description: "了解如何使用兼容适配器将您的 Angular 应用程序从 Transloco 迁移到 Intlayer。"
+keywords:
+  - transloco
+  - angular
+  - intlayer
+  - 迁移
+  - 兼容
+slugs:
+  - doc
+  - compatibility
+  - transloco
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# 从 Transloco 迁移到 Intlayer
+
+如果您的 Angular 应用程序当前使用 `@jsverse/transloco`，您可以使用我们的兼容适配器迁移到 Intlayer。这一过渡让您在利用 Intlayer 强大字典结构的同时，维持现有的模板语法。
+
+## 操作步骤
+
+只需在您的项目中运行初始化命令：
+
+```bash
+npx intlayer init
+```
+
+这将生成必要的 `intlayer.config.ts` 配置。然后，您将用 `@intlayer/transloco` 模块替换您的 Transloco 导入，或依赖构建别名。
+
+## 底层原理
+
+Transloco 使用作用域和 `TranslocoService`（`translate`、`selectTranslate`），以及结构性指令（`*transloco="let t"`）和管道（`| transloco`）。
+
+底层实现：
+
+- **作用域：** 自然映射到 Intlayer 字典键，为 bundle 优化提供出色的修剪能力。
+- **服务和指令：** Intlayer 的 Angular 适配器无缝替换了 provider，允许您现有的模板管道和指令针对 Intlayer 字典解析字符串。
+- **构建时解析：** TypeScript 分析器识别 `instant/get` 调用，即使模板使用无法静态跟踪，回退修剪也能确保正确性。

package/docs/zh/compat/vue-i18n.md

@@ -0,0 +1,58 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "从 Vue I18n 迁移到 Intlayer"
+description: "了解如何使用兼容适配器将您的 Vue 应用程序从 vue-i18n 迁移到 Intlayer。"
+keywords:
+  - vue-i18n
+  - vue
+  - intlayer
+  - 迁移
+  - 兼容
+slugs:
+  - doc
+  - compatibility
+  - vue-i18n
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# 从 Vue I18n 迁移到 Intlayer
+
+如果您的 Vue 应用程序当前使用 `vue-i18n`，您可以迁移到 Intlayer，而无需重写组件或翻译 hook。Intlayer 提供了一个兼容适配器，完美地镜像 `vue-i18n` 的 API，同时在底层利用 Intlayer 的强大功能。
+
+## 操作步骤
+
+要开始使用，只需在您的项目中运行初始化命令：
+
+```bash
+npx intlayer init
+```
+
+在初始化期间，Intlayer 将设置您的配置文件（`intlayer.config.ts`）并为迁移做好项目准备。您只需将 Intlayer 插件添加到您的 Vite 配置中，即可自动将 `vue-i18n` 导入别名化。
+
+```typescript fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import vue from "@vitejs/plugin-vue";
+import vueI18nVitePlugin from "@intlayer/vue-i18n/plugin";
+
+export default defineConfig({
+  plugins: [vue(), vueI18nVitePlugin()],
+});
+```
+
+## 底层原理
+
+`vueI18nVitePlugin` 将模块别名注入到您的 bundler 中。代码库中对 `vue-i18n` 的任何导入都将被透明地重定向到 `@intlayer/vue-i18n`。
+
+**在底层，适配器原生处理复杂的 `vue-i18n` 语法：**
+
+- **插值与复数：** 解析 `{name}` 和列表 `{0}` 插值。管道复数（`"car | cars"`）根据位置语义转换为 Intlayer 枚举/复数节点。
+- **格式：** `d()` 和 `n()` 等函数在底层包装 `Intl`，遵循您选项中定义的 `datetimeFormats` 和 `numberFormats`。
+- **全局与本地状态：** `global.locale` 映射到由 Intlayer 客户端支持的 `WritableComputedRef`，因此响应性行为与预期完全一致（例如 `locale.value = 'fr'`）。
+- **指令：** `v-t` 指令已注册并正常运行。
+
+您的应用程序继续与之前完全相同地渲染，但内容由您的 Intlayer 字典提供支持，为您带来类型安全、更好的 bundle 优化和无缝的 CMS 集成。

package/docs/zh/compiler.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-09-09
-updatedAt: 2026-03-12
+updatedAt: 2026-06-23
 title: Intlayer 编译器 | 用于 i18n 的自动内容提取
 description: 使用 Intlayer 编译器自动化您的国际化流程。直接从组件中提取内容，实现 Vite、Next.js 等框架中更快速、更高效的 i18n。
 keywords:
@@ -60,6 +60,8 @@ author: aymericzip
 
 ## 使用方法
 
+> The quickest way to wire the compiler in is the interactive setup: run `npx intlayer init --interactive` and select **Compiler**. On Vite there is nothing to configure — the compiler is plugged in directly through the `intlayerCompiler()` plugin. On Next.js the command scaffolds the `babel.config.js` shown below. The non-interactive `intlayer init` leaves the compiler setup untouched.
+
 <Tabs>
  <Tab value='vite'>
 
@@ -79,12 +81,15 @@ npm install vite-intlayer
 
 ```ts fileName="vite.config.ts"
 import { defineConfig } from "vite";
-import { intlayer, intlayerCompiler } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 export default defineConfig({
   plugins: [
-    intlayer(),
-    intlayerCompiler(), // 添加编译器插件
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
   ],
 });
 ```

package/docs/zh/configuration.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-13
-updatedAt: 2026-05-12
+updatedAt: 2026-06-23
 title: 配置
 description: 了解如何为您的应用程序配置 Intlayer。了解可用于根据您的需求自定义 Intlayer 的各种设置和选项。
 keywords:
@@ -14,6 +14,12 @@ slugs:
   - concept
   - configuration
 history:
+  - version: 9.0.0
+    date: 2026-06-24
+    changes: "Add `enableProxy` option to the routing configuration"
+  - version: 8.10.0
+    date: 2026-06-17
+    changes: "向字典配置添加 `format` 选项"
   - version: 8.9.4
     date: 2026-05-12
     changes: "添加对 LM Studio 提供者的支持"
@@ -135,6 +141,7 @@ Intlayer 接受 JSON、JS、MJS 和 TS 配置文件格式：
 ````typescript fileName="intlayer.config.ts" codeFormat="typescript"
 import { Locales, type IntlayerConfig } from "intlayer";
 import { nextjsRewrite } from "intlayer/routing";
+import { syncJSON } from "@intlayer/sync-json-plugin";
 import { z } from "zod";
 
 /**
@@ -585,10 +592,38 @@ const config: IntlayerConfig = {
     }),
   },
 
+  /**
+   * 字典配置。
+   */
+  dictionary: {
+    /**
+     * 控制如何导入字典。
+     * - "static": 在构建时静态导入。
+     * - "dynamic": 使用 Suspense 动态导入。
+     * - "fetch": 通过实时同步 API 动态获取。
+     */
+    importMode: "static",
+
+    /**
+     * 项目中所有字典的默认消息格式。
+     * - 'intlayer': 原生 intlayer 格式 (默认)。
+     * - 'icu': ICU 消息格式。
+     * - 'i18next': i18next 格式。
+     * - 'vue-i18n': Vue I18n 格式。
+     * - 'po': GNU Gettext PO 格式。
+     */
+    format: "icu",
+  },
+
   /**
    * 插件配置。
    */
-  plugins: [],
+  plugins: [
+    syncJSON({
+      format: "icu",
+      source: ({ locale }) => `./messages/${locale}.json`,
+    }),
+  ],
 };
 
 export default config;
@@ -853,24 +888,40 @@ export default config;
 
 ---
 
+### 系统配置
+
+与 Intlayer 的内部路径和输出结果相关的设置。这些设置通常是内部的，用户通常不需要修改。
+
+| Field                     | Description                                     | Type     | Default                           | Example              | Note                                  |
+| ------------------------- | ----------------------------------------------- | -------- | --------------------------------- | -------------------- | ------------------------------------- |
+| `baseDir`                 | 项目的基础目录。                                | `string` | `process.cwd()`                   | `'/path/to/project'` | 用于解析所有 Intlayer 相关的目录。    |
+| `dictionariesDir`         | 存储本地化字典的目录路径。                      | `string` | `'.intlayer/dictionary'`          |                      |                                       |
+| `moduleAugmentationDir`   | 模块增强的目录，允许更好的 IDE 建议和类型检查。 | `string` | `'.intlayer/types'`               | `'intlayer-types'`   | 确保在 `tsconfig.json` 中包含此目录。 |
+| `unmergedDictionariesDir` | 存储未合并字典的目录。                          | `string` | `'.intlayer/unmerged_dictionary'` |                      |                                       |
+| `typesDir`                | 存储字典类型的目录。                            | `string` | `'.intlayer/types'`               |                      |                                       |
+| `mainDir`                 | 存储主应用程序文件的目录。                      | `string` | `'.intlayer/main'`                |                      |                                       |
+| `configDir`               | 存储配置文件的目录。                            | `string` | `'.intlayer/config'`              |                      |                                       |
+| `cacheDir`                | 存储缓存文件的目录。                            | `string` | `'.intlayer/cache'`               |                      |                                       |
+
 ### 字典配置 (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`                      | 控制自动填充 (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` 等。 |
+| `format`                    | 项目中所有字典的默认消息格式。                                                               | `'intlayer'` &#124; <br/> `'icu'` &#124; <br/> `'i18next'` &#124; <br/> `'vue-i18n'` &#124; <br/> `'po'`        | `'intlayer'` | `'icu'`                                                                                     | • `'intlayer'`: 原生 intlayer 格式。<br/>• `'icu'`: ICU 消息格式。<br/>• `'i18next'`: i18next 格式。<br/>• `'vue-i18n'`: Vue I18n 格式。<br/>• `'po'`: GNU Gettext PO 格式。                                                                                                                                |
+| `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` 示例**:
 
@@ -960,22 +1011,6 @@ Intlayer 支持多个 AI 提供商，以提供最大的灵活性。当前支持
 
 ---
 
-### 系统配置 (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 编译器的设置，该编译器直接从组件中收集字典。

package/docs/zh/custom_domains.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-04-02
-updatedAt: 2026-04-02
+updatedAt: 2026-06-23
 title: 自定义域名
 description: 了解如何在 Intlayer 中配置基于域名的语言路由，以便从专用主机名提供不同的语言版本。
 keywords:
@@ -172,10 +172,16 @@ GET intlayer.zh/about
 
 ```typescript fileName="vite.config.ts"
 import { defineConfig } from "vite";
-import { intlayerProxy } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 export default defineConfig({
-  plugins: [intlayerProxy()],
+  plugins: [
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
+  ],
 });
 ```
 

package/docs/zh/custom_url_rewrites.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-13
-updatedAt: 2026-01-26
+updatedAt: 2026-06-23
 title: 自定义 URL 重写
 description: 了解如何在 Intlayer 中配置并使用自定义 URL 重写，以定义特定于 locale 的路径。
 keywords:
@@ -228,21 +228,19 @@ Intlayer 为所有流行框架提供格式化器：
 - `reactRouterRewrite`：用于 React Router。支持 `:slug` 和 `*`（0+）。
 - `vueRouterRewrite`：用于 Vue Router 4。支持 `:slug`、`:slug?`（0-1）、`:slug*`（0+）和 `:slug+`（1+）。
 - `solidRouterRewrite`：用于 Solid Router。支持 `:slug` 和 `*slug`（0+）。
-  /// - `tanstackRouterRewrite`: For TanStack Router。支持 `$slug` 和 `*`（0+）。
-  /// - `nuxtRewrite`: For Nuxt 3。支持 `[slug]` 和 `[...slug]`（0+）。
-  /// - `viteRewrite`: Generic formatter for any Vite-based project。规范化用于 Vite 代理的语法。
-  ///
-  /// ### 高级模式
-  ///
-  /// Intlayer 在内部将这些模式规范化为统一语法，允许复杂的路径匹配与生成：
-  ///
-  /// - **可选段**：`[[optional]]`（SvelteKit）或 `:slug?`（Vue/React）受到支持。
-  /// - **捕获全部（零个或多个）**：`[[...slug]]`（Next.js）、`[...path]`（SvelteKit/Nuxt）或 `*`（React/TanStack）允许匹配多个段。
-  /// - **必须捕获（一个或多个）**：`[...slug]`（Next.js）或 `:slug+`（Vue）确保至少存在一个段。
-  ///
-  /// ## 客户端 URL 校正：`useRewriteURL`
-  ///
-  ///
+- `tanstackRouterRewrite`: For TanStack Router。支持 `$slug` 和 `*`（0+）。
+- `nuxtRewrite`: For Nuxt 3。支持 `[slug]` 和 `[...slug]`（0+）。
+- `viteRewrite`: Generic formatter for any Vite-based project。规范化用于 Vite 代理的语法。
+
+### 高级模式
+
+Intlayer 在内部将这些模式规范化为统一语法，允许复杂的路径匹配与生成：
+
+- **可选段**：`[[optional]]`（SvelteKit）或 `:slug?`（Vue/React）受到支持。
+- **捕获全部（零个或多个）**：`[[...slug]]`（Next.js）、`[...path]`（SvelteKit/Nuxt）或 `*`（React/TanStack）允许匹配多个段。
+- **必须捕获（一个或多个）**：`[...slug]`（Next.js）或 `:slug+`（Vue）确保至少存在一个段。
+
+## 客户端 URL 校正：`useRewriteURL`
 
 为确保浏览器的地址栏始终反映“友好”的本地化 URL，Intlayer 提供了 `useRewriteURL` 钩子。该钩子在用户进入一个规范路径时，会静默地使用 `window.history.replaceState` 更新 URL。
 
@@ -344,10 +342,16 @@ export function middleware(request: NextRequest) {
 
 ```typescript fileName="vite.config.ts"
 import { defineConfig } from "vite";
-import { intlayerProxy } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 export default defineConfig({
-  plugins: [intlayerProxy()],
+  plugins: [
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
+  ],
 });
 ```