Localization Branch Management: Merges, Conflicts, Rollbacks and Best Practices

What is localization branching?

Localization branching is the practice of creating separate versions of a localization project so teams can work on translations for a feature, release, or hotfix without changing the main production-ready project.

In software development, teams often use branches to isolate code changes before merging them into the main codebase. Localization branching applies the same idea to translation work. Instead of sending every new source string directly into the main localization project, teams can create a branch, add or update strings there, complete translation and review, and merge the finished work back when it is ready.

In Lokalise, a branch is a separate version of a project. Each branch can have its own keys, source strings, translations, comments, and review progress. Changes made in one branch do not affect other branches until they are merged.

This makes localization branching useful for continuous localization workflows and software localization in general. Product teams can keep translating new features in parallel, while the main branch stays stable and ready for production releases.

How localization branching works in Lokalise

In Lokalise, branching works by creating separate versions of the same localization project. When branching is enabled, the current project becomes the master branch. From there, teams can create additional branches for features, releases, experiments, or hotfixes. Each branch can have its own keys, translations, languages, uploads, downloads, tasks, orders, statistics, activity, and translation history. This means translators and reviewers can work in one branch without changing the content in another branch.

For example, your master branch might contain the source string “Welcome to the app!” while a feature branch contains an updated version: “Welcome to our app.” The change in the feature branch does not affect master until you merge the branch.

When the branch is ready, you can merge it into another branch. Lokalise checks for conflicts before the merge and asks you to choose which version to keep when the same element was changed in both branches.

Some project elements in Lokalise are global and do not belong to a specific branch. Project settings, contributors, glossary, spelling exceptions, and some integrations are shared across branches. This is one of the main differences between Lokalise branching and Git-style version control: branches isolate translation work, but they do not create a fully independent copy of every project setting.

Branching in Lokalise vs. Git branching

Lokalise branching is similar to Git branching in concept, but it is not the same as Git version control.

• The similarity is simple: both systems let teams work on separate versions before merging changes back into a main branch. This makes branching useful when product and localization teams work on multiple releases in parallel.
• The difference is that Lokalise branches are project versions, not Git branches with commits, pull requests, rebases, or full version history. Merging in Lokalise means transferring localization changes from one branch to another through the merge flow. It is not the same as merging code in Git.

In other words, Git manages code history, while Lokalise branching manages isolated translation work.

Why duplicating localization projects is not recommended

Duplicating a localization project may look like a simple way to manage parallel translation work, but it usually creates more problems than it solves.

A duplicated Lokalise project is a fully separate project. It does not give you a clean merge path back into the original project. If translators update strings in both projects, someone has to compare the changes manually and decide what to copy back. That increases the risk of overwritten translations, missed keys, inconsistent terminology, and duplicated work.

Branching is usually the better option for feature releases, hotfixes, and continuous localization workflows because it keeps parallel work inside the same project structure. Teams can isolate changes in a branch, review them, resolve conflicts, and merge the finished work back into the main branch.

Project duplication only makes sense when the projects are meant to stay separate, such as a true product fork, a separate client-specific implementation, or a long-term project that will not need to merge back.

How to create and manage branches in Lokalise

Before you can create branches in Lokalise, project branching must be enabled for your project. Branching is available from the Advanced plan and above, and it is supported for Web and mobile projects.

Once branching is enabled, Lokalise creates a default master branch from the current version of your project. This branch usually acts as the main version of the localization project. From there, you can create additional branches for feature work, release preparation, experiments, or hotfixes. Every new branch in Lokalise is based on master. If you need a new branch to start from another non-master branch, you need to create the branch first, clear its content, and then copy the content from the branch you want to use as the base.

How to create a branch in the Lokalise UI

To enable branching, open your project and go to More > Settings. In the General tab, find the Miscellaneous section, select Branching and save your changes.

After branching is enabled, a Branches tab appears in the project settings. You can use this tab to create, delete, and merge branches.

