@intlayer/docs 8.12.5-canary.0 → 9.0.0-canary.11

package/docs/zh/cli/doc-review.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-11
-updatedAt: 2025-11-22
+updatedAt: 2026-06-17
 title: 审核文档
 description: 学习如何审核不同语言版本的文档文件，以确保质量、一致性和完整性。
 keywords:
@@ -15,6 +15,10 @@ slugs:
   - concept
   - cli
   - doc-review
+history:
+  - version: 9.0.0
+    date: 2026-06-17
+    changes: "添加 --log 选项"
 author: aymericzip
 ---
 
@@ -55,8 +59,110 @@ bun x intlayer doc review
 
 ## 参数：
 
-`doc review` 命令接受与 `doc translate` 相同的参数，允许您审核特定的文档文件并应用质量检查。
+**文件列表选项：**
 
-如果您启用了其中一个 git 选项，命令将只审核文件中发生更改的部分。脚本会将文件分块处理并审核每个块。如果某个块没有更改，脚本将跳过该块，以加快审核过程并限制 AI 提供商 API 的成本。
+- **`--doc-pattern [docPattern...]`**：匹配要审核的文档文件的全局模式。
 
-有关完整的参数列表，请参阅[翻译文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/doc-translate.md)命令文档。
+  > 示例：`npx intlayer doc review --doc-pattern "docs/**/*.md" "src/**/*.mdx"`
+
+- **`--excluded-glob-pattern [excludedGlobPattern...]`**：排除不审核的文件的全局匹配模式。
+
+  > 示例：`npx intlayer doc review --excluded-glob-pattern "docs/internal/**"`
+
+- **`--skip-if-modified-before [skipIfModifiedBefore]`**：如果文件在指定时间之前被修改，则跳过该文件。
+  - 可以是绝对时间，如 "2025-12-05"（字符串或 Date 类型）
+  - 可以是相对时间，单位为毫秒，如 `1 * 60 * 60 * 1000`（1 小时）
+  - 此选项通过 `fs.stat` 方法检查文件的更新时间，因此可能会受到 Git 或其他修改文件工具的影响。
+
+  > 示例：`npx intlayer doc review --skip-if-modified-before "2025-12-05"`
+
+- **`--skip-if-modified-after [skipIfModifiedAfter]`**：如果文件在指定时间内被修改，则跳过该文件。
+  - 可以是绝对时间，如 "2025-12-05"（字符串或 Date 类型）
+  - 可以是相对时间，单位为毫秒，如 `1 * 60 * 60 * 1000`（1 小时）
+  - 此选项通过 `fs.stat` 方法检查文件的更新时间，因此可能会受到 Git 或其他修改文件工具的影响。
+
+  > 示例：`npx intlayer doc review --skip-if-modified-after "2025-12-05"`
+
+- **`--skip-if-exists`**：如果文件已存在，则跳过该文件。
+
+  > 示例：`npx intlayer doc review --skip-if-exists`
+
+**审核模式选项：**
+
+- **`--log`**：仅记录模式。不使用 AI 进行翻译；而是记录需要关注的块（带有行号和内容），供基础语言环境和目标语言环境参考，以帮助另一个代理生成翻译。
+
+  > 示例：`npx intlayer doc review --log`
+
+**入口输出选项：**
+
+- **`--locales [locales...]`**：目标语言，用于审核文档。
+
+  > 示例：`npx intlayer doc review --locales fr es de`
+
+- **`--base-locale [baseLocale]`**：源语言（基础文档），用于对比的起始语言。
+
+  > 示例：`npx intlayer doc review --base-locale en`
+
+**文件处理选项：**
+
+- **`--nb-simultaneous-file-processed [nbSimultaneousFileProcessed]`**：同时处理审核的文件数量。
+
+  > 示例：`npx intlayer doc review --nb-simultaneous-file-processed 5`
+
+**AI 选项：**
+
+- **`--model [model]`**：用于审核的 AI 模型（例如，`gpt-3.5-turbo`）。
+- **`--provider [provider]`**：用于审核的 AI 提供商。
+- **`--temperature [temperature]`**：AI 模型的温度设置。
+- **`--api-key [apiKey]`**：为 AI 服务提供您自己的 API 密钥。
+- **`--application-context [applicationContext]`**：为 AI 审核提供额外的上下文信息。
+- **`--data-serialization [dataSerialization]`**：用于 Intlayer AI 功能的数据序列化格式。选项：`json`（标准、可靠），`toon`（更少 token，但一致性较低）。
+- **`--custom-prompt [prompt]`**：自定义用于审核的基础提示。（注意：对于大多数用例，建议使用 `--custom-instructions` 选项，因为它能更好地控制审核行为。）
+
+  > 示例：`npx intlayer doc review --model deepseek-chat --provider deepseek --temperature 0.5 --api-key sk-1234567890 --application-context "My application is a cat store"`
+
+**环境变量选项：**
+
+- **`--env`**：指定环境（例如，`development`，`production`）。
+- **`--env-file [envFile]`**：提供自定义环境文件以加载变量。
+- **`--base-dir`**：指定项目的基础目录。
+- **`--no-cache`**：禁用缓存。
+
+  > 示例: `npx intlayer doc review --base-dir ./docs --env-file .env.production.local`
+
+**日志选项:**
+
+- **`--verbose`**: 启用详细日志以便调试。（CLI 默认启用）
+
+  > 示例: `npx intlayer doc review --verbose`
+
+**自定义指令选项:**
+
+- **`--custom-instructions [customInstructions]`**: 添加到提示中的自定义指令。用于应用关于格式、URL 翻译等的特定规则。
+
+  > 示例: `npx intlayer doc review --custom-instructions "避免翻译网址，并保持 markdown 格式"`
+
+  > 示例: `npx intlayer doc review --custom-instructions "$(cat ./instructions.md)"`
+
+**Git 选项:**
+
+- **`--git-diff`**: 仅针对包含从基础分支（默认 `origin/main`）到当前分支（默认 `HEAD`）的更改的文件运行。
+- **`--git-diff-base`**: 指定 git diff 的基础参考（默认 `origin/main`）。
+- **`--git-diff-current`**: 指定 git diff 的当前参考（默认 `HEAD`）。
+- **`--uncommitted`**: 包含未提交的更改。
+- **`--unpushed`**: 包含未推送的更改。
+- **`--untracked`**: 包含未跟踪的文件。
+
+  > 示例: `npx intlayer doc review --git-diff --git-diff-base origin/main --git-diff-current HEAD`
+
+  > 示例: `npx intlayer doc review --uncommitted --unpushed --untracked`
+
+> 请注意，输出文件路径将通过替换以下模式来确定：
+>
+> - `/{{baseLocale}}/` 替换为 `/{{locale}}/`（Unix）
+> - `\{{baseLocale}}\` 替换为 `\{{locale}}\`（Windows）
+> - `_{{baseLocale}}.` 替换为 `_{{locale}}.`
+> - `{{baseLocale}}_` 替换为 `{{locale}}_`
+> - `.{{baseLocaleName}}.` 替换为 `.{{localeName}}.`
+>
+> 如果未找到上述模式，输出文件将在文件扩展名后添加 `.{{locale}}`。例如，`./my/file.md` 将被审核并为法语版本更新为 `./my/file.fr.md`。

package/docs/zh/cli/fill.md

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

package/docs/zh/cli/index.md

@@ -17,7 +17,7 @@ slugs:
   - concept
   - cli
 history:
-  - version: 8.13.0
+  - version: 9.0.0
     date: 2026-06-11
     changes: "添加 scan 命令"
   - version: 8.6.4

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/cli/scan.md

@@ -18,7 +18,7 @@ slugs:
   - cli
   - scan
 history:
-  - version: 8.13.0
+  - version: 9.0.0
     date: 2026-06-11
     changes: "添加 scan 命令"
 author: aymericzip

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 页面。