概述

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

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

结构如下

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

{
  "nav": {
    "home": "Home",
    "bank": "Bank",
    "save": "Save"
  },
  "alerts": {
    "new_lead": "You have a new lead!"
  }
}

{
  "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 时，CLI 会自动读取该文件。

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

支持的字段

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

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

这些字段对每个键都是可选的。有关每个字段的完整说明和示例，请参阅键级元数据参考。

YAML 支持

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

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