Automate translations in CI

Make translation a repeatable part of a release, from a known source revision to inspected files and application checks.

A release pipeline already connects a source revision to something people can use. Translation should preserve that connection. The job needs to know which source changed, retrieve the corresponding target files, and leave the next step enough evidence to accept or reject them.

The difficult cases appear after the first successful request: a reviewer is still editing, a runner disappears, or a newer source revision arrives before an older translation finishes. This guide develops a CI process that can handle those cases without publishing stale files or replacing accepted edits unnecessarily. Provider-specific YAML lives in the GitHub Actions, GitLab, Bitbucket, and Buildkite recipes.

Decide where translations join the release #

Use the managed GitHub App when its repository workflow fits. Default-branch changes produce a translation pull request; opt-in pull-request processing writes to that pull request's branch. Run approval authorizes translation work, while content review and merging happen afterward.

A CLI runner gives your pipeline responsibility for submission, retrieval, and delivery. Choose a destination that matches the release process:

DestinationDecision it supports
Artifact onlyAnother job or a person inspects output before repository or release changes.
Translation branch and pull requestReview translated changes separately before they enter the default branch.
Source pull request's branchReview source and translations together in one change.
Direct default-branch commitDeliver without a separate translation pull request, where branch policy explicitly permits it.

For repository writes, choose one active writer for a given translation state. Two runners working from different source revisions can otherwise compete to commit files and a lockfile. Generated commits also need branch, path, or generated-commit rules so they do not repeatedly trigger translation.

Establish the baseline the runner will inherit #

Before enabling recurrence, translate one source file into one language locally and run the application's resource checks. Commit the configuration, accepted target, and .lingo/lock.json together. A clean checkout should reproduce the same source selection and target layout.

The provider examples pin @lingo.dev/cli@1.21.0. Replace that version with the current CLI release when setting up your workflow. To manage the CLI with your project's dependencies, install it with npm install --save-dev --save-exact @lingo.dev/cli@1.21.0 and commit package.json and package-lock.json. Then use npm ci and npx --no-install lingo to run the version recorded in the lockfile.

.lingo/config.json selects locales, file patterns, and the localization engine. Establish organization and localization engine access during setup. If the job must initialize or link a project, use the explicit options in the Init and Link references rather than waiting for an unattended prompt.

In a monorepo, enter the package containing the intended configuration before running the CLI. Positional patterns narrow that configuration's selected sources; they do not select another package's configuration. Keep each independently configured package's state and artifact paths together.

Inject LINGO_API_KEY through the runner's secret mechanism. It works without interactive login. Execute credentialed jobs only from trusted code, since a branch can change scripts to expose the key. Protected-variable and fork restrictions should determine where the job runs, rather than being removed to make an untrusted job succeed.

Submit the right kind of work #

For a clean first translation, request missing target files. In an existing project, first complete ordinary source updates for the existing targets, retrieve and inspect them, then add the missing locales and backfill while keeping that source revision fixed. Follow Add a language before this command:

sh
lingo push --backfill-missing --wait

For source changes against the established baseline:

sh
lingo push --wait

An initial plain push can record source state without translating it. Backfill supplies the missing-file task; later ordinary pushes use source changes to determine the work. A scoped or backfill push is not a universal missing-key repair for existing target files.

--wait waits for the run and downloads completed output. Without it, push returns after submission. A review wait or separate retrieval job needs the CI run-state preservation procedure: retain the specific non-secret home-local pointer, original absolute project root, and matching source/configuration/target/lockfile state before the runner exits. Restore them at that same root and authenticate separately before using lingo pull --dry-run and then lingo pull. If the runner cannot recreate the path, use a persistent authorized checkout instead. Never archive credentials or all of ~/.lingo.

Keep the exit status and reported target outcomes. The current CLI fails on reported failed targets, but human review can leave a run awaiting decisions. An old file may still exist while the new version is waiting. Complete review and retrieve the result before allowing the delivery job to publish it.

Use Push and Pull for exact command behavior. --yes skips the force-regeneration confirmation; it does not approve human review or turn every pending action into completed work.

The CLI skips update checks in CI. LINGO_DISABLE_UPDATE_CHECK=1 and LINGO_TELEMETRY_DISABLED=1 provide explicit controls where needed, without disabling translation traffic.

Prove that the next step has usable files #

Check the expected changed entry against the source revision. File existence alone is weak evidence when the checkout already contains an older target. Retain the downloaded output and lock state from the same operation, and leave failed or still-waiting locales visibly incomplete.

Then use checks that understand the resource:

  • For React extraction, run lingo extract --check, lingo check, the project's TypeScript check, and the actual application build. These examine different parts of the result.
  • For native resources, run the platform's resource generation or compilation.
  • For static content, parse translated documents and inspect links, variables, and preserved syntax.
  • To fail a merge request when translations are out of date, run lingo check. It needs no API key.

lingo check works at file level: it reports a changed source and a missing target file for every configured locale, not a key missing inside an existing Android, Apple, ARB or Markdoc file.

Inspect the translation's meaning as part of the chosen acceptance process. A build can catch a malformed resource but still accept a sentence that changes an important condition. Once checks and review succeed, commit or publish only the intended output paths. Keep a no-change exit, and let required checks fail the job rather than masking them with an unconditional commit.

Resume recorded work before creating replacement work #

After an interrupted job, recover its run identity and target outcomes. If translation completed, pull that output before submitting another request. If a local target changed during the wait, resolve the pull conflict with the accepted edit visible; force-overwriting it can discard the very correction the workflow should preserve.

Keep the lockfile during diagnosis. Deleting it changes the source baseline for the next run and can turn a narrow recovery into different work. Inspect the diff and retry only the scope that remains incomplete. Recover an interrupted localization run develops that decision.

Before scheduling the job, rehearse one human-review wait and one interrupted retrieval as well as the successful case. The release step should retain the last accepted state and identify the incomplete locale, rather than accepting any file that happens to exist.