Skip to main content
Version: 3.x.x

Structured YAML

Structured YAML format is a generic format enabling you to export translations to YAML files with array support. When exporting in this format, you can choose from various placeholder & message formats listed below.

Read more about message & placeholder formats here.

In general, we recommend against using structured YAML because it can lead to unexpected behavior, as explained below. You may consider using Flat YAML instead.

Example of structured YAML​

en.yaml
user:
  settings:
    password:
      save:
        button: "Save"

When importing such YAML, the nested elements are converted into flat keys. So, the example above will be imported the same way as this one:

"user.settings.password.save.button": "Save"

Support for arrays​

In some cases, you might want to use arrays in your YAML. This is useful when you want to have a list of items, for example.

items:
  - "First item"
  - "Second item"
  - "Third item"

When importing such YAML, the array will be converted into flat keys with index suffixes. So, the example above will be imported the same way as this one:

"items[0]": "First item"
"items[1]": "Second item"
"items[2]": "Third item"

Key naming issues when using structured YAML (import)​

Imagine this structured YAML to be imported to Tolgee:

user:
  password: "Password"
"user.password": "Set your password"

Both keys are translated into the same key, user.password. In this case, Tolgee will only import the first key and ignore the second one while a warning is displayed.

A very similar situation can happen when using arrays:

user:
  - "Password"
"user[0]": "Set your password"

Again, the same key user[0] is translated into two different values. In this case, Tolgee will only import the first one. So the value for user[0] will be Password.

Key naming issues when using structured YAML (export)​

Very similar issues can happen when exporting structured YAML. Imagine these keys stored in the Tolgee platform:

"user.password": "Password"
"user": "User"

Tolgee cannot export this to structured YAML because the key user is used once as a key for the string value user, and onceas a key for the nested object.

user:
  password: "Password"
user: "User"

In such cases, Tolgee joins the last two path elements of the key. So the export will look like this:

"user.password": "Password"
"user": "User"

While this works perfectly fine for Tolgee JS SKDs, it might be an issue for other tools.

For arrays, this issue is handled differently. When the required array index is already occupied, Tolgee will try to use another one.

Let’s say you have these keys stored in Tolgee:

"item[0]": "Text"
"item[0].hey": "Text"

Such results will be exported like this when array support is enabled:

item:
  - "Text"
  - hey: "Text"

Exporting via REST API

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

{
  "format": "YAML",
  "supportArrays": "true",
  "structureDelimiter": "."
}

Example with CURL:

curl "https://app.tolgee.io/v2/projects/export?\
format=YAML\
&structureDelimiter=.\
&supportArrays=true" -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.