在代码审核中检查 React 本地化

结合消息提取、消息目录检查、TypeScript 检查和应用构建,在合并前发现不同类型的本地化缺陷。

React 消息的变更需要经过源代码、消息提取、目标消息目录和应用加载器,才能最终呈现给读者。审核文案时,也要一并检查这条链路。翻译即使正确,若关联的标识已过时,也不会显示;回退到源文本则可能在维持界面可用的同时,掩盖翻译缺失的问题。

此方法适用于当前的 React 包及通过 CLI 提取的 JSONC 消息目录。除 CLI 的提取检查外,还应运行项目自身的构建和渲染检查。

先检查源代码变更 #

先把新的源消息当作面向用户的指令或陈述来读,再看它的上下文。“按钮”描述的是形态;“在提交前取消已安排的付款”说明的是操作,而操作的含义必须在翻译中保留。源文本和上下文都会影响标识,因此,即使只修改上下文,也可能需要新增目标条目。

审核占位符时,要将其视为用途固定的值。译者应能调整人名或金额的位置,而不改变其标识。对于富文本,应将导航和组件行为保留在代码中,只翻译命名标签周围的句子。消息和富文本文档提供了具体的 API。

先检查提取,再检查目标内容 #

安装 CLI 后,在要检查的项目目录中运行:

sh
lingo extract --check
lingo check

使用与项目提取命令相同的 --src、--source-locale、--out 和 --types 选项。源语言区域默认为 en;本地化配置不会改变该命令的默认值。随后运行仓库的 TypeScript 检查和生产构建,并将生成的声明纳入检查。

在本地审核测试样例中引入的缺陷检查关卡与预期结果
修改源消息,但不重新生成消息目录或声明。extract --check 会对比生成的输出,并在输出过时时判定检查失败。
在提取的消息中省略必需的上下文。check 会报告提取或上下文问题;需检查源代码,修正消息含义。
在现有目标 JSONC 消息目录中留下缺失或为空的条目。check 会报告找到的消息目录中缺失的翻译。
未更新已过时的生成声明。提取或检查会发现生成内容不一致;TypeScript 则另行检查应用中的使用情况。
破坏语言区域导入或框架集成。应用的实际构建应能发现集成故障。

首次建立这些检查时,请使用本地测试样例。即使找不到源文件,extract --check 也会成功,因此请确认报告中的目录包含要检查的代码。否则,检查通过可能只是因为它根本没有检查任何内容。

明确检查所需语言区域的覆盖情况 #

当 .lingo/config.json 中的 files 模式匹配源消息目录(例如 locales/en.jsonc)时,lingo check 还会要求所有已配置的目标语言区域文件都存在。lingo init --yes 写入的模式 locales/en.json 不匹配 .jsonc 消息目录,因此使用该模式时,只会运行 React 检查。它只会报告现有 JSONC 目标文件中缺失的键。审核时,请将所需语言区域列表与文件及导入项逐一核对。在本地测试样例中暂时删除一个目标条目,观察回退到源文本时界面如何显示。

选取有代表性的源文本与目标文本进行对照,检查含义,尤其留意有变更的承诺和产品术语。JSONC 一致性检查通过,并不代表这些含义已经过评估。ARB、Android XML、Apple 消息目录和静态文档需要使用各自原生的验证方式,而非这项专用于 React 的覆盖检查。

处理差异,保留已审核的输出 #

使用 lingo extract 重新生成过时的输出,检查新增条目和已失去源消息关联的条目,并翻译所需的增量内容。保留已审核的目标文案和本地化锁。删除已失去源消息关联的条目会改变消息目录,应与源消息变更分开审核。

确定翻译是直接进入源代码分支,还是通过单独的翻译 PR 交付。CI 指南介绍了不同交付方式的取舍,以及托管应用的差异。无论采用哪种方式,都应将合并权限与运行权限、内容验收分开。

最后,使用有代表性的值,以目标语言区域加载变更后的界面。打开富文本链接,检查回退行为,并对照显示的消息与预期操作。只有程序中的消息链路和文案都经过检查,审核才算完成。