React Intl v2 has a peer dependency on
react@^0.14.0 || ^15.0.0-0 and now takes advantage of features and changes in React 0.14 and also works with React 15.
The locale data modules in React Intl v2 have been refactored to provide data, instead of mutating React Intl's internal locale data registry. The
react-intl/locale-data/* files are also decoupled from the
ReactIntl global and instead provide UMD modules with a new
ReactIntlLocaleData global. These changes, mean apps need update how they are registering the locale data they need in the browser.
Add Call to
addLocaleData() in Browser#
There is now an
This assumes a locale data
<script> is added based on the request; e.g., for French speaking users:
Using Browserify/Webpack to Load React Intl:
This decoupling of the library from the locale data, allows for the files to be loaded via
<script async>. When using async scripts, your client bootstrapping code will need to wait for the
load event, including the code above.
IntlMixin has been removed from React Intl v2. The mixin did two things: it automatically propagated
messages throughout an app's hierarchy, and it provided an imperative API via
format*() functions. These jobs are now handled by
In React Intl v1, you would add the
IntlMixin to your root component; e.g.,
<App>. Remove the
IntlMixin and instead wrap your root component with
locale prop is singular, required, and only accepts a string value. This is a simplification of the plural
locales prop used by the
IntlMixin also provided the imperative API for custom components to use the
format*() methods; e.g.,
formatDate() to get formatted strings for using in places like
aria attribute. Remove the
IntlMixin and instead use the
injectIntl() Hight Order Component (HOC) factory function to inject the imperative API via
Here's an example of a custom
<RelativeTime> stateless component which uses
injectIntl() and the imperative
injectIntl() is similar to a
connect() HOC factory function you might find in a Flux framework to connect a component to a store.
The way string messages are formatted in React Intl v2 has changed significantly! This is the most disruptive set of change when upgrading from v1 to v2; but it enables many great new features.
React Intl v2 introduces a new Message Descriptor concept which can be used to define an app's default string messages. A Message Descriptor is an object with the following properties,
id is the only required prop:
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)
This upgrade guide will focus on using Message Descriptors that only contain an
React Intl v2 no longer supports nested
messages objects, instead the collection of translated string messages passed to
<IntlProvider> must be flat. This is an explicit design choice which simplifies while increasing flexibility. React Intl v2 does not apply any special semantics to strings with dots; e.g.,
Apps using a nested
messages object structure could use the following function to flatten their object according to React Intl v1's semantics:
Message ids can still contain
"."s, so the ids themselves remain the same, it's only the
messages object structure that needs to change.
getIntlMessage() Calls with Message Descriptors#
getIntlMessage() method that was provided by the
IntlMixin has been removed in React Intl v2. It was simply a helper that interpreted a message id string with
"."s by looking up the translated message in a nested
messages object. With the removal of
IntlMixin and the change to a flat
messages object, this method has been removed.
All calls to
getIntlMessage() need to be replaced with a Message Descriptor.
A typical pattern when calling
formatMessage() is to nest a call to
getIntlMessage(). These can be easily updated:
The props for these two components have completely changed in React Intl v2. Instead of taking a
message prop and treating all other props as values to fill in placeholders in a message,
<FormattedHTMLMessage> now the same props as a Message Descriptor plus a new
values prop groups all of the message's placeholder values together into an object.
The following example shows up to update a
<FormattedMessage> instance to use the new props and remove the call to
Minor changes have been made to how the "now" reference time is specified when formatting relative times in React Intl v2. It's uncommon to specify this value outside of test code, so it might not exist in your app.
now Prop to
A new feature has been added to
<FormattedRelative> instances in React Intl v2, they now "tick" and stay up to date. Since time moves forward, it was confusing to have a prop named
now, so it has been renamed to
<FormattedRelative> instances that use
now should update to prop name to
formatRelative()'s Second and Third Arguments#
The signature of the
formatRelative() function has been aligned with the other
format*() functions and in React Intl v2, it only accepts two arguments:
options. To specify a "now" reference time, add it to the
options argument, and remove the third