在代码审核中检查 React 本地化
结合消息提取、消息目录检查、TypeScript 检查和应用构建,在合并前发现不同类型的本地化缺陷。
React 消息的变更需要经过源代码、消息提取、目标消息目录和应用加载器,才能最终呈现给读者。审核文案时,也要一并检查这条链路。翻译即使正确,若关联的标识已过时,也不会显示;回退到源文本则可能在维持界面可用的同时,掩盖翻译缺失的问题。
此方法适用于当前的 React 包及通过 CLI 提取的 JSONC 消息目录。除 CLI 的提取检查外,还应运行项目自身的构建和渲染检查。
先检查源代码变更 #
先把新的源消息当作面向用户的指令或陈述来读,再看它的上下文。“按钮”描述的是形态;“在提交前取消已安排的付款”说明的是操作,而操作的含义必须在翻译中保留。源文本和上下文都会影响标识,因此,即使只修改上下文,也可能需要新增目标条目。
审核占位符时,要将其视为用途固定的值。译者应能调整人名或金额的位置,而不改变其标识。对于富文本,应将导航和组件行为保留在代码中,只翻译命名标签周围的句子。消息和富文本文档提供了具体的 API。
先检查提取,再检查目标内容 #
安装 CLI 后,在要检查的项目目录中运行:
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 指南介绍了不同交付方式的取舍,以及托管应用的差异。无论采用哪种方式,都应将合并权限与运行权限、内容验收分开。
最后,使用有代表性的值,以目标语言区域加载变更后的界面。打开富文本链接,检查回退行为,并对照显示的消息与预期操作。只有程序中的消息链路和文案都经过检查,审核才算完成。