Working with branches

Working with multiple branches allows you to scale your localization process without delays. Everyone can now work in parallel.

Nina avatar
Written by Nina
Updated over a week ago

Introduction

Branch support is embedded in the core of the TX platform. You can use our API, Go CLI, or the Transifex Web Interface to work with branches

📝 Note: This feature is available on all plans.

  • Opensource: Up to 1 branch per project.

  • Basic: Up to 1 branch per project.

  • Enterprise & Premium: Unlimited branches.


Creating a Child resource

You'll need to use our API or Go CLI to create a Child resource. You must provide the resource slug you want to define as a Parent for your Child resource. Once your call is processed, the Child resource will be available in Transifex for translation.

Child resources:

  • Have a branch icon.

  • Have their Parent’s resource name in grey as part of their path name. For example, if you have the following structure:

    Then, the path for the “Child_2” resource will be the one shown below:


Changing Child’s Parent resource

You can change the Parent resource of your Child at a later point if needed using our API. If you would like to learn more about how this can be done, you can check our Developer Hub.

When you change the Parent resource of a Child, Transifex will resync your Child resource with the new Parent. Check the “How work is shared between the Child and Parent resources” section for more information.


Understanding branch states

In Transifex, you can easily detect differences between Parent and Child resources in both source and translation text. You can use the branch state filters when viewing the Child resource in the editor and get the list of strings based on that state.

AHEAD

A Child is ahead of the Parent resource when the Child has translations that do not exist on the Parent.


When applying this filter, the results you get could meet any of the following criteria:

  • Strings have translations in the Child resource but not in the Parent resource.

  • Strings in the Child resource have updated translations while the previous branch state was “in sync” i.e., the previous version of the translations in both Child and Parent resources was the same, but translations were updated later in the Child resource.

  • Strings in the Child resource have reviewed translations, while the same translations haven’t been reviewed in the Parent resource.

CONFLICT

A conflict between Parent and Child resources occurs when they have competing translations or review statuses.


When applying this filter, the results you get could meet any of the following criteria:

  • Strings with translations that were first modified in the Child resource and then in the Parent resource ending up with different translation versions.

  • Strings with translations that were first marked as proofread in the Child resource and then as reviewed in the Parent resource.

  • Strings with reviewed translations in both Child and Parent resources that, later, were marked as untranslated in Child and Proofread in Parent.

  • Strings that have been tagged as locked in the Parent resource but not in the Child resource.

  • Strings that have been tagged as locked in the Child resource but not in the Parent resource.

RESOLVED

Resolved are considered the strings in a conflict state between Parent and Child, but these conflicts were resolved via Editor (check “Resolving conflicts” section for more details).

DIVERGED SOURCE

Parent and Child resources have diverged when their existing source strings are updated in one of them only.


When applying this filter, the results you get could meet any of the following criteria:

  • Strings in both the Parent and Child resources and their source text were updated in the Child but not in the Parent resource.

  • Strings in both Parent and Child resources and their source text were updated in the Parent but not in the Child resource.

You may also notice an indicator next to the Child’s resource name on the Resources page. Hovering your mouse over this, you can see the state of the Child compared to the parent. Specifically, this indicator can be:

"This child branch has issues"

This indicator appears if any of the following states is detected:

  • When the Child resource has diverged source strings.

  • When the Child resource has source strings that are not included in the Parent.

  • When the Child resource has conflicts with the Parent.

"This child branch has changes"

This indicator appears if the Child resource is ahead of the Parent or there are resolved conflicts.

📝 Note: If the Child has a mix of statuses, the message “This child branch has issues” will be displayed.


Branch hierarchy

You can create as many Child resources as you want from your Parent resource. But you also have the option to create Child resources from your existing Child resources. Specifically, there are four levels of branch hierarchy:


How translation work is shared between the Child and Parent resources

When Parent and Child resources are in sync (no differences in the translations are detected)

  • Tags are copied from Parent to Child (smart tags, too - more information about smart tags’ behavior when working with multiple branches can be found here).

  • Tags removed from the Parent are also removed from the Child.

  • New translations are copied from Parent to Child.

  • Modified translations are copied from Parent to Child.

  • Translation deleted from Parent is also deleted from Child.

  • Review status is copied from Parent to Child.

📝 Note: Metadata like character limits, instructions, etc., is not copied from Parent to Child.

When a translation is propagated from Parent to Child

The history of the string in the Child resource is updated accordingly. Specifically, the history tab will contain the following information:

  • Origin: Branch Propagation (you can also use the filter More>Origin>TX:PROPAGATED to find such strings in the editor easily).

  • Translator: transifex-bot.

Branch propagation works in one direction only. Translations or tags are not propagated from Child-to-Parent resources. This can only be done upon merging.

When the Child is ahead of the Parent

  • Tags are copied from Parent to Child (smart tags, too - more information about smart tags’ behavior when working with multiple branches can be found here).

  • Tags removed from the Parent are also removed from the Child.

  • Any translation change applied to the Parent is not copied to the Child.

  • Review status is not copied from Parent to Child.

