@jc21/messageformat-loader NPM

ICU MessageFormat loader for Webpack

Loader that parses input JSON & YAML objects of strings as objects of JavaScript message functions with a matching structure, using messageformat.

Installation

npm install messageformat messageformat-loader

Usage

For a working demo of the loader, run npm install in the example/ directory, and then open example/dist/index.html in a browser.

webpack.config.js

{
  test: /\bmessages\.(json|ya?ml)$/,
  type: 'javascript/auto', // required by Webpack 4
  loader: require.resolve('messageformat-loader'),
  options: {
    biDiSupport: false,
    convert: false,
    disablePluralKeyChecks: false,
    formatters: null,
    intlSupport: false,
    locale: ['en'],
    strictNumberSign: false
  }
}

If you’re using Webpack 4, you must include type: 'javascript/auto' in the loader configuration to properly parse JSON files.

Uses yaml to parse input, which allows for full JSON & YAML support. As a side effect, also supports #comments in JSON files.

The default option values are shown, and are not required. See below for more information on them. As Webpack v1 does not support loader options, you should instead pass the options as query parameters in that environment; locale will accept a comma-delimited set of values.

messages.json

{
  "simple-example": "A simple message.",
  "var-example": "Message with {X}.",
  "plural-example": "You have {N, plural, =0{no messages} one{1 message} other{# messages}}.",
  "select-example": "{GENDER, select, male{He has} female{She has} other{They have}} sent you a message.",
  "ordinal-example": "The {N, selectordinal, one{1st} two{2nd} few{3rd} other{#th}} message."
}

example.js

ES6, with configuration:

import messages from './messages.json';
messages['ordinal-example']({ N: 1 });
// => 'The 1st message.'

ES5, without configuration:

var messages = require('messageformat-loader?locale=en!./messages.json');
messages['ordinal-example']({ N: 1 });
// => 'The 1st message.'

Options

locale The CLDR language code or codes to pass to messageformat. If using multiple locales at the same time, exact matches to a locale code in the data structure keys will select that locale within it (as in example/src/messages.json). Defaults to en.
convert Use messageformat-convert to convert non-MessageFormat syntax and plural objects into MessageFormat. Use an object value to configure. Defaults to false.
disablePluralKeyChecks By default, messageformat.js throws an error when a statement uses a non-numerical key that will never be matched as a pluralization category for the current locale. Use this argument to disable the validation and allow unused plural keys. Defaults to false.
intlSupport Enable or disable support for the default formatters, which require the Intl object. Defaults to false.
biDiSupport Enable or disable the addition of Unicode control characters to all input to preserve the integrity of the output when mixing LTR and RTL text. Defaults to false.
formatters Add custom formatter functions to this MessageFormat instance.
strictNumberSign Follow the stricter ICU MessageFormat spec and throw a runtime error if # is used with non-numeric input. Defaults to false.