Skip to main content

CLI Reference

The Branchlate CLI allows you to manage and synchronize translations directly from the command line. By integrating Branchlate commands into your workflow, you can streamline your translation process and automate tasks within CI/CD pipelines.

Installation​

All Branchlate CLI commands use npx to ensure you are always running the latest version.

npx branchlate@latest <command>

Commands​

Here’s an overview of all available Branchlate CLI commands, options, and usage examples.

login​

Authenticate the Branchlate CLI with your account.

npx branchlate@latest login

This command will prompt you for your Branchlate email and password, storing your authentication token locally in ~/.branchlate/authentication.json. This token is required for all subsequent commands.

init​

Initialize a Branchlate configuration in your project. This command creates a branchlate.json configuration file, specifying project settings for future syncs.

npx branchlate@latest init

This command prompts you for:

  • Project ID: Branchlate project ID.
  • Organisation ID: Branchlate organisation ID (leave blank for personal projects).
  • Translation files path: The pattern for locating translation files (e.g., i18n/{languageCode}.json).

Options:

  • --projectId <projectId>: Specify the Branchlate project ID.
  • --organisationId <organisationId>: Specify the Branchlate organisation ID.
  • --languageFilePattern <pattern>: Specify the pattern for your translation files.

Example:

npx branchlate@latest init --projectId my-project --organisationId my-org --languageFilePattern i18n/{languageCode}.json

Note: If you have an existing configuration, the command will prompt you to confirm if you want to overwrite it.

sync​

Synchronize your local translations with Branchlate, ensuring alignment across environments. By default, this command syncs using the current Git branch as the Branchlate branch.

npx branchlate@latest sync

Options:

  • --branch-name <branchName>: Specify a different branch name instead of the current Git branch.
  • --flatten: Flatten nested translation keys into a single level.
  • --auto-translate: Automatically generate translations for new or updated keys and wait for the translations to complete.
  • --no-wait: Use in combination with --auto-translate to initiate auto-translation without waiting for the translations to complete.
  • --invalidate-updated-keys: When a key's value is updated, mark all language values for that key as needing re-translation. This is useful when updating reference language values and wanting translators to re-validate every language.
  • --force: When conflicts are detected between local and remote values, interactively choose which value to keep for each conflicting key.
  • -y, --yes: Skip all confirmation prompts (automatically enabled when using BRANCHLATE_TOKEN).

Notes:

  • The sync command will create the project in Branchlate if it does not already exist.
  • If you have sub-projects defined in your branchlate.json, the sync command will also sync those sub-projects.
  • The command will automatically handle creating new branches and updating existing ones.
  • After the first flattening, further syncs will auto-detect the flattened structure, so you don't need to pass --flatten again unless you change your key structure.

Use cases​

Sync with a specific branch name​
npx branchlate@latest sync --branch-name feature/new-login

This syncs translations to the feature/new-login branch on Branchlate.

Flatten translation keys during sync​
npx branchlate@latest sync --flatten

This command flattens nested translation keys into dot-notated keys during the sync.

Automatically translate keys​
npx branchlate@latest sync --auto-translate

You can execute an auto translation for all unvalidated and not already translated keys. Here is how the process works:

  • The --auto-translate option initiates the translation process for all unvalidated and not already translated keys.
  • The CLI waits for the translations to complete before proceeding.
  • After translations are completed, the CLI syncs again to update your local files with the new translations.
Asynchronous auto-translate​
npx branchlate@latest sync --auto-translate --no-wait

This command initiates the auto-translation process but does not wait for the translations to complete.

Invalidate translations when updating keys​
npx branchlate@latest sync --invalidate-updated-keys

When you update a reference language value (e.g., changing the English wording of an existing key), translations in other languages may become stale. Use --invalidate-updated-keys to mark every language value for updated keys as "needs review". Reviewers and translators will see these keys flagged on Branchlate.

Resolve conflicts with --force​
npx branchlate@latest sync --force

When local values conflict with remote values, the CLI will show each conflict and let you choose whether to keep your local value or the Branchlate value.

format​

Format your local language files so that keys are sorted and indentation is consistent. This helps keep translation files readable and reduces noisy diffs. The command uses the same file patterns as sync (including sub-projects if defined in your configuration).

