A Guide to Localizing React Apps with react-intl/FormatJS

At 20M NPM downloads per week and integrations in everything from WordPress to native mobile apps, it’s safe to say that React has become the de facto UI library for the web and beyond.

And when it comes to React app internationalization (i18n) and localization (l10n), the react-intl library is hard to beat. react-intl sits atop the FormatJS i18n libraries, themselves standards-focused and used by giants like Dropbox and Mozilla. react-intl also boasts over a million NPM downloads per week, so it’s beyond battle-tested.

In this hands-on guide, we’ll show you how to localize a React app step by step using the react-intl library. We’ll begin with the fundamentals of internationalization, then move on to working with translations, as well as handling date and number formatting.

As we progress, we’ll delve into more advanced topics such as message extraction and integrating a dedicated software localization platform like Phrase Strings. This integration will help us automate the localization process on a larger scale.

🔗 Resource » If you want a comparison of React i18n libraries, check out our best-off list of React libraries for internationalization.

What are internationalization (i18n) and localization (l10n)?

In practice, internationalization and localization often tend to be used interchangeably, but they don’t mean the same thing. Internationalization (i18n) is the process of making an app ready for localization: not hard-coding UI strings and using keyed translation instead, for example. Localization (l10n) is making an app useable by people of different cultures and languages—this often means the actual translation, using correct date formats, etc.

What is a locale?

A locale is a geographical region with a specific language. We represent a locale using a code: fr-CA means French from Canada, while fr-FR means French from France. We often interchange the terms language and locale, but it’s important to know the difference*.*

🔗 Resource » Here’s a handy list of locale codes.

Alright, let’s get practical.

Our demo app

We’ll work with a small app that we’ll localize step by step. Here it is before any i18n or l10n:

📣 Shoutout » The burger image was created using Midjourney. Our app icon was created by Kawalan Icon from the Noun Project.

Package versions used

We used the following NPM packages when developing this app.

Let’s get to building. We’ll spin up our app from the command line using Create React App.

Our React components are presentational; the root <App> houses a <Header> and a <Recipe> card.

Let’s quickly run down the code in these components.

🗒️ Note » For brevity, we omit all style code in this tutorial, except styles that relate to localization. You can get all the code for this demo app from GitHub, including styles. (The i18n-demo-start directory contains the app before i18n.)

That’s about it for our starter code. Of course, all of our values are hard-coded into our components, and very much in need of localization. Shall we?

🔗 Resource » Get all the starter code from GitHub if you want to code along as we localize this app. Copy the i18n-demo-start directory, run npm install, and you should be good to go.

How do I localize my app with react-intl?

From a bird’s eye view, here’s how we localize our app:

1. Install react-intl.
2. Wrap our app hierarchy in an <IntlProvider>.
3. Move hard-coded strings to translation message dictionaries.
4. Use <FormattedMessage> and intl.formatMessage() to display these translation messages in our components.
5. Localize our dates and numbers using react-intl’s <FormattedDate> and <FormattedNumber> respectively (and their function equivalents).

How does all that work in practice? Let’s take a look.

How do I install and set up react-intl?

We install react-intl via NPM. From the command line, run the following.

Let’s set up some configuration. We’ll put our i18n logic under a new directory, src/i18n.

We’ll revisit this configuration throughout this guide. Let’s continue our setup.

🔗 Resource » Installation is also covered in the official FormatJS installation docs.

The IntlProvider component

All of react-intl’s localization components need to be inside an <IntlProvider> to work. <IntlProvider> manages the active locale and translations, and ensures that any nested react-intl components show their values in the active locale. Let’s see this in action.

First, we’ll create an <I18n> component to encapsulate the <IntlProvider>. <I18n> will wrap our <App> and house i18n logic as we continue to build.

Alright, now we can wrap our entire app with <I18n>; we’ll do so in index.js.

Our entire app is wrapped in a locale-aware <IntlProvider>. We can now localize our components. We’ve already added translation messages for our app’s name and tagline; let’s use those to update our <Header>. We’ll use react-intl’s <FormattedMessage> component to do this.

