All Collections
How-tos
How to enable JSON format translation?
How to enable JSON format translation?
Edvard avatar
Written by Edvard
Updated over a week ago

In modern web applications data is being transferred through AJAX requests using JSON format. By default we do not translate JSON objects, since it may break the application. To be able to translate JSON objects correctly we need to know which keys we may translate.

Note: This is only for paid plans of GTranslate.

Note: This article is written for technical persons. Please contact our live chat if you need help.

Let's say you have the following JSON object which needs to be translated:

{
    "name": "test",
    "description": "test description",
    "id": 500,
    "months": ["January","February","March"],
    "content": "<i>Hello world</i>",
    "domain": "example.com",
    "user": {
        "login": "test",
        "bio": "test user",
        "profile_link": "https://example.com/profile/test"
    }
}

You need to specify the keys to be translated in the JSON object by using special key gt_translate_keys. Like this:

{
    "name": "test",
    "description": "test description",
    "id": 500,
    "months": ["January","February","March"],
    "content": "<i>Hello world</i>",
    "domain": "example.com",
    "gt_translate_keys": ["name", "description", {"key": "months", "format": "list"}, {"key": "content", "format": "html"}, {"key": "domain", "format": "domain"}],
    "user": {
        "login": "test",
        "bio": "test user",
        "profile_link": "https://example.com/profile/test",
        "gt_translate_keys": [{"key": "bio", "format": "text"}, {"key": "profile_link", "format": "url"}]
    }
}

As you can see from this example, gt_translate_keys should be an array. It may simply specify the name of the key, value of which should be translated, or also specify the format of the value. Possible formats of the value are list, html, html-list, html-urlencoded, html-base64encoded, html-htmlentityencoded, html-jsonencoded, url, domain, json or text, which is the default format if not specified.

After it is translated it will look like this:

{
    "name": "тест",
    "description": "тестовое описание",
    "id": 500,
    "months": ["Январь","Февраль","Март"],
    "content": "<i>Привет мир</i>",
    "domain": "ru.example.com",
    "user": {
        "login": "test",
        "bio": "тестовый пользователь",
        "profile_link": "https://ru.example.com/profile/test"
    }
}


You can also define JSON keys in your User Dashboard. In that case the keys will be applied to all JSON objects on your website. The same results in the example above can be achieved by defining the keys from Settings → Advanced Settings → Translate JSON Keys:

+-------------------+---------+
| KEY | FORMAT |
+-------------------+---------+
| name | Text |
| description | Text |
| months | List |
| content | HTML |
| domain | Domain |
| user.bio | Text |
| user.profile_link | URL |
+-------------------+---------+

In other words this tells GTranslate to translate the values of name and description keys as text, treat the value of months key as a list of strings, treat the value of the content key as HTML, translate the user object's bio value as text and finally add current language code in the user objects's profile_link value.

Note: This will make sure that the defined key values are translated in all JSON objects.

We also support defining keys via X-GT-Translate-Keys request header, which is particularly useful during API calls:

curl --header "X-GT-Translate-Keys: name,description,months->list,content->html,domain->domain,user.bio,user.profile_link->url" https://es.example.com/test.json

Let's check another example which involves arrays:

{
    "users": [
        {"name": "test 1", "bio": "test user 1"},
        {"name": "test 2", "bio": "test user 2"},
        {"name": "test 3", "bio": "test user 3"}
    ]
}

In this case we would like to translate the name and the bio of each user in users array. For that we define the JSON keys as following:

users.#.name,users.#.bio

Note the "#" character, which iterates through users array to find the defined name and bio keys.

After translation the JSON object will look like this:

{
    "users": [
        {"name": "тест 1", "bio": "тестовый пользователь 1"},
        {"name": "тест 2", "bio": "тестовый пользователь 2"},
        {"name": "тест 3", "bio": "тестовый пользователь 3"}
    ]
}

Did this answer your question?