如何在 React 和 Next.js 中翻译 i18next JSON 文件 (2026)

你刚完成一个 React 应用，它需要在下周五前支持 12 种语言。你的语言环境文件位于 public/locales/en/common.json，每个语言环境有 340 个键，并且字符串中的令牌（token）看起来像 {{userName}} 和 {{count}}，散布在嵌套对象中。你将 JSON 粘贴到 ChatGPT 中，但它返回的结果中出现了 {{ nombreUsuario }}、多余的空格，并且一半的复数键被重命名了。你的应用在构建时崩溃了。

如果你尝试过自动化 i18next JSON 翻译，你就会明白这种痛苦。JSON 格式非常灵活，这正是大多数翻译工具会破坏它的原因。真正的问题不在于语言模型的质量——而是消费级 AI 工具不理解 i18next 的结构规则。

本指南将介绍 i18next JSON 与其他语言环境格式有何不同，为何简单的翻译方法会破坏 React 和 Next.js 应用，以及如何在数十个语言环境之间安全地自动化翻译，而无需手动审查每个键。

什么是 i18next JSON 以及为何翻译如此棘手

i18next 是 JavaScript 生态系统中使用最广泛的 i18n 库。它为 React (react-i18next)、Next.js (next-i18next、App Router next-intl)、Vue 和 Node 后端服务提供支持。它将可翻译字符串存储在扁平或嵌套的 JSON 文件中，每个语言环境一个文件。

典型的文件示例如下：

{
  "welcome": "Welcome, {{userName}}!",
  "cart": {
    "empty": "Your cart is empty",
    "items_one": "{{count}} item in your cart",
    "items_other": "{{count}} items in your cart"
  },
  "errors": {
    "network": "Network error. <strong>Please retry</strong>."
  }
}

这看起来很简单，但有三点使得使用通用型 AI 进行翻译变得危险。

插值令牌是结构性的，而非文本

序列 {{userName}} 不是一个词——它是一个运行时会用数据替换的占位符。添加空格 ({{ userName }})、重命名它，或者翻译内部标识符，运行时都会静默失败或抛出错误。有些翻译工具“好心”地将 {{count}} 在西班牙语中转换为 {{conteo}}。你的应用现在尝试插值一个不存在的变量，并将原始占位符呈现给用户。

复数键是魔术后缀

i18next 通过后缀检测复数形式：_zero、_one、_two、_few、_many、_other。这些并非任意字符串——它们必须与目标语言环境的 CLDR 复数类别匹配。英语只使用 _one 和 _other。俄语、阿拉伯语和波兰语最多使用六个类别。如果你的翻译工具删除了 _other 或重命名了它，回退链就会中断。

嵌套键必须保持完整

与扁平的键值对 Gettext .po 文件不同，i18next 文件可以任意嵌套。一个懒惰的翻译工具可能会扁平化结构，更改键名以匹配翻译后的文本，或重新排序对象。你的代码中的 t('cart.items_other') 调用将无法解析。

开发者首先尝试的糟糕解决方案

每个团队在投资真正的解决方案之前，都会经历相同的三阶段失败循环。

第一阶段：粘贴到 ChatGPT 中

你将 200 个键复制到 ChatGPT 中，询问“将此 JSON 翻译成西班牙语”，然后将结果粘贴回来。180 个键能正常工作。但有二十个键在 {{...}} 内部添加了空格，三个键的复数后缀被重写了，还有一个 <strong> 标签被翻译成了 <fuerte>。你的构建要么失败，要么将静默损坏的字符串发布到生产环境。

第二阶段：Google Translate API

你接入 Google Translate REST API，遍历你的 JSON，并发送每个值。速度很快，质量却不行。Google 的 API 孤立地处理每个字符串——没有关于你应用的上下文，不理解 {{count}} 是一个占位符，也不知道键 cart.empty 与 cart.items_one 的区别。你仍然需要对每个键进行人工审查。

第三阶段：商业 TMS 平台

你注册了一个翻译管理系统。他们按字收费，需要 GitHub 集成，并将你绑定到按月付费的席位。对于一个副项目或独立应用来说，经济效益很快就会崩溃——如果他们的引擎没有专门解析 i18next 格式，你仍然会遇到相同的占位符损坏问题。

相同的失败模式也出现在 Gettext 工作流程中。我们的指南如何在不破坏代码变量的情况下翻译 .po 文件涵盖了 WordPress 和其他基于 Gettext 的技术栈的类似问题。

安全的方法：语法感知翻译

大规模翻译 i18next JSON 的唯一可靠方法是使用一个工具，该工具首先解析格式，锁定语法，然后只将可翻译文本发送给 AI。

语法感知处理在底层的工作原理如下：

1. 将 JSON 解析为抽象树，保留键路径和嵌套结构。
2. 识别插值令牌 ({{name}}、{{count, number}}、{{date, datetime}})，并用占位符 ID 替换它们。
3. 识别 Trans 组件内的 HTML 标签 (<0>、<strong>、<br/>) 并锁定它们。
4. 通过后缀检测复数键，并将其映射到目标语言环境的 CLDR 规则。
5. 仅将清理后的文本连同键路径的上下文发送给 LLM。
6. 将原始令牌和标签重新插入到其精确位置。
7. 验证输出——如果任何占位符缺失或格式错误，则恢复到源文本。

