Back to top image

Capturing JSON Content

 

Your Global Delivery Network project may have content delivered as JSON, such as content coming from AJAX requests.

This article is for JSON as a result of a JSON request. To identify JSON appearing within a Javascript string literal please reference our JavaScript article here.

Certain JSON key/value pairs may be required to remain in their source language to preserve the functionality of your site, and for this reason, Smartling does not automatically capture JSON content for translation. Instead, you need to identify where in your JSON the specific values to be translated are located.

JSON is made up of key/value pairs. Smartling translates only JSON values.

 

Identify Translatable Content

You can either specify translatable and un-translatable keys, or use more granular directives to identify translatable and un-translatable key paths.

 

Identify Translatable Keys: sl_translate

Indicating what JSON values you need to be translated is as simple as creating a new key/value pair using our custom "sl_translate" key. This key can have three values:

  • "sl_all" - All values are translated.
  • "sl_none" - No values are translated.
  • Comma-separated list of JSON keys to identify that their values should be translated.

The sl_translate needs to be the first key for it to be effective

The examples below consider the three types of supported key/value pairs.

 

Using "sl_all"

{
"sl_translate": "sl_all",
"status": 200,
"messages": "The request was successful",
"user": {
    "firstName": "John",
    "role": "Editor",
    "admin": false
},
"string1": "Here's some content for John to translate.",
"string2": "<div>Smartling automatically recognizes HTML in a JSON string.</div>",
"string3": "This is an additional string from your site."
}

All of these strings will be ingested:

  • "The request was successful"
  • "John"
  • "Editor"
  • "Here's some content for John to translate."
  • "<div>Smartling automatically recognizes HTML in a JSON string</div>"
  • "This is an additional string from your site."

 

Using "sl_none"

{
"sl_translate": "sl_none",
"status": 200,
"messages": "The request was successful",
"user": {
    "firstName": "John",
    "role": "Editor",
    "admin": false
},
"string1": "Here's some content for John to translate.",
"string2": "<div>Smartling automatically recognizes HTML in a JSON string.</div>",
"string3": "This is an additional string from your site."
}
 None of the strings above will be ingested for translation. The "sl_none" value has a higher priority than "sl_all", and if both are used in a comma-separated list, "sl_none" will be prioritized and no strings will be ingested.

 

Using a Comma-separated List to Identify Keys

You have the ability to specify what keys you want to be translated by listing them as the value for the "sl_translate" key. For example:

{
"sl_translate": "messages, firstName, role",
"status": 200,
"messages": "The request was successful",
"user": {
    "firstName": "John",
    "role": "Editor",
    "admin": false
},
"string1": "Here's some content for John to translate.",
"string2": "<div>Smartling automatically recognizes HTML in a JSON string.</div>",
"string3": "This is an additional string from your site."
}
 Only the values for the directly specified keys will be ingested. For example, to capture the string "John", we need to directly specify the "firstName" key it belongs to instead of its parent key of "user". For the above JSON, the following will be ingested:
  • "The request was successful"
  • "John"
  • "Editor"

Smartling automatically recognizes HTML content in JSON strings and parses it as HTML.

 

Identify Un-translatable Keys: sl_notranslate

There may be cases when you would need to specify key/value pairs that do not require translation. For example, when working with a JSON file where it would be beneficial to use "sl_all" and indicate values that should be ignored instead of creating a large comma-separated list of values.

This can be done by using the "sl_notranslate" key that supports a comma-separated list of JSON keys to identify which values should not be translated:

{
"sl_translate": "sl_all",
"sl_notranslate": "messages, role",
"status": 200,
"messages": "The request was successful",
"user": {
    "firstName": "John",
    "role": "Editor",
    "admin": false
},
"string1": "Here's some content for John to translate.",
"string2": "<div>Smartling automatically recognizes HTML in a JSON string.</div>",
"string3": "This is an additional string from your site."
}

All of the strings in the above example will be ingested due to the "sl_all" key, with the exception of the specified "message" and "role" values that belong to "sl_notranslate":

  • "John:
  • "Here's some content for John to translate."
  • "<div>Smartling <strong>automatically</strong> recognises HTML markup in a JSON string</div>"
  • "This is an additional string from your site."

Identify Translatable Key Paths: sl_path

The directive "sl_translate" is applied to all identified keys, regardless of their specific path.
If you prefer marking only specific key paths as translatable, use the directive "sl_path" instead. This directive allows you to identify the exact key path(s) that should be translated. 

Note: The sl_path directive needs to be the first key for it to be effective

Example:

{
"sl_path": "property/name",
"status": 200,
"messages": "The request was successful",
"brand": {
   "name": "Great Brand",
   "type": "Organization"
   }
"property": {
   "location": "United States",
   "name": "New property for sale",
   "available": false
   }
}

In the above example, only the string property name (property/name) will be translated. The brand name (brand/name) is not identified by the "sl_path" directive and will not be translated.

To translate more than one key path, use a comma-separated list of translatable JSON key paths.

Alternatively, you can use a plus sign (+) as a wildcard to match any key at its level.
Example: store/bicycle/+ will match paths like store/bicycle/color or store/bicycle/style

Using a hashtag as a wildcard (#) matches all remaining levels.
Example: store/bicycle/# will match paths like store/bicycle/price or store/bicycle/price/discount

 

Identify Un-Translatable Key Paths: sl_path_notranslate

To identify specific key paths that should remain untranslated, use the directive "sl_path_notranslate".

Example:

{
"sl_path_notranslate": "brand/name",
"status": 200,
"messages": "The request was successful",
"brand": {
   "name": "Great Brand",
   "type": "Organization"
   }
"property": {
   "location": "United States",
   "name": "New property for sale",
   "available": false
   }
}

In the above example, only the brand name (brand/name) is identified as un-translatable.

 

Create Variant Metadata for JSON Strings

If you want to create variant metadata in Smartling, you can do so by adding a "sl_variant" entry to your JSON object. This should contain a comma-separated list of JSON keys and variant values. For example:

{
    "sl_translate": "sl_all",
    "sl_variant": "string1:navmenu, string2:navmenu, string3:exitmessage",
    "string1": "Home",
    "string2": "Back",
    "string3": "Goodbye"
}

Using "sl_variant" above would create the following strings in Smartling:

String: Home
Variant: navmenu

String: Back
Variant: navmenu

String: Goodbye
Variant: exitmessage

Table of Contents