返回

gtx-cli@2.10.0

Fernando Aviles avatarFernando Aviles
gtx-cli2.10.0metadatacontextjsonyamltranslation-quality

概述

gtx-cli 2.10.0 新增了对 JSON 和 YAML 翻译文件中键级元数据的支持。这是一种针对每个键的翻译说明，让你能够更细粒度地控制各个字符串的翻译方式。

此前，以键组织的文件的翻译上下文仅在项目级别生效。样式控制、术语表条目以及 locale 特定规则都会统一应用到所有内容上。键级元数据让你可以更进一步，将具体的翻译提示直接附加到文件中的各个键上。

形式如下

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

{
  "nav": {
    "home": "Home",
    "bank": "Bank",
    "save": "Save"
  },
  "alerts": {
    "new_lead": "You have a new lead!"
  }
}
{
  "nav": {
    "home": {
      "context": "Baseball term — home plate on a diamond. NOT a house."
    },
    "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
    }
  },
  "alerts": {
    "new_lead": {
      "context": "Sales/CRM context. A 'lead' is a potential customer.",
      "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: "Sports term — a goalkeeper's save. NOT saving data."
    draft:
      context: "Beer on tap, as in 'draft beer'. NOT a document version."
  labels:
    date:
      context: "The edible fruit of the date palm. NOT a calendar date."
    chips:
      context: "British English: hot fried potato strips (french fries). NOT crisps or microchips."