Bitbucket Pipelines recipe
Run file translation in Bitbucket Pipelines, commit the output back, and fail pull requests whose translations are out of date.
Use a Bitbucket Pipeline to translate the source files selected by your Lingo.dev configuration. The CLI submits the work and downloads the target files; your Pipeline decides how to retain and deliver them. This recipe starts with a custom, manually invoked Pipeline so you can inspect one translation before scheduling recurring work.
The connection is your runner's API call, rather than a native Bitbucket account connector. Repository writes and pull-request creation use separate Bitbucket authority.
Prepare one working catalog #
Follow the CLI quickstart locally, then commit .lingo/config.json, the inspected target files, and .lingo/lock.json. Source and target locales, the localization engine, and file patterns belong in that configuration.
The example uses locales/en.json and an existing Spanish file at locales/es.json as its only target. 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. The lockfile records the source as translated, so a later push skips it, and a target left out of the artifact stays stale. Create missing target files with lingo push --backfill-missing --wait before adopting the recurring source-change command below. Ordinary push processes later source edits; missing-file backfill does not repair missing keys in an existing target.
Save LINGO_API_KEY as a secured repository variable. The CLI reads only this name; a LINGODOTDEV_API_KEY variable from the previous CLI is ignored, so rename it. Run the Pipeline on trusted code and keep shell tracing off around credentials. Securing a variable does not make it safe to expose to arbitrary scripts from a pull request.
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 retain the result #
Add this custom Pipeline to 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.jsonEnsure the runner can download the CLI from npm. Adapt the file paths to your configuration.
Verify the organization and engine IDs in the committed .lingo/config.json. Commit one small English source edit and run translate-catalog on that trusted branch. Inspect the run outcome and diff, then download the artifact and read the changed Spanish entry against the source revision. Load the catalog through the application to check variables and rendering.
File existence and JSON parsing catch missing or malformed output. They cannot distinguish an old, valid file from the new translation you requested. If the localization engine requires human review, finish review and retrieve completed output before accepting the artifact.
Preserve the submission and retrieval state #
Push is asynchronous by default. push --wait waits for the run and writes the translated files into the checkout. Without --wait, lingo push only submits the run and exits, so the next command finds no new files to retain or commit. Human-review waits can still require a later retrieval step.
Before a review wait or split retrieval step, add the CI run-state preservation procedure. Export the specific pointer and original absolute project root after submission, including when a subsequent validation fails. Retain .lingo-ci/run.json, .lingo-ci/project-root.txt, .lingo/config.json, locales/en.json, the target, and lockfile as restricted artifacts with enough retention for review. Keep the original step failure visible, and never archive all of ~/.lingo or credentials.
Restore the same revision and retained file state at the recorded absolute root for retrieval. Restore only that pointer, supply credentials separately, and use Pull with --dry-run before collecting. If a later Pipeline step cannot recreate the path, use a persistent authorized runner for both submission and retrieval instead. Resolve local output conflicts deliberately; forcing a pull can discard a reviewer's changes.
Choose how output reaches the repository #
An artifact is enough when a person or a later release job should inspect output before delivery. Retain translated files and the lockfile from the same completed operation together.
For a reviewed repository update, push to a translation branch, then open a pull request in Bitbucket or through its documented API. A step can push to its own repository over the default origin without another credential, as the next section shows. Add a repository SSH key or access token only when branch permissions block that push, or to create the pull request through the API, which needs pull-request write access. Configure the team's bot identity, stage only known target paths and .lingo/lock.json, and exit if the staged diff is empty. Use distinct branch names or deliberate branch reuse so concurrent runs do not overwrite each other.
A direct commit uses the same output checks and restricted staging but pushes to the explicitly intended trusted branch. Direct default-branch delivery removes the translation pull request's review step, so it must be an intentional branch-policy choice. Review the resulting application output in either model.
Keep the Lingo.dev API key separate from repository credentials. It belongs in the translation process environment, never in a Git remote, committed file, or output artifact. Stage explicit paths instead of git add . to avoid collecting unrelated runner files.
Commit translations back to the branch #
This branch Pipeline translates each change that reaches main and commits the result to main. It assumes the initial backfill is committed and the engine's Human review is off, so translation finishes in one step. Add its branches section under the same pipelines key as the custom Pipeline. The whole file is then:
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 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.
Pipelines sets the origin remote so a step can push back to its own repository without an extra credential. The step's auth block gives its built-in token Git push access. From April 30, 2027, Bitbucket no longer gives that access to steps without an auth block. Self-hosted runners need version 6.1.0 or later to use auth. If a branch restriction on main blocks the push, add main as a source branch under the restriction's Pipelines write access, or give the step an SSH key or access token with write access, as described in Bitbucket's push-back guide.
The step does not loop. [skip ci] in the commit message stops Bitbucket from starting a Pipeline for the translation commit. Without it, the next run would find nothing to push, because the committed .lingo/lock.json already records the new source. If the branch moved during translation, Git rejects the push; the Pipeline for the newer commit translates it.
Adapt triggers and package paths #
Add automatic branch or pull-request triggers only after deciding which source code can access credentials and which branch can receive writes. A fork may lack secrets or a writable destination; do not resolve that by running its untrusted code with privileged credentials.
Generated commits should not trigger translation indefinitely. Select relevant source paths and trusted branches, apply a suitable generated-commit rule, and retain the no-change exit. An unchanged source can legitimately produce no diff.
For a configuration at apps/web/.lingo/config.json, run the CLI from apps/web. Pipeline artifact paths still follow Bitbucket's repository-relative rules, so use paths such as apps/web/locales/es.json and apps/web/.lingo/lock.json. Changing the CLI working directory does not change the artifact path convention.
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 repository variable 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.
The gate belongs to a setup without the branch Pipeline above; the table below says why. Add a pull-requests section under pipelines, next to custom if you keep the manual Pipeline. On its own, the file is:
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 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 branch Pipeline commits to main after the merge | No. Feature pull requests change sources before translation by design. |
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. Keep the application's resource checks as well.
Recover missing output or stop work #
For missing output, inspect the selected source files, baseline, target coverage, secured-variable availability, review state, and reported failures. Recover the recorded run before choosing another submission. Before backfilling missing targets in an existing project, complete, retrieve, and inspect ordinary updates for its existing targets, then hold the source revision fixed through backfill. Follow Add a language for that sequence. Use forced regeneration only when replacing the selected accepted text is intended; failed-run recovery explains how to request another attempt without forcing replacement.
Disable the Pipeline trigger to stop new jobs. Inspect any already-submitted server run separately when cancelling the runner. Remove unused API variables and provider write access when retiring the recipe.