React Intl React logo

React Components for internationalization.

npm install react-intl

This library provides React Components and a Mixin to format data and strings, and internationalize your React app.

Features

Components

The React Intl Components provide a way to declaratively format data and message strings. Using the Components is the recommended way to use React Intl.

Intl Mixin

React Intl also provides a React Component Mixin to aid with managing the i18n data within your app's hierarchy of React Components. All of the React Intl Components use this Mixin, and it's recommended that you add this Mixin to your app's root Component.

The Intl Mixin will automatically propagate the following props throughout your app's Component hierarchy:

The Intl Mixin also has the follow convenience methods:

How It Works

Create a React Component using IntlMixin and <FormattedNumber>

var IntlMixin       = ReactIntl.IntlMixin;
var FormattedNumber = ReactIntl.FormattedNumber;

var App = React.createClass({
    mixins: [IntlMixin],

    render: function () {
        return (
            <p>
                <FormattedNumber value={1000} style="currency" currency="USD" />
            </p>
        );
    }
});

Render the Component

When the <App> component is rendered a value for locales is passed. The IntlMixin will make sure to propagate this value to the nested <FormattedNumber> component so it renders the number in the correct locale.

React.render(
    <App locales={['en-US']} />,
    document.getElementById('example')
);

Rendered

$1,000.00

Usage

Browser

Load the Scripts onto the Page

<script src="react/dist/react.min.js"></script>
<script src="react-intl/dist/react-intl.min.js"></script>

By default, react-intl ships with the locale data for English built-in to the library's runtime. When you need to format data in another locale, include its data; e.g., for French:

<script src="react-intl/dist/locale-data/fr.js"></script>

All 150+ languages supported by this library use their root BCP 47 language tag; i.e., the part before the first hyphen (if any).

Note: Older browsers and Safari do not have the built-in Intl APIs (ECMA-402). Read more on how to patch the browser runtime using a polyfill.

Node/CommonJS

Require the Module

var React     = require('react');
var ReactIntl = require('react-intl');

In Node.js, the data for all 150+ languages is pre-loaded and does not need to be loaded manually.

Note: Node.js <= 0.10 doesn't have the built-in Intl APIs (ECMA-402). Node.js 0.12 does, but the default build/distribution only supports English. Read more on how to patch Node.js using a polyfill.

Format Numbers with Separators

The <FormattedNumber> Component is used to represent a number in a way appropriate for the current locale. It formats numbers using Intl.NumberFormat. The number to format is passed via the value prop.

var IntlMixin       = ReactIntl.IntlMixin;
var FormattedNumber = ReactIntl.FormattedNumber;

var Component = React.createClass({
    mixins: [IntlMixin],

    render: function () {
        return (
            <ul>
                <li><FormattedNumber value={4200} /></li>
                <li><FormattedNumber value={0.9} style="percent" /></li>
                <li>
                    <FormattedNumber
                        value={99.95}
                        style="currency"
                        currency="USD" />
                </li>
            </ul>
        );
    }
});

Rendered

  • 4 200
  • 90 %
  • 99,95 US$

Using Named Number Formats

Specifying format options (e.g.: style="currency" currency="USD") in every use of <FormattedNumber> can become a problem in large code bases, and isn't DRY. Instead, you can provide named number formats on the formats component prop. The IntlMixin automatically propagates the formats prop value through the component hierarchy.

var IntlMixin       = ReactIntl.IntlMixin;
var FormattedNumber = ReactIntl.FormattedNumber;

var Component = React.createClass({
    mixins: [IntlMixin],

    render: function () {
        return (
            <ul>
                <li><FormattedNumber value={42000} /></li>
                <li><FormattedNumber value={0.9} format="percentage" /></li>
                <li><FormattedNumber value={99.95} format="USD" /></li>
            </ul>
        );
    }
});

Rendered

  • 42 000
  • 90 %
  • 99,95 US$

In the example above, "USD" and "percentage" are names of number formats defined in the formats.number component prop. Check the RENDER tab to see the details.

See the custom formats section for more information.

Format Dates and Times Correctly

