# 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) 来启用编辑器验证和自动补全。已发布的 schema 尚未包含 `gt` 2.16.0 中新增的 `lottie` 和 `fonts` 键，因此在 schema 更新前，编辑器可能会将这些有效设置标记出来。* ## 选项 [#options] | 选项 | 描述 | 类型 | 可选 | 默认值 | | ------------------------------------ | --------------------- | ---------- | -- | ---------------- | | [`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[]` | 是 | 参见 [`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 模板。 | — | | `lottie` | dotLottie 动画文件 (`.lottie`)。 | [Lottie](/docs/cli/reference/formats/lottie-files) | ### 文件类型键 每种文件类型都支持以下键。 * `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`。 * `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}`。 ```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..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`](/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` 设置。如果在任何层级都不存在发布配置，则会跳过发布步骤。 ## 示例配置 [#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`。