GitLab CI recipe

Translate files in a trusted GitLab pipeline, deliver them through a merge request, and fail merge requests whose translations are out of date.

A GitLab runner can translate repository files with the Lingo.dev CLI and retain the results as job artifacts. This lets translation use the same checkout, checks, and release process as the rest of your application. GitLab owns pipeline execution and repository delivery; Lingo.dev processes the selected source files through a localization engine.

This is a CI recipe, not a native GitLab account connection. Begin with a manually launched pipeline on the default branch, then add recurring triggers and merge-request delivery after inspecting the result.

Establish the source and credentials #

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. Run the CLI from the directory that owns it.

Create missing target files with lingo push --backfill-missing --wait. Use ordinary lingo push --wait for later source edits. A change to the localization engine's instructions does not by itself rewrite accepted files; deliberate regeneration is a separate task.

In the project's CI/CD variable settings, save LINGO_API_KEY as a masked variable. The CLI reads only this name; a LINGODOTDEV_API_KEY variable from the previous CLI is ignored, so rename it. Restrict it to the trusted branches or environments that may submit translation work. A protected variable can be unavailable on an unprotected branch or merge request; use an authorized branch instead of exposing it to untrusted code.

The API key authorizes translation. A GitLab credential with repository write access is needed only when you add commit delivery.

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.

Run an artifact-first pipeline #

This .gitlab-ci.yml example assumes locales/en.json is the configured source and locales/es.json, an existing Spanish file, is 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 or commit stays stale. The example uses a manually launched pipeline on the default branch:

yaml
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 makes the job wait for the run and write the translated files into the checkout. Without it, lingo push only submits the run and exits, so later steps find no new files to inspect or commit.

Verify registry access from your runner, and provide any tools required by later steps. For example, an alternative minimal image may need Git installed before it can inspect or commit a diff.

Verify the organization and engine IDs in the committed .lingo/config.json. Make one source edit and launch the pipeline. In the log, confirm the reported run state and changed target entry. Download the artifact, compare the translation with that source revision, and load it through your application. The file-presence and JSON checks cannot establish freshness or meaning on their own.

--wait downloads completed output, but configured human review can leave work awaiting a person. Before using a review wait or separate retrieval job, add the CI run-state preservation procedure. Export the specific pointer and original absolute project root after submission. Include .lingo-ci/run.json, .lingo-ci/project-root.txt, .lingo/config.json, locales/en.json, the target, and lockfile in restricted job artifacts. Set when: always in the artifacts configuration and allow enough retention for review. Ensure the export also runs when later validation fails; do not conceal the original failure.

Complete review, then restore the recorded revision and file state at the same absolute root on the retrieval runner. Restore only that pointer, authenticate separately, and use lingo pull --dry-run before collection. If the runner cannot recreate the original path, use a persistent authorized runner for both jobs instead. Never archive all of ~/.lingo. A successful submission or an old target file alone does not supply new files to publish.

Commit translations to a merge request #

This job translates source changes in a merge request and commits the results to the same branch. It assumes the initial backfill is committed and the engine's Human review is off, so translation can finish in one job.

On GitLab 18.4 or later, enable Settings → CI/CD → Job token permissions → Allow Git push requests to the repository. The job uses GitLab's built-in token; the person starting it must have permission to push to the source branch. See GitLab's job-token setup.

Keep LINGO_API_KEY masked and protected. Use trusted source and target branches in the same project, protect both branches, and enable Allow merge request pipelines to access protected variables and runners in the project's CI/CD settings. The person starting the pipeline also needs push or merge access to the target branch. These are GitLab's requirements for protected variables.

Use the same source and target paths as the first example. Add this job to the translate stage:

yaml
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 runs one translation job at a time for each MR. The job commits only the Spanish target and translation lockfile. If the branch changes during translation, Git rejects the push; run a pipeline for the updated branch.

CI_REPOSITORY_URL supplies the job-token credentials. Pushes with this token do not start another pipeline, so add your application's resource checks before the commit step. Review the translation diff in the MR and run any remaining checks before merging.

Because that push starts no pipeline, the MR's newest commit has none. If the project requires Pipelines must succeed, GitLab may block the merge. Then select Run pipeline on the MR's Pipelines tab. The job finds nothing to push and exits without a commit, and that pipeline gives the newest commit a status.

