# gt: General Translation CLI tool: 配置
URL: https://generaltranslation.com/zh/docs/cli/reference/config.mdx
---
title: 配置
description: gt.config.json 文件配置文档
---

## 概述

`gt.config.json` 文件用于配置项目的 GT 设置。应将其放在项目根目录中。

CLI 设置向导 [`npx gt init`](/docs/cli/init) 会在你的项目中创建一个 `gt.config.json` 文件。

## 配置

`gt.config.json` 文件支持以下属性，但不限于这些：

* `defaultLocale`：项目的默认区域设置，即源内容所使用的区域设置。如果使用 `gt-next` 或 `gt-react`，它同时也是项目的回退区域设置。

* `locales`：项目的区域设置数组，也就是你希望将项目翻译到的那些区域设置。更多信息请参阅[支持的区域设置](/docs/platform/supported-locales)。
  如果你使用 `gt-next` 或 `gt-react`，这些也会是你的应用支持的区域设置。

* `files`：一个对象，包含你想要翻译的内容信息。

* `publish`：一个可选的布尔标志。设为 `true` 时，运行 `translate`、`upload` 或 `save-local` 后，翻译后的文件会发布到 GT CDN。默认为 `false` (不发布) 。也可以通过命令级别的 `--publish` 设置。详情请参阅 [CDN 发布](#cdn-publishing)。

* `stageTranslations`：一个可选的布尔标志，用于指示项目是否配置为使用人工审核。

* `src`：一个可选的源文件 glob 模式数组。默认值为：

```json
[
  "src/**/*.{js,jsx,ts,tsx}",
  "app/**/*.{js,jsx,ts,tsx}",
  "pages/**/*.{js,jsx,ts,tsx}",
  "components/**/*.{js,jsx,ts,tsx}"
]
```

* `dictionary`：可选的字符串，用于指定字典文件的相对路径。

* `branchOptions`：可选对象，用于配置基于分支的翻译跟踪。详见 [branching](/docs/cli/branching)。

<Callout type="info">
  为帮助验证 `gt.config.json` 文件，你可以使用适用于 CLI 的 [JSON Schema](https://assets.gtx.dev/config-schema.json)。

  将其添加到 `gt.config.json` 文件顶部：

  ```json title="gt.config.json" copy
  {
    "$schema": "https://assets.gtx.dev/config-schema.json"
  }
  ```
</Callout>

以下是 `gt.config.json` 文件的基本结构：

```json title="gt.config.json"
{
  "$schema": "https://assets.gtx.dev/config-schema.json",
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "gt": {
      "output": "..."
    },
    "json": {
      "include": [...]
    },
    "mdx": {
      "include": [...]
    },
    "md": {
      "include": [...]
    }
  },
  "src": [
    "src/**/*.{ts,tsx}",
  ],
  "dictionary": "./dictionary.json"
}
```


### 区域设置别名

如果你想为区域设置定义别名 (例如使用 `cn` 而不是 `zh`) ，可以在 `gt.config.json` 文件中指定自定义映射。

```json title="gt.config.json"
{
  "customMapping": {
    // 别名区域设置
    "cn": {
      "code": "zh" // 官方 BCP 47 区域设置代码
    }
  }
}
```

你还可以为该别名区域设置指定不同的属性。

```json title="gt.config.json"
{
  "customMapping": {
    "cn": {
      "code": "zh",
      "name": "Mandarin"
    }
  }
}
```


### 分支选项

如果你想在配置文件中设置分支相关配置，可以使用 `branchOptions` 对象：

```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 标志的优先级高于配置文件选项。更多详情请参阅[分支指南](/docs/cli/branching)。
</Callout>

***


## `files`

### 支持的文件类型

`files` 应为你想翻译的每种文件类型包含一个对应的键。
你可以将项目配置为混合使用不同的文件类型，并统一对它们进行翻译。
我们当前支持以下文件类型：

* `gt`：General Translation 文件。由 [`gt-next`](/docs/next)、[`gt-react`](/docs/react) 和 [`gt-react-native`](/docs/react-native) 使用。
* `json`：JSON 文件。
* `pot`：PO/POT (gettext) 文件。
* `yaml`：YAML 文件。
* `mdx`：Markdown 组件 (MDX) 文件。
* `md`：Markdown (MD) 文件。
* `js`：JavaScript 文件。
* `ts`：TypeScript 文件。
* `html`：HTML 文件。
* `txt`：文本文件。
* `twilioContentJson`：Twilio Content JSON 文件。用于翻译 [Twilio Content Templates](https://www.twilio.com/docs/content)。

每种文件类型都应对应一个对象，其中包含以下一个或多个键：

* `include`
* `exclude`
* `transform`
* `transformationFormat`
* `output`

### `include`

如果使用 `include` 键，其值应为一个 glob 模式数组，用于匹配你想翻译的文件。

你必须在 glob 模式中使用 `[locale]` 占位符，以确保能够正确找到源文件，并将翻译后的文件保存到正确的位置。
CLI 工具在搜索可翻译文件时，会将 `[locale]` 占位符替换为 `defaultLocale` 的值。

CLI 工具会将翻译后的文件保存到对应路径，并将 `[locale]` 占位符替换为目标区域设置代码。

```json
{
  "include": ["docs/[locale]/**/*.json"]
}
```


### `exclude`

如果使用 `exclude`，其值应为一个 glob 模式数组，用于匹配你想从翻译中排除的文件。

该模式与 `include` 模式相同，区别在于 `[locale]` 占位符是可选的。若提供，则会替换为 `defaultLocale` 的值。

```json
{
  "exclude": ["docs/[locale]/exclude/**/*.json"]
}
```

如果你想让某些文件在所有区域设置中都不进行翻译，可以使用 `[locales]` 占位符来代替 `[locale]`。

```json
{
  "exclude": ["docs/[locales]/exclude/**/*.json"]
}
```


### `transform`

`transform` 可以是字符串，也可以是对象。

如果 `transform` 是字符串，则表示对文件名进行重映射。它应包含一个通配符 `*`，该通配符会替换为原始文件名 (即第一个 `.` 之前的所有内容) 。

例如，如果你希望所有翻译后文件的扩展名使用 `.[locale].json` 而不是 `.json`，可以使用以下配置：

```json
{
  "transform": "*.[locale].json"
}
```

或者，如果 `transform` 是一个对象，则应包含以下属性：

* `match` (可选) ：用于匹配字符串的正则表达式模式，支持捕获组
* `replace` (必填) ：用于替换匹配结果的字符串或正则表达式模式

这两个值都支持正则表达式捕获组，并且都会应用到输出文件的完整相对文件名。

```json
{
  "transform": {
    "match": "^(.*)$",
    "replace": "{locale}/$1"
  }
}
```

例如，上述配置会将翻译后的文件保存到目标区域设置的子目录中。


#### 特殊占位符

`transform` 选项支持多种特殊占位符，可在 `match` 和 `replace` 字符串中使用：

* `{locale}`：区域设置代码占位符，其行为会根据上下文而变化：
  * **在 `match` 字符串中**：会替换为默认区域设置代码 (例如 `"en"`) ，用于帮助识别源文件
  * **在 `replace` 字符串中**：会替换为目标区域设置代码 (例如 `"fr"`、`"es"`) ，用于生成翻译后的输出文件

例如，如果默认区域设置是 `"en"`，并且要翻译成 `"fr"`：

* `match` 模式 `"content/{locale}/file.md"` 会变为 `"content/en/file.md"`
* `replace` 模式 `"content/{locale}/file.md"` 会变为 `"content/fr/file.md"`

此外，`getLocaleProperties` 中的任何其他属性也可以作为占位符使用，并且具有相同的上下文相关行为。

<Callout type="info">
  如果你的文档或 i18n 框架要求翻译后的文件使用特定的文件扩展名，而不是采用基于子目录的区域设置路由，这会很有用。
</Callout>

### `transformationFormat`

`transformationFormat` 键用于为翻译后的输出文件指定不同的文件格式。当源文件是 模板，且翻译后需要生成另一种文件类型时，这个选项会很有用。

例如，POT (PO Template) 文件是源 模板，但翻译后的输出应为 PO 文件：

```json
{
  "files": {
    "pot": {
      "include": ["locales/[locale]/**/*.pot"],
      "transformationFormat": "PO"
    }
  }
}
```

该值应为一个字符串，且必须与受支持的文件格式键之一匹配 (例如：`"PO"`) 。

### `output`

此键仅用于 General Translation 文件，具体来说，用于将翻译保存到本地。如果你使用 GT CDN，则不需要此键。

该值应为一个字符串，其中包含 `[locale]` 占位符，用于指明翻译的保存位置。

例如，如果你想将西班牙语翻译保存到 `public/i18n` 目录下名为 `ui.es.json` 的文件中，应使用以下字符串：

```json
{
  "output": "public/i18n/[locale].json"
}
```

<Callout type="info">
  仅当你使用 `gt-next` 或 `gt-react`，并且想将翻译保存在本地而非使用 GT CDN 时，才应使用此选项。

  目前，每个区域设置只能生成一个文件。
</Callout>

***


### 文件类型：`gt` [#gt]

**支持的键**

* `output` (必填) 

**示例**

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "gt": {
      "output": "public/i18n/[locale].json"
    }
  }
}
```

此配置会指示 CLI 工具将你的法语和西班牙语翻译保存到 `public/i18n/[locale].json` 目录。

默认情况下，在此配置下，CLI 工具不会将你的翻译发布到 GT CDN。

***


### 文件类型：`json` [#json]

**支持的键**

* `include` (必填) 
* `exclude` (可选) 
* `transform` (可选) 

**示例**

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "json": {
      "include": ["json_files/[locale]/**/*.json"],
      "exclude": ["json_files/[locale]/exclude/**/*.json"]
    }
  }
}
```

假设你的项目默认区域设置是 `en`，并且你希望将项目翻译为 `fr` 和 `es`。

使用此配置时，CLI 会搜索子目录 `json_files/en/` 下的所有 JSON 文件，并将翻译后的文件保存到 `json_files/fr/` 和 `json_files/es/`。

它会忽略子目录 `json_files/en/exclude/` 中的所有文件。

***


### 文件类型：`yaml` [#yaml]

**支持的键**

* `include` (必填) 
* `exclude` (可选) 
* `transform` (可选) 

**示例**

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "yaml": {
      "include": ["yaml_files/[locale]/**/*.yaml"],
      "exclude": ["yaml_files/[locale]/exclude/**/*.yaml"]
    }
  }
}
```

