Project branching

The development process often requires you to work on multiple branches. Lokalise supports branching similar to GitHub, with some limitations (see below).

Enabling branching

If branching feature is included in your subscription plan, you need to enable it by going to project settings and ticking the Branching checkbox. Don't forget to click Save changes in the bottom afterwards.

Once enabled, Branches tab will appear in project settings. You can add, delete and merge branches there.

Creating branches

By default, a single branch called master will be created for you. You can create additional branches either by using Branches tab in project settings, or directly from a branch selection dropdown (in the Editor or at the projects dashboard).

Merging

Once you are done working on a branch and would like to merge it, there are several things you should consider:

You cannot delete a branch when there are active tasks or orders on branch.
Merging is not available when there are active tasks or orders on the target branch.
Conflicts can be resolved before merging.
Merge is irreversible.

Whenever you start the merging process, we'll check for conflicts.

You can resolve conflicts in favour of one of the branches.

Understanding merging

It is vital to understand how the merging process works, so let's discuss some examples. Suppose you have a branch named master. Then you create a new branch named develop which is based on master. Initially, these two branches are equal (meaning that the translation data, language settings, and other content is the same). Let's also suppose we have a key called welcome with the English translation "Welcome to the app!".

Scenario #1: perform changes in develop only and merge into master

In develop branch we change "Welcome to the app!" to "Welcome to our application!". The master branch has no changes. Then we merge develop into master. As a result, the master branch will now also contain the "Welcome to our application!" translation for the welcome key.

Scenario #2: perform changes in master only and merge into develop

This scenario is very similar to the first one. If you change translation for the welcome key to "Welcome to our application!" in master and then merge this branch into develop, the this new version will appear in develop branch as well.

Scenario #3: change the same translation both in master and develop and perform merge

Now suppose we have modified English translation for the welcome key in both branches:

master — "Welcome to our application!"
develop — "Welcome onboard!"

In this case if you try to merge develop into master, or master into develop, a conflict will be detected. You will need to manually pick the version to keep. The other version will be erased during the merge.

Scenario #4: perform changes in develop and merge master in develop

This is scenario is less obvious. Suppose you change welcome translation to "Welcome to our application!" in the develop branch. The master branch, however, has no changes and contains the old translation value "Welcome to the app!". If you merge master into develop, then the "Welcome to our application!" translation will be used as a result.

Effectively, that means you cannot "restore" translations that were modified in the develop using the old master versions. Why? As long as the translation in develop was modified since the branch creation, while the translation in master was left intact, we consider the develop version to be the newest. The older version cannot overwrite the newer one, therefore in this scenario you'll get "Welcome to our application!" translation as a result. If, however, you change the same translation in both master and develop then there will be a conflict as described in scenario #3.

How branching affects your project

Once you enable branching, the current version of the project becomes the master branch.

Different areas/functions of the project are now either global or branch-specific.

Project settings

Project settings are global except for the base language, which can be set per branch.

Snapshots

Snapshots are currently created only for master branch. This applies to all automatic snapshots (i.e. when applying bulk actions).

Contributors

The contributor list is global.
Contributors have access to all branches.
Language access and roles are shared across all branches.

Languages

Languages are branch-specific.
There could be merge conflicts in languages, which you resolve at the merge phase.
Base language can differ per branch if you chose to delete base language in a branch for some reason.
Changing a language (in language settings) is disabled in branching mode.

Keys

Keys are branch-specific.
There could be merge conflicts in keys, which you resolve at the merge phase.
When merging, the new key data overwrites existing key data.
Key tags do not create conflicts, they are merged.

Comments

Comments are global.
When adding comments they will be visible across all branches for the key.

Translations

Translations are branch-specific.
There could be merge conflicts in keys, which you resolve at the merge phase.
Reviewed and Unverified statuses may also create conflicts.
On merge, the translation overwrites existing data including Reviewed, Unverified and if available Custom translation statuses.
Spelling exceptions apply to all branches.
References are branch-specific.
Cross branching references are not supported, and if you will reference some other project key then it will default to master.

Glossary

Glossary is global.
Term extraction works only from master.

Translation history

Translation history is global.
In the Translation history on a branch you can see the history from master translation.
As translation history resides on master, you cannot restore history on merge if you delete the key on master and choose to restore key on merge (if there was a conflict).

Screenshots

Screenshot storage is global, however key linking is branch-specific. If you delete a screenshot it gets deleted from all branches.

Uploads

Uploads are branch-specific.

Downloads

Downloads are branch-specific.
Strings included from other projects are based on master if branching is enabled.

Activity

Activity is branch-specific.
some activity appears only on master as it's global activity e.g. adding contributor
branch activity is lost after branch is deleted (does not apply to audit logs)

Tasks

Tasks are branch-specific.

Orders

Orders are branch-specific.

Statistics

Statistics are branch-specific.

API

API requests are branch-specific.
Branching is only available in API 2.0.

Integrations

Integrations are either global or branch-specific.
GitHub, GitLab, Bitbucket are branch-specific.
Webhook, Asana, E-mail, Jira, Slack, Trello can be either global (any branch) or per branch.
All other integrations are for master only.

Offline Translations

Offline translations are branch-specific.
If an XLIFF file was downloaded from branch_a, it can only be uploaded back to branch_a, but not to branch_b. Similarly, a file downloaded from branch_b can only be uploaded to branch_b.