docs: add branching documentation

- Add new pages for "Branching" and "Merging Branches"
- Include branching visuals and examples for key workflows
- Update sidebar navigation to include "Branching" section

Author: dkrizan

platform/branching/merging_branches.mdx

@@ -0,0 +1,87 @@
+---
+id: merging_branches
+title: Merging Branches
+image: /img/og-images/platform.png
+---
+
+import { ScreenshotWrapper } from '../shared/_ScreenshotWrapper';
+
+Merging applies the changes from one branch (the **source**) into another branch (the **target**). Before the merge is applied, Tolgee analyses the differences and shows you a preview so you can review everything — and resolve any conflicts — before committing.
+
+## Initiating a Merge
+
+Go to **Branching** in the project sidebar. Click the **branch icon button** next to the branch you want to merge. Tolgee immediately opens the merge preview page.
+
+:::info
+The merge always goes into the **default branch** (`main`). To merge into a different target, contact your administrator or restructure your branching workflow.
+:::
+
+## Understanding the Merge Preview
+
+The merge preview shows a summary of all differences between the source and target branch, grouped into four categories:
+
+<ScreenshotWrapper
+  src="/img/docs/platform/branching/screenshot_07_merge_preview_overview.png"
+  alt="Merge preview showing change summary and conflict panel"
+/>
+
+| Category | Meaning |
+|----------|---------|
+| **Added** | Keys that exist in the source branch but not in the target — they will be created |
+| **Modified** | Keys that were changed in the source branch — the target version will be updated |
+| **Deleted** | Keys that were removed in the source branch — they will be deleted from the target |
+| **Conflicts** | Keys that were changed in *both* branches — you must choose which version to keep |
+
+The tabs below the summary let you browse each category. Non-conflicting changes (Added, Modified, Deleted) are applied automatically.
+
+### Reviewing Modified Changes
+
+The **Modified** tab shows a three-column view: source branch on the left, merge preview in the centre, and the target branch on the right.
+
+<ScreenshotWrapper
+  src="/img/docs/platform/branching/screenshot_08_merge_modified_tab.png"
+  alt="Modified tab showing three-column comparison view"
+/>
+
+These changes require no action — they will be applied automatically when you complete the merge.
+
+## Resolving Conflicts
+
+A conflict occurs when the same key was changed in both branches since the branch was created. You must choose which version to keep before the merge can be completed.
+
+<ScreenshotWrapper
+  src="/img/docs/platform/branching/screenshot_09_merge_conflict_panel.png"
+  alt="Conflict panel showing source and target versions side by side"
+/>
+
+For each conflict, you see:
+- The **source branch** version on the left
+- The **merge preview** (empty until resolved) in the centre
+- The **target branch** version on the right
+
+Click **Accept** on either side to choose that version. The merge preview in the centre updates to reflect your choice and the conflict is marked as resolved.
+
+You can expand **All Translations** to see all languages for a key before deciding.
+
+:::info
+Tags, labels, and screenshots are always **combined** from both branches — they are never lost in a merge.
+:::
+
+## Completing the Merge
+
+Once all conflicts are resolved, the **Complete the merge** button becomes active and the conflicts counter shows all resolved.
+
+<ScreenshotWrapper
+  src="/img/docs/platform/branching/screenshot_10_merge_ready_to_complete.png"
+  alt="Merge ready to complete with all conflicts resolved"
+/>
+
+Optionally check **Delete [branch name] after merge** to automatically remove the source branch once the merge is applied.
+
+Click **Complete the merge** to apply all changes to the target branch.
+
+## Merge Invalidation
+
+If the source or target branch is modified while the merge preview is open (for example, someone edits a translation in the meantime), the merge preview becomes stale. Tolgee will notify you and offer a **Refresh** option to re-analyse the differences with the latest state of both branches.
+
+Any conflict resolutions you already made are preserved where possible after a refresh.

platform/branching/overview.mdx