When the Child has conflicts with the Parent

  • Tags are copied from Parent to Child (smart tags, too - more information about smart tags’ behavior when working with multiple branches can be found here).

  • Tags removed from the Parent are also removed from the Child.

  • Any translation change applied to the Parent is not copied to the Child.

  • Review status is not copied from Parent to Child.


Merging resources

When your Child resource is ready to be merged with your Parent resource:

  1. Visit the detailed page of your Child resource.

  2. Click “Merge” at the top right corner of the page.

  3. Review differences between your Parent and Child resources. You can use the links in the confirmation dialog to visit the editor page of your Child resource and review the string(s) in the target language(s) selected in the modal to resolve conflicts.

Under the "Conflicts and changes" section, you can review:

  • Changes: Changes ahead of branch.

  • Conflicts: Conflicts between Parent and Child.

  • Resolved: Conflicts that were marked as resolved already.

Once you click Merge, a confirmation message will be displayed:


“Your branch will be merged shortly. You may continue your work and refresh your page in a while to see the merge completion.”

📝 Note

  1. During a merge, the “Update” source file button on the UI will remain disabled until the merge task is completed.

  2. After a merge, the child resource is not deleted automatically. However, it can be deleted later using either the UI or the API/CLI.

  3. Only translations for common strings are merged. The rest are skipped.

If your Child resource has more source strings than those included in your Parent resource, the translations of the extra source strings are not merged. You first need to update your source content in your Parent or Child resource and then move forward with merging.

If you have source strings diverged between Parent and Child resources, their corresponding translations are not merged. You must first update your source content in your Parent or Child resource and then merge them.

If your Child resource has fewer source strings compared to the Parent, then during merge, these missing strings are ignored.


Resolving conflicts

Conflicts can be resolved using one of the ways below:

1. Resolving conflicts inside the editor

When a string in the Child resource has a conflict with the string in the Parent resource, this conflict is visible under the suggestions tab:

2. Resolving conflicts during the merge

When you are ready to merge your Child with your Parent resource, but there are still unresolved conflicts, these conflicts can be resolved upon merging using one of the following two options:

Before merging your Child resource with the Parent, you can review any conflicts and changes in the translation using the editor links available in the pop-up.

📝 Note: Diverged source strings with conflicts won’t be available for conflict resolution until the source string is updated in Parent or Child.

  • If you resolve conflicts with the Parent, the system will keep whatever translation the Parent has for the conflicted strings. For example, if the string has “Translation string #1.b” and “tag1.b” in the Parent resource and “Translation string #1.a” and “tag1.a” in the Child resource, then Transifex will keep “Translation string #1.b” in Parent, and the string in both Parent and Child resources will have both tags, i.e., “tag1.b” and “tag1.a”.

  • If you resolve conflicts with the Child, the system will keep whatever translation the Child has for the conflicted strings. For example, if the string has “Translation string #1.b” and “tag1.b” in the Parent resource and “Translation string #1.a” and “tag1.a” in the Child resource, then Transifex will keep “Translation string #1.a” in Parent and the string in both Parent and Child resources will have both tags, i.e., “tag1.b” and “tag1.a”.

Translations that are updated in your Parent resource once the merge is done will be displayed in the editor with the origin: Branch Merge. You can also use the filter More > Origin > TX:MERGED to find such strings in the editor easily).


Smart tags

Smart tags remain an option when working with branches.

Here are a few things to keep in mind when using smart tags with branches:

  • Smart tags are not propagated from Child to Parent (check the section “How translation work is shared between the Child and Parent resources” for more details).

  • Smart tags are propagated from Parent to Child, but their impact on Child translations depends on the status of the branch. To better understand their impact and behavior, you can check the scenarios below:

Scenario #1

Parent and Child source strings are in sync (they are both untranslated or translated the same way).

When smart tags are assigned to Parent source strings:

  • Smart tags are propagated from Parent to Child source strings.

  • If translation changes occur due to smart tag presence in the Parent source string, the same translation changes will also be applied to the Child source string.

  • Review/Proofread status triggered by the smart tag in the Parent source string will also be propagated to the Child source strings.

As long as strings remain in sync between Parent and Child resources, if you remove smart tags from Parent strings, Parent translations and review status changes will be propagated to the corresponding Child strings.

Scenario #2

Parent and Child source strings are in NOT sync (Parent and Child have different translations)

When smart tags are assigned to Parent source strings:

  • Smart tags are propagated from Parent to Child source strings.

  • Any changes introduced by the presence of the smart tag to the Parent source strings won’t be propagated to the Child source strings automatically. These translation differences will be handled as conflicts between Parent and Child.


Translation Memory & Branches

All the Translation Memory functionality described here remains available for both Parent and Child resources. No matter the branch you are working on, whenever a new translation is submitted, your project’s translation memory is updated accordingly based on your Translation Memory configuration.


How is word count affected when working with branches

When you work with branches:

  • Common strings between your Parent and Child resources are counted only once.

  • Unique strings introduced in either Parent or Child resources contribute to your total word count as described here.


💡Tip

Looking for more help? Get support from our Transifex Community Forum!

Find answers or post to get help from Transifex Support and our Community.

Did this answer your question?