This page is a tutorial for configuring multilingual JSON files.

Prerequisites

This tutorial uses JSON configurations with:

• Make sure to choose “Version 2” in the configuration screen.

• Choose the multilingual option.

Useful links for understanding JSON paths are:

• https://support.smartbear.com/alertsite/docs/monitors/api/endpoint/jsonpath.html (An introduction)

• https://jsonpath.com/ (A tool to try out JSON paths with your documents)

Example 1 - Translate all content

Let’s start with the simple example below. Our objective is to translate the 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.

{
	"en": {
		"text": "This is an example",
		"title": "A title to translate"
	},
	"fr": {
		"text": Ceci est un exemple"
	}
}

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:

{
	"en": {
		"text": "This is an example",
		"title": "A title to translate"
	},
	"fr": {
		"text": "Ceci est un exemple",
		"title": "Un titre à traduire"
	},
	"es": {
		"text": "(The Spanish translation)",
		"title": "(The Spanish translation)"
	}
}

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!

{
	"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:

[
  {
    "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:

[
  {
    "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”: @.language == '#' .

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 nothing else:

{
  "products": [
    {
      "language": "English",
      "id": 1002,
      "text": "This is an example",
      "notranslate": "Something not to translate"
    },
    ...
  ]
}

The configuration now is $.products[….]. The array elements are indeed located under the products property. With JSON paths, the $ sign is the root of the document 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.

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!

{
  "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.