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.
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.
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 |
|---|---|
| Do not create new files in the target branch. | |
| Do not create new languages in the target branch. | |
| Do not create new keys in the target branch. | |
| Process only conflicting translations, and skip all others. | |
| Skip all keys with existing translations. | |
| Comma-separated list of languages to process; if not specified, all languages are processed. | |
| Comma-separated list of keys to process; if not specified, all keys are process. | |
Do not fail if there are any conflicts. Doesn’t apply for the merge command. |
|
Do not fail if there are any failures. Doesn’t apply for the merge command. |
|
| Please see Conflict resolution strategies below. | |
Run the merge command asynchronously. Do not wait for results. Only applies to the merge command. |
Conflict resolution strategies #️⃣
Localazy understands any difference between the same key in the source and target branches as a conflict. To resolve the conflict, either the target or source branch has to be changed.
You can resolve all conflicts manually or use one of predefined automatic conflict resolution strategies.
| Strategy | Description |
|---|---|
| Do not resolve conflicts. | |
| Resolve all conflicts using the source branch translations. | |
| Resolve all conflicts using the target branch translations. Please note that the source branch will be affected. | |
| Resolve conflicts using translations from the source branch if their are newer than corresponding ones in the target branch. | |
| Resolve conflicts using newer translations either from the source or target branch. Please note that the source branch will be affected. | |
| When merging a branch into its direct parent, Localazy can resolve the changes automatically if the parent translation hasn’t changed. In any other situation, conflicts are skipped. |
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.
The following results are reported:
| Category | Description |
|---|---|
| Conflicting translations are those that are not the same, and the remembered translations in the source branch are different from the target. | |
| 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. | |
| Translations in the target branch that are about to be updated using translations from the source one. | |
| Conflicts resolved with translations from the source branch. | |
| Conflicts resolved with translations from the target branch. | |
| Translations newly created in the target branch. | |
| Keys newly created in the target branch. | |
| Languages newly created in the target branch. | |
| Files newly created in the target branch. | |
| 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.
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 --strategy target {source_branch} {target_branch}
Note: Always use branches in the same order and specify the direction using --strategy.
Investigate failures #️⃣
Invoke localazy branch failures [options] {source_branch} {target_branch} to list all the detected failures.
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.