@intlayer/docs 9.5.6 → 9.5.7

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)
 
 ## 总结
 

package/blog/zh/next-intl_vs_intlayer.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-09-13
-updatedAt: 2026-09-13
+updatedAt: 2026-09-22
 title: "next-intl vs Intlayer: 2026 基准测试与对比"
 description: Bundle 大小、内容泄漏、locale 切换响应性和开发者体验在 Next.js 和 TanStack Start 上的测量。你应该在 2026 年选择哪个 i18n 库？
 keywords:
@@ -24,6 +24,8 @@ author: aymericzip
 
 # next-intl VS Intlayer | Next.js 国际化 (i18n) 基准测试
 
+![next-intl VS Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/assets/i18next-next-intl-intlayer.webp?raw=true)
+
 `next-intl` 是 Next.js 最流行的 i18n 库。Intlayer 是一个基于编译器、组件作用域的替代方案。两者都可以本地化 App Router 应用程序。问题是应用程序构建后每个库的成本是多少。
 
 本文不是教程。这是一个由 [Benchmark Bloom](https://github.com/intlayer-org/benchmark-bloom) 的数据支持的比较，Benchmark Bloom 是一个开源基准测试套件，它使用每个库构建相同的应用程序，并测量浏览器实际下载和执行的内容。
@@ -96,6 +98,10 @@ Intlayer 没有"scoped"变体：编译器会自动按**组件**对内容进行
 
 ### Next.js (App Router)上的结果
 
+选择您关注的指标和库：
+
+<I18nBenchmark framework="nextjs" vertical/>
+
 | Library                        | Strategy       | Lib size (gz) | Page JS avg (gz) | Locale leak | Page leak | Component avg (gz) | E2E reactivity | Hydration |
 | ------------------------------ | -------------- | ------------: | ---------------: | ----------: | --------: | -----------------: | -------------: | --------: |
 | **base** (no i18n)             | -              |        0.0 KB |         141.0 KB |        0.0% |      0.0% |             0.9 KB |        13.4 ms |   11.8 ms |
@@ -116,6 +122,15 @@ Intlayer 没有"scoped"变体：编译器会自动按**组件**对内容进行
 - **组件大小。** 调用 `useTranslations()` 的组件编译到平均 21.8 KB；使用 `useIntlayer()` 的相同组件编译到 6.9 KB。在 `scoped-static` 设置中，`next-intl` 组件跳升到 80.1 KB，因为每个组件都内联其命名空间 catalog。
 - **Reactivity 和 hydration** 在 Next.js 上对两个库都处于相同的范围（15-18 ms）。这里都不是瓶颈。
 
+<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` 的框架无关核心。相同的 API，相同的消息格式。在 TanStack Start 上将其与 `intlayer` 进行比较，移除了方程的 Next.js 特定部分。
@@ -139,8 +154,19 @@ Intlayer 没有"scoped"变体：编译器会自动按**组件**对内容进行
 - **组件大小是架构的亮点**：使用 `use-intl` 每个组件 76-87 KB，而使用 Intlayer 仅 6-8 KB。`useTranslations()` 将每个组件绑定到全局消息树；`useIntlayer()` 将其绑定到自己的字典。
 - **区域设置切换**使用 Intlayer 快 2-4 倍（3 毫秒 vs 7-21 毫秒）。
 
+<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)
+
 `next-intl` 遵循经典模型：每个区域设置一个 JSON，在 `getRequestConfig` 中加载，推送到 `NextIntlClientProvider`，通过 `t("namespace.key")` 读取。
 
 ```bash
@@ -162,6 +188,10 @@ Intlayer 没有"scoped"变体：编译器会自动按**组件**对内容进行
 
 运行时无法知道页面将使用哪些 key，因此安全的默认做法是发送整个 catalog。优化意味着**你**需要将 catalog 拆分成 namespace，**你**需要决定每个页面需要哪些 namespace，并且**你**需要在组件移动时保持该映射同步。基准测试中的 `scoped-dynamic` 行是该工作的回报，但大多数团队从未实现过。
 
+未能实现这一目标的成本在两个维度上同时增长：页面和语言环境：
+
+![Theoretical content leakage by architecture](https://github.com/aymericzip/intlayer/blob/main/docs/assets/theorical_content_leakage.webp?raw=true)
+
 Intlayer 翻转了这个责任。内容在组件旁边声明：
 
 ```bash
@@ -189,7 +219,8 @@ Intlayer 翻转了这个责任。内容在组件旁边声明：
 
 ### Client 组件
 
-**next-intl**
+<Tabs defaultTab="intlayer" group="techno">
+<Tab label="next-intl" value="next-intl">
 
 ```json fileName="messages/en.json"
 {
@@ -226,7 +257,8 @@ export const Counter = () => {
 
 > 记住在渲染此组件的每个页面上，将 `counter` 命名空间包含在传递给 `NextIntlClientProvider` 的消息中。
 
-**Intlayer**
+</Tab>
+<Tab label="Intlayer" value="intlayer">
 
 ```ts fileName="src/components/Counter/index.content.ts"
 import { t, type Dictionary } from "intlayer";
@@ -269,11 +301,14 @@ export const Counter = () => {
 
 无需在页面上注册任何内容：该组件包含其自己的内容。
 
+</Tab>
+</Tabs>
 ### 同步服务器组件
 
 设计系统组件（导航栏、页脚、卡片）通常是作为客户端组件的子组件渲染的服务器组件，因此它们不能是 `async`。
 
-**next-intl**
+<Tabs defaultTab="intlayer" group="techno">
+<Tab label="next-intl" value="next-intl">
 
 ```tsx fileName="src/components/ServerCounter.tsx"
 type ServerCounterProps = {
@@ -291,7 +326,8 @@ export const ServerCounter = ({ t, formattedCount }: ServerCounterProps) => (
 
 页面必须 `await getTranslations("counter")` 和 `await getFormatter()`，然后将结果作为 props 向下传递。该组件不再是自包含的。
 
-**Intlayer**
+</Tab>
+<Tab label="Intlayer" value="intlayer">
 
 ```tsx fileName="src/components/ServerCounter.tsx"
 import { useIntlayer } from "next-intlayer/server";
@@ -310,9 +346,12 @@ export const ServerCounter = ({ count }: { count: number }) => {
 };
 ```
 
+</Tab>
+</Tabs>
 ### 元数据
 
-**next-intl**
+<Tabs defaultTab="intlayer" group="techno">
+<Tab label="next-intl" value="next-intl">
 
 ```tsx fileName="src/app/[locale]/about/page.tsx"
 import type { Metadata } from "next";
@@ -347,7 +386,8 @@ export const generateMetadata = async ({
 };
 ```
 
-**Intlayer**
+</Tab>
+<Tab label="Intlayer" value="intlayer">
 
 ```tsx fileName="src/app/[locale]/about/page.tsx"
 import { getIntlayer, getMultilingualUrls } from "intlayer";
@@ -371,6 +411,9 @@ export const generateMetadata = async ({
 };
 ```
 
+</Tab>
+</Tabs>
+
 ## 保持 next-intl API，获得 Intlayer 的输出
 
 您不必重写组件来获得上述基准数字。`@intlayer/next-intl` 是一个开箱即用的适配器：它保持 `useTranslations`、`getTranslations`、`useFormatter`、`t.rich()`、ICU 复数形式和 `next-intl/navigation` 助手，并从 Intlayer 编译器编译的 Intlayer 字典中提供它们。
@@ -393,17 +436,84 @@ export default withIntlayer(nextConfig);
 
 ## 何时选择哪个？
 
-- **选择 next-intl** 如果你想要 Next.js 生态标准、依赖 ICU MessageFormat、应用规模小到中等，或者你集成了翻译平台（Crowdin、Phrase、Lokalise...）期望集中式 JSON。如果性能重要，需要预留时间来命名空间目录和按页面挑选消息。
-- **选择 Intlayer** 如果你想要**组件作用域内容**、**严格的 TypeScript**、**构建时缺失键错误检测**、**零成本的 tree-shaking 和懒加载**、同步服务器组件，以及内置编辑工具（Visual Editor、CMS、AI 翻译、MCP server）。特别适合大型、模块化的 codebase 和设计系统。
-- **选择 `@intlayer/next-intl`** 如果你已经在使用 `next-intl`，想要获得 bundle 优化而无需重写。
+<AccordionGroup>
+<Accordion header="选择 next-intl">
+
+您需要 Next.js 的生态标准，依赖 ICU MessageFormat，您的应用规模较小或中等，或者您与需要集中式 JSON 的翻译平台（Crowdin、Phrase、Lokalise...）集成。如果注重性能，请预留时间按命名空间划分目录并在每个页面使用 `pick()` 选择消息。
+
+</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/next-intl">
+
+您已经在项目中使用了 `next-intl`，希望在无需重写的情况下获得包体积缩减优势。[兼容适配器](https://intlayer.org/zh/doc/compatibility/next-intl)保留了您的导入和 `messages/{locale}.json` 文件作为单一真实来源。在 [next-intl 对比 @intlayer/next-intl](https://intlayer.org/zh/blog/next-intl-vs-intlayer-next-intl) 中进行了同台实测。
+
+</Accordion>
+</AccordionGroup>
+
+## 常见问题
+
+<FAQ>
+
+<Question title="next-intl 比 Intlayer 慢吗？">
+
+在渲染阶段不是。两者的差异在于传输内容：`next-intl` 在每个页面上增加 **+12.6 KB gzip** 的运行时开销，并且在常见的配置下，每个页面都会携带 ~90% 的无关页面文本。在 Next.js 上语言切换与注水（hydration）耗时相近（15-18 毫秒）；在 TanStack Start 上，`use-intl` 耗时 7-21 毫秒，而 Intlayer 仅需 3-4 毫秒。
+
+</Question>
+
+<Question title="使用 next-intl 可以实现 0% 泄漏吗？">
+
+可以，通过 `scoped-dynamic` 配置：将 `messages/{locale}.json` 按路由拆分为单个命名空间，然后在每个页面中使用 `pick(messages, [...])` 并在组件调整时持续维护该映射关系。基准测试中的 `scoped-*` 行正代表这项工作。而 Intlayer 天然就能达到 0%，因为编译器会在组件层级对内容进行作用域划分。请参阅[包体积优化](https://intlayer.org/zh/doc/concept/bundle-optimization)。
+
+</Question>
+
+<Question title="迁移时需要重写组件吗？">
+
+不需要。`@intlayer/next-intl` 保留了 `useTranslations`、`getTranslations`、`useFormatter`、`t.rich()`、ICU 复数语法和导航助手，并通过编译后的字典进行提供。只需在 `next.config.ts` 中添加一行插件配置。详情请参阅 [next-intl 迁移指南](https://intlayer.org/zh/doc/migration/next-intl)。
+
+</Question>
+
+<Question title="Intlayer 支持 ICU MessageFormat 吗？">
+
+原生 API 正在积极完善 ICU 支持。兼容适配器（`@intlayer/next-intl`、`@intlayer/use-intl`）均能完美执行 ICU：复数、`select`、`selectordinal`、`#` 和 `{ts, date, long}` 都会经过 Intlayer 的 ICU 解析器处理。详情请参阅 [ICU 消息格式解析](https://intlayer.org/zh/blog/icu-message-format)。
+
+</Question>
+
+<Question title="我可以保留 messages/{locale}.json 文件吗？">
+
+可以。[JSON 同步插件](https://intlayer.org/zh/doc/compatibility/next-intl)会读取这些文件，将其顶层键拆分为字典，并在 CLI 或 CMS 更新时将翻译写回同一文件。译者的工作流程完全保持不变。
+
+</Question>
+
+</FAQ>
 
 ## 相关比较
 
-- [i18next vs Intlayer](https://intlayer.org/blog/i18next-vs-intlayer) (同一基准测试)
-- [Lingui vs Intlayer](https://intlayer.org/blog/lingui-vs-intlayer) (同一基准测试)
-- [vue-i18n vs Intlayer benchmark](https://intlayer.org/blog/vue-i18n-vs-intlayer-benchmark) (同一基准测试)
-- [next-i18next vs next-intl vs Intlayer](https://intlayer.org/blog/next-i18next-vs-next-intl-vs-intlayer)
-- [Is next-intl outdated?](https://intlayer.org/blog/is-next-intl-outdated)
+同一基准测试，其他库：
+
+- [i18next vs Intlayer](https://intlayer.org/zh/blog/i18next-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)
+
+深入了解 next-intl：
+
+- [next-intl vs @intlayer/next-intl](https://intlayer.org/zh/blog/next-intl-vs-intlayer-next-intl), 在同一应用上实测的适配器
+- [Is next-intl outdated?](https://intlayer.org/zh/blog/is-next-intl-outdated)
+- [Using Intlayer with next-intl](https://intlayer.org/zh/blog/intlayer-with-next-intl)
+- [How to internationalize a Next.js app with next-intl](https://intlayer.org/zh/blog/nextjs-internationalization-using-next-intl)
+
+参考文档：
+
+- [Next.js 基准测试报告](https://intlayer.org/zh/doc/benchmark/nextjs) 与 [TanStack Start 基准测试报告](https://intlayer.org/zh/doc/benchmark/tanstack)
+- [兼容适配器：next-intl](https://intlayer.org/zh/doc/compatibility/next-intl) 与 [迁移指南](https://intlayer.org/zh/doc/migration/next-intl)
+- [包体积优化](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/vue-i18n_vs_intlayer-vue-i18n.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-09-13
-updatedAt: 2026-09-13
+updatedAt: 2026-09-22
 title: "vue-i18n vs @intlayer/vue-i18n：相同的 API，不同的 Bundle"
 description: 当 Vue 3 应用保持其 vue-i18n 调用但通过 @intlayer/vue-i18n compat 适配器提供服务时会发生什么变化。在相同的 Vite + Vue 代码上测量的每页 JavaScript、运行时大小、组件大小和泄漏，以及适配器保留、忽略和无法替换的内容。
 keywords:
@@ -25,6 +25,8 @@ author: aymericzip
 
 # vue-i18n VS @intlayer/vue-i18n | 相同的 API，不同的 Bundle
 
+![Vue i18n library ecosystem](https://github.com/aymericzip/intlayer/blob/main/docs/assets/cloud_i18n_logo.webp?raw=true)
+
 `@intlayer/vue-i18n` 是一个兼容适配器：它公开了 `vue-i18n` API（`createI18n`、`useI18n`、`t()`、`d()`、`n()`、`$t`、`v-t`、`i18n.global.locale`...），并从 Intlayer 编译的字典中提供服务。你的 `.vue` 文件不会改变。改变的是 `t("footer.github")` 绑定的内容。
 
 本文在同一个 Vite + Vue 3 应用上测量了这个替换，该应用分别使用 `vue-i18n` 和适配器构建。数据来自 [Benchmark Bloom](https://github.com/intlayer-org/benchmark-bloom)。如需了解 `vue-i18n` 和 Intlayer 作为库的对比，请阅读 [vue-i18n vs Intlayer](https://intlayer.org/blog/vue-i18n-vs-intlayer) 和 [vue-i18n vs Intlayer 基准测试](https://intlayer.org/blog/vue-i18n-vs-intlayer-benchmark)。本文讨论的是当你保持组件不变时，适配器会带来什么改变。
@@ -105,6 +107,10 @@ const { t } = useI18n(_dicHash_footer);
 
 ### Vite + Vue 3 的结果
 
+选择您关注的指标和库：
+
+<I18nBenchmark framework="vite-vue" vertical/>
+
 | Setup                    | Strategy | Lib size (gz) | Lib size (min) | Page JS avg (gz) | Locale leak | Page leak | Component avg (gz) | E2E reactivity |  Page load |
 | ------------------------ | -------- | ------------: | -------------: | ---------------: | ----------: | --------: | -----------------: | -------------: | ---------: |
 | **base** (no i18n)       | -        |        0.0 KB |         0.0 KB |          41.3 KB |        0.0% |         - |             1.1 KB |         1.8 ms |    10.8 ms |
@@ -124,11 +130,24 @@ const { t } = useI18n(_dicHash_footer);
 - **响应性和页面加载。** 对于两者而言，语言环境切换成本低廉（1.5-2.8 ms）；一旦消息在内存中，Vue 的响应性系统会实现这一点。页面加载从 13.6 ms 降低到 **9.3 ms**，与减少 88 KB 的 JavaScript 解析量一致。
 - **关于原生行。** `vue-intlayer` 在此运行中在 `static` 模式下捆绑了每个区域设置，达到 57.1 KB，运行时为 3.9 KB；适配器的同步字典携带更少的外国语言环境字符串，因此每页数据更低。原生运行时仍然是三者中最轻的，其 `.content.ts` 模型是 SFC `<i18n>` 块找到其等效项的地方。
 
+<ClickToOpenIframe
+src="https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-vite_vue.md"
+width="100%"
+height="600px"
+style="border:none;"
+/>
+
+> 完整表格、各个库及每种策略，请参阅 [Vue 基准测试报告](https://intlayer.org/zh/doc/benchmark/vue)。
+
 ## 为什么数字会变化
 
+![The Intlayer compiler extracts content from components](https://github.com/aymericzip/intlayer/blob/main/docs/assets/compiler.webp?raw=true)
+
 `src/components/` 中的内容没有改变，所以收益来自 `useI18n` 绑定到的内容。
 
-**使用 `vue-i18n`** 时，绑定是全局实例。`createI18n({ messages: { en, fr, ... } })` 是一个导入，包含所有内容；每个调用 `useI18n()` 的组件都可以访问所有内容，因此 bundler 无法在实例以下进行分割。优化意味着 _你_ 需要按路由拆分 `en.json`，在路由守卫中调用 `setLocaleMessage()`，并在组件移动时保持路由到文件的映射正确。
+**使用 `vue-i18n`** 时，绑定是全局实例。`createI18n({ messages: { en, fr, ... } })` 是一个导入，包含所有内容；每个调用 `useI18n()` 的组件都可以访问所有内容，因此 bundler 无法在实例以下进行分割。优化意味着 _你_ 需要按路由拆分 `en.json`，在路由守卫中调用 `setLocaleMessage()`，并在组件移动时保持路由到文件的映射正确。 浪费在页面和语言两个维度上同时增长：
+
+![Theoretical content leakage by architecture](https://github.com/aymericzip/intlayer/blob/main/docs/assets/theorical_content_leakage.webp?raw=true)
 
 ```bash
 .
@@ -258,26 +277,107 @@ export const i18n = createI18n({ locale: "en" });
 
 ## 开始前需要了解的限制
 
-- **SFC `<i18n>` 块不被读取。** 如果你的消息存在于组件内部，它们需要移动到 locale 文件（或 `.content.ts`，这是相同的想法但带有类型）。
-- **运行时消息加载已消除。** `setLocaleMessage()` 和 `mergeLocaleMessage()` 会发出警告并返回。从 CMS 在运行时获取的翻译需要 Intlayer 的 CMS，或者使用 `intlayer pull` / `push` 命令。
-- **`messages` 是一个回退方案，不是免费的。** 在 `createI18n()` 中保留 JSON 导入会在 bundle 中保留 75 KB。一旦 `intlayer test` 通过，就删除它们。
-- **该适配器不是原生运行时。** 7.9 KB 对比 `vue-intlayer` 的 3.9 KB。一旦每个组件都迁移到 `useIntlayer`，就可以删除它。
+<AccordionGroup>
+<Accordion header="不读取 SFC <i18n> 块">
+
+如果您的消息位于组件内部，则需要将它们移动到语言文件或 `.content.ts` 中，这具有相同的理念并提供类型支持。
+
+</Accordion>
+<Accordion header="移除了运行时消息加载">
+
+`setLocaleMessage()` 和 `mergeLocaleMessage()` 会发出警告并直接返回。在运行时从 CMS 获取的翻译需要使用 [Intlayer CMS](https://intlayer.org/zh/doc/concept/cms) 或 `intlayer pull` / `push` 命令。
+
+</Accordion>
+<Accordion header="messages 是回退方案，并非零成本">
+
+在 `createI18n()` 中保留 JSON 导入会在包中保留 75 KB。一旦 `intlayer test` 通过，即可将其删除。
+
+</Accordion>
+<Accordion header="适配器不是原生运行时">
+
+`vue-intlayer` 仅 3.9 KB，而适配器为 7.9 KB。一旦所有组件都迁移到 `useIntlayer`，即可将其移除。
+
+</Accordion>
+</AccordionGroup>
 
 ## 何时使用哪个？
 
-- **继续使用 `vue-i18n`** 如果你的应用依赖 SFC `<i18n>` 块、运行时 `setLocaleMessage()` 流程，或者 90 KB 每页对你的用户来说不是问题。
-- **使用 `@intlayer/vue-i18n`** 如果你在用 `vue-i18n` 并想要节省 88 KB、缩小 23 倍的组件、0% 页面泄漏、类型化的键和 CI 检查，而无需编辑 `.vue` 文件。这是现有 `vue-i18n` codebase 的入口点。
-- **使用原生方案（`vue-intlayer`）** 用于新项目，或在适配器完成其工作后。它具有最轻的运行时（3.9 KB）和按组件的 `.content.ts` 模型，用类型化内容替代 `<i18n>` 块。
+<AccordionGroup>
+<Accordion header="继续使用 vue-i18n">
+
+您的应用依赖于 SFC `<i18n>` 块、运行时 `setLocaleMessage()` 流程，或者每页 90 KB 对您的用户群而言并不是问题。
+
+</Accordion>
+<Accordion header="使用 @intlayer/vue-i18n">
+
+您正在使用 `vue-i18n`，希望在不修改任何 `.vue` 文件的前提下节省 88 KB、实现组件体积缩小 23 倍、0% 页面泄漏、类型化键和 CI 检查。这是现有 `vue-i18n` 代码库的最佳切入点。
+
+</Accordion>
+<Accordion header="转向原生 (vue-intlayer)">
+
+适用于新项目，或在适配器完成过渡任务之后。它具有最轻量的运行时（3.9 KB）以及按组件划分的 `.content.ts` 模式，用类型化内容取代 `<i18n>` 块。请从 [Intlayer 与 Vue](https://intlayer.org/zh/doc/environment/vite-and-vue) 或 [与 Nuxt](https://intlayer.org/zh/doc/environment/nuxt-and-vue) 开始。
+
+</Accordion>
+</AccordionGroup>
+
+## 常见问题解答
+
+<FAQ>
+
+<Question title="我需要修改我的 .vue 文件吗？">
+
+不需要。基准测试构建仅修改了 `vite.config.ts`、`intlayer.config.ts` 以及 `src/i18n.ts` 中引入 `messages` 的一行代码。所有 `useI18n()`、`$t`、`v-t` 和 Options API 的调用位置均保持原样。
+
+</Question>
+
+<Question title="为什么组件体积缩小了 23 倍？">
+
+因为 `useI18n()` 不再访问全局实例。`createI18n({ messages })` 会持有所有语言的全部消息，因此单独编译的组件会拖入 196 KB。使用适配器后，它仅访问自己的字典：8.4 KB。
+
+</Question>
+
+<Question title="d() 和 n() 格式化功能如何处理？">
+
+完全保留。传递给 `createI18n()` 的 `datetimeFormats` 和 `numberFormats` 依然有效，由原生 `Intl` 提供支持。请参阅[日期、时间和数字格式化](https://intlayer.org/zh/blog/date-time-number-formatting-locales)。
+
+</Question>
+
+<Question title="它是否适用于 Nuxt？">
+
+`@intlayer/vue-i18n` 针对 Vite + Vue。对于 `@nuxtjs/i18n`，请使用 [Nuxt i18n 兼容适配器](https://intlayer.org/zh/doc/compatibility/nuxtjs-i18n)，原生设置请参阅 [Intlayer 与 Nuxt](https://intlayer.org/zh/doc/environment/nuxt-and-vue)。
+
+</Question>
+
+<Question title="我可以按组件逐个迁移吗？">
+
+可以。任何组件都可以通过同级放置的内容文件从 `useI18n()` 切换到 `useIntlayer("footer")`。JSON 和 `.content.ts` 字典可以并存并合并。
+
+</Question>
+
+</FAQ>
 
 ## 相关比较
 
-- [vue-i18n vs Intlayer](https://intlayer.org/blog/vue-i18n-vs-intlayer) (功能和开发体验)
-- [vue-i18n vs Intlayer benchmark](https://intlayer.org/blog/vue-i18n-vs-intlayer-benchmark) (库，相同基准)
-- [next-intl vs @intlayer/next-intl](https://intlayer.org/blog/next-intl-vs-intlayer-next-intl) (相同adapter系列)
-- [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) (相同adapter系列)
-- [迁移指南：vue-i18n 到 Intlayer](https://intlayer.org/doc/migration/vue-i18n)
-- [兼容适配器参考：vue-i18n](https://intlayer.org/doc/compatibility/vue-i18n), [Nuxt i18n](https://intlayer.org/doc/compatibility/nuxtjs-i18n)
+同系列适配器：
+
+- [next-intl vs @intlayer/next-intl](https://intlayer.org/zh/blog/next-intl-vs-intlayer-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](https://intlayer.org/zh/blog/vue-i18n-vs-intlayer), features and DX
+- [vue-i18n vs Intlayer benchmark](https://intlayer.org/zh/blog/vue-i18n-vs-intlayer-benchmark)
+- [Is vue-i18n outdated?](https://intlayer.org/zh/blog/is-vue-i18n-outdated)
+- [How to pick a Vue i18n library](https://intlayer.org/zh/blog/how-to-pick-vue-i18n-library)
+
+参考文档：
+
+- [Compat adapter: vue-i18n](https://intlayer.org/zh/doc/compatibility/vue-i18n) and [Nuxt i18n](https://intlayer.org/zh/doc/compatibility/nuxtjs-i18n)
+- [迁移指南：从 vue-i18n 到 Intlayer](https://intlayer.org/zh/doc/migration/vue-i18n)
+- [Vue 基准测试报告](https://intlayer.org/zh/doc/benchmark/vue)
+- [包体积优化](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)
 
 ## 总结
 
@@ -285,4 +385,4 @@ export const i18n = createI18n({ locale: "en" });
 
 所有原始数据、测试应用程序和脚本都在 [Benchmark Bloom 仓库](https://github.com/intlayer-org/benchmark-bloom) 中。自己运行它。
 
-有关更多详细信息，请参考 ['Why Intlayer?' 文档](https://intlayer.org/doc/why)。
+有关更多详细信息，请参考 ['Why Intlayer?' 文档](https://intlayer.org/zh/doc/why)。