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 应用,并使用语言区域根节点处理器。