翻译注释

单看一段文本，往往会有歧义。"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），那就没有额外价值——可以省略。

注释与引擎配置#

翻译注释是针对单条文本的，直接写在源文件里。至于适用于整个 locale 的规则——例如术语、语气、品牌表达——更适合直接配置在 engine 中，这样无需在每个键上单独添加注释，也能全局生效。