react-intl’s <FormattedMessage> component takes an id prop and renders the corresponding translation message in the active locale. The wrapping <IntlProvider> will ensure that the active locale’s messages are used here.

If we reload our app now, it looks exactly the same as it did before. That’s because the active locale currently defaults to English.

What happens, however, if we change our default locale to Arabic?

Presto.

🤿 Go deeper » Read more about **FormattedMessage in the official API docs.

Using translation files

This is a good start, but we might want a more scaleable solution: All of our translations sitting in one configuration file can quickly get messy.

Let’s move our translations out of i18n-config.js and into new, per-locale translation files. We’ll put those under a src/lang directory.

Now we can update our configuration to pull these files in.

We round out our refactor with a quick update to our <I18n> component.

Our app should now work exactly as it did before, except now we can add more translations without bloating our i18n-config.js file. We can also easily pass translation files back and forth to translators.

How do I add a language switcher?

Let’s give our users a nice UI to be able to select the locale of their choice. Adding a language switcher will also make testing easier as we continue to localize the app. Once done, it will look like this:

We’ll need to update <IntlProvider>‘s locale and messages props to effectively change the rendered language. The problem is that our language switcher will need to sit deep inside the <IntlProvider>, making our hierarchy look something like this:

We want to let <IntlProvider> know when a new language is selected in the <LangSwitcher>.

We could connect an event through the <Header> and <App> components to the <IntlProvider>. This is known as “prop drilling”. It would create an unnecessary dependency chain, making it difficult to move the <LangSwitcher> within the app hierarchy later.

To avoid prop drilling, let’s add a piece of React context to manage our global locale state.

Now let’s wire up this context to our <I18n> component.

We can now use LocaleContext in any descendent of <LocaleContext.Provider>, allowing us to set the top-level locale state practically anywhere in our hierarchy.

This means we can update the active locale in <IntlProvider> without passing props up or down our hierarchy. Let’s make use of this in our new <LangSwitcher>.

With that in place, we can select a new locale from the UI, triggering a re-render of all react-intl components, like <FormattedMessage>. This effectively switches the active locale. If we tuck our <LangSwitcher> inside our <Header> component, we should see the following.

Of course, we don’t want our users looking at locale codes like en-US when selecting their language. Let’s add human-friendly names to our locales.

Now we can update our <LangSwitcher> to use these names.

Our language switcher now looks more readable. And because we used context, our solution is flexible: We can move our <LangSwitcher> anywhere within the scope of our <LocalContext.Provider> and it will continue to work.

📣 Shoutout » Language icon by jonata hangga on the Noun Project.

🔗 Resource » The official React docs’ **Passing Data Deeply with Context is a good guide on the subject.

How do I work with text direction (LTR/RTL)?

Arabic, Hebrew, Maldivian, and other languages are laid out right-to-left (rtl). Most others are left-to-right (ltr). Web browsers accommodate this through the <html dir="rtl"> attribute, which sets the layout of the whole page. Let’s tap into this attribute in a new custom hook.

This is the first time we see the useIntl() hook. It returns an intl instance that has useful properties, like the active locale. (This is the same intl instance managed internally by our <IntlProvider>). We’ll revisit useIntl() throughout the article.

Let’s use our new custom hook in the root <App> component.

Notice that we’re referencing locales[locale].dir in our custom hook above. We need to add these direction configs to make the hook work.

Now when Arabic is the active locale, the <html> document element will have a dir="rtl" value; when English is active it has dir="ltr".

🗒️ Note » You can set the dir attribute on many HTML elements to override the page’s dir.

Updating horizontal styles

Setting the dir attribute to rtl on the <html> will flow the page right-to-left. However, we often still need to update CSS that uses properties like margin-left. Here’s an example:

🤿 Go deeper » Alternatively, we can use the newer *logical* properties, like padding-inline-start, which cover text direction automatically.

🗒️ Note » Tailwind CSS has built-in direction modifiers e.g. ltr:pr-1 rtl:pl-1. The framework also supports logical properties, like ps-1 for padding-inline-start.

