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

package/docs/zh/cli/fill.md

@@ -47,6 +47,14 @@ bun x intlayer fill
 - 通过不覆盖现有翻译来保留它们。
 - 使用队列系统并行处理文件、块和语言环境以提高速度。
 
+## 关键要点：
+
+- 将大型 JSON 文件分割成块，以保持在 AI 模型的上下文窗口限制内。
+- 如果输出格式不正确，则重试翻译。
+- 结合应用程序和特定文件的上下文，以提高翻译准确性。
+- 通过不覆盖现有翻译来保留它们。
+- 使用队列系统并行处理文件、块和语言环境，以提高速度。
+
 ## 别名：
 
 - `npx intlayer dictionaries fill`

package/docs/zh/cli/login.md

@@ -78,42 +78,6 @@ bun x intlayer login --cms-url https://intlayer.org
 
 ### 配置选项
 
-您还可以使用常见的配置选项：
-
-- `--env-file <path>`：环境文件的路径
-- `-e, --env <env>`：执行环境
-- `--base-dir <dir>`：项目的基目录
-- `--verbose`：启用详细输出（默认：true）
-- `--prefix <prefix>`：日志前缀
-
-## 工作原理
-
-1. **启动本地服务器**：该命令在一个随机端口上启动本地 HTTP 服务器，以从 CMS 接收凭证
-
-指定要用于身份验证的 Intlayer CMS 的 URL。
-
-- **类型**: `string`
-- **默认**: 在 `intlayer.config.*` 中配置的值，或 `https://intlayer.org`
-- **示例**:
-
-```bash packageManager="npm"
-npx intlayer login --cms-url https://intlayer.org
-```
-
-```bash packageManager="yarn"
-yarn intlayer login --cms-url https://intlayer.org
-```
-
-```bash packageManager="pnpm"
-pnpm intlayer login --cms-url https://intlayer.org
-```
-
-```bash packageManager="bun"
-bun x intlayer login --cms-url https://intlayer.org
-```
-
-### 配置选项
-
 您还可以使用常用的配置选项：
 
 - `--env-file <path>`: 环境文件的路径

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

@@ -0,0 +1,44 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "从 i18n-js 迁移到 Intlayer"
+description: "了解如何使用兼容适配器将您的应用程序从 i18n-js 迁移到 Intlayer。"
+keywords:
+  - i18n-js
+  - intlayer
+  - 迁移
+  - 兼容
+slugs:
+  - doc
+  - compatibility
+  - i18n-js
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# 从 i18n-js 迁移到 Intlayer
+
+从 `i18n-js` 库迁移到 Intlayer 是一个高度优化的迁移过程，旨在将大型翻译配置迁移到 Intlayer 结构化的文件解析系统中。
+
+## 操作步骤
+
+在您的仓库中执行以下设置命令：
+
+```bash
+npx intlayer init
+```
+
+准备好 `intlayer.config.ts` 后，您可以在 bundler 配置中添加 Intlayer 的别名，使 `i18n-js` 的任何导入都指向兼容 package `@intlayer/i18n-js`。
+
+## 底层原理
+
+`i18n-js` 通过 `i18n.t('scope.key', {name})` 等表达式访问命名空间，并支持语言回退和特定的复数映射。
+
+底层实现：
+
+- **插值：** 兼容适配器可以轻松地将 `%{name}` 映射解析为目标运行时字典值。
+- **复数化：** 替换 `one/other` 子键，并将其映射到 Intlayer 强大的底层复数机制（`Intl.PluralRules`），从而抽象掉手动映射的需求。
+- **语言环境：** 无需在启动时加载单体语言 payload，字典根据通过原生 Intlayer 配置设置的当前上下文进行最优化加载。

package/docs/zh/compat/i18next.md

@@ -0,0 +1,59 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "从 i18next 迁移到 Intlayer"
+description: "了解如何使用兼容适配器将您的 Vanilla JS/TS 应用程序从 i18next 迁移到 Intlayer。"
+keywords:
+  - i18next
+  - vanilla
+  - javascript
+  - typescript
+  - intlayer
+  - 迁移
+  - 兼容
+slugs:
+  - doc
+  - compatibility
+  - i18next
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# 从 i18next 迁移到 Intlayer
+
+有关详细的分步教程，请参阅我们完整的 [i18next 迁移指南](../migration_from_i18next_to_intlayer.md)。
+
+Intlayer 完美复制了 `i18next` 的核心运行时特性。通过使用兼容 package，您的 Vanilla 应用程序或内部模块可以继续利用熟悉的语法。
+
+## 操作步骤
+
+首先，在您的项目中初始化 Intlayer：
+
+```bash
+npx intlayer init
+```
+
+如果您使用 Vite，请添加 Intlayer 插件以将导入路由到 `@intlayer/i18next`：
+
+```typescript fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import { i18nextVitePlugin } from "@intlayer/i18next/plugin";
+
+export default defineConfig({
+  plugins: [i18nextVitePlugin()],
+});
+```
+
+## 底层原理
+
+`i18nextVitePlugin` 将 `i18next` 导入别名指向 `@intlayer/i18next`，避免因 JSON 文件包含而导致 bundle 体积膨胀。
+
+底层实现：
+
+- **实例配置：** `createInstance` 正确解析和应用命名空间回退，同时利用 Intlayer 的编译管道进行字典检索。
+- **插值：** 原生支持 `{{name}}` 替换和 `$t(key)` 递归嵌套。
+- **上下文与复数：** 识别并解析后缀格式，如 `key_male` 和 `key_one`/`key_other`，依据标准 `Intl.PluralRules` 进行求值。
+- **返回对象：** `returnObjects: true` 模式可安全地从 Intlayer 字典中提取树形结构。