假设你的项目默认区域设置为 `en`，并且你希望将项目翻译为 `fr` 和 `es`。

使用此配置时，CLI 会查找 `yaml_files/en/` 子目录下的所有 YAML 文件，并将翻译后的文件保存到 `yaml_files/fr/` 和 `yaml_files/es/`。

它会忽略 `yaml_files/en/exclude/` 子目录中的所有文件。

***


### 文件类型：`mdx` [#mdx]

**支持的键**

* `include` (必需) 
* `exclude` (可选) 
* `transform` (可选) 

**示例**

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["ja"],
  "files": {
    "mdx": {
      "include": ["content/docs/[locale]/**/*.mdx"],
      "transform": "*.[locale].mdx"
    }
  }
}
```

此配置会让 CLI 工具搜索 `content/docs/en` 目录下的所有 MDX 文件，并将翻译后的文件保存到 `content/docs/ja` 目录。

`transform` 键会将翻译后文件的扩展名改为 `.ja.mdx`。

***


### 文件类型：`md` [#md]

**支持的键**

* `include` (必填) 
* `exclude` (可选) 
* `transform` (可选) 

**示例**

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["ja"],
  "files": {
    "md": {
      "include": ["content/docs/[locale]/**/*.md"],
      "exclude": ["content/docs/[locale]/exclude/**/*.md"],
      "transform": "*.[locale].md"
    }
  }
}
```

