Use the CLI in CI

In CI the CLI authenticates with a deploy token in the TRANSGLOT_TOKEN environment variable. It never opens a browser and never asks a question there. On GitHub, the GitHub Action wraps the same steps; this page covers every other CI system.

Before you startCopy Anchor Link

1. Commit transglot.json. Run npx transglot@latest init once on your machine, or write the file by hand from the configuration reference.
2. Create a deploy token with the push and pull abilities. Add manage only if the job also cancels batches. See Deploy tokens.
3. Store it as a secret named TRANSGLOT_TOKEN in your CI system. Never put the token in transglot.json or in the pipeline file.

The two commandsCopy Anchor Link

Every pipeline runs the same pair:

npx --yes transglot@latest push --wait
npx --yes transglot@latest pull

push --wait uploads the source strings and waits until the translation batch finishes. pull then writes the translated files into the checkout. Without --wait, pull would run before anything is translated.

What happens to the pulled files is up to the pipeline: commit them, open a merge request, or keep them as a build artifact.

To make builds reproducible, pin a version instead of @latest, for example npx --yes transglot@0.5.0. The CLI needs Node.js 22 or later on the runner.

Environment variablesCopy Anchor Link

The CLI recognises CI from the variables CI systems set, including CI, GITLAB_CI, CIRCLECI, BUILDKITE, JENKINS_URL and BITBUCKET_BUILD_NUMBER. In CI it asks nothing, prints no colour, and refuses browser sign-in with Browser sign-in does not run in CI.

GitLab CICopy Anchor Link

This job runs on the default branch and keeps the pulled files as an artifact.

translations:
  image: node:22
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  script:
    - npx --yes transglot@latest push --wait
    - npx --yes transglot@latest pull
  artifacts:
    paths:
      - locales/

Add TRANSGLOT_TOKEN under Settings → CI/CD → Variables in GitLab, masked and protected. Replace locales/ with the folders your pull rules write to.

CircleCICopy Anchor Link

version: 2.1

jobs:
  translations:
    docker:
      - image: cimg/node:22.20
    steps:
      - checkout
      - run:
          name: Push source strings and wait for translations
          command: npx --yes transglot@latest push --wait
      - run:
          name: Pull translated files
          command: npx --yes transglot@latest pull
      - store_artifacts:
          path: locales

workflows:
  localize:
    jobs:
      - translations:
          context: transglot
          filters:
            branches:
              only: main

Store TRANSGLOT_TOKEN in a CircleCI context (here named transglot) or in the project's environment variables.

Plain shellCopy Anchor Link

Any runner with Node.js 22 and git can sync and commit in one script. This one commits only when a translation file changed.

#!/usr/bin/env bash
set -euo pipefail

: "${TRANSGLOT_TOKEN:?Set TRANSGLOT_TOKEN to a deploy token}"

npx --yes transglot@latest push --wait
npx --yes transglot@latest pull

if [ -n "$(git status --porcelain)" ]; then
  git add -A locales
  git commit -m "chore(i18n): sync translations from transglot"
  git push
fi

With set -e, the script stops at the first non-zero exit code. To keep going when the word limit is reached or some translations failed, branch on the exit code instead; see Exit codes.

RecipesCopy Anchor Link

Push on every merge, pull on a scheduleCopy Anchor Link

Uploading is quick; translation takes as long as the batch. Push without waiting on every merge, and pull in a scheduled job:

# on merge to main
npx --yes transglot@latest push

# nightly
npx --yes transglot@latest pull --wait

pull --wait waits for every active batch of the project before it downloads.

Resume a wait that timed outCopy Anchor Link

--wait gives up after 600 seconds by default and exits with code 5. The batch keeps running on the server. Raise the limit with --timeout, or pick up where the job stopped:

npx --yes transglot@latest pull --wait --batch 4821 --timeout 1800

The CLI prints the exact command, with the batch id, when the wait times out.

Stop a batch when a job is cancelledCopy Anchor Link

A cleanup step can stop a running batch. cancel needs a token with the manage ability and exits with code 0 even when the batch has already finished:

npx --yes transglot@latest cancel "$BATCH_ID"

push prints the id as Batch: #<id>. Read it from the output:

BATCH_ID=$(npx --yes transglot@latest push | sed -n 's/^Batch: #\([0-9]*\).*/\1/p' | head -n 1)

Only translations someone has checkedCopy Anchor Link

To ship only translations a person edited or reviewed, add min_state to the pull rules in transglot.json:

{
  "url": "https://api.transglot.ai",
  "sources": [{ "path": "locales/{locale}.json", "format": "json_nested" }],
  "pull": [{ "path": "locales/{locale}.json", "format": "json_nested", "min_state": "reviewed" }]
}

TroubleshootingCopy Anchor Link

Every code the CLI exits with is listed in Exit codes.