如何选择合适的 React i18n 库

React 本身并没有提供内置的 i18n 原语。你在项目第一天选择的库，将决定翻译如何存储、如何打包进 bundle，以及未来几年需要承担多少维护工作。大多数团队通常根据流行度来选型，随后在翻译键达到 2,000 个时才发现各种妥协与限制。

本指南采用另一种思路：先回答关于你项目的几个核心问题，然后将答案映射到最契合的库。本文重点关注纯 React 生态（Vite、React Router、TanStack Start）。Next.js 有其专属的约束，已在 Next.js 对比文章 中详细介绍。

目录

在对比各库之前需要回答的 6 个问题

如果不清楚哪些指标对你最重要，功能对比表格就毫无意义。请先梳理以下问题：

1. 应用采用何种渲染方式？ 纯 SPA、带 hydration 的 SSR，还是 React Server Components。基于 Context 的 Hook 在 SPA 中处处适用；但在 RSC 中，Hook 会强制要求渲染文本的每个组件都加上 "use client"，因此你还需要服务端 API。
2. 谁来编写翻译？ 开发者、使用 TMS 的内部团队、交付 ICU 文件的翻译公司，还是 AI 自动化流程。这比任何 API 细节都更能决定翻译目录的格式。
3. 有多少个语言环境和页面？ 2 个语言环境和 5 个页面完全可以一次性打包所有内容；10 个语言环境和 50 个路由则无法承受，加载策略将成为核心成本。
4. 翻译键是否需要强类型约束？ 在所有基于键的库中，t("checkout.totl") 中的拼写错误都能通过编译，除非你手动配置类型。评估团队是否能接受这一点。
5. 文案包含哪些内容？ 纯文本、复数形式，还是中间嵌入 <Link> 的复杂句子。富文本内容往往是多数 API 变得臃肿的地方。
6. 项目的生命周期有多长？ 一个 3 个月的原型项目和一个维护 5 年的产品，对构建工具链的需求完全不同。

写下你的答案，后文的所有分析都将围绕它们展开。

一图看懂技术演进版图

十五年的 JavaScript i18n 发展史可以归纳为四波架构浪潮，而你所对比的 React 库正来自于不同的阶段。

JavaScript i18n 历史 详细探讨了每一波浪潮是如何解决前一波痛点的。

最关键的抉择：内容存放在哪里以及何时加载

所有 React i18n 库都具备相似的结构：一个 store、一个 provider、一个 hook。Provider 接收的任何内容最终都会进入客户端 bundle 或 hydration payload 中。因此，两个根本性的架构选择是：

• 集中式还是局部作用域内容： 整个应用共用一个 en.json，还是每个组件（或每个 namespace）独立声明。
• 静态导入还是动态导入： 启动时打包所有内容，还是按需获取当前语言环境与路由的内容。

下图估算了包含 1 到 10 个页面、翻译成 1 到 10 个语言环境、每页约 30 KB 文本的理论应用 payload：

采用静态导入的集中式内容会随着两个维度同时膨胀：10 个页面乘以 10 个语言环境，意味着每个页面都要加载 300 KB 的文本。动态导入消除了语言维度的膨胀，组件级作用域消除了页面维度的膨胀，只有两者结合才能让体积保持平稳。

这不仅是库的特性，更关乎工程规范。react-i18next 可以通过 namespace 和 lazy backend 实现作用域划分，use-intl 也可以按路由拆分。但工具链本身并不会强制执行，一个通用的 <Button> 如果调用了 t("common:cta")，就会悄悄让 common 成为所有路由的依赖。基准测试 将这种现象衡量为“其他路由泄漏”和“其他语言泄漏”，这也是各库之间体积差距的主要来源。

如果你对第 3 个问题的答案是“多语言、多页面”，请将本节作为核心考量。按组件 vs 集中式 i18n 一文深入分析了这一选择在维护层面的影响。

候选方案一览

各库的体积数据来源于 TanStack Start 基准测试：空组件中的 provider 加上 hook，在经过打包、tree-shaking 和压缩后的体积（基于 10 个页面和 10 个语言环境）。内容体积单独计算。

