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 ...
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 update a reference language value (e.g., changing the English wording of an existing key), the translations in other languages may become stale. Use --invalidate-updated-keys to flag every language value for those keys as "needs update":
npx branchlate@latest sync --invalidate-updated-keys
This marks all language values of each updated key as unvalidated, so reviewers see them flagged on Branchlate.
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: validated and auto-translated values from Branchlate take precedence, while unvalidated values do not overwrite your local work.
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 and add it to your CI environment:
npx branchlate@latest generate-token
Set it as the BRANCHLATE_TOKEN environment variable. When this token is present, the CLI runs in non-interactive mode and all confirmation prompts are automatically accepted.
Sync precedence rules
Understanding which value "wins" during a sync helps avoid surprises:
| Local value | Remote value | Who wins? | Why |
|---|---|---|---|
"Hello" | "Hello" | No change | Values are identical |
"Hello" | "Hi" (validated) | Remote | Validated translations take precedence |
"Hello" | "Hi" (auto-translated) | Remote | Auto-translated values take precedence |
"Hello" | "Hi" (unvalidated) | Local | Unvalidated remote values don't overwrite local |
"Hello" | null | Local | Missing remote values are filled from local |
| missing | "Hi" | Remote | Key added locally from remote |
When using --invalidate-updated-keys, updated keys have all their values set to unvalidated. On the next sync, local values will take precedence for those keys — allowing you to push updated translations from your codebase.
Summary
| Step | Command | When |
|---|---|---|
| First sync on a new branch | npx branchlate@latest sync | After creating a feature branch |
| Invalidate after source text change | npx branchlate@latest sync --invalidate-updated-keys | When reference language values change meaning |
| Pull validated translations | npx branchlate@latest sync | After the team finishes reviewing |
| Check coverage before release | npx branchlate@latest status --min-coverage=100 | In release CI pipeline |
| Quick local check | npx branchlate@latest status --local | For branches not synced with Branchlate |
| Clean up after merge | npx branchlate@latest branch delete --branch-name <branch> | After merging a feature branch |
| CI on all branches | npx branchlate@latest status --fallback-to-local | Universal CI step |