Login Start for Free

Branching

Branches allow for separate, independent versions of all content in Applanga Projects.

The Branching feature is currently only available for Enterprise plans. The number of Project Branches you can create is determined by your account license. Please reach out to the Applanga support team for more details.

Table of Contents

  1. What is a Branch?
  2. How to Enable Branching
  3. How to Migrate from a Legacy Project with Drafts to a Project with Branches
  4. Creating Branches
  5. Switching Between Branches
  6. Read Only Branches
  7. Access to Branches
  8. Merging Branches
  9. Merge Calculation
  10. Merge Conflict Resolution
  11. Effects of Branching
  12. Branching and the Applanga API
  13. Branching and the Applanga Mobile SDKs
  14. Branching and the Applanga CLI

What is a Branch?

A branch is one separate, independent version of all the content in your Applanga Project. Based on what’s included in your license, you can have a certain number of Branches. They can be pretty similar or differ greatly depending on your needs.

In the dashboard, you can switch between different Branches, create new Branches, and merge 2 Branches into each other. Some Applanga features are branch-specific, while others work across all branches. Details on how Branching impacts Applanga features can be found below.

All Applanga integration options can be configured to point to a specific Branch of your Applanga Project. How you configure that depends on how Branches in your Applanga Project should mirror your application’s development processes, release management, or app environments. How an integration is configured to work with Branching is noted in the integration documentation section for each integration.

Among all Branches in your Applanga Project, one must be the Default Branch. The Default Branch can be selected in the Project Settings. The Default Branch is the one shown by default when accessing the Project in the dashboard

Back to Top


How to Enable Branching

You will only have access to the Branching feature to the extent it is included in your license. Certain limits will apply.

In the Project Settings, you can find Branches under its own category. For existing projects, activating Branching means migrating the project to a new setup. Please read the details in the next section below for more information on the migration process.

When creating new projects, there will be a checkbox for you to choose either a legacy configuration with Drafts or use Branching from the start.

Back to Top


How to Migrate from a Legacy Project with Drafts to a Project with Branches

Enabling the Branching feature for an existing Project means migrating the project from Drafts to Branches. This process can’t be undone!

In the migration process, 2 Branches are created. The “main” Branch will contain all the Project content besides Draft translations. The “Draft” Branch will contain the same content, but for every key that had a Draft in any language before, this Draft will be its new translation. Basically, on the “Draft” Branch all pre-existing Drafts are now published/target translations.

After starting the migration process, the project will no longer contain Drafts. Meaning principles like adding Drafts, import and order delivery as Drafts, publishing Drafts, or the Draft Mode will be replaced by updating the translation on the “Draft” Branch, imports and deliveries into the “Draft” Branch, merging the “Draft” Branch into “master” and configure the SDK integration to show content from the “Draft” Branch.

All integrations in a project with Branching can be configured to point to a specific Branch for either upload, download, or both. If no Branch is configured in an integration, but the Project is migrated to Branching, all integrations without a specific configuration will point to the "main" Branch, to keep backwards compability with old integrations.

For example, if you have a mobile app integrated with the Applanga SDK and your users still have a version of your app installed without a Branching configuration in the SDK, if you want to push Over-the-air updates to these users, you have to make updates to your new "main" Branch.

Back to Top


Creating Branches

Branches can be created on the Project Overview page.

Alternatively, Branches can be created in the Project Settings

To create a new Branch, you will need to name the Branch and select a source of content for the Branch.

Limitations to Branch names:

  • May contain numbers, letters, spaces, and . - _ / characters
  • Minimum length is 1 character
  • Maximum length is 120 characters

To change an existing Branch name, click Edit in the Actions column.

To change the Default Branch, mark the checkbox next to the Branch in the Project Settings.

Back to Top


Switching Between Branches

You can see the currently selected Branch on the Project Overview Page. The Branch you see by default is the one set as Default Branch in the Project Settings. To change the selected Branch use the dropdown menu on the Project Overview page.

Alternatively, in the Editor you can switch the current Branch via the breadcrumbs.

Back to Top


Read Only Branches

To prevent changes to specific Branches, you can designate the Branch as Read-Only. Branches with the Read-Only setting enabled cannot be edited in any way. Users will not be able to change, add, or remove any strings, source, translations, tags, screens, statuses, metadata, or languages. Additionally, orders cannot be created, files cannot be imported, and the Read-Only Branch cannot be on the recieving end of a merge. Users can still export translations, integrate with the Branch, and merge the Read-Only Branch into another Branch. Designating a Branch as Read-Only can be accomplished in the Project Settings.

Back to Top


Access to Branches

Permission to access Branches sits at a user role level. Users that are granted access to branches will have the same type of access in all of them. The only additional difference for Projects with Branching is that it can be defined on which Branch users with the Translator/Reviewer role can make edits to translations. This can be accomplished in the Project Settings.

Back to Top


Merging Branches

In some cases, your Branches might stay completely separate inside your project, but more often than not, there will be a point in time where content from one Branch should be passed over to another. For example, the content in your “development” Branch should be promoted to your “production” Branch. This is achieved by Merging Branches into each other.

A Merge is not just an import and overwrite. It considers all changes made on both Branches back to the point in time the newer of the two was created and then combines all changes in the same Branch.

You can start a Merging process on the Project Overview page via the Branch dropdown. First, select a Branch then chose which other Branch you want to merge into.

This same process can be started from within the Project Settings in the Actions column.

Back to Top


Merge Calculation

Depending on the Project, the Merging process must consider several different data points. This means that if you start a Merging process, Applanga will have to perform a Merge Calculation. There is a progress indicator showing you all ongoing and finished Merge Calculations.

The Merge Calculation will only take those changes into account that were made before the calculation began. If you have additional changes after the merge calculation, you must start a new Merge Calculation to ensure those changes are included.

Back to Top


Merge Conflict Resolution

In some cases, there might be changes to an element in scope - for example, a certain translation - in both Branches which results in a Merge Conflict. That simply means the Merging process cannot just pick one or the other, but will ask the user to decide which version to keep.

To further clarify, let’s assume you have the default Branch “main” in your Project and now create a new Branch based on “main” and call it “development”. When you create “development” it contains the same content as “main”, but as you continue your development and localization processes, differences will emerge. Below are some scenarios on such differences and how merging will work in the context of these scenarios:

Scenario 1: Changes are made in the “development” Branch, then “development” is merged into the “main” Branch. In “development” you change the source text of example.key.1 from “Hello user” to “Hello friend”. In “main” you don’t make any changes to example.key.1. When “development” is merged into “main”, the source text of example.key.1 in “main” is updated to “Hello friend”

Scenario 2: Changes are made in the “development” Branch, but now the “main” Branch is merged into “development”. Like in scenario 1, in “development” you change the source text of example.key.1 from “Hello user” to “Hello friend”. In the “main” Branch you don’t make any changes to example.key.1. Now “main” is merged into “development”, so the other direction as in Scenario 1. However, after the merge, the example.key.1 will still have the new source text “Hello friend”.

As mentioned above, merging does not just import into and overwrite one Branch with another. It brings together all changes made to both Branches based on a shared point in time. This also means you can’t reset or roll back a Branch to the state of another one only by merging one into the other.

Scenario 3: A change is made to the same key in the “development” and “main” Branches. This time, example.key.1 is changed in both Branches. In “development”, the new source text is “Hello friend”. In “main”, the source text is also changed to “Hello neighbor”. When merging either of these Branches into the other, the user triggering the Merging process has to decide which to keep. This means we have a Merge Conflict. It has to be resolved by choosing “development” or “main” as the basis to resolve.

Scenario 4: A key is deleted in the “development” Branch, then “development” is merged into the “main” Branch. The key example.key.1 is deleted from “development” in this scenario. When “development” is now merged into “main”, while no changes were made to that same key on “main”, after the merge, example.key.1 will also be deleted from “main”.

If there was a change to the same key in “main”, we would have a Merge Conflict again and the user would have to decide to resolve by picking from “main” or “development”.

Back to Top


How Branching Affects Other Aspects or Features of Applanga

Teams & User Roles

  • Teams are NOT branch-specific. Access to Branches is defined at a user role level and it applies across all Branches in all your Projects.
  • The access for the Translator/Reviewer role can be restricted so that users with this role can only make changes to specific Branches. This can be configured in the Project Settings in the Branching section.

Custom Workflow Statuses

  • Custom Workflow Statuses are NOT branch-specific. All Custom workflow statuses are available across all Branches of your Projects.

Translation Memory

  • The Applanga Translation Memory is NOT branch-specific. You can add to the memory or apply translations from the memory across all Branches of your Projects.

Project Settings

  • Project Settings are NOT branch-specific except for the section to manage Branches themselves.

Groups

  • Groups are branch-specific. When merging two branches into each other there can be Merge Conflicts that have to be resolved as described above.
  • Because Groups are branch-specific, the key counts normally present in the Groups management interface in the Project Settings are not shown for Projects with Branching enabled. The counts may differ depending on which Branch is currently selected so there is no global count.

Backups

  • Backups are ONLY created for the default Branch.
  • If your default Branch has existing backups and you change your default Branch to another one, the list of backups won't be visible. To view them again, switch back to the former default Branch.

Glossary

  • The Applanga Glossary is NOT branch-specific. Terms added to the Glossary are checked across all Branches.

Changelogs

  • Changelogs are branch-specific and are combined as part of the Merging process.
  • There are Branching / Versioning-specific Changelog events that are created when Branches are created and when a Merging process has occurred.
  • When a new Branch is created, it inherits the Changelog of the Branch on which it's based.

Languages

  • Languages in a project are branch-specific and when merging two branches into each other there can be Merge Conflicts that have to be resolved as described above.
  • Custom Languages are branch-specific as well. A custom language created in one Branch needs to be created again when it should be added to another Branch (where it is not already part of the Project.)

Keys

  • Keys are branch-specific. When merging two branches into each other there can be Merge Conflicts that have to be resolved as described above.
  • Linking and unlinking of keys are branch-specific as well. Differences in linking are resolved as part of the Merging process, but there can be Merge Conflicts at the linking level that have to be resolved as described above.