数据为基准测试特定版本时的快照，会随版本更新而变动。在仅凭体积做决定前，建议在自己的应用中运行基准测试。

表格中未体现的两点细节：Paraglide 本身体积接近于零，是因为它将代码直接生成到你的代码库中，这意味着每次 commit 前都需要重新生成，并且生成的文件可能产生 merge conflict；而 Intlayer 依赖打包工具插件（vite-intlayer 或等效插件），因此无法在无需构建工具（no-build）的环境中运行。

根据你的答案匹配合适的库

各个库的局限性

客观分析每个方案都存在的局限：

• react-i18next：同类中最重，自研的复数格式，类型需手动配置与维护，废弃的无用键容易在无感知中堆积。
• react-intl：DX 较为繁琐（先 useIntl() 再 formatMessage({ id })），全局实例绑定了较多节点。
• use-intl：上手简单，优化困难。Namespaces、动态加载与类型结合使用时会显著拖慢开发节奏。
• Lingui：需要额外的 extract / compile 构建步骤，多种并存的语法（t()、标签模板、i18n.t()、<Trans>）容易让开发者和 AI 助手产生混淆。
• Paraglide：在仓库中生成大量代码文件，在 React 基准测试中 tree-shaking 未充分生效，且语言环境直接从 storage 读取而非统一 store。
• Tolgee：缺乏键类型支持，上手门槛较高，核心卖点在上下文内可视化编辑。
• Intlayer：必须依赖构建插件，生态相对较新，ICU 支持尚不完整，内容天然分散在代码库中，若需为外部翻译人员导出单个全量 JSON 需要借助工具。
• gt-react, lingo.dev：在基准测试中表现欠佳：构建时容易出现配额错误、厂商锁定风险，以及需要强制刷新 provider 的响应性问题。

代码示例对比

以同一个组件（包含标题和复数统计的购物车摘要）为例，展示各个候选方案的实现。重点不仅在于组件代码，更在于内容如何存储以及类型检查器对内容的感知能力。

{
  "title": "Your cart",
  "items_one": "{{count}} item",
  "items_other": "{{count}} items"
}

import type { FC } from "react";
import { useTranslation } from "react-i18next";

export const CartSummary: FC<{ count: number }> = ({ count }) => {
  const { t } = useTranslation("cart");

  return (
    <section>
      <h2>{t("title")}</h2>
      <p>{t("items", { count })}</p>
    </section>
  );
};

{
  "cart.title": "Your cart",
  "cart.items": "{count, plural, one {# item} other {# items}}"
}

import type { FC } from "react";
import { FormattedMessage, useIntl } from "react-intl";

export const CartSummary: FC<{ count: number }> = ({ count }) => {
  const intl = useIntl();

  return (
    <section>
      <h2>
        <FormattedMessage id="cart.title" />
      </h2>
      <p>{intl.formatMessage({ id: "cart.items" }, { count })}</p>
    </section>
  );
};

{
  "Cart": {
    "title": "Your cart",
    "items": "{count, plural, one {# item} other {# items}}"
  }
}

import type { FC } from "react";
import { useTranslations } from "use-intl";

export const CartSummary: FC<{ count: number }> = ({ count }) => {
  const t = useTranslations("Cart");

  return (
    <section>
      <h2>{t("title")}</h2>
      <p>{t("items", { count })}</p>
    </section>
  );
};

msgid "Your cart"
msgstr "Votre panier"

msgid "{count, plural, one {# item} other {# items}}"
msgstr "{count, plural, one {# article} other {# articles}}"

import type { FC } from "react";
import { Plural, Trans } from "@lingui/react/macro";

export const CartSummary: FC<{ count: number }> = ({ count }) => (
  <section>
    <h2>
      <Trans>Your cart</Trans>
    </h2>
    <p>
      <Plural value={count} one="# item" other="# items" />
    </p>
  </section>
);

{
  "cart_title": "Your cart",
  "cart_items": "{count} items"
}

import type { FC } from "react";
import { m } from "../paraglide/messages.js";

export const CartSummary: FC<{ count: number }> = ({ count }) => (
  <section>
    <h2>{m.cart_title()}</h2>
    <p>{m.cart_items({ count })}</p>
  </section>
);

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

