# gt: General Translation CLI tool: 分支功能
URL: https://generaltranslation.com/zh/docs/cli/branching.mdx
---
title: 分支功能
description: 为不同的 Git 分支分别跟踪翻译
---

## 概述

分支功能可让你分别跟踪项目中不同 git 分支的翻译。
当你在功能分支上开发、引入新内容或修改现有文本，并希望在功能合并到主分支之前将这些翻译与主分支隔离时，这项功能就很有用。

启用分支功能后，CLI 会自动检测你当前所在的 git 分支，并将翻译关联到该分支。
在功能分支上创建的翻译，在合并之前不会影响生产环境中的翻译。

<Callout type="info">
  分支功能是 GT Cloud 的特性之一，且需要付费套餐。如果你在未开通付费套餐的情况下尝试创建非默认分支，CLI 会回退到使用默认分支。
</Callout>

***

## 用法

要启用分支功能，请在 `translate` 命令中使用 `--enable-branching` 标志：

```bash
npx gt translate --enable-branching
```

默认情况下，CLI 会自动检测你当前所在的 git 分支。如果你想改为手动指定自定义分支名：

```bash
npx gt translate --enable-branching --branch my-feature-branch
```

***


## 标志

| Flag                         | Description                   |
| ---------------------------- | ----------------------------- |
| `--enable-branching`         | 为项目启用分支功能。使用基于分支的翻译跟踪时，此项为必需。 |
| `--branch <branch>`          | 指定自定义分支名称，而不是由 git 自动检测。      |
| `--disable-branch-detection` | 禁用分支关系的自动检测。仅使用手动指定的分支。       |

***

## 工作原理

启用分支功能后，CLI 会执行以下操作：

1. **检测当前分支**：使用 git 确定你当前所在的分支。

2. **识别默认分支**：通过检查远程 HEAD 引用，确定默认分支是哪个 (通常为 `main` 或 `master`) 。

3. **跟踪分支关系**：识别哪些分支已合并到当前分支 (传入分支) ，以及当前分支是从哪个分支检出的 (父分支) 。

4. **将翻译与分支关联**：所有翻译都会带上当前分支的标记，从而与其他分支区分开来。

5. **继承父分支的翻译**：创建新分支时，会自动继承父分支的翻译，因此无需重新翻译，也不会被重复收费。

### 翻译继承

在功能分支上工作时，CLI 会跟踪以下内容：

* **传入分支**：已合并到当前分支的分支。这样可以纳入这些已合并分支中的翻译。
* **已检出分支**：当前分支创建时所基于的分支 (通常是默认分支) 。这样你的功能分支就能继承已有翻译。

这意味着，当你从 `main` 创建新的功能分支时，该分支将能够访问 `main` 中所有已有的翻译。你创建的任何新翻译都会关联到该功能分支，直到它被合并。

当功能分支合并回 `main` 后，该功能分支中的翻译也会自动合并到 `main` 中。

***

## 配置

你可以在 `gt.config.json` 文件中设置分支选项：

```json title="gt.config.json"
{
  "branchOptions": {
    "enabled": true,
    "currentBranch": "my-feature-branch",
    "autoDetectBranches": true,
    "remoteName": "origin"
  }
}
```

| 属性                   | 说明                        | 默认值         |
| -------------------- | ------------------------- | ----------- |
| `enabled`            | 为项目启用分支功能                 | `false`     |
| `currentBranch`      | 覆盖当前分支名称 (而非自动检测)         | `undefined` |
| `autoDetectBranches` | 自动检测分支关系 (传入分支和当前已检出的分支)  | `true`      |
| `remoteName`         | 用于检测分支的 Git 远程仓库名称        | `"origin"`  |

<Callout type="info">
  CLI 标志的优先级高于配置文件选项。例如，`--enable-branching` 会覆盖 `branchOptions.enabled`，而 `--disable-branch-detection` 会覆盖 `branchOptions.autoDetectBranches`。
</Callout>

***


## 示例工作流

以下是一个使用分支的典型工作流：

1. **创建功能分支**：
   ```bash
   git checkout -b feature/new-landing-page
   ```

2. **将新的可翻译内容添加到**功能分支中。

3. **启用分支功能运行 translate**：
   ```bash
   npx gt translate --enable-branching
   ```
   CLI 会检测到你当前位于 `feature/new-landing-page`，并将所有新翻译关联到该分支。

4. **继续迭代你的功能** - 后续新增的翻译都会保留在该功能分支上。

5. **将功能分支合并到** `main`：
   ```bash
   git checkout main
   git merge feature/new-landing-page
   ```

6. **在 main 上运行 translate**：
   ```bash
   npx gt translate --enable-branching
   ```
   CLI 会检测到来自 `feature/new-landing-page` 的翻译，并将这些翻译纳入 `main`。

***

## 故障排查

### 未检测到当前分支

如果 CLI 无法检测到你当前所在的分支，可以手动指定：

```bash
npx gt translate --enable-branching --branch my-branch
```


### 使用非标准远程

如果你的 Git 远程名称不是 `origin`，请在配置中指定该远程名称：

```json title="gt.config.json"
{
  "branchOptions": {
    "remoteName": "upstream"
  }
}
```

或使用 `--remote-name` 标志：

```bash
npx gt translate --enable-branching --remote-name upstream
```


### 禁用分支关系检测

如果你只想使用当前分支，而不跟踪传入分支或父分支：

```bash
npx gt translate --enable-branching --branch my-branch --disable-branch-detection
```