What are the 2 ways of formatting in react-intl?

Let’s review the basic translation message workflow as we look at react-intl’s 2 ways of formatting: declarative and imperative.

We’ll add translations for our recipe headers next.

Just as before, we’ll pull these translations into our <Recipe> component using react-intl’s <FormattedMessage> component.

This is a declarative way to format messages. In other words, we’re not concerned with how messages as formatted; just that the React component, <FormattedMessage>, will display a message in the active locale given its id.

As it happens, <FormattedMessage> uses an intl.formatMessage() function under the hood —that’s the how, the imperative way to format.

We can make use of intl.formatMessage() ourselves through the useIntl() hook. This comes in handy when we want to translate attributes or props. Let’s translate our recipe image’s alt attribute to illustrate.

intl.formatMessage() works much like the <FormattedMessage> component: Given an id, it returns the corresponding translation message in the active locale.

🔗 Resource » Learn more about intl.formatMessage() in the FormatJS API docs.

Localizing the document title

Now that we know about formatMessage(), we can use it to translate our <html title> in our useDocL10n() custom hook.

With that, our document title is localized.

How do I add dynamic values to translation messages?

We often want to inject runtime values in a translation string. This could be the name of the logged-in user, for example. The ICU message format used by FormatJS makes this interpolation easy. Let’s localize the author string of our recipe to demonstrate.

First, we’ll add new translation messages, and use the {variable} syntax for placeholders.

Now we can use the values prop in <FormattedMessage> to interpolate these dynamic values at runtime.

That will do it.

🗒️ Note » The date in Arabic looks off: It’s injected as a hard-coded string and hasn’t been localized. We’ll fix it when we get to date formatting a bit later.

Of course, the imperative intl.formatMessage() provides interpolation as well.

How do I work with plurals in translation messages?

“You have 1 new message.”

“You have 29 new messages.”

Ah, plurals. They’re often mishandled in translation. It’s important to realize that different languages have different plural forms. While English has two plural forms*,* one and other, other languages can have more. Arabic, for example, has six.

🔗 Resource » The CLDR Language Plural Rules chart is a canonical source for languages’ plural forms.

Let’s add a comment counter to our recipe to showcase localized plurals.

We’ll add the English translation message first. The ICU message format has excellent support for plurals, using a special syntax:

✋ Heads up » The other form is always required.

Of course, we need to add this message to our JSON language files. JSON doesn’t support multiline strings, so our message ends up looking like the following.

The count variable in the message represents an integer that we can pass to <FormattedMessage> via its values prop.

FormatJS uses the count variable to determine the plural form within the recipe.comment_count message. It also replaces instances of # with the value of count in the string. In English, this results in the following renders for count values of 0, 1, and 2, respectively.

Our Arabic translation message is more complex because it includes the language’s six plural forms.

Again, we need to squish it into one line for our JSON.

🔗 Resource » I found a handy Online ICU Message Editor that I used for testing my multiline plural strings before copying them into my JSON and removing newline characters.

With our new translation in place, we get perfectly pluralized messages when we switch our active locale to Arabic. Also notice that the Arabic messages have Eastern Arabic numerals (١، ٢، ٣), which is correct for the Arabic-Egypt locale.

🤿 Go deeper » The Missing Guide to the ICU Message Format covers all the ins and outs of ICU message plurals. And our Concise Guide to Number Localization goes into detail regarding numeral systems.

How do I localize numbers?

We’ve just seen that we need to display numbers appropriately for the active locale. Not all locales use Western Arabic numerals (1, 2, 3). Bengali, for example, uses the Bengali–Assamese numeral system (০, ১, ২, ৩). Currency and percent symbols, large number separators (1,000,000), and more are specific to each region.

✋ Heads up » This is why it’s important to use region-specific locale codes when working with numbers and dates. Use en-US, not en, for example.

Luckily, react-intl/FormatJS has good number localization support, which uses the JavaScript standard Intl.NumberFormat under the hood. Let’s make use of these react-intl features to localize the numbers in our React app.

We’ll start with the recipe “likes” counter.