You can also create a branch from the branch selection dropdown in the Editor or from the projects dashboard. This is useful when you are already working in the project and want to quickly start a new branch for a feature or release.

Naming branches

When naming branches, use clear names that match your development workflow. For example:

• feature/new-checkout
• release/2.4.0
• hotfix/payment-error
• experiment/onboarding-copy

Lokalise branch names must follow a few rules. They must start with a letter, number, or dot; end with a letter or number; and can contain letters, numbers, dots, hyphens, underscores, and slashes. Branch names must be between 2 and 100 characters long.

A simple naming convention helps developers, localization managers, translators, and reviewers understand what each branch is for. If your engineering team already uses branch names in GitHub, GitLab, or Bitbucket, mirroring those names in Lokalise can make the localization workflow easier to follow.

After the branch is created, switch to it before uploading new source strings, assigning tasks, reviewing translations, or downloading localized files. Work done in that branch stays isolated from other branches until you merge it.

How to work with branches using the Lokalise API, SDKs, and CLI

Lokalise also supports branch management through the API, official SDKs, and CLI. These options are useful when you want to connect localization branching to your development workflow, automate branch creation, or manage branches from scripts.

The Lokalise API includes endpoints for listing, creating, updating, deleting, and merging project branches. The official Node SDK exposes the same branch operations through lokaliseApi.branches(), including list, get, create, update, delete, and merge.

For example, you can list all branches in a project:

const branches = await lokaliseApi.branches().list({
  project_id: projectId,
  page: 1,
  limit: 100,
});

branches.items.forEach((branch) => {
  console.log(branch.branch_id, branch.name);
});

Create a new branch for a hotfix or feature:

const branch = await lokaliseApi.branches().create(
  {
    name: "hotfix/payment-error",
  },
  {
    project_id: projectId,
  }
);

console.log(`Created branch: ${branch.name}`);

Merge a branch programmatically with the Node SDK:

const response = await lokaliseApi.branches().merge(
  branchIdToMerge,
  {
    project_id: projectId,
  },
  {
    force_conflict_resolve_using: "master",
  }
);

console.log(`Branch merged: ${response.branch_merged}`);

The force_conflict_resolve_using option tells Lokalise how to resolve conflicts automatically during the merge. Use this carefully. For important production branches, teams should usually review conflicts manually in the Lokalise UI before merging.

The Lokalise CLI supports basic branch operations, but it does not cover the full branching workflow. In CLI v2, the available branch commands are:

lokalise2 branch create
lokalise2 branch delete
lokalise2 branch list

This means the CLI is useful for basic branch setup and inspection, but not for every branch operation. If you need to merge branches programmatically, use the Lokalise API or an official SDK instead of expecting a CLI merge command.

How branching works with GitHub and GitLab integrations

Lokalise integrations with GitHub, GitLab, Bitbucket, and Azure Repos let you exchange translation files between a Lokalise project and a repository. When project branching is enabled, the integration connects a specific Lokalise branch to a specific repository branch.

For example, when you configure the GitHub integration, you choose both:

• the branch in Lokalise, such as master or develop
• the branch in GitHub, such as main, master, develop, or a release branch

This means synchronization is branch-specific. Content moves between the Lokalise branch and the repository branch selected in the integration settings.

Advanced Git workflows with Lokalise branches

For most teams, the normal workflow is still to manage localization branches and merges inside Lokalise. You can create a branch for a feature or release, translate and review the content there, and then merge the branch back into your main Lokalise branch when it is ready. The repository integration is used to pull source files into Lokalise or push translated files back to the connected repository branch.

Automating sync with GitHub Actions? Use official Lokalise GitHub Actions to push files to Lokalise, pull translations back, apply tag-based filtering, and open pull requests automatically. Read Hands-on guide to GitHub Actions for Lokalise translation sync: A deep dive for the full setup.

