{"id":16084,"library":"icu-messageformat-parser","title":"ICU MessageFormat Parser","description":"icu-messageformat-parser is a JavaScript library that provides a PEG.js-based parser for ICU MessageFormat strings. It transforms a given MessageFormat string into an Abstract Syntax Tree (AST), enabling programmatic manipulation or interpretation of localized messages. The current stable version is 4.0.0. New major versions are released periodically to introduce breaking changes, often related to stricter conformance with the ICU MessageFormat specification, and to expand parsing capabilities. Key differentiators include its robust AST output, configurable strictness options (e.g., for number signs and function parameters), and its role as a fundamental parsing component for internationalization workflows involving MessageFormat, prioritizing accurate parsing according to Unicode CLDR and ICU standards.","status":"active","version":"2.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/messageformat/parser","tags":["javascript","icu","messageformat","parser"],"install":[{"cmd":"npm install icu-messageformat-parser","lang":"bash","label":"npm"},{"cmd":"yarn add icu-messageformat-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add icu-messageformat-parser","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The `parse` function is the primary export. Since v3.0.0, the package is primarily designed for ESM. Attempting `require()` in an ESM context will fail. Older documentation might show `require('messageformat-parser')`, but the correct package name is `icu-messageformat-parser`.","wrong":"const parse = require('icu-messageformat-parser').parse;\n// or\nconst parse = require('messageformat-parser').parse;","symbol":"parse","correct":"import { parse } from 'icu-messageformat-parser';"},{"note":"While explicit AST types are not directly shown in the README, if the package provides TypeScript definitions, common AST interfaces (e.g., `Ast`, `Argument`, `Plural` nodes) might be importable as types for enhanced type safety when working with the parsed output.","symbol":"AST Types","correct":"import type { Ast } from 'icu-messageformat-parser';"},{"note":"This package uses named exports. Attempting to import `parse` as a default export will result in `undefined` or a runtime error. The correct way is `import { parse } from '...'`. This entry serves as a common mistake pattern.","wrong":"import { parse } from 'icu-messageformat-parser';","symbol":"Default Export (hypothetical)","correct":"import parse from 'icu-messageformat-parser';"}],"quickstart":{"code":"import { parse } from 'icu-messageformat-parser';\n\n// Basic argument parsing\nconsole.log('Basic argument:', parse('So {wow}.'));\n// Expected output: [ 'So ', { type: 'argument', arg: 'wow' }, '.' ]\n\n// Complex selectordinal with octothorpe\nconst selectOrdinalAst = parse(\n  'Such { thing }. { count, selectordinal, one {First} two {Second}' +\n  '                  few {Third} other {#th} } word.'\n);\nconsole.log('Selectordinal AST:', selectOrdinalAst);\n\n// Nested select statements\nconst nestedSelectAst = parse(\n  'Many{type,select,plural{ numbers}selectordinal{ counting}' +\n  'select{ choices}other{ some {type}}}.'\n);\nconsole.log('Nested Select AST:', nestedSelectAst);\n\n// Example with options for plural key validation\nconst msg = '{words, plural, zero{No words} one{One word} other{# words}}';\nconst englishKeys = { cardinal: [ 'one', 'other' ], ordinal: [ 'one', 'two', 'few', 'other' ] };\n\nconsole.log('Parsed with default keys (zero is valid):', parse(msg));\n\ntry {\n  // This will throw an error because 'zero' is not in englishKeys.cardinal\n  parse(msg, englishKeys);\n} catch (error: any) {\n  console.error('Error during parsing with strict keys for plurals:', error.message);\n}\n\n// Example demonstrating the `strict` option (replaces `strictNumberSign` in v4+)\n// In strict mode, '#' is only special inside plural/selectordinal contexts.\nconst strictParse = parse('In plural, # is special. Outside, # is text.', { strict: true });\nconsole.log('Strict parsing of #:', strictParse);","lang":"typescript","description":"Demonstrates basic parsing, complex selectordinal statements, nested selects, and usage of options for plural key validation and strict mode for '#' parsing."},"warnings":[{"fix":"Replace backslash escapes with single quotes for literal text, e.g., `\\{` should become `'{'`. A codemod was provided with v3.0.0 to assist with this migration.","message":"Backslash (`\\`) escaping is no longer supported and will be parsed as literal text. This change was introduced to conform with the ICU MessageFormat standard.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Replace `{ strictNumberSign: true }` with `{ strict: true }` in your parser options. The `strict` option now encompasses more strict parsing behaviors.","message":"The `strictNumberSign` option has been replaced by a broader `strict` option.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Review code that processes function parameters from the AST, as their structure might have changed to accommodate nested MessageFormat elements. If you relied on parameters being simple strings, adjust your logic accordingly.","message":"Function parameters can now contain MessageFormat content, which changes how they are parsed and represented in the AST.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Ensure that the `options` object, specifically `options.cardinal` and `options.ordinal`, contains all plural and selectordinal keys expected for your target locales. To disable this validation, pass an empty array for these options.","message":"The `options` object for `cardinal` and `ordinal` rule keys validates plural and selectordinal keys. If a key used in the MessageFormat string is not present in the provided options (or the default CLDR keys if options are omitted), parsing will fail.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Be explicit about the `strictFunctionParams` option. If you expect an array of trimmed strings, ensure this option is `false` (default). If you need the raw parameter string, set it to `true` and handle parsing manually.","message":"The `strictFunctionParams` option significantly changes how function parameters are parsed. By default, parameters are split by commas and trimmed. With `strictFunctionParams: true`, parameters are treated as a single, untrimmed string.","severity":"gotcha","affected_versions":">=1.1.0"},{"fix":"Always use double apostrophes (`''`) for a literal apostrophe within quoted text. For literal text that contains curly braces or `#`, enclose it in single quotes, e.g., `'{literal text}'`.","message":"Apostrophe escaping follows `DOUBLE_OPTIONAL` mode. Single apostrophes only quote literal text if preceded by `{}` or `#` (inside `plural`/`selectordinal` and depending on `strict` option). Otherwise, they are literal apostrophes.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Review the MessageFormat string for common syntax errors like `{Such compliance` missing a closing brace or incorrect separator characters. Ensure all arguments and elements are correctly formatted according to the ICU MessageFormat specification.","cause":"The MessageFormat string contains a syntax error, such as an unclosed curly brace or incorrect argument format.","error":"SyntaxError: Expected \",\", \"}\" or [ \\t\\n\\r] but \"c\" found."},{"fix":"Check the `cardinal` and `ordinal` arrays in the parser `options` object. Ensure they contain all the plural rule keys used in your MessageFormat string for the target locale. If 'zero' is used but not listed in `options.cardinal`, it will cause this error.","cause":"A plural or selectordinal key (e.g., 'zero', 'one', 'few') used in the MessageFormat string is not present in the allowed keys specified in the parser options (or default CLDR keys).","error":"Error: Invalid key"},{"fix":"For versions 3.0.0 and above, use ES Module `import` syntax: `import { parse } from 'icu-messageformat-parser';`. If you are in a CommonJS environment, ensure your `package.json` does not have `\"type\": \"module\"` or configure your build system to correctly transpile.","cause":"Attempting to use CommonJS `require()` syntax in an ES Module context.","error":"ReferenceError: require is not defined"},{"fix":"Ensure you are using named import syntax: `import { parse } from 'icu-messageformat-parser';`. If using a bundler like Webpack or Rollup, verify its configuration for ES Module resolution and tree-shaking.","cause":"Attempting to import `parse` as a default export when it is a named export, or module resolution issues in bundlers.","error":"TypeError: (0 , icu_messageformat_parser__WEBPACK_IMPORTED_MODULE_0__.parse) is not a function"}],"ecosystem":"npm"}