# gt: General Translation CLI tool: 配置
URL: https://generaltranslation.com/zh/docs/cli/reference/config.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 使用 gt.config.json 文件配置 General Translation CLI。gt.config.json 的 API 参考。

`gt.config.json` 文件用于配置 CLI 要翻译的内容以及结果的保存位置。请将它放在项目根目录下。你可以使用 [`gt init`](/docs/cli/reference/commands/init) 或 [`gt configure`](/docs/cli/reference/commands/configure) 创建该文件，也可以手动编写。

*注意：可通过添加带有 `$schema` 键的 [JSON Schema](https://assets.gtx.dev/config-schema.json) 来启用编辑器验证和自动补全。已发布的 schema 落后于部分有效的文件键，包括 `pot`、`html`、`txt`、`twilioContentJson`、`lottie`、`dotStrings`、`dotStringsdict`、`androidStrings`、`xcstrings` 和 `srt`，同时也遗漏了 `fonts` 和 `options.saveLocal`。在 schema 更新前，编辑器可能会将这些字段标记为 schema 不支持。*

## 选项 [#options]

| 选项                                   | 描述                                 | 类型         | 可选 | 默认值                   |
| ------------------------------------ | ---------------------------------- | ---------- | -- | --------------------- |
| [`projectId`](#project-id)           | 用于 API 和翻译工作流程的项目。                 | `string`   | 是  | `GT_PROJECT_ID`       |
| [`baseUrl`](#base-url)               | General Translation API 请求的基础 URL。 | `string`   | 是  | `https://api.gtx.dev` |
| [`defaultLocale`](#default-locale)   | 源内容使用的区域设置。                        | `string`   | 是  | `en`                  |
| [`locales`](#locales)                | 要翻译成的目标区域设置。                       | `string[]` | 是  | —                     |
| [`files`](#files)                    | 要翻译哪些文件以及将其保存到何处。                  | `object`   | 是  | —                     |
| [`fonts`](#fonts)                    | 供 Lottie 翻译任务使用的字体文件。              | `object`   | 是  | —                     |
| [`publish`](#publish)                | 将翻译后的文件发布到 CDN。                    | `boolean`  | 是  | `false`               |
| [`stageTranslations`](#stage)        | 下载翻译前使用暂存工作流。                      | `boolean`  | 是  | `false`               |
| [`requiresReview`](#requires-review) | 所有翻译后的文件的默认审校要求。                   | `boolean`  | 是  | `false`               |
| [`src`](#src)                        | 用于扫描内联内容的源文件 Glob 模式。              | `string[]` | 是  | 特定于框架                 |
| [`dictionary`](#dictionary)          | 字典文件 的路径。                          | `string`   | 是  | —                     |
| [`branchOptions`](#branch-options)   | 基于分支的翻译跟踪设置。                       | `object`   | 是  | —                     |
| [`customMapping`](#custom-mapping)   | 区域设置别名和属性覆盖设置。                     | `object`   | 是  | —                     |
| [`options.saveLocal`](#save-local)   | 在加入队列前检测并提交本地翻译修改。                 | `boolean`  | 是  | `false`               |

## `projectId` [#project-id]

**Type** `string` · **Optional** · **Default** `GT_PROJECT_ID`

用于 API 和翻译工作流程的项目。`--project-id` 标志会覆盖环境变量中的值，但当配置中指定了 `projectId` 时，两者必须一致。

```json title="gt.config.json"
{
  "projectId": "project-id"
}
```

## `baseUrl` [#base-url]

**Type** `string` · **Optional** · **Default** `https://api.gtx.dev`

CLI 请求 (包括 [`gt api`](/docs/cli/reference/commands/api)) 所使用的 API 源地址。仅当你的 workflow 使用自定义的 General Translation API endpoint 时，才需要设置此项。

```json title="gt.config.json"
{
  "baseUrl": "https://api.gtx.dev"
}
```

## `defaultLocale` [#default-locale]

**类型** `string` · **可选** · **默认值** `en`

源内容所使用的区域设置。CLI 会以此区域设置作为翻译源；在使用 `gt-next`、`gt-react` 或 `gt-vue` 时，它也是后备区域设置。

```json title="gt.config.json"
{
  "defaultLocale": "en"
}
```

## `locales` [#locales]

**类型** `string[]` · **可选** · **默认值** —

要翻译到的目标区域设置。可接受的代码请参见[支持的区域设置](/docs/platform/dashboard/reference/supported-locales)。对于接受区域设置列表的框架初始化器，这些也就是你的应用支持的区域设置。

```json title="gt.config.json"
{
  "locales": ["fr", "es", "ja"]
}
```

## `files` [#files]

**类型** `object` · **可选** · **默认值** —

一个对象，每种要翻译的文件类型对应一个键，其值为一个设置对象。有关各类型的具体说明，请参阅[文件格式](/docs/cli/reference/formats/gt-jsx-files)。

### 支持的文件类型

| 键                   | 文件类型                                                                                                | 参考                                                                       |
| ------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `gt`                | 供 `gt-next`、`gt-react`、`gt-react-native`、`gt-tanstack-start` 和 `gt-vue` 使用的 General Translation 文件。 | [GT](/docs/cli/reference/formats/gt-jsx-files)                           |
| `json`              | JSON 文件。                                                                                            | [JSON](/docs/cli/reference/formats/json-files)                           |
| `yaml`              | YAML 文件 (`.yaml` 和 `.yml`) 。                                                                        | [YAML](/docs/cli/reference/formats/yaml-files)                           |
| `pot`               | PO/POT gettext 文件。                                                                                  | [PO / POT](/docs/cli/reference/formats/po-pot-files)                     |
| `mdx`               | MDX 文件。                                                                                             | [MDX and Markdown](/docs/cli/reference/formats/mdx-md-files)             |
| `md`                | Markdown 文件。                                                                                        | [MDX and Markdown](/docs/cli/reference/formats/mdx-md-files)             |
| `ts`                | TypeScript 文件。                                                                                      | [TypeScript and JavaScript](/docs/cli/reference/formats/ts-js-files)     |
| `js`                | JavaScript 文件。                                                                                      | [TypeScript and JavaScript](/docs/cli/reference/formats/ts-js-files)     |
| `html`              | HTML 文件。                                                                                            | [HTML](/docs/cli/reference/formats/html-files)                           |
| `txt`               | 纯文本文件。                                                                                              | [纯文本](/docs/cli/reference/formats/plain-text-files)                      |
| `srt`               | SubRip 字幕文件 (`.srt`)。                                                                               | [SRT](/docs/cli/reference/formats/srt-files)                             |
| `twilioContentJson` | Twilio Content JSON 模板。                                                                             | —                                                                        |
| `lottie`            | dotLottie 动画文件 (`.lottie`)。                                                                         | [Lottie](/docs/cli/reference/formats/lottie-files)                       |
| `xcstrings`         | Apple String Catalogs (`.xcstrings`)。                                                               | [.xcstrings](/docs/cli/reference/formats/xcstrings-files)                |
| `dotStrings`        | `.strings` 表，`.lproj` 目录中每个区域设置一个。                                                                  | [.strings](/docs/cli/reference/formats/dot-strings-files)                |
| `dotStringsdict`    | `.stringsdict` 复数文件，`.lproj` 目录中每个区域设置一个。                                                           | [.stringsdict](/docs/cli/reference/formats/dot-stringsdict-files)        |
| `androidStrings`    | Android `strings.xml` 资源文件。                                                                         | [Android strings.xml](/docs/cli/reference/formats/android-strings-files) |

`dotStrings` 和 `dotStringsdict` 需要 `gt` 2.18.1 或更高版本，`androidStrings` 需要 `gt` 2.19.0 或更高版本，`xcstrings` 需要 `gt` 2.21.0 或更高版本，`srt` 需要 `gt` 2.22.2 或更高版本。

<Callout type="info">
  **v2.18.1 中的变更：** Apple 文件的键由 `strings` 和 `stringsdict` 更改为 `dotStrings` 和 `dotStringsdict`。当前版本不再识别旧的键。
</Callout>

### 文件类型键

每种文件类型都支持以下键。

* `include` — 用于匹配待翻译文件的 glob 模式数组。请使用 `[locale]` 占位符：CLI 会将其替换为 `defaultLocale` 以查找源文件，并替换为各个目标代码以保存翻译。除 `gt` 外，每种类型都必填。
* `exclude` — 要跳过的 glob 模式数组。这里的 `[locale]` 占位符是可选的；使用 `[locales]` 可在所有区域设置中排除某个路径。
* `transform` — 重新映射输出文件名。带有 `*` 通配符的字符串会重新映射扩展名 (例如 `*.[locale].json`) 。带有 `match` 和 `replace` 的对象支持正则表达式捕获组以及[区域设置占位符](#locale-placeholders)中的区域设置占位符。
* `transformationFormat` — 以不同于源文件的格式输出翻译后的文件。例如，`pot` 源文件配置 `"transformationFormat": "PO"` 时会生成 `.po` 文件。
* `requiresReview` — 将翻译后的文件设为需经人工审校后才能使用。接受 `true`/`false`，或一个包含 `include` 和 `exclude` glob 数组的对象，其中 `exclude` 优先。
* `output` — 仅用于 `gt` 文件，表示带有 `[locale]` 占位符的本地保存路径，例如 `public/i18n/[locale].json`。当 Locadex 工作流使用 **Preserve local edits** 且未启用顶层 CDN 发布时，此项为必填；请参阅 [Locadex preserve local edits](#locadex-requirements)。
* `parsingFlags` — 仅用于 `gt` 文件，用于控制内联内容解析的选项。请参阅 [`autoderive`](/docs/cli/guides/using-autoderive) 和 [automatic JSX injection](/docs/cli/guides/using-auto-jsx)。

```json title="gt.config.json"
{
  "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"]
    }
  }
}
```

### 区域设置占位符 [#locale-placeholders]

对象 `transform` 的 `replace` 值支持 `{...}` 占位符，可展开为目标区域设置的属性。无法识别的名称会以原样文本保留在输出中。

| 占位符                  | 描述                                                         | `pt-BR` 示例             |
| -------------------- | ---------------------------------------------------------- | ---------------------- |
| `{locale}`           | 与 [`locales`](#locales) 中的写法完全一致的区域设置。`{localeCode}` 是其别名。 | `pt-BR`                |
| `{localeName}`       | 区域设置的英文名称，包括区域。                                            | `Brazilian Portuguese` |
| `{localeNativeName}` | 区域设置的本地名称，包括区域。                                            | `português (Brasil)`   |
| `{languageCode}`     | 单独的语言子标签。                                                  | `pt`                   |
| `{regionCode}`       | 单独的区域子标签。                                                  | `BR`                   |
| `{scriptCode}`       | 单独的书写系统子标签。                                                | `Latn`                 |
| `{minimizedCode}`    | 标签的最短无歧义形式。                                                | `pt`                   |
| `{maximizedCode}`    | 完全展开的标签，包括书写系统。                                            | `pt-Latn-BR`           |
| `{emoji}`            | 与区域设置关联的旗帜表情符号。                                            | 🇧🇷                   |

其余 [`LocaleProperties`](/docs/platform/core/reference/types/locale-properties) 字段也可按名称使用，包括 `languageName`、`nativeLanguageName`、`regionName`、`nativeRegionName`、`scriptName`、`nativeScriptName`、`nameWithRegionCode`、`nativeNameWithRegionCode`、`maximizedName`、`nativeMaximizedName`、`minimizedName` 和 `nativeMinimizedName`。

`{locale}` 使用配置中的拼写，而非规范的 BCP-47 形式。因此，配置为 `fr-ca` 的区域设置会生成 `fr-ca`，而不是 `fr-CA`。这与 `include`、`exclude` 和 `output` 中的 `[locale]` 占位符保持一致，从而确保文件路径和本地化 URL 一致。需要使用标准化后的标签时，请改用 `{minimizedCode}`、`{maximizedCode}` 或 `{regionCode}`。

唯一的例外是 [`androidStrings`](/docs/cli/reference/formats/android-strings-files)，其中两个占位符都会展开为 Android 资源目录限定符——`fr-CA` 会变成 `fr-rCA`——因为 Android 遇到无法解析的 `values-*` 目录名时会导致构建失败。

```json title="gt.config.json"
{
  "files": {
    "json": {
      "include": ["locales/[locale]/**/*.json"],
      "transform": {
        "match": "locales/(.*)/(.*)\\.json",
        "replace": "locales/{locale}/$2.{languageCode}.json"
      }
    }
  }
}
```

## `fonts` [#fonts]

**类型** `object` · **可选** · **默认值** —

翻译任务运行前要上传的字体文件。使用相对于项目根目录解析的 `include` glob 模式和可选的 `exclude` glob 模式。匹配 `.ttf` 和 `.otf` 文件；CLI 会将其作为二进制数据读取，并上传为 Organization 的持久化资源，用于 Lottie 布局处理。

| 属性        | 描述                  | 类型         | 可选 | 默认值  |
| --------- | ------------------- | ---------- | -- | ---- |
| `include` | 要上传的字体 glob 模式。     | `string[]` | 否  | —    |
| `exclude` | 要从匹配结果中排除的 glob 模式。 | `string[]` | 是  | `[]` |

```json title="gt.config.json"
{
  "fonts": {
    "include": ["public/fonts/**/*.{ttf,otf}"],
    "exclude": ["public/fonts/legacy/**"]
  }
}
```

CLI 会在执行会将新任务加入队列的 [`gt stage`](/docs/cli/reference/commands/stage)、[`gt upload`](/docs/cli/reference/commands/upload)、[`gt enqueue`](/docs/cli/reference/commands/enqueue) 和 [`gt translate`](/docs/cli/reference/commands/translate) 前同步匹配的字体。启用 `stageTranslations` 后，[`gt translate`](/docs/cli/reference/commands/translate) 仅下载暂存版本，不同步字体。字体同步失败会发出警告，但不会中止翻译；Lottie 处理将继续使用后备字体。有关字体验证和存储行为，请参阅[上传项目资源](/docs/platform/openapi/reference/project/upload-assets)。

## `publish` [#publish]

**类型** `boolean` · **可选** · **默认值** `false`

当设为 `true` 时，在执行 [`translate`](/docs/cli/reference/commands/translate)、[`upload`](/docs/cli/reference/commands/upload) 或 [`save-local`](/docs/cli/reference/commands/save-local) 后，翻译后的文件会发布到 General Translation CDN。Lottie 翻译仍仅可通过 API 和 CLI 下载获取；设置 `publish` 不会使 `.lottie` 文件可从 CDN 获取。有关按文件和按命令进行控制的说明，请参阅 [CDN 发布](#cdn-publishing)。

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

## `stageTranslations` [#stage]

**类型** `boolean` · **可选** · **默认值** `false`

当设为 `true` 时，CLI 仅下载通过 [`gt stage`](/docs/cli/reference/commands/stage) 提交的版本。CLI 会在你首次运行 [`gt stage`](/docs/cli/reference/commands/stage) 时自动设置此项。对于人工审校以及 [Lottie](/docs/cli/reference/formats/lottie-files) 等异步格式，请使用暂存工作流；项目的审校设置决定已完成的翻译是否也需要批准。

## `requiresReview` [#requires-review]

**类型** `boolean` · **可选** · **默认值** `false`

这是项目级的审核门控默认设置：当为 `true` 时，翻译产物在客户端使用前必须先经过批准。该值必须是布尔值——如需基于 glob 按文件覆盖，请使用文件级 [`files.<type>.requiresReview`](#files) 键 (可接受布尔值或 `{ include, exclude }` glob) 。文件级策略优先；未匹配 `include` 或 `exclude` glob 的文件会回退到这个顶层默认值。

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

## `src` [#src]

**类型** `string[]` · **可选** · **默认值** 特定于框架的源文件 glob 模式

一个源文件 glob 模式数组；系统会扫描匹配的源文件中的内联内容。React 系列项目默认扫描 `src`、`app`、`pages` 和 `components` 下的 JavaScript 与 TypeScript 文件。Vue 项目还会扫描根目录下的 `*.vue` 文件，以及 `composables`、`layouts`、`plugins`、`server`、`stores`、`utils`、`views` 等 Vue 和 Nuxt 惯用目录中的 JavaScript、TypeScript 和 Vue 文件。

```json title="gt.config.json"
{
  "src": [
    "src/**/*.{js,jsx,ts,tsx}",
    "app/**/*.{js,jsx,ts,tsx}",
    "pages/**/*.{js,jsx,ts,tsx}",
    "components/**/*.{js,jsx,ts,tsx}"
  ]
}
```

## `dictionary` [#dictionary]

**类型** `string` · **可选** · **默认值** —

字典文件的相对路径。省略时，CLI 会在 `./src` 和 `./` 下查找 `dictionary.[json|ts|js]`。

```json title="gt.config.json"
{
  "dictionary": "./dictionary.json"
}
```

## `branchOptions` [#branch-options]

**类型** `object` · **可选** · **默认值** —

配置基于分支的翻译跟踪。请参阅[按分支跟踪翻译](/docs/cli/guides/branching)。CLI 选项的优先级高于这些值。

| Property             | Description         | Type      | Optional | Default  |
| -------------------- | ------------------- | --------- | -------- | -------- |
| `enabled`            | 为项目启用分支跟踪。          | `boolean` | Yes      | `false`  |
| `currentBranch`      | 覆盖自动检测到的分支名称。       | `string`  | Yes      | —        |
| `autoDetectBranches` | 检测传入分支与当前检出分支之间的关系。 | `boolean` | Yes      | `true`   |
| `remoteName`         | 用于检测分支的 Git 远程名称。   | `string`  | Yes      | `origin` |

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

## `customMapping` [#custom-mapping]

**类型** `object` · **可选** · **默认值** —

将某个区域设置设为另一个代码的别名，并可选择覆盖其属性。例如，将 `cn` 设为官方代码 `zh` 的别名。

使用别名时，请将 `defaultLocale` 以及 `locales` 中的条目设置为别名 (`cn`) ，而不是规范代码 (`zh`) 。

```json title="gt.config.json"
{
  "defaultLocale": "cn",
  "locales": ["cn", "fr", "en"],
  "customMapping": {
    "cn": {
      "code": "zh",
      "name": "Mandarin"
    }
  }
}
```

## `options.saveLocal` [#save-local]

**Type** `boolean` · **Optional** · **Default** `false`

在 [`gt translate`](/docs/cli/reference/commands/translate) 或 [`gt stage`](/docs/cli/reference/commands/stage) 将新任务加入队列之前，检测此前下载的本地翻译文件中的改动并提交其差异。请在顶层 `options` 对象中设置该选项。`--save-local` 和 `--no-save-local` 选项可为单次运行覆盖此设置。

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

### 版本历史

| 版本       | 变更                                                    |
| -------- | ----------------------------------------------------- |
| `2.20.3` | 本地编辑改为按需启用；将此键设为 `true` 或传入 `--save-local` 以启用该 step。 |

## CDN 发布 [#cdn-publishing]

默认情况下，CLI 不会发布到 CDN。当你在项目“设置”中启用 CDN 后，可以按全局、按文件或按命令控制发布。

* **全局：**将顶层 [`publish`](#publish) 设为 `true`，或向 [`translate`](/docs/cli/reference/commands/translate)、[`upload`](/docs/cli/reference/commands/upload) 或 [`save-local`](/docs/cli/reference/commands/save-local) 传递 `--publish`。
* **仅 GT 文件：**在 `files.gt` 下设置 `publish: true`。
* **按文件：**在 `include` 数组中，用包含 `pattern` 和 `publish` 的对象替换 glob 字符串，以明确指定将匹配的文件纳入或排除发布。

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

对于任何文件，CLI 都会按以下顺序解析发布设置：先看显式的 `"publish": false` 不发布指定，再看显式的 `"publish": true` 启用发布，最后看全局 `publish` 设置。如果在任何层级都不存在发布配置，则会跳过发布步骤。

## Locadex 保留本地编辑 [#locadex-requirements]

当 Locadex 自动化启用了 **Preserve local edits** 时，需要配置顶层的 `"publish": true` 或 `files.gt.output`。Locadex 会在运行翻译前对此进行验证。

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

按文件配置和 `files.gt.publish` 设置都不满足此项检查。若未在顶层启用 CDN 发布，`files.gt.output` 会告知工作流本地 GTJSON 翻译的存储位置，以便保留已有的编辑内容。

## 示例配置 [#example]

```json title="gt.config.json"
{
  "$schema": "https://assets.gtx.dev/config-schema.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/reference/commands/translate)，即可翻译 `content/docs/en` 下的 MDX 文件 (保存到 `content/docs/fr` 和 `content/docs/es`，文件扩展名分别为 `.fr.mdx` 和 `.es.mdx`) 、`resources/en` 下的 JSON 文件 (不包括 `resources/en/exclude`) ，以及所有内联 [`<T>`](/docs/react/reference/components/t) 组件和词典条目。GT 的翻译结果将保存到 `public/i18n/fr.json` 和 `public/i18n/es.json`。

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.