以语言区域为根节点的 YAML
翻译单个语言区域根节点下的值,并将该根节点重命名为目标语言。
Rails 从 YAML 文件的根节点读取语言区域。即使文件名为 checkout.es.yml,只要根节点是 en:,文件定义的仍是英语资源。yaml-root-key 处理器会翻译该根节点下的消息,并将根节点改为目标语言区域,让各语言的查找路径保持一致。
语言区域包装层与消息路径 #
源消息目录可以同时包含插值和复数分支:
en:
checkout:
greeting: Hello, %{name}
items:
one: One item
other: "%{count} items"消息路径为 checkout.greeting、checkout.items.one 和 checkout.items.other。这些路径不包含 en,因此英语源文件和西班牙语目标文件可以匹配相同的消息标识。目标包装层变为 es;checkout、one 和 other 仍保留为键。
插值语法和复数类别名称是应用约定的一部分。翻译文本并不会配置 Rails 的复数规则,也不会补齐目标语言所需的所有类别。接受这些资源前,请在应用中使用相关数量和变量进行渲染验证。
解析器要求根节点只有一个键值对,其中键必须是标量,值必须是映射。语言区域的内容可以为空,但不允许在根节点下直接放置标量消息或列表。请将包含多个语言区域的 YAML 文件按语言区域拆分为独立文件;如果希望保留所有根节点不变,请使用 通用 YAML。不要使用此处理器处理 OpenAPI 规范。
更新与局部范围 #
嵌套字符串值按语言区域包装层下的路径进行比较。当前源文件提供结构,先前的源文件和现有目标文件则用于沿用未更改的值。注释和锚点会经过 YAML 树序列化处理,格式可能因此被规范化。
只要提供了先前的源文件,即使处理范围限定为特定键或术语,也仍可复用未更改的译文。CLI 的 --key 使用已保存的基准,添加 --force 也不会禁用这种复用。若要精确修正措辞,请直接编辑目标文件。若要在修改指导要求后重新生成文件,请先保存已接受的目标文件,再使用限定范围的整文件 --force,不带 --key,然后检查每条发生变化的消息。
按键限定范围时,范围外尚未解析的映射字符串可能会被省略。序列元素会保留源值,不会发生位置偏移。解析成功并不代表内容完整,请另行检查完整性,尤其是在仅处理较小范围来创建新语言区域时。
配置语言区域与目标位置 #
对于 .yml 或 .yaml 源文件,请显式设置 format: "yaml-root-key"。仅凭文件扩展名无法识别语言区域包装层。CLI 配置和 GitHub 文档介绍了文件匹配模式和目标文件布局。
重建时必须提供目标语言区域,否则会失败。CLI 的 localeFormat 只更改路径中的名称,不会更改 YAML 内写入的语言区域。请检查目标位置及其根节点,然后通过 Rails 加载一条问候消息和一条复数消息。本地化 Rails 应用介绍了如何将这些文件与请求中的语言区域选择、辅助方法和回退行为衔接起来。