package/docs/zh/compat/index.md

@@ -0,0 +1,51 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Intlayer 兼容适配器"
+description: "使用兼容适配器将您现有的 i18n 解决方案零摩擦迁移到 Intlayer。"
+keywords:
+  - 兼容
+  - 迁移
+  - 国际化
+  - i18n
+  - Intlayer
+slugs:
+  - doc
+  - compatibility
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# Intlayer 兼容适配器
+
+将大型应用程序迁移到新的国际化库可能令人望而生畏。为了简化这一过渡，Intlayer 为生态系统中最流行的 i18n 库提供了**兼容适配器**。
+
+这些适配器 package 暴露与您现有 i18n 库**完全相同的公共 API**，但在运行时将所有翻译工作委托给 Intlayer。
+
+## 工作原理
+
+使用兼容适配器时，您无需重写应用程序的导入或更改翻译 hook 和组件的使用方式。相反，Intlayer 的 bundler 插件会自动将您现有的导入别名指向 Intlayer 兼容 package。
+
+例如，开发者将 `import { useTranslation } from 'react-i18next'` 替换为 `import { useTranslation } from '@intlayer/react-i18next'`（通过 bundler 插件自动完成），应用程序继续工作，翻译现在由 Intlayer 字典提供。键值也会与您的 Intlayer 字典进行类型检查！
+
+## 可用兼容适配器
+
+在下方选择您现有的库，了解如何无缝迁移：
+
+- [Vue I18n](./vue-i18n.md)
+- [Transloco](./transloco.md)
+- [React Intl](./react-intl.md)
+- [Svelte I18n](./svelte-i18n.md)
+- [React i18next](./react-i18next.md)
+- [Polyglot.js](./polyglot.md)
+- [NuxtJS I18n](./nuxtjs-i18n.md)
+- [NGX Translate](./ngx-translate.md)
+- [Next Translate](./next-translate.md)
+- [Next Intl](./next-intl.md)
+- [Next i18next](./next-i18next.md)
+- [i18next](./i18next.md)
+- [Lingui](./lingui.md)
+- [I18n-js](./i18n-js.md)

package/docs/zh/compat/lingui.md

@@ -0,0 +1,44 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "从 Lingui 迁移到 Intlayer"
+description: "了解如何使用兼容适配器将您的应用程序从 Lingui 迁移到 Intlayer。"
+keywords:
+  - lingui
+  - intlayer
+  - 迁移
+  - 兼容
+slugs:
+  - doc
+  - compatibility
+  - lingui
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# 从 Lingui 迁移到 Intlayer
+
+如果您的项目目前依赖 Lingui 基于宏的编译，迁移到 Intlayer 可以让您在保持强大宏工作流的同时，以 Intlayer 的 JSON 编译策略作为原生支撑。
+
+## 操作步骤
+
+首先，在您的项目中初始化 Intlayer：
+
+```bash
+npx intlayer init
+```
+
+这将创建您的 `intlayer.config.ts`。确保在构建步骤中保留 `@lingui/babel-plugin-lingui-macro` / `@lingui/swc-plugin`，使其在 Intlayer 编译器*之前*运行。然后，使用 bundler 插件别名将 `@lingui/core` 和 `@lingui/react` 路由到 `@intlayer/lingui`。
+
+## 底层原理
+
+Lingui 利用宏（如 `` t`Hello ${name}` `` 和 `<Trans>`），这些宏被编译为运行时调用，如 `i18n._(id, values)`。
+
+底层实现：
+
+- **宏：** 与之前完全一致地编译，确保源代码语法不受任何干扰。
+- **运行时翻译：** 别名化的 `i18n._()` 使用 Intlayer 字典。显式命名的 ID 和哈希 ID 都通过 Intlayer 的 `.po` 同步插件完全映射，以安全地聚合和修剪键值。
+- **ICU 能力：** 由于 Intlayer 的统一 ICU 解析器，对复数化、选择和 ICU 变体的支持保持稳健，确保输出结果完全一致。

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

