Locale-root YAML
Translate the values below one locale root and rename that root for the target language.
Rails reads the locale from a YAML file's root. A file named checkout.es.yml still defines English resources if its root is en:. The yaml-root-key handler translates the messages below that root and changes the root to the target locale, keeping lookup paths consistent across languages.
The locale wrapper and message paths #
A source catalog can contain both interpolation and plural branches:
en:
checkout:
greeting: Hello, %{name}
items:
one: One item
other: "%{count} items"The message paths are checkout.greeting, checkout.items.one, and checkout.items.other. They exclude en, so the English source and Spanish target can match the same message identities. The target wrapper becomes es; checkout, one, and other remain keys.
Interpolation syntax and plural category names are part of the application's contract. Translating the words does not configure Rails plural rules or add every category required by the target language. Render the relevant quantities and variables in the application before accepting the resources.
The parser requires a single root pair with a scalar key and a mapping below it. An empty locale is allowed, but a scalar message or a list directly under the root is rejected. Split a multi-locale YAML file into per-locale files, or use generic YAML when you intend to retain all roots unchanged. Do not select this handler for an OpenAPI specification.
Updates and partial scope #
Nested string values are compared by paths below the locale wrapper. The current source supplies structure; the previous source and existing target allow unchanged values to carry forward. Comments and anchors pass through YAML tree serialization, which can normalize formatting.
Key or term scope can still reuse unchanged translations when a previous source is supplied. The CLI's --key uses its saved baseline, and adding --force does not override that reuse. Edit the target directly for an exact wording correction. To regenerate the file after changing guidance, save accepted targets and use a scoped whole-file --force without --key, then inspect every changed message.
When key scope is used, unresolved out-of-scope mapping strings can be omitted. Sequence elements keep source values rather than shift positions. Inspect completeness separately from successful parsing, particularly when building a new locale from a narrow scope.
Configure the locale and destination #
Set format: "yaml-root-key" explicitly for .yml or .yaml sources. The extension cannot identify the locale wrapper. CLI configuration and GitHub cover file patterns and target layouts.
Reconstruction requires a target locale and fails if it is absent. The CLI's localeFormat changes path spelling, not the locale written inside the YAML. Inspect both the destination and its root, then load a greeting and plural message through Rails. Localize a Rails app connects these files to request locale selection, helpers, and fallback behavior.