Skip to main content

ICU MessageFormat Parser

Parses ICU Message strings into an AST via JavaScript.

npm Version size

Overview#

This package implements a parser in JavaScript that parses the industry standard ICU Message strings — used for internationalization — into an AST. The produced AST can then be used by a compiler, like intl-messageformat, to produce localized formatted strings for display to users.

Usage#

import {parse} from '@formatjs/icu-messageformat-parser'
const ast = parse(`this is {count, plural,
one{# dog}
other{# dogs}
}`)

Example#

Live Editor
Result
[
  {
    "type": 0,
    "value": "On "
  },
  {
    "type": 3,
    "value": "takenDate",
    "style": "short"
  },
  {
    "type": 0,
    "value": " "
  },
  {
    "type": 8,
    "value": "bold",
    "children": [
      {
        "type": 1,
        "value": "name"
      }
    ]
  },
  {
    "type": 0,
    "value": " took "
  },
  {
    "type": 6,
    "value": "numPhotos",
    "options": {
      "=0": {
        "value": [
          {
            "type": 0,
            "value": "no photos."
          }
        ]
      },
      "=1": {
        "value": [
          {
            "type": 0,
            "value": "one photo."
          }
        ]
      },
      "other": {
        "value": [
          {
            "type": 7
          },
          {
            "type": 0,
            "value": " photos."
          }
        ]
      }
    },
    "offset": 0,
    "pluralType": "cardinal"
  }
]

Supported DateTime Skeleton#

ICU provides a wide array of pattern to customize date time format. However, not all of them are available via ECMA402's Intl API. Therefore, our parser only support the following patterns

SymbolMeaningNotes
GEra designator
yyear
Mmonth in year
Lstand-alone month in year
dday in month
Eday of week
elocal day of weeke..eee is not supported
cstand-alone local day of weekc..ccc is not supported
aAM/PM marker
hHour [1-12]
HHour [0-23]
KHour [0-11]
kHour [1-24]
mMinute
sSecond
zTime Zone

Benchmarks#

complex_msg AST length 10861
normal_msg AST length 1665
simple_msg AST length 364
string_msg AST length 131
complex_msg x 29,940 ops/sec ±1.23% (89 runs sampled)
normal_msg x 253,612 ops/sec ±1.01% (92 runs sampled)
simple_msg x 1,805,642 ops/sec ±0.70% (94 runs sampled)
string_msg x 2,694,133 ops/sec ±1.05% (95 runs sampled)