Here we can keep it simple and use react-intl’s <FormattedNumber> component.

<FormattedNumber> localizes its given number value to the active locale.

We can customize <FormattedNumber>‘s output: Anything that can be passed to the Intl.NumberFormat constructor options parameter can be passed as a prop to <FormattedNumber>. Here are some examples:

We can pass the same options to react-intl’s imperative equivalent, intl.formatNumber().

What about numbers interpolated in our translation messages? The ICU message syntax has us covered here.

The syntax is similar to the plural syntax we used earlier. A last, optional, format designator after the :: is passed to the Intl.NumberFormat constructor.

🤿 Go deeper » The strange currency/USD syntax is a part of the ICU syntax known as a number skeleton.

The above would render the following in English and Arabic, respectively.

How do I localize dates?

Localizing dates with react-intl is very similar to localizing numbers. We use react-intl’s <FormatteDate> and intl.formatDate(). In turn, react-intl uses the JavaScript standard Intl.DateTimeFormat under the hood to localize our dates.

✋ Heads up » Just like numbers, dates are region-specific. So favor locales with regions (ar-EG) over language-only locales (ar).

Let’s revisit our earlier interpolation example.

The above results in publishedAt rendering as “2023/06/20” in both English and Arabic. We can improve this by localizing the date value.

First, let’s update the publishedAt value itself, changing it to a Date object, which FormatJS needs for date localization.

Now let’s use the ICU message syntax to designate a medium-length date in our messages.

With that, our date is localized.

Built-in short, medium, and long date formats are always available to us. We can also use ICU datetime skeletons to granularly control our formats. Let’s say we wanted to remove the day from our recipe publishing date. ICU date skeletons come in handy here:

🔗 Resource » Find all the date skeletons FormatJS supports in the official docs.

What if we wanted to format a date outside of a translation message? We can use react-intl’s <FormattedDate> component for that. Let’s break our recipe’s publish date out of the translation message.

Much like <FormattedNumber>, <FormattedDate> takes formatting props that match the options param passed to the Intl.DateTimeFormat constructor.

And, of course, the imperative intl.formatDate() can be used to get the same result:

🤿 Go deeper » react-intl offers many more datetime formatting options, including time, datetime range, relative time, and time zone support. See the component and imperative API docs for more info (the right-hand sidebars list the relevant components and functions, respectively).

How do I load translations dynamically?

Our current solution still isn’t as scalable as it could be. If we had a hundred, or even twenty locales, we would load them all in our main JavaScript bundle. This would waste bandwidth and slow down our website.

We can fix this. Let’s refactor our translation message logic so that we only load messages for the active locale. We can do this by dynamically loading the appropriate message file once we’ve determined the active locale.

First, let’s remove the static message file imports from our config file. We won’t need them anymore.

Next, let’s update our <I18n> wrapper component to load the appropriate translation file dynamically.

If we open our browser dev tools and throttle our network speed to simulate a slow connection, we should be able to see our new loading state.

Under the hood, the Webpack bundler that Create React App uses has turned our dynamic import into a chunk that loads separately from the main bundle. We can see this if we open our browser Network tab.

Our app works almost exactly as before, except now we can have as many locales as we want without bloating our main bundle.

How do I detect the user’s preferred language?

Not everyone can read English, and a good i18n strategy should accommodate that. Our user’s preferred languages are available to us through her browser’s navigator object. We can use this to load our app shown in the supported language closest to the user’s preference.

Let’s do this step-by-step. First, we’ll write a helper that returns an array of the locales set in the browser.

navigator.languages corresponds to the list you can set in your own browser settings.

In case none are set in our user’s browser, we fall back on navigator.language.

We’ll use the browser locale to match one of our app’s supported locales. FormatJS has a handy locale matcher package, intl-localematcher, to help with just this. Let’s install it from the command line.

Now we write a function that takes both the browser locales and our app’s defined locales, and tries to find the closest match.

FormatJS’s match is doing the heavy lifting here. Let’s briefly go over how it works.

Say we have Arabic-Morocco (ar-MA) and English-Canada (en-CA), in that order, as our preferred browser languages.

