仪表板

配置

gt.config.json 文件配置文档

概览

gt.config.json 文件用于配置项目的 GT 设置，需放置在项目根目录。

CLI 设置向导 npx gtx-cli init 会在你的项目中自动生成 gt.config.json 文件。

配置

gt.config.json 文件支持以下属性（不限于此）：

  • defaultLocale：项目的默认 locale。源内容以该 locale 编写。同时也是项目的 fallback locale（在使用 gt-next 或 gt-react 时）。

  • locales：项目的 locale 数组，即你希望将项目翻译到的目标 locale。详见支持的 locales。 如果你使用 gt-next 或 gt-react，这些也是你的应用所支持的 locales。

  • files：一个对象，包含需要翻译的内容配置信息。

  • stageTranslations：可选布尔标志，指示项目是否启用人工审核流程。

  • src：源文件的可选文件通配符（glob）模式数组。默认为：

[
  "src/**/*.{js,jsx,ts,tsx}",
  "app/**/*.{js,jsx,ts,tsx}",
  "pages/**/*.{js,jsx,ts,tsx}",
  "components/**/*.{js,jsx,ts,tsx}"
]
  • dictionary: 可选字符串，用于指定字典文件的相对路径。

为便于验证你的 gt.config.json 文件，你可以在 CLI 中使用 JSON Schema。

将其添加到 gt.config.json 文件的开头：

gt.config.json
{
  "$schema": "https://assets.gtx.dev/config-schema.json",
}

下面是 gt.config.json 文件的示例框架：

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"
}

Locale 别名

如果你需要为某个 locale 设置别名（例如用 cn 代替 zh），可以在 gt.config.json 文件中配置自定义映射。

gt.config.json
{
  "customMapping": {
    "cn": {
      "code": "zh",
    }
  }
}

你也可以为该别名对应的 locale 指定不同的属性。

gt.config.json
{
  "customMapping": {
    "cn": {
      "code": "zh",
      "name": "中文",
    }
  }
}

files

支持的文件类型

files 应为你想要翻译的每种文件类型提供一个键。 你可以在项目中混合使用不同的文件类型，并让它们全部参与翻译。 我们目前支持以下文件类型：

  • gt: General Translation 文件。
  • json: JSON 文件。
  • yaml: YAML 文件。
  • mdx: Markdown 组件（MDX）文件。
  • md: Markdown（MD）文件。
  • js: JavaScript 文件。
  • ts: TypeScript 文件。

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

  • include
  • exclude
  • transform
  • output

include

如果使用，include 键的值应为一个由 glob 模式组成的数组，这些模式应匹配你要翻译的 files。

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

CLI 工具会将译文文件保存到相应路径，并将路径中的 [locale] 占位符替换为目标语言代码。

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

exclude

如果使用，exclude 键的值应为一个由 glob 模式组成的数组，用于匹配你想从翻译中排除的 files。

该模式与 include 模式相同，不同之处在于 [locale] 占位符是可选的。若提供，则会被替换为 defaultLocale 的 value。

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

如果你想在所有 locales 中将某些文件统一排除出翻译，可以使用 [locales] 占位符替代 [locale]。

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

transform

transform 可以是字符串或对象。

当 transform 为字符串时，它用于重映射文件名。字符串中应包含通配符 *，该通配符会被原始文件名（第一个 . 之前的部分）替换。

例如，如果你希望所有已翻译文件的扩展名从 .json 改为 .[locale].json，可以使用以下配置：

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

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

  • match（可选）：用于匹配字符串的正则表达式模式，支持捕获组
  • replace（必需）：用于将匹配内容替换为指定结果的字符串或正则表达式模式

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

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

例如，上述配置会将已翻译的 files 保存到目标 locale 的子目录中。

特殊占位符

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 中的任何其他属性也可以作为占位符使用，并具有相同的、取决于上下文的替换行为。

如果你的文档或 i18n 框架要求为翻译后的文件使用特定的文件扩展名，而不是通过子目录进行基于语言代码的路由，这会很有用。

output

此键仅用于 General Translation 文件，用于在本地保存翻译。如果你使用 GT CDN，则不需要此键。

该 value 应为包含 [locale] 占位符的字符串，用于指示保存翻译文件的位置。

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

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

仅在你使用 gt-next 或 gt-react，且希望将翻译保存在本地而非通过 GT CDN 时，才应启用此选项。

目前，每个 locale 仅支持生成一个文件。

文件类型：gt

支持的键

  • output（必需）

示例

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

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

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

文件类型：json

支持的键

  • include（必需）
  • exclude（可选）
  • transform（可选）

示例

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

假设你的项目默认 locale 为 en，并希望将项目翻译为 fr 和 es。

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

它会忽略子目录 json_files/en/exclude/ 中的任何文件。

文件类型：yaml

支持的键

  • include（必需）
  • exclude（可选）
  • transform（可选）

示例

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

假设你的项目默认 locale 为 en，并且你希望将项目翻译成 fr 和 es。

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

它会忽略子目录 yaml_files/en/exclude/ 中的任何文件。

文件类型：mdx

支持的键

  • include（必填）
  • exclude（可选）
  • transform（可选）

示例

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

支持的键

  • include（必需）
  • exclude（可选）
  • transform（可选）

示例

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

支持的键

  • include（必需）
  • exclude（可选）
  • transform（可选）

示例

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

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

transform 键会将翻译后文件的扩展名从 .js 分别改为 .fr.js 和 .es.js。

文件类型：ts

支持的键

  • include（必需）
  • exclude（可选）
  • transform（可选）

示例

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

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

transform 键会将翻译后文件的扩展名从 .ts 分别更改为 .fr.ts 和 .es.ts。

示例配置

我们来解析一个 gt.config.json 示例文件：

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"]
    }
  }
}

在此示例中，我们通过一次调用 gtx-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 加载。

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

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

下一步

了解如何使用 init 命令 生成此配置文件。

这份指南怎么样？

TypeScript

如何使用 General Translation 自动翻译 TypeScript 与 JavaScript 文件

使用指南

GT 命令行工具使用指南

本页内容

概览
配置
Locale 别名
files
支持的文件类型
include
exclude
transform
特殊占位符
output
文件类型：gt
文件类型：json
文件类型：yaml
文件类型：mdx
文件类型：md
文件类型：js
文件类型：ts
示例配置
下一步
配置