Skip to content

Commit 80c360c

Browse files
rohalskyyrohalskyy
authored
docs: update Version Management (#251)
1 parent 48710af commit 80c360c

File tree

2 files changed

+293
-51
lines changed

2 files changed

+293
-51
lines changed

‎src/content/docs/crowdin/project-management/sources/version-management.mdx‎

Lines changed: 146 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ sidebar:
66
order: 4
77
---
88

9-
import { Steps, Aside } from '@astrojs/starlight/components';
9+
import { Steps, Aside, Tabs, TabItem } from '@astrojs/starlight/components';
1010
import { Icon } from 'astro-icon/components';
1111
import ReadMore from '~/components/ReadMore.astro';
1212
import { Image } from 'astro:assets';
@@ -18,8 +18,6 @@ import branchTranslationVerification from '!/crowdin/project-management/sources/
1818

1919
Maintain an agile localization process and prevent translation delays for added texts or new product features. Integrate your project branches with Crowdin and allow translators to access all new texts immediately.
2020

21-
## Branches
22-
2321
When several people work on product development, branches help manage different content versions. If you have a continuous project, you can add project branches to Crowdin and allow translators to translate the texts in parallel with development to prevent deployment delays.
2422

2523
Branches in Crowdin look like regular folders marked with a specific icon and have special behavior for duplicate strings.
@@ -28,35 +26,113 @@ Example of branch structure in the version control system (VCS) and Crowdin:
2826

2927
<Image src={branchesStructure} alt="Branch Structure" class="no-shadow" />
3028

31-
### Branch Creation
29+
## Managing Branches
3230

33-
There are a few ways to add branches to Crowdin:
31+
You can create, clone, merge, rename, prioritize, or delete branches in Crowdin to streamline localization alongside development. Use the available UI options, API, or CLI depending on your workflow and project type.
3432

35-
* Integrate Crowdin projects with [GitLab](/gitlab-integration/), [GitHub](/github-integration/), [Bitbucket](/bitbucket-integration/), or [Azure Repos](/azure-repos-integration/). It’s a recommended option, as branches selected for localization in your version control system (VCS) will be created in Crowdin automatically.
36-
* Use [CLI](https://crowdin.github.io/crowdin-cli/) or [API](/developer/api/) to add new branches.
37-
* Create branches [manually](/file-management/#branches-and-folders).
33+
### Creating Branches
3834

39-
<Aside type="caution">
40-
The first files you upload to the Crowdin project must contain all the original strings and should be placed in the corresponding branch. For all article examples, a branch with original texts is named *Master*.
41-
</Aside>
35+
You can create branches manually using the web interface (UI), automatically by connecting your project to a version control system, or by using CLI or API. The method you choose may depend on your project type or integration preferences.
36+
37+
#### Creating Branches via VCS Integration
38+
39+
Integrate Crowdin projects with [GitLab](/gitlab-integration/), [GitHub](/github-integration/), [Bitbucket](/bitbucket-integration/), or [Azure Repos](/azure-repos-integration/). When you select branches for localization in your VCS, they’ll be created automatically in Crowdin.
40+
41+
#### Creating Branches via Web Interface
42+
43+
To create branches via the web interface (UI), follow these steps:
44+
45+
<Tabs syncKey="projectType">
46+
<TabItem label="File-based project">
47+
<Steps>
48+
1. Open your project and go to **Sources > Files**.
49+
2. Click **New Version Branch**.
50+
3. In the appeared dialog, enter the branch name.
51+
4. In the **Duplicate Strings** section, select how duplicated strings should be handled.
52+
5. Click **Create** to finish.
53+
</Steps>
54+
</TabItem>
55+
<TabItem label="String-based project">
56+
<Steps>
57+
1. Open your project and go to the **Branches** tab.
58+
2. Click **New Version Branch**.
59+
3. In the appeared dialog, enter the branch name.
60+
4. Select **Create empty branch** or **Clone existing branch**.
61+
5. If cloning, select the source branch from the dropdown that appears.
62+
6. Click **Create** to finish.
63+
</Steps>
64+
</TabItem>
65+
</Tabs>
4266

4367
#### Branch Creation using API
4468

45-
To create a branch via API, use the [Add Branch](/developer/api/v2/#operation/api.projects.branches.post) method.
69+
You can use the Crowdin API to programmatically create branches. The available method depends on the project type:
70+
71+
* [Add Branch (File-based)](https://support.crowdin.com/developer/api/v2/#tag/Source-Files/operation/api.projects.branches.post)
72+
* [Add Branch (String-based)](https://support.crowdin.com/developer/api/v2/string-based/#tag/Branches/operation/api.projects.branches.post)
4673

4774
#### Branch Management using CLI
4875

49-
If you use CLI, you can add and delete version branches with dedicated commands. Alternatively, you can create version branches during the file upload.
76+
With the Crowdin CLI, you can manage branches directly from your local environment, using the dedicated commands. You can also create a branch automatically during file upload.
5077

5178
<ReadMore>
5279
Read more about [Branch Management with CLI](https://crowdin.github.io/crowdin-cli/commands/crowdin-branch).
5380
</ReadMore>
5481

82+
### Cloning Branches
83+
84+
You can create a copy of an existing branch using the **New Version Branch** dialog or the **Clone** option in the context menu.
85+
86+
To clone a branch, follow these steps:
87+
88+
<Steps>
89+
1. Open your project and go to the **Branches** tab.
90+
2. Do one of the following:
91+
- Click **New Version Branch**.
92+
- Hover over the needed branch, click <Icon name="mdi:dots-horizontal" class="inline-icon" /> (or right-click), and select **Clone**.
93+
3. In the appeared dialog, enter the name for the new branch.
94+
4. If cloning via **New Version Branch**, select **Clone existing branch** and choose the source branch from the dropdown.
95+
5. Click **Create** to finish.
96+
</Steps>
97+
98+
<Aside type="caution" title="Limitations">
99+
Branch cloning is only available for [string-based](/creating-project/#string-based-project) projects.
100+
</Aside>
101+
102+
### Merging Branches
103+
104+
You can merge one branch into another directly from the **Branches** tab using the context menu. During the merge process, Crowdin displays a summary of changes and allows you to resolve any conflicts before completing the merge.
105+
106+
<Steps>
107+
1. In the **Branches** tab, hover over the source branch you want to merge.
108+
2. Click <Icon name="mdi:dots-horizontal" class="inline-icon" /> (or right-click), and select **Merge**.
109+
3. In the appeared dialog, choose the target branch to merge into.
110+
4. Click **Continue** to proceed to the Merge Summary page.
111+
</Steps>
112+
113+
On the **Merge Summary** page, you’ll see:
114+
115+
* A summary of string changes — how many were added, removed, or changed.
116+
* An optional checkbox to **Delete the source branch after merge**.
117+
118+
If any strings were changed, a conflict resolution step will follow. For each conflicting string, choose whether to keep the version from the source or the target branch. You can also:
119+
120+
* Click **Accept all from `{source_branch}`** to apply all changes from the source.
121+
* Click **Accept all from `{target_branch}`** to keep all existing strings in the target.
122+
123+
The **Merge** button becomes active only after all conflicts are resolved.
124+
125+
Once the merge is complete, translations, approvals, and votes from both branches will be preserved.
126+
127+
<Aside type="caution" title="Limitations">
128+
Branch merging is only available for [string-based](/creating-project/#string-based-project) projects.
129+
</Aside>
130+
55131
### Prioritizing Branches
56132

57-
You can set a specific priority for each branch by clicking an arrow icon next to the needed branch. Then translators will see branches sorted according to their priority on the language page and in the Editor.
133+
You can set priorities to branches in file-based projects to help translators focus on the most important content first. Branches appear sorted by priority on the language page and in the Editor.
58134

59-
Branches might have the following priorities:
135+
Available priorities:
60136

61137
- <Icon name="mdi:arrow-down-bold" class="inline-icon" /> – low
62138
- <Icon name="mdi:arrow-up-bold-outline" class="inline-icon" /> – normal
@@ -66,37 +142,77 @@ To set a priority for your branches, follow these steps:
66142

67143
<Steps>
68144
1. Open your project and go to **Sources > Files**.
69-
2. Click an arrow icon next to the needed branch to set the preferred priority.
145+
2. Click the arrow icon next to the needed branch to set the preferred priority.
70146
</Steps>
71147

72-
<Aside>
73-
Branch prioritization is only available for [file-based](/creating-project/#project-types) projects.
148+
<Aside type="caution" title="Limitations">
149+
Branch prioritization is only available for [file-based](/creating-project/#file-based-project) projects.
74150
</Aside>
75151

152+
### Other Actions from the Context Menu
153+
154+
In addition to cloning and merging, the context menu for each branch includes the following options:
155+
156+
* **Rename** – Allows you to change the name of the selected branch.
157+
* **Add Task** – Opens the task creation dialog with the branch preselected.
158+
* **Cost Estimate** – Opens the cost estimation dialog scoped to the branch.
159+
* **Delete** – Permanently deletes the branch from the project. Use with caution.
160+
76161
## Duplicates
77162

78-
Because branches are different versions of the same product feature, their localization content is usually duplicated. To help translators translate versions consistently and avoid additional translation costs, we have the **Show within a version branch** option that allows hiding duplicated strings only between versions. If your source files contain strings with apparent identifiers (keys), it's better to use a *strict* version of this option. In other cases, feel free to use a *regular* one.
163+
Because branches are different versions of the same product feature, their localization content is usually duplicated. To help translators translate versions consistently and avoid additional translation costs, Crowdin offers the **Show within a version branch** option, which hides duplicate strings between branches.
79164

80-
When this option is chosen, only the master strings first uploaded to the system should be translated. All duplicated strings will automatically gain translations from the master strings.
165+
When this option is applied, only the original strings (usually from the master branch) need to be translated. All duplicates in other branches automatically receive translations from those originals.
81166

82-
<Image src={versionsDuplicateStrings} alt="Duplicates"/>
167+
<Tabs syncKey="projectType">
168+
<TabItem label="File-based project">
169+
In file-based projects, you can configure how duplicates are handled in **Settings > Import > Source Strings**. If your source files contain clear identifiers (keys), it's recommended to use the *Strict* version of the **Show within a version branch** option. Otherwise, the *Regular* option will work well for most use cases.
170+
<Image src={versionsDuplicateStrings} alt="Duplicates"/>
171+
</TabItem>
172+
<TabItem label="String-based project">
173+
In string-based projects, the **Show within a version branch (regular detection)** behavior is applied automatically and cannot be changed. This ensures translations are reused between branches without requiring any additional configuration.
174+
</TabItem>
175+
</Tabs>
83176

84177
<ReadMore>
85-
Read more about [Duplicates settings](/project-settings/import/).
178+
Read more about [Duplicates settings](/project-settings/import/#duplicate-strings).
86179
</ReadMore>
87180

88181
## Suggested Workflow
89182

90-
To make sure versions work smoothly for your Crowdin project, we recommend the following workflow:
183+
To ensure smooth collaboration between developers and translators, version branches in Crowdin can be used in different ways depending on how you manage source content and what project type you're using.
184+
185+
### Managing Content Outside Crowdin
91186

92-
1. Upload your project files to the Crowdin project using one of the [available methods](#branch-creation).
93-
2. Open your project and go to **Settings > Import > Source Strings**.
94-
3. Switch the **Duplicate Strings** option to **Show within a version branch**.
187+
In both file-based and string-based projects, you can treat your external system (e.g., file storage or version control) as the source of truth. In this setup:
95188

96-
The screenshot below visualizes how the workflow works in practice. All texts from *Master*, *Branch 1*, and *Branch 2* are transferred to the translation server immediately after they appear, even though the branches are not merged to the *Master* branch yet.
189+
* Source files are managed and updated outside of Crowdin.
190+
* You upload project content using the web interface (UI), API, CLI, or integrations.
191+
* Selected branches are created in Crowdin accordingly.
192+
* Translations are delivered back to your system once completed.
193+
194+
To implement this approach for your Crowdin project, we recommend the following workflow:
195+
196+
<Steps>
197+
1. Upload your project files to the Crowdin project using one of the [available methods](#creating-branches).
198+
2. In file-based projects, open your project and go to **Settings > Import > Source Strings**.
199+
3. Set the **Duplicate Strings** option to **Show within a version branch**.
200+
</Steps>
201+
202+
The screenshot below visualizes how this workflow works in practice. All texts from *Master*, *Branch 1*, and *Branch 2* are transferred to the translation server immediately after they appear, even though the branches are not merged into the *Master* branch yet.
97203

98204
<Image src={branchesWorkflow} alt="Branches Workflow" class="no-shadow mb-8" />
99205

206+
### Managing Content in Crowdin (String-based Projects Only)
207+
208+
For string-based projects, you can also manage branches directly in Crowdin without relying on an external system to define structure or content updates. In this setup:
209+
210+
* Source content can be added the web interface (UI), API, CLI, or integrations.
211+
* Version branches are created, cloned, and merged within Crowdin using the UI or API.
212+
* Translations are optionally synced back to any connected integration, if used.
213+
214+
This approach gives more flexibility for teams who prefer to organize content and manage version flows entirely within Crowdin.
215+
100216
### Translation Download
101217

102218
Translations from all version branches are placed in one ZIP archive when downloaded through the web interface. Use the CLI or API to download the translations for each branch individually.
@@ -121,12 +237,14 @@ crowdin download -b branch_name
121237
Read more about [`crowdin download` command](https://crowdin.github.io/crowdin-cli/commands/crowdin-download).
122238
</ReadMore>
123239

124-
### Merging Branches
240+
### Merging Branches Outside Crowdin
125241

126242
The *Master* branch will contain new texts from the *Feature* branches as soon as they are merged. While synchronizing with Crowdin, texts in the *Master* branch are populated with translations from the appropriate branch.
127243

128244
After synchronizing the updated *Master* branch with Crowdin, you can remove the *Feature* branch from Crowdin. All translations stored in the *Master* branch will remain.
129245

246+
This approach is commonly used in file-based projects but can also apply to string-based ones if content is managed outside of Crowdin.
247+
130248
<Image src={branchMerging} alt="Merging Branches" class="no-shadow mb-8" />
131249

132250
### Branch Translation Verification

0 commit comments

Comments
 (0)