intl-messageformat-parser

What is intl-messageformat-parser?

The intl-messageformat-parser package is a tool for parsing ICU MessageFormat strings into an Abstract Syntax Tree (AST). This is useful for internationalization (i18n) as it allows developers to handle complex message formatting in a structured way.

What are intl-messageformat-parser's main functionalities?

Parsing MessageFormat Strings

This feature allows you to parse a MessageFormat string into an AST. The AST can then be used for further processing or manipulation.

const { parse } = require('intl-messageformat-parser');
const message = 'Hello, {name}! You have {numMessages, plural, one {# message} other {# messages}}.';
const ast = parse(message);
console.log(JSON.stringify(ast, null, 2));

Handling Pluralization

This feature allows you to handle pluralization in messages. The parser can interpret plural rules and convert them into an AST.

const { parse } = require('intl-messageformat-parser');
const message = '{num, plural, one {# item} other {# items}}';
const ast = parse(message);
console.log(JSON.stringify(ast, null, 2));

Handling SelectFormat

This feature allows you to handle select format in messages. The parser can interpret select rules and convert them into an AST.

const { parse } = require('intl-messageformat-parser');
const message = '{gender, select, male {He} female {She} other {They}} will respond soon.';
const ast = parse(message);
console.log(JSON.stringify(ast, null, 2));

Other packages similar to intl-messageformat-parser

messageformat

The messageformat package provides similar functionality for handling ICU MessageFormat strings. It includes both a parser and a compiler, allowing you to parse MessageFormat strings and compile them into JavaScript functions. Compared to intl-messageformat-parser, it offers a more comprehensive solution by including both parsing and compiling capabilities.

format-message

The format-message package is another tool for handling ICU MessageFormat strings. It provides a simple API for formatting messages and supports interpolation, pluralization, and select format. While it does not provide a direct AST like intl-messageformat-parser, it offers a higher-level API for message formatting.

i18next

i18next is a full-featured internationalization framework for JavaScript. It supports various types of message formatting, including ICU MessageFormat. While it is more comprehensive and includes features like language detection and translation management, it may be overkill if you only need to parse MessageFormat strings.

README

Intl MessageFormat Parser

Parses ICU Message strings into an AST via JavaScript.

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.

This parser is written in PEG.js, a parser generator for JavaScript.

Usage

import {parse} from 'intl-messageformat-parser';
const ast = parse('this is {count, plural, one{# dog} other{# dogs}}');

Example

Given an ICU Message string like this:

On {takenDate, date, short} {name} took {numPhotos, plural,
    =0 {no photos.}
    =1 {one photo.}
    other {# photos.}
}

// Assume `msg` is the string above.
parse(msg);

This parser will produce this AST:

[
  {
    "type": 0,
    "value": "On "
  },
  {
    "type": 3,
    "style": "short",
    "value": "takenDate"
  },
  {
    "type": 0,
    "value": " "
  },
  {
    "type": 1,
    "value": "name"
  },
  {
    "type": 0,
    "value": " took "
  },
  {
    "type": 6,
    "pluralType": "cardinal",
    "value": "numPhotos",
    "offset": 0,
    "options": [
      {
        "id": "=0",
        "value": [
          {
            "type": 0,
            "value": "no photos."
          }
        ]
      },
      {
        "id": "=1",
        "value": [
          {
            "type": 0,
            "value": "one photo."
          }
        ]
      },
      {
        "id": "other",
        "value": [
          {
            "type": 0,
            "value": "# photos."
          }
        ]
      }
    ]
  }
]

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

Symbol	Meaning	Notes
G	Era designator
y	year
M	month in year
L	stand-alone month in year
d	day in month
E	day of week
e	local day of week	e..eee is not supported
c	stand-alone local day of week	c..ccc is not supported
a	AM/PM marker
h	Hour [1-12]
H	Hour [0-23]
K	Hour [0-11]
k	Hour [1-24]
m	Minute
s	Second
z	Time Zone

Benchmarks

complex_msg AST length 2053
normal_msg AST length 410
simple_msg AST length 79
string_msg AST length 36
complex_msg x 3,926 ops/sec ±2.37% (90 runs sampled)
normal_msg x 27,641 ops/sec ±3.93% (86 runs sampled)
simple_msg x 100,764 ops/sec ±5.35% (79 runs sampled)
string_msg x 120,362 ops/sec ±7.11% (74 runs sampled)