Core FormatJS Intl

This library contains core intl API that is used by react-intl.

Installation

npm i -S @formatjs/intl

The intl object

The core of @formatjs/intl is the intl object (of type IntlShape), which is the instance to store a cache of all Intl.* APIs, configurations, compiled messages and such. The lifecycle of the intl object is typically tied to the locale & the list of messages that it contains, which means when you switch locale, this object should be recreated.

tip

The intl object should be reused as much as possible for performance.

createIntl

This allows you to create an IntlShape object that contains all format* methods. For example:

import {createIntl, createIntlCache} from '@formatjs/intl'
// This is optional but highly recommended
// since it prevents memory leak
const cache = createIntlCache()
const intl = createIntl(
{
locale: 'fr-FR',
messages: {},
},
cache
)
// Call imperatively
intl.formatNumber(20)

IntlShape

interface IntlConfig {
locale: string
timeZone?: string
formats: CustomFormats
messages: Record<string, string> | Record<string, MessageFormatElement[]>
defaultLocale: string
defaultRichTextElements?: Record<string, FormatXMLElementFn<React.ReactNode>>
defaultFormats: CustomFormats
onError(err: string): void
}
interface IntlFormatters {
formatDate(value: number | Date | string, opts?: FormatDateOptions): string
formatTime(value: number | Date | string, opts?: FormatDateOptions): string
formatDateToParts(
value: number | Date | string,
opts?: FormatDateOptions
): Intl.DateTimeFormatPart[]
formatTimeToParts(
value: number | Date | string,
opts?: FormatDateOptions
): Intl.DateTimeFormatPart[]
formatRelativeTime(
value: number,
unit?: FormattableUnit,
opts?: FormatRelativeTimeOptions
): string
formatNumber(value: number, opts?: FormatNumberOptions): string
formatNumberToParts(
value: number,
opts?: FormatNumberOptions
): Intl.NumberFormatPart[]
formatPlural(
value: number | string,
opts?: FormatPluralOptions
): ReturnType<Intl.PluralRules['select']>
formatMessage(
descriptor: MessageDescriptor,
values?: Record<string, PrimitiveType | FormatXMLElementFn<string, string>>
): string
formatMessage(
descriptor: MessageDescriptor,
values?: Record<string, PrimitiveType | T | FormatXMLElementFn<T, R>>
): R
formatList(values: Array<string>, opts?: FormatListOptions): string
formatList(
values: Array<string | T>,
opts?: FormatListOptions
): T | string | Array<string | T>
formatDisplayName(
value: string,
opts?: FormatDisplayNameOptions
): string | undefined
}
type IntlShape = IntlConfig & IntlFormatters

The definition above shows what the intl object will look like. It's made up of two parts:

  • IntlConfig: The intl metadata passed as props into the parent <IntlProvider>.
  • IntlFormatters: The imperative formatting API described below.

locale, formats, and messages

The user's current locale and what the app should be rendered in. While defaultLocale and defaultFormats are for fallbacks or during development and represent the app's default. Notice how there is no defaultMessages, that's because each Message Descriptor provides a defaultMessage.

defaultLocale and defaultFormats

Default locale & formats for when a message is not translated (missing from messages). defaultLocale should be the locale that defaultMessages are declared in so that a sentence is coherent in a single locale. Without defaultLocale and/or if it's set incorrectly, you might run into scenario where a sentence is in English but embeded date/time is in Spanish.

onError

Allows the user to provide a custom error handler. By default, error messages are logged using console.error if NODE_ENV is not set to production.

defaultRichTextElements

A map of tag to rich text formatting function. This is meant to provide a centralized way to format common tags such as <b>, <p>... or enforcing certain Design System in the codebase (e.g standardized <a> or <button>...). See https://github.com/formatjs/formatjs/issues/1752 for more context.

formatDate

function formatDate(
value: number | Date,
options?: Intl.DateTimeFormatOptions & {format?: string}
): string

This function will return a formatted date string. It expects a value which can be parsed as a date (i.e., isFinite(new Date(value))), and accepts options that conform to DateTimeFormatOptions.

Live Editor
Result
9/20/2020

formatTime

function formatTime(
value: number | Date,
options?: Intl.DateTimeFormatOptions & {format?: string}
): string

This function will return a formatted date string, but it differs from formatDate by having the following default options:

{
hour: 'numeric',
minute: 'numeric',
}

It expects a value which can be parsed as a date (i.e., isFinite(new Date(value))), and accepts options that conform to DateTimeFormatOptions.