Open a translation merge request from the default branch #

This job translates each change that reaches the default branch and opens a merge request with the result. GitLab push options create the merge request in the same git push, so no API call or extra tool is needed. It makes the same assumptions as the job above: the initial backfill is committed and Human review is off.

Create a project access token with the Developer role and the write_repository scope. Save it as a masked, protected CI/CD variable named GITLAB_PUSH_TOKEN. On GitLab.com, project access tokens need a paid tier. CI_JOB_TOKEN is not used here, because GitLab starts no pipeline for a push made with it. The push URL uses CI_SERVER_FQDN, which keeps the port of a self-managed instance that uses a non-standard one. CI_SERVER_FQDN needs GitLab 16.10 or later. On an older self-managed instance, use ${CI_SERVER_HOST}:${CI_SERVER_PORT} instead.

Add this job to the translate stage:

yaml
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 exits non-zero when a target fails, so the job stops before the commit. When nothing changed, it prints "Nothing to push", the staged diff is empty, and the job exits without a commit.

The first two lines stop the job when the default branch has moved past the commit it runs on. resource_group runs one job at a time, but in GitLab's default unordered process mode it starts waiting jobs in no fixed order. Without the check, an older job could run last and force-push older translations over newer ones. The job for the newest commit translates it, and nothing is submitted for a commit that is already outdated.

The job does not loop. It runs only for pushes to the default branch and writes only to lingo/translations. GitLab's docs say -o ci.skip affects only branch pipelines, not merge request pipelines, and that a merge request pipeline runs when a merge request is created or its source branch gets a new commit. So the gate below should run on the translation merge request; confirm that on the first run. Merging that merge request starts the job once more, which finds nothing to push.

Each run rebuilds lingo/translations from the default-branch commit it ran on and force-pushes it, so an open merge request shows the newest translation diff. Hand edits made on that branch are replaced by the next run; make them after merging. Until the merge request is merged, the default branch keeps the previous .lingo/lock.json, so the next run submits the same source changes again. If later commits undo every source change the merge request translates, the next run finds nothing to push and leaves the merge request open with outdated translations; close it instead of merging.

Fail merge 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 CI/CD variable and writes nothing, so it also runs on merge requests from forks. Apart from CLI telemetry, which DO_NOT_TRACK=1 turns off, it makes no network call; the npx examples still download 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 check to the stages list, then add the job for your setup. When developers run lingo push --wait and commit the result with their source change, check every merge request:

yaml
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

With the default-branch job, check only its translation merge request, because feature merge requests change sources before translation:

yaml
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

The gate fits a setup where translations are committed together with the source change:

Where translation runsGate on every merge request
Developers run lingo push --wait and commit the result before opening the merge requestYes. It fails a merge request whose source changed without translation.
The merge-request job commits to the source branchNo. The check would inspect the commit before translation, and the job's push starts no new pipeline.
The default-branch job opens a translation merge requestOnly on lingo/translations, with the second job above. Feature merge 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.

Make recurring work predictable #

Filter automatic jobs to the intended trusted branches and source paths. If using merge-request triggers, also constrain the source project and target branch. Prevent generated commits from repeatedly submitting translation, with an appropriate branch rule or skip-CI policy and an empty-diff exit.

For a monorepo, enter the package containing the intended configuration and retain its package-relative output and state. Independent packages can have different localization engines and locales; keep their lockfiles separate. The same runner approach works with self-managed GitLab when network access, runner tooling, variables, and repository policy support it.

Ordinary incremental translation can retain a manually edited target key while its source stays unchanged. A changed source can regenerate that key. Missing-file backfill and forced regeneration have different scopes. Without file patterns, --force covers every configured source and target locale and can replace accepted translations. Use explicit patterns and inspect an estimate before forcing work. Consult Push when changing the submission command.

Recover and retire the pipeline #

Use the error to identify the next action: repair package installation, supply an authorized variable, complete review, resolve a pull conflict, or retry failed target work after correcting its cause. Preserve successful artifacts, but keep a partially completed release visibly incomplete.

Disable the trigger to stop new pipelines. Inspect any already-submitted translation separately when cancelling its runner. Remove obsolete API and repository credentials when retiring the recipe.