![]() |
JSON Localization and Internationalization |
JavaScript Object Notation (Wikipedia) is a lightweight text-based open standard that is used to store data. Soluling localization tool and service support JSON. You might have a standalone JSON file that needs to be localized, or your other file (e.g., application) contains embedded JSON data that needs to be localized. Soluling can handle them both.
A JSON file can contain text, number, and boolean properties. Here is a simple JSON file:
[
{
"id": "soccer",
"name": "Soccer",
"fieldplayers": 10,
"goalie": true,
"origin": "England",
"description": "Soccer is a sport played between two teams of eleven players with a spherical ball."
},
{
"id": "hockey",
"name": "Ice hockey",
"fieldplayers": 5,
"goalie": true,
"origin": "Canada",
"description": "Ice hockey is a team sport played on ice, in which skaters use sticks to direct a puck into the opposing team's goal."
},
{
"id": "basketball",
"name": "Basketball",
"fieldplayers": 5,
"goalie": false,
"origin": "United States",
"description": "Basketball is a team sport in which two teams of five players try to score points by throwing a ball through the top of a basketball hoop while following a set of rules."
}
]
The sample file contains three sport records that each contain six properties. The id property contains a unique record id. The name, origin, and description properties contain text that needs to be localized. The fieldplayers and goalie properties contain a number and a boolean that do not need to be localized.
When Soluling scans the file, it is smart enough to treat id as the context value, localize the three other string properties, and skip the number and boolean properties.
Here is the process for localizing JSON files. Soluling is a hybrid localization tool, which means you can use the cloud tool, the desktop tools, or both.
With Soluling Cloud, you localize a JSON file in your browser: upload the file, translate it in Translate, and download the localized files. You need a Soluling account. See the available Cloud plans. The steps below use the sport file shown above. Save it as Sport.json, or use the Sport.json sample file in GitHub.
Sport.json, or drag and drop the file onto the page. Click Create.Sport.json is written in.Sport.json, use the generic JSON parser.Soluling scans the file in the same way as described above: the name, origin, and description strings become rows to translate, the number and boolean properties are skipped, and the id values give the rows their context.
Click the project's green Translate button on the dashboard. Translate opens the project, and you can type the translations into the grid. Machine translation suggestions, translation memory, and spell checking are available there. You do not have to finish every language before moving on to the next step.

Sport.json with a download button for each target language. Click a language to download Sport.json localized into that language.When the JSON file changes, upload the new version, translate what is new or changed, and download the localized files again. For example, add the skiing record to Sport.json. Then, on the dashboard, click the project's Update file button (the upload arrow), select the edited Sport.json or drop it onto the page, and click Update. If the project has several files, use the file's own Manage file button in the project's Files section instead.
Existing translations are kept, so you only translate the rows that were added or changed. This is where the id values matter: because each record has an id, adding the skiing record does not change the context of the existing rows, and their translations stay valid. Read more in Context.
The dashboard is one of four ways to use Soluling Cloud. You can also use the SoluCLI command-line tool, Soluling Desktop, or SoluMake. See the Cloud tutorial for all of them.
If you use Soluling Desktop, you will get more options to configure how to localize. By default, Soluling localizes only string properties. You can use the default settings by accepting the default value in the Project Wizard.

When using the default settings, Soluling scans all string properties but not number or boolean properties. However, you can specify what properties are localized. In that case, check the Select items you want to localize radio button in the Project Wizard (or later in Source dialog). Project Wizard shows the structure of the file. Initially, only the name, origin, and description nodes are checked.

Double-click the fieldplayers and goalie nodes to check them. Once you have done that, you have instructed Soluling to localize all properties in the JSON file. You can read more about selecting items to be localized.
When you complete the Project Wizard, Soluling scans the JSON file and shows the localizable properties in the translation grid. Each row is one property. The Context column shows where the property is in the file. Because the records have an id property, the context uses the id value instead of the record's index (see Context). The grid has one translation column for each target language.

