The Branching feature allows for maintaining and merging multiple project branches, enabling complex workflows for versioned development and larger teams.

Basic overview #️⃣

When a new branch is created, it’s a copy of its source, including the glossary, screenshots, and contributors/user roles. It allows you to invite specific people, experiment with different context information, or keep the branch as a standalone project to maintain separate versions of your software or, e.g., create separate branches for white-labeled solutions.

You can access any branch with writeKey/readKey corresponding to a different one as long as you have permission to access both of them.

Each branch counts against the source key limit of your plan.

The main branch #️⃣

Similarly to Github naming conventions, the initial project is called the main branch and can be referenced as main in all commands.

Create a new branch #️⃣

To create a new branch, invoke the following command:

localazy branch create {source_branch} {target_branch}

The process can take a while.

List existing branches #️⃣

Invoke localazy branch list to show all the branches as the tree structure.

Article Image

As you can see, Localazy keeps track of the structure of branches for you.

Delete branches #️⃣

Invoke localazy branch delete {branch} to delete the branch.

It’s only possible to delete branches that do not have any child branches.

Merge branches #️⃣

Localazy keeps track of the structure of branches but allows for merging any two of them in both directions.

When the branch is created, it remembers the original translations in its source, and when the merge is performed, it can automatically resolve conflicts for translations that didn’t change. This feature works when merging any of the branches, so be careful not to overwrite your translations.

It’s recommended to run analysis before the merge as it can fail (CLI returns non-zero exit code) when conflicts and failures are detected.

All of the following commands can be limited to process a specific set of languages or keys and/or to resolve conflicts in a specific way using command-line options:

Option Description
––no–new–files Do not create new files in the target branch.
––no–new–langs Do not create new languages in the target branch.
––no–new–keys Do not create new keys in the target branch.
––conflicts–only Process only conflicting translations, and skip all others.
––skip–existing Skip all keys with existing translations.
––langs cs,de,fr Comma-separated list of languages to process; if not specified, all languages are processed.
––keys _aXXX,_aBBB Comma-separated list of keys to process; if not specified, all keys are process.
––no–fail–on–conflicts Do not fail if there are any conflicts. Doesn’t apply for the merge command.
––no–fail–on–failures Do not fail if there are any failures. Doesn’t apply for the merge command.
––resolve–conflicts DIR Use source to resolve conflicts using the source branch translations. Use target to resolve conflicts using the target branch translations. If this option is not provided or the value is skip, conflicting translations are not resolved.
––async Run the merge command asynchronously. Do not wait for results. Only applies to the merge command.

Analyze changes #️⃣

Analyze what is going to happen when the merge command is performed. It honors all of the command-line options described above to show you precisely the results of the operation.

Invoke localazy branch analyze [options] {source_branch} {target_branch} to run analysis for {source_branch} -> {target_branch} merging.

Article Image

The following results are reported:

Category Description
Conflicting Translations Conflicting translations are those that are not the same, and the remembered translations in the source branch are different from the target.
Failed Translations Translations that cannot be merged because they have different types (e.g., plural vs. string) or do not have the same number of array items.
Updated Translations Translations in the target branch that are about to be updated using translations from the source one.
Resolved From Source Conflicts resolved with translations from the source branch if --resolve-conflicts source is specified.
Resolved From Target Conflicts resolved with translations from the target branch if --resolve-conflicts target is specified.
New Translations Translations newly created in the target branch.
New Keys Keys newly created in the target branch.
New Languages Languages newly created in the target branch.
New Files Files newly created in the target branch.
Matching Translations Translations that are the same both in source and target branches and are about to be left untouched.

If --no-fail-on-conflicts is not provided, the command fails with exit code 127 when conflicts are detected. The same applies to failures if --no-fail-on-failures is not provided.

Investigate conflicts #️⃣

Invoke localazy branch conflicts [options] {source_branch} {target_branch} to list all the detected conflicts.

Article Image

This honors all of the command-line options described above. If --no-fail-on-conflicts is not provided, the command fails with exit code 127 when conflicts are detected.

Conflict resolution #️⃣

You can resolve conflicts by invoking the merge command with specific command-line options. E.g. to resolve the conflict above by using the translation from the target branch, use this command:

localazy branch merge --langs en --keys _a7779040310148463412 --resolve-conflicts target {source_branch} {target_branch}

Note: Always use branches in the same order and specify the direction using --resolve-conflicts.

Investigate failures #️⃣

Invoke localazy branch failures [options] {source_branch} {target_branch} to list all the detected failures.

Article Image

This honors all of the command-line options described above. If --no-fail-on-failures is not provided, the command fails with exit code 127 when failures are detected.

Perform merge #️⃣

Invoke localazy branch merge [options] {source_branch} {target_branch} to perform the actual merge operation based on specified options.

Note: The merge command doesn’t fail on conflicts or failures. It just skips or resolves them according to the command-line options.

Merge glossary and screenshots #️⃣

This feature has yet to be made available. Stay tuned.

Support for other CLI commands #️⃣

You can access any branch with writeKey/readKey corresponding to a different one as long as you have permission to access both of them.

Many commands such as upload, download, cdn, tags support a command-line option --branch [branch_name], allowing to specify the branch to perform the operation on even if the writeKey/readKey belongs to a different one.

It’s also possible to specify the branch in the configuration file.