1 | # Intl MessageFormat Parser
|
2 |
|
3 | Parses [ICU Message strings][icu] into an AST via JavaScript.
|
4 |
|
5 | [![npm Version](https://badgen.net/npm/v/intl-messageformat-parser)](https://www.npmjs.com/package/intl-messageformat-parser)
|
6 | [![size](https://badgen.net/bundlephobia/minzip/intl-messageformat-parser)](https://bundlephobia.com/result?p=intl-messageformat-parser)
|
7 |
|
8 | ## Overview
|
9 |
|
10 | This package implements a parser in JavaScript that parses the industry standard [ICU Message strings][icu] — used for internationalization — into an AST. The produced AST can then be used by a compiler, like [`intl-messageformat`][intl-mf], to produce localized formatted strings for display to users.
|
11 |
|
12 | This parser is written in [PEG.js][], a parser generator for JavaScript.
|
13 |
|
14 | ## Usage
|
15 |
|
16 | ### Loading in the Browser
|
17 |
|
18 | The `dist/` folder contains the version of this package for use in the browser, and it can be loaded and used like this:
|
19 |
|
20 | ```html
|
21 | <script src="intl-messageformat-parser/dist/parser.min.js"></script>
|
22 | <script>
|
23 | IntlMessageFormatParser.parse('...');
|
24 | </script>
|
25 | ```
|
26 |
|
27 | ### Loading in Node.js
|
28 |
|
29 | This package can also be `require()`-ed in Node.js:
|
30 |
|
31 | ```js
|
32 | var parser = require('intl-messageformat-parser');
|
33 | parser.parse('...');
|
34 | ```
|
35 |
|
36 | ### Example
|
37 |
|
38 | Given an ICU Message string like this:
|
39 |
|
40 | ```
|
41 | On {takenDate, date, short} {name} took {numPhotos, plural,
|
42 | =0 {no photos.}
|
43 | =1 {one photo.}
|
44 | other {# photos.}
|
45 | }
|
46 | ```
|
47 |
|
48 | ```js
|
49 | // Assume `msg` is the string above.
|
50 | parser.parse(msg);
|
51 | ```
|
52 |
|
53 | This parser will produce this AST:
|
54 |
|
55 | ```json
|
56 | [
|
57 | {
|
58 | "type": 0,
|
59 | "value": "On "
|
60 | },
|
61 | {
|
62 | "type": 3,
|
63 | "style": "short",
|
64 | "value": "takenDate"
|
65 | },
|
66 | {
|
67 | "type": 0,
|
68 | "value": " "
|
69 | },
|
70 | {
|
71 | "type": 1,
|
72 | "value": "name"
|
73 | },
|
74 | {
|
75 | "type": 0,
|
76 | "value": " took "
|
77 | },
|
78 | {
|
79 | "type": 6,
|
80 | "pluralType": "cardinal",
|
81 | "value": "numPhotos",
|
82 | "offset": 0,
|
83 | "options": [
|
84 | {
|
85 | "id": "=0",
|
86 | "value": [
|
87 | {
|
88 | "type": 0,
|
89 | "value": "no photos."
|
90 | }
|
91 | ]
|
92 | },
|
93 | {
|
94 | "id": "=1",
|
95 | "value": [
|
96 | {
|
97 | "type": 0,
|
98 | "value": "one photo."
|
99 | }
|
100 | ]
|
101 | },
|
102 | {
|
103 | "id": "other",
|
104 | "value": [
|
105 | {
|
106 | "type": 0,
|
107 | "value": "# photos."
|
108 | }
|
109 | ]
|
110 | }
|
111 | ]
|
112 | }
|
113 | ]
|
114 | ```
|
115 |
|
116 | ## Benchmarks
|
117 |
|
118 | ```
|
119 | complex_msg AST length 2053
|
120 | normal_msg AST length 410
|
121 | simple_msg AST length 79
|
122 | string_msg AST length 36
|
123 | complex_msg x 3,926 ops/sec ±2.37% (90 runs sampled)
|
124 | normal_msg x 27,641 ops/sec ±3.93% (86 runs sampled)
|
125 | simple_msg x 100,764 ops/sec ±5.35% (79 runs sampled)
|
126 | string_msg x 120,362 ops/sec ±7.11% (74 runs sampled)
|
127 | ```
|
128 |
|
129 | ## License
|
130 |
|
131 | This software is free to use under the Yahoo! Inc. BSD license.
|
132 | See the [LICENSE file][] for license text and copyright information.
|
133 |
|
134 | [icu]: http://userguide.icu-project.org/formatparse/messages
|
135 | [intl-mf]: https://github.com/formatjs/formatjs
|
136 | [peg.js]: https://pegjs.org/
|
137 | [license file]: https://github.com/formatjs/formatjs/blob/master/LICENSE.md
|