GitHub Actions CI 配置示例

在可信的 GitHub Actions 作业中运行翻译,检查产物,并在输出就绪后添加拉取请求交付步骤。

如果翻译需要沿用现有流水线的触发条件和检查机制,可以在 GitHub Actions 中运行 Lingo.dev CLI。运行器会读取仓库配置、提交源内容更改,并下载翻译后的文件。你可以决定将这些文件保留为产物,还是通过拉取请求交付。

本示例以手动触发和只读仓库访问权限为起点。检查一条已更改的消息后,你就可以添加创建翻译拉取请求所需的写入权限。原生 GitHub App 则提供托管式仓库处理,无需采用本示例中的运行器配置。

准备仓库 #

在本地使用一个源文件和一种目标语言,完成 CLI 快速入门。提交 .lingo/config.json、检查过的目标文件和 .lingo/lock.json。配置用于指定本地化引擎、源语言区域、目标语言区域和文件匹配模式。Lockfile 则记录基线,供后续源内容更改使用。

在下方示例中,将 locales/en.json 配置为源语言,将西班牙语配置为目标语言,生成 locales/es.json。首次缺失的目标文件使用 lingo push --backfill-missing --wait 创建;后续修改源内容时使用 lingo push --wait。回填只会选取缺失的目标文件,因此不能用来补齐现有文件中缺失的键。

将 LINGO_API_KEY 添加到仓库或环境的 Actions 密钥中。它用于授予 Lingo.dev 访问权限,与 GitHub 仓库权限相互独立。带有凭据的作业只能运行可信代码。尤其不要使用 pull_request_target 检出不可信拉取请求的头部提交,再使用该密钥执行其中的代码。

本示例固定了 CLI 版本。如需通过项目依赖项和 Lockfile 管理版本,请参阅 CI 设置指南。

获取翻译产物 #

将以下内容保存为 .github/workflows/translate.yml。本示例使用 Node.js 22。

yaml
name: Translate catalog
on:
  workflow_dispatch:
permissions:
  contents: read
jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - name: Translate and download
        # Replace 1.21.0 with the current CLI version.
        run: npx -y @lingo.dev/cli@1.21.0 push --wait
        env:
          LINGO_API_KEY: ${{ secrets.LINGO_API_KEY }}
      - name: Inspect expected output
        run: |
          test -s locales/es.json
          node -e 'JSON.parse(require("node:fs").readFileSync("locales/es.json", "utf8"))'
          git diff -- locales/es.json .lingo/lock.json
      - uses: actions/upload-artifact@v4
        with:
          name: translated-catalog
          include-hidden-files: true
          path: |
            locales/es.json
            .lingo/lock.json

核实已提交的 .lingo/config.json 中的组织 ID 和引擎 ID。修改一处英语源内容并提交,然后从该可信分支手动触发工作流。查看作业日志中的运行结果和差异,再下载产物,找到与此次修改对应的西班牙语条目。通过应用加载该条目,检查其含义和变量。

上传时会包含隐藏文件,以保留 .lingo/lock.json。请将上传路径列表限定为预期的目标文件和 Lockfile,不要扩大范围,以免包含凭据或其他私有隐藏文件。

Shell 检查用于确认文件是否存在、JSON 语法是否有效。旧的目标文件也可能通过这两项检查,因此必须检查发生更改的条目。如果本地化引擎要求人工审核,命令返回后,该次运行仍可能在等待人工处理。在一次性运行器上使用该策略前,请添加 CI 运行状态保存流程。提交后,导出该次运行的具体指针和项目根目录的原始绝对路径,并将 .lingo-ci/run.json、.lingo-ci/project-root.txt、.lingo/config.json、locales/en.json、目标文件和 Lockfile 上传为访问受限的产物。在导出和上传步骤中使用 if: always(),避免后续检查失败导致可恢复的状态丢失;如果缺少指针,应调查提交情况,而不是凭空构造指针。

审核完成后,在记录的绝对根路径下恢复完全相同的版本和文件状态,恢复指针,单独完成身份验证,然后使用带冲突检查的 拉取。如果其他运行器无法重建该路径,请改用持久且已获授权的运行器提交翻译并获取结果。不要将首个产物中的旧目标文件视为已完成的翻译。

push --wait 会等待并下载可用的已完成输出。不使用 --wait 时,推送通常会在提交后返回。将提交和结果获取拆分为两个作业时,也需要执行相同的运行状态导出与恢复流程;仅复制 Lockfile 并不足够。请将同一次已完成操作下载的目标文件和 Lockfile 一并保存,切勿归档整个 ~/.lingo。

通过拉取请求交付 #

产物检查通过后,授予作业 contents: write 和 pull-requests: write 权限。仓库策略也必须允许 Actions 创建拉取请求。GITHUB_TOKEN 用于授权这些 GitHub 操作;翻译仍使用 LINGO_API_KEY。

按照团队的机器人策略配置 Git 身份。然后在输出验证后添加一个步骤,仅暂存预期的目标文件和 Lockfile:

bash
git add locales/es.json .lingo/lock.json
git diff --cached --quiet && exit 0
branch="lingo/translations-${GITHUB_RUN_ID}"
git switch -c "$branch"
git commit -m "chore: update translations"
git push origin "$branch"
gh pr create --fill --base "$GITHUB_REF_NAME" --head "$branch"

GitHub 托管的运行器已包含 GitHub CLI。为此步骤提供来自 secrets.GITHUB_TOKEN 的 GH_TOKEN。这套操作假定工作流从可信分支手动触发,并使用新的分支名称;如果重新运行时分支已存在,就必须明确决定复用还是替换该分支。这不是向派生仓库回写的工作流。

拉取请求以触发作业的分支为目标分支。如果 GitHub 将其工作流标记为等待批准,拥有仓库写入权限的人员必须选择 批准工作流运行;请参阅 GitHub 的 GITHUB_TOKEN 行为说明。合并前,请审核翻译差异、检查结果和应用输出。

在合适的分支策略下,也可以直接提交到触发工作流的分支,但这样会省去单独的内容审核步骤,并且需要防止循环触发。

安排运行并处理单体仓库 #

首次运行得到有用结果后,添加可信的推送分支和源文件路径筛选条件。生成的翻译提交不得反复触发新的翻译作业。请结合使用合适的分支或路径筛选条件,以及交付步骤中的无更改退出机制。

在单体仓库中,将翻译步骤的工作目录设置为包含 .lingo/config.json 的包目录,并更新产物路径和暂存路径,使其包含该包目录。矩阵可以处理彼此独立的包,但应避免两个条目同时更新同一份配置和 Lockfile。同一次运行中的条目共享运行 ID,因此请为每个条目设置独立的产物名称和翻译分支,例如在 translated-catalog 和 lingo/translations-${GITHUB_RUN_ID} 中加入包名。

恢复未完成的运行 #

先查看报告的状态:失败的目标需要解决相应错误,等待审核的目标需要作出审核决定,本地拉取冲突则需要在本地修改和下载结果之间作出选择。保留成功的输出以供检查,同时让未完成的语言区域保持未解决状态。不要将部分结果当作完整的语言区域版本发布。

确保非零退出状态清晰可见。|| true、强制拉取并覆盖修改,或对所有目标强制处理,都可能掩盖原因并替换已接受的成果。CI 工作流指南 说明了如何在恢复过程中保留版本和基线。

禁用工作流或其触发器,停止创建新的运行器作业。如果作业已提交翻译,请在取消 Actions 作业时单独检查对应的服务器端运行。停用工作流时,移除不再使用的密钥和仓库写入权限。