Supported File Types

JSON

 

Extension .json
Smartling Identifier json
Example File Example JSON with common directives
Resources Official JSON Standards 

JSON files are based on name and 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.

Inline file directives are listed below.

Content Parsing

Default

If you upload a JSON file without any custom Smartling 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. Not capture any string instructions
  5. Deliver translations, one file per language.

For more information, see Content Parsing.

HTML

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 directive:

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 string with default vs HTML parsing:

"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 parsing

 

 

(1 string with key + variant)

HTML parsing

 

(5 strings with variant only - translations cannot be imported)

<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>
  1. These are the terms you should be aware of.
  2. First things first
  3. The first thing about the terms is that they apply to you.
  4. Second things second
  5. The second things about the terms is that they apply to us.

Plurals

ICU MessageFormat

To parse the strings using ICU MessageFormat you can use two Smartling directives (either inline or via API):

  1. string_format with a value of icu
  2. string_format_paths with a value of icu and then specifying array of the specific keys or paths.

Smartling paths support simple wildcards. See ICU MessageFormat for additional information.

ICU MessageFormat parsing implies both placeholders and support for advanced formatting syntax such as select statements and plurals. When parsing strings as ICU MessageFormat that default placeholder syntax takes precedence and will always apply if the syntax is present.

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.

Preparing JSON for Translation

Directives are commands embedded in code that essentially direct Smartling to the various elements in your file. Examples include the path where your content for translation, where to find translator instructions, where any key or variants are, and command multi-lingual output, so all translations are on one file. See examples of these directives below.

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 node’s 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.

Keys and 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 by using the variants_enabled directive.

String Instructions

Smartling will automatically ingest and display any value or path paired with the "instruction" name as instructions for translators. The instructions must  precede the "translate_paths".

For example, for the following thread, the instruction is anything that is paired with the "translation-node" path will be captured as a file instruction for translators,

When translators translate the string Hello, ^^USER_NAME^^ the instruction "^^username^^ will be the first name, e.g. Mary" will be visible to them in the CAT Tool. Similarly, the string Home will include the instruction "Used in navigation to provide link back to home page."

JSON

{
"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."
},

See File and String Instructions for more information on using instructions.

Placeholder Format

Default

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

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 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 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:

String Key Instruction
Hello, ^^USER_NAME^^. Key1 ^^username^^ will be the first name, e.g. Mary
Home Key2 Used in navigation to provide link back to home page.
Copyright 2017 Key3  
About Us Key4  

The values of the "attribute" names are ignored.

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

See Placeholders in Resource Files for more on placeholders.

Exclude Content from Translation

You can specify paths to exclude from translation by using the exclude_path directive. Note that exclude_path always must be a sub-path of path pointer in the same set of translate_paths item.

For more information on excluding content via the Smartling dashboard, see Exclude Content from Translation and Restore.

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.

See Pseudo Translations for more information on how you can view pseudo translations.

Directives

Format

JSON

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

character_limit

Values integer or NONE
Description Sets or removes the maximum characters allowed for a translation. If NONE is specified, character limits will be removed. (You can also remove the limit key/value pair and re-upload a file.)
Examples (See example below.)

{
   "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.

Values  auto (default)
true (or yes)
false (or no) 
Description Can control whether or not characters will be "escaped" into entities when delivering translations. This can be set universally for the whole file via API, or by setting the directive at the top/start of the file. The directive can also be placed inline to control the behavior of specific strings.
In Auto mode Smartling escaping will depend on whether Smartling believes the specific string requires HTML escaping. With true or false this will force the behavior for all strings. 
Examples 

To use inline:

"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

Values The value of this directive is expressed as exclude_paths:[path].
Description

Excludes the specified path as content that will be translated.  Content will not be parsed.  

Notice that exclude_path always must be a sub-path of path pointer in the same set of translate_paths item.

Examples
{
  "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

Values  NONE; C; IOS; PYTHON; JAVA; YAML; QT, RESX 
Description  Used to specify a standard placeholder format 
Examples 
"smartling":{"placeholder_format" : "IOS"}

Specifies iOS-style placeholders for the file.

 

 

placeholder_format_custom

Values 

 

1) Custom Java regular expression.
2) NONE - disables any current custom placeholders

 
Description   Specifies a custom placeholder format. Any text in your file matching the regular expression you provide will be captured as a placeholder.
Examples 
"smartling" : {
"placeholder_format_custom" : ["\[.+?\]"]
}

When customizing placeholders with this directive inside the file, the value must be expressed as an array of strings (square brackets).

 

See Placeholders in Resource Files for more on placeholders.

translate_paths

Description 

The translate_paths directive tells Smartling which parts of your JSON file are translatable strings, keys and instructions.

