@intlayer/docs 9.4.2 → 9.4.3

package/blog/zh/i18n_meaning.md

@@ -19,8 +19,6 @@ author: aymericzip
 
 # i18n 的含义：什么是国际化，为什么它很重要？
 
-![i18n 插图](https://github.com/aymericzip/intlayer/blob/main/docs/assets/i18n.webp)
-
 ## 理解 \"i18n 的含义\"
 
 如果你从事软件开发、网页设计或数字营销，你可能遇到过 **i18n** 这个术语。**i18n 的真正含义**其实是 **国际化** (internationalization) 的一个数字略写。

package/blog/zh/i18n_testing_strategies.md

@@ -0,0 +1,179 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: "如何测试翻译而不写出脆弱的测试"
+description: 在多语言（i18n）应用中什么值得测试，什么不值得测试。基于 Provider 的渲染测试、伪本地化、RTL 与复数覆盖率，以及快照测试的陷阱。
+keywords:
+  - 测试翻译
+  - i18n 测试
+  - testing library i18n
+  - 伪本地化
+  - 语言环境 provider 测试
+  - snapshot test i18n
+slugs:
+  - blog
+  - i18n-testing-strategies
+author: aymericzip
+---
+
+# 如何测试翻译而不写出脆弱的测试
+
+大多数 i18n 测试套件都会以两种方式之一崩溃。要么它们断言字面文案，导致每次文案修改都会破坏五十个测试，团队最终将其全部删除。要么它们完全在默认语言环境中渲染，对其他十七种语言没有提供任何保证。两种情况最终都会导致同一个结果，一个无人信任的测试套件。
+
+## 目录
+
+<TOC/>
+
+## 模式与库无关
+
+以下每个模式都适用于任何 i18n 技术栈。将 Provider 替换为 `I18nextProvider`、`NextIntlClientProvider` 或 `IntlProvider`，测试代码保持完全一致，因为它们断言的是渲染输出，而不是特定的库 API。
+
+覆盖率工具也同样可以迁移：通过将 [Sync JSON 插件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/plugins/sync-json.md) 指向现有字典目录，或使用 [兼容适配器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/compat/index.md) 别名化当前的导入，覆盖率断言可以直接针对你现有的 JSON 文件运行。
+
+## 明确你到底在测试什么
+
+翻译质量不是一个可以通过代码断言来验证的事物。没有任何断言能告诉你德语是否地道，试图这样做只会让你的测试套件充斥着硬编码的字符串。
+
+真正值得机械化测试的内容如下：
+
+| 值得测试                             | 不值得测试                   |
+| :----------------------------------- | :--------------------------- |
+| 每个必需的语言环境都有值             | 文案用词是否优美             |
+| 正确的语言环境传递到了组件中         | 每个标签的精确字面文本       |
+| 复数能针对每个类别正确解析           | 翻译人员是否尽职尽责         |
+| RTL 语言正确设置了方向和镜像布局     | 每种语言中的每一个具体字符串 |
+| 格式化的日期和数字正确遵循了语言环境 | `Intl` 底层内部实现的正确性  |
+
+覆盖率检查应该归入单个数据驱动的测试中，而不是分散在组件测试里。这部分内容在 [如何检测缺失的翻译](https://github.com/aymericzip/intlayer/blob/main/docs/blog/zh/detecting_missing_translations.md) 中有详细介绍；本文主要关注其余部分。
+
+## 在 Provider 下渲染并按角色（Role）断言
+
+核心模式是将组件挂载到语言环境 Provider 内，并通过 role 或 test id 进行查询，而不是通过文案查询。
+
+```tsx fileName="CartSummary.test.tsx"
+import { render, screen } from "@testing-library/react";
+import { IntlayerProvider } from "react-intlayer/client";
+import { CartSummary } from "./CartSummary";
+
+test("以法语渲染结算摘要标题", () => {
+  render(
+    <IntlayerProvider locale="fr-FR">
+      <CartSummary />
+    </IntlayerProvider>
+  );
+
+  expect(screen.getByRole("heading")).toBeInTheDocument();
+});
+```
+
+查询 `getByRole("heading")` 能够经受住文案变更的考验。而 `getByText("Récapitulatif")` 则做不到。仅当字符串本身就是要测试的对象时，才使用字面量，这种情况十分罕见。
+
+对于 `aria-label` 等属性，你需要原始字符串而不是可渲染节点。在 React 中，`useIntlayer` 返回的条目为此暴露了 `.value` 字段。
+
+## 跨语言环境进行参数化测试
+
+一个运行在所有语言环境上的测试逻辑，远比为每种语言单独写测试更有价值。
+
+```tsx fileName="direction.test.tsx"
+import { getHTMLTextDir } from "intlayer";
+import { render } from "@testing-library/react";
+import { IntlayerProvider } from "react-intlayer/client";
+
+describe.each(["en", "fr", "ja", "ar"])("语言环境 %s", (locale) => {
+  it("渲染时不会回退到原始 key", () => {
+    const { container } = render(
+      <IntlayerProvider locale={locale}>
+        <CartSummary />
+      </IntlayerProvider>
+    );
+
+    // 如果渲染出了 key，说明查找失败。
+    expect(container.textContent).not.toMatch(/^[a-z]+(\.[a-z]+)+$/);
+  });
+
+  it("设置了正确的文本方向", () => {
+    expect(getHTMLTextDir(locale)).toBe(locale === "ar" ? "rtl" : "ltr");
+  });
+});
+```
+
+第一个断言是非常廉价且通用的收益：如果查找失败并且你的库直接渲染了 key，DOM 中就会出现类似 `cart.summary.title` 的内容。这可以在不列出任何字符串的情况下捕获一整类错误。
+
+## 伪本地化发现目录无法检测到的问题
+
+添加一个能够转换每个字符串的伪语言环境，例如将 `Checkout` 转换为 `[!!! Çĥéçķöũţ !!!]`。然后使用该语言环境渲染页面。
+
+任何依然显示为纯英文的内容都是硬编码在代码中的。任何基于字典目录的审计都无法发现这一点，因为在工具看来该字符串根本不存在。方括号还有第二个作用：它们将文本拉长约 30%，可以在德语上线之前提前暴露布局破损问题。
+
+这适合作为视觉测试或端到端测试运行，而不是单元测试，因为这类错误是肉眼直观可见的。
+
+## 复数需要按类别测试，而不是按语言测试
+
+复数相关的错误往往难以察觉，因为英语只有两种形式，大多数开发者也只验证这两种。波兰语有四种，阿拉伯语有六种。
+
+```ts fileName="plural.test.ts"
+// 阿拉伯语涵盖 zero, one, two, few, many, other。
+describe.each([0, 1, 2, 3, 11, 100])("数量 %i", (count) => {
+  it("在阿拉伯语中生成非空字符串", () => {
+    expect(formatItems(count, "ar")).not.toBe("");
+  });
+});
+```
+
+针对最复杂的语言选择能命中每个 CLDR 类别的数值，而不是处处只测试 1 和 2。`Intl.PluralRules` 可以告诉你一个数字属于哪个类别，从而让你推导测试样本而不是靠猜测。有关类别的更多信息见 [ICU 消息格式文章](https://github.com/aymericzip/intlayer/blob/main/docs/blog/zh/icu_message_format.md)。
+
+## 快照（Snapshot）的陷阱
+
+快照和多语言是一对糟糕的组合。本地化组件的快照会记录其中的每一个字符串：当翻译人员修复葡萄牙语中的拼写错误时，绿色的测试套件就会变红，而且修改发生在没有审查者能看懂的文件中。几次之后，大家就会在不阅读 diff 的情况下直接运行 `-u`，快照也就失去了所有意义。
+
+如果你想使用快照，请仅在单一语言环境下执行，并将其视为结构检查而非内容检查。所有与特定语言相关的内容都应放在显式断言中。
+
+## 测试协商逻辑，而不仅仅是渲染
+
+生产环境中最常见的 i18n 错误不是缺失字符串。而是选错了语言环境：URL 标明 `/fr/`，客户端却读取 `navigator.language`，两者产生冲突。
+
+将解析顺序作为纯函数直接测试，独立于任何组件：
+
+```ts fileName="locale-resolution.test.ts"
+it("优先使用 URL 而不是存储的偏好设置", () => {
+  expect(resolveLocale({ url: "/fr/about", stored: "de", header: "ja" })).toBe(
+    "fr"
+  );
+});
+
+it("当 URL 没有前缀时回退到请求头", () => {
+  expect(resolveLocale({ url: "/about", stored: null, header: "ja" })).toBe(
+    "ja"
+  );
+});
+```
+
+这是大多数代码库中缺失的、最具价值的单一 i18n 测试，而且它完全不需要 DOM。
+
+## 测试职责划分
+
+- **Unit**：语言协商、格式化器、复数类别。快速，无 DOM。
+- **Component**：每个语言环境一次基于 Provider 的渲染，断言角色和原始 key 的缺失。
+- **Coverage**：单次数据驱动测试，断言没有缺失必需的语言环境。
+- **Visual / E2E**：伪本地化检查和 RTL 页面测试，因为这些缺陷属于视觉问题。
+
+在每次 commit 的流水线中保留前三项。最后一项在夜间构建中运行成本较低，而在每次 push 时运行成本较高。
+
+## 常见错误
+
+- **在所有地方断言精确文案。** 会确保测试套件在几个月内被彻底删除。
+- **对多语言组件进行快照测试。** 翻译人员破坏构建，审查者盲目合入更新。
+- **只测试默认语言。** 这是唯一不可能缺失的语言环境。
+- **复数只测试 1 和 2。** 遗漏了英语所没有的所有类别。
+- **完全 Mock 掉 i18n 库。** 这样你只是在测试 Mock 对象是否返回了字符串。
+- **从不测试协商逻辑。** 最常见的真实故障，且最容易进行测试。
+
+## 深入阅读
+
+- [测试你的内容：CLI 审计、编程式 API 与 UI 断言](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/testing.md)
+- [ESLint 插件：捕获硬编码字符串与未使用内容](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/eslint.md)
+- [格式化器与语言实用工具（包括 `getHTMLTextDir`）](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/formatters.md)
+- [跨框架基准测试报告](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/benchmark/index.md)
+- [react-i18next 兼容适配器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/compat/react-i18next.md)
+- [如何检测缺失的翻译](https://github.com/aymericzip/intlayer/blob/main/docs/blog/zh/detecting_missing_translations.md)
+- [ICU 消息格式：复数、select 与骨架](https://github.com/aymericzip/intlayer/blob/main/docs/blog/zh/icu_message_format.md)

package/blog/zh/intlayer_with_i18next.md

@@ -74,15 +74,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > `--interactive` 标志是可选的。如果你是 AI 代理，请使用 `intlayer-cli init`。

package/blog/zh/intlayer_with_next-i18next.md

@@ -67,15 +67,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > `--interactive` 标志是可选的。如果您是 AI 代理，请使用 `intlayer-cli init`。

package/blog/zh/intlayer_with_next-intl.md

@@ -68,15 +68,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > `--interactive` 标志是可选的。如果你是 AI agent，请使用 `intlayer-cli init`。

package/blog/zh/intlayer_with_react-i18next.md

@@ -68,15 +68,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > `--interactive` 标志是可选的。如果您是 AI 代理，请使用 `intlayer-cli init`。

package/blog/zh/intlayer_with_react-intl.md

@@ -66,15 +66,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > `--interactive` 标志是可选的。如果您是 AI agent，请使用 `intlayer-cli init`。

package/blog/zh/intlayer_with_vue-i18n.md

@@ -68,15 +68,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > `--interactive` 标志是可选的。如果您是 AI 代理，请使用 `intlayer-cli init`。

package/blog/zh/is_i18next_outdated.md

@@ -0,0 +1,317 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: 2026 年，i18next 已经过时了吗？
+description: i18next 为数百万个网站提供多语言支持，但其始于 2011 年的运行时架构已显老态。本文深入剖析其打包体积膨胀、Tree-shaking 限制与创新停滞问题。
+keywords:
+  - i18next
+  - react-i18next
+  - next-i18next
+  - Intlayer
+  - 国际化
+  - i18n
+  - 打包体积
+  - 博客
+slugs:
+  - blog
+  - is-i18next-outdated
+author: aymericzip
+---
+
+# 2026 年，i18next 已经过时了吗？
+
+`i18next` 诞生于 2011 年，远早于 React 组件、Webpack 打包和 TypeScript 成为业界标准的时间。凭借灵活性和无处不在的生态，它几乎支持所有技术栈，并在 StackOverflow 上积累了海量的解决方案。
+
+该项目并未被遗弃，维护者依然在定期发布补丁。然而，维护一个古老的运行时引擎与顺应现代前端架构持续演进，这两者有着本质区别。
+
+近几年，前端架构全面转向构建时编译、React Server Components (RSC)、极致的 Tree-shaking 以及 AI 驱动的工作流。相比之下，i18next 的核心依旧停留在十年前：一个在客户端解析字符串键名的运行时单例。
+
+<TOC/>
+
+## 核心观点
+
+**维护模式：**
+
+在过去 12 个月里，`next-i18next` 仅提交了约 63 次 commit（约每周一次），`react-i18next` 约 157 次，且绝大部分只是依赖项更新与细微问题修补。
+
+**沉重的运行时开销：**
+
+`react-i18next` 和 `next-i18next` 在渲染第一个翻译字符之前，就会向客户端注入约 17–18 KB（gzip 压缩后，未压缩约 60 KB）的代码，几乎是 `next-intlayer`（约 4.7 KB）的 4 倍。
+
+**严重的翻译内容泄漏：**
+
+在默认的静态配置下，单页加载的翻译数据中有高达 **89.8%** 属于其他路由或当前未使用的语言。
+
+**无法进行 Tree-shaking：**
+
+像 `t("home.hero.title")` 这样的动态字符串调用无法被打包工具静态分析，迫使整个 JSON 文件全部打包进客户端 chunk。
+
+**商业模式的局限：**
+
+其维护团队运营着商业翻译平台 Locize。在 CLI 中直接内置完全免费的本地 AI 翻译工作流，与其核心盈利模式存在直接冲突。
+
+## 仅维护 vs. 积极演进
+
+GitHub Stars 仅代表历史上的流行程度，并不代表当下的架构活力。
+
+| 仓库                    | Stars                                                                                                                                                      | 总 Commit 数                                                                                                                                                            | 年 Commit 数                                                                                                                                                           | 最近一次 Commit                                                                                                                                  |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `i18next/i18next`       | [![stars](https://img.shields.io/github/stars/i18next/i18next?style=for-the-badge&label=stars)](https://github.com/i18next/i18next/stargazers)             | [![commits](https://img.shields.io/github/commit-activity/t/i18next/i18next?style=for-the-badge&label=commits)](https://github.com/i18next/i18next/commits)             | [![yearly](https://img.shields.io/github/commit-activity/y/i18next/i18next?style=for-the-badge&label=%2Fyear)](https://github.com/i18next/i18next/commits)             | [![last](https://img.shields.io/github/last-commit/i18next/i18next?style=for-the-badge)](https://github.com/i18next/i18next/commits)             |
+| `i18next/react-i18next` | [![stars](https://img.shields.io/github/stars/i18next/react-i18next?style=for-the-badge&label=stars)](https://github.com/i18next/react-i18next/stargazers) | [![commits](https://img.shields.io/github/commit-activity/t/i18next/react-i18next?style=for-the-badge&label=commits)](https://github.com/i18next/react-i18next/commits) | [![yearly](https://img.shields.io/github/commit-activity/y/i18next/react-i18next?style=for-the-badge&label=%2Fyear)](https://github.com/i18next/react-i18next/commits) | [![last](https://img.shields.io/github/last-commit/i18next/react-i18next?style=for-the-badge)](https://github.com/i18next/react-i18next/commits) |
+| `i18next/next-i18next`  | [![stars](https://img.shields.io/github/stars/i18next/next-i18next?style=for-the-badge&label=stars)](https://github.com/i18next/next-i18next/stargazers)   | [![commits](https://img.shields.io/github/commit-activity/t/i18next/next-i18next?style=for-the-badge&label=commits)](https://github.com/i18next/next-i18next/commits)   | [![yearly](https://img.shields.io/github/commit-activity/y/i18next/next-i18next?style=for-the-badge&label=%2Fyear)](https://github.com/i18next/next-i18next/commits)   | [![last](https://img.shields.io/github/last-commit/i18next/next-i18next?style=for-the-badge)](https://github.com/i18next/next-i18next/commits)   |
+| `aymericzip/intlayer`   | [![stars](https://img.shields.io/github/stars/aymericzip/intlayer?style=for-the-badge&label=stars)](https://github.com/aymericzip/intlayer/stargazers)     | [![commits](https://img.shields.io/github/commit-activity/t/aymericzip/intlayer?style=for-the-badge&label=commits)](https://github.com/aymericzip/intlayer/commits)     | [![yearly](https://img.shields.io/github/commit-activity/y/aymericzip/intlayer?style=for-the-badge&label=%2Fyear)](https://github.com/aymericzip/intlayer/commits)     | [![last](https://img.shields.io/github/last-commit/aymericzip/intlayer?style=for-the-badge)](https://github.com/aymericzip/intlayer/commits)     |
+
+过去 12 个月的开发动态：
+
+| 项目            | 历史 Commit 总数 | 过去 12 个月 | 侧重点                                   |
+| --------------- | ---------------- | ------------ | ---------------------------------------- |
+| `next-i18next`  | 1,311            | **63**       | Next.js 版本兼容与补丁                   |
+| `react-i18next` | 1,988            | **157**      | 类型定义与日常维护                       |
+| `i18next` 核心  | 2,626            | **259**      | 小幅度更新                               |
+| Intlayer        | 7,156            | **4,343**    | 编译器优化、IDE 工具链与 AI 翻译引擎研发 |
+
+[![Star History Chart](https://api.star-history.com/chart?repos=i18next%2Fi18next%2Ci18next%2Freact-i18next%2Ci18next%2Fnext-i18next%2Caymericzip%2Fintlayer&type=date&legend=top-left)](https://www.star-history.com/#i18next/i18next&i18next/react-i18next&i18next/next-i18next&aymericzip/intlayer)
+
+成熟的代码库能提供稳定性，但现代 i18n 工具链已经发生质变：现代打包工具在构建期剔除无用文本，CI 阶段借助大语言模型实现自动化翻译，编辑器环境深度融合 Language Server (LSP) 与 AI Agent。纯运行时的架构设计很难融入这些前沿技术。
+
+## 测量打包体积开销
+
+<I18nBenchmark framework="tanstack" vertical/>
+
+<ClickToOpenIframe
+src="https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-tanstack.md"
+width="100%"
+height="600px"
+style="border:none;"
+/>
+
+> 基于包含 10 个路由、10 种语言的生产环境应用测量，采用 gzip 压缩。完整数据见 [i18n 基准测试报告](https://intlayer.org/zh/doc/benchmark)。
+
+### 库的基础体积
+
+在未添加任何翻译词条之前的空白开销：
+
+| 库                     | Gzip 压缩后 | Minified 未压缩 |
+| ---------------------- | ----------- | --------------- |
+| `next-i18next@16.0.5`  | 17.8 KB     | 61.2 KB         |
+| `react-i18next@17.0.2` | 17.3 KB     | 59.8 KB         |
+| `intlayer@8.7.12`      | **4.7 KB**  | **12.8 KB**     |
+
+### 页面体积与数据泄漏
+
+在 React / TanStack Start（静态策略）环境下的表现：
+
+| 库                    | 单页平均 JS (gz) | 跨语言泄漏 | 跨页面泄漏 | 平均组件大小 (gz) | 水合耗时    |
+| --------------------- | ---------------- | ---------- | ---------- | ----------------- | ----------- |
+| `react-i18next`       | 180.3 KB         | **50.0%**  | **89.8%**  | 24.3 KB           | 85.1 ms     |
+| Intlayer              | **127.8 KB**     | 50.0%      | **0.8%**   | **7.1 KB**        | **24.1 ms** |
+| Intlayer (scoped dyn) | **118.1 KB**     | **0.0%**   | **0.8%**   | **4.6 KB**        | 23.7 ms     |
+
+在 Next.js 环境下的表现：
+
+| 库              | 单页平均 JS (gz) | 跨页面泄漏 | 平均组件大小 (gz) |
+| --------------- | ---------------- | ---------- | ----------------- |
+| 基准（无 i18n） | 150.8 KB         | 0.0%       | 0.7 KB            |
+| `next-i18next`  | **227.5 KB**     | **89.8%**  | 24.5 KB           |
+| `next-intlayer` | **152.1 KB**     | **0.0%**   | **7.2 KB**        |
+
+### 核心发现
+
+**单页体积增加：**
+
+在 Next.js 中，`next-i18next` 相比无 i18n 基准应用额外增加了 **76.7 KB (gzip)**，增幅达 50%。而 `next-intlayer` 仅增加了 1.3 KB。
+
+**翻译内容泄漏：**
+
+在默认设置下，下发到特定路由的内容中约 **90%** 实际上属于其他页面。依靠手动划分命名空间不仅繁琐，而且容易漏配。
+
+**水合延迟：**
+
+采用 `react-i18next` 的组件水合耗时达到 **85 ms**，而 Intlayer 仅需 **24 ms**。向客户端组件注入巨型 JSON 树会明显拖慢首屏可交互速度。
+
+## 为什么 i18next 这么重？
+
+### 运行时功能过度堆砌
+
+为了在浏览器端处理所有需求，必须提前加载所有模块：插值、复数规则、上下文解析、格式化器和事件总线。即使只是渲染一句普通文本，也得为整个引擎买单。
+
+### 动态键名阻断 Tree-shaking
+
+由于 `"hero.title"` 在运行时才会被动态求值，打包工具无法推测哪些字符串被真正引用了。未使用的词条只能全量打包进客户端 chunk。
+
+<Tabs defaultTab="intlayer" group="techno">
+  <Tab label="i18next" value="i18next">
+
+```tsx fileName="Component.tsx"
+const { t } = useTranslation("home");
+
+return <h1>{t("hero.title")}</h1>;
+```
+
+  </Tab>
+  <Tab label="Intlayer" value="intlayer">
+
+```tsx fileName="Hero.tsx"
+const { title } = useIntlayer("hero");
+
+return <h1>{title}</h1>;
+```
+
+  </Tab>
+</Tabs>
+
+[Intlayer 编译器](https://intlayer.org/zh/doc/compiler)可以确切识别 `Hero.tsx` 访问的字段，并在生成客户端代码前剔除未引用的内容。详情请查阅[打包优化](https://intlayer.org/zh/doc/concept/bundle-optimization)。
+
+## 开发者体验对比
+
+### 分离式 JSON vs. 组件就近存放
+
+在 i18next 中，翻译集中放在远离组件的 JSON 文件夹中。Intlayer 则支持将内容声明直接与组件放在一起：
+
+<Tabs defaultTab="intlayer" group="techno">
+  <Tab label="i18next" value="i18next">
+
+```json fileName="locales/en/hero.json"
+{
+  "title": "Ship in every language"
+}
+```
+
+```json fileName="locales/zh/hero.json"
+{
+  "title": "用每一种语言发布产品"
+}
+```
+
+```tsx fileName="Hero.tsx"
+import { useTranslation } from "react-i18next";
+
+export const Hero = () => {
+  const { t } = useTranslation("hero");
+  return <h1>{t("title")}</h1>;
+};
+```
+
+  </Tab>
+  <Tab label="Intlayer" value="intlayer">
+
+```ts fileName="hero.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+export default {
+  key: "hero",
+  content: {
+    title: t({
+      en: "Ship in every language",
+      zh: "用每一种语言发布产品",
+    }),
+  },
+} satisfies Dictionary;
+```
+
+```tsx fileName="Hero.tsx"
+import { useIntlayer } from "react-intlayer";
+
+export const Hero = () => {
+  const { title } = useIntlayer("hero");
+  return <h1>{title}</h1>;
+};
+```
+
+  </Tab>
+</Tabs>
+
+当移动或删除 `Hero.tsx` 时，相关的内容声明文件会自动一同移动或删除。
+
+### 代码补全 vs. 严格类型安全
+
+通过扩展 `CustomTypeOptions` 可以获得编辑器代码提示，但这无法检查翻译是否完备。如果在 `zh/hero.json` 中删除了某个键，构建依然会成功，只在运行时降级显示兜底文本。
+
+Intlayer 直接基于内容声明推导类型，启用 [`strictMode`](https://intlayer.org/zh/doc/concept/configuration) 后，缺失任何一种语言的翻译都会直接导致构建失败，彻底杜绝遗漏。
+
+### 工具链生态对比
+
+| 功能特性                  | i18next 生态        | Intlayer                                                      |
+| ------------------------- | ------------------- | ------------------------------------------------------------- |
+| **VS Code 插件**          | 仅第三方插件        | ✅ [官方插件](https://intlayer.org/zh/doc/vs-code-extension)  |
+| **Language Server (LSP)** | ❌ 无               | ✅ [专属 LSP](https://intlayer.org/zh/doc/lsp)                |
+| **AI MCP 服务**           | ❌ 无               | ✅ [内置 MCP Server](https://intlayer.org/zh/doc/mcp-server)  |
+| **AI Agent Skills**       | ❌ 无               | ✅ [预制 Skills](https://intlayer.org/zh/doc/agent_skills)    |
+| **上下文可视化 CMS**      | Locize（付费 SaaS） | ✅ [免费开源 CMS](https://intlayer.org/zh/doc/concept/editor) |
+
+内置 LSP 和 MCP 服务使 AI 编程助手能深入理解项目的多语言拓扑结构，从而提供极高准确度的补全与重构。
+
+## 翻译机制与 Locize 的商业考量
+
+Locize 是 i18next 原班团队运营的商业服务。虽然开源项目的商业化值得鼓励，但这种模式不可避免地带来了利益冲突：依靠收费翻译平台盈利的项目，缺乏动力在开源 CLI 中提供完全免费的本地 AI 翻译功能。
+
+Intlayer 则采用开放的方案：
+
+- [`intlayer fill`](https://intlayer.org/zh/doc/concept/auto-fill) 允许你在终端或 CI 中使用自己的 OpenAI、Anthropic、Mistral 或 Gemini API 密钥自动补齐缺失的翻译。
+- [Intlayer CMS](https://intlayer.org/zh/doc/concept/cms) 完全开源，支持通过 Docker Compose 自主部署。
+- 编译器、CLI、编辑器和 CMS 均在 Apache 2.0 协议下完全开源。
+
+## 何时继续选择 i18next 依然合理？
+
+<AccordionGroup>
+<Accordion header="稳定运行的遗留系统">
+
+如果现有项目稳定可靠，打包体积未对业务指标产生实质性影响，无需急于重构。
+
+</Accordion>
+<Accordion header="特殊或老旧平台">
+
+i18next 庞大的插件生态可以很好地覆盖 Electron、老版 jQuery 应用或自定义 Native Bridge 等现代编译器鲜有支持的特殊场景。
+
+</Accordion>
+<Accordion header="深厚的社区答疑沉淀">
+
+多年积累在 StackOverflow 和 GitHub 上的答疑资源，能够快速解决各类边界问题。
+
+</Accordion>
+</AccordionGroup>
+
+## 如何改进现有的 i18next 配置？
+
+Intlayer 提供了开箱即用的兼容包，完整保留了 i18next 系列库（`i18next`、`react-i18next` 和 `next-i18next`）的函数调用签名。你无需重写组件代码，即可直接享受现代编译器架构带来的性能红利。
+
+配置仅需一行命令：
+
+```bash packageManager="npm"
+npx intlayer init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer init --interactive
+```
+
+该交互式 CLI 工具会自动完成以下工作：
+
+1. 安装 `@intlayer/i18next` 兼容包。
+2. 配置打包工具别名（alias），使现有的导入语句（`useTranslation`、`Trans`、`t`）无缝指向 Intlayer，从而可以安全地从 `package.json` 中移除原有的旧库。
+3. 立即激活 IDE 语言服务器（LSP）诊断、构建期 Tree-shaking 打包优化以及本地 AI 自动翻译工作流。
+
+详细操作请参阅我们的专题指南：
+
+- **无缝兼容层：** 借助 [i18next](https://intlayer.org/zh/doc/compatibility/i18next)、[react-i18next](https://intlayer.org/zh/doc/compatibility/react-i18next) 和 [next-i18next](https://intlayer.org/zh/doc/compatibility/next-i18next) 兼容层，在保留当前语法的同时实现构建优化。
+- **词典迁移指南：** 将旧有的 JSON 转换为类型安全的词典：[从 i18next 迁移](https://intlayer.org/zh/doc/migration/i18next)、[从 react-i18next 迁移](https://intlayer.org/zh/doc/migration/react-i18next)以及[从 next-i18next 迁移](https://intlayer.org/zh/doc/migration/next-i18next)。
+- **混合架构：** 保留 i18next 运行时，[将 Intlayer 与 i18next 搭配使用](https://intlayer.org/zh/blog/intlayer-with-i18next)以引入类型检查和本地 AI 翻译。
+
+使用免费的 [i18n SEO 分析器](https://intlayer.org/i18n-seo-scanner) 检测你的线上应用是否存在多余的内容泄漏：
+
+<ClickToOpenIframe src="https://intlayer.org/i18n-seo-scanner" width="100%" height="600px" style="border:none;"/>
+
+## 相关阅读
+
+- [Next.js i18n 性能基准：深度对比测试](https://intlayer.org/zh/doc/benchmark/nextjs)
+- [react-i18next 对比 react-intl 与 Intlayer](https://intlayer.org/zh/blog/react-i18next-vs-react-intl-vs-intlayer)
+- [2026 年，next-intl 已经过时了吗？](https://intlayer.org/zh/blog/is-next-intl-outdated)
+- [编译型国际化与声明式 i18n 架构对比](https://intlayer.org/zh/blog/compiler-vs-declarative-i18n)