@@ -0,0 +1,57 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "从 next-i18next 迁移到 Intlayer"
+description: "了解如何使用兼容适配器将您的 Next.js 应用程序从 next-i18next 迁移到 Intlayer。"
+keywords:
+  - next-i18next
+  - nextjs
+  - intlayer
+  - 迁移
+  - 兼容
+slugs:
+  - doc
+  - compatibility
+  - next-i18next
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# 从 next-i18next 迁移到 Intlayer
+
+有关完整详细的分步教程，请参阅我们完整的 [next-i18next 迁移指南](../migration_from_next-i18next_to_intlayer.md)。
+
+Intlayer 透明地处理所有 Next.js Pages Router 和 App Router 实现。使用适配器可以让您以零代码重写的方式迁移 `next-i18next` 实现。
+
+## 操作步骤
+
+首先，运行：
+
+```bash
+npx intlayer init
+```
+
+这将创建所需的 Intlayer 设置文件。要在后台切换到 Intlayer，请更新您的 `next.config.ts`：
+
+```typescript fileName="next.config.ts"
+import type { NextConfig } from "next";
+import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin";
+
+const withIntlayer = createNextI18nPlugin();
+
+const nextConfig: NextConfig = {};
+
+export default withIntlayer(nextConfig);
+```
+
+## 底层原理
+
+`createNextI18nPlugin` 将 Next.js 的原生行为与核心 `next-intlayer` 插件组合在一起，为 `next-i18next`、`react-i18next` 和 `i18next` 注入所有必需的 Webpack/Turbopack 别名。
+
+底层实现：
+
+- **`serverSideTranslations` 和 `appWithTranslation`：** 现在作为 Intlayer 内部加载器的包装器运行，绕过了大型静态 JSON 注入。
+- **客户端 hook：** 立即委托给 `@intlayer/react-i18next`，保留所有格式化、复数和嵌套命名空间功能。

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

@@ -0,0 +1,59 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "从 next-intl 迁移到 Intlayer"
+description: "了解如何使用兼容适配器将您的 Next.js 应用程序从 next-intl 迁移到 Intlayer。"
+keywords:
+  - next-intl
+  - nextjs
+  - intlayer
+  - 迁移
+  - 兼容
+slugs:
+  - doc
+  - compatibility
+  - next-intl
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# 从 next-intl 迁移到 Intlayer
+
+有关完整详细的分步教程，请参阅我们完整的 [next-intl 迁移指南](../migration_from_next-intl_to_intlayer.md)。
+
+从 `next-intl` 迁移到 Intlayer，让您的应用程序路由和语法完全不受干扰。
+
+## 操作步骤
+
+在您的仓库中执行以下命令：
+
+```bash
+npx intlayer init
+```
+
+这将创建一个 `intlayer.config.ts`。在您的 `next.config.ts` 中，使用插件包装器无缝地将 `next-intl` 别名注入到 `@intlayer/next-intl`。
+
+```typescript fileName="next.config.ts"
+import type { NextConfig } from "next";
+import { createNextIntlPlugin } from "@intlayer/next-intl/plugin";
+
+const withIntlayer = createNextIntlPlugin();
+
+const nextConfig: NextConfig = {};
+
+export default withIntlayer(nextConfig);
+```
+
+## 底层原理
+
+bundler 包装器替换了翻译，但**保留 `next-intl/navigation` 功能完好无损**（例如 `Link`、`redirect`、`usePathname`）。
+
+底层实现：
+
+- **ICU 运行时：** 复数（`=0`、`one`、`other`）、select/selectordinal、`#` 参数和格式化参数（`{ts, date, long}`）通过共享的 `resolveMessage(..., 'icu')` 解析器正确运行。
+- **`useTranslations()` 和 `getTranslations()`：** 裸作用域调用将第一个键段提取为正确的字典标识符。嵌套命名空间优雅地拆分为字典路径和前缀。
+- **富文本格式化：** `t.rich()` 和 `t.markup()` 都经过完整的原生实现，将类 HTML 节点转换为渲染的 React chunk。
+- **`useFormatter`：** `relativeTime`、`list`、`dateTimeRange` 和配置中的命名格式桥接到核心原生 `Intl` 格式化器。

package/docs/zh/compat/next-translate.md

