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.

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.

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.

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.
  • 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: