# gt: General Translation CLI tool: 配置 CLI
URL: https://generaltranslation.com/zh/docs/cli/guides/configuring.mdx
---

title: 配置 CLI
description: "如何设置 General Translation 的 gt.config.json：本指南将介绍如何配置区域设置、文件和存储选项。"
related:
  links:
    - /docs/cli/guides/generating-translations
    - /docs/cli/guides/managing-translations
    - /docs/cli/guides/using-auto-jsx
    - /docs/cli/guides/branching

---

CLI 会读取项目根目录中的 `gt.config.json` 文件，以确定要翻译的内容以及结果保存的位置。本指南将介绍如何创建和编辑该文件。

*注意：本指南介绍的是常见的配置选项。要查看所有可用字段，请参阅[配置参考](/docs/cli/reference/config)。*

## 创建配置文件 [#create]

你可以通过三种方式创建 `gt.config.json`。选择最适合你工作流程的一种。

### a) 运行完整的设置向导

运行 [`gt init`](/docs/cli/reference/commands/init)，即可自动检测你的框架、安装依赖、创建配置文件，并一次性生成凭据。

```bash
npx gt init
```

### b) 仅创建配置文件

运行 [`gt configure`](/docs/cli/reference/commands/configure)，即可创建 `gt.config.json`，无需安装依赖项或修改框架配置。

```bash
npx gt configure
```

### c) 手动编写

自行创建该文件，并添加 `$schema` 引用，以便编辑器进行校验和自动补全。

```json title="gt.config.json"
{
  "$schema": "https://assets.gtx.dev/config-schema.json",
  "defaultLocale": "en",
  "locales": ["fr", "es"]
}
```

## 设置 locales [#locales]

将 `defaultLocale` 设置为源内容所使用的语言，并在 `locales` 中列出目标语言。

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

两者均使用标准的区域设置代码，例如 `en`、`en-US` 或 `zh`。完整列表请参阅[支持的区域设置](/docs/platform/dashboard/reference/supported-locales)。

如果要为某个区域设置使用自定义别名——例如用 `cn` 替代 `zh`——请添加一个指向官方代码的 `customMapping` 条目。

```json title="gt.config.json"
{
  "customMapping": {
    "cn": { "code": "zh" }
  }
}
```

## 选择要翻译的文件 [#files]

添加一个 `files` 对象，为你要翻译的每种文件类型设置一个键。每种类型都接受一个 `include` 数组，其中包含 glob 模式，使用 `[locale]` 占位符来定位源文件并保存翻译后的文件。

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "json": {
      "include": ["locales/[locale]/**/*.json"]
    },
    "mdx": {
      "include": ["content/docs/[locale]/**/*.mdx"]
    }
  }
}
```

CLI 在搜索源文件时会将 `[locale]` 替换为 `defaultLocale`，保存翻译时则会将其替换为各个目标代码。有关各类型的选项，请参阅 [File formats](/docs/cli/reference/formats/gt-jsx-files)；有关高级匹配，请参阅 [`include`](/docs/cli/reference/config#files)。

## 选择翻译的存储位置 [#storage]

如果你使用 `gt-next`、`gt-react` 或 `gt-react-native`，请先决定如何提供翻译。

* **保存到本地**，将翻译打包到应用中。添加一个 `gt` 条目，并将 `output` 路径设置为包含 `[locale]`。
* **发布到 CDN**，以便在 Runtime 加载翻译，而不是将其打包进应用。将 `publish` 设置为 `true`。

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

参见 [CDN 发布](/docs/cli/reference/config#cdn-publishing)，了解如何在全局、按文件或按命令控制发布。

## 添加凭据 [#credentials]

[`translate`](/docs/cli/reference/commands/translate) 命令需要生产环境 API Key 和项目 ID。请不要把它们写入 `gt.config.json`，而是改为设置成环境变量。

```bash title=".env"
GT_API_KEY=your-api-key
GT_PROJECT_ID=your-project-id
```

运行 [`gt auth`](/docs/cli/reference/commands/auth)，即可生成这些凭据并自动写入 `.env.local`。
## Next steps

- /docs/cli/guides/generating-translations
- /docs/cli/guides/managing-translations
- /docs/cli/guides/using-auto-jsx
- /docs/cli/guides/branching