However, teams with more complex Git workflows can also configure multiple integrations in the same Lokalise project. For example, one integration can connect master in Lokalise to master in GitHub, while another connects develop in Lokalise to develop in GitHub. This setup can be useful when you want localization file synchronization to follow the same branch structure as your code repository. Translators still work in Lokalise, but each Lokalise branch can sync with the matching repository branch.

For more advanced cases, teams can also use Git as the final place where branch merges happen. In that workflow, Lokalise sends translated files from different Lokalise branches to matching repository branches, and developers handle the final merge in Git. This is not required for most teams, but it can help when the repository has complex release rules, custom review requirements, or a strict pull request process.

The important point is that Lokalise branching and Git branching are connected through integration settings, but they are not the same system. Lokalise manages translation work and branch merges inside the localization project. Git manages repository branches, pull requests, and code-level merges.

Automating localization with GitLab pipelines? You can use GitLab CI/CD to upload source files to Lokalise, tag keys by Git branch, translate them in Lokalise, and download the finished translations back into your repository. This is a practical option for teams that want a tag-based workflow tied to Git branches and merge requests. Learn how in Syncing Lokalise translations with GitLab pipelines.

How to merge translation branches in Lokalise

When a branch is ready, you can merge it into another branch from Settings > Branches. In most workflows, this means merging a feature, release, or hotfix branch back into master.

Merging in Lokalise incorporates changes from one branch into another. Before the merge is finalized, Lokalise checks the source and target branches for differences and conflicts. If there are active tasks or orders on the target branch, merging is not available. You also cannot delete a branch that has active tasks or orders.

It is important to review the merge carefully because a merge operation is irreversible. Once changes are merged into the target branch, Lokalise does not provide a simple “undo merge” button.

What the merge summary shows

The merge summary shows whether each branch-specific project area is ready to merge or needs attention. This can include languages, keys, and translations.

If there are no conflicts in an area, Lokalise marks it as ready to merge. If there are conflicts, the summary shows the number of conflicts and lets you open the conflict details. For example, the merge summary can show:

• Languages: Ready to merge

• Keys: Ready to merge

• Translations: 1 conflict

From this screen, you can either resolve all conflicts using one branch or open the conflict details and review each conflict manually.

A conflict means that the same element was changed in both branches. For example, the same translation may have one value in master and a different value in a feature branch. Lokalise asks you to choose which version should be preserved before the merge can continue.

How to choose which changes to merge

When Lokalise detects a conflict, you can resolve it in two ways.

• You can resolve all conflicts using one branch. This is faster, but it should only be used when you are sure that one branch should win for every conflicting item.

• You can also open the conflict details and choose the version to keep for each item. This is safer for production branches because it lets you compare the source and target versions before deciding.

For translation conflicts, Lokalise shows the affected key and the competing translation values side by side. You can then choose to keep the version from the target branch, such as master, or the version from the source branch, such as dev.

Use manual review when conflicts affect production copy, legal text, onboarding flows, checkout flows, or any other high-impact content. The version you do not choose will be erased during the merge.

When to delete a branch after merging

Lokalise lets you delete the source branch after the merge. This is useful for feature branches, hotfix branches, and short-lived release branches that are no longer needed. Deleting merged branches keeps the project easier to manage. It also reduces the chance that translators or developers continue working in an outdated branch by mistake.

Do not delete a branch immediately if it still has active tasks, translation orders, unresolved review work, or content that your team may need to inspect after release. Branch activity is branch-specific and can be lost after the branch is deleted, so keep the branch until the release is complete and any post-release checks are finished.

A good rule is to delete short-lived branches after the merge has been verified in the target branch and the localized files have been successfully delivered to your app or repository.

How to resolve merge conflicts in localization keys

A localization merge conflict happens when the same branch-specific element is changed in both the source branch and the target branch before the merge. In Lokalise, conflicts can happen for languages, keys, and translations.

For example, if the welcome key has one English translation in master and a different English translation in develop, Lokalise cannot know which version should win automatically. Before the merge can continue, you need to choose which version to keep.

This is different from a normal one-way update. If a key, translation, or language was changed in only one branch, Lokalise can usually merge that change without asking for a manual decision.

