![format-message][logo]

> Internationalize text, numbers, and dates using ICU Message Format

[![npm Version][npm-image]][npm]
[![Build Status][build-image]][build]
[![JS Standard Style][style-image]][style]
[![MIT License][license-image]][LICENSE]

Quick Examples
--------------

npm install format-message --save

By default, the passed in string is parsed and formatted.

``js
var formatMessage = require('format-message')
var message = formatMessage('Hello { place }!', { place: 'World' })
`

You can pass an object to provide more information about a message.

`js
import formatMessage from 'format-message'

let message = formatMessage({
id: 'welcome_name', // optional, can be generated from default
default: 'Welcome, {name}!',
// optional description gives translators more context
description: 'Greeting at the top of the home page, showing the current user’s preferred name'
}, {
name: user.preferredName
})
`

Configure format-message to use translations, infer missing ids from the default message, report and replace missing translations, and add custom placeholder style formats.

`js
formatMessage.setup({
locale: 'es-ES', // what locale strings should be displayed
translations: require('./locales'), // object containing translations
generateId: require('format-message-generate-id/underscored_crc32'), // function to generate a missing id from the default message
missingReplacement: '!!NOT TRANSLATED!!', // use this when a translation is missing instead of the default message
missingTranslation: 'ignore', // don't console.warn or throw an error when a translation is missing
formats: {
number: { // add '{ amount, number, EUR }' format
EUR: { style: 'currency', currency: 'EUR' }
},
date: { // add '{ day, date, weekday }' format
weekday: { weekday: 'long' }
}
}
})
`

Formatting number, date, and time arguments relies on the ECMAScript Internationalization API (Intl). If you are in an environment missing this API ([like node <= 0.12, IE < 11, or Safari < 10][caniuse-intl]) you'll want to use a [polyfill][intl]. Otherwise an error will be thrown when trying to format these arguments.


Format 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]. There is a [guide for translators][icu-for-translators] you can send to your translators, and it's a nice primer for developers as well.

format-message provides a way to write your default (often English) message patterns as literals in your source, and then lookup translations at runtime. There are also tools to lint, extract, and inline translations.

This relies on [message-format][message-format] for parsing and formatting ICU messages.

$3

See [message-format][message-format] for supported ICU formats.

$3

See the [ICU site][icu-message] and [message-format][message-format] for details on how to escape special characters in your messages.

$3

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


API
---

$3

Translate and format the message with the given pattern and arguments. Literal arguments for pattern and locales are recommended so you can take advantage of linting, extraction, and inlining tools.

Parameters

- pattern is a string or object describing the message. A string value is equivalent to { default: value }.
- default is a properly formatted ICU Message Format pattern. A poorly formatted pattern will cause an Error to be thrown.
- This will be used directly if no translations are conifgured or if the translation is missing and no missingReplacement is configured.
- This is also used to generate an inferred id, if none is explicitly included.
- id is a string identifier for the message. This is used as a key to look up the translation from the configured translations. If none is specified, one is generated from the default pattern.
- description is a string providing additional context for this message. This has no runtime effect, but can be extracted along with the default message to be sent to translators.
- args is an object containing the values to replace placeholders with. Required if the pattern contains placeholders.
- locales is an optional string with a BCP 47 language tag, or an array of such strings.
- When specified, format-message will attempt to look up the translation for each language until one is found.
- When omitted the locale configured in setup() is used instead.

$3

Translate and format the message with the given pattern and arguments and return an array of message parts. If the pattern contains any html-like tags (go, , etc.) they are interpreted as placeholders expecting a function that will receive the children message parts as an array. Attributes are not supported for the placeholder tags and will throw a parse error.

Note that for React, and perhaps other libraries as well, elements in an array should have a key specified, or you will trigger warnings.

`jsx
formatMessage.rich("Click here", {
a: ({ children }) => {children}
})
// returns [ "Click ", here ]
`

Parameters

The same as formatMessage(pattern[, args[, locales]]).

$3

Configure formatMessage behavior for subsequent calls. This should be called before any code that uses formatMessage. Returns an object containing the current options.

Parameters

- options is an object containing the following config values:
- locale is the default locale to use when no locale is passed to formatMessage. Defaults to "en".
- translations is an object with locales as properties, each value is an object with message ids as properties. The value for each message id property is either the translated message pattern string, or an object with the message property containing the translated message pattern string.
- generateId(defaultPattern) is a function to generate an id from the default message pattern.
- defaultPattern is the default message pattern.
- This function must return a string id.
- The [format-message-generate-id][format-message-generate-id] module has a few functions you can use if you don't want to use your own.
- missingReplacement is a string or function that returns a string that will be used when a message translation isn't found. If a function, it will be called with (pattern, id, locale) parameters to get the replacement. If null or not specified, then the default message is used.
- missingTranslation is one of "ignore", "warning", "error". By default it is "warning", and missing translations cause a console warning. If "error", an error is thrown.
- formats is an object containing objects that define placeholder styles { name, type, style }:
- number is an object containing number format styles to add. Each property name can be used afterwards as a style name for a number placeholder. The value of each property is an object that will be passed to an [Intl.NumberFormat][mdn-intl-numberformat] constructor as the second argument.
- date is an object containing date format styles to add. Each property name can be used afterwards as a style name for a date placeholder. The value of each property is an object that will be passed to an [Intl.DateTimeFormat][mdn-intl-datetimeformat] constructor as the second argument.
- time is an object containing time format styles to add. Each property name can be used afterwards as a style name for a time placeholder. The value of each property is an object that will be passed to an [Intl.DateTimeFormat][mdn-intl-datetimeformat] constructor as the second argument.

$3

Return a new instance of formatMessage with isolated configuration. Calls to setup()
on the new namespace will not be affect any another namespace (including the global
namespace).

`js
var namespace = formatMessage.namespace()

