This feature is available from the Pro plan and above. Please note that it is available only for "Software localization" type of projects, but not for "Documents".
The development process often requires you to work on multiple branches. Lokalise supports branching similar to GitHub, with some limitations (see below).
Index
Merging
— Understanding merging (examples)
Enabling branching
If the branching feature is included in your subscription plan, you can enable it by proceeding to More > Settings:
Tick the Branching checkbox under the General tab, Miscellaneous section. Don't forget to click Save changes in the bottom afterwards:
Once enabled, the Branches tab will appear in the 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 under the Branches tab in the project settings, or directly from the 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 that has active tasks or orders.
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 beforehand.
You can resolve conflicts in favor of one of the branches.
Understanding merging
It is vital to understand how the merging process works, so let's take a look at 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, then this new version will appear in the develop branch as well.
Scenario #3: change the same translation both in master and develop and perform merge
Now suppose we have modified the English translation for our 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 into develop
This is scenario is less obvious. Suppose you change the 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.
Scenario #5: delete the welcome key in master, update the same key in develop, and then perform merge
In this case the result will depend on the target and the source branches that you choose:
If you choose to merge develop into master, then you'll see a conflict saying that the
welcomekey was removed in one branch and updated in another one.If you choose to merge master into develop, then no conflicts will be detected and as a result the
welcomekey will be left intact (it won't be removed).
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:
Automations
Automations work only for the master branch
Project settings
Project settings are global.
Snapshots
Snapshots are currently created only for the 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 and you cannot make certain branches "protected" (available only to project admins or certain contributors).
Language access and roles are shared across all branches.
Languages
Languages are branch-specific.
There could be merge conflicts in languages, which you'll need to resolve at the merge phase.
Changing a language (in the language settings) is disabled in branching mode.
Keys
Keys are branch-specific.
There could be merge conflicts which you'll need to resolve at the merge phase.
When merging, the new key data overwrites the existing key data in the target branch (check the examples above).
Key tags do not create conflicts, they are merged.
Comments
Key comments are global.
Key comments are visible across all branches.
Translations
Translations are branch-specific.
There could be merge conflicts which you'll need to resolve at the merge phase.
Reviewed and Unverified statuses may also create conflicts.
Upon merge, the source translation overwrites the target (existing) data including Reviewed, Unverified and Custom translation statuses (if enabled).
Spelling exceptions apply to all branches.
Key references are branch-specific.
Cross branching key references are not supported. If you 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 branch-specific.
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 the master if branching is enabled in the chosen project.
Activity
Activity is branch-specific.
Certain events appears only on master if it's a global activity (for example, adding a contributor).
Branch activity is lost after the branch is deleted (does not apply to audit logs).
Tasks
Tasks are branch-specific.
Orders
Orders are branch-specific.
Statistics
Statistics is 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, and other Git-related integrations are branch-specific.
Webhook, Asana, E-mail, Jira, Slack, Trello can be either global (any branch) or per branch.
All other integrations are for the master branch only.
Offline Translations
Offline translations are branch-specific.
If an XLIFF file was downloaded from the
branch_a, it can only be uploaded back to thebranch_a, but not to thebranch_b. Similarly, a file downloaded from thebranch_bcan only be uploaded to thebranch_b.