@intlayer/docs 9.5.5 → 9.5.7

package/blog/zh/i18next_vs_intlayer.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-09-13
-updatedAt: 2026-09-13
+updatedAt: 2026-09-22
 title: "i18next vs Intlayer: 2026年基准测试与深度对比"
 description: "在 Next.js 和 TanStack Start 上对比评测 react-i18next、next-i18next 与 Intlayer。涵盖打包体积、多余内容泄露、语言切换响应速度及开发体验。"
 keywords:
@@ -25,6 +25,8 @@ author: aymericzip
 
 # i18next VS Intlayer | React & Next.js 国际化 (i18n) 基准测试对比
 
+![i18next VS Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/assets/i18next-next-intl-intlayer.webp?raw=true)
+
 `i18next` 是 JavaScript 生态中最广泛使用的国际化（i18n）框架。通过 `react-i18next` 和 `next-i18next`，它为大量的 React 和 Next.js 应用提供支持。Intlayer 则是基于编译器、按组件作用域划分的现代化替代方案。
 
 本文基于实测数据而非功能清单进行对比。所有数据均来自 [Benchmark Bloom](https://github.com/intlayer-org/benchmark-bloom)，这是一个开源基准测试套件，它使用每个库构建完全相同的应用，并精确记录浏览器实际下载的内容。
@@ -99,6 +101,10 @@ Intlayer 无需独立的 "scoped" 策略: 编译器会自动**以组件为粒度
 
 ### Next.js 平台测试结果 (`next-i18next`)
 
+选择您关注的指标和库：
+
+<I18nBenchmark framework="nextjs" vertical/>
+
 | 方案                              | 策略           | 库体积 (gz) | 页面平均 JS (gz) | 语言泄露率 | 页面泄露率 | 组件平均体积 (gz) | 端到端响应时间 | 水合耗时 |
 | --------------------------------- | -------------- | ----------: | ---------------: | ---------: | ---------: | ----------------: | -------------: | -------: |
 | **base** (无 i18n)                | -              |      0.0 KB |         141.0 KB |       0.0% |       0.0% |            0.9 KB |        13.4 ms |  11.8 ms |
@@ -119,6 +125,15 @@ Intlayer 无需独立的 "scoped" 策略: 编译器会自动**以组件为粒度
 - **组件级打包体积**: 调用 `useTranslation()` 的组件打包体积在 26 到 79 KB 之间；而使用 `useIntlayer()` 的相同组件仅需 6.9 KB。
 - **水合延迟**: 在 `dynamic` 配置下，水合耗时飙升至 27.7 ms，这是因为客户端在 React 启动水合之前，i18next 实例必须完成初始化并解析后端。
 
+<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 平台测试结果 (`react-i18next`)
 
 为了排除 Next.js 平台特有机制的影响，在 TanStack Start 上直接运行纯粹的 `react-i18next`:
@@ -141,8 +156,19 @@ Intlayer 无需独立的 "scoped" 策略: 编译器会自动**以组件为粒度
 - Intlayer 的 `static` 策略已默认具备 **0% 页面泄露**，因为仅打包当前页面组件显式导入的字典。若开启 `importMode: 'dynamic'`，更可彻底杜绝语言层面的泄露。
 - **组件体积差异**: `react-i18next` 单组件占用 24-27 KB，而 Intlayer 仅为 6-8 KB。因为 `useTranslation()` 会将每个组件与全局 i18next 实例绑定。
 
+<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)。
+
 ## 为什么差距如此悬殊？全局实例模式 vs 编译时字典
 
+![Centralized catalogs versus per-component dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/assets/project_stucture_18n_vs_intlayer.png?raw=true)
+
 `i18next` 最初于 2012 年设计为纯运行时架构: 全局单一实例维护资源仓库，各种插件对其进行扩展，并在组件渲染时通过 `t()` 查找键名。这种设计赋予了它极高的通用性（支持任何框架、后端与文件格式），但也是其性能开销的根源:
 
 ```bash
@@ -166,7 +192,13 @@ Intlayer 无需独立的 "scoped" 策略: 编译器会自动**以组件为粒度
                 └── page.tsx     # 必须明确知道该页面依赖 ["common", "about"]
 ```
 
