在 CI 中自动化翻译
让翻译成为发布流程中可重复的一环:从确定的源代码修订版本出发,到检查译文文件、运行应用检查。
发布流水线本就将源代码修订版本与用户能用上的成果连在一起,翻译也应延续这种关联。任务需要知道哪些源内容发生了变化,获取对应的目标文件,并为下一步留下足够的依据,以便决定接受还是拒绝这些文件。
首次请求成功后,棘手的情况才会出现:审核者还在编辑,运行器突然失联,或旧版本的翻译尚未完成,源内容就有了新版本。本指南将介绍如何构建能应对这些情况的 CI 流程,避免发布过时文件,也避免不必要地覆盖已接受的修改。各平台专用的 YAML 配置可在 GitHub Actions、GitLab、Bitbucket 和 Buildkite 配置指南中找到。
确定翻译在哪个环节接入发布流程 #
如果托管式 GitHub App 的仓库工作流符合你的需求,直接使用即可。默认分支上的更改会生成翻译拉取请求;启用可选的拉取请求处理后,译文会写入该拉取请求所在的分支。运行审批负责授权翻译工作,内容审核与合并则在其后进行。
使用 CLI 运行器时,提交、获取和交付都由你的流水线负责。请选择与发布流程相匹配的目标位置:
| 目标位置 | 适用的决策方式 |
|---|---|
| 仅保存为产物 | 在更改仓库或发布内容之前,由另一个任务或人员检查输出。 |
| 翻译分支和拉取请求 | 在译文更改进入默认分支之前,对其单独审核。 |
| 源拉取请求所在分支 | 在同一次更改中同时审核源内容和译文。 |
| 直接提交到默认分支 | 在分支策略明确允许时,无需单独的翻译拉取请求即可交付。 |
涉及仓库写入时,同一翻译状态应只由一个活跃的写入方负责。否则,两个基于不同源代码修订版本的运行器可能会争相提交文件和 Lockfile。自动生成的提交还需要配合分支、路径或生成提交规则,避免反复触发翻译。
建立运行器将沿用的基线 #
启用定期运行之前,先在本地将一个源文件翻译成一种语言,并运行应用的资源检查。然后将配置、已接受的目标文件和 .lingo/lock.json 一并提交。在干净的 checkout 中,应能复现相同的源文件选择和目标文件布局。
服务提供商的示例固定使用 @lingo.dev/cli@1.21.0。设置工作流时,请将其替换为当前的 CLI 版本。如需通过项目依赖来管理 CLI,请使用 npm install --save-dev --save-exact @lingo.dev/cli@1.21.0 安装,并提交 package.json 和 package-lock.json。之后使用 npm ci 和 npx --no-install lingo 运行 Lockfile 中记录的版本。
.lingo/config.json 用于选择语言区域、文件匹配模式和本地化引擎。请在设置阶段配置好组织和本地化引擎的访问权限。如果任务需要初始化或关联项目,请使用 初始化 和 关联 参考文档中的显式选项,不要依赖无人值守环境中的交互提示。
在单体仓库中,运行 CLI 前请先进入包含目标配置的包目录。位置参数中的匹配模式只会缩小该配置所选源文件的范围,而不会选中其他包的配置。对于每个独立配置的包,请将其状态路径和产物路径集中管理。
请通过运行器的密钥机制注入 LINGO_API_KEY,无需交互式登录即可使用。带凭据的任务只应运行可信代码,因为分支可能篡改脚本来泄露密钥。任务能在哪里运行,应由受保护变量和派生仓库限制来决定,切勿为了让不可信任务跑通而移除这些限制。
提交正确类型的任务 #
如果是全新项目的首次翻译,直接请求生成缺失的目标文件即可。对于已有项目,请先为现有目标完成常规的源内容更新,获取并检查译文;然后在保持该源代码修订版本不变的前提下,添加缺失的语言区域并补全翻译。运行以下命令前,请先完成 添加语言 中的步骤:
lingo push --backfill-missing --wait针对相对于既定基线的源内容更改:
lingo push --wait首次普通推送可以只记录源内容状态而不进行翻译。补全操作负责生成缺失文件的任务;之后的普通推送则依据源内容更改来确定工作内容。限定范围的推送或补全推送,并不能通用地修复现有目标文件中缺失的键。
--wait 会等待运行结束,并下载已完成的输出;不使用该选项时,推送会在提交后立即返回。如果需要等待审核或单独执行获取任务,请遵循 CI 运行状态保留流程:在运行器退出前,保留主目录中特定的非机密本地指针、项目根目录的原始绝对路径,以及彼此匹配的源文件、配置、目标文件和 Lockfile 状态。在同一根目录下恢复这些内容,单独完成身份验证后,先使用 lingo pull --dry-run,再使用 lingo pull。如果运行器无法重建该路径,请改用持久化且已授权的 checkout。切勿归档凭据或整个 ~/.lingo。
请保留退出状态以及报告的各目标结果。当前 CLI 在报告目标失败时会以失败状态退出,但人工审核可能让运行停留在等待决定的状态。新版本等待期间,旧文件可能依然存在。务必先完成审核并获取结果,再允许交付任务发布。
具体命令行为请参阅 推送 和 拉取。--yes 会跳过强制重新生成的确认,但不会批准人工审核,也不会让所有待处理操作直接变为已完成。
CLI 在 CI 中会跳过更新检查。如有需要,可通过 LINGO_DISABLE_UPDATE_CHECK=1 和 LINGO_TELEMETRY_DISABLED=1 进行显式控制,且不会影响翻译通信。
确保下一步拿到的是可用文件 #
对照源代码修订版本,核对预期发生更改的条目。如果 checkout 中已有旧的目标文件,仅凭文件存在并不能说明问题。请保留同一次操作下载的输出和锁定状态,并将失败或仍在等待的语言区域明确标记为未完成。
接着,运行能够识别资源格式的检查:
- 对于 React 提取,请运行
lingo extract --check、lingo check、项目的 TypeScript 检查以及实际的应用构建。它们各自检验结果的不同方面。 - 对于原生资源,请运行平台的资源生成或编译流程。
- 对于静态内容,请解析翻译后的文档,并检查链接、变量以及需要保留的语法。
- 如需在翻译过时时让合并请求检查失败,请运行
lingo check,无需 API 密钥。
lingo check 以文件为单位工作:它会针对每个已配置的语言区域,报告源文件的更改和目标文件的缺失,但不会报告现有 Android、Apple、ARB 或 Markdoc 文件内部缺失的键。
在选定的验收流程中,还要检查译文的含义是否准确。构建可以发现格式错误的资源,却可能放过一句改变了关键条件的译文。检查和审核通过后,只提交或发布预期的输出路径。请保留无更改时的退出路径,并让必需检查的失败直接导致任务失败,而不是用无条件提交掩盖问题。
先恢复已记录的任务,再创建替代任务 #
任务中断后,请先恢复其运行标识和各目标结果。如果翻译已经完成,请先拉取该输出,再提交新的请求。如果等待期间本地目标文件有所改动,请在能看到已接受编辑的情况下解决拉取冲突;强制覆盖可能会丢掉工作流原本要保留的修正。
排查期间请保留 Lockfile。删除它会改变下次运行的源内容基线,可能让一次小范围的恢复变成另一项工作。请检查差异,只重试仍未完成的部分。恢复中断的本地化运行 将进一步介绍如何做出这一判断。
在安排定期任务之前,除了成功场景,还应演练一次人工审核等待和一次获取中断。发布步骤应保留最近一次已接受的状态,并标出未完成的语言区域,而不是来者不拒地接受任何恰好存在的文件。