@intlayer/docs 9.0.0-canary.6 → 9.0.0-canary.8

package/docs/zh/intlayer_with_astro_react.md

@@ -541,6 +541,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Babel 编译器'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 更新您的 `vite.config.ts` 以包含 `intlayerCompiler` 插件：
 
 ```ts fileName="vite.config.ts"
@@ -550,7 +552,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // 添加编译器插件
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/zh/intlayer_with_astro_solid.md

@@ -541,6 +541,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Babel 编译器'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 更新您的 `vite.config.ts` 以包含 `intlayerCompiler` 插件：
 
 ```ts fileName="vite.config.ts"
@@ -550,7 +552,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // 添加编译器插件
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/zh/intlayer_with_astro_svelte.md

@@ -545,6 +545,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Babel 编译器'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 更新您的 `vite.config.ts` 以包含 `intlayerCompiler` 插件：
 
 ```ts fileName="vite.config.ts"
@@ -554,7 +556,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // 添加编译器插件
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/zh/intlayer_with_astro_vanilla.md

@@ -519,6 +519,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Babel 编译器'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 更新您的 `vite.config.ts` 以包含 `intlayerCompiler` 插件：
 
 ```ts fileName="vite.config.ts"
@@ -528,7 +530,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // 添加编译器插件
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/zh/intlayer_with_astro_vue.md

@@ -563,6 +563,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Babel 编译器'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 更新您的 `vite.config.ts` 以包含 `intlayerCompiler` 插件：
 
 ```ts fileName="vite.config.ts"
@@ -572,7 +574,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // 添加编译器插件
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/zh/intlayer_with_nextjs_16.md

@@ -993,6 +993,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Babel 编译器'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 ```bash packageManager="npm"
 npm install @intlayer/babel --save-dev
 ```

package/docs/zh/intlayer_with_nextjs_compiler.md

@@ -583,6 +583,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Babel 编译器'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 ```bash packageManager="npm"
 npm install @intlayer/babel --save-dev
 ```

package/docs/zh/intlayer_with_react_native+expo.md

@@ -258,6 +258,8 @@ export default RootLayout;
 在项目中任意位置（通常在 `src/` 目录中）创建**内容声明**文件，使用 Intlayer 支持的任何扩展格式：
 
 - `.content.json`
+- `.content.jsonc`
+- `.content.json5`
 - `.content.ts`
 - `.content.tsx`
 - `.content.js`
@@ -265,7 +267,10 @@ export default RootLayout;
 - `.content.mjs`
 - `.content.mjx`
 - `.content.cjs`
-- `.content.cjx`
+- `.content.md`
+- `.content.mdx`
+- `.content.yaml`
+- `.content.yml`
 - 等等
 
 > **Expo Router (web): 请将 `.content.*` 文件保留在 `app/` 目录之外。** Expo Router 会将 `app/` 内的每个 JavaScript/TypeScript 文件视为一个路由。在 web 上，它的路由发现会直接扫描文件系统，并且 **不** 遵循 Metro 的 `resolver.blockList`，因此同位置的 `*.content.ts` 会被注册为一个路由。像 `app/(tabs)/_layout.content.ts` 这样的文件甚至会被解析为布局（`.content` 部分被读取为平台后缀），这会与实际的 `_layout.tsx` 发生冲突并抛出错误：

package/docs/zh/intlayer_with_react_router_v7.md

@@ -339,6 +339,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Babel 编译器'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 更新您的 `vite.config.ts` 以包含 `intlayerCompiler` 插件：
 
 ```ts fileName="vite.config.ts"
@@ -348,7 +350,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // 添加编译器插件
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/zh/intlayer_with_react_router_v7_fs_routes.md