这与使基于云的 PO 翻译安全可靠的原理相同。如果你对底层架构感到好奇，我们的AI 翻译质量比较详细阐述了不同的 LLM 如何处理这些限制。

循序渐进：使用 SimplePoTranslate 翻译 i18next JSON

SimplePoTranslate 在 Pro 和 Lifetime 计划中原生支持 i18next JSON。免费版目前支持 .po 和 .pot 文件——升级或使用试用版即可访问 JSON。

1. 准备你的源文件

使用你的英文（或源语言环境）文件作为主文件。确保它是有效的 JSON 格式，并包含你的应用使用的所有键。一个常见错误是留下陈旧或未使用的键，这会浪费你用于永远不会渲染的字符串的翻译配额。

# From your project root
cp public/locales/en/common.json ~/Desktop/common.json

2. 上传到 SimplePoTranslate

登录到你的仪表板，点击 New Translation，然后上传 common.json。平台会自动检测 i18next 格式。从 41 种支持的语言环境中选择你的目标语言，选择一种语调（专业、休闲、营销），然后提交。

3. 让引擎工作

在底层，文件被解析，分割成安全的批次，并并行翻译。插值令牌被锁定。复数后缀被保留并映射到目标语言环境的 CLDR 规则。Trans 组件内的 HTML 保持不变。

4. 下载 ZIP

你会得到一个 ZIP 文件，其中包含翻译后的 JSON 以及其他格式（.php 用于 PHP 应用，.po 用于跨工具兼容性）。将 JSON 文件放入 public/locales/es/common.json 并重新部署。

unzip common_es.zip
mv common.json public/locales/es/common.json
npm run build

5. 重复或批量处理

对于所有 12 个目标语言环境，提交 12 个作业。Pro 计划的配额足以覆盖数十个典型的 SaaS 应用。对于具有多个命名空间文件的单体仓库，可以分别上传或按顺序批量处理。

将翻译集成回你的应用

一旦你有了翻译好的 JSON 文件，集成就是最简单的部分。有几个注意事项：

• 验证复数类别。 对每个语言环境进行快速冒烟测试：渲染一个 count={0}、count={1}、count={5} 的组件，并确认这三者都生成了正确的字符串。
• 检查 RTL 语言环境。 如果你翻译成阿拉伯语、希伯来语或波斯语，你的 UI 需要支持 RTL 的 CSS。我们的 WordPress RTL 翻译指南涵盖了同样适用于 React 应用的 CSS 模式。
• 设置回退链。 配置 i18next 在键缺失时回退到英文，这样在部署过程中就不会导致用户崩溃。
• 在 CI 中锁定你的源文件。 添加一个检查，如果 en/common.json 在未重新生成其他语言环境的情况下发生更改，则拒绝 PR。翻译偏差是生产环境中 i18n bug 的最大单一原因。

对于在 React、Next.js 和服务器端发布应用的团队，从一个源生成所有格式是一个巨大的优势。我们的文章一文件多格式输出解释了多格式输出对长期维护的重要性。

当 JSON 不够用时：处理复杂情况

少数边缘情况需要额外注意。

ICU 消息格式

如果你的项目使用 ICU 语法 ({count, plural, one {1 item} other {# items}})，i18next 会将其视为插值，但其结构更复杂。确保你的翻译工具能识别 ICU 参数，并且不会翻译像 one、other 这样的类别名称，或像 plural、number、date 这样的格式标识符。

带有 React 节点的 Trans 组件

<Trans> 在翻译后的字符串中渲染 React 组件，通过索引 (<0>、<1>) 进行键控。翻译工具必须保留精确的标签顺序。SimplePoTranslate 的语法锁定功能可以处理这个问题，但如果你使用不同的工具，请在发布前进行验证。

命名空间文件

大型应用将语言环境文件拆分为命名空间：common.json、dashboard.json、checkout.json。独立翻译每个文件——不要合并它们。当每个命名空间的键路径保持限定范围时，上下文质量更高。

总结

为 React 或 Next.js 应用翻译 i18next JSON 并非选择最佳 AI 模型那么简单。它关乎尊重格式的结构规则：插值、复数后缀、嵌套键和 HTML 标签必须在往返翻译过程中保持完整。消费级 AI 工具将 JSON 视为非结构化文本。语法感知工具将其解析为结构化数据，并且只触及可翻译的部分。

如果你正在发布一个多语言应用，并且一直将 JSON 复制粘贴到聊天界面中，你已经知道其代价：每个语言环境需要数小时的人工审查、随机的生产环境错误，以及不断增多的损坏复数形式。格式感知型管道可以消除所有这些失败模式。

准备好安全地翻译你的 i18next JSON 文件了吗？免费试用 SimplePoTranslate - 无需信用卡。上传一次，即可支持 41 种语言。