@intlayer/docs 9.5.2 → 9.5.4-canary.0

package/blog/zh/how_to_pick_react_i18n_library.md

@@ -0,0 +1,548 @@
+---
+createdAt: 2026-09-16
+updatedAt: 2026-09-16
+title: "如何在 2026 年选择合适的 React i18n 库"
+description: "React 国际化选型指南。在对比 react-i18next、react-intl、Lingui、use-intl、Paraglide 和 Intlayer 之前需要回答的关键问题，以及各方案在 bundle size、类型支持和维护成本方面的权衡。"
+keywords:
+  - React i18n
+  - React 国际化
+  - react-i18next
+  - react-intl
+  - Lingui
+  - use-intl
+  - Paraglide
+  - Intlayer
+  - i18n 库对比
+slugs:
+  - blog
+  - how-to-pick-react-i18n-library
+author: aymericzip
+---
+
+# 如何选择合适的 React i18n 库
+
+React 本身并没有提供内置的 i18n 原语。你在项目第一天选择的库，将决定翻译如何存储、如何打包进 bundle，以及未来几年需要承担多少维护工作。大多数团队通常根据流行度来选型，随后在翻译键达到 2,000 个时才发现各种妥协与限制。
+
+本指南采用另一种思路：先回答关于你项目的几个核心问题，然后将答案映射到最契合的库。本文重点关注纯 React 生态（Vite、React Router、TanStack Start）。Next.js 有其专属的约束，已在 [Next.js 对比文章](https://github.com/aymericzip/intlayer/blob/main/docs/blog/zh/next-i18next_vs_next-intl_vs_intlayer.md) 中详细介绍。
+
+![React i18n 库生态系统](https://github.com/aymericzip/intlayer/blob/main/docs/assets/cloud_i18n_logo.webp?raw=true)
+
+## 目录
+
+<TOC/>
+
+## 在对比各库之前需要回答的 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 库发展史](https://github.com/aymericzip/intlayer/blob/main/docs/assets/history_i18n.webp?raw=true)
+
+<AccordionGroup>
+<Accordion header="运行时字典（2011 至 2017 年）：i18next, react-intl">
+
+在内存中加载 JSON 目录，运行时查找 `t("a.b")`，并在浏览器中解析 ICU 或自定义语法。生态最庞大，运行时最重，类型支持为 opt-in（可选配置）。
+
+</Accordion>
+<Accordion header="编译时宏（2018 至 2021 年）：Lingui, typesafe-i18n">
+
+在构建时提取文案并编译为紧凑目录，提供类型化参数。通过增加额外的构建步骤（`extract`、`compile`）换取更小的 bundle 体积。
+
+</Accordion>
+<Accordion header="服务端优先（2022 至 2024 年）：use-intl / next-intl">
+
+围绕 SSR 和 Server Components 设计。在服务端完成渲染，客户端仅 hydrate 必需的内容。本质上仍然基于键且集中管理。
+
+</Accordion>
+<Accordion header="编译器与同构/就近内容管理（2024 至 2026 年）：Paraglide, Intlayer, wuchale">
+
+文案被编译为支持 tree-shaking 的函数或按组件划分的字典。类型自动生成，缺失翻译直接中断构建，并通过 CLI 执行 AI 翻译。
+
+</Accordion>
+</AccordionGroup>
+
+[JavaScript i18n 历史](https://github.com/aymericzip/intlayer/blob/main/docs/blog/zh/history_of_i18n.md) 详细探讨了每一波浪潮是如何解决前一波痛点的。
+
+## 最关键的抉择：内容存放在哪里以及何时加载
+
+所有 React i18n 库都具备相似的结构：一个 store、一个 provider、一个 hook。Provider 接收的任何内容最终都会进入客户端 bundle 或 hydration payload 中。因此，两个根本性的架构选择是：
+
+- **集中式还是局部作用域内容：** 整个应用共用一个 `en.json`，还是每个组件（或每个 namespace）独立声明。
+- **静态导入还是动态导入：** 启动时打包所有内容，还是按需获取当前语言环境与路由的内容。
+
+下图估算了包含 1 到 10 个页面、翻译成 1 到 10 个语言环境、每页约 30 KB 文本的理论应用 payload：
+
+![不同架构下的理论内容泄漏](https://github.com/aymericzip/intlayer/blob/main/docs/assets/theorical_content_leakage.webp?raw=true)
+
+采用静态导入的集中式内容会随着两个维度同时膨胀：10 个页面乘以 10 个语言环境，意味着每个页面都要加载 300 KB 的文本。动态导入消除了语言维度的膨胀，组件级作用域消除了页面维度的膨胀，只有两者结合才能让体积保持平稳。
+
+这不仅是库的特性，更关乎工程规范。`react-i18next` 可以通过 namespace 和 lazy backend 实现作用域划分，`use-intl` 也可以按路由拆分。但工具链本身并不会强制执行，一个通用的 `<Button>` 如果调用了 `t("common:cta")`，就会悄悄让 `common` 成为所有路由的依赖。[基准测试](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/benchmark/index.md) 将这种现象衡量为“其他路由泄漏”和“其他语言泄漏”，这也是各库之间体积差距的主要来源。
+
+如果你对第 3 个问题的答案是“多语言、多页面”，请将本节作为核心考量。[按组件 vs 集中式 i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/zh/per-component_vs_centralized_i18n.md) 一文深入分析了这一选择在维护层面的影响。
+
+## 候选方案一览
+
+各库的体积数据来源于 [TanStack Start 基准测试](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/benchmark/tanstack.md)：空组件中的 provider 加上 hook，在经过打包、tree-shaking 和压缩后的体积（基于 10 个页面和 10 个语言环境）。内容体积单独计算。
+
+| 库                      | 演进浪潮   | 内容模型                                | 类型安全                           | 消息格式                      | 库体积                             |
+| :---------------------- | :--------- | :-------------------------------------- | :--------------------------------- | :---------------------------- | :--------------------------------- |
+| `react-i18next`         | 运行时     | 集中式 JSON，namespaces                 | 2/5 — Opt-in (`CustomTypeOptions`) | i18next (后缀复数)            | ~18.4 kB                           |
+| `react-intl` (FormatJS) | 运行时     | 集中式 JSON，ICU                        | 2/5 — Opt-in (提取 + union)        | ICU                           | ~15.3 kB                           |
+| `use-intl`              | 服务端优先 | 集中式 JSON，ICU                        | 2/5 — Opt-in (declaration merging) | ICU                           | ~14.1 kB                           |
+| `@tolgee/react`         | 运行时     | 集中式，上下文内可视化编辑 (in-context) | 1/5 — 无                           | ICU                           | ~11.1 kB                           |
+| Lingui                  | 宏         | 代码内源码文本，编译后目录              | 2/5 — 良好，由编译器生成           | 基于宏的 ICU                  | ~11.8 kB                           |
+| Paraglide               | 编译器     | inlang 项目，生成函数                   | 3.5/5 — 自动生成                   | 自研格式                      | 接近于零（因为代码生成到代码库中） |
+| Intlayer                | 编译器     | 单组件 `.content.ts` 声明               | 5/5 — 自动生成，默认开启           | Intlayer (+ ICU, i18next, PO) | ~5.0 kB                            |
+
+> 数据为基准测试特定版本时的快照，会随版本更新而变动。在仅凭体积做决定前，建议在自己的应用中运行基准测试。
+> 类型安全：5/5 表示键、参数和每个语言环境均无需手动配置即可得到校验，包括 URL 格式化工具与辅助函数。
+
+表格中未体现的两点细节：`Paraglide` 本身体积接近于零，是因为它将代码直接生成到你的代码库中，这意味着每次 commit 前都需要重新生成，并且生成的文件可能产生 merge conflict；而 `Intlayer` 依赖打包工具插件（`vite-intlayer` 或等效插件），因此无法在无需构建工具（no-build）的环境中运行。
+
+## 根据你的答案匹配合适的库
+
+<AccordionGroup>
+<Accordion header="原型开发、小型团队、少量语言环境">
+
+选择最简单能用的方案，避免过度投入。`react-i18next` 配合每个语言一个单独的 JSON 文件即可满足需求，Stack Overflow 上十年的积累能帮你节省大量时间。在真正需要前无需引入 namespaces。如果原型后续演进为正式产品，可以规划迁移到作用域隔离的内容管理；[react-i18next 兼容适配器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/compat/react-i18next.md) 支持渐进式迁移。
+
+</Accordion>
+<Accordion header="翻译来自支持 ICU 的翻译机构或 TMS">
+
+翻译目录格式已经预先确定。`react-intl` 原生支持 ICU，FormatJS 的提取工具专为该流程构建。`use-intl` 同样读取 ICU。`react-i18next` 则需要安装 ICU 插件，否则只能使用自有的复数键规则。Intlayer 的 ICU 支持仍在完善中，如果你当前依赖 ICU 字符串，建议将其作为关键考量项。
+
+</Accordion>
+<Accordion header="大型应用、众多路由、严格关注 bundle 预算">
+
+优先默认采用作用域隔离内容与动态加载，而不是依赖开发约定。`Lingui` 和 `Paraglide` 通过编译实现这一点。Intlayer 通过按组件声明实现，编译器仅打包当前路由渲染的内容。如果选用 `react-i18next` 或 `use-intl`，必须在第一天规划好 namespace 和懒加载策略并在 code review 中严格把关，因为工具链不会自动拦截违规引入。
+
+</Accordion>
+<Accordion header="类型安全不可妥协">
+
+所有基于键的库都可以配置类型，但几乎没有哪个是默认启用的。如果你不想维护在懒加载 namespaces 下脆弱的 declaration merging，请选择能从内容自动生成类型的库：`Lingui`、`Paraglide` 或 Intlayer。[检测缺失翻译](https://github.com/aymericzip/intlayer/blob/main/docs/blog/zh/detecting_missing_translations.md) 一文对比了各工具在构建时能捕获的错误类型。
+
+</Accordion>
+<Accordion header="包含大量富文本内容：markdown、句子中嵌入链接、按语言定制组件">
+
+富文本节点是 `t()` 返回字符串模式的短板所在。`react-i18next` 和 `Lingui` 提供了 `<Trans>`，`react-intl` 提供了富文本标签，这些处理方式都比普通字符串更繁琐。Intlayer 的内容节点可直接接收 JSX、markdown 和嵌套对象，如果内容不仅限于简单 UI 标签，这种方式更为契合。
+
+</Accordion>
+<Accordion header="翻译由 AI 生成、开发者审核">
+
+集中式 JSON 不再是刚需，因为无需导入到传统 TMS 中。代码就近放置的内容（colocated content）加上自动填充缺失语言的 CLI 是更高效的路径。Intlayer 的 `fill` 命令直接使用你自己的 API key（OpenAI、Anthropic、Mistral、Gemini），并且只翻译变更的内容。Paraglide 和 Tolgee 则提供了对应的托管版商业方案。
+
+</Accordion>
+<Accordion header="未来可能迁移至 Next.js App Router">
+
+React context 无法跨越服务端/客户端边界。仅依赖客户端 Hook 构建的库（`react-i18next`、`react-intl`）在引入 RSC 时需要配套的服务端 API。`use-intl`（作为 `next-intl`）和 Intlayer（作为 `next-intlayer`）已经实现了这种架构拆分。在统一规范前，建议阅读 [Next.js i18n 指南](https://github.com/aymericzip/intlayer/blob/main/docs/blog/zh/list_i18n_technologies/frameworks/nextjs.md)。
+
+</Accordion>
+</AccordionGroup>
+
+## 各个库的局限性
+
+客观分析每个方案都存在的局限：
+
+- **`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 的响应性问题。
+
+## 代码示例对比
+
+以同一个组件（包含标题和复数统计的购物车摘要）为例，展示各个候选方案的实现。重点不仅在于组件代码，更在于内容如何存储以及类型检查器对内容的感知能力。
+
+<Tabs defaultTab="react-i18next">
+  <Tab label="react-i18next" value="react-i18next">
+
+  <Tabs group="locale">
+  <Tab value="en" label="英语">
+
+```json fileName="public/locales/en/cart.json"
+{
+  "title": "Your cart",
+  "items_one": "{{count}} item",
+  "items_other": "{{count}} items"
+}
+```
+
+  </Tab>
+  <Tab value="fr" label="法语">
+
+```json fileName="public/locales/fr/cart.json"
+{
+  "title": "Votre panier",
+  "items_one": "{{count}} article",
+  "items_other": "{{count}} articles"
+}
+```
+
+  </Tab>
+  <Tab value="es" label="西班牙语">
+
+```json fileName="public/locales/es/cart.json"
+{
+  "title": "Tu carrito",
+  "items_one": "{{count}} artículo",
+  "items_other": "{{count}} artículos"
+}
+```
+
+  </Tab>
+  </Tabs>
+
+```tsx fileName="src/components/CartSummary.tsx"
+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>
+  );
+};
+```
+
+复数是基于 `Intl.PluralRules` 解析的后缀键。除非声明了 `CustomTypeOptions`，否则 `t` 的类型签名仅为 `(key: string) => string`，`t("titel")` 也能通过编译。
+
+  </Tab>
+  <Tab label="react-intl" value="react-intl">
+
+  <Tabs group="locale">
+  <Tab value="en" label="英语">
+
+```json fileName="src/locales/en.json"
+{
+  "cart.title": "Your cart",
+  "cart.items": "{count, plural, one {# item} other {# items}}"
+}
+```
+
+  </Tab>
+  <Tab value="fr" label="法语">
+
+```json fileName="src/locales/fr.json"
+{
+  "cart.title": "Votre panier",
+  "cart.items": "{count, plural, one {# article} other {# articles}}"
+}
+```
+
+  </Tab>
+  <Tab value="es" label="西班牙语">
+
+```json fileName="src/locales/es.json"
+{
+  "cart.title": "Tu carrito",
+  "cart.items": "{count, plural, one {# artículo} other {# artículos}}"
+}
+```
+
+  </Tab>
+  </Tabs>
+
+```tsx fileName="src/components/CartSummary.tsx"
+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>
+  );
+};
+```
+
+端到端采用 ICU 格式，这也是大多数 TMS 平台导出的标准格式。`id` 上的类型来自于 `formatjs` 提取步骤和生成的 union 类型，并非开箱即用。
+
+  </Tab>
+  <Tab label="use-intl" value="use-intl">
+
+  <Tabs group="locale">
+  <Tab value="en" label="英语">
+
+```json fileName="messages/en.json"
+{
+  "Cart": {
+    "title": "Your cart",
+    "items": "{count, plural, one {# item} other {# items}}"
+  }
+}
+```
+
+  </Tab>
+  <Tab value="fr" label="法语">
+
+```json fileName="messages/fr.json"
+{
+  "Cart": {
+    "title": "Votre panier",
+    "items": "{count, plural, one {# article} other {# articles}}"
+  }
+}
+```
+
+  </Tab>
+  <Tab value="es" label="西班牙语">
+
+```json fileName="messages/es.json"
+{
+  "Cart": {
+    "title": "Tu carrito",
+    "items": "{count, plural, one {# artículo} other {# artículos}}"
+  }
+}
+```
+
+  </Tab>
+  </Tabs>
+
+```tsx fileName="src/components/CartSummary.tsx"
+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>
+  );
+};
+```
+
+结构与 `next-intl` 一致，但移除了 Next.js 专属绑定。使用 messages 类型扩展 `AppConfig` 后可获得键类型支持；namespaces 的拆分需要开发者自行规划。
+
+  </Tab>
+  <Tab label="Lingui" value="lingui">
+
+```po fileName="src/locales/fr/messages.po"
+msgid "Your cart"
+msgstr "Votre panier"
+
+msgid "{count, plural, one {# item} other {# items}}"
+msgstr "{count, plural, one {# article} other {# articles}}"
+```
+
+```tsx fileName="src/components/CartSummary.tsx"
+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>
+);
+```
+
+源语言直接编写在组件中；其他语言在执行 `lingui extract` 后存放于带哈希 id 的 `.po` 文件中。如果遗漏了 `extract` 或 `compile`，会静默回退到英文。
+
+  </Tab>
+  <Tab label="Paraglide" value="paraglide">
+
+  <Tabs group="locale">
+  <Tab value="en" label="英语">
+
+```json fileName="messages/en.json"
+{
+  "cart_title": "Your cart",
+  "cart_items": "{count} items"
+}
+```
+
+  </Tab>
+  <Tab value="fr" label="法语">
+
+```json fileName="messages/fr.json"
+{
+  "cart_title": "Votre panier",
+  "cart_items": "{count} articles"
+}
+```
+
+  </Tab>
+  <Tab value="es" label="西班牙语">
+
+```json fileName="messages/es.json"
+{
+  "cart_title": "Tu carrito",
+  "cart_items": "{count} artículos"
+}
+```
+
+  </Tab>
+  </Tabs>
+
+```tsx fileName="src/components/CartSummary.tsx"
+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>
+);
+```
+
+每条消息都是自动生成的类型化函数，因此缺失键会直接触发导入错误。`paraglide/` 目录直接生成在项目中，并在每次修改时重新生成。
+
+  </Tab>
+  <Tab label="Intlayer" value="intlayer">
+
+```ts fileName="src/components/cartSummary.content.ts"
+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;
+```
+
+```tsx fileName="src/components/CartSummary.tsx"
+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>
+  );
+};
+```
+
+所有语言环境集中在组件同级的单个文件中。类型在构建时自动生成，`title` 具备自动补全，拼写错误无需 declaration merging 即可在 `tsc` 中报错。删除组件目录即可同步删除对应文案。
+
+  </Tab>
+</Tabs>
+
+如果已经在使用 `react-i18next`、`react-intl` 或 `Lingui`，兼容适配器（[react-i18next](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/compat/react-i18next.md)、[react-intl](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/compat/react-intl.md)、[Lingui](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/compat/lingui.md)）会在打包工具层面设置别名，让你在逐个迁移组件的同时保持现有 API 正常工作。[迁移指南](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/migration_from_react-i18next_to_intlayer.md) 涵盖了其余迁移步骤。
+
+## 最终决定前的自查清单
+
+功能清单仅说明库当前能做什么，以下几点则决定了长期维护的实际体验。
+
+**检查仓库活跃度。**
+
+关注 commit 频率、issue 响应速度，以及最近的小版本更新是否发生在今年。一个设计精良但缺乏维护的库，意味着未来不可避免的重构与迁移。
+
+**不要单纯依据 npm 下载量做决定。**
+
+安装量最大的往往是最早发布的库，而不一定是最适合 2026 年 React 代码库的方案。下载量衡量的是历史沉淀，而不是当下的契合度。
+
+![JavaScript i18n 库评级梯队图](https://github.com/aymericzip/intlayer/blob/main/docs/assets/alphabet_rank_i18n_lib.webp?raw=true)
+
+**了解维护者的资金来源和商业模式。**
+
+`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](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/agent_skills.md) 或 [MCP server](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/mcp_server.md)，以便 Agent 可以列出、填充和测试文案？内容加载策略是开箱即优化的，还是需要每季度人工审核 namespaces 和懒加载导入？
+
+**开箱即用的类型安全。**
+
+关注的不是“通过额外配置能否支持类型”，而是“在全新安装后输入错误键名能否直接导致 `tsc` 报错”。测试访问不存在的键或某一语言缺少某条翻译时的行为表现。
+
+**废弃与未引用内容的检测。**
+
+翻译目录往往只增不减。Intlayer 构建时会自动清除未使用的字段并输出日志（`build.purge`）。Paraglide 依托架构天然支持，未被调用的消息函数会被 tree-shake 剔除。其他方案则需要开发者手动清理。
+
+**开发者体验 (DX)。**
+
+从零配置到渲染出第一条翻译字符串所需的时间、显示悬停翻译并支持跳转到声明的 [LSP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/lsp.md) 或 [VS Code 插件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/vs_code_extension.md)、用于填充、测试和推送的 [CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/index.md)、能把组件中硬编码的字符串提取出来、免去逐个键维护的[编译器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/compiler.md)或提取工具，以及非开发人员无需提交 PR 即可编辑文案的渠道（[可视化编辑器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_visual_editor.md) 或 [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_CMS.md)）。
+
+## 常见问题解答
+
+<FAQ>
+
+<Question title="react-i18next 在 2026 年依然是稳妥的默认选项吗？">
+
+对于大多数团队而言依然如此。它拥有最庞大的生态系统和最丰富的在线解决方案。它的成本真实存在但可预期：最大的运行时开销、自定义的复数格式，以及需要团队自行配置和维护的类型安全与作用域隔离。
+
+</Question>
+
+<Question title="我需要基于编译器的库吗？">
+
+只有当 bundle 体积、生成的类型或构建时缺失键检查是核心诉求时才需要。对于仅有两种语言的小型应用，运行时方案更为简单。[编译器 vs 声明式 i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/zh/compiler_vs_declarative_i18n.md) 一文解析了编译器的优势以及可能存在的边界问题。
+
+</Question>
+
+<Question title="以后能否在不重写每个组件的前提下更换库？">
+
+部分可以。基于键的库具有相似的 API 结构，可以通过兼容适配器将一个 API 别名映射到另一个 API（如 Intlayer 适配器的实现方式）。但消息格式（ICU、i18next、辅助函数）无法自动转换，因此复数和插值语法部分需要手动调整。
+
+</Question>
+
+<Question title="库的选择会影响 SEO 吗？">
+
+会产生间接影响。搜索引擎爬虫获取的内容由路由设计、`hreflang`、`<html lang>` 以及文本是否包含在服务端渲染的 HTML 中决定。部分库提供了相关辅助工具，大多数则需要开发者自行处理。详情参见 [hreflang 指南](https://github.com/aymericzip/intlayer/blob/main/docs/blog/zh/hreflang_guide_multilingual_seo.md)。
+
+</Question>
+
+</FAQ>
+
+## 延伸阅读
+
+- [i18n 库基准测试：bundle 大小、泄漏与语言切换耗时](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/benchmark/index.md) 及 [TanStack Start 评测报告](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/benchmark/tanstack.md)
+- [React i18n：Provider 模式的工作原理及性能开销](https://github.com/aymericzip/intlayer/blob/main/docs/blog/zh/list_i18n_technologies/frameworks/react.md)
+- [react-i18next vs react-intl vs Intlayer 全方位特性对比](https://github.com/aymericzip/intlayer/blob/main/docs/blog/zh/react-i18next_vs_react-intl_vs_intlayer.md)
+- [next-i18next vs next-intl vs Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/blog/zh/next-i18next_vs_next-intl_vs_intlayer.md)
+- [JavaScript i18n 发展史](https://github.com/aymericzip/intlayer/blob/main/docs/blog/zh/history_of_i18n.md)
+- [编译器 vs 声明式 i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/zh/compiler_vs_declarative_i18n.md)
+- [按组件管理 vs 集中式 i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/zh/per-component_vs_centralized_i18n.md)
+- [构建时 bundle 优化机制](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/bundle_optimization.md)
+- [在 Vite + React 应用中配置 i18n](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_with_vite+react.md)
+- 对应指南：[Vue](https://github.com/aymericzip/intlayer/blob/main/docs/blog/zh/how_to_pick_vue_i18n_library.md)、[Svelte](https://github.com/aymericzip/intlayer/blob/main/docs/blog/zh/how_to_pick_svelte_i18n_library.md) 与 [Solid](https://github.com/aymericzip/intlayer/blob/main/docs/blog/zh/how_to_pick_solid_i18n_library.md)