Bitbucket Pipelines 配置示例
在 Bitbucket Pipelines 中运行文件翻译,将结果提交回仓库,并阻止翻译未更新的拉取请求通过检查。
使用 Bitbucket 流水线翻译 Lingo.dev 配置中选定的源文件。CLI 负责提交任务并下载目标文件,流水线则决定如何保留和交付这些文件。本示例从手动触发的自定义流水线开始,让你先检查一次翻译结果,再安排定期运行。
连接通过运行器的 API 调用建立,而不是通过原生 Bitbucket 账户连接器。写入仓库和创建拉取请求需要另外授予 Bitbucket 权限。
准备一个可用的翻译目录 #
先在本地按照 CLI 快速入门完成操作,再提交 .lingo/config.json、检查后的目标文件和 .lingo/lock.json。源语言区域、目标语言区域、本地化引擎和文件匹配模式都应在该配置中设置。
此示例使用 locales/en.json,并以 locales/es.json 处已有的西班牙语文件作为唯一目标文件。如果有多个目标文件,请对每个目标文件分别运行一次 test -s 和 JSON 检查,并在其他指定 locales/es.json 的命令中列出所有目标路径。Lockfile 会将源文件标记为已翻译,因此后续推送会跳过该源文件,未包含在构建产物中的目标文件也就无法更新。在采用下方用于持续处理源文件变更的命令前,请先用 lingo push --backfill-missing --wait 创建缺失的目标文件。常规推送会处理后续的源文件修改;补全缺失文件并不会补齐已有目标文件中缺失的键。
将 LINGO_API_KEY 保存为受保护的仓库变量。CLI 只读取这个名称;旧版 CLI 的 LINGODOTDEV_API_KEY 变量会被忽略,因此请将其重命名。仅对可信代码运行流水线,并在涉及凭据的操作中关闭 shell 跟踪。将变量设为受保护,并不意味着可以安全地将其暴露给拉取请求中的任意脚本。
示例固定使用 CLI 1.21.0。自 CLI 1.20.0 起,lingo check 可用于检查翻译文件。如需通过项目依赖项和 Lockfile 管理版本,请参阅 CI 设置指南。
翻译并保留结果 #
将这条自定义流水线添加到 bitbucket-pipelines.yml:
image: node:22
pipelines:
custom:
translate-catalog:
- step:
name: Translate and inspect
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:
- locales/es.json
- .lingo/lock.json确保运行器能够从 npm 下载 CLI,并根据你的配置调整文件路径。
核对已提交的 .lingo/config.json 中的组织 ID 和引擎 ID。提交一处小幅英文源文件修改,并在该可信分支上运行 translate-catalog。检查运行结果和差异,再下载构建产物,对照源文件版本查看修改后的西班牙语条目。通过应用加载翻译目录,检查变量和渲染效果。
文件存在性检查和 JSON 解析可以发现输出缺失或格式错误,但无法区分旧的有效文件和此次请求的新翻译。如果本地化引擎要求人工审核,请先完成审核并获取已完成的输出,再接受该构建产物。
保留提交和获取状态 #
推送默认异步执行。push --wait 会等待运行完成,再将翻译后的文件写入 checkout。未使用 --wait 时,lingo push 只会提交运行任务,随后退出,因此下一条命令找不到可保留或提交的新文件。需要等待人工审核时,仍可能需要稍后再执行获取步骤。
在等待审核或将获取结果拆分为单独步骤之前,请加入 CI 运行状态保留流程。提交后,导出此次运行的特定指针和原始项目根目录的绝对路径,即使后续验证失败也要导出。将 .lingo-ci/run.json、.lingo-ci/project-root.txt、.lingo/config.json、locales/en.json、目标文件和 Lockfile 保存为访问受限的构建产物,并设置足够长的保留期限,以便完成审核。确保原始步骤的失败状态仍然可见,切勿归档整个 ~/.lingo 或凭据。
获取结果时,在记录的绝对根路径下恢复同一版本和保留的文件状态。仅恢复该指针,单独提供凭据,并在收集结果前使用带有 --dry-run 的 拉取操作。如果后续流水线步骤无法重建该路径,请改用持久化且已授权的运行器来完成提交和获取。谨慎处理本地输出冲突;强制拉取可能会丢弃审核者的修改。
选择输出交付到仓库的方式 #
如果需要由人员或后续发布任务在交付前检查输出,保留构建产物即可。请将同一次已完成操作生成的翻译文件和 Lockfile 一起保留。
如需在审核后更新仓库,请先推送到翻译分支,再在 Bitbucket 中或通过其文档所述的 API 创建拉取请求。如下一节所示,步骤可以通过默认的 origin 推送回自身所在的仓库,无需额外凭据。仅在分支权限阻止推送,或需要通过 API 创建拉取请求时,才添加仓库 SSH 密钥或访问令牌;通过 API 创建拉取请求需要拉取请求写入权限。配置团队的机器人身份,仅暂存已知的目标路径和 .lingo/lock.json,并在暂存区没有差异时退出。使用不同的分支名称,或有计划地复用分支,避免并发运行相互覆盖。
直接提交采用相同的输出检查和暂存范围限制,但会推送到明确指定的可信分支。直接交付到默认分支会省去翻译拉取请求的审核步骤,因此必须是有意做出的分支策略选择。无论采用哪种方式,都应审核最终的应用输出。
将 Lingo.dev API 密钥与仓库凭据分开保存。它应放在翻译进程的环境中,绝不能出现在 Git 远程地址、已提交的文件或输出构建产物中。暂存时指定明确路径,而不要使用 git add .,以免一并收集运行器上的无关文件。
将翻译提交回分支 #
此分支流水线会翻译进入 main 的每次更改,并将结果提交到 main。前提是初始补齐的翻译已提交,且引擎的人工审核已关闭,这样翻译就能在一个步骤内完成。将其 branches 部分添加到与自定义流水线相同的 pipelines 键下。完整文件如下:
image: node:22
pipelines:
custom:
translate-catalog:
- step:
name: Translate and inspect
script:
- 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:
- locales/es.json
- .lingo/lock.json
branches:
main:
- step:
name: Translate and commit
auth:
system:
scopes:
- read:git:bitbucket
- write:git:bitbucket
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 "[skip ci] Update translations"
- git push origin "HEAD:$BITBUCKET_BRANCH"任一目标失败时,lingo push --wait 都会以非零状态码退出,因此该步骤会在提交前停止。如果没有任何更改,它会输出“没有可推送的内容”,暂存区没有差异,该步骤便会退出,不创建提交。
Pipelines 会设置 origin 远程仓库,让步骤无需额外凭据即可将更改推送回自身所在的仓库。步骤中的 auth 配置块 会授予其内置令牌 Git 推送权限。从 2027 年 4 月 30 日起,Bitbucket 将不再向未配置 auth 块的步骤授予该权限。自托管运行器需升级至 6.1.0 或更高版本才能使用 auth。如果 main 上的分支限制阻止了推送,请在该限制的 Pipelines 写入权限设置中,将 main 添加为源分支;或按照 Bitbucket 的回推指南,为该步骤提供具有写入权限的 SSH 密钥或访问令牌。
该步骤不会循环执行。提交消息中的 [skip ci] 会阻止 Bitbucket 为翻译提交启动流水线。未添加它时,下一次运行也会发现没有可推送的内容,因为已提交的 .lingo/lock.json 已记录新的源内容。如果分支在翻译期间发生变动,Git 会拒绝推送;较新提交的流水线会负责翻译该提交。
调整触发条件和包路径 #
先确定哪些源代码可以访问凭据、哪些分支可以接收写入,再添加自动分支或拉取请求触发器。派生仓库可能没有机密变量或可写入的目标;不要为了绕过这一问题,用高权限凭据运行其中不可信的代码。
自动生成的提交不应无限触发翻译。选择相关的源文件路径和可信分支,为自动生成的提交设置合适的规则,并保留无变更时退出的逻辑。源文件未变更时,没有差异是正常情况。
如果配置位于 apps/web/.lingo/config.json,请从 apps/web 运行 CLI。流水线的构建产物路径仍遵循 Bitbucket 的仓库相对路径规则,因此应使用 apps/web/locales/es.json 和 apps/web/.lingo/lock.json 等路径。更改 CLI 工作目录不会改变构建产物的路径约定。
阻止翻译未更新的拉取请求通过检查 #
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。
此检查关卡适用于未使用上述分支流水线的配置,下表说明了原因。在 pipelines 下添加 pull-requests 部分;如果保留手动流水线,请将其放在 custom 旁边。单独使用此检查关卡时,文件如下:
image: node:22
pipelines:
pull-requests:
"**":
- step:
name: Check translations
script:
# lingo check needs CLI 1.20.0 or newer.
- npx -y @lingo.dev/cli@1.21.0 check此检查关卡适用于将翻译与源文件更改一起提交的配置:
| 翻译在哪里运行 | 是否检查每个拉取请求 |
|---|---|
开发者运行 lingo push --wait,并在创建拉取请求前提交结果 | 是。源文件已更改但未更新翻译的拉取请求无法通过检查。 |
分支流水线在合并后提交到 main | 否。按照此流程的设计,功能拉取请求先更改源文件,再进行翻译。 |
源文件哈希按字节精确计算。请确保运行 lingo push 的 checkout 与 CI checkout 使用相同的换行符,例如在 .gitattributes 中设置 * text=auto eol=lf。同时也要保留应用的资源检查。
恢复缺失的输出或停止任务 #
如果输出缺失,请检查所选源文件、基线、目标覆盖情况、安全变量的可用性、审核状态以及报告的失败。在决定再次提交之前,先恢复已记录的运行。为现有项目补全缺失的目标文件前,先完成现有目标文件的常规更新,获取并检查结果,再在整个补全过程中保持源文件版本不变。请按照 添加语言中的顺序操作。只有在确实要替换所选的已接受文本时,才使用强制重新生成;失败运行恢复说明了如何在不强制替换的情况下请求重试。
禁用流水线触发器可停止新任务。取消运行器时,请单独检查服务器上已提交的运行。停用此配置方案时,请移除不再使用的 API 变量和提供方写入权限。