Skip to main content

Workflow with Git

Branchlate mirrors your Git branching model. Each Git branch maps to a Branchlate branch, so translations follow the same lifecycle as your code: develop on feature branches, merge into main, and release with confidence.

This guide walks through a complete workflow covering feature development, release branches, hotfixes, and CI automation.

How branches map​

Every time you run sync, Branchlate uses your current Git branch name (or the --branch-name option) to create or update the corresponding branch on Branchlate.

This 1:1 mapping means:

  • Feature branches get their own isolated translation workspace.
  • Main / develop holds the source of truth for validated translations.
  • Release branches can be checked for completeness before shipping.

Where translations come from​

Branchlate is not only a translation engine — it is a collaboration and validation platform. Translations can come from multiple sources:

  • Developers writing translations directly in code, often with the help of AI tools (Claude Code, Copilot, etc.)
  • Translators or business teams editing values on the Branchlate app
  • Branchlate's built-in AI translation via --auto-translate (optional)

Regardless of where translations originate, Branchlate is where the team reviews, validates, and tracks them. The sync command is the bridge between your codebase and Branchlate: it pushes local changes up and pulls validated changes down.

Complete workflow​

Here is a typical workflow combining Git branching and Branchlate:

Step-by-step​

1. Start a feature branch​

Create a Git branch and make your code changes — add new keys, update existing values, translate with whatever tools you prefer.

git checkout -b feature/new-screen
# ... edit code, add/update translation keys ...
tip

Many developers use AI assistants like Claude Code to generate translations directly in their JSON files. This works great with Branchlate — just sync when you're done, and the team can review everything on the platform.

2. First sync​

Run sync to push your local translation files to Branchlate. This creates the branch and uploads all keys and values.

npx branchlate@latest sync

Branchlate now shows the branch with all your keys. Share the link with your team so they can review and validate.

3. Invalidate translations when updating source text​

If you change the meaning of a reference language value (e.g., the English wording of an existing key), the translations in other languages may become stale. Use --invalidate-updated-keys to flag them as "Update needed":

npx branchlate@latest sync --invalidate-updated-keys

The values the code changes and the other values of these keys get a red chip, so reviewers see them flagged on Branchlate, except the values validated on Branchlate (green chip) and those added by the code and not changed since: invalidate them on Branchlate if they must be reviewed again. See what the flag does exactly.

tip

Only use --invalidate-updated-keys when you've changed the meaning of a key's value. If you're just fixing a typo that doesn't affect other languages, a regular sync is enough.

4. Pull translations back​

After the team validates their work on Branchlate, run sync again to pull the reviewed translations into your local files:

npx branchlate@latest sync

The CLI merges remote changes into your files following precedence rules: values validated or waiting for review on Branchlate take precedence, while the values last written by the code are updated from your local files.

5. Merge and clean up​

Once the feature is complete and translations are validated, merge into your main branch and sync:

git checkout main
git merge feature/new-screen
npx branchlate@latest sync

Then clean up the feature branch on Branchlate:

npx branchlate@latest branch delete --branch-name feature/new-screen

Release and hotfix branches​

For release workflows with dedicated branches:

Release branches​

Before shipping a release, ensure translations are complete:

git checkout release/1.1
npx branchlate@latest sync
npx branchlate@latest status --min-coverage=100

The status command exits with code 1 if any language is below 100% validated, blocking the release pipeline.

Hotfix branches​

Hotfixes follow the same pattern. Even a one-line fix can include a translation change:

git checkout -b hotfix/fix-typo
# Fix the translation in code
npx branchlate@latest sync

If the hotfix doesn't need to go through Branchlate (e.g., a quick fix directly in the translation files), you can skip sync and use --local to verify key completeness:

npx branchlate@latest status --local

CI/CD integration​

Automate the workflow in your CI pipeline:

On every push (feature branches)​

Sync translations so the team always sees the latest keys on Branchlate:

npx branchlate@latest sync

On release branches​

Check that everything is validated and in sync before deploying:

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

On merge to main​

Sync the merged translations and delete the feature branch on Branchlate:

npx branchlate@latest sync
npx branchlate@latest branch delete --branch-name ${MERGED_BRANCH}