We know that our app’s locales are Arabic-Egypt (ar-EG) and English-USA (en-US). So in our scenario, the match() call above is equivalent to the following.

match looks at the browser locales and realizes that, ideally, our user wants content served in Arabic for the Morocco region. It checks against the second list and sees that while we don’t have that exact flavor of Arabic, we do have Egyptian Arabic. That’s the best our app can do, so match returns ar-EG.

🗒️ Note » When all else fails, match returns the value of its last param, the default locale.

Alright, let’s make use of this logic by wiring it up to the <I18n> component.

Now when a user visits our app, they’ll see it translated in a locale that’s closest to their preferred language.

🔗 Resource » Learn more in Detecting a User’s Locale in a Web App.

Storing the user-selected locale

What if the user wants to pick a language themselves, overriding the one we matched for them? We already have a language selector to allow them to do that. The problem now is that every time they visit our app, we’ll always use the detected/matched locale, ignoring any selection the user made in a previous visit.

We can fix this by utilizing the browser’s localStorage (that’s local not locale). localStorage allows us to store key/value pairs on the browser that we can retrieve on future site visits. Let’s add a simple module to store the user’s selected locale.

Now let’s make sure that if a user selects a locale using our language switcher, it gets stored for later retrieval.

Finally, let’s update our userLocale() function to return the stored locale if it finds it.

That’s it! Now if the user selects a locale from our language switcher, it will always be used on future visits, regardless of their browser settings.

How do I include HTML in my translation messages?

Sometimes we want to embed links or special styles within our translation messages. For example:

Luckily, react-intl makes it easy to embed markup in our translation messages using rich text formatting. Here’s how we can use it to translate the above message:

The above would render:

We can have as many embedded tags in our messages as we want, as long as they have corresponding resolver functions in FormattedMessage‘s value prop.

And, of course, we can use rich text formatting in intl.formattedMessage() as well.

🔗 Resource » Read more about rich text formatting in the official API documentation.

🗒️ Note » In earlier versions of react-intl, rich text formatting was achieved with a <FormattedHtmlMessage> component. This has been deprecated in favor of the above solution.

How do I extract translations from my app?

So far, we’ve covered a workflow where we manually set messages in translation files and reference them by ID in our components. As our app scales, this approach can become cumbersome, as we have to manually maintain increasingly large translation files.

As our app scales, we can automate this process. Let’s start with message extraction. Instead of placing messages in translation files ourselves, we can have the FormatJS CLI do it for us.

Additional packages used

For our extraction workflow, we will use the following NPM packages:

We’ll start by installing the FormatJS CLI, which will allow us to extract our messages. Running the following command from the command line should do it.

Let’s add a new script to our package.json file to make our lives easier.

Our new extract script will use the FormatJS CLI to pull messages out of the .js and .jsx files in our source directory. The extracted messages will go into our source language file, src/lang/en-US.json.

✋ Heads up » To avoid errors during extraction, we use the --ignore flag to tell the CLI to skip our translations (lang) directory, when looking for messages to extract.

Designating --format simple keeps the outputted en-US.json file in the {"id": "translation"} format we’ve been using so far. You can use the default FormatJS format by omitting the --format option. We’ll use the simple format in this tutorial.

🔗 Resource » Read about message extraction in the official docs. You might also find the CLI documentation handy.

If we run our extraction command now, en-US.json will contain ID keys and empty translation messages. That’s because, with an extraction workflow, we need to add our source/default (English) messages directly to our components. Let’s update our Header component to demonstrate.

The defaultMessages we pass to formatMessage() and FormattedMessage are what the extract command will pull from our source code. They should be in the app’s default locale, English in our case.

🗒️ Note » When a translation is missing from the active locale, the contents of defaultMessage will be shown as a fallback.

✋ Heads up » We need to make sure that the app.title declaration in our useDocL10n() hook matches the one in the Header component. Otherwise, we’ll get a warning that the messages don’t match when we try to extract (and an empty message in our translation file).

Now let’s run our new command from the command line.

