next-intl VS Intlayer | Next.js 国际化 (i18n) 基准测试

next-intl 是 Next.js 最流行的 i18n 库。Intlayer 是一个基于编译器、组件作用域的替代方案。两者都可以本地化 App Router 应用程序。问题是应用程序构建后每个库的成本是多少。

本文不是教程。这是一个由 Benchmark Bloom 的数据支持的比较，Benchmark Bloom 是一个开源基准测试套件，它使用每个库构建相同的应用程序，并测量浏览器实际下载和执行的内容。

tl;dr: 在相同的 Next.js 应用上，next-intl 在每个页面上增加 +12.6 KB gzip 的 JavaScript，而 Intlayer 仅增加 +0.3 KB。无需额外工作，next-intl 在每个页面上附带 ~90% 的外语页面字符串。要通过 next-intl 达到 0% 泄漏，需要命名空间作用域和按页面的 pick(messages, [...])。Intlayer 默认达到 0%，因为其编译器按组件作用内容。如果你想要 Intlayer 输出的 next-intl API，@intlayer/next-intl 适配器测得每个页面 147.5 KB 对比原始的 153.6 KB。

简而言之

• next-intl - 轻量级、文档齐全、支持 ICU 消息格式、App Router 第一类支持（含 middleware）、formatters 和 navigation 助手。内容存储在集中式 JSON catalogs 中；性能优化（namespaces、per-page message picking、lazy loading）需要你自己实现。
• Intlayer - 以组件为中心的内容模型。.content.ts 字典与服务的组件并置，build-time compiler 对每个组件和每个 locale 进行 tree-shake 和 lazy-load，从你的内容生成严格的 TypeScript 类型，缺失的翻译在 build 时会失败。提供 middleware、SEO 助手、Visual Editor / CMS 和 AI 辅助翻译。

显示表格的所有内容

显示表格的所有内容

在弹窗中打开表格以清晰地查看所有数据

库	GitHub Stars	总提交数	最后提交	首个版本	NPM 版本	NPM 下载量
aymericzip/intlayer				2024年4月
amannn/next-intl				2020年11月

徽章自动更新。快照会随时间变化。

并排功能比较

基准测试

测量的内容

Benchmark Bloom 套件使用每个库构建相同的应用程序：10 个页面（首页、关于、博客、职业、联系、常见问题、定价、产品、设置、团队），10 个语言环境（en、fr、es、de、it、pt、zh、ja、ko、ru），相同的组件和相同的内容。页面在 en 和 fr 中进行测量。每个库实现了多达四种加载策略，从最初的设置到最优的设置：

Intlayer 没有"scoped"变体：编译器会自动按组件对内容进行作用域划分，因此其 static 和 dynamic 行已经是作用域的。

对于每次构建，该套件记录：

• Lib size: 仅导入 i18n 库的空组件的 gzip 大小。运行时的固定成本。
• Page JS: 每个页面下载的 gzip JavaScript，在所有页面和语言环境中平均计算。
• Locale leak %: 下载的 JS 中找到的已翻译字符串中属于用户未查看的语言环境的份额（在 en 和 fr 上进行指纹识别，因此 50% 表示"另一个测量的语言环境完全存在"；使用 10 个捆绑的语言环境时，实际浪费更高）。
• Page leak %: 下载的 JS 中找到的已翻译字符串中属于用户未浏览的页面的份额。
• Component avg: 各个编译的每个组件的平均 gzip 大小。显示单个组件拖入多少 i18n 运行时。
• E2E reactivity: 选择新locale和html[lang]在DOM中更新之间的实时时间（Playwright，5次迭代）。
• Hydration: React hydration阶段持续时间。

下面的数字来自2026-09-12运行，使用next-intl 4.14.2、use-intl 4.14.2和intlayer 9.5.1。测试应用程序故意很小（每个locale只有几十个字符串），所以泄漏百分比描述的是一个模式：随着您的内容增长而增长，但运行时成本保持固定。

Next.js (App Router)上的结果

选择您关注的指标和库：

如何阅读

• 运行时成本。 基础应用程序每页重 141.0 KB。next-intl 将其增加到 153.6 KB（每页额外 +12.6 KB gzip），Intlayer 增加到 141.3 KB（额外 +0.3 KB）。这个差异不取决于你有多少个字符串：它是库运行时的成本。
• Leakage. 在两个最多团队实际使用的设置中（static 和 dynamic），next-intl 会在每个页面上传送 ~90% 的外语页面字符串：整个 en.json 都会进入客户端 provider。要达到 0% 需要使用 scoped-* 设置：将目录分割成命名空间，然后在每个页面中 pick() 正确的。Intlayer 在两行中都是 0%，无需任何额外配置。
• 每页面 JS 大小在不同策略间对 next-intl 没有变化。 测试内容很小，所以 ~90% 的泄漏这里只有几 KB。在一个有数百个字符串每页面的真实应用中，这个比例会成为主导成本。同时 +12.6 KB 的 runtime 在每个配置中都会被支付。
• 组件大小。 调用 useTranslations() 的组件编译到平均 21.8 KB；使用 useIntlayer() 的相同组件编译到 6.9 KB。在 scoped-static 设置中，next-intl 组件跳升到 80.1 KB，因为每个组件都内联其命名空间 catalog。
• Reactivity 和 hydration 在 Next.js 上对两个库都处于相同的范围（15-18 ms）。这里都不是瓶颈。

