Intl MessageFormat Parser

Parses ICU Message strings into an AST via JavaScript.

npm Version Build Status Dependency Status

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:

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

Loading in Node.js

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

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

Example

Given an ICU Message string like this:

  1. On {takenDate, date, short} {name} took {numPhotos, plural,
  2.     =0 {no photos.}
  3.     =1 {one photo.}
  4.     other {# photos.}
  5. }
  1. // Assume `msg` is the string above.
  2. parser.parse(msg);

This parser will produce this AST:

  1. {
  2.     "type": "messageFormatPattern",
  3.     "elements": [
  4.         {
  5.             "type": "messageTextElement",
  6.             "value": "On "
  7.         },
  8.         {
  9.             "type": "argumentElement",
  10.             "id": "takenDate",
  11.             "format": {
  12.                 "type": "dateFormat",
  13.                 "style": "short"
  14.             }
  15.         },
  16.         {
  17.             "type": "messageTextElement",
  18.             "value": " "
  19.         },
  20.         {
  21.             "type": "argumentElement",
  22.             "id": "name",
  23.             "format": null
  24.         },
  25.         {
  26.             "type": "messageTextElement",
  27.             "value": " took "
  28.         },
  29.         {
  30.             "type": "argumentElement",
  31.             "id": "numPhotos",
  32.             "format": {
  33.                 "type": "pluralFormat",
  34.                 "offset": 0,
  35.                 "options": [
  36.                     {
  37.                         "type": "optionalFormatPattern",
  38.                         "selector": "=0",
  39.                         "value": {
  40.                             "type": "messageFormatPattern",
  41.                             "elements": [
  42.                                 {
  43.                                     "type": "messageTextElement",
  44.                                     "value": "no photos."
  45.                                 }
  46.                             ]
  47.                         }
  48.                     },
  49.                     {
  50.                         "type": "optionalFormatPattern",
  51.                         "selector": "=1",
  52.                         "value": {
  53.                             "type": "messageFormatPattern",
  54.                             "elements": [
  55.                                 {
  56.                                     "type": "messageTextElement",
  57.                                     "value": "one photo."
  58.                                 }
  59.                             ]
  60.                         }
  61.                     },
  62.                     {
  63.                         "type": "optionalFormatPattern",
  64.                         "selector": "other",
  65.                         "value": {
  66.                             "type": "messageFormatPattern",
  67.                             "elements": [
  68.                                 {
  69.                                     "type": "messageTextElement",
  70.                                     "value": "# photos."
  71.                                 }
  72.                             ]
  73.                         }
  74.                     }
  75.                 ]
  76.             }
  77.         }
  78.     ]
  79. }

License

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