Exit codes
Read the CLI's exit code to tell a configuration mistake from a revoked token, a spent word limit or a failed translation, and react to each in your pipeline.
Every CLI command exits with one of these codes. They are stable across the 0.x releases, so scripts can branch on them.
| Code | Meaning | Typical causes | What to do |
|---|---|---|---|
0 | Success. | Nothing. | |
1 | Configuration or usage. | transglot.json missing or invalid; a source file missing or over 10 MiB; an unknown command or flag; a batch id that does not exist; a locale that is not a language of the project; pull refusing to write an empty file over a full one; a choice init needs a flag for outside a terminal. | Fix the input the message names. Retrying does not help. |
2 | Sign-in, token or access refused. | TRANSGLOT_TOKEN missing, revoked or expired; the token lacks the ability the command needs; the plan does not include API access; the workspace or account is suspended, read-only or closing; browser sign-in attempted in CI. | Read the hint: it names the missing ability or what to change. Replace the token or ask an admin. |
3 | Word limit reached. | The upload went through but the translation batch was held back because the workspace's words are used up, or AI translation is paused for the account. | Your files are synced. Raise the limit or wait for the reset, then push again. |
4 | A translation batch failed or was stopped. | With --wait, a batch finished as failed or completed_with_errors, or was cancelled. | The failed keys are listed with their reasons. Translations that did complete are still written by pull. Select Retry failed on the run in the project's Runs page to re-run only the strings that failed. |
5 | Timed out while waiting. | --wait ran longer than --timeout (default 600 seconds). | The batch keeps running on the server. Resume with the command in the hint, for example transglot pull --wait --batch 4821. |
6 | Server or network error. | The server could not be reached, answered with a server error or an unexpected response, redirected the request, or was still rate-limiting after two retries. | Retry later. Check that url points at https://api.transglot.ai. |
130 | Interrupted. | You pressed Ctrl+C. | Nothing. |
How the CLI picks a code
- Worst signal wins. When one
push --waitboth hits the word limit and has a failed batch, it exits with4, because missing translations need attention first. pullwrites first, then reports. With--wait, a failed batch makespullexit with4, but only after it has written every file it could.statusandcancelare read-outs. They exit with0whenever the request succeeds, including for a failed batch or one that had already finished.- Rate limits are retried for you. A
429is retried up to two times, waiting as long as the server asks (at most 60 seconds), before the CLI gives up with6.
Errors are printed on stderr as error: <message> and error: hint: <what to do>. A token that lacks an ability, for example, reads:
error: hint: The token lacks the "push" ability. Issue a token that has it.React to codes in a script
Treat 3 and 4 as warnings if a partial result is acceptable, and everything else as a failure:
#!/usr/bin/env bash
set -u
npx --yes transglot@latest push --wait
code=$?
case "$code" in
0) ;;
3) echo "Word limit reached: sources synced, nothing new translated." ;;
4) echo "Some translations failed: pulling what finished." ;;
*) exit "$code" ;;
esac
npx --yes transglot@latest pullThe GitHub Action follows the same idea: it pulls and commits after 0, 3 and 4, skips the pull after any other code, and fails the job with the worst code of the run.
Use the CLI in CI
Upload new strings on every merge, wait for the translations, and write the finished locale files back from any CI system.
The GitHub Action
Run transglot on every push to your repository: upload new strings, wait for the translations, and commit the finished locale files back to the branch.