Soluling home   Document home

JSON Localization and Internationalization

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.

Cloud process Cloud process

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.

Create a project

  1. Sign in at www.soluling.com and open Cloud > Dashboard for Projects, Users and Terminology.
  2. Click Add a new project, then Select files and pick Sport.json, or drag and drop the file onto the page. Click Create.
  3. On the next page, check the project's Name. It defaults to the file's name.
  4. Set the Original language to English, the language Sport.json is written in.
  5. Under Target languages, check the languages you want to translate to, for example, Finnish and Japanese.
  6. Under Source type, select JSON file (.json). Soluling has several JSON parsers, for example, for Angular-translate and Ngx-translate files. For a plain JSON file such as Sport.json, use the generic JSON parser.
  7. Click Create. The project appears on the dashboard, and its status changes to Ready once the file has been processed.

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.

Translate the project

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.

Translating the JSON file in Soluling Translate

Get the localized files

  1. In Translate's top bar, click the project's name. It opens the project's Manage page, the same page that the project's Manage button on the dashboard opens.
  2. If you have translated something since the localized files were last built, the page says Localized files need to be built. Click Build localized files and wait until it finishes.
  3. The Files section lists Sport.json with a download button for each target language. Click a language to download Sport.json localized into that language.

Update the project

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.

Desktop process Desktop process

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.

Localize all items

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.

Select items you want to localize

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.

Translate the project

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.

Translating the JSON file in Soluling Desktop

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.

Localize item of JSON

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

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.

Samples

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.

Configuring JSON Localization

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.

Settings

Read more about other data files such as XML, XSL, JSON, YAML, INI, Excel, SVG, TMX, XLIFF, text and binary files.