完整表格、每个库和每种策略，请参阅 Next.js 基准测试报告。

TanStack Start 上的结果（use-intl）

use-intl 是 next-intl 的框架无关核心。相同的 API，相同的消息格式。在 TanStack Start 上将其与 intlayer 进行比较，移除了方程的 Next.js 特定部分。

如何阅读

• 朴素的 use-intl 设置比基础应用多装载了 68.8 KB 的 JS，其中一半的字符串属于错误的语言环境，90% 属于错误的页面。
• use-intl 在 dynamic 模式下达到 119.4 KB，接近 Intlayer 的 118.6 KB，但仍然存在 89.8% 页面泄漏：活跃 locale 的所有页面字符串都在每个页面加载。按路由作用域划分（scoped-*）可以消除泄漏，但需要额外支付约 9 KB 的 chunk 开销。
• Intlayer 的 static 行已经实现 0% 页面泄漏：编译器仅打包页面上的组件使用的字典。启用 importMode: 'dynamic'（在 intlayer.config.ts 中只需一行）也消除了 locale 泄漏。
• 组件大小是架构的亮点：使用 use-intl 每个组件 76-87 KB，而使用 Intlayer 仅 6-8 KB。useTranslations() 将每个组件绑定到全局消息树；useIntlayer() 将其绑定到自己的字典。
• 区域设置切换使用 Intlayer 快 2-4 倍（3 毫秒 vs 7-21 毫秒）。

完整表格请参阅 TanStack Start 基准测试报告。

为什么存在差距？集中式目录 vs. 编译的字典

next-intl 遵循经典模型：每个区域设置一个 JSON，在 getRequestConfig 中加载，推送到 NextIntlClientProvider，通过 t("namespace.key") 读取。

.
├── messages
│   ├── en.json
│   └── fr.json
└── src
    ├── i18n
    │   ├── request.ts
    │   └── routing.ts
    ├── middleware.ts
    └── app
        └── [locale]
            ├── layout.tsx
            └── about
                └── page.tsx

运行时无法知道页面将使用哪些 key，因此安全的默认做法是发送整个 catalog。优化意味着你需要将 catalog 拆分成 namespace，你需要决定每个页面需要哪些 namespace，并且你需要在组件移动时保持该映射同步。基准测试中的 scoped-dynamic 行是该工作的回报，但大多数团队从未实现过。

未能实现这一目标的成本在两个维度上同时增长：页面和语言环境：

Intlayer 翻转了这个责任。内容在组件旁边声明：

.
├── intlayer.config.ts
└── src
    ├── middleware.ts
    ├── app
    │   └── [locale]
    │       ├── layout.tsx
    │       └── about
    │           ├── page.tsx
    │           └── page.content.ts
    └── components
        └── Counter
            ├── index.tsx
            └── index.content.ts

在构建时，编译器（@intlayer/swc / @intlayer/babel）会检查哪个组件导入了哪个字典。它只为活跃的语言环境捆绑那些字典，并删除未被导入的字典。"scoped-dynamic"模式成为构建的输出，而不是团队必须维护的纪律。

要获得 dynamic 行的数字，请在 intlayer.config.ts 中设置 dictionary.importMode: 'dynamic'。请参阅 bundle 优化文档。

开发者体验

Client 组件

{
  "counter": {
    "label": "Counter",
    "increment": "Increment"
  }
}

"use client";

import { useState } from "react";
import { useTranslations, useFormatter } from "next-intl";

export const Counter = () => {
  // 使用 useTranslations 获取 counter 命名空间的翻译
  const t = useTranslations("counter");
  // 使用 useFormatter 获取数字格式化工具
  const format = useFormatter();
  const [count, setCount] = useState(0);

  return (
    <div>
      <p>{format.number(count)}</p>
      <button aria-label={t("label")} onClick={() => setCount((c) => c + 1)}>
        {t("increment")}
      </button>
    </div>
  );
};

import { t, type Dictionary } from "intlayer";

const counterContent = {
  key: "counter",
  content: {
    label: t({ zh: "计数器", en: "Counter", fr: "Compteur" }),
    increment: t({ zh: "增加", en: "Increment", fr: "Incrémenter" }),
  },
} satisfies Dictionary;

export default counterContent;

"use client";

import { useState } from "react";
import { useIntlayer } from "next-intlayer";
import { useNumber } from "next-intlayer/format";

export const Counter = () => {
  // 获取国际化内容
  const { label, increment } = useIntlayer("counter");
  // 获取数字格式化工具
  const number = useNumber();
  const [count, setCount] = useState(0);

  return (
    <div>
      <p>{number(count)}</p>
      <button aria-label={label} onClick={() => setCount((c) => c + 1)}>
        {increment}
      </button>
    </div>
  );
};

同步服务器组件

