Branches

Branching is currently in private beta. Contact us to try it out.

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

If you are interested in using the branching feature in private beta, please contact us, and we enable it for your account. Additionally, you then have to enable the feature in the Project Settings of each project where you want to work with branches.

Working with Branches

Create a new branch

If branching is enabled for your account, and you are assigned the manager or developer role in your project, you can create a new branch via the Translation Center, our API or command line client (CLI). Because the feature is still in beta stage, we recommend testing it with a separate test project instead of your actual project.

To create a new branch via the 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 

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

$ phraseapp push --branch 

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 our API or command line client (CLI) run

$ phraseapp branches list 

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

$ phraseapp branch delete  


Merge branches and solve conflicts

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 our API or command line client (CLI) you can also choose between the two merge strategies by running:

$ phraseapp branch merge <project_id> <branch_name> --strateg <use_ma
ster/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 & comments)
  • Translations

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

Push & Pull with a specific branch

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.

API endpoints supporting the branch parameter

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"}"

FAQs

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 PhraseApp. 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 PhraseApp 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) and are not copied into the main project when merging it.
  • 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.
  • Notifications are currently not triggered when something happens in a branch.

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

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

$ 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 PhraseApp?

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.

Are Jobs created in a branch also visible in the main project?

Jobs are currently not connected to the branching feature, but this is planned for the future.

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?

No you don’t.

How do translators know on which branch they should work?

The best way currently is to tell them explicitly on which branch they should work and how they can select it. But as explained above, we recommend using this early version of the branching feature only in a test project until is is developed further.

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.

Did this answer your question?