Buildkite 配置方案

在 Buildkite 流水线中翻译文件,将结果推送回分支,并让翻译未更新的拉取请求无法通过检查。

Buildkite 步骤可在你自己的代理上通过 Lingo.dev CLI 翻译仓库文件。CLI 会提交 Lingo.dev 配置所选的源文件,并将翻译后的文件写入 checkout;如何交付这些文件,由你的流水线决定。Buildkite 负责管理代理、密钥和仓库访问;Lingo.dev 则通过本地化引擎处理文件。

这是一套 CI 配置方案,而非原生 Buildkite 连接。先在默认分支或拉取请求构建中添加一个翻译步骤,再检查它生成的首个提交。仅在下方表格表明检查关卡适用时,添加拉取请求检查。

准备仓库和代理 #

在本地完成 CLI 快速入门。提交 .lingo/config.json、已确认接受的目标文件和 .lingo/lock.json。配置用于选择源语言区域、目标语言区域、文件匹配模式和本地化引擎。示例以 locales/en.json 为源文件,并使用 locales/es.json 处已有的西班牙语目标文件。如果有更多目标文件,请对每个目标文件分别运行一次 test -s 和 JSON 检查,并在其他指定 locales/es.json 的命令中列出所有目标路径,或暂存整个目标目录,例如 locales/。Lockfile 会将源文件记录为已翻译,因此后续推送会跳过它;未纳入提交的目标文件则仍未更新。

采用定期运行的步骤前,先用 lingo push --backfill-missing --wait 创建缺失的目标文件。后续修改源文件时,使用常规的 lingo push --wait。补全缺失文件不会修复已有目标文件中缺失的键。

代理需要安装 Node.js、npm 和 Git,并能通过网络访问 npm 注册表和 Lingo.dev。代理用于 checkout 的仓库凭据(例如部署密钥)还必须允许向该步骤写入的分支推送。

将 Lingo.dev API 密钥保存为名为 LINGO_API_KEY 的 Buildkite 密钥。CLI 只读取这个名称;旧版 CLI 使用的 LINGODOTDEV_API_KEY 变量会被忽略,因此请将其重命名。仅在执行翻译的步骤中加载密钥。该步骤的 secrets: 键要求使用 Buildkite 代理 3.106.0 或更高版本,且代理必须在存有该密钥的集群中运行;更早版本的代理会导致流水线失败。对于旧版代理或未加入集群的代理,请移除 secrets:,改为通过代理的 environment 钩子或密钥插件,为该步骤导出 LINGO_API_KEY。

在流水线的 GitHub 设置中,保持允许来自第三方派生仓库的构建处于关闭状态。派生仓库的拉取请求会使用其自身的 pipeline.yml 进行构建,其中可以添加读取密钥的步骤,而你文件中的任何 if: 都无法阻止这种行为。同时为密钥添加访问策略,确保只有此流水线的构建可以读取它。

示例将 CLI 版本固定为 1.21.0。从 CLI 1.20.0 起,lingo check 可用于检查翻译文件。如需通过项目依赖项和 Lockfile 管理版本,请参阅 CI 设置指南。

翻译并推送回分支 #

此步骤会翻译进入默认分支的每次更改,并将结果推送到同一分支。它假定初始补全结果已提交,且引擎的人工审核已关闭,因此翻译能在一个步骤中完成。将其添加到 .buildkite/pipeline.yml:

yaml
steps:
  - label: "Translate"
    if: build.branch == pipeline.default_branch && build.pull_request.id == null
    concurrency: 1
    concurrency_group: "lingo-translations"
    # secrets: needs Buildkite agent 3.106.0 or later.
    secrets:
      - LINGO_API_KEY
    command: |
      # Replace 1.21.0 with the current CLI version.
      npx -y @lingo.dev/cli@1.21.0 push --wait
      test -s locales/es.json
      node -e 'JSON.parse(require("node:fs").readFileSync("locales/es.json", "utf8"))'
      git add -- locales/es.json .lingo/lock.json
      if git diff --cached --quiet; then exit 0; fi
      git config user.name "Localization bot"
      git config user.email "localization@example.com"
      git commit -m "[skip ci] Update translations"
      git push origin "HEAD:refs/heads/$${BUILDKITE_BRANCH}"

