ICU syntax crash course
This library analyzes and compiles the translations authored in the ICU message syntax. While the ICU message syntax is an independent project this is an accelerated course on why it's good and how to use the main features.
Why use the ICU message syntax?
Internationalizing apps is a whole lot more than just mapping some keys to the appropriate translated string in a dictionary. Properly internationalized apps must handle all aspects of translation, including the way dates and times are formatted, what delimiters are used in numbers to separate the thousands or the decimals, currencies and support gendered languages.
Even something as simple as plurals can get very complex depending on the language. English, German and Spanish have singular and plural, but some slavic languages have 3, and other languages like Arabic have 6 depending on the number of items being pluralized. Sometimes the threshold where we have to change from one plural form to the next varies depending on the regional variant.
English doesn't have many gendered words but French or Italian do, and the adjectives must match the noun's gender. Formatting
123456789 in the US english variant will result in
123,456,789 but in the Indian variant will be
Formatting currencies the $ symbol goes before the amount, but the € goes after.
The ICU syntax abstracts all this complexity from the developers and gives the real professional translators a meta language expressive enough to handle all the subtleties on they side.
ICU messages support interpolating values, which will be properly sanitized so passing
undefined will not interpolate as "undefined".
||Your favorite color is orange|
The second most used feature in any app is pluralization. The ICU syntax has a dedicated
plural helper to define plural translations that from very simple to quite complicated, all within the translation itself.
- one (singular)
- two (dual)
- few (paucal)
- many (Also used for fractions)
- other (general plural form. The one used on languages with only one plural)
||Your have 0 cats|
||Your have no cats at all|
||Mary does not give a party.|
Some languages like English only leverage
other but others will be able to use the best plural form. The particular threshold value that divides
many is heavily cultural.
You can also specify translations for exact values using
=N. When a number is specified that way that translation will supersede the language's default behavior.
For instance, in english you could use
=12 to have different translations specifically for a couple and a dozen instead of using the generic plural.
Lastly, plurals can also make us of the hashtag to print as number the value being used in the plural, and optionally the helper can receive an offset that will be substracted to the value in the hashtag.
select helper is used to choose among several translation paths depending on an argument.
While it has many possible uses the most common one is for having gendered translations.
||Your son has won an award|
The default format are:
short: The most compact date representation
medium: Abbreviated textual representation
long: Long textual representation
full: The most verbose and complete date
||Your next holidays start on Thursday, August 11, 2022|
Just like the date helpers but for formatting only the time part of a date.
||Your doctor's appointment is today at 2:23 AM|
Formats a number according to the rules of the current locale.
||Your account balance is 0|
There's also an advanced feature called Number Skeletons that allow you to customize to great lengths how you want your numbers formatted.
||Your account balance is €0.00|
||Your account balance is +€0.00|
||Game progress 0%|
||Game progress 0.00%|
||Game progress 0.00%|
||Your destination is 0 m away|
||Your destination is 0 meters away|
||Are you sure you want to bid 5K over asking?|
||Are you sure you want to bid 5 thousand over asking?|
||The chances of winning the lottery are 1 in 1.235E8|
The possibilities of number skeletons are limitless.