On any branch (fallback)​

If some branches are synced with Branchlate and others are not, use --fallback-to-local to handle both cases. It runs the full remote check when the branch exists on Branchlate, and falls back to a local key-completeness check when it doesn't:

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

Authentication​

Generate a token locally, named after the pipeline that will use it, and add it to your CI environment:

npx branchlate@latest generate-token --name "GitHub Actions"

Set it as the BRANCHLATE_TOKEN environment variable, stored as a secret. When this token is present, the CLI runs in non-interactive mode and all confirmation prompts are automatically accepted.

CI tokens do not expire. List them with npx branchlate@latest token list and revoke the ones you no longer use with npx branchlate@latest token revoke <id>. See Securing CI/CD tokens.

Sync precedence rules​

sync compares each local value with the value on Branchlate. Who wins depends on the review status of the Branchlate value, shown by a chip next to it:

Review status on BranchlateHow a value gets itCounted by status as
No chipWritten by sync from your filesValidated
Red chip ("Update needed")Auto-translated, empty, invalidated on Branchlate, or flagged by --invalidate-updated-keys or --forceUnvalidated
Green chipValidated or edited on BranchlateValidated

Values pushed by the code therefore count as validated in status, but they have no chip, and the code still owns them:

Local valueBranchlate valueWho wins?Why
"Hello""Hello"No changeValues are identical
"Hello""Hi", no chipLocalValues written by the code are owned by the code
"Hello""Hi", red chipBranchlateA value waiting for review belongs to Branchlate
"Hello""Hi", red chip, + --invalidate-updated-keysLocalThe flag lets the code overwrite values waiting for review; the value keeps a red chip
"Hello""Hi", green chipBranchlateValidated values are protected
"Hello""Hi", red or green chip, + --forceLocal, for the conflicts you confirmThe value gets a red chip. With --yes or BRANCHLATE_TOKEN, every conflict is resolved this way without asking
"Hello"emptyLocalMissing values are filled from local
missing from a translated language file"Hi"BranchlateThe key is added back to the local file
missing from the reference language file"Hi"DeletedThe key is deleted on Branchlate in every language

In short: values validated or waiting for review on Branchlate are protected from the code by default, values written by the code are not. Only --force lets the code overwrite a validated value.

The reference language file defines the keys

With a referenceLanguage, removing a key from the local reference language file deletes it on Branchlate in every language, even if other local files still contain it and its translations are validated. Without a referenceLanguage, a key is deleted when it is missing from every local file. sync asks no confirmation before deleting keys.

Sync from an up-to-date copy​

sync compares your files with the current Branchlate values only: it doesn't know what your files looked like at the previous sync (there is no three-way merge). Syncing from an outdated copy of a branch, for example before pulling the latest commits, therefore:

  • re-creates the keys deleted on Branchlate since then;
  • restores the old text of the values without a chip, including in the reference language.

Values with a red or green chip are not affected. Pull or rebase your Git branch before running sync.

--invalidate-updated-keys in detail​

For each key whose value the code changes, --invalidate-updated-keys:

  • lets the code value overwrite values waiting for review (red chip);
  • flags the values the code changes, including in the reference language, as "Update needed" (red chip);
  • flags the other values of the key as "Update needed", except the values validated on Branchlate (green chip) and the values added by the code and not changed since.

The values created during that sync, including new keys, are also flagged as "Update needed". Use it when you've changed the meaning of a source text and want translators to review the translations again; invalidate on Branchlate the validated translations that must be reviewed again.

Summary​

StepCommandWhen
First sync on a new branchnpx branchlate@latest syncAfter creating a feature branch
Invalidate after source text changenpx branchlate@latest sync --invalidate-updated-keysWhen reference language values change meaning
Pull validated translationsnpx branchlate@latest syncAfter the team finishes reviewing
Check coverage before releasenpx branchlate@latest status --min-coverage=100In release CI pipeline
Quick local checknpx branchlate@latest status --localFor branches not synced with Branchlate
Clean up after mergenpx branchlate@latest branch delete --branch-name <branch>After merging a feature branch
CI on all branchesnpx branchlate@latest status --fallback-to-localUniversal CI step