Core FormatJS Intl

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

Installation

npm
yarn

npm i -S @formatjs/intl

yarn add @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)

createIntlCache

Creates a cache instance to be used globally across locales. This memoizes previously created Intl.* constructors for performance and is only an in-memory cache.

IntlShape

interface IntlConfig {
  locale: string
  timeZone?: string
  fallbackOnEmptyString?: boolean
  formats: CustomFormats
  messages: Record<string, string> | Record<string, MessageFormatElement[]>
  defaultLocale: string
  defaultRichTextElements?: Record<string, FormatXMLElementFn<React.ReactNode>>
  defaultFormats: CustomFormats
  onError(err: string): void
  onWarn(warning: 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>
  formatListToParts(values: Array<string | T>, opts?: FormatListOptions): Part[]
  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 embedded 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.

fallbackOnEmptyString

Defaults to true.

This boolean option can be useful if you want to intentionally provide empty values for certain locales via empty strings. When fallbackOnEmptyString is false, empty strings will be returned instead of triggering the fallback procedure. This behaviour can be leveraged to "skip" content in specific locales.

See this issue 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

intl.formatDate(Date.now(), {
  year: 'numeric',
  month: 'numeric',
  day: 'numeric',
})

Result

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

intl.formatTime(Date.now()) // "4:03 PM"

Result

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

intl.formatRelativeTime(0)

Result

Live Editor

intl.formatRelativeTime(-24, 'hour', {style: 'narrow'})

Result

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

intl.formatNumber(1000, {style: 'currency', currency: 'USD'})

Result

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

intl.formatNumber(1000, {
  style: 'unit',
  unit: 'kilobyte',
  unitDisplay: 'narrow',
})

Result

Live Editor

intl.formatNumber(1000, {
  unit: 'fahrenheit',
  unitDisplay: 'long',
  style: 'unit',
})

Result

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

intl.formatPlural(1)

Result

Live Editor

intl.formatPlural(3, {style: 'ordinal'})

Result

Live Editor

intl.formatPlural(4, {style: 'ordinal'})

Result

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

intl.formatList(['Me', 'myself', 'I'], {type: 'conjunction'})

Result

Live Editor

intl.formatList(['5 hours', '3 minutes'], {type: 'unit'})

Result

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 | Record<string, unknown>,
  options: FormatDisplayNameOptions
): string | undefined

Usage examples:

Live Editor

intl.formatDisplayName('zh-Hans-SG', {type: 'language'})

Result

Live Editor

// ISO-15924 four letters script code to localized display name
intl.formatDisplayName('Deva', {type: 'script'})

Result

Live Editor

// ISO-4217 currency code to localized display name
intl.formatDisplayName('CNY', {type: 'currency'})

Result

Live Editor

// ISO-3166 two letters region code to localized display name
intl.formatDisplayName('UN', {type: 'region'})

Result

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:

Lookup and format the translated message at id, passed to <IntlProvider>.
Fallback to formatting the defaultMessage.
Fallback to source of translated message at id.
Fallback to source of defaultMessage.
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.ReactNode[]

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

function () {
  const messages = defineMessages({
    greeting: {
      id: 'app.greeting',
      defaultMessage: 'Hello, {name}!',
      description: 'Greeting to welcome the user to the app',
    },
  })

  return intl.formatMessage(messages.greeting, {name: 'Eric'})
}

Result

with ReactElement

Live Editor

function () {
  const messages = defineMessages({
    greeting: {
      id: 'app.greeting',
      defaultMessage: 'Hello, {name}!',
      description: 'Greeting to welcome the user to the app',
    },
  })

  return intl.formatMessage(messages.greeting, {name: <b>Eric</b>})
}

Result

with rich text formatting

Live Editor

function () {
  const messages = defineMessages({
    greeting: {
      id: 'app.greeting',
      defaultMessage: 'Hello, <bold>{name}</bold>!',
      description: 'Greeting to welcome the user to the app',
    },
  })

  return intl.formatMessage(messages.greeting, {
    name: 'Eric',
    bold: str => <b>{str}</b>,
  })
}

Result

The message we defined using defineMessages to support extraction via babel-plugin-formatjs, 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 are exported by the @formatjs/intl package and are 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',
})

Installation​

The intl object​

createIntl​

createIntlCache​

IntlShape​

locale, formats, and messages​

defaultLocale and defaultFormats​

onError​

defaultRichTextElements​

fallbackOnEmptyString​

formatDate​

formatTime​

formatRelativeTime​

formatNumber​

formatPlural​

formatList​

formatDisplayName​

formatMessage​

Message Syntax​

Message Descriptor​

Message Formatting Fallbacks​

Usage​

defineMessages/defineMessage​

Installation

The `intl` object

createIntl

createIntlCache

IntlShape

locale, formats, and messages

defaultLocale and defaultFormats

onError

defaultRichTextElements

fallbackOnEmptyString

formatDate

formatTime

formatRelativeTime

formatNumber

formatPlural

formatList

formatDisplayName

formatMessage

Message Syntax

Message Descriptor

Message Formatting Fallbacks

Usage

defineMessages/defineMessage