@@ -0,0 +1,45 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "从 Next Translate 迁移到 Intlayer"
+description: "了解如何使用兼容适配器将您的 Next.js 应用程序从 next-translate 迁移到 Intlayer。"
+keywords:
+  - next-translate
+  - nextjs
+  - intlayer
+  - 迁移
+  - 兼容
+slugs:
+  - doc
+  - compatibility
+  - next-translate
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# 从 Next Translate 迁移到 Intlayer
+
+从 `next-translate` 迁移到 Intlayer 几乎是一个直接替换，可以保留您现有的语法和标签。
+
+## 操作步骤
+
+在您的项目中初始化 Intlayer：
+
+```bash
+npx intlayer init
+```
+
+CLI 将生成您的配置文件。然后，您可以在 `next.config.ts` 中应用 Intlayer 插件，该插件注入构建时子路径别名，将 `next-translate/useTranslation` 映射到 `@intlayer/next-translate`。
+
+## 底层原理
+
+`next-translate` 提供了如 `useTranslation('ns')`、`t('ns:key.path')` 的 hook 以及 `<Trans>` 组件。
+
+底层实现：
+
+- **插值与复数：** 它紧密依赖 `react-i18next` 适配器的行为。动态处理 `{{var}}` 占位符以及从 `key_0`、`key_one` 和 `key_other` 等后缀映射的复数化。
+- **`<Trans>` 组件：** 直接支持类 HTML 标签解析，并支持基于数组的 `components` prop。
+- **命名空间：** 子路径别名确保您的 `useTranslation` 引用正确的内部字典命名空间，无需手动修改。

package/docs/zh/compat/ngx-translate.md

@@ -0,0 +1,45 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "从 NGX-Translate 迁移到 Intlayer"
+description: "了解如何使用兼容适配器将您的 Angular 应用程序从 ngx-translate 迁移到 Intlayer。"
+keywords:
+  - ngx-translate
+  - angular
+  - intlayer
+  - 迁移
+  - 兼容
+slugs:
+  - doc
+  - compatibility
+  - ngx-translate
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# 从 NGX-Translate 迁移到 Intlayer
+
+使用兼容适配器，将您的 Angular 应用程序从 `ngx-translate` 迁移到 Intlayer 非常简单，让您无需重写所有模板。
+
+## 操作步骤
+
+首先运行：
+
+```bash
+npx intlayer init
+```
+
+这将设置 `intlayer.config.ts`。替换您的 `TranslateModule.forRoot()` 设置，并将导入别名适当地指向 `@intlayer/ngx-translate`。
+
+## 底层原理
+
+`ngx-translate` 使用 `TranslateService`（`instant`、`get`、`stream`）以及 `{{ 'KEY' | translate:params }}` 管道和 `[translate]` 指令。
+
+底层实现：
+
+- **服务：** `TranslateService` 包装了 `getIntlayer` 和一个语言环境可观察对象，提供完全相同的方法。
+- **管道和指令：** 重新实现以直接针对 Intlayer 字典进行解析。
+- **加载器：** `TranslateHttpLoader` 设置被转换为警告存根，因为 Intlayer 在构建时（或通过标准动态导入）固有地解析和 bundle 您的字典，完全消除了对 HTTP 加载器的需求。

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

@@ -0,0 +1,46 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "从 NuxtJS I18n 迁移到 Intlayer"
+description: "了解如何使用兼容适配器将您的 Nuxt.js 应用程序从 @nuxtjs/i18n 迁移到 Intlayer。"
+keywords:
+  - nuxtjs-i18n
+  - nuxt
+  - vue
+  - intlayer
+  - 迁移
+  - 兼容
+slugs:
+  - doc
+  - compatibility
+  - nuxtjs-i18n
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# 从 NuxtJS I18n 迁移到 Intlayer
+
+使用 Nuxt 适配器模块，将您的 Nuxt 应用程序从 `@nuxtjs/i18n` 迁移到 Intlayer 是一个无缝的过程。
+
+## 操作步骤
+
+要初始化项目，运行：
+
+```bash
+npx intlayer init
+```
+
+这将设置 `intlayer.config.ts`。然后，在您的 `nuxt.config.ts` 的模块数组中添加 Intlayer Nuxt 模块（例如 `@intlayer/nuxt-i18n`）。这将自动为您的应用程序应用兼容配置。
+
+## 底层原理
+
+`@nuxtjs/i18n` 包装了 `vue-i18n`，同时提供 Nuxt 特定的路由组合式函数（`useLocalePath`、`useSwitchLocalePath`、`<NuxtLinkLocale>`）。
+
+底层实现：
+
+- **翻译：** 原生依赖 `@intlayer/vue-i18n` 兼容层来处理所有字符串翻译任务（完全支持 `vue-i18n` 格式、管道复数和响应性）。
+- **路由：** 使用 Intlayer 的本地化 URL 辅助函数镜像路由组合式函数。
+- **配置：** 直接从您的 `intlayer.config.ts` 读取 `availableLocales` 和默认设置，以自动协调 Nuxt 页面。

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`。