JSON

 

Extension	.json
Smartling Identifier	json
Example File	(see example below)
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.

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.

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. Smartling, however, will do basic HTML parsing of the strings in the file even without any HTML directive, but won't break down a large JSON value with HTML, into smaller strings. It will come in as one string.

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:

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

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

Exact delivery depends on file type.

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.
Examples	To use inline: <!-- smartling.entity_escaping = false --> String: <!-- smartling.entity_escaping = auto -->

For example, your translation might look like this:
Smartling HTML escaping < > & " example string4

By default, using the "auto" setting, we would assume this is HTML from the <hr> tag and it would be converted to:
Smartling HTML escaping < > & " example string4

Using smartling.entity_escaping = false would allow Smartling HTML escaping < > & " example string4 to appear as it should.

string_format

Value	icu
Description	Parse the strings in this JSON file using ICU MessageFormat rules for placeholders, SelectFormat, PluralFormat
Examples	"string_format" : "icu"

 

placeholder_format

Values	NONE; C; IOS; PYTHON; JAVA; YAML; QT, RESX
Description	Used to specify a standard placeholder format
Examples	"placeholder_format" : "IOS" Specifies iOS-style placeholders for the file.

 

placeholder_format_custom

Values	1) Custom Perl compatible 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	"placeholder_format_custom" : ["\[.+?\]"] Any characters surrounded by square brackets will be treated as a placeholder.

 

translate_paths

Description

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

 

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 object.
Description	When included in this list, all plain text within the specified path will be considered a translatable string.
Examples	"translate_paths": ["*/translation"] Smartling will tranlate content in any path ending in translation, such as string/translation nav/translation, etc.

 

source_key_paths (deprecated)

Values	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”. For new files, use the new translate paths directive.
Description	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 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.
Examples	"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’

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	"variants_enabled" : "TRUE"

 

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 @default - (note the leading at-sign) string value will be treated as simple text. TXT - string value will be parsed as plain text with strings separated by new lines. 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.
Examples	"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.