ICU Message Syntax Reference

ICU MessageFormat Syntax Reference

This is a comprehensive quick-reference for the ICU MessageFormat syntax used in internationalization libraries like FormatJS, react-intl, vue-i18n, and Angular i18n.

Grammar Overview

message     = (text | argument)*
argument    = '{' argName (',' argType (',' argStyle)?)? '}'
argName     = identifier
argType     = 'number' | 'date' | 'time' | 'plural' | 'select' | 'selectordinal'
argStyle    = styleKeyword | pattern

Simple Arguments

Pattern	Input	Output
Hello, {name}	name="World"	Hello, World
{a} + {b} = {c}	a=1, b=2, c=3	1 + 2 = 3

Number Formatting

Pattern	Input (en-US)	Output
{n, number}	1234.5	1,234.5
{n, number, integer}	1234.5	1,235
{n, number, currency}	42.5	$42.50
{n, number, percent}	0.25	25%

Date Formatting

Pattern	Style	Example (en-US)
{d, date, short}	short	1/15/24
{d, date, medium}	medium	Jan 15, 2024
{d, date, long}	long	January 15, 2024
{d, date, full}	full	Monday, January 15, 2024

Time Formatting

Pattern	Style	Example (en-US)
{t, time, short}	short	3:30 PM
{t, time, medium}	medium	3:30:00 PM
{t, time, long}	long	3:30:00 PM EST

Plural

{count, plural,
    =0 {No items}
    one {# item}
    other {# items}
}

Plural categories: zero, one, two, few, many, other

Select

{gender, select,
    male {He}
    female {She}
    other {They}
}

Selectordinal

{pos, selectordinal,
    one {#st}
    two {#nd}
    few {#rd}
    other {#th}
}

Escape Sequences

Sequence	Output
''	Literal single quote '
'{'	Literal left brace {
'}'	Literal right brace }
'any text'	Text between quotes is not parsed

Nesting Rules

Arguments can be nested inside plural, select, and selectordinal cases:

{gender, select,
    male {He bought {count, plural, one {# item} other {# items}}}
    other {They bought {count, plural, one {# item} other {# items}}}
}

Nesting depth is unlimited, but deeper nesting makes messages harder to translate. Keep nesting to two levels maximum when possible.