设计系统组件（导航栏、页脚、卡片）通常是作为客户端组件的子组件渲染的服务器组件，因此它们不能是 async。

type ServerCounterProps = {
  t: (key: string) => string;
  formattedCount: string;
};

export const ServerCounter = ({ t, formattedCount }: ServerCounterProps) => (
  <div>
    <p>{formattedCount}</p>
    <button aria-label={t("label")}>{t("increment")}</button>
  </div>
);

import { useIntlayer } from "next-intlayer/server";
import { useNumber } from "next-intlayer/server/format";

export const ServerCounter = ({ count }: { count: number }) => {
  const { label, increment } = useIntlayer("counter");
  const number = useNumber();

  return (
    <div>
      <p>{number(count)}</p>
      <button aria-label={label}>{increment}</button>
    </div>
  );
};

元数据

import type { Metadata } from "next";
import { getTranslations } from "next-intl/server";
import { routing } from "@/i18n/routing";

// 本地化路径函数
const localizedPath = (locale: string, path: string) =>
  locale === routing.defaultLocale ? path : `/${locale}${path}`;

// 生成元数据
export const generateMetadata = async ({
  params,
}: {
  params: Promise<{ locale: string }>;
}): Promise<Metadata> => {
  const { locale } = await params;
  const t = await getTranslations({ locale, namespace: "about" });

  const languages = Object.fromEntries(
    routing.locales.map((l) => [l, localizedPath(l, "/about")])
  );

  return {
    title: t("title"),
    description: t("description"),
    alternates: {
      canonical: localizedPath(locale, "/about"),
      languages: { ...languages, "x-default": "/about" },
    },
  };
};

import { getIntlayer, getMultilingualUrls } from "intlayer";
import type { Metadata } from "next";
import type { LocalPromiseParams } from "next-intlayer";

export const generateMetadata = async ({
  params,
}: LocalPromiseParams): Promise<Metadata> => {
  const { locale } = await params;
  const metadata = getIntlayer("about-metadata", locale);
  const multilingualUrls = getMultilingualUrls("/about");

  return {
    ...metadata,
    alternates: {
      canonical: multilingualUrls[locale as keyof typeof multilingualUrls],
      languages: { ...multilingualUrls, "x-default": "/about" },
    },
  };
};

保持 next-intl API，获得 Intlayer 的输出

您不必重写组件来获得上述基准数字。@intlayer/next-intl 是一个开箱即用的适配器：它保持 useTranslations、getTranslations、useFormatter、t.rich()、ICU 复数形式和 next-intl/navigation 助手，并从 Intlayer 编译器编译的 Intlayer 字典中提供它们。

import type { NextConfig } from "next";
ts fileName="next.config.ts"
import { createNextIntlPlugin } from "@intlayer/next-intl/plugin";

const withIntlayer = createNextIntlPlugin();

const nextConfig: NextConfig = {};

export default withIntlayer(nextConfig);

在基准测试中，同一应用的兼容性构建从每页 153.6 KB 降至 147.5 KB，从每个组件 21.8 KB 降至 8.1 KB，以及从约 90% 的页面泄漏降至 0%，应用代码保持不变。你现有的 messages/{locale}.json 文件可以通过 JSON 同步插件保持作为真实来源。

查看 next-intl 迁移指南获取分步说明。

何时选择哪个？

常见问题

相关比较

同一基准测试，其他库：

• i18next vs Intlayer
• Lingui vs Intlayer
• vue-i18n vs Intlayer benchmark
• next-i18next vs next-intl vs Intlayer
• react-i18next vs react-intl vs Intlayer

深入了解 next-intl：

• next-intl vs @intlayer/next-intl, 在同一应用上实测的适配器
• Is next-intl outdated?
• Using Intlayer with next-intl
• How to internationalize a Next.js app with next-intl

参考文档：

• Next.js 基准测试报告 与 TanStack Start 基准测试报告
• 兼容适配器：next-intl 与 迁移指南
• 包体积优化 与 Intlayer 编译器
• 组件级 vs 集中式 i18n
• 编译器驱动 vs 声明式 i18n

GitHub Stars

GitHub Stars 是项目受欢迎程度、社区信任度和长期相关性的强有力指标。虽然不是技术质量的直接衡量标准，但它们反映了有多少开发者认为该项目有用、关注其进展，以及可能采用它的开发者数量。

结论

next-intl 是一个可靠的、维护良好的库，基准测试证实它远不是 Next.js 上最差的选择。但是它的集中式目录模型将每项优化都交给了开发者：天真的设置会泄漏约 90% 的外语页面内容，而 runtime 本身在每个页面上就花费 +12.6 KB gzip。

Intlayer 将这些工作转移到编译器中。按组件字典、按语言环境的懒加载和无用内容清理是构建输出，而不是约定。在同一个应用上的结果：每页 +0.3 KB，0% 泄漏，组件小 3 倍，以及在 TanStack Start 上语言切换快 2-4 倍。

所有原始数据、测试应用和脚本都在 Benchmark Bloom 仓库 中。自己运行它。

有关更多详细信息，请参阅 '为什么选择 Intlayer?' 文档。