This feature is available from the Pro plan and above. It is available only for Web and mobile projects, not for Ah doc documents or Marketing and support.

For recommendations and best practices, refer to Software localization workflow document in our DevHub.

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

What is branching?

In simple terms, think of a branch as a different version of your translation project. When you use the branching feature, your project can have many separate versions. You can move between these versions, get rid of them, or take changes from one version and add them to another.

For instance, imagine your project has a welcome key with the "Welcome to the app!" translation value, and you turn on branching. You create two branches: master and develop. Initially the welcome key has identical translations in both branches. But then, you can switch to the develop branch and modify the key's value to "Welcome to our app". This change will not affect the translation value stored in the master branch (it will still contain "Welcome to the app!" text).

Now, you can choose which version you like more. If you like the original master version, just delete the develop branch. But if you prefer the new develop version, you can merge it into the master branch. Branching is great because it lets you try out different things with your translations without worrying about affecting the main version of your project.

Please be aware that certain project elements are global (in other words, do not support branching), which is explained more in the How branching affects your project section.

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):

Branch names have certain restrictions

must start with a letter or number or dot
must end with a number or letter
may contain numbers, letters, and . - _ / characters
multiple consecutive slashes are not allowed
multiple consecutive dots are not allowed
no slash-separated component can begin with a dot
no slash-separated component can end with the sequence .lock
minimum length is 2 characters
maximum length is 100 characters

Which branch is used as a base for creation?

Every new branch you create is always based on the master branch.

If you need to create a separate branch but copy content from another non-master branch, follow these steps:

Create your new branch. In this example, we'll call it staging
Remove all content from the newly created staging branch:
Switch to the branch you’d like to base your staging branch on:
Choose all keys within this branch and choose Copy/move to project from the bulk actions menu. Pick your project and the branch, tick the Include all languages, and then press Copy.
Your new branch now contains all translations from the chosen base branch.

Merging

Once you are done working on a branch and would like to merge it (incorporate changes from this branch into another one), 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.
The merge operation is irreversible.

To start the merging process, go to Settings > Branches. We'll check for any conflicts beforehand.

A conflict means that a certain element (e.g., a translation key) was modified in both branches. You have to decide which version of this element should be kept.

You can resolve conflicts in favor of one of the branches by clicking Resolve all using... or by clicking Show next to the conflict. When the Show button is clicked, you'll see a similar interface:

Now simply choose what version to preserve.

Special note on translation orders

In some cases you might see a checkbox I understand, no claims can be done further on TOs in this branch:

You'll see this checkbox if you have an active professional translation order created on the source branch, and this order is still in progress. Be aware that if the source branch is merged into the target branch, the order is not moved to the target branch. It remains valid for the source branch only.

This checkbox serves as a reminder that you won’t be able to request corrections on the source branch order because the translation history is lost.

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 identical in both branches). 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.

Here's a similar scenario but with plurals. Suppose that in develop branch we change the singular key to a plural key. The master branch has no changes. Then we merge develop into master. As a result, the master branch will now also contain the plural key.

Scenario #2:

Perform changes in master only and merge into develop.

This scenario is very similar to the first one. If you change the 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.

The same applies to converting regular keys into plural ones. If you change the key form from singular to plural 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.

The same applies to converting regular keys into plural ones. Suppose you change the singular key into the plural key in the develop branch. The master branch, however, has no changes and contains the key in a singular form. If you merge master into develop, then the plural key form will be used as a result.

Scenario #4

Perform changes in develop and merge master into develop.

This 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 welcome key 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 welcome key will be left intact (it won't be removed).

Scenario #6

Delete the welcome key in develop and merge into master.

Suppose, we delete the welcome key in the develop branch. The master branch has no changes. Then we merge develop into master. As a result, the master branch will now also get the changes for the welcome key, which means that the welcome key gets deleted on master.

How branching affects your project

Once you enable branching, the current version of the project becomes the master (main) 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, including all automatic snapshots (e.g., 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.
Merge conflicts in languages need to be resolved during the merge phase.
Changing a language (in the language settings) is disabled in branching mode.

Keys

Keys are branch-specific.
Merge conflicts need to be resolved during the merge phase.
When merging, 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 branch-specific.
Key comments are not merged when merging branches; only comments from the target branch will be preserved.

Translations

Translations are branch-specific.
Merge conflicts need to be resolved during the merge phase.
Reviewed and Unverified statuses may also create conflicts.
Upon merge, the source translation overwrites the target 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 another project key, it defaults to master.

Glossary

Glossary is global.
Term extraction works only from master.

Translation history

Translation history is branch-specific.

Screenshots

Screenshot storage is global, but 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 appear 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.

Apps

Apps (previously known as "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 the branch_a, but not to the branch_b. Similarly, a file downloaded from the branch_b can only be uploaded to the branch_b.