-全局实例在运行时无法预知某个组件到底会请求哪些键，因此只能加载开发者预先指定的整个命名空间。优化意味着**开发者必须**手动拆分翻译文件为命名空间、**必须**在每个页面手动枚举所需命名空间，并且在组件移动或重构时**必须**手动同步这一映射清单。正如[基准测试总结](https://github.com/intlayer-org/benchmark-bloom/blob/main/report/NOTE.md)所言: “在保证类型安全的同时，精确维护每个页面需要哪些命名空间简直是一场噩梦”。
+全局实例在运行时无法预知某个组件到底会请求哪些键，因此只能加载开发者预先指定的整个命名空间。优化意味着**开发者必须**手动拆分翻译文件为命名空间、**必须**在每个页面手动枚举所需命名空间，并且在组件移动或重构时**必须**手动同步这一映射清单。
+
+资源开销在页面与语言两个维度上成倍激增：
+
+![Theoretical content leakage by architecture](https://github.com/aymericzip/intlayer/blob/main/docs/assets/theorical_content_leakage.webp?raw=true)
+
+正如 [基准测试总结](https://github.com/intlayer-org/benchmark-bloom/blob/main/report/NOTE.md)所言: “在保证类型安全的同时，精确维护每个页面需要哪些命名空间简直是一场噩梦”。
 
 Intlayer 彻底抛弃了全局实例模式。翻译内容直接声明在组件同级，编译器在构建阶段直接解析依赖图谱:
 
@@ -193,7 +225,8 @@ Intlayer 彻底抛弃了全局实例模式。翻译内容直接声明在组件
 
 ### 初始化配置
 
-**next-i18next (App Router)**
+<Tabs defaultTab="intlayer" group="techno">
+<Tab label="next-i18next" value="i18next">
 
 ```ts fileName="src/app/i18n/server.ts"
 import { createInstance } from "i18next";
@@ -228,7 +261,8 @@ export const initI18next = async (
 
 此外还需要编写客户端 `I18nProvider`，配置 `generateStaticParams`，并在每个页面显式指定 `namespaces` 数组。
 
-**Intlayer**
+</Tab>
+<Tab label="Intlayer" value="intlayer">
 
 ```ts fileName="intlayer.config.ts"
 import { type IntlayerConfig, Locales } from "intlayer";
@@ -264,9 +298,13 @@ const LocaleLayout: NextLayoutIntlayer = async ({ children, params }) => {
 export default LocaleLayout;
 ```
 
+</Tab>
+</Tabs>
+
 ### 客户端组件开发
 
-**react-i18next**
+<Tabs defaultTab="intlayer" group="techno">
+<Tab label="react-i18next" value="i18next">
 
 ```json fileName="src/locales/en/about.json"
 {
@@ -304,7 +342,8 @@ export const Counter = () => {
 
 > 渲染该组件的页面必须确保预加载了 `about` 命名空间，且除非扩展 `CustomTypeOptions`，否则 `t("counter.label")` 只是无类型保护的普通字符串。
 
-**Intlayer**
+</Tab>
+<Tab label="Intlayer" value="intlayer">
 
 ```ts fileName="src/components/Counter/index.content.ts"
 import { t, type Dictionary } from "intlayer";
@@ -345,9 +384,13 @@ export const Counter = () => {
 
 `label` 和 `increment` 拥有完全严格的自动类型推导；输错字段名会直接触发 TypeScript 编译报错，如果缺少法语翻译则会在构建时立即拦截。
 
+</Tab>
+</Tabs>
+
 ### 同步服务端组件 (RSC)
 
-**next-i18next**
+<Tabs defaultTab="intlayer" group="techno">
+<Tab label="next-i18next" value="i18next">
 
 ```tsx fileName="src/components/ServerCounter.tsx"
 type ServerCounterProps = {
@@ -366,7 +409,8 @@ export const ServerCounter = ({ t, locale, count }: ServerCounterProps) => (
 
 顶层页面必须先调用 `i18n.getFixedT(locale, "about")`，然后通过 Props 将 `t` 和 `locale` 逐层传递给子组件。
 
-**Intlayer**
+</Tab>
+<Tab label="Intlayer" value="intlayer">
 
 ```tsx fileName="src/components/ServerCounter.tsx"
 import { useIntlayer } from "next-intlayer/server";
@@ -385,6 +429,9 @@ export const ServerCounter = ({ count }: { count: number }) => {
 };
 ```
 
+</Tab>
+</Tabs>
+
 ## 保留 i18next API，直接享受 Intlayer 的极致性能
 
 你不必重写所有组件也能享受上述基准测试中的性能红利。`@intlayer/i18next`、`@intlayer/react-i18next` 和 `@intlayer/next-i18next` 提供了即插即用的兼容适配器: 代码中现有的 `useTranslation`、`t()`、`<Trans>`、`{{interpolation}}`、复数形式与上下文后缀均可无缝工作，底层则由 Intlayer 编译器自动优化并按需分发字典。
@@ -415,18 +462,85 @@ export default defineConfig({
 
 ## 如何做出选择？
 
-- **选择 i18next**: 如果你的应用极度依赖其庞大的插件生态（特定语言检测器、特殊后端、ICU、Locize 等），需要在 React 之外（如 Node.js 后端服务、原生 JS 或其他前端框架）统一国际化方案，团队成员已有深度积累，或者外部翻译平台硬性要求使用 `locales/{lng}/{ns}.json` 目录结构。若追求性能，需预留充足精力维护命名空间与页面加载清单。
-- **选择 Intlayer**: 如果你追求**就近组织组件文本**、**严苛的 TypeScript 类型安全**、**构建期漏翻即时报错**、**零配置自动 Tree-shaking 与按需懒加载**、瞬时语言切换、原生同步服务端组件支持以及开箱即用的可视化编辑器 / CMS / AI 翻译工具流。在大型复杂模块化项目及设计系统中表现尤为出色。
-- **选择 `@intlayer/*-i18next` 适配器**: 如果你已经在运行大型 i18next 项目，并希望零成本获取打包体积缩减与响应速度提升。
+<AccordionGroup>
+<Accordion header="选择 i18next">
+
+如果你的应用极度依赖其庞大的插件生态（特定语言检测器、特殊后端、ICU、Locize 等），需要在 React 之外（如 Node.js 后端服务、原生 JS 或其他前端框架）统一国际化方案，团队成员已有深度积累，或者外部翻译平台硬性要求使用 `locales/{lng}/{ns}.json` 目录结构。若追求性能，需预留充足精力维护命名空间与页面加载清单。
+
+</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/*-i18next 适配层">
+
+您现有项目已深度依赖 i18next，希望在完全不重构组件代码的前提下，立即获取包体积缩减与极致响应速度。您的 `locales/{lng}/{ns}.json` 文件继续作为唯一事实来源。在 [i18next vs @intlayer/i18next](https://intlayer.org/zh/blog/i18next-vs-intlayer-i18next) 中进行了同台实测。
+
+</Accordion>
+</AccordionGroup>
+
+## 常见问题解答 (FAQ)
+
+<FAQ>
+
+<Question title="为什么 i18next 的体积比其他现代国际化库大得多？">
+
+它最初被设计为跨框架的通用运行时：全局单例实例、插件执行管道、资源存储库、键名解析器。这种高灵活性全部被编译进了每个客户端包中。一个仅引入该库的空组件在 `next-i18next` 下需要 **19.7 KB gzip**，而 `next-intlayer` 仅需 **5.5 KB**，且这一基准开销在每个页面都必须无差别承担。
+
+</Question>
+
+<Question title="通过后端加载插件（Lazy Loading）能否彻底解决开销问题？">
+
+它仅优化了下载字节数，却牺牲了交互延迟。采用 `i18next-resources-to-backend` 每页节省了 ~49 KB，但在切换语言时增加了网络往返延迟：在 `dynamic` 配置下为 **123 ms**，在 `scoped-static` 下为 **185 ms**，而 Intlayer 仅需 **3-4 ms**。客户端水合耗时也激增至 27.7 ms，因为实例必须在 React 水合前完成远程解析。
+
+</Question>
+
+<Question title="使用 i18next 能否达到 0% 内容泄漏？">
+
+可以，通过 `scoped-dynamic` 方案：为每个路由划分独立的命名空间、配置资源后端并人工维护页面与命名空间的映射表。这使 Next.js 页面体积降至 163.4 KB，但仍比零配置的 Intlayer（141.3 KB）多出 **+22 KB**。请参阅[包体积优化指南](https://intlayer.org/zh/doc/concept/bundle-optimization)。
+
+</Question>
+
+<Question title="迁移到 Intlayer 是否需要彻底重写我的现有组件？">
+
+不需要。`@intlayer/i18next`、`@intlayer/react-i18next` 和 `@intlayer/next-i18next` 完整保留了 `useTranslation`、`t()`、`<Trans>`、`{{interpolation}}`、`_one` / `_other` 复数规则、上下文后缀及 `returnObjects`。仅需在 `next.config.ts` 或 `vite.config.ts` 中配置一行插件即可。详见 [next-i18next 迁移指南](https://intlayer.org/zh/doc/migration/next-i18next)。
+
+</Question>
+
+<Question title="我原有的 i18next 插件会受到什么影响？">
+
+后端加载器与语言探测器依然会被接收但处于空转状态：运行时不再需要加载或探测任何内容。语言探测被 Intlayer 的原生路由策略（URL 前缀、Cookie、Header）接管。若您的应用依赖请求期从 CMS 动态获取翻译，请改用 [Intlayer CMS](https://intlayer.org/zh/doc/concept/cms) 或 `intlayer pull` / `push` 指令。
+
+</Question>
+
+</FAQ>
 
 ## 相关对比
 
-- [next-intl vs Intlayer](https://intlayer.org/zh/blog/next-intl-vs-intlayer) (同一基准测试)
-- [Lingui vs Intlayer](https://intlayer.org/zh/blog/lingui-vs-intlayer) (同一基准测试)
-- [vue-i18n vs Intlayer 评测](https://intlayer.org/zh/blog/vue-i18n-vs-intlayer-benchmark) (同一基准测试)
+同类基准测试，其他国际化库：
+
+- [next-intl vs Intlayer](https://intlayer.org/zh/blog/next-intl-vs-intlayer)
+- [Lingui vs Intlayer](https://intlayer.org/zh/blog/lingui-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)
+
+深入探索 i18next 与 Intlayer：
+
+- [i18next vs @intlayer/i18next](https://intlayer.org/zh/blog/i18next-vs-intlayer-i18next)，在相同应用下的适配器性能实测
 - [i18next 已经过时了吗？](https://intlayer.org/zh/blog/is-i18next-outdated)
+- [在 i18next 中使用 Intlayer](https://intlayer.org/zh/blog/intlayer-with-i18next) 以及[在 react-i18next 中使用](https://intlayer.org/zh/blog/intlayer-with-react-i18next)
+- [如何使用 next-i18next 实现 Next.js 应用国际化](https://intlayer.org/zh/blog/nextjs-internationalization-using-next-i18next)
+
+核心参考文档：
+
+- [Next.js 基准测试报告](https://intlayer.org/zh/doc/benchmark/nextjs) 与 [TanStack Start 基准测试报告](https://intlayer.org/zh/doc/benchmark/tanstack)
+- 兼容适配器：[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)
+- 迁移指南：[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)
+- [包体积优化](https://intlayer.org/zh/doc/concept/bundle-optimization) 与 [Intlayer 编译器](https://intlayer.org/zh/doc/compiler)
+- [组件级 vs 集中式 i18n](https://intlayer.org/zh/blog/per-component-vs-centralized-i18n)
+- [编译器驱动 vs 声明式 i18n](https://intlayer.org/zh/blog/compiler-vs-declarative-i18n)
 
 ## GitHub 关注度趋势 (STARs)
 

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 星标发展历程