Translation Management

Branching (Strings)

Branching is used in software version control. Copies of project files called branches allow teams to work on parallel versions of the project at the same time while retaining an unedited copy. This eliminates the risk of accidentally overwriting others’ changes to project files.

The main project is copied when a new branch is created with changes being made only to that branch. When changes are complete, the branch is merged back into the main project. Multiple branches can be worked on at the same time and after merging, branches can be deleted.

A webinar is available on the topic of branching.

Limitations

  • Only Admin, Project Manager and Developer roles have access to the Branches view.

  • Merges cannot be reverted and branches cannot be undeleted.

  • Jobs created in a specific branch are not visible in the main project and vice versa. When a branch is merged into the main project, any open Jobs in it are lost.

  • Reports in the Reports view reflect only the status of the active branch. Merging a branch into the main project updates the main project reports.

  • The Activity view contains only activities in the active branch. Activities in branches aren’t visible in the main project and vice versa. Activities in a branch are lost when merging it into the main project.

  • GitHub Sync can only be used on the main project and not on branches.

  • Comments made in a branch aren’t visible in the main project and vice versa.

  • Orders created in a branch aren’t visible in the main project and vice versa. When a branch is merged into the main project, any open orders in it are lost.

  • Translators cannot be restricted to specific branches but are given permission to work on specific locales. Translators should be instructed on how to work with branches.

Enable Branching

Branching is enabled in the Advanced tab of Project Settings with the option to protect the main branch from changes.

When enabled, a branch menu branch_menu.pngis presented on the project screen where working branches can be selected. To specify a branch in CLI, use the --branch parameter:

--branch <branch_name>

Branches are listed on the Branches view where creation and merging information is presented. Branches can also be deleted or merged and jobs created for that branch from the Branches view.

To list all branches for project via API or CLI, run:

$ phrase branches list <project_id>

To delete a branch via API or CLI, run:

$ phrase branch delete <project_id> <branch_name>

Create a Branch

Admin, Project Manager and Developer roles can create new branches in the Translation Center, via API or in the CLI.

To create a branch in the Translation Center, follow these steps:

  1. From a Project page, select the Branches tab.

  2. Click Create branch.

    The Create branch window opens.

  3. Provide a name for the branch.

  4. Click Create branch.

    The new branch is added to the list.

To create a branch via API or CPI, run:

$ phrase branches create --project_id <project_id> --data <data>

To create a branch when pushing translations, run:

$ phrase push --branch <branch_name>

Merge Branches

After changes are made to a branch, it can be merged back into the main translation in order to incorporate any new translations.

Only changes to the following resources are applied to the main branch during merges:

  • Locales

  • Keys

  • Translations

Changes to other resources, such as Activities, Jobs, and Orders, are not applied.

Conflicts

A conflict occurs when a resource (translation, key, or locale) has changed in the main project between the time a branch is created and when it is merged back to the main project. For example, translations and key settings such as plural forms) may have changed in the main project after a branch is created making the values in the branch different from those in the main project.

To merge a branch, follow these steps:

  1. From the Branches view of a project, select a branch for merging and click Compare and Merge.

    The Merge branch page opens. Information about translations to be modified during the merge can be accessed by clicking in the cells.

  2. If there are conflicts, select a merge strategy:

    • Select Use Main Project to reject the conflicting changes and preserve existing translations.

    • Select Use branch_menu.png BranchName to replace existing translations with changes from the branch.

  3. Click Merge Branch.

    The branch is merged to the main project.

To merge a branch via API or CPI, run:

$ phrase branches merge \
  --project_id <project_id> \
  --name <name> \
  --data '{"strategy":"use_master"}' \
  --access_token <token>
  • use_branch resolves conflicts by applying changes from the branch and if not specified is the default.

  • use_master resolves conflicts by rejecting changes from the branch.

Push and Pull

When using CLI, specify a branch to push or pull from with the --branch parameter.

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

If the specified branch doesn’t exist in a project, the client creates it.

Use --use-local-branch-name to push and pull using the branch name of an active git branch:

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

API

All API endpoints that take a project argument also support the --branch parameter to perform an action on a specific branch of a project:

$ phrase 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"}" 
Was this article helpful?

Sorry about that! In what way was it not helpful?

The article didn’t address my problem.
I couldn’t understand the article.
The feature doesn’t do what I need.
Other reason.

Note that feedback is provided anonymously so we aren't able to reply to questions.
If you'd like to ask a question, submit a request to our Support team.
Thank you for your feedback.