JSON

JSON files are based on name/value pairs. For example, in this basic JSON file “button1” is the name and “Home” is the value.

JSON

{
"button1": "Home"
}

Name/value pairs can be nested so that a path of several names leads to a value.

Smartling parses JSON files for translatable strings, and for key/variant metadata (Smartling keys) and translator instructions relating to those strings. Only JSON values can become strings or translator instructions in Smartling. Depending on how your file is structured, however, you may want to capture either a JSON value, or part of a name path as a key. Smartling allows for either option using the translate_paths directive.

Default Parsing

If you upload a JSON file without any custom Smartling Integration directives Smartling will:

1. Capture all values in the file as strings.
2. Use the complete name path to each string as key and variant data.
3. Create placeholders in the strings using a default regular express to capture a number of common placeholder formats.
4. No Smartling String Instructions are captured.
5. Deliver translations, one file per language.

To parse the strings using ICU MessageFormat you must use the Smartling file directive string_format (either inline or via API). See ICU MessageFormat for more info. If ICU string formatting is used, then that takes precedence over HTML and any HTML directive will be ignored if your directives resolve in a value being parsed for both ICU and HTML. It is possible in a single file to have both HTML formatted strings and ICU formatted strings but they must be on different paths.

If a string contains HTML, Smartling automatically parses the strings in the file with basic HTML parsing, even without any HTML directive. Just note, this basic parsing will not break down the JSON value with HTML into smaller strings. It is ingested as one string. If this is not desirable and you want the value to be broken down into smaller strings in Smartling based on the HTML formatting, you can use the string_format_paths HTML feature. This will benefit both your translation resources and your translation memory leverage.

It is worth noting that in doing so, you lose any "keys", however, you still have "variants". In most cases, such as translation Jobs, this is acceptable, however, this is not acceptable if you are importing translations from a file, as keys are critical for alignment.

Example JSON value:

"terms": "<p>These are the terms you should be aware of them.</p><h1>First things first</h1><p>The first thing about the terms is that they apply to you.</p><h1>Second things second</h1><p>The second things about the terms is that they apply to us.</p>"

Default Placeholder Format

If you do not specify a custom placeholder format, even if you specify other directives, Smartling will convert the following subtext of a string into a placeholder for that string:

• {x}
• {{x}}
• ${x}
• %x%
• %%x%%
• ##x##
• __x__

Custom Integration

If you want to control how Smartling will capture the content and metadata from your JSON file, or specify a custom placeholder format, you can use custom Smartling directives. The directives can be added "inline" to the file or they be configured as API parameters.

JSON inline directives must be the "first" or "top" object in the JSON
If you are integrating "inline" the the integration "smartling" must be the first object in the JSON.

The syntax for directives might change if you are using them as API parameters instead of inlining them.

Below is an example of a JSON document with custom directives integrated in the file:

json.json file example:

{
"smartling" : {
"translate_paths": [{
"path": "*/translation",
"key": "{*}/translation",
"instruction":"*/translation-note"
}],
"placeholder_format_custom": ["\\^\\^.*?\\^\\^"],
"variants_enabled" : "true"
},
"Key1": {
"attribute": "4215050",
"translation": "Hello, ^^USER_NAME^^.",
"translation-note": "^^username^^ will be the first name, e.g. Mary"
},
"Key2": {
"attribute": "400913",
"translation": "Home",
"translation-note": "Used in navigation to provide link back to home page."
},
"Key3": {
"attribute": "4215049",
"translation": "Copyright 2017",
"translation-note": ""
},
"Key4": {
"attribute": "4213290",
"translation": "About Us"
}
}

The value of placeholder_format_custom is a regular expression (regex). We want to match on a "^" character as part of our expression. "^" is a reserved character for regex so we must escape it with "\". Because we are saving this in a JSON file where "\" is itself a reserved character for escaping, we must escape it for the JSON file with an additional "\".

Uploading this file will result in the following strings and metadata:

The values of the "attribute" names are completely ignored.

One of the strings has an empty/null instruction and another has no instruction at all. No errors are registered because of this.

Keys/Variants

By default, the full path of keys leading to a string are captured as Key and Variant metadata. Custom key paths can be set and variant behavior turned off with directives

Specifying Paths

Some directives require you to specify a path or set of paths to keys or strings in the file. A path is a slash-separated string which uses Xpath-like syntax (although it’s not Xpath.). The nodes separator is always / (slash).

Wildcards are allowed in path definitions.