Metadata Fields and Values

  • Metadata field values are branch-specific. When merging two branches into each other there can be Merge Conflicts that have to be resolved as described above.
  • Custom Metadata fields are NOT branch-specific since they are created and managed in the Project Settings. All Metadata (both Custom and default fields) are available across all Branches.

Tags

  • Tags are branch-specific. When merging two branches into each other there needs to be a decision to keep the setup of Tags from one of the two Branches in scope.
  • This includes the Tags themselves AND their association with Keys.
  • Tag Categories are NOT branch-specific since they are created and managed in the Project Settings. All Tag Categories are available across all Branches.

Screenshots

  • Screenshots are branch-specific. When merging two branches into each other, you must decide to keep the Screens from one of the two Branches.
  • This includes the Screens themselves, all Variants for a given Screen, AND their association with Keys.

Source text and Translations

  • Both the Source Text and Translations are branch-specific. When merging two branches into each other there can be Merge Conflicts that must be resolved as described above.

Workflow Status and Comments

  • Workflow Statuses and Comments are branch-specific. When merging two branches into each other there can be Merge Conflicts that have to be resolved as described above.

Translation Orders

  • Translation Orders are branch-specific. There is a selector to choose the Branch during order creation. Translations will only deliver to the Branch from which the order was created.

Imports and Exports

  • All imports and exports are branch-specific meaning an export will only consider the scope of the Branch currently selected and an import will only affect the Branch currently selected.

Integrations

  • All work is branch-specific; meaning integrations need to be configured to upload and/or download to and from a specific Branch in your Project.
  • You can configure your integrations with multiple Branches, e.g. your development environment could be integrated with the “dev” Branch of your Project and your production environment with the “prod” Brach of your Project.
  • Integrations use Branch Ids instead of the actual Branch name on the dashboard to connect to certain Branches. Changing a Branch’s name on the Applanga dashboard has no impact on the integration(s).
  • Existing integrations have to be extended to use the Branching feature (point to a specific Branch). If integrations are not updated, any previously existing integration will point to the "main" Branch of the connected Project.

Back to Top

Branching and the Applanga API

  • For a Project with Branching enabled, the Applanga API Access Token will stay the same and all previously working API calls will work in the same way but only interact with the Default Branch as defined in the Project Settings.

  • If you want to call a specific Branch with your API request (get or post), you have to add the branchId of the Branch you want to perform the action on as a parameter to the call. You can retrieve the branchId from the Project Settings

  • As an example for requesting the complete scope of your Project you would have previously requested the url https://api.applanga.com/v1/api?app=<your-app_id> as get request with the header Authorization: Bearer <your-api_token> in place. If you now want to do the same kind of call to any Branch that is NOT the "main" of your Project, you need to modify the API request url to look like this https://api.applanga.com/v1/api?app=<your-app_id>&branchId=<your-branch_id> The header remains the same.

  • This pattern also applies to all API methods for Tag or Screenshot requests and post calls.

  • Additionally, to request all branches that are currently present in your Project you can use this route https://api.applanga.com/v1/api/branches?app=<your-app_id>. It will return all Branches of your Project with names and branchId. This way you can build your scripts and integration to work with different Branches. This only works if your Project is already migrated to a Branching Project. If not, call will return an error.

  • All calls without branchId present will always route to the "main" Branch.

Back to Top

Branching and the Applanga Mobile SDK's

To be able to use branch-specific features you need to use at least the Applanga SDK 4.0.184 on Android and at least version 2.0.167 on iOS. If your project is a branching project and the SDK version does support branching, watch out for the log line: Branching is enabled.

Mobile Apps with SDK Integration but without Branching support

  • All mobile apps with existing integrations without Branching configuration will update with the "main" Branch configured in the Project Settings.

Applanga Settingsfile

  • Applanga Settingsfile's are branch-specific.
  • The Settingsfile defines the Branch the integrated Applanga Mobile SDK connects to for Missing String uploads and Over-the-Air updates and contains all translations from the defined Branch
  • Make sure to update the SDK version to the minimal version mentioned above if you use a Settingsfile pointing to a specific Branch.

Draft Mode

  • When enabling the Draft Mode when Branching is enabled you will be able choose a different Branch to connect your integrated app. An app restart is required.
  • In the overlay menu you can switch Branches at runtime as well. An app restart is required.
  • You only can see changes after switching a branch in Draft Mode when you have a running internet connection, since the Settingsfile will only contain translations for one specific Branch.
  • Screenshot uploads are branch-specific, so they will be uploaded to the currently selected Branch (either defined in the Settingsfile or selected in the Draft Mode). This also implies that if a Tag didn’t exist, it’s created for the selected Branch.

Back to Top

Branching and the Applanga CLI

  • For a Project with Branching enabled, the Applanga API Access Token will stay the same and all previously working CLI configurations will work in the same way, but they will only interact with the "main" Branch.

  • If you want to call a specific Branch with the CLI (push or pull), you have to add the branch_id parameter, of the Branch you want to perform the action on, into the 'app' object inside the .applanga.json file. You can retrieve the branchId from the Project Settings

Back to Top