Workflow
Branches
Branches let you work on translations in isolation — just like Git branches for code. Create a branch, make changes, review them, and merge back into main when ready.
How it works
Create a branch
Branch off from main to start working in isolation.
Make changes
Add, edit, or delete translation keys on your branch. Main stays untouched.
Review the diff
See exactly what changed before merging — added, modified, and deleted keys.
Get approval
If approval is required, a team member reviews and approves the branch.
Merge
Merge your branch into main (or the configured default target). Changes go live.
Branch statuses
| Status | Meaning |
|---|---|
Open | Active branch. Can be edited, synced, and merged. The branch overview shows no badge for it: open is the absence of a marker, not a marker of its own. |
| Merged | Branch has been merged into the target. Changes are live. Can be deleted. |
Open branches that have seen no activity for 14 days are additionally flagged as Stale. That is a marker, not a status: the branch stays fully editable, syncable, and mergeable. The API reports it as the separate isStale field.
The merge target and protected branches are exempt in the UI: they are long-lived by design, so the branch overview shows no Stale badge for them and leaves them out of the stale count. The API still reports their isStale value unchanged.
Finding a branch
Above a handful of branches the list is searched rather than scrolled. The row of controls over it narrows the list by name and by three questions, and the sort select decides the order of what is left. Filters combine: Needs review and Mine together is "my branches that somebody still has to look at".
| Control | Keeps |
|---|---|
| Search | Branches whose name contains what you typed. Case does not matter. |
| Needs review | Branches carrying at least one change nobody has approved yet — the same set the review queue lists across all your projects. |
| Mine | Branches you created. |
| Stale | Open branches untouched for 14 days — see Branch statuses. Protected branches and the merge target are exempt. |
Waiting longest in the sort select orders by the oldest change still awaiting review, not by when the branch was last touched: a branch renamed this morning does not jump ahead of one whose changes have been sitting since March. It is the same order the review queue is in.
Above ten matches the list is paged. When a filter or the search leaves nothing, the list says so and offers to clear them — an empty list under an active filter never means the branch is gone.
Branch operations
Create a branch
Go to your project's Branches tab and click New Branch. Give it a name (e.g. feature/checkout-flow). The branch is created from main with a snapshot of all current translations.
Edit on a branch
Switch to your branch in the translation editor using the branch dropdown. All changes are isolated — they won't affect main until you merge. You can add keys, delete keys, and modify translations.
View diff
Before merging, review the diff to see all changes: added keys, deleted keys, and modified translations. The diff compares your branch against the target and only shows actual differences.
For added keys, the diff highlights entries that don't have a translation in the current locale yet. You can click Go to key to navigate directly to the key in the editor, or approve it from the diff view.
Sync from the target
A branch can pull the newer translations in at any time, as often as you like — nothing about a branch's age stops it. Sync from main sits in the branch banner, and the arrow beside it picks a different source: any other open branch of the project.
Where your branch changed a value and the source changed it too, the sync reports the count as conflicts to settle before the merge. Everything else is simply brought up to date, and the diff afterwards is the same diff as before — only against newer content.
Merge
When your translations are ready, merge the branch into the target (main by default, or a custom default merge branch). Merge metadata is recorded: who merged, when, and stats (keys added, deleted, modified).
Approval workflow
Projects can require approval before merging. Enable Require approval in the project settings. When enabled, an Owner or Translator must approve the branch before it can be merged.
Review progress
The branch banner shows a progress bar with the review percentage for the current locale (e.g. "50% · 3 / 6 reviewed"). On the branches list, each branch card also displays its review progress. Both count what a reviewer actually has to look at: approving an added key approves the values that arrived with it, so those values are not counted a second time. The bar is full exactly when the branch can be merged.
Branches waiting across projects
This page is per branch. To see every branch in the organization that is waiting on you, with the longest wait first, open Reviews in the app header — What is waiting on you describes it.
Needs attention filter
When a branch has unreviewed operations, a "needs attention" badge appears in the branch banner. Click it to filter the editor to only those entries. Click again to show all entries. This filter counts all branch operations that have not been reviewed yet, regardless of whether they have a translation.
Protected branches
A protected branch cannot be renamed or deleted. Use protection on the branches other people's work depends on — the merge target, a release branch, anything long-lived — so a name nobody expected to change cannot change under a running pipeline.
Protection is not a permission: it does not stop anyone from translating on the branch. What governs whether a value can reach the target unreviewed is approval, and who may edit at all is the member's role.
How to protect a branch
Open the branch options menu (three dots) and select Protect branch. A shield icon appears next to the branch name to indicate protection. Only project Owners can protect or unprotect branches.
What protection does
- Prevents the branch from being deleted — the delete option is disabled.
- Prevents it from being renamed, which is what a CI job matching on the branch name relies on.
- When merging another branch, a protected branch cannot be auto-deleted after merge.
- The default merge target is protected automatically, and stays protected while it holds that role: unprotecting it is refused until another branch is the target.
Default merge target
By default, branches merge into main. If your workflow uses a different branch (e.g. develop), you can change the default merge target in project settings. All new merge operations will target the configured branch instead.
Choosing one
Any open branch of the project can be the target, and picking it protects that branch in the same step — so the branch everything merges into cannot be renamed or deleted by accident. A merged branch cannot be chosen; reopen it first.
Overriding it for one merge
The merge dialog offers the target, main, and every other open branch. Picking one there changes that merge only — useful for a release branch that is not going into develop yet. Main chosen deliberately and no choice at all are two different things: only the second falls back to the project's target.
What the rest of the product reads
The diff, the conflict list and Sync from… all name the same target, so a project on develop never quietly compares against main. A download without ?branch= stays the project's main content — the target decides where merges go, not what the API serves by default.
Branches & Pipeline Sync
Mergua branches integrate directly with your CI/CD pipeline. When Pipeline Sync is enabled, your Git branches and Mergua branches stay connected automatically.
Git branch created
You create a feature branch in Git (e.g. feature/checkout).
Mergua branch auto-created
Pipeline Sync detects the new Git branch and creates a matching Mergua branch. New translation keys from your code are pushed to it.
Translators work on the branch
Your team adds translations on the Mergua branch. The pipeline pulls them back into your Git branch as a Merge Request.
Git merge triggers Mergua merge
When the Git branch is merged, the pipeline notifies Mergua. With auto-merge enabled, the Mergua branch is merged too — fully automated.
For setup instructions and configuration options, see the Pipeline Sync documentation.