# General Translation Changelog: gtx-cli 2.10.0: 针对每个键的翻译说明
URL: https://generaltranslation.com/zh/blog/gtx-cli_v2_10_0.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 
Authors: Fernando Aviles
Published: 2026-03-12

## 概述

**gtx-cli 2.10.0** 新增了对 JSON 和 YAML 翻译文件中**键级元数据**的支持。这类元数据是针对每个键的翻译说明，可让你精细控制单个字符串的翻译方式。

此前，键控文件的翻译上下文是在项目级别生效的。风格控制、术语表条目和特定区域设置规则都会统一应用到所有内容上。键级元数据让你能够更进一步，直接为文件中的各个键附加具体的翻译提示。

***

## 结构如下

你需要创建一个与源文件配套的元数据文件，并将其放在源文件旁边，使其键结构与源文件保持一致。在叶子节点层级，你提供的不再是字符串，而是包含翻译说明的元数据对象：

```json title="translations.json"
{
  "nav": {
    "home": "Home",
    "bank": "Bank",
    "save": "Save"
  },
  "alerts": {
    "new_lead": "You have a new lead!"
  }
}
```

```json title="translations.metadata.json"
{
  "nav": {
    "home": {
      "context": "棒球术语——内野菱形场地的本垒板。不是房屋。"
    },
    "bank": {
      "context": "河岸——河流的岸边。不是金融机构。"
    },
    "save": {
      "context": "体育术语——守门员扑救进球。不是保存数据。",
      "maxChars": 12
    }
  },
  "alerts": {
    "new_lead": {
      "context": "销售/CRM 场景。'lead' 指潜在客户。",
      "maxChars": 30
    }
  }
}
```

配套文件必须与源文件位于同一目录中，并遵循命名约定 `{name}.metadata.json` (YAML 文件则为 `.metadata.yaml`) 。运行 [`npx gt translate`](/docs/cli/reference/commands/translate) 时，CLI 会自动读取该文件。

借助按键级别的上下文，"Bank" 会被翻译为 "Ribera" (河岸) ，而不是可能的 "Banco" (金融机构) ；"Save" 会变成 "Parada" (守门员的扑救) ，而不是 "Guardar" (存储) 。对于本身已经没有歧义的字符串，你完全不需要提供元数据——只需为那些确实能从中受益的键添加条目即可。

***

## 支持的字段

我们目前支持三个元数据字段：

* **`context`** — 针对特定字符串的翻译说明。这是影响最大的字段：可用来消除歧义、指定领域术语，或澄清意图。
* **`maxChars`** — 翻译结果的最大字符数限制。这是尽力而为的：引擎会使用更短的近义表达和更简洁的措辞来适配，但不会将翻译生硬地截断到不切实际的长度。
* **`sourceCode`** — 字符串周围的源代码上下文。你可以用它向引擎展示该字符串在代码库中的使用位置和方式，从而帮助它在语气、术语和措辞上做出更合适的判断。

这些字段对每个键都是可选的。有关每个字段的完整说明和示例，请参阅[键级元数据参考](/docs/cli/reference/keyed-metadata)。

***

## YAML 支持

同样的方法也适用于 YAML 文件。创建一个键结构相同的 `.metadata.yaml` 配套文件：

```yaml title="translations.metadata.yaml"
ui:
  buttons:
    save:
      context: "体育术语——守门员的扑救。不是保存数据。"
    draft:
      context: "生啤，即扎啤/桶装啤酒。不是文档版本。"
  labels:
    date:
      context: "椰枣树的可食用果实。不是日历日期。"
    chips:
      context: "英式英语：热炸薯条（相当于美式英语的 french fries）。不是薯片或微芯片。"
```

## Sitemap

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