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.