--wait 会让该步骤等待运行完成,并将翻译后的文件写入 checkout。没有它,lingo push 只会提交运行并退出,因此该步骤找不到可提交的内容。当某个目标失败时,lingo push --wait 会以非零状态退出,让步骤在提交前停止。如果没有更改,它会输出“没有内容可推送”,暂存区的差异为空,步骤便会退出,不创建提交。

Buildkite 对单个提交而非分支执行 checkout,因此推送时需要指定分支。$$ 会保留 BUILDKITE_BRANCH,供 shell 在步骤运行时展开;如果只使用一个 $,Buildkite 就会在上传流水线时将分支名称写入命令文本。concurrency 和 concurrency_group 确保每次只运行一个翻译任务。如果分支在翻译期间发生变化,Git 会拒绝推送;较新提交的构建会负责翻译该提交。

此步骤不会循环运行。对于提交消息中包含 [skip ci] 的提交,Buildkite 会跳过构建。即使没有它,下一次构建也会发现没有内容可推送,因为已提交的 .lingo/lock.json 已记录新的源内容。

直接推送到默认分支会跳过翻译拉取请求的审核,因此请在制定分支策略时慎重选择。如果希望先审核翻译,请改为推送到单独的分支,例如 lingo/translations,再使用 Git 提供商的工具创建拉取请求。

在拉取请求构建中翻译 #

如需在每个拉取请求自身的分支上翻译其源内容更改,请用此步骤替代默认分支步骤。两者的前提条件相同。其中的 if: 会跳过来自派生仓库的拉取请求,因为该步骤无法向派生仓库的分支推送。

此步骤需要在流水线的 GitHub 设置中配置两个选项。开启打开或更新拉取请求时构建。关闭构建分支,或将其限制为默认分支。启用分支构建后,向拉取请求分支推送可能会启动不含拉取请求详情的构建。此步骤会跳过该构建,因此既不会执行翻译,也不会失败。

if: 无法保护 LINGO_API_KEY。Buildkite 会从拉取请求自身的 pipeline.yml 中读取它,而派生仓库可以修改该文件,因此必须按照设置说明,始终关闭派生仓库构建。来自仓库内部分支的拉取请求也可以修改该文件,因此任何能向分支推送的人都可以通过此步骤读取密钥。仅当所有拥有推送权限的人都可以持有该密钥时,才使用此步骤。

yaml
steps:
  - label: "Translate pull request"
    if: build.pull_request.id != null && build.pull_request.repository.fork != true
    # secrets: needs Buildkite agent 3.106.0 or later.
    secrets:
      - LINGO_API_KEY
    command: |
      # Replace 1.21.0 with the current CLI version.
      npx -y @lingo.dev/cli@1.21.0 push --wait
      test -s locales/es.json
      node -e 'JSON.parse(require("node:fs").readFileSync("locales/es.json", "utf8"))'
      git add -- locales/es.json .lingo/lock.json
      if git diff --cached --quiet; then exit 0; fi
      git config user.name "Localization bot"
      git config user.email "localization@example.com"
      git commit -m "Update translations"
      git push origin "HEAD:refs/heads/$${BUILDKITE_BRANCH}"

提交消息中刻意不包含 [skip ci]。Buildkite 会构建翻译提交;该步骤再次运行时,会发现没有内容可推送,随后退出,不创建提交,因此循环会在额外构建一次后结束。这次构建会为拉取请求的最新提交提供状态。如果添加 [skip ci],最新提交就不会触发 Buildkite 构建,必需的 Buildkite 状态检查便会阻止合并。

