Skip to content
Contact us
  • There are no suggestions because the search field is empty.

ICU support in Matecat

Matecat supports the ICU (International Components for Unicode) Message Format, a standardized syntax used to create dynamic and localized content.

The ICU Message Format allows translators and developers to handle language variations directly within a single string, ensuring that translations remain grammatically correct and contextually appropriate across languages.

With ICU Message Format, you can manage:

  • Plural forms
  • Ordinal numbers
  • Conditional text output (such as gender variations)

This format is widely used in multilingual applications and websites to ensure translations adapt correctly to different grammatical structures and language rules.

Matecat specifically supports the plural, selectordinal and select complex ICU arguments (aee below for more information).

Matecat’s detection of ICU syntax can be activated through the dedicated toggle in the Other tab of Matecat’s project creation settings.
When ICU syntax detection is activated:

  • Strings containing valid complex ICU arguments are never segmented.
  • Matecat performs ICU-specific QA checks on these strings (more details below).

Supported Complex Arguments

Plural (Cardinal Numbers)

The plural argument allows a message to change depending on the value of cardinal numbers (e.g. 1, 15, 100 etc.).

This ensures your translation remains grammatically correct, no matter what number is inserted into the sentence.

An example of a valid plural argument could be:
{itemCount, plural, one{He has one book} other{He has # books}}

In the example above, the # symbol acts as a placeholder that automatically displays the actual number. In your translations, you can use two different methods to display this value:

  • The # symbol: This is the standard ICU shorthand for the numeric value.

  • The variable name in curly brackets: For example, {itemCount}.

Both will result in the same final output (e.g., "He has 15 books").

Plural rules vary by language, Matecat follows the rules established in the latest CLDR version.
When you translate a plural argument, Matecat identifies the specific categories your target language requires and displays them in the ICU tab (details below).

All required plural forms must be included in the translation. If a form is missing, Matecat will flag it as a blocking issue to prevent errors in the final localized product.

Selectordinal (Ordinal Numbers)

The selectordinal argument is similar to the plural argument, but it is used for ordinal numbers (e.g. 1st, 2nd, 3rd, 4th etc.).

An example of a valid selectordinal argument could be:
{year, selectordinal, one {It's my cat's #st birthday!} two {It's my cat's #nd birthday!} few {It's my cat's #rd birthday!} other {It's my cat's #th birthday!}}

Just like with plurals, you can display the numeric value in your translation using:

  • The # symbol: The standard shorthand.
  • The variable name in curly brackets: For example, {year}.

Selectordinal rules vary by language, Matecat follows the rules established in the latest CLDR version.
When you translate a selectordinal argument, Matecat identifies the specific categories your target language requires and displays them in the ICU tab (details below).

All required selectordinal forms must be included in the translation. If a form is missing, Matecat will flag it as a blocking issue to prevent errors in the final localized product.

Select (Gender or Conditional Content)

The select argument is used when the text changes depending on a variable’s value (a specific word or category).
It is most commonly used to handle gender-based grammar variations.

An example of a valid select argument could be:
{gender, select, male{He uses Matecat} female{She uses Matecat} other{They use Matecat}}

In this case, the sentence will change based on the value of the gender variable.

The only rule for select arguments is that the other clause is always required.
Failure to include the other clause in the translation is flagged as a blocking issue by Matecat.

Nested ICU Arguments

ICU syntax allows you to nest arguments inside one another. This is useful when a sentence contains multiple dynamic values that each require different grammatical rules, such as a sentence that changes based on both gender and quantity.
Nesting can involve identical argument types or a mix of different types.

An example of a plural argument nested inside a select argument could be:
{gender, select, male} female} other}}

Tips for handling nested arguments:

  • Track your braces: Every opening bracket { must have a matching closing bracket }. Nested arguments often end with multiple brackets (e.g., }}}), and missing even one will cause a syntax error.
  • Use the ICU Tab: For complex nested strings, the ICU tab is highly recommended. It breaks the logic down into separate fields, so you don't have to manage the nested brackets manually in the main editor.
  • Check the Live Preview: Use the preview tool in the ICU tab to test different combinations of your variables (e.g., "female" + "plural") to ensure the sentence flows naturally in every scenario.

ICU Messages in Matecat’s Editor

When ICU detection is enabled, Matecat automatically identifies complex arguments. To help you translate effectively, several features are activated:

  • Syntax Highlighting: ICU code elements are highlighted in blue. These are functional parts of the segment and should not be translated.
  • Automatic QA: Matecat enables specific checks for ICU syntax and CLDR language rules.
  • The ICU Tab: A dedicated interface appears to help you manage complex logic without manual coding.

The ICU Tab

The ICU tab is designed to simplify the translation of complex arguments. It provides:

  • Plural & Ordinal Rules: It shows the specific rules for your target language, including descriptions and examples of when to use each form (e.g., one, few, many).
  • Interactive Testing: You can input different "Test values" for your variables to see how the sentence adapts.
  • Live Preview: This section shows the rendered output in real time, allowing you to verify that the grammar and flow are perfect before confirming the segment.

Syntax and QA Checks

To ensure the final product works correctly, Matecat runs automatic checks for both syntax errors (like missing brackets) and linguistic requirements (like missing plural forms).

If an issue is found:

  1. A Warning Message is displayed: You will see a clear notification of what is wrong.
  2. A Suggestion is provided: Whenever possible, Matecat will suggest a fix to help you correct the issue quickly.

These errors are flagged as a blocking issue by Matecat.