Type the translations into the translation columns. You can also use machine translation and translation memory to translate many rows at once, or send the project to translators. Read more about how to translate a project.
Once the project is translated, click Home | Build All to build the localized JSON files. Soluling creates one Sport.json for each target language, each in its own language directory, for example, fi\Sport.json and ja\Sport.json. The localized files have the same structure as the original file: only the translated string values differ, and the numbers and booleans keep their original values unless you selected them for localization.
Sometimes you need finer control over what properties are localized than the selection tree can offer. For example, you might have several properties with the same name, but there is one that you don't want to localize. The following JSON file contains one value property that should be localized and another that should not be localized.
{
"sample":
[
{
"value": "Translate this"
},
{
"value": "Do not translate this"
}
]
}
How can you solve this? The answer is to use the localize item. It is a boolean property that sets either a positive or a negative localize flag for the object that contains it. If you add a negative localize item, Soluling will not localize that value property even if you check it in the selection tree.
{
"sample":
[
{
"value": "Translate this"
},
{
"value": "Do not translate this",
"localize": false
}
]
}
Here is a positive localize item.
{
"sample":
[
{
"value": "Translate this",
"localize": true
},
{
"value": "Do not translate this"
}
]
}
Of course, you can add both negative and positive localize items in the same JSON file.
{
"sample":
[
{
"value": "Translate this",
"localize": true
},
{
"value": "Do not translate this",
"localize": false
}
]
}
The localize item is stronger than the selection. Even if you have not checked a property, it is localized if its object contains a positive localize item. If you check the Localize only those elements that have a positive localize item checkbox, Soluling localizes only those properties that have a positive localize item. So even if a property has been checked in the selection, it is not localized if it does not have a positive localize item. By default, Soluling handles localize and translate properties as localize items. You can turn any boolean property into a localize item by using the selection tree.
For example, if your file uses a property named loc instead, Soluling does not detect it automatically:
{
"sample":
[
{
"value": "Translate this"
},
{
"value": "Do not translate this",
"loc": false
}
]
}
In that case, right-click the loc node in the selection tree and set it as the localize item. After that, Soluling handles loc the same way as localize.
Context is a very important issue in JSON localization. Whenever Soluling extracts items from a source file, it has to give each item a unique context. The context is used to identify the extracted properties. Let's see how the context is generated. By default, the context is a combination of the property names (property + parent + parent's parent + ...) and the index of the item if it is in an array. The following JSON file contains sport names.
{
"sports":
[
{
"name": "Soccer"
},
{
"name": "Ice hockey"
},
{
"name": "Basketball"
}
]
}
When Soluling extracts the names, it gives each value a unique context. The following table shows the values and context values.
| Value | Context |
|---|---|
| Soccer | sports[0].name |
| Ice hockey | sports[1].name |
| Basketball | sports[2].name |
If you never change your JSON file, the default context works just fine. However, if you modify the JSON file, the context values of the existing elements may change. If we add a new Skiing element between Soccer and Ice hockey, the JSON file looks just fine.
{
"sports":
[
{
"name": "Soccer"
},
{
"name": "Skiing"
},
{
"name": "Ice hockey"
},
{
"name": "Basketball"
}
]
}
However, the context values change in a dangerous way. Only Soccer keeps its old context value, but all others get new context values.
| Value | New context | Old context |
|---|---|---|
| Soccer | sports[0].name | sports[0].name |
| Skiing | sports[1].name | - |
| Ice hockey | sports[2].name | sports[1].name |
| Basketball | sports[3].name | sports[2].name |
As a result, Soluling notices that either the original value or the context has changed, and it has to invalidate or drop the existing translations, so you may lose existing translations. How can we prevent this? Fortunately, there is a simple solution: use context values. Our original JSON file did not contain any context values, so we need to add them. The following JSON file is a modified file that contains context values in id properties.
{
"sports":
[
{
"id": "soccer",
"name": "Soccer"
},
{
"id": "hockey",
"name": "Ice hockey"
},
{
"id": "basketball",
"name": "Basketball"
}
]
}
Most real JSON files contain some context value. In most cases, it is either an id or a context property. However, a file might use a property with some other name.
The following table shows the values and context values.
| Value | Context |
|---|---|
| Soccer | sports[soccer].name |
| Ice hockey | sports[hockey].name |
| Basketball | sports[basketball].name |
If we now add the Skiing element, it won't change the existing context values.
{
"sports":
[
{
"id": "soccer",
"name": "Soccer"
},
{
"id": "skiing",
"name": "Skiing"
},
{
"id": "hockey",
"name": "Ice hockey"
},
{
"id": "basketball",
"name": "Basketball"
}
]
}
The following table shows the values, old and new context values.
| Value | New context | Old context |
|---|---|---|
| Soccer | sports[soccer].name | sports[soccer].name |
| Skiing | sports[skiing].name | |
| Ice hockey | sports[hockey].name | sports[hockey].name |
| Basketball | sports[basketball].name | sports[basketball].name |
As you can see, the existing context values remain unchanged. Soluling detects context properties automatically if they are named id or context. If you use a property with some other name, you have to specify it manually in the Items sheet of the Project Wizard or the Source dialog: right-click the property and choose Context value.
GitHub and <data-dir>\Samples\JSON contain the following JSON sample directories:
| Directory | Description |
|---|---|
| Simple | A simple JSON file. Same as the sample used above. Study this first. |
| Data | A sample file that contains binary data encoded as base64 strings. |
| Image | A sample file that contains base64, base32, base16/hex and URL encoded images. |
| Sport | A sample file that contains text and numbers. |
| Types | A sample file that contains various data types and a parameter that uses expression. |
You can configure how to localize your JSON file or data by selecting the item in the project tree, right-clicking, and choosing the Options menu. A source dialog appears that lets you edit the options. This source uses the following option sheets.
Read more about other data files such as XML, XSL, JSON, YAML, INI, Excel, SVG, TMX, XLIFF, text and binary files.