# gt: General Translation CLI tool: 配置 CLI
URL: https://generaltranslation.com/zh/docs/cli/guides/configuring.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 如何使用区域设置、文件和存储选项设置 General Translation 的 gt.config.json。

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

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

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

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

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

运行 [`gt init`](/docs/cli/reference/commands/init)，即可自动检测你的框架、配置相关文件，并可按需预配项目和开发环境运行时密钥。如果某个步骤需要登录，向导会自动引导你完成登录。你可以传入[选项](/docs/cli/reference/commands/init#flags)来预先回答向导的问题，也可以以无界面 (headless) 模式运行。

```bash
npx gt init
```

在 monorepo 中，请从要本地化的应用目录运行该命令，而不是从 workspace 根目录运行。对于 Vite React 应用，向导会安装 `gt-react`，在现有应用入口之前配置 [`initializeGTSPA`](/docs/react/reference/config#initialize-spa)，并设置从本地或 CDN 加载翻译。

### b) 跳过 React 设置步骤进行配置

运行 [`gt configure`](/docs/cli/reference/commands/configure) 即可创建或更新 `gt.config.json`，且不会执行实验性的 React 框架代码改写。除此之外，它与完整向导的其余设置流程相同：可以生成加载器、安装 CLI、提示登录，并预配开发凭据。

```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` 条目。之后，凡是在 `defaultLocale` 或 `locales` 中选用该区域设置的地方，都应使用该别名。

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["cn", "fr"],
  "customMapping": {
    "cn": { "code": "zh" }
  }
}
```

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

添加一个 `files` 对象，为你要翻译的每种文件类型设置一个键。大多数类型都接受一个 `include` 数组，其中包含 glob 模式，使用 `[locale]` 占位符来定位源文件并保存翻译后的文件。[`.xcstrings` 翻译目录](/docs/cli/reference/formats/xcstrings-files)是个例外，因为所有区域设置都存储在同一个文件中并原地更新。

```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]

### a) 登录以进行本地 CLI 操作

1. 运行 [`gt login`](/docs/cli/reference/commands/login)，并在浏览器中批准访问。使用 [`gt whoami`](/docs/cli/reference/commands/whoami) 查看当前账户，使用 [`gt logout`](/docs/cli/reference/commands/logout) 退出登录。
2. 在现有的 `gt.config.json` 中通过 [`projectId`](/docs/cli/reference/config#project-id) 将应用绑定到项目，或设置 `GT_PROJECT_ID`。仅登录并不会选择或创建项目。如果希望通过引导流程选择或创建项目，而非手动绑定，请使用 [`gt init`](/docs/cli/reference/commands/init)。
3. 运行 [`gt translate`](/docs/cli/reference/commands/translate)。你的账户必须具备执行每项所请求操作的 Permission。

SDK 不会读取已保存的 CLI 登录信息，请另行配置运行时凭据。

### b) 在 CI 中使用显式密钥

提交你的配置文件，并通过 CI 提供商的密钥设置提供 `GT_API_KEY`。在配置文件或环境变量中设置项目 ID。登录 (包括使用 `--no-browser` 登录) 需要人工批准。只有当所有问题都已通过选项给出答案且无需登录时，无界面模式下的 [`gt init`](/docs/cli/reference/commands/init) 才能无人值守地运行。

```bash
GT_API_KEY=your-api-key
GT_PROJECT_ID=your-project-id
```

创建一个[自定义项目密钥](/docs/platform/dashboard/reference/api-keys#create-project-keys)，或使用 [`gt api-key create`](/docs/cli/reference/commands/api-key-create) 并显式指定 Permission。需授予覆盖整个工作流的 Permission：文件读取/下载、文件写入/上传、将翻译任务加入队列，以及上下文访问 Permission (如需使用上下文) 。仅具备生成 Permission 的运行时密钥无法满足翻译流水线的需求。切勿将 API Key 存储在 `gt.config.json` 中，常规的 CLI 设置校验会拒绝此类配置。

### 凭据优先级与环境文件

托管命令优先使用 `--api-key`，其次是非空的 `GT_API_KEY`；仅在未显式提供工具密钥时，才会使用已保存的登录信息。显式密钥无效或权限不足时，绝不会回退到登录信息。`GT_DEV_API_KEY` 及其带公开前缀的变体属于运行时设置，而非 CLI 管理凭据。如需使用登录信息，请同时从进程环境和已加载的 env 文件中移除不需要的工具密钥，登录操作不会自动清除它们。

启动时，可执行文件会先加载 `.env`，再以覆盖模式依次加载 `.env.local` 和 `.env.production`。后两个文件可以替换已导出的密钥。有关项目绑定和冲突检查，请参阅 [`projectId`](/docs/cli/reference/config#project-id)。

### 开发环境运行时密钥

[`gt init`](/docs/cli/reference/commands/init) 可以在已被 Git 忽略的 `.env.local` 中预配一个仅具有 `project:translations:generate` 权限的密钥，并使用你所用框架的变量名。它不会替换 `GT_API_KEY`。 (有关运行时配置，请参阅 [Next.js 凭据](/docs/react/nextjs/config#credentials)。) 

<Callout type="warn">
  切勿将 API Key 打包进已部署的浏览器端或移动端 bundle 中，即使是仅具有生成权限的密钥也不行。 (请参阅 [init 文件保护](/docs/cli/reference/commands/init#notes)。) 
</Callout>

## Next steps

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

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.