Buildkite recipe
Translate files in a Buildkite pipeline, push the output back to the branch, and fail pull requests whose translations are out of date.
A Buildkite step can translate repository files with the Lingo.dev CLI on your own agents. The CLI submits the source files selected by your Lingo.dev configuration and writes the translated files into the checkout; your pipeline decides how to deliver them. Buildkite owns the agents, secrets, and repository access; Lingo.dev processes the files through a localization engine.
This is a CI recipe, not a native Buildkite connection. Start with one translation step, on the default branch or on pull request builds, and inspect its first commit. Add the pull-request check only where its table says the gate fits.
Prepare the repository and agent #
Complete the CLI quickstart locally. Commit .lingo/config.json, accepted target files, and .lingo/lock.json. The configuration selects the source locale, target locales, file patterns, and localization engine. The examples use locales/en.json as the source and an existing Spanish target at locales/es.json. With more targets, run the test -s and JSON checks once for each target file, and list every target path in the other commands that name locales/es.json, or stage the whole target directory, such as locales/. The lockfile records the source as translated, so a later push skips it, and a target left out of the commit stays stale.
Create missing target files with lingo push --backfill-missing --wait before adopting the recurring step. Use ordinary lingo push --wait for later source edits. Missing-file backfill does not repair missing keys in an existing target.
The agent needs Node.js, npm, and Git, and network access to the npm registry and Lingo.dev. The repository credential the agent uses for checkout, such as a deploy key, must also allow pushes to the branch the step writes.
Store the Lingo.dev API key as a Buildkite secret named LINGO_API_KEY. The CLI reads only this name; a LINGODOTDEV_API_KEY variable from the previous CLI is ignored, so rename it. Load the secret only in the step that translates. The step's secrets: key needs Buildkite agent 3.106.0 or later, running in the cluster that holds the secret; earlier agents fail the pipeline. On older or unclustered agents, remove secrets: and export LINGO_API_KEY for that step from an agent environment hook or your secrets plugin instead.
Keep Allow builds from third-party forked repositories off in the pipeline's GitHub settings. A fork's pull request builds with the fork's own pipeline.yml, which can add a step that reads the secret, and no if: in your file can stop it. Add an access policy to the secret as well, so that only this pipeline's builds can read it.
The examples pin CLI 1.21.0. lingo check checks translation files from CLI 1.20.0 on. To manage the version through your project's dependencies and lockfile, follow the CI setup guide.
Translate and push back to the branch #
This step translates each change that reaches the default branch and pushes the result to the same branch. It assumes the initial backfill is committed and the engine's Human review is off, so translation finishes in one step. Add it to .buildkite/pipeline.yml:
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 makes the step wait for the run and write the translated files into the checkout. Without it, lingo push only submits the run and exits, so the step finds nothing to commit. lingo push --wait exits non-zero when a target fails, so the step stops before the commit. When nothing changed, it prints "Nothing to push", the staged diff is empty, and the step exits without a commit.
Buildkite checks out a single commit rather than a branch, so the push names the branch. $$ leaves BUILDKITE_BRANCH for the shell to expand when the step runs; with a single $, Buildkite would write the branch name into the command text when it uploads the pipeline. concurrency and concurrency_group run one translation at a time. If the branch moved during translation, Git rejects the push; the build for the newer commit translates it.
The step does not loop. Buildkite skips builds for commits whose message contains [skip ci]. Without it, the next build would find nothing to push, because the committed .lingo/lock.json already records the new source.
Pushing straight to the default branch removes the review of a translation pull request, so make it a deliberate branch-policy choice. To review translations first, push to a separate branch such as lingo/translations instead and open a pull request with your Git provider's tooling.
Translate on pull request builds #
To translate each pull request's source changes on its own branch, use this step instead of the default-branch one. It makes the same assumptions as that step. Its if: skips pull requests from forks, because the step cannot push to a fork's branch.
The step needs two settings in the pipeline's GitHub settings. Turn on Build when pull request is opened or updated. Turn Build branches off, or limit it to the default branch. With branch builds on, a push to a pull request branch can start a build without pull request details. The step skips that build, so nothing is translated and nothing fails.
The if: does not protect LINGO_API_KEY. Buildkite reads it from the pull request's own pipeline.yml, and a fork can change that file, so fork builds must stay off, as the setup says. A pull request from a branch in the repository can change the file too, so anyone who can push a branch can read the key through this step. Use the step only where everyone with push access may hold the key.
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}"The commit message has no [skip ci], on purpose. Buildkite builds the translation commit, the step runs again, finds nothing to push, and exits without a commit, so the loop ends after one extra build. That build gives the pull request's newest commit a status. With [skip ci], the newest commit would get no Buildkite build, and a required Buildkite status check would block the merge.
The agent's checkout credential must allow pushes to pull request branches. If the branch moved during translation, Git rejects the push and the step fails; the build for the newer commit translates it. So two quick pushes start two translations, and both are billed. Turn on Cancel Intermediate Builds in the pipeline settings, so a newer push cancels the older build. A translation the older build already submitted is not cancelled.
Fail pull requests with out-of-date translations #
lingo check compares each configured source with .lingo/lock.json and requires every target file. It exits 1 when a source changed since its last translation, a source has no lockfile entry, a target file is missing, or no source file matches the files patterns. It needs no API key or secret and writes nothing. Apart from CLI telemetry, which DO_NOT_TRACK=1 turns off, it makes no network call; the npx example still downloads the CLI from npm before the check runs. It replaces the --frozen gate of the previous CLI.
It checks files, not keys: a target edited by hand passes, and a key missing inside an existing target is not reported, except inside React .jsonc catalogs. Without .lingo/lock.json it cannot see source changes, so a changed or never-pushed source does not fail it, and it says so on stderr. Commit the lockfile that lingo push writes.
Add this step to .buildkite/pipeline.yml when the table below says the gate fits. It belongs to a setup without either translation step above, so each example here is a whole steps: list for one setup; merge its step into your existing steps: list rather than adding a second steps: key:
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 checkThe gate fits a setup where translations are committed together with the source change:
| Where translation runs | Gate on every pull request |
|---|---|
Developers run lingo push --wait and commit the result before opening the pull request | Yes. It fails a pull request whose source changed without translation. |
| The translation step pushes to the default branch after the merge | No. Feature pull requests change sources before translation by design. |
| The pull-request step commits to the pull request branch | No. In the build that translates, the check sees the commit before translation and fails. The step's own rerun on the translation commit, which finds nothing to push, shows that no source changed since .lingo/lock.json. |
Source hashes are byte-exact. Make the checkout that ran lingo push and the CI checkout use the same line endings, for example with * text=auto eol=lf in .gitattributes.
Adapt the step #
For a monorepo, run the CLI from the package that holds .lingo/config.json, for example with cd apps/web at the start of the command, and stage that package's target files and lockfile. Independent packages keep separate lockfiles and can use different localization engines.
If the localization engine sends work to human review, lingo push --wait exits 0 after writing only the finished files. Do not commit that partial result as complete. Add the CI run-state preservation procedure and retrieve the rest with Pull on the same agent once review finishes.
Recover and retire the step #
Use the error to identify the next action: repair package installation, supply the secret, complete review, resolve a pull conflict, or retry failed target work after correcting its cause. Keep nonzero exits visible; || true hides the cause.
Remove the step or its trigger to stop new builds. Inspect any already-submitted translation separately when cancelling a build. Remove the LINGO_API_KEY secret and the agent's write access when retiring the recipe.