GitLab CI 配置方案
在受信任的 GitLab 流水线中翻译文件,通过合并请求交付翻译结果,并让翻译过期的合并请求无法通过检查。
GitLab 运行器可以使用 Lingo.dev CLI 翻译仓库文件,并将结果保存为作业产物。这样,翻译就能与应用的其他部分共用同一套 checkout、检查和发布流程。GitLab 负责执行流水线并将结果交付到仓库;Lingo.dev 则通过本地化引擎处理选定的源文件。
这是一套 CI 配置方案,并非原生的 GitLab 账户连接。请先在默认分支上手动启动流水线,检查结果后,再添加定期触发和通过合并请求交付的机制。
准备源文件和凭据 #
在本地完成 CLI 快速开始。提交 .lingo/config.json、已确认的目标文件和 .lingo/lock.json。配置决定了源语言区域、目标语言区域、文件匹配模式和本地化引擎。请在该配置所在的目录中运行 CLI。
使用 lingo push --backfill-missing --wait 创建缺失的目标文件。后续修改源文件时,使用常规的 lingo push --wait 即可。仅更改本地化引擎的指令,并不会重写已确认的文件;主动重新生成文件需要单独执行。
在项目的 CI/CD 变量设置中,将 LINGO_API_KEY 保存为掩码变量。CLI 只读取这一名称,旧版 CLI 的 LINGODOTDEV_API_KEY 变量会被忽略,请将其重命名。将该变量的使用范围限制在允许提交翻译任务的受信任分支或环境内。受保护的变量在未受保护的分支或合并请求中可能不可用;请改用已授权的分支,不要将变量暴露给不受信任的代码。
API 密钥用于授权翻译。只有在添加通过提交交付结果的步骤时,才需要具有仓库写入权限的 GitLab 凭据。
这些示例固定使用 CLI 1.21.0。从 CLI 1.20.0 起,lingo check 支持检查翻译文件。如需通过项目依赖和 Lockfile 管理版本,请参阅 CI 设置指南。
运行以产物为先的流水线 #
此 .gitlab-ci.yml 示例假定已将 locales/en.json 配置为源文件,且现有的西班牙语文件 locales/es.json 是唯一的目标文件。如果有多个目标文件,请为每个目标文件分别运行一次 test -s 和 JSON 检查,并在其他指定 locales/es.json 的命令中列出所有目标文件路径。Lockfile 会将源文件记录为已翻译,后续推送便会跳过该源文件;未纳入产物或提交的目标文件则仍会处于过期状态。此示例使用在默认分支上手动启动的流水线:
stages:
- translate
translate_catalog:
stage: translate
image: node:22
rules:
- if: '$CI_PIPELINE_SOURCE == "web" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
script:
# 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 diff -- locales/es.json .lingo/lock.json
artifacts:
paths:
- locales/es.json
- .lingo/lock.json--wait 会让作业等待运行完成,并将翻译后的文件写入 checkout。不使用它时,lingo push 只会提交运行并退出,后续步骤便找不到可供检查或提交的新文件。
确认运行器能够访问镜像注册表,并备好后续步骤所需的工具。例如,改用其他精简镜像时,可能需要先安装 Git,才能检查或提交差异。
确认已提交的 .lingo/config.json 中的组织 ID 和引擎 ID 正确。修改一处源内容,然后启动流水线。在日志中确认报告的运行状态和发生更改的目标条目。下载产物,将翻译与对应的源文件修订版本进行比较,并在应用中加载验证。仅检查文件是否存在以及 JSON 是否有效,无法判断内容是否最新、语义是否正确。
--wait 会下载已完成的输出,但如果配置了人工审核,任务可能仍在等待人工处理。在使用审核等待机制或单独的获取作业前,请添加 CI 运行状态保留流程。提交后,导出该次运行的具体指针和原始项目根目录的绝对路径。将 .lingo-ci/run.json、.lingo-ci/project-root.txt、.lingo/config.json、locales/en.json、目标文件和 Lockfile 保存到访问受限的作业产物中。在 artifacts 配置中设置 when: always,并预留足够的产物保留时间,以便完成审核。确保后续验证失败时仍会执行导出,同时不要掩盖原始错误。
完成审核后,在负责获取结果的运行器上,使用相同的根目录绝对路径恢复记录的修订版本和文件状态。只恢复该指针,另行完成身份验证,并在收集结果前使用 lingo pull --dry-run。如果运行器无法重建原始路径,请改用持久且已获授权的运行器执行这两个作业。切勿归档整个 ~/.lingo。仅仅提交成功或存在旧目标文件,并不意味着已有可发布的新文件。
将翻译提交到合并请求 #
此作业会翻译合并请求中的源内容更改,并将结果提交到同一分支。它假设初始补全结果已提交,且引擎的人工审核已关闭,因此翻译可以在一个作业中完成。
在 GitLab 18.4 或更高版本中,启用 设置 → CI/CD → 作业令牌权限 → 允许向仓库发送 Git 推送请求。此作业使用 GitLab 的内置令牌;启动作业的人必须具有向源分支推送的权限。请参阅 GitLab 作业令牌设置。
保持 LINGO_API_KEY 的掩码和保护设置。使用同一项目中的可信源分支和目标分支,为两个分支都启用保护,并在项目的 CI/CD 设置中启用 允许合并请求流水线访问受保护的变量和运行器。启动流水线的人还需要具有向目标分支推送或合并的权限。这些是 GitLab 对受保护变量的要求。
使用与第一个示例相同的源路径和目标路径。将此作业添加到 translate 阶段:
translate_merge_request:
stage: translate
image: node:22
resource_group: lingo-mr-$CI_MERGE_REQUEST_IID
rules:
- if: >-
$CI_PIPELINE_SOURCE == "merge_request_event" &&
$CI_MERGE_REQUEST_EVENT_TYPE == "detached" &&
$CI_MERGE_REQUEST_SOURCE_PROJECT_ID == $CI_MERGE_REQUEST_TARGET_PROJECT_ID
script:
# 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 "$CI_REPOSITORY_URL" "HEAD:refs/heads/$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME"resource_group 确保每个 MR 同时只运行一个翻译作业。该作业仅提交西班牙语目标文件和翻译 Lockfile。如果分支在翻译期间发生更改,Git 会拒绝推送;请为更新后的分支重新运行流水线。
CI_REPOSITORY_URL 提供作业令牌凭据。使用此令牌推送不会启动另一条流水线,因此请在提交步骤前添加应用的资源检查。在 MR 中审核翻译差异,并在合并前完成其余检查。
由于这次推送不会启动流水线,合并请求的最新提交也没有对应的流水线。如果项目要求流水线必须成功,GitLab 可能会阻止合并。此时,请在合并请求的流水线选项卡中选择运行流水线。作业会发现没有内容需要推送,不创建提交便退出;这条流水线则会为最新提交提供状态。
从默认分支创建翻译合并请求 #
此作业会翻译进入默认分支的每项更改,并创建包含翻译结果的合并请求。GitLab 的推送选项会在同一次 git push 中创建合并请求,无需调用 API 或使用额外工具。它与上面的作业有相同的前提:已提交初始补全翻译,且已关闭人工审核。
创建一个具有开发者角色和 write_repository 作用域的项目访问令牌,并将其保存为名为 GITLAB_PUSH_TOKEN 的 CI/CD 变量,同时设置为掩码变量和受保护变量。在 GitLab.com 上,使用项目访问令牌需要付费套餐。此处不使用 CI_JOB_TOKEN,因为 GitLab 不会为使用它进行的推送启动流水线。推送 URL 使用 CI_SERVER_FQDN,可保留自托管实例的非标准端口。CI_SERVER_FQDN 要求 GitLab 16.10 或更高版本;在较旧的自托管实例上,请改用 ${CI_SERVER_HOST}:${CI_SERVER_PORT}。
将此作业添加到 translate 阶段:
translate_default_branch:
stage: translate
image: node:22
resource_group: lingo-translations
rules:
- if: '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
script:
- git fetch --quiet "$CI_REPOSITORY_URL" "$CI_DEFAULT_BRANCH"
- if [ "$(git rev-parse FETCH_HEAD)" != "$CI_COMMIT_SHA" ]; then exit 0; fi
# 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 --force
-o ci.skip
-o merge_request.create
-o merge_request.target="$CI_DEFAULT_BRANCH"
-o merge_request.title="Update translations"
"https://oauth2:${GITLAB_PUSH_TOKEN}@${CI_SERVER_FQDN}/${CI_PROJECT_PATH}.git"
"HEAD:refs/heads/lingo/translations"只要有目标检查失败,lingo push --wait 就会以非零状态码退出,使作业在提交前停止。如果没有任何更改,它会输出“没有内容需要推送”,暂存区的差异为空,作业不创建提交便退出。
如果默认分支已推进到作业所基于的提交之后,前两行会停止该作业。resource_group 一次只运行一个作业,但在 GitLab 默认的 unordered 处理模式下,等待中的作业并没有固定的启动顺序。如果不做这项检查,较旧的作业可能最后运行,通过强制推送用旧翻译覆盖新翻译。最新提交对应的作业会翻译该提交,已过期的提交则不会再提交翻译任务。
此作业不会循环运行。它仅在推送到默认分支时运行,且只写入 lingo/translations。GitLab 文档指出,-o ci.skip 只影响分支流水线,不影响合并请求流水线;创建合并请求或向其源分支添加新提交时,都会运行合并请求流水线。因此,下面的检查关卡应在翻译合并请求上运行,请在首次运行时确认。合并该请求会再次启动作业,但作业会发现没有内容需要推送。
每次运行都会基于本次运行所对应的默认分支提交重新构建 lingo/translations,并强制推送,让尚未合并的合并请求显示最新的翻译差异。在该分支上手动编辑的内容会被下一次运行覆盖,请在合并后再进行这些编辑。合并请求尚未合并时,默认分支仍保留之前的 .lingo/lock.json,因此下一次运行会再次提交相同的源文件更改。如果后续提交撤销了该合并请求已翻译的所有源文件更改,下一次运行就会发现没有内容需要推送,并让包含过期翻译的合并请求保持打开状态;此时请关闭该请求,不要合并。
让翻译过期的合并请求无法通过检查 #
lingo check 会将每个已配置的源文件与 .lingo/lock.json 比较,并要求所有目标文件都存在。如果源文件自上次翻译后发生更改、源文件没有对应的 Lockfile 条目、目标文件缺失,或没有源文件匹配 files 模式,它就会以状态码 1 退出。它不需要 API 密钥或 CI/CD 变量,也不会写入任何内容,因此同样可以在来自分叉仓库的合并请求上运行。除了可通过 DO_NOT_TRACK=1 关闭的 CLI 遥测,它不会发起任何网络调用;不过,npx 示例仍会在运行检查前从 npm 下载 CLI。它取代了旧版 CLI 的 --frozen 检查关卡。
它检查文件,而不是键:手动编辑过的目标文件可以通过检查,现有目标文件中缺失的键也不会被报告,React .jsonc 消息目录除外。没有 .lingo/lock.json,它就无法识别源文件更改,因此已更改或从未推送过的源文件不会导致检查失败;检查会在标准错误输出中说明这一点。请提交 lingo push 写入的 Lockfile。
将 check 添加到 stages 列表中,再添加适合你当前配置的作业。如果开发者运行 lingo push --wait,并将结果与源文件更改一并提交,就应检查每个合并请求:
check_translations:
stage: check
image: node:22
rules:
- if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
script:
# lingo check needs CLI 1.20.0 or newer.
- npx -y @lingo.dev/cli@1.21.0 check使用默认分支作业时,只检查它创建的翻译合并请求,因为功能合并请求会在翻译前更改源文件:
check_translations:
stage: check
image: node:22
rules:
- if: '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME == "lingo/translations"'
script:
# lingo check needs CLI 1.20.0 or newer.
- npx -y @lingo.dev/cli@1.21.0 check此检查关卡适用于将翻译与源文件更改一并提交的配置:
| 翻译运行位置 | 是否检查每个合并请求 |
|---|---|
开发者在创建合并请求前运行 lingo push --wait 并提交结果 | 是。源文件已更改但未翻译的合并请求无法通过检查。 |
| 合并请求作业将结果提交到源分支 | 否。检查针对的是翻译前的提交,而作业的推送不会启动新流水线。 |
| 默认分支作业创建翻译合并请求 | 仅在 lingo/translations 上使用上述第二个作业进行检查。按设计,功能合并请求会在翻译前更改源文件。 |
源文件哈希精确到字节。请确保运行 lingo push 的 checkout 与 CI checkout 使用相同的换行符,例如在 .gitattributes 中使用 * text=auto eol=lf。
让定期任务更可控 #
将自动作业限定在指定的可信分支和源路径上。如果使用合并请求触发,还应限制源项目和目标分支。采用适当的分支规则或跳过 CI 的策略,并在没有差异时退出,避免生成的提交反复触发翻译任务。
对于单体仓库,请进入包含所需配置的包,并保留相对于该包的输出和状态。独立的包可以使用不同的本地化引擎和语言区域;请分别维护各自的 Lockfile。只要网络访问、运行器工具、变量和仓库策略支持,同样的运行器方案也适用于自托管 GitLab。
只要源内容保持不变,常规增量翻译就可以保留手动编辑的目标键内容。源内容发生更改后,该键的内容可能会重新生成。缺失文件补全与强制重新生成的作用范围不同。未指定文件匹配模式时,--force 会覆盖所有已配置的源语言区域和目标语言区域,并可能替换已确认的翻译。强制执行任务前,请明确指定匹配模式,并检查估算结果。更改提交命令时,请参阅 推送。
恢复和停用流水线 #
根据错误确定下一步操作:修复包安装、提供已获授权的变量、完成审核、解决合并冲突,或在排除原因后重试失败的目标任务。保留成功的产物,同时明确标示尚未全部完成的发布。
禁用触发器,停止启动新的流水线。取消运行器时,请单独检查已提交的翻译任务。停用此配置方案时,移除不再使用的 API 凭据和仓库凭据。