YAML language pack formats supported by the importer

YAML is a generic file format that can have any structure. This makes importing difficult, so Loco recognizes the following structures as translation mappings:

Flat

A flat structure will be imported as simple key/value pairs, for example:

hello: Hello World

This will import a single asset with ID "hello" and source text "Hello World"

Nested

Loco supports key folding for nested structures. For example:

pleasantry:
  hello: "Hello World"
  goodbye: "So long!"

This will import two assets with dot-separated IDs "pleasantry.hello" and "pleasantry.goodbye". There is no limit to the depth of this structure.

Multiple locales

Files containing multiple locales can be imported, as long as all top-level keys look like valid locale codes. For example:

en:
  greeting:
    hello: "Hello World"
fr:
  greeting:
    hello: "Bonjour tout le Monde"

This will import a single asset with ID "greeting.hello". The same key folding rules as above are applied, but the top-level locale keys will be discarded.

Note that only one language can be imported at the same time from a file like this. From the Loco dashboard importer, select the language you want to extract. Via the API, specify it with the locale parameter, e.g. ?locale=fr

Symfony

Symfony language files in the flat and nested styles will import into Loco. However, be aware that PHP-specific features (such as printf formatting) won't be automatically detected. It's recommended to import native PHP language packs, or Symfony XLIFF files.

See:

• Symfony support in Loco
• Symfony translation component

Ruby on Rails

Rails language files in the multiple locale style will import into Loco, even if they only contain one top-level locale code. See: guides.rubyonrails.org/i18n.html

Lookup keys

Your YAML file may by mapped by Asset IDs or by full source text.

By default Loco assumes object keys are Asset IDs, so if you want to map keys to your source locale you must tell Loco what to do. For example:

Hello World: "Bonjour tout le monde"

This will import an English translation and a French translation, but only if you tell Loco that the keys are English and the values are French. See General notes on importing for how to specify the locales.

Gotchas

Working with translations means you probably only care about strings, but YAML is a generic serialization format, so it supports non-string data types too. If you're constructing a YAML file manually, take care to always add quotes around keywords and reserved symbols. The following example will not produce what you expect:

answer:
  no: no
  yes: yes

The mistake here is that yes and no are boolean keywords in YAML (as are on, off, true and false). Loco parses YAML strictly according to the specification, and so although this example will import without an error, you'll end up with two assets called "answer.0" and "answer.1".

The following will produce what you expect:

answer:
  'no': 'no'
  'yes': 'yes'

Other mistakes include leaving reserved symbols in unquoted values. Generally this kind of error will result in a failed import, so if you get a parse error, try validating your YAML for values that should be quoted.