npx branchlate@latest format

Options:

  • --dry-run: Show a diff of what would be changed without writing to files.

Notes:

  • If you only have sub-projects in your branchlate.json (no root languageFilePattern), the command will still find and format all files from your sub-project patterns.
  • Use --dry-run to preview changes before applying them, for example before committing.

Example:

npx branchlate@latest format --dry-run

Example output:

When some files need formatting, format --dry-run shows a diff for each file that would change. After running format, those files are updated; running format --dry-run again then reports that all files are already formatted.

format (apply changes)

$ npx branchlate@latest format
npx branchlate@latest format
📝 Formatting 4 language file(s)...
🇺🇸 src/common/i18n/translations/notifications/en.json (formatted)
🇫🇷 src/common/i18n/translations/categories/fr.json (formatted)
✅ Successfully formatted 2 file(s)

format --dry-run (with changes to apply)

$ npx branchlate@latest format --dry-run
npx branchlate@latest format --dry-run
📝 Formatting 4 language file(s)...
🇺🇸 src/common/i18n/translations/notifications/en.json (would be formatted)
Index: src/common/i18n/translations/notifications/en.json
===================================================================
--- src/common/i18n/translations/notifications/en.json original
+++ src/common/i18n/translations/notifications/en.json formatted
@@ -19,5 +19,5 @@
"postTagTitle": "You were tagged",
"postTagWithPreview": "{taggerName} tagged you in a post{bookContext}: "{contentPreview}"",
"recommendationBody": "{recommenderName} recommended you {bookTitle}. Tap for more details.",
"recommendationTitle": "New Recommendation"
-}
\ No newline at end of file
+}
🇫🇷 src/common/i18n/translations/categories/fr.json (would be formatted)
Index: src/common/i18n/translations/categories/fr.json
===================================================================
--- src/common/i18n/translations/categories/fr.json original
+++ src/common/i18n/translations/categories/fr.json formatted
@@ -871,5 +871,5 @@
"Young Adult Fiction": "Fiction pour jeunes adultes",
"Young Women": "Jeunes femmes",
"Youth": "Jeunesse",
"Youth Literature": "Littérature jeunesse"
-}
\ No newline at end of file
+}
⚠️ Dry run: 2 file(s) would be formatted

format --dry-run (all files already formatted)

$ npx branchlate@latest format --dry-run
npx branchlate@latest format --dry-run
📝 Formatting 4 language file(s)...
✅ All files are already properly formatted

status​

Print a translation coverage report for the current branch. This is especially useful in CI to ensure that all languages meet a minimum validation level before releasing—so you never ship untranslated or unvalidated keys to users.

By default, the command fails if your local files are out of sync with Branchlate (exit code 2) or if any language is below the required coverage (exit code 1).

npx branchlate@latest status

Options:

  • --min-coverage <percent>: Minimum validated percentage required for each language (default: 100). The command exits with code 1 if any language is below this value.
  • --no-fail-on-out-of-sync: Do not exit with code 2 when local files are out of sync with remote. Use this to still get a coverage report even when a sync is pending.
  • --branch-name <branchName>: Branch to check (default: current Git branch).
  • --json: Output the result as structured JSON for CI parsing and automation.
  • --local: Check that all translation keys are defined across all languages, without comparing against a remote branch. Useful for branches that don't have a corresponding branch in Branchlate.
  • --fallback-to-local: Run the normal remote comparison when the branch exists on Branchlate; automatically fall back to --local behavior when it doesn't. Ideal for CI pipelines that run on every branch.

Exit codes:

  • 0: Local files are in sync and all languages meet the minimum coverage.
  • 1: At least one language is below the required coverage (see --min-coverage).
  • 2: Local files are out of sync with Branchlate (run sync first, or use --no-fail-on-out-of-sync to only check coverage).

Notes:

  • The command uses the same project and sub-project configuration as sync, so it will report coverage for all configured language file sets.
  • For release branches, run branchlate status in CI to block releases when translations are incomplete or out of sync.
  • --local and --fallback-to-local are mutually exclusive.

Example:

npx branchlate@latest status --min-coverage=100

Example output:

