babelhub / cli

v0.1.5 2026-10-28 18:54 UTC

Requires

• php: ^8.3
• ext-curl: *
• ext-json: *
• symfony/console: ^7.4
• symfony/yaml: ^7.4

Requires (Dev)

• phpstan/phpstan: ^2.2
• phpunit/phpunit: ^11.0
• squizlabs/php_codesniffer: ^4.0

MIT

• i18n
• translation
• cli
• ci
• localization
• babelhub

Published on Packagist.org on 2026-10-28 18:59 UTC

README

Synchronize translation keys and approved catalogs between your codebase and BabelHub, and run translation checks in CI.

• Scan PHP and Twig source files for translation keys.
• Push keys and source strings to BabelHub.
• Pull approved translations into PHP or JSON files, preserving local formatting and extra keys.
• Check translation quality, coverage, approval status and hardcoded strings.

Installation

Requires PHP 8.3 or newer with the cURL extension, and access to a BabelHub instance.

Install globally with Composer:

composer global require babelhub/cli:~0.1.0
babelhub --version

Or add it to your project:

composer require --dev babelhub/cli:~0.1.0
vendor/bin/babelhub --version

A standalone babelhub.phar is distributed through GitHub Releases. Run it with php babelhub.phar in place of babelhub in the examples below.

Quick start

Create a project in your BabelHub instance, then run these commands from your application directory:

# Replace the URL with your BabelHub instance. Complete login in the browser.
babelhub login --api-url=https://babelhub.example.com

# Select the project, source language and translation file paths.
babelhub init

babelhub scan       # inspect keys found in the code
babelhub push       # upload keys and source strings
babelhub pull       # download approved translations
babelhub validate   # run translation checks

babelhub sync combines push and pull. For project-local installations, use vendor/bin/babelhub instead of babelhub.

Configuration and credentials

babelhub init creates .babelhub.json; YAML configuration is also supported with babelhub init --config=yaml. Commit the configuration to your application's repository. Keep only one configuration file: .babelhub.json or .babelhub.yml.

Credentials are stored separately from project configuration. For CI, provide the server URL through BABELHUB_API_URL and a personal access token through the secret BABELHUB_TOKEN. Never commit the token. See the CI guide for permissions and setup examples.

Commands

Command	Purpose
login, logout, whoami	Manage authentication and inspect the current identity
init	Configure a project
scan	Find translation keys in PHP and Twig
push	Upload keys and source strings
pull	Download approved translation catalogs
sync	Push, then pull
status	Show coverage, quality and readiness
diff	Show key changes since a point in time
validate	Run translation checks and return a nonzero exit code on failure

Use babelhub <command> --help for options. --output=json provides machine-readable results; diagnostics go to stderr. validate returns exit code 6 when a check fails.

Documentation

• CLI manual: configuration, commands, file formats and exit codes.
• CI guide and workflow examples: GitHub Actions and GitLab CI.
• Changelog: changes in each release.
• Contributing: local development, tests and PHAR builds.

CLI messages and the detailed manual are currently in Polish.

License

MIT.