What causes localization merge conflicts

Localization merge conflicts usually happen when the same key, translation, or language is changed in two branches before one branch is merged into the other.

Below are the most common merge scenarios.

Scenario 1: Only one branch changes a translation

This is the simplest merge case.

Suppose master and develop both start with the same key: welcome = “Welcome to the app!”

Then the translation is changed in develop: welcome = “Welcome to our application!”

If you merge develop into master, Lokalise applies the updated translation to master.

There is no conflict because only develop changed the translation. The same logic works in the other direction: if only master changes the translation and you merge master into develop, Lokalise applies the master version to develop.

Scenario 2: Both branches change the same translation differently

A conflict appears when both branches change the same translation in different ways.

For example:

• master: welcome = “Welcome to our application!”
• develop: welcome = “Welcome onboard!”

If you merge develop into master, Lokalise detects a conflict because both branches contain different updated versions of the same translation.

Before the merge can continue, you must choose which version to keep. The version you do not choose is erased during the merge.

Scenario 3: One branch deletes a key while another branch updates it

Conflicts can also happen when one branch deletes a key and another branch updates that same key.

For example:

• master: the welcome key was deleted
• develop: welcome = “Welcome to our application!”

If you merge develop into master, Lokalise shows a conflict because one branch removed the key while the other branch changed it.

If you merge master into develop, Lokalise does not automatically remove the key from develop. In this case, the updated key in develop stays intact.

This behavior matters because Lokalise does not treat every delete as a command to remove the key from every branch. The merge result depends on where the newer change exists and whether the same element was changed in both branches.

Scenario 4: An unchanged branch does not restore an older value

Branch merging should not be used as a rollback tool.

Suppose master still has the original value: welcome = “Welcome to the app!”

But develop changed the same translation: welcome = “Welcome to our application!”

If you merge master into develop, Lokalise does not restore the old master value. The newer develop value remains because master did not change after the branch was created.

If you need to recover an earlier project state, use project snapshots. If you need to restore a previous value for a specific translation, use translation history or update the affected string manually.

How Lokalise shows conflicted strings during merge

When you start a merge from Settings > Branches, Lokalise checks for conflicts before finalizing the merge. The merge summary groups the result by area, such as languages, keys, and translations. Areas without conflicts are marked as ready to merge. Areas with conflicts show the number of conflicts and a Show button.

For translation conflicts, Lokalise displays the affected key and the competing translation values from each branch. You can choose which version to preserve. For example, you may choose the version from master or the version from develop.

You can resolve conflicts in two ways:

• Use Resolve all using master or Resolve all using develop when one branch should clearly win for every conflict.

• Use Show and review conflicts one by one when different keys need different decisions.

Manual review is usually safer for production content. Use it for high-impact strings such as checkout copy, legal text, onboarding flows, pricing pages, error messages, and release-critical UI text.

When you resolve a conflict, the selected version is kept in the target branch after the merge. The other version is removed as part of the merge, so review carefully before continuing.

Best practices to prevent merge conflicts

1. Keep localization branches short-lived. The longer two branches exist independently, the more likely they are to modify the same keys, translations, or languages in different ways.
2. Sync branches frequently. If a feature branch lives for more than a few days, merge the latest changes from the main branch into it regularly. This helps surface conflicts earlier, while the context is still fresh.
3. Avoid editing the same keys in multiple active branches. If two teams need to update the same source strings, decide which branch owns the change before translators start working.
4. Use clear branch names. Names like feature/new-checkout, release/2.4.0, and hotfix/payment-error make it easier to understand why the branch exists and whether it should be merged, reviewed, or deleted.
5. Add new languages to the master branch first. We recommend adding languages to master before using Lokalise branches for translation work, because branch-only languages can cause inconsistent behavior in permissions, bulk actions, and some API responses.
6. Do not use branch merging as rollback. Merging an unchanged older branch into a newer branch does not necessarily restore old translation values. If you need recovery, use project snapshots or manually restore the affected strings.
7. Review conflicts manually before merging into production. Bulk conflict resolution is fast, but it can overwrite valid translations if both branches contain important changes. Use Resolve all only when you are sure one branch should win everywhere.

