message-format

> Intl.MessageFormat prollyfill supporting ICU message format

[![npm Version][npm-image]][npm]
[![JS Standard Style][style-image]][style]

Quick Start
-----------

npm install message-format --save adds the library to node_modules. You can
then use it as follows:

``js
var MessageFormat = require('message-format');

var message = new MessageFormat('en-US', 'Hello { place }!');
var formatted = message.format({ place:'World' });
`

The library works great with tools like browserify and webpack for use in
front-end code. Also check out [format-message][format-message] for an
alternative API and inlining translations at build time.

Note: message-format relies on Intl.NumberFormat and Intl.DateTimeFormat
for formatting number, date, and time arguments. If you are in an
environment missing these (like node <= 0.12, IE < 11, or Safari < 10) you'll
need to use a [polyfill][intl]. If Intl formats are missing, an error occurs
when formatting these arguments.


Overview
--------

The [ICU Message Format][icu-message] is a great format for user-visible
strings, and includes simple placeholders, number and date placeholders, and
selecting among submessages for gender and plural arguments. The format is
used in apis in [C++][icu-cpp], [PHP][icu-php], and [Java][icu-java].

message-format is intended as a polyfill for the yet to be standardized
Intl.MessageFormat api. Since there is only a [strawman proposal][proposal]
at this point, this library represents only one possible way the standard api
could eventually work, hence "prollyfill".

$3

message-format supports plural rules for all CLDR languages. Locale-aware
formatting of number, date, and time are delegated to the Intl objects,
and select is the same across all locales. You don't need to load any extra
files for particular locales for message-format.

$3

* number - percent, currency
* date - short, medium, long, full
* time - short, medium, long, full
* plural
* selectordinal
* select

$3

ordinal, duration, and spellout arguments are supported by the parser,
but just act like number. These are not supported by Intl.NumberFormat.
They require a lot of language-specific code, and would make the library
undesireably large. For now, if you need these kinds of formats, you can pass
them into the message pre-formatted, and refence them in the message pattern
with a simple string placeholder ({ arg }).


API
---

$3

`js
var MessageFormat = require('message-format')
// or
import MessageFormat from 'message-format'

new MessageFormat(locales, pattern)
`

Construct a message format object

Parameters

- locales is a string with a BCP 47 language tag, or an array of such strings.
- pattern is a properly formatted ICU Message Format pattern. A poorly formatted pattern will cause an Error to be thrown.

$3

`js
message.format([args])
`

Format the message with the given arguments

Parameters

- args is an object containing the values to replace placeholders with. Required if the pattern contains placeholders.


Examples
--------

$3

`js
var message = new MessageFormat('en', 'Welcome back, {name}!');
message.format({ name:'Bob' }); // "Welcome back, Bob!"
message.format({ name:'Bill' }); // "Welcome back, Bill!"
`

$3

Escaping is a little weird in ICU Message Format.

1. '' is always '
2. ' begins an escaped string only if followed immediately by a syntax char ({}#)
3. ' ends an escaped string, unless it is doubled. See #1

The recommendation from ICU is to use the ASCII apostrophe (' U+0027) only
for escaping syntax characters, and use the pretty single quote (’ U+2019)
for actual apostrophes and single quotes in a message pattern.

`js
var message = new MessageFormat('en', 'This isn\'\'t a \'{simple}\' \'string\'');
message.format(); // "This isn't a {simple} 'string'"

// double quotes or backticks (ES6) make it a little easier to read
message = new MessageFormat("en", "This isn''t a '{simple}' 'string'");
message.format(); // "This isn't a {simple} 'string'"
`

$3

`js
var message = new MessageFormat('en', 'You took {n,number} pictures since {d,date} {d,time}');
message.format({ n:4000, d:new Date() }); // "You took 4,000 pictures since Jan 1, 2015 9:33:04 AM"

message = new MessageFormat('en', '{ n, number, percent }');
message.format({ n:0.1 }); // "10%"

message = new MessageFormat('en', '{ shorty, date, short }');
message.format({ shorty:new Date() }); // "1/1/15"
`

$3

`js
var message = new MessageFormat('en', '{ n, selectordinal,\
one {#st}\
two {#nd}\
few {#rd}\
other {#th}\
} place')
message.format({ n:102 }) // "102nd place"
`

$3

`js
import MessageFormat from 'message-format'

// using a template string for multiline, no interpolation
let message = new MessageFormat('en', On { date, date, short } {name} ate {
numBananas, plural,
=0 {no bananas}
=1 {a banana}
other {# bananas}
} {
gender, select,
male {at his house.}
female {at her house.}
other {at their house.}
})

message.format({
date: new Date(),
name: 'Curious George',
gender: 'male',
numBananas: 27
}) // "On 1/1/15 Curious George ate 27 bananas at his house."
``

License
-------

This software is free to use under the MIT license.
See the [LICENSE-MIT file][LICENSE] for license text and copyright information.

[npm]: https://www.npmjs.org/package/message-format
[npm-image]: https://img.shields.io/npm/v/message-format.svg
[style]: https://github.com/feross/standard
[style-image]: https://img.shields.io/badge/code%20style-standard-brightgreen.svg
[format-message]: https://github.com/format-message/format-message
[icu-message]: http://userguide.icu-project.org/formatparse/messages
[icu-cpp]: http://icu-project.org/apiref/icu4c/classicu_1_1MessageFormat.html
[icu-php]: http://php.net/manual/en/class.messageformatter.php
[icu-java]: http://icu-project.org/apiref/icu4j/
[proposal]: http://wiki.ecmascript.org/doku.php?id=globalization:messageformatting
[intl]: https://github.com/andyearnshaw/Intl.js
[LICENSE]: https://github.com/format-message/format-message/blob/master/LICENSE-MIT