Class: MessageFormat

MessageFormat

new MessageFormat(localeopt, pluralFuncopt, formattersopt)

Create a new message formatter

Parameters:
Name Type Attributes Default Description
locale string | Array.<string> <optional>
"en"

The locale to use, with fallbacks

pluralFunc function <optional>

Optional custom pluralization function

formatters Array.<function()> <optional>

Optional custom formatting functions

Source:

Namespaces

formatters
runtime

Members

(static) plurals :Object.<string, function()>

Pluralization functions from make-plural

Type:
  • Object.<string, function()>
Source:

Methods

compile(messages, optopt) → {function}

Compile messages into an executable function with clean string representation.

If messages is a single string including ICU MessageFormat declarations, opt is ignored and the returned function takes a single Object parameter d representing each of the input's defined variables. The returned function will be defined in a local scope that includes all the required runtime variables.

If messages is a map of keys to strings, or a map of namespace keys to such key/string maps, the returned function will fill the specified global with javascript functions matching the structure of the input. In such use, the output of compile() is expected to be serialized using .toString(), and will include definitions of the runtime functions. If opt.global is null, calling the output function will return the object itself.

Together, the input parameters should match the following patterns:

 messages = "string" || { key0: "string0", key1: "string1", ... } || {
   ns0: { key0: "string0", key1: "string1", ...  },
   ns1: { key0: "string0", key1: "string1", ...  },
   ...
 }

 opt = null || {
   locale: null || {
     ns0: "lc0" || [ "lc0", ... ],
     ns1: "lc1" || [ "lc1", ... ],
     ...
   },
   global: null || "module.exports" || "exports" || "i18n" || ...
 }
Parameters:
Name Type Attributes Default Description
messages string | Object

The input message(s) to be compiled, in ICU MessageFormat

opt Object <optional>
{}

Options controlling output for non-simple intput

Properties
Name Type Attributes Default Description
locale Object <optional>

The locales to use for the messages, with a structure matching that of messages

global string <optional>
""

The global variable that the output function should use, or a null string for none. "exports" and "module.exports" are recognised as special cases.

Source:
Returns:

The first match found for the given locale(s)

Type
function
Examples
> var MessageFormat = require('messageformat'),
...   mf = new MessageFormat('en'),
...   mfunc0 = mf.compile('A {TYPE} example.');
> mfunc0({TYPE:'simple'})
'A simple example.'
> mfunc0.toString()
'function (d) { return "A " + d.TYPE + " example."; }'

 
> var msgSet = { a: 'A {TYPE} example.',
...              b: 'This has {COUNT, plural, one{one member} other{# members}}.' },
...   mfuncSet = mf.compile(msgSet);
> mfuncSet().a({TYPE:'more complex'})
'A more complex example.'
> mfuncSet().b({COUNT:2})
'This has 2 members.'

> console.log(mfuncSet.toString())
function anonymous() {
var number = function (value, offset) {
  if (isNaN(value)) throw new Error("'" + value + "' isn't a number.");
  return value - (offset || 0);
};
var plural = function (value, offset, lcfunc, data, isOrdinal) {
  if ({}.hasOwnProperty.call(data, value)) return data[value]();
  if (offset) value -= offset;
  var key = lcfunc(value, isOrdinal);
  if (key in data) return data[key]();
  return data.other();
};
var select = function (value, data) {
  if ({}.hasOwnProperty.call(data, value)) return data[value]();
  return data.other()
};
var pluralFuncs = {
  en: function (n, ord) {
    var s = String(n).split('.'), v0 = !s[1], t0 = Number(s[0]) == n,
        n10 = t0 && s[0].slice(-1), n100 = t0 && s[0].slice(-2);
    if (ord) return (n10 == 1 && n100 != 11) ? 'one'
        : (n10 == 2 && n100 != 12) ? 'two'
        : (n10 == 3 && n100 != 13) ? 'few'
        : 'other';
    return (n == 1 && v0) ? 'one' : 'other';
  }
};
var fmt = {};

return {
  a: function(d) { return "A " + d.TYPE + " example."; },
  b: function(d) { return "This has " + plural(d.COUNT, 0, pluralFuncs.en, { one: function() { return "one member";}, other: function() { return number(d.COUNT)+" members";} }) + "."; }
}
}

 
> mf.runtime.pluralFuncs.fi = MessageFormat.plurals.fi;
> var multiSet = { en: { a: 'A {TYPE} example.',
...                      b: 'This is the {COUNT, selectordinal, one{#st} two{#nd} few{#rd} other{#th}} example.' },
...                fi: { a: '{TYPE} esimerkki.',
...                      b: 'Tämä on {COUNT, selectordinal, other{#.}} esimerkki.' } },
...   multiSetLocales = { en: 'en', fi: 'fi' },
...   mfuncSet = mf.compile(multiSet, { locale: multiSetLocales, global: 'i18n' });
> mfuncSet(this);
> i18n.en.b({COUNT:3})
'This is the 3rd example.'
> i18n.fi.b({COUNT:3})
'Tämä on 3. esimerkki.'

setBiDiSupport(enableopt) → {Object}

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.

Parameters:
Name Type Attributes Default Description
enable boolean <optional>
true
Source:
See:
Returns:

The MessageFormat instance, to allow for chaining

Type
Object
Example
// upper case stands for RTL characters, output is shown as rendered in browser
 > var MessageFormat = require('messageformat');
 > var mf = new MessageFormat('en');

 > mf.compile("{0} >> {1} >> {2}")(["first", "SECOND", "THIRD"]);
 // "first >> THIRD << SECOND"

 > mf.setBiDiSupport(true);
 > mf.compile("{0} >> {1} >> {2}")(["first", "SECOND", "THIRD"]);
 // "first >> SECOND >> THIRD"

setIntlSupport(enableopt) → {Object}

Enable or disable support for the default formatters, which require the Intl object. Note that this can't be autodetected, as the environment in which the formatted text is compiled into Javascript functions is not necessarily the same environment in which they will get executed.

Parameters:
Name Type Attributes Default Description
enable boolean <optional>
true
Source:
See:
Returns:

The MessageFormat instance, to allow for chaining

Type
Object
Example
> var Intl = require('intl');
 > var MessageFormat = require('messageformat');
 > var mf = (new MessageFormat('en')).setIntlSupport(true);
 > mf.currency = 'EUR';
 > mf.compile("The total is {V,number,currency}.")({V:5.5});
 "The total is €5.50."