How to restore previous translation versions in Lokalise

Lokalise supports translation recovery through project snapshots, translation history, and bulk undo. These tools help you recover from bad uploads, incorrect bulk actions, accidental translation changes, or other project-wide mistakes.

A snapshot is the broadest recovery option. It captures a complete backup of the project at a specific point in time, including translation keys, values, contributors, settings, and other project data. If something goes wrong later, you can restore from that snapshot and return to the earlier project state.

However, snapshots should not be treated as a simple “undo merge” button. Restoring from a snapshot creates a copy of the project from that snapshot. It does not directly overwrite the current project, and the restored copy has a different project ID. That makes snapshots useful for recovery, but they are not the same as reverting a Git merge or rolling back one branch operation.

What project snapshots do

Project snapshots let you save the state of a Lokalise project before major changes. You can create a snapshot manually from More > Settings > Snapshots.

You can also use automatic snapshots. Lokalise can create snapshots during file uploads, after certain bulk actions, and on a daily schedule for users on supported plans.

Creating a snapshot before high-risk work is a good habit. For example, take a snapshot before:

• uploading a large set of source files
• importing translations from a vendor
• running bulk actions
• applying translation memory at scale
• clearing or replacing translations
• making major project configuration changes
• merging important branch changes into master

If the change causes a problem, the snapshot gives you a recovery point. Snapshots are project-level backups, so they are best for large recovery scenarios. If only a few translations were changed incorrectly, translation history or bulk undo may be a better option.

Why snapshots are not the same as undoing a merge

A snapshot restore is not the same as undoing a branch merge. It is a project recovery tool, not a merge rollback tool. Here’s what to keep in mind:

1. Restoring a snapshot creates a new project copy. Lokalise does not overwrite your current project directly. Instead, it creates a separate project based on the saved snapshot.
2. The restored project has a different project ID. This matters if your setup depends on the original project ID. API scripts, repository integrations, CI/CD jobs, OTA workflows, and internal tools may need to be updated if you decide to use the restored project going forward.
3. Snapshots only include the master branch. Data from other branches is not included, so snapshots should not be treated as backups of your full branching structure.
4. Some project data is not restored. Project tasks, workflows, glossary tags, OTA tokens, and OTA bundles are not included in snapshot restores.
5. Translation history is no longer included in snapshots starting from October 2025. If you need to restore an older version of a specific translation, use translation history instead of relying on a snapshot.

Because of these limits, snapshots should not be described as branch rollback. A snapshot can help you recover a previous project state, but it does not reverse a specific merge inside the original project.

When to restore from a snapshot instead of re-translating

Restore from a snapshot when the problem is broad, hard to isolate, or risky to fix manually.

A snapshot restore can make sense when a large upload replaced many translations incorrectly, a bulk action affected too many keys, a bad import damaged multiple languages, or a production-ready project needs to be compared against a known clean state.

Do not restore from a snapshot for every small mistake. If only a few keys or translations are affected, use translation history instead. Translation history lets you restore selected translations to previously saved versions without creating a full project copy.

Bulk undo can also be a better fit when the problem came from a specific bulk action, such as applying translation memory, pseudolocalizing, clearing translations, or copying source text to target languages. In that case, undoing the specific bulk action is usually cleaner than restoring the whole project.

A practical recovery workflow is:

1. Check whether the issue affects a few translations, a bulk action, or the whole project.
2. Use translation history for targeted translation recovery.
3. Use bulk undo for supported bulk actions.
4. Use a snapshot restore only when the project needs to return to a broader saved state.
5. Before using the restored project in production, check integrations, project IDs, OTA setup, tasks, and branch-related data.

For branch-based workflows, the safest approach is prevention: keep unfinished work in feature or release branches, review conflicts before merging, and take a snapshot before major changes to master.

