JSDoc: Class: MessageFormat

# 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:
  - messageformat.js, line 51

### Namespaces

formatters

### Members

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

Pluralization functions from make-plural

##### Type:

- Object.<string, function()>

Source:
  - messageformat.js, line 89

### 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 result of `compile()` may be serialized using its `toString()` method, including all required runtime function definitions. 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:
  - messageformat.js, line 499

##### Returns:

The first match found for the given locale(s)

Type
  function

##### Examples

    var mf = new MessageFormat('en');
    var cf = mf.compile('A {TYPE} example.');

    cf({ TYPE: 'simple' })
    // 'A simple example.'

    cf.toString()
    // 'function (d) { return "A " + d.TYPE + " example."; }'

    var fs = require('fs');
    var mf = new MessageFormat('en');
    var msgSet = {
      a: 'A {TYPE} example.',
      b: 'This has {COUNT, plural, one{one member} other{# members}}.'
    };
    var cfSet = mf.compile(msgSet, { global: 'module.exports' });
    var str = cfSet.toString().replace(/^[^{]*{/, '').replace(/}\s*$/, '').trim();
    fs.writeFileSync('messages.js', str);
    ...
    var messages = require('./messages');

    messages.a({ TYPE: 'more complex' })
    // 'A more complex example.'

    messages.b({ COUNT: 2 })
    // 'This has 2 members.'

    var mf = new MessageFormat('en');
    mf.runtime.pluralFuncs.fi = MessageFormat.plurals.fi;
    mf.compile({
      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.' }
    }, {
      locale: { en: 'en', fi: 'fi' },
      global: 'i18n'
    })(this);

    i18n.en.b({ COUNT: 3 })
    // 'This is the 3rd example.'

    i18n.fi.b({ COUNT: 3 })
    // 'Tämä on 3. esimerkki.'

#### setBiDiSupport(enableopt) → {MessageFormat}

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:
  - messageformat.js, line 174
See:
  - http://cldr.unicode.org/development/development-process/design-proposals/bidi-handling-of-structured-text

##### Returns:

The MessageFormat instance, to allow for chaining

Type
  MessageFormat

##### Example

    // upper case stands for RTL characters, output is shown as rendered
    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) → {MessageFormat}

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:
  - messageformat.js, line 199
See:
  - MessageFormat.formatters

##### Returns:

The MessageFormat instance, to allow for chaining

Type
  MessageFormat

##### Example

    // Intl is not defined in default Node until 0.11.15 / 0.12.0
    var Intl = require('intl');
    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.'