代理的 checkout 凭据必须允许向拉取请求分支推送。如果分支在翻译期间发生变化,Git 会拒绝推送,步骤也会失败;较新提交的构建会负责翻译该提交。因此,短时间内连续推送两次会启动两次翻译,且两次都会计费。在流水线设置中开启 取消中间构建,让较新的推送取消较旧的构建。较旧构建已提交的翻译不会被取消。

让翻译未更新的拉取请求无法通过检查 #

lingo check 会将每个已配置的源文件与 .lingo/lock.json 比较,并要求所有目标文件都存在。如果源文件自上次翻译后发生了更改、源文件没有对应的 Lockfile 条目、目标文件缺失,或没有源文件匹配 files 模式,它会以状态码 1 退出。它不需要 API 密钥或其他密钥,也不会写入任何内容。除了可通过 DO_NOT_TRACK=1 关闭的 CLI 遥测,它不会发起网络调用;不过,npx 示例仍会在运行检查前从 npm 下载 CLI。它取代了旧版 CLI 的 --frozen 检查关卡。

它检查文件,而非键:手动编辑过的目标文件会通过检查,已有目标文件中缺失的键也不会被报告,React .jsonc 目录中的键除外。没有 .lingo/lock.json,它就无法检测源文件的更改,因此已更改或从未推送过的源文件不会导致检查失败,它会在标准错误输出中说明这一点。请提交 lingo push 写入的 Lockfile。

当下表表明检查关卡适用时,将此步骤添加到 .buildkite/pipeline.yml。它适用于未采用上述两个翻译步骤中任何一个的配置,因此这里的每个示例都提供了对应配置的完整 steps: 列表;请将其中的步骤合并到现有的 steps: 列表中,而不是添加第二个 steps: 键:

yaml
steps:
  - label: "Check translations"
    if: build.pull_request.id != null
    command:
      # lingo check needs CLI 1.20.0 or newer.
      - npx -y @lingo.dev/cli@1.21.0 check

此检查关卡适用于翻译结果与源内容更改一同提交的配置:

翻译运行位置是否对每个拉取请求启用检查关卡
开发者在创建拉取请求前运行 lingo push --wait 并提交结果是。源内容已更改但未翻译的拉取请求无法通过检查。
翻译步骤在合并后推送到默认分支否。按照这一流程的设计,功能拉取请求会先更改源内容,再进行翻译。
拉取请求步骤将结果提交到拉取请求分支否。在执行翻译的构建中,检查看到的是翻译前的提交,因此会失败。该步骤在翻译提交上自行重新运行时,会发现没有内容可推送,这表明源内容自 .lingo/lock.json 以来未发生更改。

源内容的哈希值按字节精确计算。请确保运行 lingo push 的 checkout 与 CI checkout 使用相同的行尾格式,例如在 .gitattributes 中配置 * text=auto eol=lf。

调整步骤 #

对于单体仓库,请从包含 .lingo/config.json 的软件包目录运行 CLI,例如在命令开头使用 cd apps/web,并暂存该软件包的目标文件和 Lockfile。独立软件包各自维护单独的 Lockfile,也可以使用不同的本地化引擎。

如果本地化引擎将任务交给人工审核,lingo push --wait 会仅写入已完成的文件,然后以状态码 0 退出。不要将这部分结果作为完整结果提交。请添加 CI 运行状态保留流程,并在审核完成后,在同一代理上通过 拉取获取其余文件。

恢复运行与停用步骤 #

根据错误确定下一步操作:修复软件包安装、提供密钥、完成审核、解决拉取冲突,或在排除原因后重试失败的目标任务。确保非零退出状态清晰可见;|| true 会掩盖失败原因。

移除该步骤或其触发器,以停止新的构建。取消构建时,请单独检查已提交的翻译。停用此配置方案时,请移除 LINGO_API_KEY 密钥,并撤销代理的写入权限。