Project branching

For many multilingual products, one set of translations per language is not enough. A released version still needs fixes while the next one is in development, a staging environment needs to run ahead of production, or each white-label client needs their own wording. Branching lets you keep those variants apart in a single Localizely project and move changes between them when the time is right.

Branches are flexible, so use them in whatever way fits your release process. As a rule of thumb, keep the number of branches small. Fewer branches are easier for your team to understand and keep in sync.

Typical branching use cases

Branch per app version

Use case: You have just released version 1.0 and started work on version 2.0. The new version changes parts of the interface, and the translations change with it. Meanwhile, 1.0 stays in production for months and still needs occasional fixes and additions to its translations.

This matters even more if you deliver over-the-air translation updates to apps already installed on users' devices, because each app version must keep receiving translations that match its screens.

Solution: When work on 2.0 begins, create a Version_2.0 branch from Version_1.0. Translators work on 2.0 without disturbing the released version, and you can return to the Version_1.0 branch whenever a fix is needed. Each version keeps exactly the translations that belong to it.

Once you stop maintaining 1.0, delete its branch to keep the project tidy.

Branch per environment

Use case: You want a separate set of translations for each environment your product runs in, such as Development, Stage, and Production. This is common for web applications, where the browser always loads the latest deployment and translations move through the same pipeline as the code.

Most changes start in Development, get verified in Stage, and finally reach Production.

Solution: Use one branch per environment. When translations are ready to move forward, merge the Development branch into Stage, and later Stage into Production.

Urgent fixes can go straight into the Production branch. Merge them back into the earlier environments afterwards so nothing drifts apart.

You can compare any two environment branches at any time to see exactly what differs between them.

Branch per white-label client

Use case: In white-label development, the core product lives on the main branch of your repository and is merged into a separate branch for each client. The translations need to follow the same structure: shared wording in the core, client-specific wording on top.

Solution: Keep core product translations on the main branch in Localizely and give each client a branch of their own. New features are translated once, on the main branch. When a client release is due, merge main into that client's branch, adjust any client-specific strings, and build the app.

These patterns are not mutually exclusive. You can, for example, branch per version and per client at the same time. Just keep the total number of branches as small as your process allows.

How to use branching

Branching is enabled per project. Open your project's Settings and turn it on.

Once enabled, a branch selector appears at the top of the page next to the project name. Everything you do in the project, from editing translations to uploading and downloading files, applies to the branch selected there.

The Branches item in the project menu opens the page where you manage branches: create new ones from an existing branch, delete the ones you no longer need, compare two branches, and merge changes between them.

A comparison shows every difference between two branches, and it is directional: comparing Version_2.0 with Version_1.0 shows what would change in Version_1.0 if you merged Version_2.0 into it. Review the comparison first, then merge with confidence.

Branches are also available to your automation. The configuration file used by the CLI has a branch option, so each Localizely branch can sync with the matching branch in your repository.

In case you have any questions, feel free to reach out via email support@localizely.com.