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.
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 |
---|---|
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. |
|
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. |
|
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.
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 if --resolve-conflicts source is specified. |
|
Conflicts resolved with translations from the target branch if --resolve-conflicts target is specified. |
|
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 --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.
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.