# gt: General Translation CLI tool: 配置 URL: https://generaltranslation.com/zh/docs/cli/reference/config.mdx --- title: 配置 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) 来启用编辑器验证和自动补全。* ## 选项 [#options] | 选项 | 描述 | 类型 | 可选 | 默认值 | | ------------------------------------ | --------------------- | ---------- | -- | ---------------- | | [`defaultLocale`](#default-locale) | 源内容使用的区域设置。 | `string` | 是 | `en` | | [`locales`](#locales) | 要翻译成的目标区域设置。 | `string[]` | 是 | — | | [`files`](#files) | 要翻译哪些文件以及将其保存到何处。 | `object` | 是 | — | | [`publish`](#publish) | 将翻译后的文件发布到 CDN。 | `boolean` | 是 | `false` | | [`stageTranslations`](#stage) | 在提供翻译内容前需经过人工审核。 | `boolean` | 是 | `false` | | [`requiresReview`](#requires-review) | 所有翻译后的文件的默认审核要求。 | `boolean` | 是 | `false` | | [`src`](#src) | 用于扫描内联内容的源文件 Glob 模式。 | `string[]` | 是 | 参见 [`src`](#src) | | [`dictionary`](#dictionary) | 字典文件 的路径。 | `string` | 是 | — | | [`branchOptions`](#branch-options) | 基于分支的翻译跟踪设置。 | `object` | 是 | — | | [`customMapping`](#custom-mapping) | 区域设置别名和属性覆盖设置。 | `object` | 是 | — | ## `defaultLocale` [#default-locale] **类型** `string` · **可选** · **默认值** `en` 源内容所使用的区域设置。CLI 会以此区域设置作为翻译源；在使用 `gt-next` 或 `gt-react` 时，它也是后备区域设置。 ```json title="gt.config.json" { "defaultLocale": "en" } ``` ## `locales` [#locales] **类型** `string[]` · **可选** · **默认值** — 要翻译到的目标区域设置。可接受的代码请参见[支持的区域设置](/docs/platform/dashboard/reference/supported-locales)。使用 `gt-next` 或 `gt-react` 时，这些也就是你的应用支持的区域设置。 ```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` 使用的 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) | | `twilioContentJson` | Twilio Content JSON 模板。 | — | ### 文件类型键 每种文件类型都支持以下键。 * `include` — 用于匹配待翻译文件的 glob 模式数组。请使用 `[locale]` 占位符：CLI 会将其替换为 `defaultLocale` 以查找源文件，并替换为各个目标代码以保存翻译。除 `gt` 外，每种类型都必填。 * `exclude` — 要跳过的 glob 模式数组。这里的 `[locale]` 占位符是可选的；使用 `[locales]` 可在所有区域设置中排除某个路径。 * `transform` — 重新映射输出文件名。带有 `*` 通配符的字符串会重新映射扩展名 (例如 `*.[locale].json`) 。带有 `match` 和 `replace` 的对象支持正则表达式捕获组和 `{locale}` 占位符。 * `transformationFormat` — 以不同于源文件的格式输出翻译后的文件。例如，`pot` 源文件配置 `"transformationFormat": "PO"` 时会生成 `.po` 文件。 * `requiresReview` — 将翻译后的文件设为需经人工审核后才能使用。接受 `true`/`false`，或一个包含 `include` 和 `exclude` glob 数组的对象，其中 `exclude` 优先。 * `output` — 仅用于 `gt` 文件，表示带有 `[locale]` 占位符的本地保存路径，例如 `public/i18n/[locale].json`。 * `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"] } } } ``` ## `publish` [#publish] **类型** `boolean` · **可选** · **默认值** `false` 当设为 `true` 时，在执行 [`translate`](/docs/cli/reference/commands/translate)、`upload` 或 `save-local` 后，翻译后的文件会发布到 General Translation CDN。有关按文件和按命令进行控制的说明，请参阅 [CDN 发布](#cdn-publishing)。 ```json title="gt.config.json" { "publish": true } ``` ## `stageTranslations` [#stage] **类型** `boolean` · **可选** · **默认值** `false` 当设为 `true` 时，翻译在提供给用户之前必须先经过人工审核。CLI 会在你首次运行 [`gt stage`](/docs/cli/reference/commands/stage) 时自动设置此项。启用后，`translate` 只会下载你已通过 `gt stage` 暂存的版本中的翻译；如果还没有暂存任何内容，就没有可下载的翻译。 ## `requiresReview` [#requires-review] **类型** `boolean` · **可选** · **默认值** `false` 这是项目级的审核门控默认设置：当为 `true` 时，翻译产物在客户端使用前必须先经过批准。该值必须是布尔值——如需基于 glob 按文件覆盖，请使用文件级 [`files..requiresReview`](#files) 键 (可接受布尔值或 `{ include, exclude }` glob) 。文件级策略优先；未匹配 `include` 或 `exclude` glob 的文件会回退到这个顶层默认值。 ```json title="gt.config.json" { "requiresReview": true } ``` ## `src` [#src] **类型** `string[]` · **可选** · **默认值** `src`, `app`, `pages`, `components` glob 模式 一个源文件 glob 模式数组；当你使用 `gt-next`、`gt-react` 或 `gt-react-native` 时，系统会扫描与这些模式匹配的源文件中的内联内容。 ```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` 的别名。 ```json title="gt.config.json" { "customMapping": { "cn": { "code": "zh", "name": "Mandarin" } } } ``` ## CDN 发布 [#cdn-publishing] 默认情况下，CLI 不会发布到 CDN。当你在项目“设置”中启用 CDN 后，可以按全局、按文件或按命令控制发布。 * **全局：**将顶层 [`publish`](#publish) 设为 `true`，或向 `translate`、`upload` 或 `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` 设置。如果在任何层级都不存在发布配置，则会跳过发布步骤。 ## 示例配置 [#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`) ，以及所有内联 [``](/docs/react/reference/components/t) 组件和词典条目。GT 的翻译结果将保存到 `public/i18n/fr.json` 和 `public/i18n/es.json`。