✋ Heads up » Please make sure that every translation message in your app has a defaultMessage before running extract, or you will lose its translation in your source locale file.

This should have overwritten our src/lang/en-US.json file, which should largely unchanged.

Except now we don’t have to maintain it manually. We can add and update translation messages in our app and npm run extract to update the translation file.

✋ Heads up » The built-in react-intl React components will work fine with extract, as well as intl.formatMessage(). However, if you use any other components or functions for translation (like your own wrappers) you need to declare them using the CLI’s additional-function-names or additional-component-names options.

Of course, the translation workflow remains the same from here. We copy the en-US.json file to ar-EG.json, have a translator add the Arabic, and run the app as usual.

🔗 Resource » The i18n-demo-extraction directory in our GitHub repo has all of the code that we cover in this section.

Auto-generating IDs

We can further streamline our i18n process by removing message IDs from our source code entirely. Instead, FormatJS can automatically generate message IDs and use them under the hood.

🗒️ Note » FormatJS uses a hashing algorithm to generate message IDs that look like "7pboUV". It needs to be able to run the same algorithm when our app builds or runs in development so that it always generates the same ID for a given message. We’ll see all this in action as we go.

First, let’s remove the explicit custom IDs from our message definitions.

Next, let’s modify the extract command so that it auto-generates message IDs.

The --id-interpolation-pattern option tells the extract command to generate a SHA-512 hash as an ID for any message that doesn’t have an explicit ID. (We don’t have to worry too much about the specifics of the hashing algorithm for our purposes).

Let’s run the npm run extract command to see the output. If we look at our English translation file now, we’ll see auto-generated IDs.

If we run our app now, we’ll get missing translation errors: FormatJS isn’t using its hashing algorithm at runtime, so it doesn’t know how to connect a message to its translation in a translation file.

To fix this, we need to use FormatJS’s Babel plugin, which means we need to update the Webpack configuration of our app. Create React App hides this configuration by default, so we’ll use react-app-rewired and customize-cra to hack into it.

✋ Heads up » Create React App maintains its own build scripts to keep you focused on building your app. When you circumvent and update CRA’s build scripts, you’re responsible for maintaining these updates.

First, we’ll install the packages.

Next, let’s create a .babelrc file to tell Babel to use the FormatJS plugin.

Now let’s create a config-overrides.js file; we’ll use it to configure react-app-rewired so that it feeds our .babelrc to Babel when running our app.

Our last step here is to bypass Create React App’s stock scripts and use the ones supplied by react-app-rewired.

Now when we run our app, FormatJS runs its hash algorithm to re-generate its IDs, and our app works without errors.

🤿 Go deeper » We can also compile messages before distributing our app. This has a few benefits, including potentially speeding up our app. Read the FormatJS Message Distribution for more info on compiling.

Streamlining our localization process allows us to focus on the creative code of our app. With one command, we can create a translation source file to hand off to our translators, who can in turn return translations in ten languages, or a hundred.

And instead of maintaining somewhat cryptic message IDs, defaultMessages tell us exactly what a string in our UI says and means.

How do I integrate react-intl with Phrase Strings?

We can make our jobs, and those of our translators, even easier by adopting a software localization platform like Phrase Strings. A single CLI command can push our latest source translations to Phrase Strings, where our translators can use a powerful translation admin panel to translate our app into many locales. With another command, we can pull the updated translations into our app. This keeps us focused on building our app, and not on the localization.

Creating the Phrase Strings project

To integrate Phrase Strings into your app, you need to configure a new Phrase Strings project:

1. Create a Phrase account (you can start for free).
2. Login, open Phrase Strings, and click the New Project button near the top of the screen to create a project.
3. Configure the project to use the React Intl Simple translation file format
4. Add starting languages. In our case, we can add en-US first as the default locale, then add ar-EG.
5. Generate an access token from your profile page. (Click the user avatar near the top-right of the screen → Settings → Profile → Access tokens → Generate Token). Make a copy of this token somewhere safe.
6. Open your new project and go to More → Settings. Check Enable ICU Message format support and click Save.

Setting up the Phrase Strings CLI