The value is an array of objects. Each object contains one path, that is at the minimum the path to the strings to extract. For each path you can also optionally specify how to assign the key and translator instructions for each string found on that path.

The object takes three parameters:

path - the name path leading to a translatable string (required)
instruction - the name path leading to a translator instruction
key - EITHER the name path leading to a value you want to capture as a Smartling key OR the part of a name path leading to a translatable string you want to use as a Smartling key

For path and instruction, see Specifying Paths.

If your key is a JSON value, see Specifying Paths. If you want to capture part of the name path to the translatable string, give the path to the translatable string, surrounding the part of the name path you want to capture as the key with curly braces {}.

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


An upload will fail if Smartling cannot find at least one translatable string in your file but, otherwise, errors in your key and instruction paths will not cause an upload to fail. If your key and instruction paths do not match any content in your JSON file, no keys or instructions will be captured, but the upload will still proceed. Check your content in the Dashboard after uploading to be sure you have captured the correct information.


For more information, see Advanced JSON Configuration.

 

key_generation_strategy

Values  strict | partial_match
Description 

Used to specify the method used to generate keys. This is not mandatory. The default is strict.

strict = construct a variant from defined key paths - all paths must match in order to capture the key.
partial_match = construct a variant from available keys, and would skip any missing keys.
Keys are evaluated and added to a variant in the order they listed in the key directive.

Examples 
{
  "smartling": {
    "translate_paths": [{
      "path": "/strings/text",
      "key": ["/strings/key1", "/strings/key2", "/strings/key3"],
      "key_generation_strategy": "partial_match"
    }]
  },
  "strings": [{
      "key1": "A",
      "key2": "B",
      "key3": "C",
      "text": "String1"
    },
    {
      "key1": "A",
      "key2": "B",
      "text": "String2"
    },
    {
      "key2": "B",
      "key3": "C",
      "text": "String3"
    },
    {
      "key1": "A",
      "key3": "C",
      "text": "String4"
    },
    {
      "key3": "C",
      "text": "String5"
    },
    {
      "text": "String6"
    },
  ]
}
}
Variant String
ABC String1
AB String2
BC String3
AC String4
C String5
  String6

 

 

variants_enabled

Values

 

true|TRUE|on|ON OR false|FALSE|off|OFF

Description

When enabled, Smartling will make strings unique using variant metadata. Must be used in conjunction with the source_key_paths directive, which provides the information needed to generate variant metadata.

If you have previously uploaded a file with variants turned off, and reupload the file with variants on, Smartling will capture all content as new strings. You can configure Smartmatch to automatically match the existing translations.

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

 

string_format

Value  icu
Description 

Parse the strings in this JSON file using ICU MessageFormat rules for placeholders, SelectFormat, PluralFormat.

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

 

string_format_paths

Values The value of this directive is expressed as [format]:[paths].
Description

Specifies the format of strings for the specified paths and can enable HTML inside another file format.

Currently supported formats are:

  • HTML - string value will be parsed as HTML
  • ICU - string value will be parsed as ICU MessageFormat
  • TXT - string value will be parsed as plain text with strings separated by new lines.
  • Markdown - string value will be parsed as Markdown.
  • @default - (note the leading at-sign) string value will be treated as simple text.

Separate multiple paths by commas. 

You may specify a single path for a format or a comma-separated list of paths enclosed in square brackets. The list may be empty.

Wildcards are allowed in path definitions.

  • If no wildcards are used, then the path identifies a single node and all its children ("exact subpath").
  • If wildcards are used, then a path identifies a set of nodes and all their children ("path pattern"). Currently, only * (asterisk) wildcard is implemented, which means "one or more nodes with any names".
  • Exact subpaths have precedence over path patterns.
Examples
"smartling": {"string_format_paths" : "html: *"}

Smartling parses values of all nodes as HTML.

----

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

Smartling enables HTML in text nodes (and their subnodes), regardless of their parents.

----

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

Smartling enables HTML in text and string nodes (and their subnodes), regardless of their parents.

----

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

Smartling enables HTML in /product/description and subnodes.

----

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

Smartling parses all strings as ICU MessageFormat

---- 

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

Smartling enables HTML in text nodes (and subnodes), but disables HTML in /system/log/text (and subnodes), as the exact match overrides the pattern match.

Considerations

When to use multiple string_format_paths in a single document, recommended use case:

If your document has disparate kinds of strings that are used in different contexts, for example, if your single JSON file contains application UI strings, with standard string formatting and placeholders, together with one or few keys that are just giant HTML documents (example; TOS or Privacy Policy).
Just remember the side effects of HTML parsing, including losing keys, and precendence rules for other formats.

Was this article helpful?