The <FormattedDate> Component is used to represent a date in a way appropriate for the current locale. It formats dates using Intl.DateTimeFormat. The date to format is passed via the value prop.

var IntlMixin     = ReactIntl.IntlMixin;
var FormattedDate = ReactIntl.FormattedDate;

var Component = React.createClass({
    mixins: [IntlMixin],

    render: function () {
        return (
            <p>
                <FormattedDate
                    value={new Date()}
                    day="numeric"
                    month="long"
                    year="numeric" />
            </p>
        );
    }
});

Rendered

23. ledna. 2017

Using Named Date Formats

Specifying format options (e.g.: day="numeric" month="long" year="numeric") in every use of <FormattedDate> can become a problem in large code bases, and isn't DRY. Instead, you can provide named date formats on the formats component prop. The IntlMixin automatically propagates the formats prop value through the component hierarchy.

var IntlMixin     = ReactIntl.IntlMixin;
var FormattedDate = ReactIntl.FormattedDate;

var Component = React.createClass({
    mixins: [IntlMixin],

    render: function () {
        return (
            <p>
                <FormattedDate value={new Date()} format="short" />
            </p>
        );
    }
});

Rendered

23. ledna. 2017

In the example above, "short" is the name of a custom date format defined in the formats.date component property. Check the RENDER tab to see the details.

See the custom formats section for more information.

Using Named Time Formats

The <FormattedTime> Component is just like the <FormattedDate> component, except it will reference any named formats from the formats.time component prop.

Format Dates Relative To "now"

The <FormattedRelative> Component is used to represent a relative time in a way appropriate for the current locale. It formats the relative time following the rules from Unicode CLDR. The date to format is passed via the value prop.

var IntlMixin         = ReactIntl.IntlMixin;
var FormattedRelative = ReactIntl.FormattedRelative;

var Component = React.createClass({
    mixins: [IntlMixin],

    render: function () {
        var postDate    = Date.now() - (1000 * 60 * 60 * 24);
        var commentDate = Date.now() - (1000 * 60 * 60 * 2);
        var meetingDate = Date.now() + (1000 * 60 * 51);

        return (
            <ul>
                <li><FormattedRelative value={postDate} /></li>
                <li><FormattedRelative value={commentDate} /></li>
                <li><FormattedRelative value={meetingDate} /></li>
            </ul>
        );
    }
});

Rendered

  • včera
  • před 2 hodinami
  • za 1 hodinu

Using Specific Relative Units

By default, the relative time is formatted using the best fit unit of time. However, you can explicitly set the units prop to one of the following values:
"second", "minute", "hour", "day", "month" or "year".

var IntlMixin         = ReactIntl.IntlMixin;
var FormattedRelative = ReactIntl.FormattedRelative;

var Component = React.createClass({
    mixins: [IntlMixin],

    render: function () {
        var postDate = Date.now() - (1000 * 60 * 60 * 22);
        var lastTrip = Date.now() - (1000 * 60 * 60 * 24 * 70);

        return (
            <div>
                <p>
                    <b><FormattedRelative value={postDate} /></b>
                    <i>(best fit)</i><br/>

                    <b><FormattedRelative value={postDate} units="minute" /></b>
                    <i>(in minutes)</i>
                </p>
                <p>
                    <b><FormattedRelative value={lastTrip} /></b>
                    <i>(best fit)</i><br/>

                    <b><FormattedRelative value={lastTrip} units="day" /></b>
                    <i>(in days)</i>
                </p>
            </div>
        );
    }
});

Rendered

včera(best fit)
před 1 320 minutami(in minutes)

před 2 měsíci(best fit)
před 70 dny(in days)

Using Specific Relative Styles

The style prop provides another level of customization. By default, the relative time is computed with a "best fit" style, which means, for example, that instead of "1 day ago", it will display "yesterday", or "in 1 year" will be "next year", etc. The other style is "numeric", in which the output will always contain a number.

var IntlMixin         = ReactIntl.IntlMixin;
var FormattedRelative = ReactIntl.FormattedRelative;