const cartSummaryContent = {
  key: "cart-summary",
  content: {
    title: t({
      zh: "购物车",
      en: "Your cart",
      fr: "Votre panier",
      es: "Tu carrito",
    }),
    items: t({
      zh: plural({ one: "{{count}} 件商品", other: "{{count}} 件商品" }),
      en: plural({ one: "{{count}} item", other: "{{count}} items" }),
      fr: plural({ one: "{{count}} article", other: "{{count}} articles" }),
      es: plural({ one: "{{count}} artículo", other: "{{count}} artículos" }),
    }),
  },
} satisfies Dictionary;

export default cartSummaryContent;

import type { FC } from "react";
import { useIntlayer } from "react-intlayer";

export const CartSummary: FC<{ count: number }> = ({ count }) => {
  const { title, items } = useIntlayer("cart-summary");

  return (
    <section>
      <h2>{title}</h2>
      <p>{items(count)}</p>
    </section>
  );
};

如果已经在使用 react-i18next、react-intl 或 Lingui，兼容适配器（react-i18next、react-intl、Lingui）会在打包工具层面设置别名，让你在逐个迁移组件的同时保持现有 API 正常工作。迁移指南 涵盖了其余迁移步骤。

最终决定前的自查清单

功能清单仅说明库当前能做什么，以下几点则决定了长期维护的实际体验。

检查仓库活跃度。

关注 commit 频率、issue 响应速度，以及最近的小版本更新是否发生在今年。一个设计精良但缺乏维护的库，意味着未来不可避免的重构与迁移。

不要单纯依据 npm 下载量做决定。

安装量最大的往往是最早发布的库，而不一定是最适合 2026 年 React 代码库的方案。下载量衡量的是历史沉淀，而不是当下的契合度。

了解维护者的资金来源和商业模式。

i18next 背后有 Locize 支持；next-intl / use-intl、vue-i18n、svelte-i18n 和 Lingui 由 Crowdin 支持；Tolgee、Paraglide (inlang) 和 Intlayer 则运营着各自的平台。靠托管翻译盈利的商业公司，通常缺乏动力在你的本地工具链内提供完全免费的翻译能力。Intlayer 是其中唯一支持直接通过 CLI 调用自带 API key（OpenAI、Anthropic、Mistral、Gemini）执行 AI 翻译并提供可私有化部署 CMS 的方案。

是否具备 AI Agent 就绪能力？

目前的 AI Agent 在处理 i18n 时仍容易出错：遗漏语言、凭空捏造键名、混淆消息语法。该库是否提供了 Agent Skills 或 MCP server，以便 Agent 可以列出、填充和测试文案？内容加载策略是开箱即优化的，还是需要每季度人工审核 namespaces 和懒加载导入？

开箱即用的类型安全。

关注的不是“通过额外配置能否支持类型”，而是“在全新安装后输入错误键名能否直接导致 tsc 报错”。测试访问不存在的键或某一语言缺少某条翻译时的行为表现。

废弃与未引用内容的检测。

翻译目录往往只增不减。Intlayer 构建时会自动清除未使用的字段并输出日志（build.purge）。Paraglide 依托架构天然支持，未被调用的消息函数会被 tree-shake 剔除。其他方案则需要开发者手动清理。

开发者体验 (DX)。

从零配置到渲染出第一条翻译字符串所需的时间、显示悬停翻译并支持跳转到声明的 LSP 或 VS Code 插件、用于填充、测试和推送的 CLI，以及非开发人员无需提交 PR 即可编辑文案的渠道（可视化编辑器 或 CMS）。

常见问题解答

延伸阅读

• i18n 库基准测试：bundle 大小、泄漏与语言切换耗时 及 TanStack Start 评测报告
• React i18n：Provider 模式的工作原理及性能开销
• react-i18next vs react-intl vs Intlayer 全方位特性对比
• next-i18next vs next-intl vs Intlayer
• JavaScript i18n 发展史
• 编译器 vs 声明式 i18n
• 按组件管理 vs 集中式 i18n
• 构建时 bundle 优化机制
• 在 Vite + React 应用中配置 i18n
• 对应指南：Vue、Svelte 与 Solid