The command lists each project (or sub-project), whether it is in sync, and for each language the validated percentage and count. Languages below the minimum coverage are shown in red; unvalidated keys are listed when there are few enough to display.

$ npx branchlate@latest status
npx branchlate@latest status
⚠️ notifications: local files are out of sync with remote
🇺🇸 en 90.5% validated (19/21)
- bookContextRelated
- bookContextAbout
🇫🇷 fr 100.0% validated (21/21)
✓ categories: in sync
🇺🇸 en 100.0% validated (873/873)
🇫🇷 fr 100.0% validated (873/873)

status --json (structured output for CI)

npx branchlate@latest status --json
{
  "branch": "main",
  "minCoverage": 100,
  "projects": [
    {
      "project": "notifications",
      "isOutOfSync": true,
      "languages": [
        {
          "language": "en",
          "totalKeys": 21,
          "validatedCount": 19,
          "unvalidatedCount": 2,
          "validatedPercentage": 90.47,
          "unvalidatedKeys": ["bookContextRelated", "bookContextAbout"]
        },
        {
          "language": "fr",
          "totalKeys": 21,
          "validatedCount": 21,
          "unvalidatedCount": 0,
          "validatedPercentage": 100,
          "unvalidatedKeys": []
        }
      ]
    }
  ],
  "summary": {
    "anyOutOfSync": true,
    "anyBelowCoverage": true,
    "exitCode": 1
  }
}

Use the JSON output in CI scripts to parse results programmatically, for example with jq:

# Get languages below 100% coverage
npx branchlate@latest status --json | jq '.projects[].languages[] | select(.validatedPercentage < 100)'

Local-only check​

Not every Git branch needs a corresponding branch in Branchlate. Quick fixes, hotfixes, or translations received directly from translators may not go through the full Branchlate workflow. In those cases, you still want to make sure no translation key is missing before merging.

--local checks that every key in the reference language exists with a non-empty value in all other languages. No remote branch comparison is performed — only local file consistency is verified.

npx branchlate@latest status --local

Fallback to local (--fallback-to-local)​

In CI, you typically want to run status on every branch. Some branches are synced with Branchlate (and benefit from the full remote comparison), while others are not. --fallback-to-local handles both cases: it runs the normal remote check when the branch exists on Branchlate, and automatically falls back to a local key-completeness check when it doesn't.

This is the recommended option for CI pipelines that run on all branches:

npx branchlate@latest status --fallback-to-local --min-coverage=100

generate-token​

Generate an authentication token for CI/CD environments.

npx branchlate@latest generate-token

This command outputs a token that can be used in CI/CD pipelines to authenticate non-interactively.

Example:

export BRANCHLATE_TOKEN=$(npx branchlate@latest generate-token)

project delete​

Delete a project from Branchlate.

npx branchlate@latest project delete

Options:

  • --project-id <projectId>: Specify the slug of the project to delete.
  • --organisation-id <organisationId>: Specify the slug of the organisation.
  • --force: Skip confirmation prompts.

Example:

npx branchlate@latest project delete --project-id my-project --organisation-id my-org

Notes:

  • When using a CI token (BRANCHLATE_TOKEN), the --force option is automatically enabled, so you don't need to include it.
  • The command will use the project ID and organisation ID from your branchlate.json if not specified.
  • The --force option allows the command to proceed without a confirmation prompt, which is useful in automated scripts.

branch delete​

Delete a specific branch from a Branchlate project.

npx branchlate@latest branch delete

Options:

  • --branch-name <branchName>: Name of the branch to delete (defaults to current Git branch if not specified).
  • --project-id <projectId>: ID of the project containing the branch.
  • --organisation-id <organisationId>: ID of the organisation.
  • --force: Skip confirmation prompts.

Example:

npx branchlate@latest branch delete --branch-name feature/new-login --project-id my-project --organisation-id my-org

Notes:

  • If --branch-name is not specified, the current Git branch is used.
  • When using a CI token (BRANCHLATE_TOKEN), the --force option is automatically enabled, so you don't need to include it.
  • The command will use the project ID and organisation ID from your branchlate.json if not specified.
  • The --force option allows the command to proceed without a confirmation prompt, which is useful in automated scripts.

