Back to top image

ICU MessageFormat

 

Smartling supports ICU MessageFormat with some limitations. ICU Message Format is supported in JSON, Java, Android XML, and YAML file formats, only. As the format is not fully supported, it could result in the creation of 2 different strings.

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'
  • plural strings with multiple plurals

If you are currently using MessageFormat or considering using it, it is always important to test as needed to confirm whether the translations are formatted correctly when used in your application.

i18next plural format is currently not supported. However, this has an ICU Message Format extension that works with Smartling's current ICU MessageFormat support.

Default Parsing

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 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 choice.
Not Supported:   
String with multiple plural arguments  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 in JSON, Java, Android XML, and YAML files. 

If ICU string formatting is used, then that takes precedence over HTML and any HTML directive will be ignored. Smartling, however, supports basic HTML parsing of the strings in the file even without any HTML directive. But without an HTML directive, it won't break down a large string value with HTML blocks into smaller strings. The block tags will be present but protected in the string, and the translators can manipulate them as needed.

JSON

Separate from specifying formatting, you can use translate_paths to target specific keys in your JSON file to control which values even get captured/formatted in the first place. See JSON for more details about Smartling directives.

Whether you translate all values (no paths specified) or only some values (translate_path specified) to parse the values that are captured using ICU MessageFormat you must use a Smartling directive.

If all the translatable values in your file should be treated as ICU MessageFormat strings the string_format directive with a value of icu either inline or via API) is easiest to use. 

If only some of the values in your file should be treated as ICU MessageFormat strings then you will need to use the string_format_paths directive either inline or via API to specify which values or paths to values should be ICU MessageFormat parsed. 

Directive  Value
string_format icu
string_format_paths

[*]

or

[*/uistring, */notification-string]

or

[messageformat/*, icu-format/*]

Example using the Smartling CLI tool  (string_format):

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

Example of inline integration (string_format):

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

Example of complex integration (string_format_paths):

In this example values with a parent name of "messageformat" or "printf" will all be captured as strings for translation in Smartling because of the translate_paths directive. Additional the values on the "/messageformat" path will be parsed as ICU MessageFormat strings. Lastly all strings will be parsed to handle C format placeholders. These probably shouldn't occur in the strings on the "/messageformat" path but do occur in the strings "/printf" path and so will be treated as placeholders accordingly. 

{
  "smartling": {
    "string_format_paths": "icu: [*/messageformat]",
      "translate_paths": [{
        "path": "*/messageformat",
        "key": "{*}/messageformat"
	},
      {
        "path": "*/printf",
        "key": "{*}/printf"
      }],
      "placeholder_format": "C"
    },
  "icuMessageFormatString_page_x_of_y": {
    "messageformat": "Page {X} of {Y}"
  },
  "printfString_page_x_of_y": {
    "printf": "Page %1$s of %2$s"
  },
  "icuMessageFormatString_pagesCount": {
    "messageformat": "You have {pagesCount, plural, one {# page.} other {# pages.}}"
  }
}

When using ICU MessageFormat, no other placeholder formats should need to be enabled for those strings (ICU MessageFormat specifies its own placeholder syntax). If you specify any placeholder (custom or named) and the string is ICU MessageFormat parsed that formats placeholder syntax takes precedence, but both syntaxes can apply to a single string.

 

YAML

To parse the strings using ICU MessageFormat, you can use two Smartling directives string_format with a value of icu

or the  string_format_paths with a value of icu and then specifying an array of the specific keys or paths. Smartling paths support simple wildcards.

YAML files support multiple inline directives that can change the behavior of strings that appear after each directive. This means you can selectively turn on/off behavior by adding string_format with ICU and NON value. Or by changing the format_paths from HTML to ICU MessageFormat. As noted, a string cannot be both HTML parsed and ICU MessageFormat parsed.

For more information, read our documentation on YAML.

Directive  Example Value
string_format

icu

or 

none
string_format_paths

[*]

or

[*/uistring, */notification-string]

or

[messageformat/*, icu-format/*]

Example of inline integration:

# smartling.string_format = ICU

# smartling.string_format_paths = icu: [messageformat/*]

 

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.

Choiceformat is considered deprecated and pluralformat and selectformat are favored.

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.

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.

Table of Contents