Extension .json
Smartling identifier json
Example File json.json
Resources Official JSON Standards

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

    "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 include no integration directives, Smartling will apply its default template and capture all JSON values as translatable strings and the complete name path leading to each string as key and variant metadata. The following placeholder types will be captured:


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.

For example, in the following path specifications:

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

Smartling processes these paths as follows:

Other Information

New defaults for JSON handling are in place for accounts created after June 11 2015. See here for details.

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=70will result in pseudo translation length being increased by 70 percent. Accepted values are 50-100.

Note: When using 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.


Directive Format

    "smartling" : {
        "directive_name" : "value",
        "directive_name" : "value",

JSON directives are set at the top of the file, in the "smartling" node. Directives apply to the whole file and cannot be changed.

Note: Directives in JSON sometimes require extra escaping. For example, in a regular expression for the placeholder_format_custom directive, it is necessary to double escape special characters, since \ is an escape character for both regex and JSON.

Remember if you switch from using inline JSON directives to specifying directives in the Upload File API request, your directives may need to take a slightly different format. For example: in JSON, you can specify square bracket placeholders like this: "placeholder_format_custom": "\\[.+?\\]", but as an API directive, the same command would take the format smartling.placeholder_format_custom=\[.+?\].



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

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 {}. For example.

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

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

To set translate paths via the Upload File API request, you can pass the translate_paths object as a single string literal. Depending on platform/format, you may need to escape the double-quotes. For example: smartling.translate_paths={\"path\": \"/*/text\", \"key\": \"/{*}/text\", \"instruction\": \"/*/notes\"}

For more information, see Advanced JSON Configuration.

translate_paths (to be deprecated)

Values:A comma-separated list of paths to be captured as strings for translation. Note: for new files, use the new translate paths directive.
Description:When included in this list, all plain text within the specified tag will be considered a translatable string. Optionally, you can append a "." and a relevant attribute name to the path to translate tag attributes with the file. You can end the path with a trailing slash, "/" and it will treat all child nodes as translatable (content must still be text within a tag).
"translate_paths": ["*/translation"]

Smartling will tranlate content in any path ending in translation, such as string/translation, nav/translation, etc.

source_key_paths (to be deprecated)


A comma separated list of paths to use 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".

Note: for new files, use the new translate paths directive.


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

    Note: creating or updating variants for previously uploaded strings cause new strings to be created 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 to manually apply the translation.

  • Specify the full path to the value, then indicate which part of the path should be used as the key using {} notation.

"source_key_paths" : "{*}"

Smartling will capture the full path of keys leading to each translatable string as Key metadata

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

smartling will capture string_name [any subsequent keys] as the key


Values:1. Custom regular expression (pcre)
2. NONE - disable custom placeholders
Description:Used to define a custom placeholder format for strings in the file. See Placeholders in Resource Files for more information.
"placeholder_format_custom" : ["\\[.+?\\]"]

Any characters surrounded by square brackets will be treated as a placeholder.


Description:Used to specify a standard placeholder format. See Placeholders in Resource Files for more information.
"placeholder_format" : "IOS"

Specifies iOS-style placeholders for the file.


Values: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 code>source_key_paths directive, which provides the information needed to generate variant metadata.

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

"variants_enabled" : "TRUE"


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

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
  • @default - (note the leading at-sign) string value will be treated as simple text.

Separate multiple formats 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.

"string_format_paths" : "html: *"

Smartling parses values of all nodes as HTML.

"string_format_paths" : "html: */text"

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

"string_format_paths" : "html: [*/text, *string]"

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

"string_format_paths" : "html: /product/description"

Smartling enables HTML in /product/description and subnodes

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