Live Editor
Result
SyntaxError: Unexpected token (1:49)
1 : return (intl.formatTime(Date.now()) // "4:03 PM")
                                                     ^

formatRelativeTime

browser support

This requires Intl.RelativeTimeFormat which has limited browser support. Please use our polyfill if you plan to support them.

type Unit =
| 'second'
| 'minute'
| 'hour'
| 'day'
| 'week'
| 'month'
| 'quarter'
| 'year'
type RelativeTimeFormatOptions = {
numeric?: 'always' | 'auto'
style?: 'long' | 'short' | 'narrow'
}
function formatRelativeTime(
value: number,
unit: Unit,
options?: Intl.RelativeTimeFormatOptions & {
format?: string
}
): string

This function will return a formatted relative time string (e.g., "1 hour ago"). It expects a value which is a number, a unit and options that conform to Intl.RelativeTimeFormatOptions.

Live Editor
Result
in 0 seconds
Live Editor
Result
24 hr. ago

formatNumber

This function uses Intl.NumberFormat options.

function formatNumber(
value: number,
options?: Intl.NumberFormatOptions & {format?: string}
): string

This function will return a formatted number string. It expects a value which can be parsed as a number, and accepts options that conform to NumberFormatOptions.

Live Editor
Result
$1,000.00

Formatting Number using unit

Currently this is part of ES2020 NumberFormat. We've provided a polyfill here and @formatjs/intl types allow users to pass in a sanctioned unit:

Live Editor
Result
1,000kB
Live Editor
Result
1,000 degrees Fahrenheit

formatPlural

type PluralFormatOptions = {
type?: 'cardinal' | 'ordinal' = 'cardinal'
}
function formatPlural(
value: number,
options?: Intl.PluralFormatOptions
): 'zero' | 'one' | 'two' | 'few' | 'many' | 'other'

This function will return a plural category string: "zero", "one", "two", "few", "many", or "other". It expects a value which can be parsed as a number, and accepts options that conform to PluralFormatOptions.

This is a low-level utility whose output could be provided to a switch statement to select a particular string to display.

Live Editor
Result
one
Live Editor
Result
other
Live Editor
Result
other
multiple language support

This function should only be used in apps that only need to support one language. If your app supports multiple languages use formatMessage instead.

formatList

browser support

This requires Intl.ListFormat which has limited browser support. Please use our polyfill if you plan to support them.

type ListFormatOptions = {
type?: 'disjunction' | 'conjunction' | 'unit'
style?: 'long' | 'short' | 'narrow'
}
function formatList(
elements: (string | React.ReactNode)[],
options?: Intl.ListFormatOptions
): string | React.ReactNode[]

This function allows you to join list of things together in an i18n-safe way. For example, when the locale is en:

Live Editor
Result
Me, myself, and I
Live Editor
Result
5 hours, 3 minutes

formatDisplayName

browser support

This requires Intl.DisplayNames which has limited browser support. Please use our polyfill if you plan to support them.

type FormatDisplayNameOptions = {
style?: 'narrow' | 'short' | 'long'
type?: 'language' | 'region' | 'script' | 'currency'
fallback?: 'code' | 'none'
}
function formatDisplayName(
value: string | number | object,
options?: FormatDisplayNameOptions
): string | undefined

Usage examples:

Live Editor
Result
Simplified Chinese (Singapore)
Live Editor
Result
Devanagari
Live Editor
Result
Chinese Yuan
Live Editor
Result
United Nations

formatMessage

Message Syntax

String/Message formatting is a paramount feature of React Intl and it builds on ICU Message Formatting by using the ICU Message Syntax. This message syntax allows for simple to complex messages to be defined, translated, and then formatted at runtime.

Simple Message:

Hello, {name}

Complex Message:

Hello, {name}, you have {itemCount, plural,
=0 {no items}
one {# item}
other {# items}
}.

See: The Message Syntax Guide.

Message Descriptor

React Intl has a Message Descriptor concept which is used to define your app's default messages/strings and is passed into formatMessage. The Message Descriptors work very well for providing the data necessary for having the strings/messages translated, and they contain the following properties:

  • id: A unique, stable identifier for the message
  • description: Context for the translator about how it's used in the UI
  • defaultMessage: The default message (probably in English)
type MessageDescriptor = {
id: string
defaultMessage?: string
description?: string | object
}
Extracting Message Descriptor

You can extract inline-declared messages from source files using our CLI.

Message Formatting Fallbacks

The message formatting APIs go the extra mile to provide fallbacks for the common situations where formatting fails; at the very least a non-empty string should always be returned. Here's the message formatting fallback algorithm:

  1. Lookup and format the translated message at id, passed to <IntlProvider>.
  2. Fallback to formatting the defaultMessage.
  3. Fallback to source of translated message at id.
  4. Fallback to source of defaultMessage.
  5. Fallback to the literal message id.

Above, "source" refers to using the template as is, without any substitutions made.

Usage

type MessageFormatPrimitiveValue = string | number | boolean | null | undefined
function formatMessage(
descriptor: MessageDescriptor,
values?: Record<string, MessageFormatPrimitiveValue>
): string
function formatMessage(
descriptor: MessageDescriptor,
values?: Record<
string,
MessageFormatPrimitiveValue | React.ReactElement | FormatXMLElementFn
>
): string | React.ReactNodeArray

This function will return a formatted message string. It expects a MessageDescriptor with at least an id property, and accepts a shallow values object which are used to fill placeholders in the message.

If a translated message with the id has been passed to the <IntlProvider> via its messages prop it will be formatted, otherwise it will fallback to formatting defaultMessage. See: Message Formatting Fallbacks for more details.

Live Editor
Result
Hello, Eric!

with ReactElement

Live Editor
Result
Hello, Eric!

with rich text formatting

Live Editor
Result
Hello, Eric!

The message we defined using defineMessages to support extraction via babel-plugin-react-intl, but it doesn't have to be if you're not using the Babel plugin.

simple message

Messages can be simple strings without placeholders, and that's the most common type of message.

defineMessages/defineMessage

interface MessageDescriptor {
id?: string
description?: string | object
defaultMessage?: string
}
function defineMessages(
messageDescriptors: Record<string, MessageDescriptor>
): Record<string, MessageDescriptor>
function defineMessage(messageDescriptor: MessageDescriptor): MessageDescriptor

These functions is exported by the @formatjs/intl package and is simply a hook for our CLI & babel/TS plugin to use when compiling default messages defined in JavaScript source files. This function simply returns the Message Descriptor map object that's passed-in.

import {defineMessages, defineMessage} from '@formatjs/intl'
const messages = defineMessages({
greeting: {
id: 'app.home.greeting',
description: 'Message to greet the user.',
defaultMessage: 'Hello, {name}!',
},
})
const msg = defineMessage({
id: 'single',
defaultMessage: 'single message',
description: 'header',
})