Skip to main content
Version: 3.x.x

Flat YAML

Flat YAML is a simple key-value YAML. When exporting in this format, you can choose from various placeholder & message formats listed below.

Read more about message & placeholder formats here.

Example​

This is an example of .yaml file.

en.yaml
"user-settings.password.save.button": "Save"
"interpolated_key": "Hello, {name}!"
"plural_key": "You have {count, plural, one {one message} other {# messages}}."

Flat YAML doesn't support nesting or array support. We recommend using flat YAML in favor of Structured YAML because there is no space for confusion as with structured YAML. If you need support for nesting or arrays, go ahead with structured YAML.

Format specification​

In flat YAML format, we store data as a flat YAML object, so the keys are not nested and all the keys are on the first level of the root YAML object.

The keys in the YAML are localization keys, e.g. user-settings.password.save.button, and the values are the translated strings, e.g., Save, as you can see in the example. Keys, including dots or array indexes, are not converted to nested objects.

The message format and placeholder conversion​

When importing data to Tolgee from the Flat YAML files, you can either enable or disable the conversion to the Tolgee Universal ICU placeholders. The conversion is enabled by default. You can also disable the conversion globally in the project settings. We recommend keeping the conversion enabled, as it brings many benefits. Read more about the benefits of Tolgee Universal ICU placeholders.

When the conversion is disabled, the original placeholders (e.g., %s, %d). are preserved. The message format is automatically detected when importing data in Flat YAML format. When exporting, you can choose from message & placeholder formats listed above.

Exporting via REST API​

To export to Tolgee Native YAML via REST API, you have to set the following parameters:

{
  "format": "YAML",
  "supportArrays": "false",
  "structureDelimiter": ""
}

Example with CURL:

curl "https://app.tolgee.io/v2/projects/export?\
format=YAML\
&structureDelimiter=\
&supportArrays=false" -H "X-API-Key: <Your Project API key>" --output data.zip

Importing / Exporting in general​

To read more about importing and exporting with Tolgee, continue to import section or export section.