# gt: General Translation CLI tool: JSON
URL: https://generaltranslation.com/zh/docs/cli/reference/formats/json-files.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 使用 General Translation CLI 翻译 JSON 文件。JSON 文件格式的 API 参考。

无论你使用哪种 i18n 库，CLI 都可以翻译 JSON 文件。翻译结果会保留原始字符串语法。

*注意：CLI 会读取 `package.json` 来决定如何处理 JSON 字符串。`next-intl` 使用 ICU 消息；如果安装了 `i18next-icu`，`i18next` 也会使用 ICU 消息。仅使用 `i18next` 时，会保留 i18next 语法，例如 `{{name}}` 插值。对于其他库，字符串会按普通字符串翻译，因此包含自定义语法的字符串翻译准确性可能会稍低。*

## 配置 [#config]

在 `files` 下添加一个 `json` 条目，并在 `include` 数组中填入 glob 模式。使用 `[locale]` 占位符，这样 CLI 就能找到源文件，并将翻译保存到正确的路径。

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["zh", "es", "ja"],
  "files": {
    "json": {
      "include": ["i18n/[locale]/*.json"],
      "exclude": ["i18n/[locale]/exclude/**/*.json"]
    }
  }
}
```

使用此配置后，CLI 会翻译 `i18n/en/` 下的每个 JSON 文件，将结果保存到 `i18n/zh/`、`i18n/es/` 和 `i18n/ja/`，并跳过 `i18n/en/exclude/` 下的文件。有关所有文件键，请参阅[配置参考](/docs/cli/reference/config#files)。

## 输出顺序 [#order]

CLI 不会对翻译后的 JSON 文件中的键进行排序。通过 [`files.gt`](/docs/cli/reference/config#files) 配置的 GTJSON 翻译文件仍会按键排序，以确保差异稳定。

<Callout type="info">
  **v2.26.0 变更：**&#x7FFB;译后的 JSON 文件不再按字母顺序排序，GTJSON 输出仍保持排序。
</Callout>

## 键级元数据 [#metadata]

使用与源结构对应的配套 `.metadata.json` 文件，为每个键添加翻译说明。你可以用它为特定键补充上下文、字符限制或源代码上下文，而无需修改原文。

```json title="translations.metadata.json"
{
  "nav": {
    "bank": {
      "context": "Riverbank — the side of a river. NOT a financial institution."
    },
    "save": {
      "context": "Sports term — a goalkeeper preventing a goal. NOT saving data.",
      "maxChars": 12
    }
  }
}
```

有关所有受支持的字段，请参阅 [键级元数据 参考](/docs/cli/reference/keyed-metadata)。

## Sitemap

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