YAML
Rails-style YAML locale files: one locale root over nested maps, flattened to dotted keys.
| Format | Identifier | Extensions |
|---|---|---|
| YAML | yaml | .yml, .yaml (exports use .yml) |
The layout Rails I18n and similar libraries use: a single top-level key naming the locale, with the strings nested under it.
fr:
home:
title: "Bon retour"
greeting: "Bonjour, %{name} !"
cart:
items:
one: "%{count} article"
other: "%{count} articles"Keys
Nested map keys are joined with ., below the locale root: the file above imports home.title, home.greeting, cart.items.one and cart.items.other. On export, keys are split on . to rebuild the maps, with the same rules as JSON (nested): a project where one key is a prefix of another (home and home.title) cannot be exported as YAML, and two paths that flatten to the same key are an import error.
What the file must contain
- Exactly one root key, the locale. A different root key than the locale you are importing is accepted with a warning; both
pt-BRandpt_BRmatchpt_BR. An empty root (fr:with nothing under it) is a valid empty file. - Maps and strings only. Every leaf must be a string. A sequence (a YAML list, such as Rails'
day_names) is an error, and so is an unquoted number or boolean (count: 5,enabled: true): quote such values if they are text. - Comments, either quote style, multi-line strings and anchors are all accepted. Alias expansion is bounded, so a file built to expand without limit is rejected.
Plurals
YAML has no plural construct of its own. Rails-style plurals (items.one, items.other) are ordinary nested keys to transglot, each translated as its own string. Add the categories a target language needs (few, many) as keys of their own. Plural keys you create in transglot are left out of a YAML export.
Placeholders
%{name} (Rails), {name} and %s are kept exactly as written. See Placeholders.
Export
Exports are written so that they load the same way in every YAML parser:
- The root key is the locale in hyphenated form (
pt-BR,zh-CN), which is how Rails names locales. - Two-space indentation.
- Every value is double-quoted, with
\n,\t,\r,\"and\\escapes, so multi-line text never folds. - A key is written bare only when it is a plain identifier that no YAML parser would read as something else; keys such as
no,on,trueor digits are double-quoted.
Comments and anchors from the file you imported are not kept.