These pages describe how to translate JSON files with the new version 2 of the JSON filter.

Access your filter configurations

Login a manager or administrator and click the Settings top navigation link. Then click JSON files to view all your existing configurations and add new ones.

Each filter configuration tells the system the JSON properties to translate, any texts to entirely exclude from translation (e.g. numbers only), whether content is raw text or HTML formatted, and many other parameters. The most important configuration section is in the top:

Choose version 2

This tutorial is for version 2. Therefore, make sure the configurations shows “Version 2” in the top right. If not, click the link just below to convert it.

Version 2 is substantially more powerful than version 1 and we strongly recommend using it.

Choose monolingual or multilingual

In a monolingual workflow, the JSON contains texts in the source language and the translated JSON will contain all the texts in a given target language. In a multilingual workflow, the translated JSON will contain both the source texts and all the translated texts in one single file.

Specify translatable content with JSON paths

Now it gets interesting And this section is what this tutorial really is about. We introduce “JSON path” which is the standard mechanism to select content in JSON files and, in our case, the content we want to translate. Often JSON files contain content to translate and other content that must not be translated. JSON paths will make this choice simple.

Useful links 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)

Translating monolingual JSON files

Example 1 - Translate all content

Let’s start with the simple example below. Our objective is to translate all the text content:

{
	"module": {
		"text": "This is an example",
		"title": "A title to translate"
	},
	"options": [ "Delete element", "Add new element" ],
	"welcome": "Welcome to this product"
}

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.

In both cases we extract these texts:

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”.

{
	"module": {
	    "key": "module-228787",
		"text": "This is an example",
		"title": "A title to translate"
	},
	"options": [ "Delete element", "Add new element" ],
	"text": "Welcome to this product",
	"customer": 12121,
	"customer-data": "internal information"
}

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.

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

{
	"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”!

[
	{ "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 { … } : [?( … condition …)]

It checks that the product object has a “translate” property with value “yes”: @.translate == 'yes' . The @ character means to

Translate monolingual JSON - Tutorial