That’s it for the Phrase Strings project config. Now let’s set up the Phrase Strings CLI so we can automate the transfer of our translation files to and from our translators.

🔗 Resource » Installation instructions for the Phrase Strings CLI depend on your platform (Windows, macOS, Linux). Just follow the CLI installation docs and you should be good to go.

CLI installed, let’s use it to connect our React project to Phrase Strings. From our React project root, let’s run the following command from the command line.

We’ll be asked to provide the access token we generated in Step 5 above. Let’s paste it in.

We’ll then be given some prompts:

1. Select project—Select the Phrase Strings project we created above.
2. Select the format to use for language files you download from Phrase Strings—Hit Enter to select the project’s default.
3. Enter the path to the language file you want to upload to Phrase—Enter ./src/lang/en-US.json, since that’s our source translation file.
4. Enter the path to which to download language files from Phrase—Enter ./src/lang/<locale_name>.json. (<locale_name> is a placeholder here, and it allows us to download all the translation files for our project: en-US, ar-EG, etc.).
5. Do you want to upload your locales now for the first time?—Hit Enter to accept and upload.

🗒️ Note » A .phrase.yml is created in our project to save the config we created above. It will be used by default when we run commands like phrase push or phrase pull in our project.

At this point, our en-US.json file will get uploaded to Phrase, where our translators can use the powerful Phrase web admin to translate our app.

When our translators are finished, we can run the following command to pull all of their work into our project.

Our en-US.json and ar-EG.json files should now have the latest updates from our translators. We can simply run our app as normal to test our updated translations. Whether you have two locales, or two hundred, you only need to run two commands to keep your translations in sync. And your translators get an excellent environment to work in.

Adding a new language

Let’s demonstrate how much easier our lives are now with this new workflow. We’ll add French (fr-FR) to our app. Here are the steps:

1. Tell our translators we want to add fr-FR to our app. (They’ll manage all that in Phrase Strings).
2. Add French in our locales config object (see i18n-config.js listing below).
3. Pull the new French translators from Phrase using phrase pull.

That’s literally it!

Here’s the updated i18n-config.js:

And here’s our app in French.

🔗 Resource » The app with French added is in the i18n-demo-extraction directory of our GitHub repo.

How do I localize my React TypeScript app with react-intl?

Using react-intl with TypeScript in a React app is relatively straightforward. An in-depth guide for this is outside the scope of this tutorial. We’ll cover strongly typing message IDs and we’ll share our complete solution code for your perusal.

In fact, most of react-intl will work with TypeScript out of the box. If you want to make your message IDs typed only to your keys, you can add the following code somewhere in your project.

That’s basically it for react-intl TypeScript integration. Most of our other TypeScript considerations are specific to our demo.

🤿 Go deeper » You can find a diff of our TypeScript i18n solution in our GitHub repo. The entire TypeScript i18n demo is in an i18n-demo-typescript folder in the repo as well.

✋ Heads up » We used TypeScript 4.9.5, since TypeScript 5 was giving us peer dependency errors when we tried installing it in our project. (--forceing the version 5 install seemed to work fine, but use at your own risk).

🔗 Resource » If you’re working with TypeScript and want to use the extraction/auto-generated ID workflow (optionally with Phrase), check out this diff. An entire Typescript extraction demo is in a dedicated i18n-demo-typescript-extraction folder.

Take React localization to the next level

We hope you found this guide to localizing React apps with react-intl/FormatJS enjoyable and informative. If you’re interested in localizing a Next.js app, check out our tutorial on Next.js internationalization. If you prefer using i18next, our guide to React localization with i18next should have you covered.

When you’re ready to start translating, let Phrase Strings take care of the hard work. With plenty of tools to automate your translation process and native integrations with platforms like GitHub, GitLab, and Bitbucket, Phrase Strings makes it simple for translators to pick up your content and manage it in its user-friendly string editor.

Once your translations are ready, you can easily pull them back into your project with a single command—or automatically—so you can stay focused on the code you love. Sign up for a free trial and see for yourself why developers love using Phrase Strings for software localization.