Localization branching best practices

Good localization branch management keeps translation work isolated without making the project hard to maintain. The goal is to use branches when they help your team ship safely, while avoiding too many long-running branches that drift away from master.

Use these best practices to keep branching clean and predictable:

1. Keep branches short-lived. Create branches for specific features, releases, experiments, or hotfixes, then merge and delete them when the work is complete. Long-lived branches are more likely to drift from master, create conflicts, and contain outdated translations.
2. Use clear branch names. A branch name should explain why the branch exists. Names like feature/new-checkout, release/2.4.0, and hotfix/payment-error are easier to understand than vague names like updates or new-copy. If your engineering team already uses a branch naming convention, reuse the same pattern in Lokalise where it makes sense.
3. Treat master as the production-ready branch. For most teams, master should contain the strings and translations that are safe to ship. Feature work, experimental copy, and incomplete translations should stay in separate branches until they have been translated, reviewed, and approved.

4. Limit who can contribute to master. In each Lokalise project, contributors have project-level permissions, including the Contribute to master branch permission. If this permission is enabled, the contributor can make changes in master. If it is disabled, they cannot contribute directly to master. This is the closest Lokalise pattern to protecting a production branch. It does not work like full Git branch protection: you cannot allow a contributor to edit one non-master branch while blocking them from another specific non-master branch. Branch-level access control is focused on master.

5. Sync active branches regularly. If a branch stays open for more than a few days, bring changes from master into that branch before the final merge. This helps teams find conflicts earlier and reduces the chance of a difficult merge right before release.
6. Review merge summaries before merging. The merge summary shows whether languages, keys, and translations are ready to merge or have conflicts. Do not treat merging as a blind final step. Check added, changed, deleted, and conflicted content before applying changes to the target branch.
7. Resolve important conflicts manually. Bulk conflict resolution is useful when one branch clearly owns the correct version, but it can overwrite useful work. For production copy, checkout flows, legal content, pricing, onboarding, and critical error messages, review conflicts one by one.
8. Take snapshots before high-risk changes. Before large uploads, bulk actions, major imports, or important merges into master, create a project snapshot. Snapshots are not the same as undoing a merge, but they give you a recovery point if a broad project-level issue appears later.
9. Do not use project duplication as a normal branching workflow. Duplicated projects are hard to merge back, easy to drift apart, and more likely to create inconsistent terminology. Use separate projects only when the products, teams, or clients are meant to stay separate long term.
10. Use repository integrations carefully. GitHub, GitLab, Bitbucket, and Azure Repos integrations can connect specific Lokalise branches to specific repository branches. This is useful when localization should follow your release structure, but remember that Lokalise branching and Git branching are not the same system. Use Lokalise for translation branch management and Git for repository-level pull requests and code merges.
11. Delete branches when they are no longer needed. After a branch has been merged, verified, and released, delete it unless your team has a reason to keep it. Cleaning up old branches helps translators and developers avoid working in the wrong place.

Using tags as a simple alternative to branches

If project branching is not available on your Lokalise plan, tags can be used as a lightweight alternative for organizing feature or release work.

Instead of creating a separate branch, you can tag related keys with a feature, release, or task name. For example, you might use tags like feature-new-checkout, release-2-4-0, or hotfix-payment-error. Then you can filter keys by tag in the editor, assign translation work for that tagged group, and export only the strings that belong to a specific tag.

This approach can work well for small teams, simple releases, or projects where you only need to group and filter translation keys. It is also useful when you want a quick way to separate new feature strings from the rest of the project.

However, tags are not the same as branches.

• Tags do not create a separate version of the project.

• They do not isolate translations from master, do not provide a merge workflow, and do not detect merge conflicts.

• If the same key is edited for two releases, tags will not preserve separate versions of that key.

Use tags when you need simple organization and filtering. Use project branching when you need isolated translation work, branch merging, conflict resolution, or a workflow that follows multiple parallel releases.