此配置会让 CLI 工具搜索 `content/docs/en` 目录下的所有 MD 文件，并将译后的文件保存到 `content/docs/ja` 目录。

`transform` 键会将译后文件的扩展名改为 `.ja.md`。

`content/docs/en/exclude` 目录中的所有文件都会被忽略。

***


### 文件类型：`js` [#js]

**支持的键**

* `include` (必填) 
* `exclude` (可选) 
* `transform` (可选) 

**示例**

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "js": {
      "include": ["scripts/[locale]/**/*.js"]
    }
  }
}
```

此配置会让 CLI 工具在 `scripts/en` 目录下查找所有 JavaScript 文件，并将翻译后的文件保存到 `scripts/fr` 和 `scripts/es` 目录。

***


### 文件类型：`ts` [#ts]

**支持的键**

* `include` (必需) 
* `exclude` (可选) 
* `transform` (可选) 

**示例**

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "ts": {
      "include": ["scripts/[locale]/**/*.ts"]
    }
  }
}
```

此配置会让 CLI 工具搜索 `scripts/en` 目录下的所有 TypeScript 文件，并将翻译后的文件保存到 `scripts/fr` 和 `scripts/es` 目录。

***


### 文件类型：`html` [#html]

**支持的键**

* `include` (必填) 
* `exclude` (可选) 
* `transform` (可选) 

**示例**

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["ja"],
  "files": {
    "html": {
      "include": ["content/docs/[locale]/**/*.html"],
      "exclude": ["content/docs/[locale]/exclude/**/*.html"],
      "transform": "*.[locale].html"
    }
  }
}
```

此配置会让 CLI 工具搜索 `content/docs/en` 目录下的所有 HTML 文件，并将翻译后的文件保存到 `content/docs/ja` 目录。

`transform` 键会将翻译后文件的扩展名改为 `.ja.html`。

`content/docs/en/exclude` 目录中的所有文件都会被忽略。

***


### 文件类型：`txt` [#txt]

**支持的键**

* `include` (必填) 
* `exclude` (可选) 
* `transform` (可选) 

**示例**

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["ja"],
  "files": {
    "txt": {
      "include": ["content/docs/[locale]/**/*.txt"],
      "exclude": ["content/docs/[locale]/exclude/**/*.txt"],
      "transform": "*.[locale].txt"
    }
  }
}
```

