Command reference

transglot <command> [options]

A batch is one translation run. Its id is the number the CLI prints after #.

Global optionsCopy Anchor Link

Running transglot with no command prints the help text and exits with code 1. An unknown command or flag stops the CLI with exit code 1:

error: Unknown flag --locale for "push".
error: hint: Run transglot --help for usage.

initCopy Anchor Link

Sets up the repository in the current folder: scans it for locale files, signs you in through the browser, writes transglot.json, uploads your strings and runs the first translation. The walk-through is on The command line tool.

npx transglot@latest init

What init does depends on the folder and the environment:

• No transglot.json. The full setup: scan, browser sign-in, write the file, upload, first translation.
• A transglot.json this machine has no link for. init signs you in and links the folder on this machine only. It does not change the file and uploads nothing.
• A transglot.json this folder is already linked for. init stops with transglot.json already exists and this folder is linked on this machine. Pass --force to scan again and rewrite the file.
• TRANSGLOT_TOKEN is set. No browser and no upload. init reads the token's project, scans the repository for the layout, and writes transglot.json for that project. It stops if transglot.json exists unless you pass --force, and if the repository's source language differs from the project's. It ends with Next: transglot push --wait && transglot pull.

When transglot.json names a server other than https://api.transglot.ai, init asks before it signs in or sends a token there. Outside a terminal it stops instead and tells you to pass that address with --url.

Outside an interactive terminal (a script, CI, or a coding agent), and with --yes or --json, init asks nothing and takes every choice from flags. Browser sign-in never runs in CI: there, init stops with Browser sign-in does not run in CI. unless TRANSGLOT_TOKEN is set.

npx transglot@latest init --yes --path "src/locales/{locale}.json" --format json_nested --targets fr,de,ja

pushCopy Anchor Link

Uploads the files the sources rules name. Each source file updates the project's keys and source text; a file for another locale uploads its existing translations.

npx transglot@latest push --wait

Before the first upload, push plans every path and reads every file. A missing file, a file over 10 MiB, or a bad sidecar stops the run with nothing uploaded. Files then upload one locale at a time, up to four files at once.

For each file it prints what changed:

push locales/en.json (en, json_nested)
keys_created          12
keys_deleted          0
source_updated        3
translations_written  0
Batch: #4821

Batch: #<id> appears when the upload queued a translation batch, which happens when the project translates new strings automatically. Depending on the upload, push also lists conflicts:, unknown keys: and warnings:, and with a metadata sidecar descriptions_updated and max_lengths_updated.

push returns as soon as the batch is queued. With --wait it polls until the batch finishes, printing a progress line on each check:

waiting: batch #4821 processing 120/400

If the batch fails or is cancelled, push --wait lists the failed keys and exits with code 4:

error: batch #4821 finished completed_with_errors (2 of 400 failed)
error:   - checkout.total (de): <reason>

When the word limit stops the batch, the files are still uploaded and push prints error: quota exceeded: translation batch suppressed by monthly word quota and exits with code 3.

Removing keysCopy Anchor Link

--sync-removals deletes server keys the pushed source file no longer contains. It only applies to the source locale. The CLI refuses it when more than one file uploads for the same locale (each upload would delete the keys of the others), and when TRANSGLOT_TOKEN belongs to a different project from the one this folder is linked to.

pullCopy Anchor Link

Writes the files the pull rules name, one request per file.

npx transglot@latest pull

For each file, pull prints one line:

written locales/fr.json
unchanged locales/de.json

A file is rewritten only when its content changed, and the write is atomic, so an interrupted pull never leaves a half-written file. Missing folders are created.

A pulled file holds what the project has for that locale, not one entry per key. A key nobody has translated yet is absent, and so is a key a min_state filter leaves out. On a project whose message syntax is ICU, a translation that is not valid ICU MessageFormat is left out too, so it cannot break your app at render time. pull names those under the file:

written messages/fr.json
  omitted 3 invalid ICU translation(s) for fr: cart.items, cart.total, and 1 more

Fix those translations in transglot and the next pull writes them. If your i18n library does not fall back to the source language for a missing key, pull the source locale too and merge it under each target.

Empty files are not written over existing onesCopy Anchor Link

If the server has no entries for a locale, pull refuses to replace an existing non-empty file and exits with code 1:

error: refusing to overwrite locales/fr.json with an empty bundle: the server returned 0 entries for this locale

This happens when a locale has not been translated yet, when min_state: reviewed matches nothing so far, or when a push is still translating. Run push --wait before pull rather than the bare pair. Writing to a path that does not exist yet is not affected. If you mean to clear the file, pass --allow-empty.

WaitingCopy Anchor Link

With --wait, pull waits for every active batch of the project, or only --batch <id>, before it downloads anything. If a batch failed or was cancelled, pull still writes the files, then exits with code 4. If the wait runs out, it exits with code 5 and prints the command that resumes it:

error: Timed out after 600s waiting for batch(es): #4821.
error: hint: Resume with: transglot pull --wait --batch 4821 --timeout 600

statusCopy Anchor Link

Prints the project and its active batches. It always exits with code 0 unless the lookup itself fails.

npx transglot@latest status

Project        Storefront (storefront)
Source locale  en
Locales        en, fr, de
Keys           412
Active batches:
#4821  processing 120/400

With a batch id, it prints that batch, its per-language counts and, once it has finished, any failed keys:

npx transglot@latest status 4821

Batch     #4821
Status    completed
Progress  400/400 (400 ok, 0 failed)
Started   2026-10-12T09:14:03+00:00
Finished  2026-10-12T09:16:41+00:00

cancelCopy Anchor Link

Stops a running translation batch. It needs TRANSGLOT_TOKEN set to a token with the manage ability; the token stored by init cannot cancel.

TRANSGLOT_TOKEN=tgl_xxx npx transglot@latest cancel 4821

Batch #4821 is cancelled.

Cancelling a batch that has already finished is not an error: the CLI prints Batch #4821 had already finished (completed), nothing to cancel. and exits with code 0, so a cleanup step can cancel defensively.

Environment variablesCopy Anchor Link

OutputCopy Anchor Link

Results go to stdout. Errors go to stderr, prefixed error: , followed by a hint: line that says what to do next. Scripts can rely on the lines Batch: #<id>, written <path> and unchanged <path>; the GitHub Action reads them.

Every command exits with one of the documented exit codes. Pressing Ctrl+C prints Cancelled. and exits with code 130.