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. This parser's implementation was inspired by and derived from Alex Sexton's messageformat.js project. The differences from Alex's implementation are:

• This project is standalone.
• It's authored as ES6 modules compiled to CommonJS and the Bundle format for the browser.
• The produced AST is more descriptive and uses recursive structures.
• The keywords used in the AST match the ICU Message "spec".

Usage

Loading in the Browser

The dist/ folder contains the version of this package for use in the browser, and it can be loaded and used like this:

<script src="intl-messageformat-parser/dist/parser.min.js"></script>
<script>
  IntlMessageFormatParser.parse('...');
</script>

Loading in Node.js

This package can also be require()-ed in Node.js:

var parser = require('intl-messageformat-parser');
parser.parse('...');

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.
parser.parse(msg);

This parser will produce this AST:

{
  "type": "messageFormatPattern",
  "elements": [
    {
      "type": "messageTextElement",
      "value": "On "
    },
    {
      "type": "argumentElement",
      "id": "takenDate",
      "format": {
        "type": "dateFormat",
        "style": "short"
      }
    },
    {
      "type": "messageTextElement",
      "value": " "
    },
    {
      "type": "argumentElement",
      "id": "name",
      "format": null
    },
    {
      "type": "messageTextElement",
      "value": " took "
    },
    {
      "type": "argumentElement",
      "id": "numPhotos",
      "format": {
        "type": "pluralFormat",
        "offset": 0,
        "options": [
          {
            "type": "optionalFormatPattern",
            "selector": "=0",
            "value": {
              "type": "messageFormatPattern",
              "elements": [
                {
                  "type": "messageTextElement",
                  "value": "no photos."
                }
              ]
            }
          },
          {
            "type": "optionalFormatPattern",
            "selector": "=1",
            "value": {
              "type": "messageFormatPattern",
              "elements": [
                {
                  "type": "messageTextElement",
                  "value": "one photo."
                }
              ]
            }
          },
          {
            "type": "optionalFormatPattern",
            "selector": "other",
            "value": {
              "type": "messageFormatPattern",
              "elements": [
                {
                  "type": "messageTextElement",
                  "value": "# photos."
                }
              ]
            }
          }
        ]
      }
    }
  ]
}

License

This software is free to use under the Yahoo! Inc. BSD license. See the LICENSE file for license text and copyright information.