1. Help Center
  2. Phrase for Developers
  3. How to use Version Control with Phrase


This guide describes how to work with branches in localization.


What is branching?

Branching is a concept typically used in software version control. It is the practice of creating copies of programs, also called branches, which enables teams to work in parallel versions at the same time whereas retaining the original, and without the risk of overwriting others’ changes (e.g. code or translations) unintentionally.

How to enable branching

Enable the branching feature in the Project Settings of each project:

You can also select Protect Master Branch. When this is enabled, you will not be able to make any changes to the Master Branch. You can then only work in side branches and merge those into the Master Branch.

Working with Branches

Create a new branch

Users with the role "Manager" or "Developer" can create a new branch via Translation Center, API or command line client (CLI).

To create a new branch via Translation Center, click “Create branch” in the “Branches” dropdown, always visible on the right-hand side, or in the “Branches” Section of your project. After creating you can select the new branch via the “Branches” dropdown.

To create a new branch via our API or command line client (CLI) run:

$ phraseapp branch create --name <branch_name>

or create a branch on-the-fly when pushing translations:

$ phraseapp push --branch <branch_name>

Select a branch

You can easily switch between different branches in the “Branches” dropdown. The highlighted branch is always the one you are currently working in.

To specify a branch for the execution of command line arguments via your terminal or our command line client (CLI) simply add the following parameter:

--branch <branch_name>

Manage branches

You can manage all existing branches of your project in the “Branches” section. Here you get an overview of all your created branches and all other branches. You see when a branch was last changed, when it was created and by whom, and if it has already been merged into the main project. You can delete one or multiple branches and merge a ready branch into the main project as shown below.

To list all branches for a project via API or command line client (CLI) run:

$ phraseapp branches list <project_id>

To delete a branch via API or command line client (CLI) run:

$ phraseapp branch delete <project_id> <branch_name>

Merge branches

When all required changes are made and a branch is not needed anymore, you can merge it into the main project to synchronize the translations.

To merge a branch via the Translation Center, go to the “Branches” section of your project and click “Compare and Merge”. Then you get an overview of all changes which will be made in your main project and, if existing, all occurring conflicts. Fold out a conflict to see it in detail. To solve the conflicts you can currently choose between two merge strategies. “Use Branch” applies all changes made in the selected branch to the main project, whereas “Use Main Project” rejects the changes and takes the status of the main project.

If there are no conflicts but you want to know e.g. which translations will be modified after a merge and how, simply click on the corresponding colored cell in the table.

To merge a branch via API or command line client (CLI) you can also choose between the two merge strategies by running:

$ phraseapp branch merge <project_id> <branch_name> --strategy <use_master/use_branch>

use_branch merges branch and main project by applying all changes made in the branch.
use_master merges branch and main project but doesn’t apply the changes made in the branch. When no strategy is specified the default is use_branch.

Please be aware that currently only changes to the following resources will be applied to the main project when merging a branch:

  • Locales
  • Keys (except screenshots)
  • Translations

Other changes, especially to the following resources, will currently NOT be applied: Activities, Jobs, Orders.

Push & Pull

You can specify a branch for push & pull via our command line client (CLI) by running:

$ phraseapp push --branch <branch_name>
$ phraseapp pull --branch <branch_name>

If the specified branch doesn’t exist in your current project, a new one will be created.

You can also use --use-local-branch-name to push and pull using the branch name of your currently active git branch:

$ phraseapp push --use-local-branch-name
$ phraseapp pull --use-local-branch-name


All API endpoints which take a project argument now also support the additional branch parameter to perform an action on a specific branch of the selected project:

$ phraseapp upload create <project_id> \
  --branch <branch_name>
  --file /path/to/my/file.json \
  --file-format json \
  --locale-id abcd1234cdef1234abcd1234cdef1234 \
  --tags awesome-feature,needs-proofreading \
  --locale-mapping "{"en": "2"}" \
  --format-options "{"foo": "bar"}" 


For a demo and more information on the benefits of branching, you can also watch our Webinar on Branching and Versioning.
After entering your contact information you will be able to access the webinar.

What is the difference between main project and branch?

The most significant difference is that the main project is always the origin of a new branch and is not treated as an own branch in Phrase. Moreover, branches are always merged into the main project, and not the other way round.

Are changes in a branch also applied to the main project?

No. Only when you merge a branch into the main project.

Can several teams work on several branches at the same time?

Yes. Teams can work on several branches within Phrase as they might do it with a version control system in software development.

Are there any limitations when working in a branch?

Yes. Currently, you encounter the following limitations:

  • Jobs created in a specific branch are not visible in the main project (also the other way round). Open Jobs in a branch thus get lost when merging it.
  • Statistics under the Reports tab reflect only the status of the selected branch. When merging it, the main project’s statistics get updated according to the changes.
  • Activity view only contains the activities of the selected branch and are not visible in the main project (also the other way round). They get lost when merging the branch.
  • GitHub Sync cannot be used in a branch but only in the main project.
  • Comments made in a specific branch are not visible in the main project (also the other way round).
  • Orders created in a specific branch are not visible in the main project (also the other way round). Open orders in a branch thus get lost when merging it.

Can a new branch automatically be created when pushing via CLI?

Yes. When you specify the name of a non-existing branch during a push, a new branch gets automatically created:

$ phraseapp push --branch <branch_name>

How long does a branch exist?

A branch exists until it has been merged into the main project and deleted. All merged branches are still visible in the “Branches” section, marked as “merged”. What happens with a branch after merging it into the main project? The branch gets closed and marked as “merged”. You can see all merged branches in the “Branches” section, but you cannot open a merged branch anymore to work on it again. Therefore, you always have to create a new branch from the current main project.

Can I reopen a merged branch?

No. A merged branch cannot be reopened, you always have to create a new one.

Can I revert a merge?

No. This is currently not possible.

Can I undo deleting a branch?

No. You currently can’t undo deleting a branch.

What is a conflict in Phrase?

A conflict always occurs when a resource (translation, key, locale) has been changed both in the main project and the compared branch. For example:

  • translation has changed in both the project and branch but with different content
  • key settings (like pluralization) are different in project and branch

What happens with comments made on a key in a specific branch?

Currently, all comments made in a specific branch only are displayed in the currently selected branch, but not in the main project.

Can a branch be merged into another branch?

No. Currently, it is only possible to merge a branch into the main project.

Do I need to change my .phraseapp.yml config file when working with branches?

Your configuration file can be used without further adjustments unless you are referencing hashed locale ids via the locale_id parameter. Locales on branches have a separate unique ID. However, you can work around this by using the locale name instead.

How do translators know on which branch they should work?

Translator can be given permission to work on a certain locale, but can't be restricted to a specific branch. The best way currently is to tell them explicitly on which branch they should work and how they can select it.

Why do I get the error message “Access Denied”

To access the “Branches” section and to manage branches you need to have a manager or developer role in your project.

Can I use a different branch when working with the In-Context Editor?

Yes, you can initialize the In-Context Editor for a specific branch by adding the branch configuration value. See our article Configure In-Context Editor for further information.