format-message
message-format
Intl.MessageFormat prollyfill supporting ICU message format
Quick Start
npm install message-format --save adds the library to node_modules. You can
then use it as follows:
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 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. If Intl formats are missing, an error occurs
when formatting these arguments.
Overview
The ICU Message Format 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++, PHP, and Java.
message-format is intended as a polyfill for the yet to be standardized
Intl.MessageFormat api. Since there is only a strawman proposal
at this point, this library represents only one possible way the standard api
could eventually work, hence "prollyfill".
Loading locale data
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.
Supported ICU Formats
number-percent,currencydate-short,medium,long,fulltime-short,medium,long,fullpluralselectordinalselect
Unsupported ICU Formats
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
MessageFormat
var MessageFormat = require('message-format')
// or
import MessageFormat from 'message-format'
new MessageFormat(locales, pattern)Construct a message format object
Parameters
localesis a string with a BCP 47 language tag, or an array of such strings.patternis a properly formatted ICU Message Format pattern. A poorly formatted pattern will cause anErrorto be thrown.
MessageFormat instances
message.format([args])Format the message with the given arguments
Parameters
argsis an object containing the values to replace placeholders with. Required if the pattern contains placeholders.
Examples
Simple string placeholders
var message = new MessageFormat('en', 'Welcome back, {name}!');
message.format({ name:'Bob' }); // "Welcome back, Bob!"
message.format({ name:'Bill' }); // "Welcome back, Bill!"Quote escaping rules
Escaping is a little weird in ICU Message Format.
''is always''begins an escaped string only if followed immediately by a syntax char ({}#)'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.
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'"number, date, and time placeholders
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"selectordinal
var message = new MessageFormat('en', '{ n, selectordinal,\
one {#st}\
two {#nd}\
few {#rd}\
other {#th}\
} place')
message.format({ n:102 }) // "102nd place"Complex string with select and plural in ES6
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 for license text and copyright information.