Default parsing

(1 string with key + variant)

HTML parsing

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

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.

Controls whether base characters ( > < & " ) are "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.

To use inline:
"smartling":{"entity_escaping": "false"}

String:
"smartling":{"entity_escaping": "auto"}

For example, your translation might look like this:
This is an <hr> & " example string4

By default, using the "auto" setting, we will assume this is HTML from the <hr> tag.

When the translated file is downloaded, the translated string will be escaped as:
This is an <hr> &amp; &quot; example string4

Using "smartling":{"entity_escaping": "false"}  will allow This is an <hr> & " example string4 to appear unescaped.

< (less-than)

&lt;

> (greater-than)

&gt;

& (ampersand)

&amp;

' (apostrophe or single quote)

" (double-quote)

html4 (default)|html5

(case-insensitive)

By default, all html4 entities are unescaped, except the basic set: &lt; &gt; &amp; &quot;.

When this directive is set to html5, all html5 entities will be unescaped as well.

"smartling":{"entity_escaping": "html5"}

Used to retain entity escaping for all non-base entities. For example, normally we turn &copy; into © but if we use this new directive the translation will automatically update to use escaping from the source. For each entity character, we'll check to see if it was escaped in the source and try to match (propagate) it in the target.

The default is none which is the current behavior, which recognizes HTML4 entities only - if HTML5 entities are required as well, you must use the entity_escaping_type=propagate directive.

propagate will only affect non-base entities - all named entities except &amp; , &quot;, &lt;, &gt; . Base entities continue to be controlled by HTML detection and the entity_escaping directive.

If the same character is both escaped and unescaped in the same string, propagate will return the characters in the translation escaped in the same order as they were in the source. However, if there are a different number of characters in the translation where the translation process removed or added some and the escaping is inconsistent among them, propagate will escape all entities for that character.

This directive can be placed inline, in the API or in a template (consult your SA about configuring directive templates).

This does not affect source content at all - so using it will not result in new strings.

Numerical entities are not considered at all with this directive, and are treated normally.

To use inline:
"smartling":{"entity_escaping": "propagate"}

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.

{
  "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"
      }
    ]
}

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

Specifies iOS-style placeholders for the file.

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

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

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.

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.

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

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 re-upload the file with variants on, Smartling will capture all content as new strings. You can configure SmartMatch to automatically match the existing translations.

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

A comma separated list of paths, as used to create “keys” for strings on translate_paths.

The key will be a space-separated string of all the keys leading to the source string. For example: “string”, “group1 string”.

Specify the full path to the value, then indicate which part of the path should be used as the key using {} notation.  Each part of the path that has {} will be used to construct the key, with each part separated by a ':#:' in the key.

Wildcard searches are supported.

Used to define the schema for capturing a key for each source string.

Keys are required:

If you want to import pre-existing translations from a file with the same structure
If you want to create variants of strings that would otherwise be duplicates; by default, Smartling does not create duplicate strings.
Creating or updating variants for previously uploaded strings will create new strings that will not have translations. The SmartMatch feature can be configured to automatically apply the existing translations, or translators can use the 100% match from the Translation Memory to manually apply the translation.

Note: Keys are not created if the element is a sibling of the element that has the string, e.g.:

string_format_paths = /data/value
and
source_key_paths = /data/

{key}

Result: though there are no errors, no key is created.

{
"smartling": {"source_key_paths" : ["data/{*}"]},
"data" : {
        "key1" : "text1",
        "key2" : "text2"
    }
}

The captured keys: "key1" for "text1" "key2" for "text2"

{
"smartling": {"source_key_paths" : ["{data}/{*}"]},
"data" : {
        "key1" : "text1",
        "key2" : "text2"
    }
}

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

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

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
• SVG - string value will be parsed as SVG
• 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.

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

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 precedence rules for other formats.

on|yes|true or off|no|false or leading|trailing

The default value is on

A whitespace is any character or series of characters that represent horizontal or vertical space in typography. When rendered, a whitespace character is not a visible mark, but does occupy an area or space on a page.

Although whitespaces are necessary within a string (typically to separate words), unnecessary whitespaces can be found at the start of a string (leading) and at the end of a string (trailing).

With this directive, you can trim whitespaces, as it enables or disables whitespace trim management for the ingested strings.

Whitespace is optionally trimmed from content then re-inserted on download for convenience so that translators do not have to manage the extra spaces. However, content owners may want to retain surrounding whitespace so that translators can
manipulate it during translation.

By default, the leading and trailing whitespaces are trimmed.

You can choose to disable trimming or specify trimming for leading or trailing whitespaces.

The directive can only be used as the API request parameter.

"smartling":{"whitespace_trim":on}

Smartling will trim leading and trailing whitespaces (default)

# smartling.whitespace_trim=off

Smartling will not trim leading or trailing whitespaces

# smartling.whitespace_trim=leading

Smartling will trim only leading whitespaces

# smartling.whitespace_trim=trailing

Smartling will trim only trailing whitespaces