Translation Management
    1. Phrase
    2. Phrase Strings
    3. Translation Management

    Branching (Strings)

    Content is machine translated from English by Phrase Language AI.

    Available for

    • Business and Enterprise plans

    Get in touch with Sales for licensing questions.

    Available for

    • Enterprise plan (Legacy)

    Get in touch with Sales for licensing questions.

    Important

    As of December 10, 2025 the new branching is enabled by default for all new customers.

    Existing customers can opt in to the new branching model by selecting Switch to new branching in the Branches tab of a project.

    Legacy branching will be deprecated as of June 1, 2026.

    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 are automatically deleted. Merged branches remain available in the Merged tab for simplified history tracking. Tags from an existing branch are copied to the new branch.

    Limitations

    • All roles except Translator and Guest 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 are not 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 are not visible in the main project and vice versa.

    • Orders created in a branch are not 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 is 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 tab of a project, where creation and merging information is presented. Branches can also be deleted or merged and jobs created for that branch from the Branches tab.

    Tip

    Click Switch to new branching in the Branches tab to access the new branching interface and features.

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

    $ phrase branches list --project_id <project_id>

# e.g.
$ phrase branches list --project_id 1d8ae641902624df63ce6fbd64ff9549$ phrase branches list <project_id>

    To delete a branch via API or CLI, run:

    $ phrase branches delete --project_id <project_id> --name <branch_name>

# e.g.
$ phrase branches delete --project_id 1d8ae641902624df63ce6fbd64ff9549 --name test-test$ phrase branch delete <project_id> <branch_name>

    Create a Branch (Legacy)

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

    To create a branch in the translation editor, 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 (Legacy)

    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 both the main project and the branch 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 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_main"}' \
  --access_token <token>

    • use_branch resolves conflicts by applying changes from the branch and if not specified is the default.

    • use_main resolves conflicts by rejecting changes from the branch. use_master is also supported.

    Push and Pull (Legacy)

    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 does not 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 (Legacy)

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

    New Branching

    Available for

    • Business and Enterprise plans

    Get in touch with Sales for licensing questions.

    Important

    As of December 10, 2025 the new branching is enabled by default for all new customers.

    Existing customers can opt in to the new branching model by selecting Switch to new branching in the Branches tab of a project.

    The new branching experience introduces a redesigned architecture to improve performance, stability, and flexibility, and expanded version-control capabilities. It enables teams to work on multiple versions of their content in parallel, keep long-running branches up to date, and merge changes more efficiently.

    New features include:

    • Multi-level (stacked) branches

      Branches can be created from any other branch, not only the main branch. Up to 5 branch levels are supported.

    • Syncing changes between branches

      Long-running branches can become outdated as changes accumulate in their base branches. The new branching introduces a sync capability that helps prevent inconsistencies.

    Branches that remain unmerged for more than 30 days since their creation count toward Strings managed words.

    Create a Branch

    Admin, Project Manager, Designer and Developer roles can create new branches in the Branches tab, via API or in the CLI.

    To create a branch from the UI, 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. Select a Base branch from the list of existing branches.

    5. Click Create.

      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>

    Sync Branches

    Syncing ensures the working branch stays aligned with the latest changes from the branch it originated from. This way, translators can work with an updated version of content also in long-term projects.

    To sync a branch with its base branch, follow these steps:

    1. In the Branches tab, click Sync with base branch next to the desired branch.

      The Sync page is displayed with information about any conflicts and changes to be synced with the base branch.

    2. Click on any of the detected changes to review it before syncing.

      A table with details about the selected change is displayed.

    3. Select Sync and confirm to apply the changes.

      The changes are added to the base branch and become visible in the translation editor. Information about the last sync is displayed in the Synced column of the Branches tab.

    Branch sync can also be performed via API by running this CLI command:

    $ phrase branches sync \
  --project_id <project_id> \
  --name <branch_name> \
  --data '{"strategy":"use_main"}' \
  --access_token <token>

    • use_branch resolves conflicts by applying changes from the branch and if not specified is the default.

    • use_main resolves conflicts by rejecting changes from the branch and refers to the base branch. When working with stacked branches, the base branch is not necessarily the actual main project branch.

    Merge Branches

    After completing translation or version-specific work in a branch, any changes can be merged into the base branch. Once all changes are merged up the chain, the top-level branch can be merged into the main branch.

    After a successful merge, the merged branch is automatically deleted and appears in the Merged tab for history tracking.

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

    • Locales

    • Keys

    • Translations

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

    Branches with active child branches cannot be merged until the child branches are deleted or merged first.

    Conflicts

    A conflict occurs when a resource (translation, key, or locale) has changed in both the current branch and its base branch after the branch was created or last synced. Conflicts can occur at any level of the branch stack, not only when merging into main.

    To merge a branch, follow these steps:

    1. From the Branches tab of a project, click Merge with base branch next to the desired branch.

      The Merge 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 Base Branch to reject the conflicting changes and preserve existing translations.

      • Select Use Branch Menu BranchName to replace existing translations with changes from the branch.

    3. Click Merge and confirm to apply the changes.

      The branch is merged to the base branch and deleted automatically. To review merged branch history, open the Merged tab in the Branches page.

    To merge a branch via API or CPI, run:

    $ phrase branches merge \
  --project_id <project_id> \
  --name <name> \
  --data '{"strategy":"use_main"}' \
  --access_token <token>

    • use_branch resolves conflicts by applying changes from the branch and if not specified is the default.

    • use_main resolves conflicts by rejecting changes from the branch. use_master is also supported.

    The merge action also deletes the merged branch automatically.

    Push and Pull (Legacy)

    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 does not 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 (Legacy)

    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.

    Articles related to Administration

    Articles related to Project Manager