翻译备注

单看一个字符串，往往容易产生歧义。比如 "Records"，可能指病历、唱片，也可能是数据库记录。在 JSONC 源文件中，键上方的注释会作为上下文传递给引擎，帮助它判断并翻译出正确含义：

{
  // Medical context: patient medical records
  "records": "Records"
}

注释不会出现在输出结果中——它的作用只是为翻译提供引导。

备注在哪些地方生效#

翻译备注会从 JSONC（.jsonc）源文件中读取。只需将一个 files[] 条目指向该文件：

{ "pattern": "content/en/app.jsonc" }

JSON（.json）本身不支持注释，因此无法承载备注信息。如果你需要添加备注，请将该文件改用 JSONC。

如果你是从旧版 CLI 迁移过来的：它也支持从 Xcode String Catalog（.xcstrings）中读取备注。但当前 CLI 已不再支持这种格式，因此现在为内容附加上下文的方式就是使用 JSONC 注释。

如何写出有用的备注#

好的备注，应该补充字符串本身没有提供的上下文：

{
  // Button in the checkout flow — keep it short
  "checkout.pay": "Pay now",

  // "Set" here means a collection, not the verb
  "library.set": "Set",

  // Formal tone — shown in the legal footer
  "footer.terms": "Terms of Service"
}

如果备注只是重复字符串本身的内容（// This says Welcome），那就没有提供任何额外信息——可以直接省略。

备注与引擎配置#

翻译备注是逐条字符串添加、直接写在源文件中的。对于适用于整个语言环境的规则——例如术语、语气、品牌调性——更适合直接配置在 engine 中，这样无需在每个键上都添加备注，也能全局生效。