@intlayer/docs 9.5.6 → 9.5.8

package/blog/zh/lingui_vs_intlayer.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-09-13
-updatedAt: 2026-09-13
+updatedAt: 2026-09-22
 title: "Lingui vs Intlayer：2026 年基准测试与深度对比"
 description: "在 Next.js 和 TanStack Start 上实测的两款基于编译器的 i18n 库。打包体积、内容泄漏、组件大小、水合性能、语言切换响应速度及开发者体验全面对比。"
 keywords:
@@ -24,6 +24,8 @@ author: aymericzip
 
 # Lingui VS Intlayer | React & Next.js 国际化 (i18n) 基准测试对比
 
+![JavaScript i18n library ecosystem](https://github.com/aymericzip/intlayer/blob/main/docs/assets/cloud_i18n_logo.webp?raw=true)
+
 Lingui 和 Intlayer 是本次基准测试中仅有的两个依赖**编译器**而非纯运行时的国际化库。Lingui 在构建时从宏中提取消息，并为每个语言环境编译目录。Intlayer 按组件编译字典，并按语言环境进行 Tree-shaking。理论上它们的表现应当十分接近，但实际测试数据揭示了它们在哪方面走向了分歧。
 
 测试数据来源于 [Benchmark Bloom](https://github.com/intlayer-org/benchmark-bloom)，这是一个开源基准测试套件，它使用每个库构建完全相同的应用程序，并记录浏览器实际下载和执行的代码细节。
@@ -96,6 +98,10 @@ Intlayer 无需单独的 "scoped" 变体：编译器自动**按组件维度**界
 
 ### Next.js 测试结果
 
+选择您关注的指标和库：
+
+<I18nBenchmark framework="nextjs" vertical/>
+
 | 库                  | 策略           | 库体积 (gz) | 页面 JS 平均 (gz) | 语言泄漏 | 页面泄漏 | 组件平均体积 (gz) | E2E 响应耗时 | 水合耗时 |
 | ------------------- | -------------- | ----------: | ----------------: | -------: | -------: | ----------------: | -----------: | -------: |
 | **base** (无 i18n)  | -              |      0.0 KB |          141.0 KB |     0.0% |     0.0% |            0.9 KB |      13.4 ms |  11.8 ms |
@@ -114,6 +120,15 @@ Intlayer 无需单独的 "scoped" 变体：编译器自动**按组件维度**界
 - **源语言回退导致的固有泄漏。** 即便在最佳配置下，**仍有 3-15% 的英文原文字符串被打包到法语页面中**。这是因为 Lingui 宏保留了原文字符串作为运行时安全回退。Intlayer 在构建期便彻底解决了回退关系，客户端仅传输目标语言。
 - **`scoped-dynamic` 下组件体积急剧放大。** 隔离编译下的单个组件平均体积暴增至 **152.6 KB**，因为通过导入引用，该组件将所有路由目录全都牵连了进来。而在 Intlayer 中，同样的组件使用 `useIntlayer()` 平均仅有 **6.9 KB**。
 
+<ClickToOpenIframe
+src="https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-nextjs.md"
+width="100%"
+height="600px"
+style="border:none;"
+/>
+
+> 完整表格、所有库和策略请参阅 [Next.js 基准测试报告](https://intlayer.org/zh/doc/benchmark/nextjs)。
+
 ### TanStack Start 测试结果
 
 | 库                          | 策略           | 库体积 (gz) | 页面 JS 平均 (gz) | 语言泄漏 | 页面泄漏 | 组件平均体积 (gz) | E2E 响应耗时 |    水合耗时 |
@@ -135,8 +150,19 @@ Intlayer 无需单独的 "scoped" 变体：编译器自动**按组件维度**界
 - **Intlayer 的 `static` 模式已天然具备 0% 页面泄漏**，因为打包器只打包当前页面所渲染组件显式导入的字典。仅需增加一行配置（`importMode: 'dynamic'`）即可同时消除语言泄漏。
 - **`@intlayer/lingui`** 允许开发者继续沿用 Lingui 宏语法，底层由 Intlayer 字典直接服务。它牺牲了少许整页体积（由于宏运行时驻留，为 137 KB），换取了大幅缩小的单组件（12.8 KB）和显著加快的水合速度。对于既有项目而言是非常理想的平滑升级通道。
 
+<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;"
+/>
+
+> 完整表格请参阅 [TanStack Start 基准测试报告](https://intlayer.org/zh/doc/benchmark/tanstack)。
+
 ## 根本成因剖析：两个编译器，两种不同的工作单元
 
+![The Intlayer compiler extracts content from components](https://github.com/aymericzip/intlayer/blob/main/docs/assets/compiler.webp?raw=true)
+
 两款库都引入了编译阶段。核心差异在于它们究竟**在编译什么**。
 
 **Lingui 编译的是目录（Catalogs）。** 源代码中的宏被提取到单语言的 `.po` 文件中，继而被编译为单语言的 JS 模块。它的工作单元是**语言环境整体（Locale）**。若想进一步细分（按路由或组件），就必须创建多个目录，并在 `lingui.config.ts` 中精细配置规则，手动控制每个路由的加载行为。其 `I18n` 实例是全局唯一的，每一个 `useLingui()` 都会将组件牢牢绑定在这个全局实例上。
@@ -176,7 +202,9 @@ Intlayer 无需单独的 "scoped" 变体：编译器自动**按组件维度**界
             └── about.content.ts
 ```
 
-这也是为什么 `scoped-dynamic` 模式在 Intlayer 中是自动生成的底层产物，而在 Lingui 中则是一项复杂的工程配置项目。
+这也是为什么 `scoped-dynamic` 模式在 Intlayer 中是自动生成的底层产物，而在 Lingui 中则是一项复杂的工程配置项目. 差距在页面和语言两个维度上同时拉大：
+
+![Theoretical content leakage by architecture](https://github.com/aymericzip/intlayer/blob/main/docs/assets/theorical_content_leakage.webp?raw=true)
 
 > 若要复现 `dynamic` 行的性能指标，只需在 `intlayer.config.ts` 中声明 `dictionary.importMode: 'dynamic'`。详见 [打包优化文档](https://intlayer.org/zh/doc/concept/bundle-optimization)。
 
@@ -184,7 +212,8 @@ Intlayer 无需单独的 "scoped" 变体：编译器自动**按组件维度**界
 
 ### 基础初始化
 
-**Lingui**
+<Tabs defaultTab="intlayer" group="techno">
+<Tab label="Lingui" value="lingui">
 
 ```ts fileName="lingui.config.ts"
 import { defineConfig } from "@lingui/cli";
@@ -215,7 +244,8 @@ export const loadCatalog = async (locale: string) => {
 
 随后需在打包器中接入 `@lingui/babel-plugin-lingui-macro`（或 `@lingui/swc-plugin`），在源码更改后运行 `lingui extract`，在应用构建前运行 `lingui compile`，并使用 `<I18nProvider i18n={i18n}>` 嵌套根视图。
 
-**Intlayer**
+</Tab>
+<Tab label="Intlayer" value="intlayer">
 
 ```ts fileName="intlayer.config.ts"
 import { type IntlayerConfig, Locales } from "intlayer";
@@ -232,9 +262,12 @@ export default config;
 
 在 `vite.config.ts` 中加入 `intlayer()`（在 Next.js 中使用 `withIntlayer()`），再用 `<IntlayerProvider>` 包裹组件树。无需独立的提取或编译命令行操作：启动打包器时字典自动完成编译。
 
+</Tab>
+</Tabs>
 ### 组件内编写
 
-**Lingui**
+<Tabs defaultTab="intlayer" group="techno">
+<Tab label="Lingui" value="lingui">
 
 ```tsx fileName="src/components/Counter.tsx"
 import { useState } from "react";
@@ -258,7 +291,8 @@ export const Counter = () => {
 
 英文文本直接书写在组件内；法语翻译由 `lingui extract` 提取到 `src/locales/fr/messages.po` 的哈希键下。如果开发者遗漏了提取或编译步骤，界面将静默显示英文原文。
 
-**Intlayer**
+</Tab>
+<Tab label="Intlayer" value="intlayer">
 
 ```ts fileName="src/components/Counter/index.content.ts"
 import { t, type Dictionary } from "intlayer";
@@ -297,11 +331,14 @@ export const Counter = () => {
 
 各语言配置统一存放在组件同级的单文件内。缺少 `fr` 内容会引发编译阻断，输入错误键名会立刻收到 TypeScript 的错误提示。
 
+</Tab>
+</Tabs>
 ### 组件树之外的环境
 
 如路由元数据、加载器（loaders）、服务端执行函数等非 React 树环境。
 
-**Lingui**
+<Tabs defaultTab="intlayer" group="techno">
+<Tab label="Lingui" value="lingui">
 
 ```ts fileName="src/routes/$locale/about.tsx"
 import { setupI18n } from "@lingui/core";
@@ -324,7 +361,8 @@ export const loader = async ({ params }: { params: { locale: string } }) => {
 
 每次调用都需重新实例化 `I18n`，手动导入正确的目录，并必须采用 `msg` + `i18n._()` 而不能直接写 `t`。正如 [基准测试记录](https://github.com/intlayer-org/benchmark-bloom/blob/main/report/NOTE.md) 所指出的，判断何时该使用 `t`、`` t` ` ``、`i18n.t()`、`msg` 还是 `<Trans>`，非常不够直观。
 
-**Intlayer**
+</Tab>
+<Tab label="Intlayer" value="intlayer">
 
 ```ts fileName="src/routes/$locale/about.tsx"
 import { getIntlayer } from "intlayer";
@@ -336,6 +374,9 @@ export const loader = async ({ params }: { params: { locale: string } }) => {
 };
 ```
 
+</Tab>
+</Tabs>
+
 ## 保留 Lingui 宏，接入 Intlayer 字典
 
 `@intlayer/lingui` 是针对 `@lingui/core` 和 `@lingui/react` 的无缝兼容适配器。宏依然照常编译，底层调用的 `i18n._()` 直接由 Intlayer 字典提供支撑，同时配套的 `.po` 同步插件依然将现有目录视作单一事实来源。ICU 复数与条件分支渲染效果完全一致。
@@ -353,16 +394,82 @@ export default defineConfig({
 
 ## 该如何做出选型抉择？
 
-- **选择 Lingui 的场景**：如果你深度依赖 **ICU MessageFormat** 与强类型宏，翻译团队已高度绑定于基于 **`.po`** 的专业 TMS 协作管线，喜欢在 JSX 内直接编写源码字符串，且团队有成熟能力自管提取、编译和目录拆分工作流。配置好延迟加载后，其单页体积具备极佳的竞争力。
-- **选择 Intlayer 的场景**：如果你追求**组件级内聚内容**、**严格的 TypeScript 约束**、**构建期未翻译键自动报错**、**零配置全自动 Tree-shaking 与按需加载**、轻巧的单组件体积、闪电般的水合响应、瞬时语言切换，以及一整套现代内置协作套件（Visual Editor、CMS、AI 辅助翻译、MCP 服务端）。在大型模块化项目和设计系统中优势格外显著。
-- **选择 `@intlayer/lingui` 的场景**：如果你已有庞大的 Lingui 项目，并希望在不重构既有宏代码的前提下，平滑、渐进式地拥抱 Intlayer 字典架构。
+<AccordionGroup>
+<Accordion header="选择 Lingui">
+
+如果您想要带有类型化宏的 **ICU MessageFormat**，您的翻译人员在已有 TMS 流程中使用 **`.po`** 文件，您喜欢在 JSX 中就近书写源语言字符串，并且您的团队乐于掌控提取 / 编译 / 目录拆分的工作流。配置好懒加载后，其每页 JS 体积非常有竞争力。
+
+</Accordion>
+<Accordion header="选择 Intlayer">
+
+如果您想要**组件级作用域内容**、**严格的 TypeScript**、**构建期缺失键报错**、**零成本 tree-shaking 与懒加载**、微小的组件体积、快速注水、即时语言切换以及内置编辑工具（[可视化编辑器](https://intlayer.org/zh/doc/concept/editor)、[CMS](https://intlayer.org/zh/doc/concept/cms)、[AI 翻译](https://intlayer.org/zh/doc/concept/auto-fill)、[MCP 服务器](https://intlayer.org/zh/doc/mcp-server)）。特别适用于大型、模块化代码库与设计系统。
+
+</Accordion>
+<Accordion header="选择 @intlayer/lingui">
+
+如果您已在使用 Lingui，并希望在无需修改宏代码的情况下渐进式迁移到 Intlayer 字典。您的 `.po` 目录通过 [PO 同步插件](https://intlayer.org/zh/doc/compatibility/lingui) 仍然保持为唯一事实来源。在 [Lingui vs @intlayer/lingui](https://intlayer.org/zh/blog/lingui-vs-intlayer-lingui) 中并排测试。
+
+</Accordion>
+</AccordionGroup>
+
+## 常见问题
+
+<FAQ>
+
+<Question title="Lingui 也会编译，为什么输出差异如此之大？">
+
+因为编译的单元不同。Lingui **按语言编译单一目录**：其之下的细分（按路由分包、懒加载、将 fallback 排除在 bundle 之外）全部需要繁琐配置。Intlayer **按组件编译字典**，因此路由级作用域自然由构建器生成。这就是为什么单独编译一个 Lingui 组件体积高达 58-153 KB，而 Intlayer 仅为 6-8 KB。
+
+</Question>
+
+<Question title="为什么 Lingui 的语言泄漏率永远无法达到 0%？">
+
+宏会将源码中的原始消息保留为运行时兜底（fallback），因此英文文本会紧随翻译内容一同打包。基准测试在所有优化方案中均测得 `fr` 页面中含有 **3-15% 的 `en` 文本**。Intlayer 在构建期解析 fallback，并且只打包当前激活的语言。
+
+</Question>
+
+<Question title="Lingui 的每页 JS 体积真的很有竞争力吗？">
+
+是的，在 TanStack Start 上它甚至微弱胜出：`dynamic` 模式下为 115.2 KB（Intlayer 为 118.6 KB）。采用哈希 ID 的编译目录非常紧凑。但开销体现在其他方面：注水耗时 28-34 ms（Intlayer 为 11-14 ms），在 `scoped-dynamic` 配置下语言切换耗时高达 **42 ms**。
+
+</Question>
+
+<Question title="迁移需要放弃宏吗？">
+
+不需要。`@intlayer/lingui` 让 `` t`...` ``、`<Trans>`、`msg`、`plural`、`select` 和 `selectOrdinal` 保持原样编译；仅仅是 `i18n._()` 底层解析的数据来源发生了改变。在构建中保留 `@lingui/babel-plugin-lingui-macro` 或 `@lingui/swc-plugin` 即可。参见 [Lingui 兼容性文档](https://intlayer.org/zh/doc/compatibility/lingui)。
+
+</Question>
+
+<Question title="提取和编译步骤怎么处理？">
+
+宏代码继续保留这两个步骤，但对于 Intlayer 自身的内容则完全不需要。`.content.ts` 字典在打包器运行时自动生成，无需单独的 CLI 命令，并且 [`intlayer test`](https://intlayer.org/zh/doc/concept/cli) 会在缺失键时直接让 CI 报错，而不是静默回退到源文本。
+
+</Question>
+
+</FAQ>
 
 ## 相关对比评测
 
-- [next-intl vs Intlayer](https://intlayer.org/zh/blog/next-intl-vs-intlayer)（同一基准测试）
-- [i18next vs Intlayer](https://intlayer.org/zh/blog/i18next-vs-intlayer)（同一基准测试）
-- [vue-i18n vs Intlayer](https://intlayer.org/zh/blog/vue-i18n-vs-intlayer-benchmark)（同一基准测试）
-- [编译器型与声明式 i18n 理念对比](https://intlayer.org/zh/blog/compiler-vs-declarative-i18n)
+相同基准测试，其他库：
+
+- [next-intl vs Intlayer](https://intlayer.org/zh/blog/next-intl-vs-intlayer)
+- [i18next vs Intlayer](https://intlayer.org/zh/blog/i18next-vs-intlayer)
+- [vue-i18n vs Intlayer benchmark](https://intlayer.org/zh/blog/vue-i18n-vs-intlayer-benchmark)
+- [next-i18next vs next-intl vs Intlayer](https://intlayer.org/zh/blog/next-i18next-vs-next-intl-vs-intlayer)
+- [react-i18next vs react-intl vs Intlayer](https://intlayer.org/zh/blog/react-i18next-vs-react-intl-vs-intlayer)
+
+深入了解：
+
+- [Lingui vs @intlayer/lingui](https://intlayer.org/zh/blog/lingui-vs-intlayer-lingui), 在同一应用上实测的适配器
+- [Compiler-driven vs declarative i18n](https://intlayer.org/zh/blog/compiler-vs-declarative-i18n)
+- [Per-component vs centralized i18n](https://intlayer.org/zh/blog/per-component-vs-centralized-i18n)
+- [ICU message format explained](https://intlayer.org/zh/blog/icu-message-format)
+
+参考文档：
+
+- [Next.js 基准测试报告](https://intlayer.org/zh/doc/benchmark/nextjs) 与 [TanStack Start 基准测试报告](https://intlayer.org/zh/doc/benchmark/tanstack)
+- [Compat adapter: Lingui](https://intlayer.org/zh/doc/compatibility/lingui)
+- [包体积优化](https://intlayer.org/zh/doc/concept/bundle-optimization) 与 [Intlayer 编译器](https://intlayer.org/zh/doc/compiler)
 
 ## GitHub 星标发展历程
 

package/blog/zh/next-intl_vs_intlayer-next-intl.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-09-13
-updatedAt: 2026-09-13
+updatedAt: 2026-09-22
 title: "next-intl vs @intlayer/next-intl: 相同的 API，不同的 Bundle"
 description: 当 Next.js 应用程序的 next-intl 导入由 @intlayer/next-intl 兼容适配器提供时会发生什么。在相同代码上测量的 Bundle 大小、泄漏、组件大小和水合，以及适配器保留、忽略和无法替换的内容。
 keywords:
@@ -26,6 +26,8 @@ author: aymericzip
 
 # next-intl VS @intlayer/next-intl | 相同的 API，不同的 Bundle
 
+![next-intl VS Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/assets/i18next-next-intl-intlayer.webp?raw=true)
+
 `@intlayer/next-intl` 是一个兼容适配器：它暴露 `next-intl` API（`useTranslations`、`getTranslations`、`useLocale`、`t.rich()`、ICU 复数、`NextIntlClientProvider`...），并从 Intlayer 编译的字典中提供服务。应用代码不会改变。但 bundle 会改变。
 
 本文在同一个 Next.js 应用上对两者进行了比较，一次使用 `next-intl` 构建，一次使用适配器构建。这些数据来自 [Benchmark Bloom](https://github.com/intlayer-org/benchmark-bloom)，一个记录浏览器实际下载内容的开源套件。如果你想要 `next-intl` vs Intlayer 作为库的比较，请阅读 [next-intl vs Intlayer](https://intlayer.org/blog/next-intl-vs-intlayer)。本文是关于当你保持组件原样不变时，适配器改变了什么。
@@ -109,6 +111,10 @@ const AboutPage = () => {
 
 ### Next.js 上的结果
 
+选择您关注的指标和库：
+
+<I18nBenchmark framework="nextjs" vertical/>
+
 | 设置                      | 策略           | 库大小 (gz) | 页面 JS 平均 (gz) | 语言环境泄漏 | 页面泄漏 | 组件平均 (gz) |  E2E 响应性 |        水合 |
 | ------------------------- | -------------- | ----------: | ----------------: | -----------: | -------: | ------------: | ----------: | ----------: |
 | **base** (no i18n)        | -              |      0.0 KB |          141.0 KB |         0.0% |     0.0% |        0.9 KB |     13.4 ms |     11.8 ms |
@@ -129,6 +135,15 @@ const AboutPage = () => {
 - **Hydration 快 2 ms**（12.8 vs 14.7 ms）：在 React 可以 hydrate 之前，无需从 RSC payload 反序列化消息对象。
 - **adapter 不是原生 runtime。** `next-intlayer` 位于 **141.3 KB**，比基础应用多 0.3 KB，带有 5.5 KB 的 runtime。adapter 在 Intlayer 的核心之上提供 `next-intl` API 表面（`useFormatter`、`t.rich`、ICU resolver），因此有 8.0 KB 和每页 +6 KB。它是桥接器，而不是目的地。
 
+<ClickToOpenIframe
+src="https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-nextjs.md"
+width="100%"
+height="600px"
+style="border:none;"
+/>
+
+> 完整表格、所有库和策略请参阅 [Next.js 基准测试报告](https://intlayer.org/zh/doc/benchmark/nextjs)。
+
 ### TanStack Start 上的结果（`use-intl`）
 
 `use-intl` 是 `next-intl` 的框架无关核心。其 adapter `@intlayer/use-intl` 采用相同的设计，配合 Vite plugin（`@intlayer/use-intl/plugin`）。
@@ -152,11 +167,24 @@ const AboutPage = () => {
 - **区域设置切换更快。** 优化的 `use-intl` 设置需要 **13-21 ms** 来更新 `html[lang]`；适配器需要 **4-9 ms**。更少的组件重新渲染，并且不会从消息树中重新提取任何内容。
 - **`static` 保留每个区域设置。** 适配器的 `static` 行显示 49.7% 的区域设置泄漏，与 `static` 模式下的本地 Intlayer 相同：所有区域设置都被打包，只有页面的字典。一行配置（`importMode: 'dynamic'`）就可以消除它。
 
+<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;"
+/>
+
+> 完整表格请参阅 [TanStack Start 基准测试报告](https://intlayer.org/zh/doc/benchmark/tanstack)。
+
 ## 为什么数字会变动
 
+![The Intlayer compiler extracts content from components](https://github.com/aymericzip/intlayer/blob/main/docs/assets/compiler.webp?raw=true)
+
 组件中没有任何改变，所以所有收益完全来自于 `useTranslations` 绑定的内容。
 
-**使用 `next-intl`**，绑定是 provider。`NextIntlClientProvider` 为该 locale 接收整个 `messages` 对象；每个 `useTranslations("about")` 都从中读取。bundler 看到一个组件导入一个读取一个 context 的 hook，无法知道只使用了 `about` 分支。下面的路由都共享同一个消息对象，所以 page-leak 列显示约 ~90%，直到你自己分割文件。
+**使用 `next-intl`**，绑定是 provider。`NextIntlClientProvider` 为该 locale 接收整个 `messages` 对象；每个 `useTranslations("about")` 都从中读取。bundler 看到一个组件导入一个读取一个 context 的 hook，无法知道只使用了 `about` 分支。下面的路由都共享同一个消息对象，所以 page-leak 列显示约 ~90%，直到你自己分割文件, 并且这种开销在页面和语言两个维度上同时增长：
+
+![Theoretical content leakage by architecture](https://github.com/aymericzip/intlayer/blob/main/docs/assets/theorical_content_leakage.webp?raw=true)
 
 ```bash
 .
@@ -280,25 +308,106 @@ export default withIntlayer(nextConfig);
 
 ## 开始前需要了解的限制
 
-- **路由配置移至 `intlayer.config.ts`。** `createNavigation(routing)` 和 `createMiddleware(routing)` 保持其签名但忽略该参数：locale、默认 locale 和前缀策略来自 Intlayer 的 `routing` 配置。如果你使用 `next-intl` 的本地化 `pathnames`（`/about` → `/a-propos`），适配器不会对其进行插值；Intlayer 的 `routing.rewrite` 涵盖了这个情况，但这是一个单独的更改。
-- **无命名空间的 `useTranslations()` 未绑定。** 优化过程需要一个静态命名空间来了解要导入哪个字典。一个空调用仍然有效，通过一个引用每个字典的运行时注册表，这正是你试图移除的泄漏。传递命名空间。
-- **该适配器不是免费的。** 8.0 KB 的运行时相对于 `next-intlayer` 的 5.5 KB，以及原生构建之上每页 +6-7 KB。它支付了 `next-intl` API 表面的成本。如果你到达了每个组件都已移至 `useIntlayer` 的阶段，请放弃该适配器。
-- **提供者上的 `messages`、`timeZone`、`now` 被忽略。** 格式化器由原生 `Intl` 支持，只有语言环境影响其输出；如果你依赖于强制时区或固定的 `now` 用于水合稳定日期，请在调用点处理。
+<AccordionGroup>
+<Accordion header="路由配置迁移至 intlayer.config.ts">
+
+`createNavigation(routing)` 和 `createMiddleware(routing)` 保留其函数签名但忽略该参数：支持的语言、默认语言和前缀策略均来自 Intlayer 的 `routing` 配置。如果您使用 `next-intl` 的本地化路径 `pathnames`（`/about` 转 `/a-propos`），适配器不会对其进行插值；Intlayer 的 `routing.rewrite` 涵盖了这种情况，但这是一项单独的改动。
+
+</Accordion>
+<Accordion header="未指定命名空间的 useTranslations() 不会被自动绑定">
+
+优化过程需要一个静态命名空间来确定要导入的字典。无参数调用仍可通过引用每个字典的运行时注册表运行，但这恰恰是您试图消除的内容泄漏。请显式传递命名空间。
+
+</Accordion>
+<Accordion header="适配器并非零开销">
+
+运行时体积为 8.0 KB，而原生 `next-intlayer` 为 5.5 KB，且每页比原生构建多出 +6-7 KB。这是为了兼容 `next-intl` API 表面所付出的代价。如果每个组件都迁移到了 `useIntlayer`，请直接移除适配器。
+
+</Accordion>
+<Accordion header="provider 上的 messages、timeZone 和 now 将被忽略">
+
+格式化器由原生 `Intl` 提供支持，只有当前语言会影响其输出。如果您依赖强制的时区或固定的 `now` 来获得注水稳定的日期，请在调用处自行处理。参见[日期、时间和数字格式化](https://intlayer.org/zh/blog/date-time-number-formatting-locales)。
+
+</Accordion>
+</AccordionGroup>
 
 ## 何时使用哪一个？
 
-- **坚持使用 `next-intl`** 如果你的应用程序很小，你的 bundle 不是问题，你的团队对拥有命名空间和每页 `pick()` 感到舒适。
-- **使用 `@intlayer/next-intl`**，如果你正在使用 `next-intl`，并希望获得 bundle、leakage 和 hydration 方面的改进、类型化的 keys 以及 CLI / CMS 工具，而无需重写代码。这是任何现有 `next-intl` codebase 的推荐入口点。
-- **使用原生方案 (`next-intlayer`)**，用于新项目，或者一旦 adapter 完成其工作。它是这三者中最轻量的（5.5 KB，每页 +0.3 KB），并且支持同步 server components、per-component `.content.ts` 文件和完整功能集。
+<AccordionGroup>
+<Accordion header="留在 next-intl">
+
+您的应用规模较小，无需担心打包体积，且团队乐于手动维护命名空间和按页面 `pick()`。
+
+</Accordion>
+<Accordion header="使用 @intlayer/next-intl">
+
+您目前已在使用 `next-intl`，希望在无需重写代码的情况下获得包体积、防泄漏和更快的注水收益，并获得类型化键以及 CLI / CMS 工具支持。这是任何现有 `next-intl` 代码库的最佳切入点。
+
+</Accordion>
+<Accordion header="使用原生 (next-intlayer)">
+
+适用于新项目，或适配器完成过渡任务后。它是三者中最轻量级的（5.5 KB，每页仅增加 +0.3 KB），并解锁同步服务端组件、按组件就近维护 `.content.ts` 文件以及完整的全套功能。请阅读 [在 Next.js 中使用 Intlayer](https://intlayer.org/zh/doc/environment/nextjs)。
+
+</Accordion>
+</AccordionGroup>
+
+## 常见问题
+
+<FAQ>
+
+<Question title="我的应用代码真的可以保持不变吗？">
+
+在 Next.js 中，组件代码完全无需修改：基准测试构建仅修改了 `next.config.ts` 和 `intlayer.config.ts`。`src/i18n.ts` 中的 `getRequestConfig`、provider 上的 `messages` 属性以及每页的 `pick()` 调用都会变成无用代码，您后续可以将其删除。
+
+</Question>
+
+<Question title="ICU 消息支持情况如何？">
+
+它们可以继续正常工作。`t("key", { count })`、`t.rich()`、`t.markup()`、`select`、`selectordinal`、`#` 和 `{ts, date, long}` 均由 Intlayer 的 ICU 解析器处理。参见 [ICU 消息格式](https://intlayer.org/zh/blog/icu-message-format)。
+
+</Question>
+
+<Question title="为什么适配器比原生 next-intlayer 更重？">
+
+它在 Intlayer 核心之上承载了整个 `next-intl` API 表面：`useFormatter`、`t.rich`、ICU 解析器、导航辅助工具。这使得体积达到 8.0 KB（原生为 5.5 KB），且每页多出 +6 KB。它是过渡桥梁，而不是最终目的地。
+
+</Question>
+
+<Question title="我可以按组件逐个迁移吗？">
+
+可以。任何组件都可以随时从 `useTranslations("about")` 切换到使用就近 `.content.ts` 文件的 `useIntlayer("about")`。JSON 和 `.content.ts` 字典可以共存并自动合并。
+
+</Question>
+
+<Question title="本地化路径 (pathnames) 能正常工作吗？">
+
+不能通过 `next-intl` 的 `pathnames` 生效：适配器接受其用于类型推断但不会进行插值。请改用 Intlayer 的 `routing.rewrite`，它会将本地化字面量生成到类型注册表中。
+
+</Question>
+
+</FAQ>
 
 ## 相关比较
 
-- [next-intl vs Intlayer](https://intlayer.org/blog/next-intl-vs-intlayer)（库本身，相同的基准）
-- [i18next vs @intlayer/i18next](https://intlayer.org/blog/i18next-vs-intlayer-i18next)（同一 adapter 系列）
-- [Lingui vs @intlayer/lingui](https://intlayer.org/blog/lingui-vs-intlayer-lingui)（相同的适配器系列）
-- [vue-i18n vs @intlayer/vue-i18n](https://intlayer.org/blog/vue-i18n-vs-intlayer-vue-i18n)（相同的适配器系列）
-- [迁移指南：next-intl 到 Intlayer](https://intlayer.org/doc/migration/next-intl)
-- [兼容性适配器参考：next-intl](https://intlayer.org/doc/compatibility/next-intl)
+同一适配器系列：
+
+- [i18next vs @intlayer/i18next](https://intlayer.org/zh/blog/i18next-vs-intlayer-i18next)
+- [Lingui vs @intlayer/lingui](https://intlayer.org/zh/blog/lingui-vs-intlayer-lingui)
+- [vue-i18n vs @intlayer/vue-i18n](https://intlayer.org/zh/blog/vue-i18n-vs-intlayer-vue-i18n)
+
+两款库的直接对比：
+
+- [next-intl vs Intlayer](https://intlayer.org/zh/blog/next-intl-vs-intlayer), 相同基准测试
+- [next-i18next vs next-intl vs Intlayer](https://intlayer.org/zh/blog/next-i18next-vs-next-intl-vs-intlayer)
+- [Is next-intl outdated?](https://intlayer.org/zh/blog/is-next-intl-outdated)
+
+参考文档：
+
+- [Compat adapter: next-intl](https://intlayer.org/zh/doc/compatibility/next-intl)
+- [迁移指南：从 next-intl 到 Intlayer](https://intlayer.org/zh/doc/migration/next-intl)
+- [Next.js 基准测试报告](https://intlayer.org/zh/doc/benchmark/nextjs) 与 [TanStack Start 基准测试报告](https://intlayer.org/zh/doc/benchmark/tanstack)
+- [包体积优化](https://intlayer.org/zh/doc/concept/bundle-optimization) 与 [Intlayer 编译器](https://intlayer.org/zh/doc/compiler)
+- [可视化编辑器](https://intlayer.org/zh/doc/concept/editor)、[CMS](https://intlayer.org/zh/doc/concept/cms) 与 [AI 翻译](https://intlayer.org/zh/doc/concept/auto-fill)
 
 ## 总结