@intlayer/docs 9.1.3 → 9.2.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/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;
-```
-
 ## 其他资源
 
 有关配置和使用的更多详细信息，请参考以下资源：