Structured JSON
Structured JSON format is a generic format enabling you to export translations to JSON 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 JSON because it can lead to unexpected behavior, as explained below.
Example of structured JSON:
{
"user": {
"settings": {
"password": {
"save": {
"button": "Save"
}
}
}
}
}
When importing such JSON, 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"
}
The message format and placeholder conversion
When importing data to Tolgee from the Structured JSON 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 Structured JSON format. When exporting, you can choose from message & placeholder formats listed above.
Support for arrays
In some cases, you might want to use arrays in your JSON. This is useful when you want to have a list of items, for example.
{
"items": [
"First item",
"Second item",
"Third item"
]
}
When importing such JSON, 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 JSON (import)
Imagine this structured JSON 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 JSON (export)
Very similar issues can happen when exporting structured JSON. Imagine these keys stored in the Tolgee platform:
{
"user.password": "Password",
"user": "User"
}
Tolgee cannot export this to structured JSON because the key user is used once as a key for the string value user, and once
as a key for the nested object.
{
"user": { // <--- This is a problem
"password": "Password"
},
"user": "User" // <--- This is a problem
}
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 JSON via REST API, you have to set the following parameters:
{
"format": "JSON",
"supportArrays": "true",
"structureDelimiter": "."
}
Example with CURL:
curl "https://app.tolgee.io/v2/projects/export?\
format=JSON\
&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.