YAML

翻译 YAML 中嵌套的字符串值,保留消息目录的键不变;如果根节点或模式有特殊含义,请选择其他处理器。

yaml 文件处理器会翻译嵌套映射和序列中的字符串值,同时保留应用代码用于查找的键,以及数字和布尔值。适合用于结构在各语言区域间保持一致的消息目录。

判断通用 YAML 是否适合你的需求 #

例如,下面的消息目录将结账消息分组,但没有语言区域包装层:

yaml
checkout:
  title: Complete your order
  steps:
    - Review your items
    - Confirm delivery
  retries: 3

处理器会选中 checkout.title 和序列中的两个字符串。retries 仍保留为数值。带引号的标识符也会被选中,因为它属于字符串。决定将哪些数据放入消息目录时,请留意这一区别。

如果 Rails 风格的 en: 包装层需要改为目标语言区域,请使用 语言区域根节点 YAML。通用 YAML 会保留 en:,即使文件名已改为 es.yml。这可能导致 Rails 忽略这些内容,因为根节点仍标识为英语。

处理 API 规范时,请使用 OpenAPI。通用 YAML 还会选中字符串类型的操作标识符、引用和示例。仅凭 .yml 扩展名无法区分这些用途。

复用与重建 #

当前源文件决定输出树的结构。上一版源文件用于判断各字符串路径是否发生变化,现有目标文件则提供匹配路径上的值。新译文会替换已更改的字符串;未更改的字符串可以保留现有译文,即使它们已被按键或术语限定的范围选中。

CLI 会为 --key 提供已保存的基准版本,因此这种选择方式无法可靠地重新生成未更改的 YAML 文本。在同一命令中添加 --force 也不会改变这一行为。如需精确修正,请直接编辑目标文件;如需重新生成,请先保存已认可的目标文件,再使用限定范围的整文件 --force,且不带 --key。替换后,请审核整个文件。

重建时会使用 YAML 语法树,在替换值的同时保留注释和锚点结构。序列化可能会规范化格式。注释仍是文档内容,而不是给翻译器的指令。请在实际读取 YAML 的应用中检查别名,尤其是同一个值通过多处引用出现的情况。

按键限定范围的运行中,如果没有对应的目标值,范围外尚未解析的映射字符串可能会被丢弃。序列中的字符串会保留源值,以免位置发生偏移。因此,仅处理部分范围并不意味着文件中的所有字符串都已翻译。

配置并加载消息目录 #

对于 .yaml 或 .yml 源文件,请在 CLI 配置中显式设置 format: "yaml"。推送时,文件发现机制会排除未显式指定格式的 YAML 文件。GitHub App 使用独立的仓库选择机制。

请确保目标路径与应用的加载器相匹配。config/locales/checkout.en.yml 这样的源文件与位于 locales/en/checkout.yml 的源文件需要采用不同的路径推导方式。序列位置也用于标识消息:移动序列项可能会改变与之匹配的现有译文。调整结构后,请检查加载后的消息目录。有关 Rails 查找、语言区域选择和回退,请参阅 本地化 Rails 应用,并使用语言区域根节点处理器。