@intlayer/docs 9.5.6 → 9.5.8

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/is_intlayer_lighter_than_paraglide.md

@@ -0,0 +1,284 @@
+---
+createdAt: 2026-09-23
+updatedAt: 2026-09-23
+title: Intlayer 比 Paraglide 更轻量吗？
+description: Paraglide 在 i18n 基准测试中看起来几乎没有开销，因为其代码是直接生成到你的代码库中的。本文将深入分析其实际体积去了哪里、为什么按节点读取语言会带来性能损耗，以及 Intlayer 的动态加载如何做到仅下发单一语言而非全量语言包。
+keywords:
+  - Paraglide
+  - Intlayer
+  - 国际化
+  - i18n
+  - Bundle size
+  - Tree shaking
+  - Benchmark
+  - Blog
+slugs:
+  - blog
+  - is-intlayer-lighter-than-paraglide
+author: aymericzip
+---
+
+# Intlayer 比 Paraglide 更轻量吗？
+
+是的。
+
+`Paraglide` 作为业界公认非常轻量的 i18n 解决方案享有良好声誉，初看之下，[基准测试](https://intlayer.org/zh/doc/benchmark/tanstack) 也印证了这一点：其库体积几乎为零。然而，库体积为零并不代表下发到浏览器的体积为零。这只意味着字节被转移到了该指标不统计的地方。
+
+<TOC/>
+
+## 核心要点
+
+**库体积只是被隐藏了，并没有消失：**
+
+Paraglide 将其 runtime 和消息函数直接生成到你的代码库中。这部分代码虽然依然传输给浏览器，但被归类为_你的_代码，而不是库的代码。
+
+**无 Provider 并非免费的午餐：**
+
+每次调用 `m.my_key()` 都会自行解析语言，在渲染每个节点时都要读取 cookie 或本地存储，而不是从 context 中一次性读取。
+
+**缺乏动态加载机制：**
+
+Paraglide 会将一条消息的所有语言全部引入客户端 bundle 中。而 Intlayer 在配置 `importMode: 'dynamic'` 或 `'fetch'` 时，仅加载当前正在渲染的单一语言。
+
+**Tree Shaking 并非总是生效：**
+
+在我们的部分基准测试中，Paraglide 宣传的 Tree Shaking 未能起效。建议务必检查你自己的 bundle 体积。
+
+## Paraglide 的体积究竟去了哪里？
+
+在基准测试报告中，“库体积”指标衡量的是在添加任何业务内容之前，空组件中各 i18n 库的 Provider 和 Hook 体积。
+
+| 库 (TanStack Start)           | 库体积 (gz) | 库体积 (min) |
+| ----------------------------- | ----------- | ------------ |
+| `@inlang/paraglide-js@2.15.1` | 1.8 KB      | 4.5 KB       |
+| `react-intlayer@9.5.1`        | 5.0 KB      | 15.2 KB      |
+
+单看这项数据，Paraglide 确实获胜。但 Paraglide 本质上是一个编译器：它读取你的 `messages/*.json` 文件，并在你的仓库中生成一个 `paraglide/` 目录，其中包含 `runtime.js`（语言检测、cookie 和存储策略、URL 本地化）以及每个消息对应的 JavaScript 函数。
+
+```bash
+src/paraglide/
+├── runtime.js      # 语言检测、策略、URL 辅助工具
+├── server.js
+├── messages.js     # 重新导出所有消息
+└── messages/
+    ├── _index.js
+    ├── en.js
+    └── fr.js
+```
+
+由于这些代码位于你的 `src/` 目录下且通过相对路径导入，打包工具会将其归算到你的应用程序中，而不是 `node_modules` 包。因此，库体积一栏几乎显示为零，但相同的业务逻辑依旧被完整打包进了你的页面 bundle 中。
+
+生成代码本身并不是坏事：生成的 runtime 仅包含你配置中真正需要的逻辑（前缀策略、cookie 与 local storage 选择等）。Intlayer 则通过另一种方式达到相同效果，即在构建时注入环境变量，使打包工具自动剔除你配置未启用的代码分支。这两种方案最终都比 `i18next` 或 `next-intl` 轻量 3 到 10 倍。
+
+因此，真正公平的衡量标准并不是库体积，而是**每个页面实际传输的 JavaScript 体积**。
+
+## 页面实测体积
+
+TanStack Start 应用，10 个页面，在 `en` 和 `fr` 路由上进行实测（经 gzip 压缩）：
+
+| 配置                               | 页面 JS 平均 (gz) | 超出基准    | 语言泄露率 | 跨页面泄露率 |
+| ---------------------------------- | ----------------- | ----------- | ---------- | ------------ |
+| 基准（无 i18n）                    | 111.0 KB          | -           | 0.0%       | 0.0%         |
+| `paraglide`（任何策略）            | 125.1 KB          | +14.1 KB    | 49.7%      | 0.0%         |
+| `intlayer` (`importMode: static`)  | 125.8 KB          | +14.8 KB    | 50.0%      | 0.0%         |
+| `intlayer` (`importMode: dynamic`) | **118.6 KB**      | **+7.6 KB** | **0.0%**   | **0.0%**     |
+
+Next.js 16 App Router，同一应用：
+
+| 配置             | 页面 JS 平均 (gz) | 超出基准    |
+| ---------------- | ----------------- | ----------- |
+| 基准（无 i18n）  | 141.0 KB          | -           |
+| `paraglide-next` | 155.3 KB          | +14.3 KB    |
+| `next-intlayer`  | **141.3 KB**      | **+0.3 KB** |
+
+<I18nBenchmark framework="tanstack" vertical/>
+
+> 完整数据请参阅 [TanStack Start 基准测试报告](https://intlayer.org/zh/doc/benchmark/tanstack) 与 [Next.js 基准测试报告](https://intlayer.org/zh/doc/benchmark/nextjs)。所有 bundle 均可在 [基准测试仓库](https://github.com/intlayer-org/benchmark-i18n) 中核查。
+
+实测结果呈现出两个明显特征：
+
+- 在 `static` 模式下，Intlayer 传输的内容体积与 Paraglide 基本持平（125.8 KB 对比 125.1 KB）。这符合预期：两者都包含了页面所需消息的所有语言版本。
+- 无论使用何种策略，Paraglide 的体积始终保持在 125.1 KB，因为它没有动态加载模式。上表中其每一行都等同于静态引入。
+
+## 无 Provider：看似美妙却代价不菲的方案
+
+Paraglide 不需要 Provider。你只需导入消息并直接调用：
+
+```tsx fileName="Hero.tsx"
+import { m } from "../paraglide/messages.js";
+
+export const Hero = () => (
+  <section>
+    <h1>{m.hero_title()}</h1>
+    <p>{m.hero_description()}</p>
+    <button>{m.hero_cta()}</button>
+  </section>
+);
+```
+
+没有 context，没有外层包裹组件，没有 hook。表面上看简单直观。但是语言依然必须由某个地方解析。每个生成的消息函数大致如下所示（简化代码）：
+
+```js fileName="paraglide/messages/_index.js"
+export const hero_title = (inputs = {}, options = {}) => {
+  const locale = options.locale ?? getLocale(); // 每次调用都要重新解析
+
+  if (locale === "en") return en.hero_title(inputs);
+  if (locale === "fr") return fr.hero_title(inputs);
+  // ...每个语言对应一个分支
+};
+```
+
+而 `getLocale()` 会遍历已配置的各种策略（cookie、本地存储、URL、基础语言）以获取当前语言。这意味着你渲染的每个文本节点（`<>{m.my_key()}</>`）都会各自执行一次语言解析流程，包括在浏览器中读取 `document.cookie`。一个包含 200 个翻译字符串的页面，在单次渲染中就会解析 200 次语言，并且在每次重新渲染时周而复始。
+
+基于 Provider 的库仅需读取**一次**语言，将其保存在 context（或 signal、store）中，所有节点直接读取已存在于内存中的值。Provider 的开销仅有几百字节。省去 Provider 会导致每次渲染都消耗 CPU 周期，这在基准测试中表现得尤为明显：在 TanStack Start 上，Paraglide 的页面加载时间与语言切换延迟均落后于 Intlayer（页面加载时间 22.1 ms 对比 14.6 ms，端到端响应度 4.3 ms 对比 3.2 ms）。
+
+## 开发者体验（DX）
+
+Paraglide 的事实来源是 JSON，但你从不直接导入这些 JSON 文件，而是导入生成的 `.js` 文件：
+
+<Tabs defaultTab="intlayer" group="techno">
+  <Tab label="Paraglide" value="paraglide">
+
+```json fileName="messages/en.json"
+{
+  "hero_title": "Ship your app in every language"
+}
+```
+
+```json fileName="messages/zh.json"
+{
+  "hero_title": "以所有语言发布你的应用程序"
+}
+```
+
+```tsx fileName="Hero.tsx"
+// 仅在编译器从 JSON 重新生成该文件后才存在
+import { m } from "../paraglide/messages.js";
+
+export const Hero = () => <h1>{m.hero_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({
+      zh: "以所有语言发布你的应用程序",
+      en: "Ship your app in every language",
+    }),
+  },
+} satisfies Dictionary;
+```
+
+```tsx fileName="Hero.tsx"
+import { useIntlayer } from "react-intlayer";
+
+export const Hero = () => {
+  const { title } = useIntlayer("hero");
+
+  return <h1>{title}</h1>;
+};
+```
+
+  </Tab>
+</Tabs>
+
+这种开发循环需要付出相应代价：
+
+- 每次修改 JSON 文件，都必须等待重新生成完成，导入才能被识别或类型才能得到更新。
+- 生成的 `paraglide/` 目录要么提交至 Git（这意味着每次涉及文案修改的 PR 都会在生成文件上产生合并冲突），要么将其忽略（这意味着在每次类型检查、测试和 CI 任务之前都必须额外执行一次生成步骤）。
+- 每个字符串都被包裹成函数调用。常量在各处变成了 `m.key()`，即便在原本只需静态值的地方也是如此。
+
+## Tree Shaking：请核查你的实际 Bundle
+
+Paraglide 最主要的主打特性是：由于每个消息都是独立的 export，未使用的消息能被 Tree Shaking 剔除。在 Svelte + Vite 的基准测试中，它确实如宣传的那样生效了。
+
+但在其它技术栈中并非如此。在我们针对 [Next.js](https://intlayer.org/zh/doc/benchmark/nextjs) 的测试中，Paraglide 的页面体积比基础应用多出 14 KB，而 `next-intlayer` 仅增加了 0.3 KB。在 TanStack Start 上的早期测试也表明，来自其他页面的消息同样混入了当前路由的 bundle 中。
+
+Tree Shaking 效果取决于你的打包工具（Turbopack、Rolldown、Rollup）、消息导入语法（`import { m }` 与 `import * as m`）以及副作用分析能力。如果你因体积小巧而选择 Paraglide，请务必打开 bundle 可视化工具并在自己的项目中实际验证。
+
+## 无动态加载机制
+
+这是架构上的硬伤。Paraglide 无法做到一次只加载一种语言：每个消息函数都会静态导入每种语言的实现代码，因此所有语言都会全部打包到你的客户端 bundle 中。
+
+在支持 2 种语言时，有一半的翻译数据传输被浪费了，这与前文测得的 ~50% 语言泄露率完全吻合。当支持 10 种语言时，浪费率高达 90%；当支持 30 种语言时，浪费率高达 97%。
+
+即使改成动态加载也无法根治：由于每个消息是一个独立函数，如果按函数进行懒加载，将会导致成千上万次碎小的网络请求。
+
+Intlayer 允许你全局或按字典自由配置加载模式：
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  dictionary: {
+    importMode: "dynamic", // 'static' | 'dynamic' | 'fetch'
+  },
+};
+
+export default config;
+```
+
+| `importMode` | 传输至客户端的内容                          | 对比 Paraglide              |
+| ------------ | ------------------------------------------- | --------------------------- |
+| `static`     | 页面所用字典的所有语言版本                  | 理论体积完全一致            |
+| `dynamic`    | 仅加载当前语言，按字典进行按需懒加载        | N 个语言时体积**轻量 N 倍** |
+| `fetch`      | 仅加载当前语言，直接通过 Live Sync API 获取 | N 个语言时体积**轻量 N 倍** |
+
+借助 [构建期转换优化](https://intlayer.org/zh/doc/concept/bundle-optimization) 与 `importMode: 'static'`，Intlayer 在理论上加载的内容与 Paraglide 毫无二致。而启用 `'dynamic'` 或 `'fetch'` 后，它仅加载当前语言所需的内容：对于支持 N 种语言的应用，翻译数据的网络传输量将比 Paraglide 小 N 倍。
+
+## Paraglide 依然适用的场景
+
+<AccordionGroup>
+<Accordion header="语种较少的 Svelte + Vite 项目">
+
+如果你的技术栈是 Svelte 搭配 Vite，且仅需支持两到三种语言，Tree Shaking 可以按预期工作，多语言带来的体积开销也相对可控。
+
+</Accordion>
+<Accordion header="现有基于 inlang 的工作流">
+
+如果你的团队已经深度依赖 inlang 生态（Fink、Sherlock、消息格式插件），Paraglide 能够与其实现原生无缝集成。
+
+</Accordion>
+</AccordionGroup>
+
+## 在你的应用中实际测验
+
+使用免费的 [i18n SEO Scanner](https://intlayer.org/i18n-seo-scanner) 检测线上生产应用的传输体积与语言泄露情况：
+
+<ClickToOpenIframe src="https://intlayer.org/i18n-seo-scanner" width="100%" height="600px" style="border:none;"/>
+
+安装并初始化 Intlayer：
+
+```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
+```
+
+## 拓展阅读
+
+- [TanStack Start i18n 基准测试](https://intlayer.org/zh/doc/benchmark/tanstack)
+- [Next.js i18n 基准测试](https://intlayer.org/zh/doc/benchmark/nextjs)
+- [Bundle 优化与 `importMode`](https://intlayer.org/zh/doc/concept/bundle-optimization)
+- [如何挑选合适的 React i18n 库](https://intlayer.org/zh/blog/how-to-pick-react-i18n-library)
+- [编译器驱动与声明式国际化的优劣权衡](https://intlayer.org/zh/blog/compiler-vs-declarative-i18n)