CLI
babelhub synchronizes keys and catalogs between your code and BabelHub, and runs translation
checks in CI. Requires PHP 8.3+ with the cURL extension.
Install
composer global require babelhub/cli:~0.1.0
# or per project
composer require --dev babelhub/cli:~0.1.0
Commands
| Command | Purpose |
|---|---|
login, logout, whoami |
credential and identity |
init |
project configuration (.babelhub.json) |
scan |
find keys in PHP and Twig files |
push |
upload keys and source strings |
pull |
download approved catalogs |
sync |
push, then pull |
status |
coverage, quality and readiness |
diff |
what changed since a point in time |
validate |
translation checks; nonzero exit code on failure |
Full flags: babelhub <command> --help. --output=json gives machine-readable results,
diagnostics go to stderr.
Project configuration
babelhub init writes .babelhub.json in the project directory. The file belongs in the
repository, because it is configuration, not a secret:
{
"project": "your-project",
"source_locale": "en_GB",
"files": { "pattern": "translations/messages.{lang}.php", "format": "php", "root_key": null },
"scan": { "paths": ["src", "templates", "config"] }
}
The credential never goes into that file — it lives outside the repository.
Exit codes
| Code | Meaning |
|---|---|
0 |
success (also when diff shows changes — it is a read, not a gate) |
1 |
the tool could not finish (network, configuration, hook failure) |
6 |
a check failed: QA errors, missing approvals, skipped keys in push |
124 |
a hook exceeded the 300 s limit |
6 is separate from 1 on purpose: "the translations are wrong" and "the tool broke" need
different reactions, and a push with skipped keys must not pretend to be a success.
CI
- run: composer global require babelhub/cli:~0.1.0
- run: babelhub validate --fail-on=error
env:
BABELHUB_TOKEN: ${{ secrets.BABELHUB_TOKEN }}
validate is the gate; diff and status are reads and do not fail the pipeline.