var Component = React.createClass({
    mixins: [IntlMixin],

    render: function () {
        var postDate = Date.now() - (1000 * 60 * 60 * 24);
        var lastTrip = Date.now() - (1000 * 60 * 60 * 24 * 380);

        return (
            <div>
                <p>
                    <b><FormattedRelative value={postDate} /></b>
                    <i>(best fit)</i><br/>

                    <b><FormattedRelative value={postDate} style="numeric" /></b>
                    <i>(numeric)</i>
                </p>
                <p>
                    <b><FormattedRelative value={lastTrip} /></b>
                    <i>(best fit)</i><br/>

                    <b><FormattedRelative value={lastTrip} style="numeric" /></b>
                    <i>(numeric)</i>
                </p>
            </div>
        );
    }
});

Rendered

včera(best fit)
před 1 dnem(numeric)

minulý rok(best fit)
před 1 rokem(numeric)

Using Named Relative Formats

Specifying format options (e.g.: style="numeric") in every use of <FormattedRelative> can become a problem in large code bases. Instead, you can provide named relative formats on the formats component prop. The IntlMixin automatically propagates the formats prop value through the component hierarchy.

var IntlMixin         = ReactIntl.IntlMixin;
var FormattedRelative = ReactIntl.FormattedRelative;

var Component = React.createClass({
    mixins: [IntlMixin],

    render: function () {
        var postDate = Date.now() - (1000 * 60 * 60 * 24);
        var lastTrip = Date.now() - (1000 * 60 * 60 * 24 * 2);

        return (
            <div>
                <p>
                    <b><FormattedRelative value={postDate} /></b>
                    <i>(best fit)</i><br/>

                    <b><FormattedRelative value={postDate} format="hours" /></b>
                    <i>(hours, numeric)</i>
                </p>
                <p>
                    <b><FormattedRelative value={lastTrip} /></b>
                    <i>(best fit)</i><br/>

                    <b><FormattedRelative value={lastTrip} format="hours" /></b>
                    <i>(hours, numeric)</i>
                </p>
            </div>
        );
    }
});

Rendered

včera(best fit)
před 24 hodinami(hours, numeric)

předevčírem(best fit)
před 48 hodinami(hours, numeric)

In the example above, "hours" is the name of a relative format defined in the formats.relative component prop. Check the RENDER tab to see the details.

See the custom formats section for more information.

Pluralize Labels in Strings

When internationalizing a React app, you will need a way to localize your UI strings, including any logic pieces like pluralization rules for all the languages you wish to support. These strings should be externalized from your React components so that the same React component can be used for all languages. Using the IntlMixin and <FormattedMessage> Component together provides a way to lookup and format language-specific strings.

The this.getIntlMessage() method provided by the IntlMixin implements a lookup process to resolve the localized strings from the component's messages prop. This method takes a string path/namespace to a localized string within the messsages object; e.g., "photos.likeButtonLabel".

The <FormattedMessage> component formats a translated message written in the ICU Message syntax (which is used by professional translators). The message format supports placeholders, plus choosing different strings based on pluralization, gender, or other criteria.

See the Guide for details on how to write those messages using the ICU Message syntax.

The following example is the same one used on the home page of this website. It uses a moderately complex message to show basic substitution, number and date formatting, and pluralization. Be sure to look at the MESSAGE tab.

var IntlMixin        = ReactIntl.IntlMixin;
var FormattedMessage = ReactIntl.FormattedMessage;

var Component = React.createClass({
    mixins: [IntlMixin],

    render: function () {
        return (
            <p>
                <FormattedMessage
                    message={this.getIntlMessage('photos')}
                    name="Annie"
                    numPhotos={1000}
                    takenDate={Date.now()} />
            </p>
        );
    }
});

Rendered

23. ledna. 2017 Annie vyfotila 1 000 fotek.

In the example above, this.getIntlMessage('photos'); will return the "photos" message provided at this.props.messages.photos. Beyond the basic nested object value lookup process, it provides descriptive error messages when accessing a property that is undefined. Check the RENDER tab to see the details.

