icu-at-d2l.md

ICU Message Syntax at D2L

At D2L, we use the ICU Message Syntax to help express the subtleties of spelling, grammar and conjugation inherent in each language.

The following sections describe the different features of ICU Message Syntax.

Basic Principles

In its simplest form, each message is a plain piece of text, like this:

Hello everyone

This can be translated in its entirety. Translated into French it would become:

Bonjour à tous

Simple Argument

To place a value inside the message, "arguments" are used. Arguments are enclosed in curly braces ({ and }).

Each argument has a unique key written in English. For example, if the original message was:

Hello {firstName}

Then the French translation would look like this:

Bonjour {firstName}

Note: the argument key (firstName in this example) should NOT be translated.

Messages can contain any number of arguments:

{firstName} must be at least {minimumLength} characters

{select} Format

The {select} format is used to choose between different outputs depending on the value of the argument.

For example, some users of our product may refer to units of learning as a "course", while others may call them a "class". The {select} format allows us to build customized messages for each option:

The {learningUnitType, select,
  courseType {course}
  classType {class}
} has been created successfully.

In this example, there are two possible choices for the learningUnitType argument: courseType, and classType. The final message will be either "The course has been created successfully." or "The class has been created successfully."

Note: the argument key (learningUnitType), select keyword and the possible values (courseType, and classType) should NOT be translated.

The {select} format becomes very powerful for languages where the context around the argument may need to change depending on the value of the argument. For example, in French the word "course" is masculine and "class" is feminine. As a result, more of the message moves into the individual options:

{learningUnitType, select,
  courseType {Le cours a été créé}
  classType {La classe a été créée}
} avec succès.

The final message will be either "Le cours a été créé avec succès." or "La classe a été créée avec succès."

{plural} Format

The {plural} format is a more specialized version of the {select} format for numbers, and is used to choose output based on the pluralization rules of the language.

The match is a literal value and is matched to one of these plural categories. Not all languages need to use all plural categories.

• zero: This category is used for languages that have grammar specialized specifically for zero number of items. (Examples are Arabic and Latvian.)
• one: This category is used for languages that have grammar specialized specifically for one item. Many languages, but not all, use this plural category. (Many Asian languages, such as Chinese and Japanese, do not use this category.)
• two: This category is used for languages that have grammar specialized specifically for two items. (Examples are Arabic and Welsh.)
• few: This category is used for languages that have grammar specialized specifically for a small number of items. For some languages this is used for 2-4 items, for some 3-10 items, and other languages have even more complex rules.
• many: This category is used for languages that have grammar specialized specifically for a larger number of items. (Examples are Arabic, Polish, and Russian.)
• other: This category is used if the value doesn't match one of the other plural categories. Note that this is used for "plural" for languages (such as English) that have a simple "singular" versus "plural" dichotomy.
• =value: This is used to match a specific value regardless of the plural categories of the current locale.

For example, if we wanted to show the number of messages to a user:

You have {messageCount, plural,
    =0 {no messages}
    one {1 message}
    other {{messageCount} messages}
}.

In French this could be translated as:

Vous {messageCount, plural,
    =0 {n'avez pas de messages}
    one {avez 1 message}
    other {avez {messageCount} messages}
}.

Note: the other option is required.