博客Dashboard

配置

gt.config.json 文件配置文档

概览

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

CLI（命令行界面）设置向导 npx gtx-cli init 会在你的项目中自动创建一个 gt.config.json 文件。

配置

gt.config.json 文件可接受以下属性（不限于此）：

  • defaultLocale: 项目的默认 locale。源内容以该 locale 编写。若使用 gt-next 或 gt-react，它也将作为项目的 fallback locale。

  • locales: 项目的 locale 数组，即你希望将项目翻译成的目标 locale。更多信息参见 supported 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 模式组成的数组，用于匹配你要翻译的文件。

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

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

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

exclude

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

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

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

如果你想在所有 locales 中排除某些 files 不参与翻译，可以使用 [locales] 占位符替代 [locale]。

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

transform

transform 可以是字符串或对象。

如果 transform 是字符串，则用于重映射文件名。它应包含通配符 *，该通配符会被原始文件名（第一个 . 之前的所有内容）替换。

例如，如果你希望所有翻译后的文件扩展名使用 .[locale].json 而非 .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 的任何其他属性也可作为占位符使用，并具备相同的、取决于上下文的行为。

This is useful if your docs or i18n framework requires a specific file extension for translated files instead of subdirectory-based locale routing.

output

此键仅用于 General Translation 的文件，专门用于在本地保存翻译。如果你使用的是 GT CDN（内容分发网络，Content Delivery Network），则不需要此键。

该 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
配置示例
下一步