@intlayer/docs 8.12.4 → 9.0.0-canary.10

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

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

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

package/docs/zh/compat/transloco.md

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