CI/CD Integration​

The Branchlate CLI can be integrated into your CI/CD pipelines to automate translation synchronization and project management tasks.

Authentication in CI/CD​

To authenticate in CI/CD environments, use a token generated with the generate-token command. Set this token as an environment variable in your CI/CD environment.

Steps:

  1. Generate the token locally:

    npx branchlate@latest generate-token

  2. Set the token as the BRANCHLATE_TOKEN environment variable in your CI/CD environment.

    export BRANCHLATE_TOKEN=<your-token>

When BRANCHLATE_TOKEN is set, the CLI operates in non-interactive mode, suitable for automated environments. The --force option is automatically enabled in this mode, so you don't need to include it in your commands.

Example CI/CD use cases​

In your CI/CD pipeline, you can use Branchlate commands to:

Sync translations and auto-translate on each commit​

Sync translations and automatically generate translations whenever a new commit is pushed to a branch:

npx branchlate@latest sync --branch-name ${CI_COMMIT_BRANCH} --auto-translate --no-wait

This keeps your translation files in sync with Branchlate’s database, ensuring that every commit reflects the latest translations. Using --no-wait ensures the build process isn't delayed by waiting for translations to complete.

Delete feature branches after merging​

Automatically delete feature branches in Branchlate once they are merged, cleaning up unused branches in your project.

npx branchlate@latest branch delete --branch-name ${CI_COMMIT_BRANCH} --project-id my-project --organisation-id my-org

Note: Since BRANCHLATE_TOKEN is used, the --force option is automatically enabled, so you don't need to include it.

Check translation coverage before release​

Ensure translations are complete and in sync before releasing. Run status on your release branch; it will exit with code 1 if any language is below 100% validated, or code 2 if local files are out of sync.

npx branchlate@latest status --min-coverage=100

If the command fails, fix translations or run sync, then re-run the check before deploying.

Check translation keys on every branch​

Not every branch needs to be synced with Branchlate — quick fixes or translations received directly from translators may skip the full workflow. Use --fallback-to-local so that synced branches get the full remote comparison, while other branches still get a local key-completeness check. This way, no branch can merge with missing translation keys.

npx branchlate@latest status --fallback-to-local --min-coverage=100

Parse status results in CI scripts​

Use --json to get structured output that can be parsed with tools like jq:

# Fail the pipeline and log which languages are incomplete
npx branchlate@latest status --json > status.json
if [ $? -ne 0 ]; then
  echo "Incomplete translations:"
  jq '.projects[].languages[] | select(.validatedPercentage < 100) | "\(.language): \(.validatedPercentage)%"' status.json
  exit 1
fi

Best Practices​

  • Authentication: Ensure you are authenticated before running commands. Use npx branchlate@latest login to authenticate or set BRANCHLATE_TOKEN for CI/CD environments.
  • Configuration file: The branchlate.json file stores your project configuration and should be version-controlled.
  • Branch names: By default, the CLI uses the current Git branch name. Use the --branch-name option to specify a different branch if needed.
  • Error handling: The CLI provides error messages for common issues. If you encounter an error, ensure your configuration is correct and you have the necessary permissions.
  • Sub-projects: If your project uses sub-projects, ensure they are defined in your branchlate.json and understand how the sync command handles them.
  • Reference language: Define a reference language in your branchlate.json to control which keys are synchronized and maintain consistent key order across languages.
  • Flattened keys: Use the --flatten option if you prefer flat translation keys with dot notation. This can simplify key management and improve consistency.
  • Auto-translation: Use --auto-translate to automatically generate translations for new keys. Combine with --no-wait in CI/CD environments to avoid delays.
  • Formatting: Use format to keep translation files consistently sorted and indented. Use format --dry-run to preview changes before applying them.
  • Release checks: Use status in CI on release branches to ensure translations are 100% validated and in sync before deploying. The command exits with a non-zero code when coverage is insufficient or files are out of sync.
  • Non-interactive mode: When using BRANCHLATE_TOKEN, the CLI operates in non-interactive mode. The --force and --ignore-not-found options are automatically enabled, preventing the CLI from prompting or failing in automated scripts.

For further assistance or to explore more features, refer to the following sections: