@intlayer/docs 9.1.3 → 9.3.0

package/docs/zh/analytics.md

@@ -0,0 +1,222 @@
+---
+createdAt: 2026-07-08
+updatedAt: 2026-07-08
+title: Intlayer Analytics | 跟踪内容曝光并运行 A/B 测试
+description: 探索 @intlayer/analytics 如何跟踪页面/区域设置浏览量和内容曝光，以及如何使用它对您的 Intlayer 内容运行 A/B 测试。
+keywords:
+  - 分析 (Analytics)
+  - A/B 测试
+  - 受众 (Audience)
+  - 国际化 (Internationalization)
+  - 文档
+  - Intlayer
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - concept
+  - analytics
+history:
+  - version: 9.0.0
+    date: 2026-07-08
+    changes: "Init doc — @intlayer/analytics 包，Provider/Node级别跟踪，A/B 测试，仪表板"
+author: aymericzip
+---
+
+# Intlayer Analytics 文档
+
+`@intlayer/analytics` 是一个可选的配套包，它可以告诉您**哪些内容实际显示给了您的访问者** —— 哪个页面、哪个区域设置（locale）以及哪个特定的翻译内容片段 —— 从而让您能够了解您的受众并**对内容运行 A/B 测试**。
+
+## 目录
+
+<TOC/>
+
+---
+
+## 跟踪内容
+
+`@intlayer/analytics` 会批处理三种类型的匿名事件：
+
+| 事件 (Event)       | 捕获位置                               | 它的作用                                                                                                           |
+| ------------------ | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `page_view`        | Provider 级别 (`IntlayerProvider`)     | 会话在首次加载、路由更改或切换区域设置时查看了哪个页面和区域设置。                                                 |
+| `content_exposure` | Node 级别 (`useIntlayer` / 解释器插件) | 实际解析并显示了哪个字典键 (dictionary key) / 键路径 —— 并且，如果它是实验的一部分，具体是哪个**变体 (variant)**。 |
+| `conversion`       | 任何调用 `useConversion()` 的地方      | 将达成的目标（注册、点击、购买等）归因于该会话所暴露的 A/B 变体。                                                  |
+
+事件收集在内存中，并作为**大约每 20 秒一次的单一批量请求**发送 —— 而不是在每次击键或渲染时发送 —— 因此分析功能永远不会影响首次渲染时间，也不会在每次交互时增加网络请求。
+
+## 它如何为内容的 A/B 测试提供支持
+
+Intlayer 已经允许您声明内容 [变体 (Variants)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dynamic_dictionaries/index.md)（例如，一个具有 `control` 和 `black_friday` 变体的 `hero-banner` 字典）。`@intlayer/analytics` 完成了整个循环：
+
+1. `getVariant(experimentKey, variants)` 确定性地将每个匿名会话分配给一个变体 —— 它是会话 ID 和实验键 (experiment key) 的纯函数，因此分配在**整个会话期间保持稳定**，并且在首次渲染之前**不需要服务器往返**（无闪烁，无布局偏移）。
+2. 每个 `content_exposure` 事件都会携带所显示的 `variant`。
+3. `useConversion()` 允许您将目标（例如 `"cta_click"`）归因于该变体。
+4. 仪表板的实验结果端点 (endpoint) 比较各变体的转化率，包括统计显著性（z 检验）。
+
+## 安装
+
+`@intlayer/analytics` 是一个**对等 (peer)、可选**的依赖项 —— 框架包永远不会自动安装它。请将其与 `intlayer` 一起添加：
+
+```bash packageManager="npm"
+npm install @intlayer/analytics
+```
+
+```bash packageManager="yarn"
+yarn add @intlayer/analytics
+```
+
+```bash packageManager="pnpm"
+pnpm add @intlayer/analytics
+```
+
+```bash packageManager="bun"
+bun add @intlayer/analytics
+```
+
+如果您不安装它，每个集成点都将解析为空操作 (no-op) —— 请参阅下文的[未安装时零成本](#未安装时零成本)。
+
+## 配置
+
+Analytics **重用了现有的 `editor` 配置块** —— 没有单独的 `analytics` 配置模式需要填写：
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  editor: {
+    backendURL: "https://back.intlayer.org", // 也用作分析数据摄取端点
+    clientId: "your-client-id", // 也用作分析项目密钥
+    clientSecret: "your-client-secret",
+  },
+};
+
+export default config;
+```
+
+- `editor.backendURL` — 发送分析事件的基本 URL (`POST {backendURL}/api/analytics/events`)。
+- `editor.clientId` — 归因于每个摄取事件的公共项目密钥。它也充当**启用开关**：在配置 `clientId` 之前，分析将保持完全禁用（并被摇树优化去除，见下文）。
+
+如果您自托管 Intlayer，分析会自动指向您自己的实例，因为它共享 `editor.backendURL`。
+
+## 框架支持
+
+Analytics 已连接到 `react-intlayer` 共享的 `IntlayerProvider` 中，因此今天只要使用该 provider 的任何地方都可以使用它：
+
+| 框架                                                     | 状态                                                                       |
+| -------------------------------------------------------- | -------------------------------------------------------------------------- |
+| React                                                    | ✅ 可用                                                                    |
+| Next.js (`next-intlayer`)                                | ✅ 可用 (通过 `react-intlayer`)                                            |
+| React Native / Expo (`react-native-intlayer`)            | ✅ 可用 (通过 `react-intlayer`)                                            |
+| Vue, Svelte, Angular, Solid, Preact, Lit, Astro, Vanilla | 🚧 计划中 — 相同的客户端，遵循 `@intlayer/editor` 推出模式的提供商级别绑定 |
+
+## 使用方法
+
+### 自动 Provider 级别跟踪
+
+无需更改代码。一旦安装了 `@intlayer/analytics` 并配置了 `editor.clientId`，`IntlayerProvider` 会自动：
+
+- 在挂载时初始化分析客户端，
+- 在初始加载时记录一个 `page_view`，
+- 在每次更改区域设置时记录一个 `page_view`，
+- 启动约 20 秒的刷新循环，并在卸载/关闭选项卡时刷新任何剩余事件（通过 `navigator.sendBeacon`，回退至 `fetch(..., { keepalive: true })`）。
+
+### 自动 Node 级别跟踪
+
+每次 `useIntlayer` 解析用于显示的内容片段时，解释器都会为该确切的 `dictionaryKey` + 键路径 + 区域设置报告一个 `content_exposure` 事件 —— 同样，无需更改代码。在刷新窗口内同一节点的重复曝光会合并为一个带有 `count`（计数）的事件，因此重新渲染 50 次的列表不会发送 50 个事件。
+
+### 跟踪 A/B 测试的转化
+
+使用 `useConversion()` 将目标归因于会话看到的变体：
+
+```tsx fileName="CTAButton.tsx" codeFormat="tsx"
+import { useConversion } from "react-intlayer";
+
+const CTAButton = () => {
+  const trackConversion = useConversion();
+
+  return (
+    <button
+      onClick={() =>
+        trackConversion({
+          experimentKey: "homepage-hero",
+          variant: "black_friday",
+          goal: "cta_click",
+        })
+      }
+    >
+      开始使用
+    </button>
+  );
+};
+```
+
+### 在客户端解析变体
+
+```tsx fileName="useHeroVariant.ts" codeFormat="tsx"
+import { getGlobalAnalyticsClient } from "@intlayer/analytics/client";
+
+const client = getGlobalAnalyticsClient();
+const variant = client?.getVariant("homepage-hero", [
+  "control",
+  "black_friday",
+]);
+```
+
+## 隐私与性能
+
+- **设计上匿名**：会话由轮换 ID 标识；后端永远只存储该 ID 的 **SHA-256 哈希值** —— 从不存储原始 ID，从不存储 IP 地址。
+- **位置是粗略的**：只有一个国家/地区代码，该代码从 CDN 地理位置标头（`cf-ipcountry`、`x-vercel-ip-country` 等）派生 —— 不会读取或存储 IP。
+- **默认情况下 URL 排除搜索参数**，因此永远不会捕获查询字符串。
+- **采样**：`sampleRate` 允许您在高流量应用程序中仅保留一小部分内容曝光事件。
+- **批处理**：大约每 20 秒发送一个请求 (`flushInterval`)，或者如果缓冲区满了则提前发送 (`maxBufferSize`) —— 永远不会每个事件发送一个请求。
+
+### 未安装时零成本
+
+`@intlayer/analytics` 遵循与 `@intlayer/editor` 完全相同的可选依赖模式：
+
+- 每个集成点通过**包裹在 `try/catch` 中的动态 `import()`** 加载包 —— 从未安装 `@intlayer/analytics` 的应用程序永远不会支付包大小或运行时成本，也永远不会看到错误；
+- 一个编译时环境变量（`INTLAYER_ANALYTICS_ENABLED`），当没有配置 `editor.clientId` 时，它会由 `@intlayer/config` 自动设置为 `'false'`，允许打包器 (bundlers) **将整个集成作为死代码消除 (dead-code-eliminate)**；
+- 分析在 Intlayer 编辑器/CMS 预览 iframe 中被禁用，因此编辑器会话永远不会算作真实流量。
+
+## 仪表板：Analytics 页面
+
+一旦您的项目收集了事件，[Intlayer 仪表板](https://app.intlayer.org/analytics) 中的 **Analytics（分析）** 页面（选择项目后在侧边栏中可见）会显示：
+
+- **活跃用户** — 选定滚动窗口（7 / 30 / 90 天）内的独立访客。
+- **今日用户** 和 **过去 7 天的用户**。
+- 选定窗口内的 **页面浏览量**。
+- 每日独立访客的 **演变图**。
+- **区域设置 (Locales)** 和 **位置 (Location)** 细分选项卡，按区域设置和国家/地区对您的受众进行排名。
+
+## 后端 API 参考
+
+所有读取端点都需要身份验证；数据摄取是公开的，并且由主体中的 `clientId` 进行归因。
+
+| 方法 (Method) | 端点 (Endpoint)                             | 描述                                                       |
+| ------------- | ------------------------------------------- | ---------------------------------------------------------- |
+| `POST`        | `/api/analytics/events`                     | 摄取一批事件（公开，由主体中的 `clientId` 归因）。         |
+| `GET`         | `/api/analytics/overview`                   | 认证项目的页面/区域设置总数。                              |
+| `GET`         | `/api/analytics/audience?days=30`           | 独立访客，页面浏览量，每日序列，区域设置 + 国家/地区分类。 |
+| `GET`         | `/api/analytics/content-stats`              | 每个内容的曝光总数，按字典键 / 键路径 / 区域设置分组。     |
+| `GET`         | `/api/analytics/experiments/:experimentKey` | A/B 实验中每个变体的转化率和统计显著性。                   |
+
+您还可以使用 [CMS SDK](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_CMS.md) 以编程方式调用这些端点：
+
+```ts fileName="analytics.ts"
+import { createIntlayerCMS } from "@intlayer/api";
+import { analyticsEndpoint } from "@intlayer/api/analytics";
+
+const cms = createIntlayerCMS();
+
+const { data: audience } = await analyticsEndpoint(cms).getAudience(30);
+```
+
+## 有用的链接
+
+- [动态字典 - 集合与变体 (Collections & Variants)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dynamic_dictionaries/index.md)
+- [Intlayer CMS - CMS SDK](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_CMS.md)
+- [Intlayer 可视化编辑器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_visual_editor.md)
+- [配置参考](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md)
+- [自托管指南](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/self_hosting.md)

package/docs/zh/autoFill.md

@@ -75,11 +75,30 @@ Intlayer 还将考虑以下自动填充指令：
 
 使用路径选项写入另一个文件时，填充机制通过内容声明文件之间的 _主从_ 关系工作。主（master）文件作为真实来源，当它被更新时，Intlayer 将自动将这些更改应用到由路径指定的派生（填充）声明文件。
 
-# 自动填充内容声明文件翻译
+### 按语言环境自定义
 
-**自动填充内容声明文件** 是加快开发工作流程的一种方式。
+您也可以使用对象为每个语言环境自定义行为：
 
-自动填充机制通过内容声明文件之间的 _主从_ 关系来实现。当主（master）文件被更新时，Intlayer 会自动将这些更改应用到派生的（自动填充的）声明文件中。
+```ts fileName="intlayer.config.ts"
+const config: IntlayerConfig = {
+  content: {
+    internationalization: {
+      locales: [Locales.ENGLISH, Locales.FRENCH, Locales.POLISH],
+      defaultLocale: Locales.ENGLISH,
+      requiredLocales: [Locales.ENGLISH], // 建议设置以避免在 t 函数中出现"Property 'pl' is missing in type '{ en: string; xxx }"错误
+    },
+  },
+  dictionary: {
+    fill: {
+      en: true, // 为英文填充并编辑当前文件
+      fr: "./translations/fr.json", // 为法文创建单独的文件
+      es: false, // 禁用西班牙文的填充
+    },
+  },
+};
+```
+
+这允许您在同一项目中为不同的语言环境设置不同的填充行为。
 
 ```ts fileName="src/components/example/example.content.ts"
 import { Locales, type Dictionary } from "intlayer";
@@ -87,18 +106,18 @@ import { Locales, type Dictionary } from "intlayer";
 const exampleContent = {
   key: "example",
   locale: Locales.ENGLISH,
-  autoFill: "./example.content.json",
+  fill: "./example.content.json",
   content: {
-    contentExample: "这是一个内容示例",
+    contentExample: "This is an example of content",
   },
 } satisfies Dictionary;
 
 export default exampleContent;
 ```
 
-这是一个使用 `autoFill` 指令的[按语言环境划分的内容声明文件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/per_locale_file.md)。
+这是一个[按语言环境的内容声明文件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/per_locale_file.md)，使用了 `fill` 指令。
 
-然后，当你运行以下命令时：
+然后，当您运行以下命令时：
 
 ```bash packageManager="npm"
 npx intlayer fill --file 'src/components/example/example.content.ts'
@@ -116,7 +135,7 @@ pnpm intlayer fill --file 'src/components/example/example.content.ts'
 bun x intlayer fill --file 'src/components/example/example.content.ts'
 ```
 
-Intlayer 将自动生成派生的声明文件，路径为 `src/components/example/example.content.json`，并填充主文件中尚未声明的所有语言环境。
+Intlayer 将自动在 `src/components/example/example.content.json` 生成派生声明文件，填充主文件中尚未声明的所有语言环境。
 
 ```json5 fileName="src/components/example/example.content.json"
 {
@@ -133,7 +152,7 @@ Intlayer 将自动生成派生的声明文件，路径为 `src/components/exampl
 }
 ```
 
-之后，这两个声明文件将合并为一个字典，可以通过标准的 `useIntlayer("example")` 钩子（React）或组合函数（Vue）访问。
+之后，两个声明文件将被合并为一个单一字典，可以使用标准的 `useIntlayer("example")` hook (react) / composable (vue) 访问。
 
 ## 全局配置
 

package/docs/zh/bundle_optimization.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-11-25
-updatedAt: 2026-06-07
+updatedAt: 2026-08-09
 title: 优化 i18n 打包体积与性能
 description: 通过优化国际化（i18n）内容来减小应用程序包的大小。了解如何利用 Intlayer 实现字典的 tree shaking 和延迟加载（lazy loading）。
 keywords:
@@ -16,6 +16,12 @@ slugs:
   - concept
   - bundle-optimization
 history:
+  - version: 9.2.1
+    date: 2026-08-09
+    changes: "`purge` 和 `minify` 现在可通过 `@intlayer/swc` 在 Next.js 上工作 — 无需 `babel.config.js`"
+  - version: 8.12.0
+    date: 2026-06-24
+    changes: "在参考表中按所需的流水线顺序列出 Babel 插件（extract → purge → minify → optimize）"
   - version: 8.12.0
     date: 2026-06-07
     changes: "为 Babel/Webpack 引入了 `intlayerPurgeBabelPlugin` 和 `intlayerMinifyBabelPlugin`，明确了插件管线"
@@ -191,12 +197,14 @@ Intlayer 的构建优化被划分为若干个职责单一的插件。了解它
 
 这些被直接运用在基于 Webpack 设置的 `babel.config.js` 当中（比如使用了 Babel 的 Next.js、CRA，或是自定义的 Webpack 等）。
 
+下表按所需的流水线顺序列出它们（与它们必须在 `babel.config.js` 中出现的顺序相同）：
+
 | 插件                          | 功能说明                                                                                             |
 | :---------------------------- | :--------------------------------------------------------------------------------------------------- |
 | `intlayerExtractBabelPlugin`  | 扫描 `.content.ts` 文件并把编译好的字典写入 `.intlayer/`                                             |
-| `intlayerOptimizeBabelPlugin` | 将 `useIntlayer('key')` 重写为 `useDictionary(hash)` 并注入匹配对应字典的 `import` 语句              |
 | `intlayerPurgeBabelPlugin`    | 扫描所有源代码文件，从已编译的 `.intlayer/**/*.json` 字典文件中删除**未被使用的内容字段**            |
 | `intlayerMinifyBabelPlugin`   | **重命名内容字段的键（keys）** 为简短的字母别名（例如 `title` 变成 `a`），作用范围包括 JSON 与源代码 |
+| `intlayerOptimizeBabelPlugin` | 将 `useIntlayer('key')` 重写为 `useDictionary(hash)` 并注入匹配对应字典的 `import` 语句              |
 
 > **插件的执行顺序很重要。** 在你的 `babel.config.js` 里，purge 和 minify 的插件必须放置在 optimize 插件**之前**。优化步骤（optimize）会把 `useIntlayer('key')` 替换为模糊的 `useDictionary(hash)`，此举抹除了能够让 purge 和 minify 识别哪些字段被使用过的字典 key 信息。
 
@@ -205,9 +213,9 @@ Intlayer 的构建优化被划分为若干个职责单一的插件。了解它
 | 选项助手                     | 配套插件                      |
 | :--------------------------- | :---------------------------- |
 | `getExtractPluginOptions()`  | `intlayerExtractBabelPlugin`  |
-| `getOptimizePluginOptions()` | `intlayerOptimizeBabelPlugin` |
 | `getPurgePluginOptions()`    | `intlayerPurgeBabelPlugin`    |
 | `getMinifyPluginOptions()`   | `intlayerMinifyBabelPlugin`   |
+| `getOptimizePluginOptions()` | `intlayerOptimizeBabelPlugin` |
 
 ### Vite 插件 (`vite-intlayer`)
 
@@ -220,6 +228,20 @@ Vite 用户**不需要直接对它们进行配置**。当你在 `vite.config.ts`
 | Dictionary minify | 等同于 `intlayerMinifyBabelPlugin` 的 JSON 写入步骤                                 |
 | Babel transform   | 等同于 `intlayerMinifyBabelPlugin` 的代码重命名步骤 + `intlayerOptimizeBabelPlugin` |
 
+### SWC 插件（`@intlayer/swc`）
+
+Next.js 用户同样**从不直接配置这些**。自 **v9.2.1** 起，`next.config.ts` 中的 `withIntlayer()` 仅凭 `build.purge` 和 `build.minify` 两个标志就会运行完整流水线 —— 清除、压缩和导入重写。
+
+工作被分成两部分，因为 SWC Wasm 插件一次只转换一个文件，且无法访问文件系统：
+
+| 阶段                               | 运行位置                       | 作用                                                         |
+| :--------------------------------- | :----------------------------- | :----------------------------------------------------------- |
+| 使用分析 + JSON 清除/压缩          | Node，位于 `withIntlayer()` 内 | 读取每个组件源文件，重写 `.intlayer/**/*.json`，生成重命名表 |
+| 源码重写（`content.title` → `.a`） | `@intlayer/swc`（Wasm）        | 将重命名表应用到你代码中对应的属性访问                       |
+| 导入重写（`useIntlayer` → dict）   | `@intlayer/swc`（Wasm）        | 与 `intlayerOptimizeBabelPlugin` 相同                        |
+
+判断_哪些_字段未被使用以及每个字段获得_什么_别名，需要跨文件状态和文件 I/O，因此这一半在 Node 中运行；SWC 插件只接收生成的表。
+
 ## 各平台配置指南
 
 <Tabs>
@@ -227,10 +249,12 @@ Vite 用户**不需要直接对它们进行配置**。当你在 `vite.config.ts`
 
 ### Next.js
 
-Next.js 需要依靠 `@intlayer/swc` 插件来进行优化步骤（导入重写），因为 Next.js 采用 SWC 作为编译器。
+Next.js 需要 `@intlayer/swc` 插件，因为 Next.js 使用 SWC 进行构建。自 **v9.2.1** 起，这一个包即可覆盖整条流水线 —— 优化（导入重写）、清除和压缩。
 
 > 该插件并未默认安装，因为 SWC 插件在 Next.js 当中目前仍处于实验阶段。未来这部分有可能会发生改变。
 
+> **Next.js 16.1.0 是最低版本。** 它是首个基于 SWC 向前兼容 Wasm 插件 ABI 构建的版本；更早的版本会拒绝该插件。`withIntlayer` 会读取你项目的 Next.js 版本，低于 16.1.0 时干脆不注册该插件 —— 这些构建仍会成功，只是在没有打包优化的情况下运行。
+
 <Tabs>
  <Tab value="npm">
 
@@ -265,33 +289,40 @@ intlayer-swc-plugin = "*"
 
 安装完毕后，Intlayer 将会自动侦测并使用该插件。
 
-至于**清除（purge）和最小化（minify）**步骤（即字段移除和字段重命名），请连同 `@intlayer/babel` 一并安装并加入 Babel 插件。由于 Next.js 依靠 SWC 处理代码转化，但仍会评估 `babel.config.js` 以决定插件配置，因此上述 Babel 插件能够在进入 SWC 前作为预处理步骤得以执行。
+**清除和压缩**阶段（字段移除与字段重命名）不需要额外的包，也不需要 `babel.config.js`。用 `withIntlayer` 包裹你的配置，并在 `intlayer.config.ts` 中开启相应标志：
 
-```bash packageManager="npm"
-npm install -D @intlayer/babel
+```typescript fileName="next.config.ts"
+import { withIntlayer } from "next-intlayer/server";
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {/* 你的配置 */};
+
+export default withIntlayer(nextConfig);
 ```
 
-```javascript fileName="babel.config.js"
-const {
-  intlayerPurgeBabelPlugin,
-  intlayerMinifyBabelPlugin,
-  getPurgePluginOptions,
-  getMinifyPluginOptions,
-} = require("@intlayer/babel");
+```typescript fileName="intlayer.config.ts"
+import type { IntlayerConfig } from "intlayer";
 
-module.exports = {
-  presets: ["next/babel"],
-  plugins: [
-    // Purge: 移除 .intlayer/**/*.json 里未被使用的内容字段
-    [intlayerPurgeBabelPlugin, getPurgePluginOptions()],
-    // Minify: 对 JSON 以及源代码里的内容字段的键（keys）进行重命名
-    [intlayerMinifyBabelPlugin, getMinifyPluginOptions()],
-    // 注意: 在这里不需要使用 intlayerOptimizeBabelPlugin，因为
-    // @intlayer/swc 已经处理了 useIntlayer → useDictionary 的重写过程。
-  ],
+const config: IntlayerConfig = {
+  build: {
+    purge: true, // 从打包的 JSON 中移除未使用的内容字段
+    minify: true, // 将内容字段键重命名为简短别名
+  },
 };
+
+export default config;
 ```
 
+在 `next build` 期间，`withIntlayer` 会分析你的源码、重写已编译的字典，并将生成的字段重命名表传给 `@intlayer/swc`，由它更新你代码中对应的属性访问。
+
+> 请使用异步的 `withIntlayer`，而不是 `withIntlayerSync`。同步版本不会运行分析流水线，因此清除和压缩对它没有效果。
+
+> 清除和压缩仅在 `next build` 时运行 —— 优化流水线在 `next dev` 期间是关闭的。
+
+> 当配置了兼容适配器调用方时它们也会被禁用（`swcExtraCallers`，由 `@intlayer/next-intl`、`@intlayer/react-i18next` 等兼容包设置）：这些调用点对使用分析器不可见，因此清除会移除代码仍在读取的字段。导入重写仍保持启用。
+
+**更早的版本（9.2.1 之前）** 需要 `@intlayer/babel` 以及一个声明 `intlayerPurgeBabelPlugin` 和 `intlayerMinifyBabelPlugin` 的 `babel.config.js`。该文件不再需要，可以删除。
+
  </Tab>
  <Tab value="vite">
 
@@ -447,6 +478,8 @@ export default config;
 
 > 如果在 `optimize` 被设为 `false`、又或是启用了可视化编辑器也就是当 `editor.enabled` 设定为了 `true` 时（由于编辑器需要保留字段名称以便做后续处理），重命名这个操作都将会被跳过。
 
+> 在 Next.js 上，当 `@intlayer/swc` 未安装或无法加载时（Next.js 低于 16.1.0），压缩同样会被跳过。重写源码访问的正是这个插件，因此在没有它的情况下重命名字典，会让你的代码读取已不存在的字段名。
+
 > 同理，如果是利用了 `importMode: 'fetch'` 来载入字段时此过程同样不适用。因为它们的内容会以原始命名由后端 API 所提供，对客户端内容随意重命名会破坏客户端与服务端的匹配契约。
 
 ### 字段清除 / Purging (去掉未被引用的字段内容)
@@ -475,7 +508,7 @@ export default config;
 { "title": "…", "subtitle": "…" }
 ```
 
-> 与前边提到的类似，当 `optimize` 是 `false` 或是开启了可视化编辑器(`editor.enabled` 取值 `true`) 时，它会选择跳过对数据的清除操作。
+> 与前边提到的类似，当 `optimize` 是 `false` 或是开启了可视化编辑器(`editor.enabled` 取值 `true`) 时，它会选择跳过对数据的清除操作。 在 Next.js 上，当 `@intlayer/swc` 不可用以及配置了兼容适配器调用方时，还会被额外跳过。
 
 > 当检测到某份代码因为异常无法顺利解析、又或者当把由 `useIntlayer` 输出的值以静态解析器难以预测分析的模式在不同组件中来回丢（比如被打包成对象传入等而未被进行解构）的时候，它同样会跳过，以此保守地保留整部字典的全部信息，避免意外发生。
 

package/docs/zh/configuration.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-13
-updatedAt: 2026-07-11
+updatedAt: 2026-08-06
 title: 配置
 description: 了解如何为您的应用程序配置 Intlayer。了解可用于根据您的需求自定义 Intlayer 的各种设置和选项。
 keywords:
@@ -14,6 +14,9 @@ slugs:
   - concept
   - configuration
 history:
+  - version: 9.1.3
+    date: 2026-08-06
+    changes: "将 `routing.enableProxy` 改为三态：未设置（auto）、`true`、`false`"
   - version: 9.0.0
     date: 2026-07-11
     changes: "添加 `analytics` 配置"
@@ -235,6 +238,18 @@ const config: IntlayerConfig = {
      */
     mode: "prefix-no-default",
 
+    /**
+     * 启用 Intlayer 语言环境路由代理（中间件）。
+     * 负责在 dev、preview 和 SSR 中进行语言环境检测、重定向和重写。
+     * - 未设置（auto）：dev 和 preview 服务器忽略 Cookie 和请求头中存储的语言环境，
+     *   保持路由由 URL 驱动。前缀仍会解析，语言环境仍会持久化，
+     *   Accept-Language 检测仍然生效。生产环境下的行为与 `true` 相同。
+     * - true：在所有环境中启用完整行为。
+     * - false：不进行语言环境路由。
+     * 默认值：undefined（auto）
+     */
+    enableProxy: undefined,
+
     /**
      * 用户选择的区域设置存储在哪里。
      * 选项：'cookie', 'localStorage', 'sessionStorage', 'header' 或这些选项的数组。
@@ -716,13 +731,14 @@ export default config;
 
 控制路由行为的设置，包括 URL 结构、区域设置存储和中间件管理。
 
-| 字段       | 说明                                                                                                                                | 类型                                                                                                                                                                                                         | 默认值                 | 示例                                                                                                                                                                                    | 备注                                                                                                                                                                                                                             |
-| ---------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `mode`     | 区域设置管理的 URL 路由模式。                                                                                                       | `'prefix-no-default'` &#124; <br/> `'prefix-all'` &#124; <br/> `'no-prefix'` &#124; <br/> `'search-params'`                                                                                                  | `'prefix-no-default'`  | `'prefix-no-default'`: `/dashboard` (en) 或 `/fr/dashboard` (fr)。 `'prefix-all'`: `/en/dashboard` 。 `'no-prefix'`: 区域设置以其他方式管理。 `'search-params'`: `/dashboard?locale=fr` | 不影响 cookie 管理或本地存储。                                                                                                                                                                                                   |
-| `storage`  | 客户端区域设置存储的配置。                                                                                                          | `false` &#124; <br/> `'cookie'` &#124; <br/> `'localStorage'` &#124; <br/> `'sessionStorage'` &#124; <br/> `'header'` &#124; <br/> `CookiesAttributes` &#124; <br/> `StorageAttributes` &#124; <br/> `Array` | `['cookie', 'header']` | `'localStorage'` <br/> `[{ type: 'cookie', name: 'custom-locale', secure: true }]`                                                                                                      | 参阅下方的存储参数表。                                                                                                                                                                                                           |
-| `basePath` | 应用程序 URL 的基础路径。                                                                                                           | `string`                                                                                                                                                                                                     | `''`                   | `'/my-app'`                                                                                                                                                                             | 如果您的应用程序位于 `https://example.com/my-app`，则 basePath 为 `'/my-app'`，指向 URL 为 `https://example.com/my-app/en` 。                                                                                                    |
-| `rewrite`  | 自定义 URL 重写规则，用于覆盖特定路径的默认路由模式。支持动态参数 `[param]`。                                                       | `Record<string, StrictModeLocaleMap<string>>`                                                                                                                                                                | `undefined`            | 见下方示例                                                                                                                                                                              | • 重写规则优先级高于 `mode`。<br/>• 与 Next.js 和 Vite 配合。 <br/>• `getLocalizedUrl()` 自动应用适当的规则。<br/>• 见 [自定义 URL 重写](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/custom_url_rewrites.md)。 |
-| `domains`  | 将区域设置映射到域主机名以进行基于域的路由。设置后，区域设置的 URL 将使用该域作为基础（绝对 URL），并且不会向路径添加区域设置前缀。 | `Partial<Record<Locale, string>>`                                                                                                                                                                            | `undefined`            | `{ zh: 'intlayer.zh', fr: 'intlayer.org' }`                                                                                                                                             | • 如果主机名中未包含，默认协议为 `https://`。<br/>• 域本身标识区域设置，因此不会添加 `/zh/` 前缀。<br/>• `getLocalizedUrl('/', 'zh')` 返回 `https://intlayer.zh/`。                                                              |
+| 字段          | 说明                                                                                                                                | 类型                                                                                                                                                                                                         | 默认值                 | 示例                                                                                                                                                                                    | 备注                                                                                                                                                                                                                                                                                                   |
+| ------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `mode`        | 区域设置管理的 URL 路由模式。                                                                                                       | `'prefix-no-default'` &#124; <br/> `'prefix-all'` &#124; <br/> `'no-prefix'` &#124; <br/> `'search-params'`                                                                                                  | `'prefix-no-default'`  | `'prefix-no-default'`: `/dashboard` (en) 或 `/fr/dashboard` (fr)。 `'prefix-all'`: `/en/dashboard` 。 `'no-prefix'`: 区域设置以其他方式管理。 `'search-params'`: `/dashboard?locale=fr` | 不影响 cookie 管理或本地存储。                                                                                                                                                                                                                                                                         |
+| `enableProxy` | 启用 Intlayer 语言环境路由代理（中间件）。                                                                                          | `boolean` &#124; <br/> `undefined`                                                                                                                                                                           | `undefined`（auto）    | `true`                                                                                                                                                                                  | • 未设置（auto）：dev 和 preview 服务器忽略 Cookie/请求头中存储的语言环境作为重定向来源；前缀、持久化和 `Accept-Language` 检测仍然生效。生产环境下的行为与 `true` 相同。<br/>• `true`：在任何地方都启用完整行为。<br/>• `false`：不进行语言环境路由。在 Next.js 中，`intlayerProxy` 中间件将变为直通。 |
+| `storage`     | 客户端区域设置存储的配置。                                                                                                          | `false` &#124; <br/> `'cookie'` &#124; <br/> `'localStorage'` &#124; <br/> `'sessionStorage'` &#124; <br/> `'header'` &#124; <br/> `CookiesAttributes` &#124; <br/> `StorageAttributes` &#124; <br/> `Array` | `['cookie', 'header']` | `'localStorage'` <br/> `[{ type: 'cookie', name: 'custom-locale', secure: true }]`                                                                                                      | 参阅下方的存储参数表。                                                                                                                                                                                                                                                                                 |
+| `basePath`    | 应用程序 URL 的基础路径。                                                                                                           | `string`                                                                                                                                                                                                     | `''`                   | `'/my-app'`                                                                                                                                                                             | 如果您的应用程序位于 `https://example.com/my-app`，则 basePath 为 `'/my-app'`，指向 URL 为 `https://example.com/my-app/en` 。                                                                                                                                                                          |
+| `rewrite`     | 自定义 URL 重写规则，用于覆盖特定路径的默认路由模式。支持动态参数 `[param]`。                                                       | `Record<string, StrictModeLocaleMap<string>>`                                                                                                                                                                | `undefined`            | 见下方示例                                                                                                                                                                              | • 重写规则优先级高于 `mode`。<br/>• 与 Next.js 和 Vite 配合。 <br/>• `getLocalizedUrl()` 自动应用适当的规则。<br/>• 见 [自定义 URL 重写](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/custom_url_rewrites.md)。                                                                       |
+| `domains`     | 将区域设置映射到域主机名以进行基于域的路由。设置后，区域设置的 URL 将使用该域作为基础（绝对 URL），并且不会向路径添加区域设置前缀。 | `Partial<Record<Locale, string>>`                                                                                                                                                                            | `undefined`            | `{ zh: 'intlayer.zh', fr: 'intlayer.org' }`                                                                                                                                             | • 如果主机名中未包含，默认协议为 `https://`。<br/>• 域本身标识区域设置，因此不会添加 `/zh/` 前缀。<br/>• `getLocalizedUrl('/', 'zh')` 返回 `https://intlayer.zh/`。                                                                                                                                    |
 
 **`rewrite` 示例**:
 

package/docs/zh/dictionary/file.md

@@ -25,6 +25,8 @@ author: aymericzip
 
 # 文件内容 / 在 Intlayer 中嵌入文件
 
+在 Intlayer 中，`file` 函数允许将外部文件内容嵌入到字典中。这种方法确保 Intlayer 识别源文件，从而与 Intlayer Visual Editor 和 CMS 实现无缝集成。
+
 ## 文件嵌入的工作原理
 
 在 Intlayer 中，`file` 函数允许将外部文件内容嵌入到字典中。这种方法确保 Intlayer 识别源文件，实现与 Intlayer 可视化编辑器和 CMS 的无缝集成。与直接使用 `import`、`require` 或 `fs` 文件读取方法不同，使用 `file` 会将文件与字典关联，使 Intlayer 能够在文件被编辑时动态跟踪和更新内容。

package/docs/zh/dictionary/nesting.md

@@ -64,6 +64,53 @@ export default firstDictionary;
 }
 ```
 
+### 使用 Nest 进行引用
+
+现在，创建另一个内容模块，使用 `nest` 函数来引用上述内容。您可以引用整个内容或特定的嵌套值：
+
+```typescript fileName="secondDictionary.content.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+import { nest, type Dictionary } from "intlayer";
+
+const myNestingContent = {
+  key: "key_of_my_second_dictionary",
+  content: {
+    // 引用整个字典：
+    fullNestedContent: nest("key_of_my_first_dictionary"),
+    // 引用特定的嵌套值：
+    partialNestedContent: nest(
+      "key_of_my_first_dictionary",
+      "subContent.contentNumber"
+    ),
+  },
+} satisfies Dictionary;
+
+export default myNestingContent;
+```
+
+```json fileName="secondDictionary.content.json" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "key_of_my_second_dictionary",
+  "content": {
+    "fullNestedContent": {
+      "nodeType": "nested",
+      "nested": {
+        "dictionaryKey": "key_of_my_first_dictionary"
+      }
+    },
+    "partialNestedContent": {
+      "nodeType": "nested",
+      "nested": {
+        "dictionaryKey": "key_of_my_first_dictionary",
+        "path": "subContent.contentNumber"
+      }
+    }
+  }
+}
+```
+
+作为第二个参数，您可以指定该内容中嵌套值的路径。如果未提供路径，则返回引用字典的全部内容。
+
 ## 设置嵌套
 
 <Tabs group="framework">
@@ -258,36 +305,6 @@ document.getElementById("nested")!.textContent = content.partialNestedContent;
   </Tab>
 </Tabs>
 
-## 在 React Intlayer 中使用嵌套
-
-要在 React 组件中使用嵌套内容，可以利用 `react-intlayer` 包中的 `useIntlayer` 钩子。此钩子根据指定的键检索正确的内容。以下是如何使用它的示例：
-
-```tsx fileName="**/*.tsx" codeFormat={["typescript", "esm"]}
-import type { FC } from "react";
-import { useIntlayer } from "react-intlayer";
-
-const NestComponent: FC = () => {
-  const { fullNestedContent, partialNestedContent } = useIntlayer(
-    "key_of_my_second_dictionary"
-  );
-
-  return (
-    <div>
-      <p>
-        Full Nested Content: {JSON.stringify(fullNestedContent)}
-        {/* 输出: {"content": "content", "subContent": {"contentNumber": 0, "contentString": "string"}} */}
-      </p>
-      <p>
-        Partial Nested Value: {partialNestedContent}
-        {/* 输出: 0 */}
-      </p>
-    </div>
-  );
-};
-
-export default NestComponent;
-```
-
 ## 其他资源
 
 有关配置和使用的更多详细信息，请参考以下资源：