此配置会让 CLI 工具搜索 `content/docs/en` 目录下的所有文本文件，并将译文文件保存到 `content/docs/ja` 目录。

`transform` 键会将译文文件的扩展名改为 `.ja.txt`。

`content/docs/en/exclude` 目录中的所有文件都会被忽略。

***


### 文件类型：`twilioContentJson` [#twilioContentJson]

**支持的键**

* `include` (必填) 
* `exclude` (可选) 
* `transform` (可选) 

**示例**

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["es", "fr"],
  "files": {
    "twilioContentJson": {
      "include": ["twilio/[locale]/**/*.json"]
    }
  }
}
```

此配置会让 CLI 工具搜索 `twilio/en` 目录下的所有 Twilio Content JSON 文件，并将翻译后的文件保存到 `twilio/es` 和 `twilio/fr` 目录中。

Twilio Content JSON 文件是供 [Twilio&#39;s Content Template Builder](https://www.twilio.com/docs/content) 用于 WhatsApp、SMS 和 RCS 消息的结构化模板。CLI 会翻译面向用户的字符串值 (如正文文本、按钮标签和卡片标题) ，同时保留模板结构、变量占位符和不可翻译的字段。

***


## CDN 发布 [#cdn-publishing]

默认情况下，CLI 不会将翻译后的文件发布到 GT CDN。如果你已在项目设置中启用 CDN，则可以在全局、单个文件或单条命令级别控制发布。

### 全局 publish 标志

在顶层设置 `publish`，即可将**所有**已翻译文件发布到 CDN：

```json title="gt.config.json"
{
  "publish": true
}
```

你也可以为 `translate`、`upload` 或 `save-local` 命令传入 `--publish`：

```bash
npx gt translate --publish
```


### GT JSON 标志

如果只想发布 GT 的内部翻译格式，请使用 `files.gt` 下的 `publish` 键：

```json title="gt.config.json"
{
  "files": {
    "gt": {
      "output": "public/i18n/[locale].json",
      "publish": true
    }
  }
}
```


### 按文件控制发布

对于其他文件类型 (`json`、`yaml`、`mdx`、`md`、`po`、`xliff`、`csv`、`properties`) ，你可以在 `include` 数组中使用对象而非普通的 glob 字符串，以按文件控制发布：

```json title="gt.config.json"
{
  "files": {
    "json": {
      "include": [
        { "pattern": "locales/[locale]/*.json", "publish": true },
        { "pattern": "locales/[locale]/internal/**/*.json", "publish": false }
      ]
    }
  }
}
```

`include` 中的每个条目都可以是以下两种形式之一：

* **字符串** —— glob 模式 (不单独指定发布偏好；使用全局 `publish` 设置) 
* 带有 `pattern` (glob) 和 `publish` (布尔值) 的 **对象** —— 明确指定将匹配的文件纳入或排除发布


### 判定顺序

对于任意给定文件，CLI 会按以下顺序判断是否发布：

1. **显式禁用** — 文件匹配带有 `"publish": false` 的 include 条目 → 不发布，或从 CDN 中移除
2. **显式启用** — 文件匹配带有 `"publish": true` 的 include 条目 → 发布到 CDN
3. **全局兜底** — 使用顶层的 `publish` 设置 (如果未设置，则默认为 `false`) 

如果在任何层级都没有 publish 配置，则会完全跳过发布步骤。

***

## 示例配置

下面来解析一个示例 `gt.config.json` 文件：

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "gt": {
      "output": "public/i18n/[locale].json"
    },
    "mdx": {
      "include": ["content/docs/[locale]/**/*.mdx"],
      "transform": "*.[locale].mdx"
    },
    "json": {
      "include": ["resources/[locale]/**/*.json"],
      "exclude": ["resources/[locale]/exclude/**/*.json"]
    }
  }
}
```

在此示例中，我们通过一次调用 [`gt translate`](/docs/cli/translate) 翻译以下文件：

* `content/docs/en` 目录中的所有 MDX 文件。
* `resources/en` 目录中的所有 JSON 文件 (不包括 `resources/en/exclude` 目录中的任何文件) 。
* 你的 React 或 Next.js 项目中的所有内联 `<T>` 组件。
* 你的 `dictionary.[json|js|ts]` 文件。

GT：翻译结果将保存到 `public/i18n/es.json` 和 `public/i18n/fr.json`。你可以使用 [`loadTranslations`](/docs/react/api/config/load-translations) 加载这些文件。

MDX：翻译结果将保存到 `content/docs/fr` 和 `content/docs/es` 目录中。
文件扩展名将分别从 `.mdx` 改为 `.fr.mdx` 和 `.es.mdx`。

JSON：翻译结果将保存到 `resources/fr` 和 `resources/es` 目录中。

***


## 后续步骤

了解如何使用 [init 命令](/docs/cli/init) 生成此配置文件。