# 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)，即可自动检测你的框架、安装依赖项、创建配置文件，并在需要时生成凭据。

```bash
npx gt init
```

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

### 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]` 占位符来定位源文件并保存翻译后的文件。[`.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]

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

## Sitemap

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