@@ -294,6 +294,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Babel 编译器'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 更新您的 `vite.config.ts` 以包含 `intlayerCompiler` 插件：
 
 ```ts fileName="vite.config.ts"
@@ -303,7 +305,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // 添加编译器插件
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/zh/intlayer_with_storybook.md

@@ -103,7 +103,13 @@ const config: StorybookConfig = {
     } as const;
 
     const viteConfig = defineConfig(() => ({
-      plugins: [intlayer()],
+      plugins: [
+        intlayer({
+          proxy: {
+            ignore: (req) => req.url?.startsWith("/api"),
+          },
+        }),
+      ],
     }));
 
     return mergeConfig(baseConfig, viteConfig(env));

package/docs/zh/intlayer_with_svelte_kit.md

@@ -229,14 +229,17 @@ goto(localizedPath); // 根据语言环境导航到 /en/about 或 /fr/about
 
 ```ts fileName="vite.config.ts"
 import { defineConfig } from "vite";
-import { intlayer, intlayerProxy } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 import { sveltekit } from "@sveltejs/kit/vite";
 
 // https://vitejs.dev/config/
 export default defineConfig({
   plugins: [
-    intlayerProxy(), // should be placed first
-    intlayer(),
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
     sveltekit(),
   ],],
 });
@@ -334,6 +337,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Babel 编译器'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 更新您的 `vite.config.ts` 以包含 `intlayerCompiler` 插件：
 
 ```ts fileName="vite.config.ts"
@@ -343,7 +348,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // 添加编译器插件
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/zh/intlayer_with_vite+preact.md

@@ -495,6 +495,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Babel 编译器'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 更新您的 `vite.config.ts` 以包含 `intlayerCompiler` 插件：
 
 ```ts fileName="vite.config.ts"
@@ -504,7 +506,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // 添加编译器插件
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/zh/intlayer_with_vite+react.md

