Preparing Content for Translation

ICU Message Format

Smartling only supports ICU MessageFormat in JSON files.

Smartling supports standard arguments (a.k.a. placeholders), as well as 'select' and 'plural' arguments. The following items will not be supported: 'selectordinal', nested 'select' and 'plural', and plural strings with multiple plurals. If you are currently using MessageFormat or considering using it, contact your Smartling Customer Success Manager to review your files and ensure compatibility.

Capture

Smartling can parse your resource file’s strings as ICU MessageFormat strings. Using this string formatting impacts how strings are created in your project. Captured strings are prepared and optimized for translation in the Smartling CAT tool.

Translation

When translating ICU MessageFormat strings translators and editors are not required to understand ICU MessageFormat syntax. They are presented with normalized strings that are segmented and use placeholders (tags) as needed, making them easily translatable.

Mapping ICU MessageFormat Features to Strings

The support for ICU MessagFormat is “limited”. See the tables below for details and examples.

ICU Feature Smartling Support 
Fully Supported:   
String without arguments  Plain string without placeholders 
String with arguments  String with placeholders 
String with single select argument  Multiple source strings; one source string for each option of the select.
String with single plural argument  Smartling Plural string - see Plurals for more information on how Smartling captures plural strings and presents them for translation.
Partially Supported:   
String with multiple nested arguments (limit of one plural)  Limited to creating up to 20 strings, otherwise unsupported and captured as raw text
String with choice argument  Multiple source strings; one source string for each option of the select.
Not Supported:   
String with multiple plural argument  Not supported - captured as raw text 
String with plural argument and offset property  Not supported - captured as raw text 
String with selectordinal argument  Not supported - captured as raw text

 

In the following table we show the value of an example source string and the corresponding string captured in Smartling.

ICU Example String  Smartling Captured String(s) 
Hello world.  Hello world.
Hello world. Welcome to ICU MessageFormat support.  Hello world. Welcome to ICU MessageFormat support. 
Current temperature {temp}.  Current temperature {0}. 
Please confirm this is your date of birth: {dob, date}.  Please confirm this is your date of birth: {0}.
You chose {selector, select, 1 {Option 1} other {an unsupported option.}}  You chose Option 1
You chose an unsupported option. 
Your playlist has {items, plural, one {# album.} other {# albums.}} 

Plural Other: Your playlist has {0} albums.
Plural One: Your playlist has {0} album.

{color1, select, red {{color2, select, red {Red and Red make Red} yellow {Red and Yellow make Orange} blue {Red and Blue make Purple} other {Choose primary colors.}}}yellow {{color2, select, red {Yellow and Red make Orange} yellow {Yellow and Yellow make Yellow} blue {Yellow and Blue make Green} other {Choose primary colors.}}}blue {{color2, select, red {Blue and Red make Purple} yellow {Blue and Yellow make Green} blue {Blue and Blue make Blue} other {Choose primary colors.}}}other {Choose primary colors.}}
  1. Red and Red make Red
  2. Red and Yellow make Orange
  3. Red and Blue make Purple
  4. Choose Primary colors.
  5. Yellow and Red make Orange
  6. Yellow and Yellow make Yellow
  7. Yellow and Blue make Green
  8. Blue and Red make Purple
  9. Blue and Yellow make Green
  10. Blue and Blue make Blue 
The following strings are “unsupported” and are captured as raw text.   
Your playlist has {items, plural, one {# album.} other {# albums.}} and {items, plural, one {# song.} other {# songs.}}  Your playlist has {items, plural, one {# album.} other {# albums.}} and {items, plural, one {# song.} other {# songs.}} 
You {NUM_ADDS, plural, offset:1
=0 {did not add this}
=1 {added this}
one {and one other person added this}
other {and # others added this}
You {NUM_ADDS, plural, offset:1
=0 {did not add this}
=1 {added this}
one {and one other person added this}
other {and # others added this}
It's my dog's {year, selectordinal, one {#st} two {#nd} few {#rd} other {#th}} birthday!  It's my dog's {year, selectordinal, one {#st} two {#nd} few {#rd} other {#th}} birthday! 

 

File Formats

Smartling supports ICU MessageFormat strings in the following file formats:

JSON

To parse the strings using ICU MessageFormat you must use the Smartling file directive string_format with a value of icu (either inline or via API) - see JSON for more details about Smartling directives.

Directive  Value
string_format icu

Example using the Smartling CLI tool:

$ smartling-cli files push icu.json --directive string_format=icu

Example of inline integration:

{
     "smartling" :
        {
          "string_format" : "icu"
        },
     "1" : "Hello world.",
     "2" : "Hello {name}.",
     "3" : "{option, select, morning {Good morning world.} night {Good night world.} other {Hello world}}",
     "4" : "{people_count, plural, one {{people_count} person here.} other {{people_count} people here.}}"
}

When using ICU MessageFormat, no other placeholder formats should be enabled.

You can use translate_paths to target specific keys in your JSON file. See the JSON file integration documentation for full details.

About Select and Choice Format Strings

Smartling will create one string for each permutation of the options. The strings appear in the Smartling dashboard as separate strings with no explicit connection to each other. In order for the string to be completely translated in the resulting file, each permutation string should be authorized and translated.

Note that choiceformat is considered deprecated and pluralformat and selectformat are favored.

About Plural Format Strings

Smartling has general support for plural strings from various string and file formats. Review the documentation on plurals for more information about how plural strings are captured and managed as well as how they appear in the CAT tool for translators.

About Unsupported Strings

Some ICU MessageFormat strings are not supported. When an unsupported string is found in a file, rather than preventing the file from being processed at all, or skipping the string, which would prevent the translation of the entire file, Smartling will simply capture the string as raw text including all the ICU MessageFormat syntax. In this case, translators can provide a translation, but must properly include all the formatting syntax in the translation. Translators may need additional support and instruction for these strings. You can use, for example, the Smartling String Instruction features to help translators in this case.

Was this article helpful?