Check translations in GitLab CI

The job

Add it to .gitlab-ci.yml. Change --source to your base-language file and --langs to the locales you ship. The rules block runs the job only on merge requests that change something under locales/; drop the changes lines to run it on every merge request.

i18n-check:
  stage: test
  image: python:3.12-slim
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        - locales/**/*
  script:
    - pip install kaeris
    - kaeris check --source locales/en.json --langs de,fr --ci

What the job prints

The two script lines, run in order. Left: files that are fine. Right: de.json with {nam} instead of {name} and the checkout key missing; the job stops with exit code 1.

$ pip install kaeris
Collecting kaeris
  Using cached kaeris-0.2.35-py3-none-any.whl.metadata (26 kB)
Using cached kaeris-0.2.35-py3-none-any.whl (131 kB)
Installing collected packages: kaeris
Successfully installed kaeris-0.2.35

$ kaeris check --source locales/en.json --langs de,fr --ci
✓ de: complete & placeholder-safe
✓ fr: complete & placeholder-safe
✓ all locales complete & placeholder-safe
Job succeeded
exit code: 0

$ pip install kaeris
Requirement already satisfied: kaeris in C:\Users\Inzagi\AppData\Local\Temp\claude\C--Users-Inzagi-projects-kaeris\bfeebe69-3cfd-4f28-bbe7-e5600be082b9\scratchpad\venv-gl2\Lib\site-packages (0.2.35)

$ kaeris check --source locales/en.json --langs de,fr --ci
✗ de: 1 missing key(s): checkout
✗ de: 1 placeholder mismatch(es):
    greeting: missing ['{name}'], added ['{nam}']
✗ de: 2 translation fault(s):
    greeting: lost placeholder {name}
    greeting: invented placeholder {nam} (not in source)
✓ fr: complete & placeholder-safe
✗ 1 missing key, 1 placeholder mismatch, 2 translation faults
ERROR: Job failed: exit code 1
exit code: 1

1. Add the job

   Paste the job into .gitlab-ci.yml and set your own --source and --langs.

2. Open a merge request

   Change a locale file on a branch and open a merge request. The job runs and shows every finding in its log.

3. Require the pipeline

   In the project settings under merge requests, turn on that pipelines must succeed. A red job then blocks the merge.

• What ran

  Both script lines, taken from the parsed YAML and run one after another in a clean Python virtual environment, stopping at the first failing line as a GitLab job does. pip install kaeris downloaded kaeris 0.2.35 from PyPI. Clean files: exit code 0. The broken de.json: exit code 1.

• What did not run

  No GitLab runner and no Docker image were used (the log above comes from a Windows PC with Python 3.14, not from python:3.12-slim). The rules and changes block was only parsed as YAML; GitLab did not evaluate it. The package declares Python 3.8 or newer.

• Fail on stale keys too

  --strict also fails when a translation has keys that the source no longer has.

• Keep brand names as written

  --glossary 'KAERIS,GitHub' fails a target that dropped one of the terms. The same list can live under keep in kaeris.json.

• Different file layout

  --out is the folder with the translations and --pattern '{lang}/common.json' their file names. Default: the layout kaeris translate writes.

• No flags at all

  With a kaeris.json in the project (kaeris init writes one), kaeris check takes the source, languages and folder from it.

Other recipes: GitHub Actions · pre-commit · Make and npm scripts

CLI reference · Check reference · GitHub Action reference · Free check in the browser · Translate in the browser