@@ -225,14 +225,17 @@ const App: FC = () => (
 ```typescript {3,7} fileName="vite.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
 import { defineConfig } from "vite";
 import react from "@vitejs/plugin-react-swc";
-import { intlayer, intlayerProxy } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 // https://vitejs.dev/config/
 export default defineConfig({
   plugins: [
-    intlayerProxy(), // should be placed first
     react(),
-    intlayer(),
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
   ],
 });
 ```
@@ -536,6 +539,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Babel 编译器'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 更新您的 `vite.config.ts` 以包含 `intlayerCompiler` 插件：
 
 ```ts fileName="vite.config.ts"
@@ -545,7 +550,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // 添加编译器插件
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/zh/intlayer_with_vite+svelte.md

@@ -460,14 +460,17 @@ $: content = useIntlayer('app', locale);
 ```typescript {3,7} fileName="vite.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
 import { defineConfig } from "vite";
 import { svelte } from "@sveltejs/vite-plugin-svelte";
-import { intlayer, intlayerProxy } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 // https://vitejs.dev/config/
 export default defineConfig({
   plugins: [
-    intlayerProxy(), // should be placed first
     svelte(),
-    intlayer(),
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
   ],
 });
 ```
@@ -598,6 +601,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Babel 编译器'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 更新您的 `vite.config.ts` 以包含 `intlayerCompiler` 插件：
 
 ```ts fileName="vite.config.ts"
@@ -607,7 +612,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // 添加编译器插件
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/zh/intlayer_with_vite+vue.md

@@ -636,14 +636,17 @@ import LocaleSwitcher from "@components/LocaleSwitcher.vue";
 ```typescript {3,7} fileName="vite.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
 import { defineConfig } from "vite";
 import vue from "@vitejs/plugin-vue";
-import { intlayer, intlayerProxy } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 // https://vitejs.dev/config/
 export default defineConfig({
   plugins: [
-    intlayerProxy(), // should be placed first
     vue(),
-    intlayer(),
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
   ],
 });
 ```
@@ -967,6 +970,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Babel 编译器'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 更新您的 `vite.config.ts` 以包含 `intlayerCompiler` 插件：
 
 ```ts fileName="vite.config.ts"
@@ -976,7 +981,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // 添加编译器插件
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/zh/packages/@intlayer_babel/export.md

@@ -0,0 +1,131 @@
+---
+createdAt: 2026-06-25
+updatedAt: 2026-06-25
+title: "@intlayer/babel 包文档"
+description: 用于 Intlayer 的 Babel 插件，处理构建期间的内容提取、导入优化、删除未使用字段以及混淆字段名称。
+keywords:
+  - "@intlayer/babel"
+  - babel
+  - plugin
+  - 国际化
+  - i18n
+  - 编译器
+  - 优化
+  - 清除
+  - 压缩
+slugs:
+  - doc
+  - packages
+  - "@intlayer/babel"
+  - export
+history:
+  - version: 9.0.0
+    date: 2026-06-25
+    changes: "统一所有导出的文档"
+author: aymericzip
+---
+
+# @intlayer/babel 包
+
+`@intlayer/babel` 包为 Intlayer 提供了一套专业的 Babel 插件。这些插件涵盖了整个构建生命周期：提取内容声明、将 `useIntlayer` / `getIntlayer` 调用重写为优化后的字典导入、清除未使用的字段以及压缩字段名称。
+
+## 安装
+
+```bash
+npm install @intlayer/babel
+```
+
+## 导出
+
+导入：
+
+```ts
+import { ... } from "@intlayer/babel";
+```
+
+---
+
+### 插件
+
+| 函数 / 类                      | 描述                                                                                                                                       |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `intlayerExtractBabelPlugin`   | Babel 插件，可从源文件中提取可翻译内容并自动注入 `useIntlayer` / `getIntlayer` 钩子。设计用于 Next.js 和基于 Babel 的构建工具。            |
+| `intlayerOptimizeBabelPlugin`  | Babel 插件，可转换 `useIntlayer` 和 `getIntlayer` 调用，并将其导入重写为优化后的 JSON 字典导入（静态、动态或通过 fetch）。                 |
+| `intlayerPurgeBabelPlugin`     | Babel 插件，可分析源文件并重写编译后的字典 JSON 文件，以移除未使用的字段（`build.purge`）或将其重命名为简短别名（`build.minify`）。        |
+| `intlayerMinifyBabelPlugin`    | Babel 插件，可重写源文件以使用在混淆/压缩阶段分配的简短字段别名（例如 `content.title` ← `content.a`）。依赖于 `intlayerPurgeBabelPlugin`。 |
+| `makeFieldRenameBabelPlugin`   | 工厂函数，用于生成一个 Babel 插件，根据 `PruneContext` 中填充的 `dictionaryKeyToFieldRenameMap` 重命名源文件中的字典内容字段访问。         |
+| `makeUsageAnalyzerBabelPlugin` | 工厂函数，用于生成一个 Babel 插件，以分析源代码中 `useIntlayer` / `getIntlayer` 的使用情况，并在共享的 `PruneContext` 中聚合字段使用数据。 |
+| `getSharedPruneContext`        | 辅助函数，用于返回指定根目录的共享 `PruneContext` 对象，如果尚未初始化，则返回 `null`。                                                    |
+
+---
+
+### 插件配置工具
+
+| 函数                       | 描述                                                                                                                |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `getExtractPluginOptions`  | 加载 Intlayer 配置并返回准备好与 `intlayerExtractBabelPlugin` 配合使用的 `ExtractPluginOptions`。                   |
+| `getOptimizePluginOptions` | 加载 Intlayer 配置和编译好的字典，并返回准备好与 `intlayerOptimizeBabelPlugin` 配合使用的 `OptimizePluginOptions`。 |
+| `getPurgePluginOptions`    | 加载 Intlayer 配置并返回准备好与 `intlayerPurgeBabelPlugin` 配合使用的 `PurgePluginOptions`。                       |
+| `getMinifyPluginOptions`   | 加载 Intlayer 配置并返回准备好与 `intlayerMinifyBabelPlugin` 配合使用的 `MinifyPluginOptions`。                     |
+
+---
+
+### 类型
+
+| 类型                    | 描述                                                                          |
+| ----------------------- | ----------------------------------------------------------------------------- |
+| `CompilerMode`          | 编译器模式：用于带 HMR 支持的开发的 `'dev'`，或用于生产环境构建的 `'build'`。 |
+| `ExtractPluginOptions`  | `intlayerExtractBabelPlugin` 的选项：文件列表、配置、`onExtract` 回调函数等。 |
+| `ExtractResult`         | 提取结果：字典键、文件路径、内容和语言区域。                                  |
+| `OptimizePluginOptions` | `intlayerOptimizeBabelPlugin` 的选项：字典路径、导入模式、每字典模式映射等。  |
+| `PurgePluginOptions`    | `intlayerPurgeBabelPlugin` 的选项：根目录、清除/混淆/优化标志、组件文件列表。 |
+| `MinifyPluginOptions`   | `intlayerMinifyBabelPlugin` 的选项：根目录、混淆/优化/editorEnabled 标志。    |
+| `PruneContext`          | 分析和清除插件之间的共享状态：字段使用映射、重命名映射等。                    |
+| `DictionaryFieldUsage`  | 单个字典的字段使用结果：`Set<string>`，在静态分析不确定时为 `'all'`。         |
+| `NestedRenameEntry`     | 重命名树中的节点：`shortName` 和子节点映射。                                  |
+| `NestedRenameMap`       | 重命名树中的一级：`Map<string, NestedRenameEntry>`。                          |
+| `CompatCallerConfig`    | 用于兼容包（`compat-adapter`）的兼容使用分析器配置（调用者名称和处理选项）。  |
+| `ScriptBlock`           | 从 SFC 文件（Vue 或 Svelte）中提取的脚本块：内容、起始偏移量和结束偏移量。    |
+
+---
+
+### 工具函数
+
+| 函数                              | 描述                                                                                                          |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `generateShortFieldName`          | 将整数（从零开始）转换为简短的字母标识符：`0` → `'a'`，`25` → `'z'`，`26` → `'aa'` 等。                       |
+| `buildNestedRenameMapFromContent` | 从编译好的字典的内容值中递归构建 `NestedRenameMap`，并遵循 Intlayer 节点结构（translation、enumeration 等）。 |
+| `createPruneContext`              | 创建一个初始化为默认值的新的空 `PruneContext` 对象。                                                          |
+| `extractScriptBlocks`             | 从 SFC 文件（Vue / Svelte）中提取 `<script>` 块，以便进行后续的 Babel 分析。                                  |
+| `BABEL_PARSER_OPTIONS`            | 表示覆盖支持的框架（React/Vue/Svelte/Angular/...）的 Babel 解析器选项的常量。                                 |
+| `INTLAYER_CALLER_NAMES`           | 原始 Intlayer 调用者名称的常量列表：`['useIntlayer', 'getIntlayer']`。                                        |
+
+---
+
+## 使用示例
+
+```js
+// babel.config.js
+const {
+  intlayerExtractBabelPlugin,
+  intlayerPurgeBabelPlugin,
+  intlayerMinifyBabelPlugin,
+  intlayerOptimizeBabelPlugin,
+  getExtractPluginOptions,
+  getPurgePluginOptions,
+  getMinifyPluginOptions,
+  getOptimizePluginOptions,
+} = require("@intlayer/babel");
+
+module.exports = {
+  presets: ["next/babel"],
+  plugins: [
+    [intlayerExtractBabelPlugin, getExtractPluginOptions()],
+    [intlayerPurgeBabelPlugin, getPurgePluginOptions()],
+    [intlayerMinifyBabelPlugin, getMinifyPluginOptions()],
+    [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()],
+  ],
+};
+```
+
+> **注意：** `intlayerPurgeBabelPlugin` 必须在 `intlayerMinifyBabelPlugin` **之前**声明，因为后者需要读取前者构建的重命名映射。此外，这两者之前都必须先声明 `intlayerOptimizeBabelPlugin`，以便它在重写 `useIntlayer` 调用之前能够检测到字典键。

package/docs/zh/packages/vite-intlayer/intlayerCompiler.md

@@ -0,0 +1,120 @@
+---
+createdAt: 2026-06-25
+updatedAt: 2026-06-25
+title: intlayerCompiler Vite 插件文档 | vite-intlayer
+description: Vite 插件，用于在构建/转换时从组件文件中提取内联 Intlayer 内容声明并将其写入字典 JSON 文件。
+keywords:
+  - intlayerCompiler
+  - vite
+  - 插件
+  - 编译器
+  - 内容
+  - 字典
+  - 国际化
+  - i18n
+slugs:
+  - doc
+  - packages
+  - vite-intlayer
+  - intlayerCompiler
+history:
+  - version: 9.0.0
+    date: 2026-06-25
+    changes: "集成到 intlayer() 中；初始化文档"
+author: aymericzip
+---
+
+# intlayerCompiler
+
+`intlayerCompiler` 是一个 Vite 插件，它扫描组件源文件以查找**内联 Intlayer 内容声明**（即直接在组件内部定义的内容，而不是在单独的 `.content.ts` 文件中），并在转换（transform）阶段将它们写入字典 JSON 文件中。
+
+> **自 Intlayer v9 起**，当您的 Intlayer 配置中同时设置了 `compiler.enabled` 为 `true` 且设置了 `compiler.output` 时，`intlayerCompiler` 会自动包含在主 [`intlayer()`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/vite-intlayer/intlayer.md) 插件中。只有当您希望完全控制编译器特定配置时，才需要单独注册它。
+
+## 用法
+
+### 作为 `intlayer()` 的一部分（推荐，v9+）
+
+通过您的 Intlayer 配置启用编译器：
+
+```ts
+// intlayer.config.ts
+import { defineConfig } from "intlayer";
+
+export default defineConfig({
+  compiler: {
+    enabled: true,
+    output: "./src/dictionaries", // 提取的字典写入的位置
+  },
+});
+```
+
+然后使用标准插件，无需额外交册：
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [intlayer()],
+});
+```
+
+### 独立使用（需要时）
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayerCompiler } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [intlayerCompiler()],
+});
+```
+
+## 选项
+
+```ts
+import type { IntlayerCompilerOptions } from "vite-intlayer";
+```
+
+| 选项             | 类型                      | 描述                                                                  |
+| ---------------- | ------------------------- | --------------------------------------------------------------------- |
+| `configOptions`  | `GetConfigurationOptions` | 转发给 `getConfiguration()` 的 Intlayer 配置覆盖项。                  |
+| `compilerConfig` | `Partial<CompilerConfig>` | 编译器特定配置部分的覆盖项（例如 `enabled`, `output`, `filesList`）。 |
+
+### 示例
+
+```ts
+intlayerCompiler({
+  configOptions: { configFile: "./config/intlayer.config.ts" },
+  compilerConfig: { enabled: true, output: "./src/dictionaries" },
+});
+```
+
+## 工作原理
+
+### 转换（Transform）阶段
+
+对于每个与 `compiler.filesList` 匹配的源文件，编译器插件执行以下操作：
+
+1. 将文件内容传递给 `@intlayer/babel` 中的 `extractContent`。
+2. 对找到的每个声明调用 `onExtract`，这会将生成的字典 JSON 写入 `compiler.output`。
+3. 返回转换后的源代码，内联声明已替换为标准的 `useIntlayer('key')` / `getIntlayer('key')` 调用。
+
+支持的文件类型：`.ts`, `.tsx`, `.js`, `.jsx`, `.vue`, `.svelte`, `.astro`。
+
+### HMR（热模块替换）
+
+在开发模式下保存组件文件时，编译器：
+
+1. 通过 Vite 的 `handleHotUpdate` 钩子检测文件更改。
+2. 从更新后的文件中重新提取内容。
+3. 写入更新后的字典 JSON。
+4. 触发页面完全重新加载（`server.ws.send({ type: 'full-reload' })`）。
+
+500 毫秒的防抖（debounce）可防止字典写入本身（这也会触发文件更改事件）导致无限的重新提取循环。
+
+### 去重（Deduplication）
+
+`intlayerCompiler` 使用与其他捆绑插件相同的 `createPrimaryInstanceGuard` 去重机制。当同时存在 `intlayer()`（已捆绑编译器）和手动 `intlayerCompiler()` 调用时，仅运行第一个注册 ins — 不会重复写入任何字典。