Note: You can provide the messages property value to the root React component when rendering a the top-level component in the React hierarchy, and messages — just like locales — will be propagated to any child components using IntlMixin.

Additionally, you can leverage custom formats as described below, to specify a set of named format options to use in your messages, e.g: {someNum, number, USD} and {someDate, date, short} or {someTime, time, long}.

Formatting Rich-Text Strings

If you inspect the DOM for the rendered example above, you'll notice the formatted message is a string of text inside of a <span>. This will work for many strings, but sometimes string messages benefit from being rendered as rich-text. React Intl supports formatting rich-text strings in the following ways:

React Elements as props Values

The recommended way to format strings as rich-text is to use the <FormattedMessage> Component, and pass other React Elements as props values to be used to fill-in placeholders in the static message string.

The following example has a static ICU Message string with two generic placeholders {name}, and {timeAgo}. These placeholders will will be replaced with rich-text values to make the name bold, and timeAgo represented as a relative time inside an HTML <time> element:

var IntlMixin         = ReactIntl.IntlMixin;
var FormattedMessage  = ReactIntl.FormattedMessage;
var FormattedRelative = ReactIntl.FormattedRelative;

var Component = React.createClass({
    mixins: [IntlMixin],

    render: function () {
        var takenDate = 1421881732917;

        return (
            <p>
                <FormattedMessage
                    message={this.getIntlMessage('photosNested')}
                    name={<b>Annie</b>}
                    numPhotos={1000}
                    takenAgo={
                        <time dateTime={new Date(takenDate)}>
                            <FormattedRelative value={takenDate} />
                        </time>
                    } />
            </p>
        );
    }
});

Rendered

Annie took 1,000 photos .

HTML in Static ICU Message Strings

In some cases you might want to put HTML directly into the static ICU Message String, while we recommend you use the nested React Elements approach mentioned about React Intl provides a <FormattedHTMLMessage> Component.

The following example formats numComments with a pluralized label and bolds the number of comments if it's more than one:

var IntlMixin            = ReactIntl.IntlMixin;
var FormattedHTMLMessage = ReactIntl.FormattedHTMLMessage;

var Component = React.createClass({
    mixins: [IntlMixin],

    render: function () {
        return (
            <p>
                <FormattedHTMLMessage
                    message={this.getIntlMessage('commentsHTML')}
                    numComments={42} />
            </p>
        );
    }
});

Rendered

42 comments

<FormattedHTMLMessage> only supports HTML in the static ICU Message string, it does not support JSX. Also, using this component is less performant than using <FormattedMessage> because it has to opt-out of React's virtual DOM diffing.

Define Your Own Custom Formats

The IntlMixin allows you to define named formats that can be used throughout the entire application or within a component hierarchy. These named format can be specified for date, time, number and relative format types. The following example illustrates how these custom named formats work.

var IntlMixin         = ReactIntl.IntlMixin;
var FormattedNumber   = ReactIntl.FormattedNumber;
var FormattedDate     = ReactIntl.FormattedDate;
var FormattedTime     = ReactIntl.FormattedTime;
var FormattedRelative = ReactIntl.FormattedRelative;

var Component = React.createClass({
    mixins: [IntlMixin],

    render: function () {
        var yesterday = Date.now() - (1000 * 60 * 60 * 24);

        return (
            <ul>
                <li><FormattedNumber value={1400.34} format="USD" /></li>
                <li><FormattedDate value={1390518044403} format="short" /></li>
                <li><FormattedTime value={new Date()} format="hhmm" /></li>
                <li><FormattedRelative value={yesterday} format="hours" /></li>
            </ul>
        );
    }
});

Rendered

  • 1 400,34 US$
  • 23. ledna. 2014
  • 14:37
  • před 24 hodinami

In the example above, "USD", "short", "hhmm", and "hours" are the named custom formats defined in formats component prop. Check the RENDER tab to see the details.

Note: You can provide the formats property value at the root React component when rendering the top-level component in the React hierarchy, and formats — just like messages and locales — will be propagated to any component child components using IntlMixin.