• If no wildcards, then the path identifies a single node and all its children (“exact subpath”).
• If wildcards, then a path identifies a set of nodes and all their children (“path pattern”). Currently, only the * (asterisk) wildcard is implemented, which means “one or more nodes with any names”.
• Exact subpaths have precedence over path patterns.

For example, in the following path specifications:

[*/text, */string, system/log/text, system/log/text/details]

Smartling processes these paths as follows:

• /description/text — matches */text.
• /description/general/text - matches */text directly.
• /description/text/general — matches its parent, /description/text , matches */text.
• /system/log/text — matches both /system/log/text (exact path) and */text (pattern). Exact path takes precedence.
• /system/log/text/details — matches its parent, /system/log/text and system/log/text/details (exact). Exact path takes precedence.

See Placeholders in Resource Files for more on placeholders.

Return Untranslated Strings as Empty

When using the API file/get to download JSON files from Smartling, the parameter includeOriginalStrings=false ensures that if no translations are available, Smartling returns an empty string. If the parameter is set to true, Smartling returns the original string.

Pseudo Translations

The pseudo_inflation directive is not supported as an inline directive for JSON files, however, you can still control pseudo inflation for JSON files by including it as an argument in the API upload request. For example: smartling.pseudo_inflation=70 will result in pseudo translation length being increased by 70 percent.

Directives

Format

JSON

{
"smartling" : {
"directive_name" : "value",
"directive_name" : "value",
"..."
},
...
}

character_limit

{
   "smartling" : {
     "translate_paths" : [
     {
       "path":"/*/text",
       "key":"/*/id",
       "character_limit" : "/*/limit"
     },
     {
       "path":"/*/value",
       "key":"/*/key",
       "character_limit" : "/*/charlimit"
     }],
   },
   "testkey1" : {
     "limit" : 10,
     "text" : "item1",
     "id" : 1
       },
   "testkey2" : {
     "limit" : 20,
     "text" : "item2",
     "id" : 2
     },
   "testkey3" : {
     "limit" : 30,
     "text" : "item3",
     "id" : 3
     },
   "testkey4" : {
     "charimit" : 100,
     "value" : "item4",
     "key : "key"
   }
}

entity_escaping

Control whether or not certain characters will be HTML escaped when delivering the translations.

"smartling":{"entity_escaping": "false"}

For example, your translation in the dashboard might look like this:
Smartling <hr> HTML escaping <, >, &, " example

By default, using the auto setting, we would assume this is HTML from the <hr> tag present in the translation and it would be delivered as:

Smartling <hr> HTML escaping &lt;, &gt;, &amp;, &quot;, example

When downloading the translated file.

Using false would deliver:

Smartling <hr> HTML escaping <, >, &, ", example 

with no characters entity escaped.

exclude_path

{
  "smartling" : {
    "translate_paths" : [
      {
        "path":"/nodes/*",
        "exclude_path":"*/comment"
      },    
      {
        "path":"/messages/*",
        "exclude_path":"*/note"
      }
    ]
  },
  "nodes" : [
      {
        "text" : "item1",
        "comment" : "comment1"
      },
      {
        "text" : "item2",
        "comment" : "comment2"
      },
      {
        "text" : "item3",
        "comment" : "comment3"
      }
    ],
  "messages" : [
      {
        "message" : "message1",
        "note" : "note1"
      },
      {
        "message" : "message2",
        "note" : "note2"
      },
      {
        "message" : "message3",
        "note" : "note3"
      }
    ]
}

placeholder_format

"smartling":{"placeholder_format" : "IOS"}

placeholder_format_custom

"smartling" : {
    "placeholder_format_custom" : ["\[.+?\]"]
}

translate_paths

"smartling": {
  "translate_paths": [{
    "path": "//text",
    "key": "/{}/text",
    "instruction": "/*/notes"
  }]
}

translate_paths (to be deprecated)

"translate_paths": ["*/translation"]

source_key_paths (deprecated)

"source_key_paths" : "{*}"

"source_key_paths" : "data/item/{string_name/*}"

variants_enabled

"smartling": {"variants_enabled" : "TRUE"}

string_format

"smartling":{"string_format" : "icu"}

string_format_paths

"smartling": {"string_format_paths" : "html: *"}

"smartling": {"string_format_paths" : "html: */text"}

"smartling": {"string_format_paths" : "html: [/text, string]"}

"smartling": {"string_format_paths" : "html: /product/description"}

"smartling": {"string_format_paths": "icu: [*]"}

"smartling": {"string_format_paths" : "html: */text, @default: /system/log/text"}