@@ -0,0 +1,92 @@
+---
+id: overview
+title: Branching
+image: /img/og-images/platform.png
+---
+
+import { ScreenshotWrapper } from '../shared/_ScreenshotWrapper';
+
+:::info Feature availability
+Branching is available on Business and Enterprise plans. [Upgrade your plan](https://tolgee.io/pricing) to use this feature.
+
+If you use the self-hosted version, you must [set up the license](/platform/self_hosting/licensing) to use this feature.
+:::
+
+Branching lets you create isolated copies of your project's translations to work on independently. Different teams can work on separate branches simultaneously without affecting each other, then merge changes back when ready.
+
+**Common use cases:**
+- Translating a new feature without affecting the production translations
+- Preparing translations for an upcoming release while regular translation work continues
+- Experimenting with copy changes before committing them to the main branch
+
+## Key Concepts
+
+- **Branch** — an isolated copy of all translation keys and their translations at the point of branching
+- **Default branch** (`main`) — the primary branch every project starts with; it always exists and cannot be deleted
+- **Protected branch** — a read-only branch; translations can only be changed via a merge, not edited directly
+- **Merge** — the process of applying changes from one branch into another, with conflict detection and resolution
+
+## Navigating Between Branches
+
+The **branch selector** in the breadcrumb bar lets you switch between branches. All views that work with translations — dashboard, translations, import, export, and tasks — reflect the currently selected branch.
+
+<ScreenshotWrapper
+  src="/img/docs/platform/branching/screenshot_01_translations_with_branch_selector.png"
+  alt="Translations view with branch selector in the breadcrumb"
+/>
+
+Click the branch selector to open the list of available branches and switch to a different one.
+
+<ScreenshotWrapper
+  src="/img/docs/platform/branching/screenshot_02_branch_selector_open.png"
+  alt="Branch selector open showing all branches"
+/>
+
+## Managing Branches
+
+Go to **Branching** in the project sidebar to manage all branches for the project.
+
+<ScreenshotWrapper
+  src="/img/docs/platform/branching/screenshot_03_branches_list.png"
+  alt="Branches list with multiple branches"
+/>
+
+### Creating a Branch
+
+Click **+ Branch** to open the create dialog. Give the branch a name and optionally choose a source branch to branch from (defaults to the default branch).
+
+<ScreenshotWrapper
+  src="/img/docs/platform/branching/screenshot_04_create_branch_dialog.png"
+  alt="Create new branch dialog"
+/>
+
+Branch names can contain letters, numbers, slashes, hyphens, and underscores. Slashes are commonly used to group branches by purpose, e.g. `feature/new-onboarding`.
+
+### Branch Actions
+
+Each branch has a **⋮** menu with the following actions:
+
+<ScreenshotWrapper
+  src="/img/docs/platform/branching/screenshot_05_branch_actions_menu.png"
+  alt="Branch actions menu showing Rename, Protect, and Delete"
+/>
+
+- **Rename** — change the branch name
+- **Protect / Unprotect** — toggle the protected state. A protected branch is read-only; translations must be merged in, not edited directly. Useful for guarding stable branches.
+- **Delete** — permanently remove the branch and all its translations
+
+:::caution
+Deleting a branch is permanent. All translations that exist only in that branch will be lost.
+:::
+
+### Merge Button
+
+The branch icon button (next to the ⋮ menu) starts a merge from that branch into the default branch. See [Merging Branches](merging_branches) for the full merge workflow.
+
+## Permissions
+
+| Action | Required permission |
+|--------|-------------------|
+| View branches and switch between them | Any project member |
+| Create, rename, delete, protect branches | Branch management |
+| Merge branches | Any project member |

sidebarPlatform.js

@@ -19,6 +19,14 @@ module.exports = {
         'projects_and_organizations/machine-translation-settings',
         'projects_and_organizations/ai-settings',
         'projects_and_organizations/tasks',
+        {
+          label: 'Branching',
+          type: 'category',
+          items: [
+            'branching/overview',
+            'branching/merging_branches',
+          ],
+        },
         'projects_and_organizations/order_translation',
         'projects_and_organizations/members',
         'projects_and_organizations/import',