formatMessage.setup({
locale: "en",
translations: {
en: {
foo: "foo"
}
}
})

namespace.setup({
locale: "fr",
transations: {
fr: {
foo: "bar"
}
}
})

formatMessage("foo") // => "foo"
namespace("foo") // => "bar"
`

If you are using a custom namespace and still want to be able to extract strings using the format message CLI, create a module named format-message.js that exports the new namespace. Import formatMessage from this module in all other modules that use the namespace.

$3

format-message also provides a few extra functions to simplify localizing (but not translating) data. These mostly just pass through to Intl APIs.

`js
import { number, date, time, select, plural, selectordinal } from 'format-message'
// or
var { number, date, time, select, plural, selectordinal } = require('format-message')
`

$3

Convert a number to a localized string.

Parameters

- value is the number to format.
- style is the optional string name of a style (decimal, integer, percent, etc). Defaults to 'decimal'.
- locale is the optional BCP 47 language tag. If not passed, the locale passed to setup() will be used.

$3

Convert a date to a localized date string.

Parameters

- value is the date to format.
- style is the optional string name of a style (short, medium, long, full, etc). Defaults to 'medium'.
- locale is the optional BCP 47 language tag. If not passed, the locale passed to setup() will be used.

$3

Convert a date to a localized time string.

Parameters

- value is the date to format.
- style is the optional string name of a style (short, medium, long, full, etc). Defaults to 'medium'.
- locale is the optional BCP 47 language tag. If not passed, the locale passed to setup() will be used.

$3

Select an option by exact text match. (This is not locale-specific.)

Parameters

- value is the string to match.
- options is an object whose keys are candidates for matching value. The value of the property with the matching key is returned, or the other property's value. The object should always have an other property.

$3

Select an option by matching plural rules. plural matches rules for cardinal numbers, and selectordinal matches rules for ordinal numbers. These function very similar to the parameters plural and selectordinal embedded in a message.

Parameters

- value is the number to match against plural rules.
- offset is an optional number subtracted from value before matching keyword plural rules. The offset is not applied when matching exact number options.
- options is an object whose keys are candidates for matching value. The value of the property with the matching key is returned, or the other property's value. The object should always have an other property. Keys should be either plural keywords (zero, one, two, few, many, other), or exact number matches (=13, =4, etc). Note that not all languages use all rules. For example English doesn't have a zero rule (0 falls under the other rule), but can still match =0.

$3

Deprecated: Use formatMessage.rich() instead.
This module includes utilities for working specifically with react when composing messages with embedded components.

$3

Applies a message to a map of React elements to produce a list of child nodes.

Parameters

- message is a pre-formatted string containing tokens marking the beginning and ending of nodes.
- elements is an object with keys matching tokens in the message, and values of React elements to put message parts in.

Example

`jsx
import formatMessage from 'format-message'
import {formatChildren} from 'format-message/react'

export default ({ extensions }) =>