...
Make sure to choose “Version 2” in the configuration screen.
Choose the monolingual multilingual option.
...
Useful links for understanding JSON paths are:
...
Let’s start with the simple example below. Our objective is to translate all the text content:English content and then insert translation back with the respective language code.
In the example below “en” contains the source texts and “fr”, “es” and “zh” shall be populated with the French, Spanish and Chinese translations once these are done.
| Code Block |
|---|
{
"moduleen": {
"text": "This is an example",
"title": "A title to translate"
},
"optionsfr": [ "Delete element", "Add new element" ],
"welcome{
"text": "WelcomeCeci toest thisun productexemple"
}
} |
We use the configuration below. The code ..* (two dots and a star) is a JSON path and it will select each and every text in the file.
Explanation: The * means to translate any node, whatever its name and the .. means to look for these nodes in any location (level of depth) in the file.
...
And we can even make it simpler with this configuration. We put * (putting nothing has the same effect) into the path field (which selects nodes at the root level) and then choose to translate all the children of those root nodes.
...
Example 2 - Translate certain nodes only
In this example, we want to translate the “text”, “title” and “options” node but not all the other ones such as the “key”.Then we will translate the texts into French and Spanish. Note that the original file already contains one French translation, it will be read and used as a pre-translation.
When we later build the translated file we expect it to contain all the translations:
| Code Block |
|---|
{
"moduleen": {
"key": "module-228787",
"text": "This is an example",
"title": "A title to translate"
},
"optionsfr": [{
"text"Delete: element",Ceci "Addest newun elementexemple" ],
"texttitle": "WelcomeUn totitre thisà producttraduire"
},
"customer": 12121,
"customer-data"es": {
"text": "(The Spanish translation)",
"title": "internal information"(The Spanish translation)"
}
} |
Our configuration now explicitly states the node names we want to translate:
...
Example 3 - Extract meta-information with texts
Let’s look at a JSON file that contains product descriptions. With each product there is a title, a description, an identifier and some more meta-information.
Our objective is to extract texts + meta information. This can then be made visible to the translation team.
| Code Block |
|---|
[
{ "key": "product-1000", "title": "Washing machine", "description": "A great machine", "internal-info": "Seems to be our best seller!" }
{ "key": "product-1092", "title": "Coffee machine", "description": "Also a great machine", "internal-info": "Make sure to translate properly" }
] |
In our configuration we ticked the “Extract context/key” option and put another JSON path to select the “key” node. It will be extracted to the segment’s key/context field.
...
You can also pull data and save to each segment’s custom fields like this:
...
Example 4 - Handling plain text and HTML content
JSON files may contain HTML formatted content. Our file contains “text” nodes that are not html and “html” nodes that are, well, HTML.
It is important to tell the filter if there is HTML because it will protect markup in the translation editor.
| Code Block |
|---|
{
"html": "<p>Hello <strong>world</strong></p>",
"text": [ "Simple text", "Another simple text" ],
"section": { "html": "<div>Some more formatted text</div>" }
} |
We achieve this by simply defining two JSON paths. One for our plain text nodes and one for our HTML formatted nodes:
...
Example 5 - Using advanced node selectors
Check out the file below. Each product has “status” field. We only want to translate if its value is “yes”!
| Code Block |
|---|
[
{ "title": "Washing machine", "description": "A great machine", "translate": "yes" }
{ "title": "Coffee machine", "description": "Also a great machine", "translate": "no" }
] |
The JSON path now includes a condition on the parent’s object { … } The configuration to use is:
...
The JSON path is # which is replaced by the language code. Like with monolingual configurations it will be replaced by en, fr, es and other project languages you translate. The second option says that # will be substituted by the source language code and each of the target language codes.
Example 2 - Customizing language codes
The previous example was very simple. Luckily, the JSON file contained the exact language codes we are using in our Wordbee project.
Obviously, this is not always the case in the real-world!
| Code Block |
|---|
{
"English": {
"text": "This is an example",
"title": "A title to translate"
},
"French": {
"text": Ceci est un exemple"
}
} |
The configuration needs to specify how Wordbee project locales are “mapped” to the language titles in the JSON file:
...
If you tick the option below the box then any project locales that are not listed will be mapped unchanged. In our example we do not want this.
Example 3 - Translate array elements with language indicator
Check out the file below and how the language is saved in a property within array elements:
| Code Block |
|---|
[
{
"language": "en-US",
"text": "This is an example",
"description": "My description"
},
{
"language": "en-US",
"text": "This is another example",
"description": "Another description"
},
] |
If we translate this into French, we want that result:
| Code Block |
|---|
[
{
"language": "en-US",
"text": "This is an example",
"description": "My description"
},
{
"language": "en-US",
"text": "This is another example",
"description": "Another description"
},
{
"language": "fr-FR",
"text": "Ceci est un exemple",
"description": "Ma description"
},
{
"language": "fr-FR",
"text": "Un autre exemple",
"description": "Une autre description"
}
] |
The configuration will look like this:
...
Here too, # is replaced by the source or target language codes of the Wordbee project.
The JSON path selects all array elements by language. We use a condition for that: [?( … condition …)]
It checks that the product object has a “translate” property with value “yes”: @.translate language == 'yes#' . The @ character means to
...
Example 6 - Extract meta-data from any location in the file
We already discussed an example earlier on how to extract meta-information. These examples were simple in that the meta-information was on the same object level as the actual text to translate.
In the JSON below we
When the filter looks for the English content, it selects the array elements using [?(@.language == 'en-US')] . Translations are inserted back by cloning each source array elements.
Example 4 - Translate array elements with language indicator, no 2
Let’s push the envelope further. Our latest file uses custom language names instead of locales. And we only want to translate the “text” properties and attach to it the meta-information “key” and “catalog”. The “key” is one object level above “text” and the “catalog” is at the root. How do we select those fields? nothing else:
| Code Block |
|---|
{
"products": [
{
"key
"language": "1000English",
"product": { "id": 1002,
"text": "This is aan productexample",
} }, { "keynotranslate": "1000",
"product": { "text": "This is a product" }
}
],
"catalog": "Summer products"Something not to translate"
},
...
]
} |
The configuration is:
...
We use the ^ character to tell the system that the property named key is one level further up in the hierarchy relative to the translatable text.
...
now is $.products[….]. The array elements are indeed located under the products property. With JSON paths, the $ sign is the root of the document
...
To move two levels up in the hierarchy we would have typed ^^key.To simply find the first catalog property in the document whatever its level, we would have written $..catalog (two dots).
...
and writing $.products locates the product node at the root. We further instructed to only translate the “text” properties but not any of the other ones.
...
| Info |
|---|
When the system inserts back the translations, it will clone the source language node or array element for each target language. If the target objects/elements already exist fully or partially in the source file, the system will keep any existing properties and replace only those that we are translating. |
Example 4 - Arrays in arrays in arrays
All the examples up to here are simple and you may come across more advanced files.
Keep in mind that you can configure multiple JSON paths at any time. The example below translates array based content (selector #1) and object based content (selector #1).
...
It is even possible to translate multilingual content containing multilingual content - if anyone ever wants to do it!
| Code Block |
|---|
{
"products": [
{
"language": "English",
"text": "This is an example",
"features": {
"English": "English feature",
"French": "French translation",
"Spanish": "Spanish translation"
}
}
{
"language": "French",
"text": "Ceci est un exemple",
}
]
} |
Example 5 - Reading meta data
Please check out the meta-data examples we explain with monolingual files.
The mechanism and configuration options are the same.
Final word
We only touched on some of the possibilities of the JSON filter. For more advanced files check out the JSON path links printed in the top.
...