Internationalization (i18n) is all about making your app ready for the real world: a world where people don’t all use the same language, the same date formats, the same currency rules, or even the same reading direction. React i18n is simply the process of bringing that flexibility into a React application. Instead of hard-coding English strings everywhere and hoping for the best, a properly internationalized app separates content from code, handles plurals and formatting correctly, respects the user’s locale, and behaves like it was actually built for them.
This guide shows you exactly how to do that with react-intl, one of the most stable and feature-rich libraries in the React ecosystem. No filler, no outdated patterns, just practical, modern techniques.
Here’s what we’ll cover:
By the end of this guide, you’ll have a fully localized React app that:
The source code for this article is available on GitHub.
You may also be interested in learning how to translate React apps with react-I18next.
Localization (aka l10n) isn't just "translate your app and ship it". So basically, what is localization? It's the process of adapting your product so it actually feels native to users in a specific region. That includes not only language but also formatting rules, cultural expectations, and sometimes even UX or logic adjustments that a new market requires.
Here's what localization usually covers:
Translation swaps words; localization makes the whole app behave like it was built for those users from day one.
This guide assumes you're already running the latest stable Node.js and npm. You should also be comfortable with basic JavaScript, HTML, and simple npm/Yarn commands. Nothing hardcore, just enough to move around a React project.
Before you start adding react-intl or any i18n logic, you need a clean React setup that isn't stuck in the 'yer olde days' era of tooling. Nowadays, the go-to way to spin up a fast, lightweight React project is Vite. It's quick, minimal, and feels exactly like something a sane developer would want to work with.
Run the official Vite initializer:
npm create vite@latest react-intl-lokaliseIf you prefer Yarn or pnpm:
yarn create vite react-intl-lokalise
pnpm create vite react-intl-lokaliseWhen asked by the wizard, choose "React" as a framework and "TypeScript" as a language.
Move into your project folder and install everything:
cd react-intl-lokalise
npm installFire it up:
npm run devNow you can navigate to localhost:5173 and observe your app. If you see the cute counter button doing its thing, congrats — the project is alive and ready for react-intl.
When you start adding internationalization to a React app, one of the first questions you'll hit is: which i18n library should I use? There are several solid options, and they all solve similar problems in slightly different ways. Picking the right one isn't always obvious, so here are a few things worth considering before you commit.
Choosing an i18n library isn’t just “install whatever is trending on npm.” It sits at the center of your UI, your build pipeline, your translators’ workflow, and your entire long-term product strategy. Before you commit, make sure the library fits your real needs, not just the demo app.
Here are some factors to consider:
Different frameworks have different needs:
Once again, think about the real product, not the “hello world” version:
If your product spans multiple markets, these capabilities are typically non-negotiable.
The best library is the one your team actually enjoys using:
A good i18n library must be alive and healthy:
Especially important if you use a TMS:
Some libraries:
Look at how the library interacts with the platform:
React-intl is part of the FormatJS ecosystem and supports 150+ languages out of the box. It's widely used, battle-tested, and plays nicely with standard locale features like numbers, dates, times, and currency. Because it's built on top of the native JavaScript Intl API, it automatically leans on browser-level features when possible, and you get polyfills for older environments that don't support Intl.
React-intl uses React context under the hood and provides components and hooks that make it easy to load and switch locales dynamically. The API is clean, predictable, and comes with extensive docs (yeah, seriously good docs). In this guide, we're using react-intl because it's still one of the best all-around choices for React i18n.
React-i18next is built on top of the broader i18next ecosystem and is extremely flexible. It handles automatic re-rendering when the user switches languages, supports backend loaders, caching, language detection, and even packs translation files with your bundler. That plugin system is the library's superpower: if there's something you want to automate, there's probably an i18next plugin for it.
It also offers experimental React Suspense support, which can simplify async translation loading in modern apps. If you're interested in learning more, we have a dedicated tutorial on React with i18next.
LinguiJS is newer compared to the big players, but it's built with developer ergonomics in mind. It focuses on simplicity and minimal overhead while still giving you ICU message formatting, pluralization, extraction tools, and good integration with modern bundlers. If you want something clean and code-driven without too much ceremony, LinguiJS is worth a look.
First, add react-intl to your React + Vite project:
npm install react-intlor with Yarn:
yarn add react-intlThat's all you need on the dependency side for now.
Before we write any translated text, we need a clear place for our messages. For this tutorial, we will support three locales:
en)fr)ar)A simple structure is (later I'll also explain how to make it more scalable):
src/
i18n/
messages/
en.json
fr.json
ar.json
App.tsx
main.tsxThis setup keeps all i18n-related files under src/i18n/messages, which makes it easier to:
Each *.json file will be a flat key → value map, and we will keep keys consistent across locales.
For now, our demo messages will be simple: a title and a short description.
Example: src/i18n/messages/en.json
{
"app.title": "React-intl demo",
"app.description": "This is a small demo showing how to localize a React app with react-intl."
}Example: src/i18n/messages/fr.json
{
"app.title": "Démo React-intl",
"app.description": "Cet exemple montre comment localiser une application React avec react-intl."
}Example: src/i18n/messages/ar.json
{
"app.title": "عرض React-intl",
"app.description": "هذا مثال بسيط يوضح كيفية تعريب تطبيق React باستخدام react-intl."
}We will extend these files with more complex messages (plurals, dates, gender, etc.) later, but for now we only need these two keys.
To make translations work, we have to wrap our React tree in IntlProvider and pass it the current locale plus the right set of messages.
In a Vite + React setup, the best place to do this is your entry file, usually src/main.tsx. Replace the contents of src/main.tsx with something like this:
// src/main.tsx
import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import { IntlProvider } from 'react-intl'
import App from './App'
import './index.css'
import enMessages from './i18n/messages/en.json'
import frMessages from './i18n/messages/fr.json'
import arMessages from './i18n/messages/ar.json'
const messagesMap: Record<string, Record<string, string>> = {
en: enMessages,
fr: frMessages,
ar: arMessages
}
// For now, we hard-code the current locale.
// Later, we can wire this to user preference or browser settings.
const locale = 'en'
const messages = messagesMap[locale]
createRoot(document.getElementById('root') as HTMLElement).render(
<StrictMode>
<IntlProvider locale={locale} messages={messages}>
<App />
</IntlProvider>
</StrictMode>
)At this point, App and all components below can use react-intl to render translated text.
Now we will replace the default Vite starter UI with a minimal page that uses two translated messages:
app.title)app.description)We will use FormattedMessage, the simplest way to render a message by ID. Replace the contents of src/App.tsx with:
// src/App.tsx
import { FormattedMessage } from 'react-intl'
function App() {
return (
<main style={{ maxWidth: 600, margin: '2rem auto', fontFamily: 'system-ui, sans-serif' }}>
<h1>
<FormattedMessage id="app.title" />
</h1>
<p>
<FormattedMessage id="app.description" />
</p>
</main>
)
}
export default AppWhat is happening here:
FormattedMessage looks up the id in the messages object we passed to IntlProvider.'en', it will use en.json. If you change locale to 'fr' or 'ar' in main.tsx, the same components will automatically render French or Arabic text.At this point, you already have a working, localized React app with:
Pluralization is one of those things that looks easy in English and then completely falls apart once you add more languages. If you try to do it manually with "message" + (count === 1 ? '' : 's'), it will break the moment you add French, Arabic, or pretty much anything that isn’t English.
React-intl solves this with ICU MessageFormat, which knows about plural rules per locale and lets translators control the sentence, not your business logic.
Let’s add a message that shows how many notifications a user has. We’ll use the same message ID in all locales: app.notifications.
src/i18n/messages/en.json
{
"app.notifications": "{count, plural, =0 {You have no new notifications} one {You have # new notification} other {You have # new notifications}}"
}(I'm omitting already existing keys.)
What’s going on in app.notifications:
count is the variable we pass from React.plural tells ICU this is a pluralized message.=0, one, other are plural categories:=0 — explicit zero case (nice UX).one — used when the locale thinks the number is “one”.other — fallback for all other counts.# inside text is replaced with the numeric value of count.Now we add equivalents for French and Arabic. They don’t have to be perfect translations for this tutorial, the important part is the structure.
src/i18n/messages/fr.json
{
"app.notifications": "{count, plural, =0 {Vous n'avez aucune nouvelle notification} one {Vous avez # nouvelle notification} other {Vous avez # nouvelles notifications}}"
}src/i18n/messages/ar.json
For Arabic, real plural rules are more complex (zero, one, two, few, many, other), but for a demo we can keep it simple and still use plural:
{
"app.notifications": "{count, plural, =0 {لا توجد إشعارات جديدة} one {لديك إشعار جديد واحد} other {لديك # إشعارات جديدة}}"
}Later, if you want to be precise, you can extend it with two, few, many categories and let your translators own that. You can also take advantage of Lokalise and hire professional translators or utilize our AI.
Now we need a place in the UI that shows this message and lets us play with different values of count. We’ll add a small counter in App.tsx.
Replace src/App.tsx with:
// src/App.tsx
import { useState } from 'react'
import { FormattedMessage } from 'react-intl'
function App() {
const [count, setCount] = useState(0)
return (
<main style={{ maxWidth: 600, margin: '2rem auto', fontFamily: 'system-ui, sans-serif' }}>
{/* Simple heading */}
<h1>
<FormattedMessage id="app.title" />
</h1>
{/* Simple paragraph */}
<p>
<FormattedMessage id="app.description" />
</p>
{/* Pluralized notifications */}
<section style={{ marginTop: '2rem' }}>
<p>
<FormattedMessage
id="app.notifications"
values={{ count }}
/>
</p>
<div style={{ display: 'flex', gap: '0.5rem', marginTop: '0.5rem' }}>
<button type="button" onClick={() => setCount(0)}>
=0
</button>
<button type="button" onClick={() => setCount(1)}>
=1
</button>
<button type="button" onClick={() => setCount((prev) => prev + 1)}>
+1
</button>
</div>
</section>
</main>
)
}
export default App;Key parts:
FormattedMessage receives:id="app.notifications" → connects to the message in your JSON.values={{ count }} → injects count into the ICU message.=0, one, other) based on:IntlProvider), andIf you now change locale in main.tsx from 'en' to 'fr' or 'ar', you’ll see completely different sentences but no code changes in your React components. That’s the main win: React renders the same, translators control the text.
The naive approach in React usually looks like this:
<p>
You have {count} new message{count === 1 ? '' : 's'}
</p>This has a few problems:
if/else branches.With react-intl + ICU:
count).Different locales format dates and times in completely different ways: day/month/year vs month/day/year, 12h vs 24h, different separators, different month names, and sometimes even different numerals. React-intl solves all of this by building on top of the native Intl API. You pass a raw Date, and the library decides how it should look for the current locale.
The rule of thumb: store raw values in your code, and let react-intl format them.
We’ll add a new message with the ID app.lastLogin. All three locales use the same structure: a timestamp called ts, formatted as a date and a time.
src/i18n/messages/en.json
{
"app.lastLogin": "Last login: {ts, date, medium} at {ts, time, short}"
}src/i18n/messages/fr.json
{
"app.lastLogin": "Dernière connexion : {ts, date, medium} à {ts, time, short}"
}src/i18n/messages/ar.json
{
"app.lastLogin": "آخر تسجيل دخول: {ts, date, medium} في {ts, time, short}"
}Explanation:
{ts, date, medium} → uses the locale’s default medium date style{ts, time, short} → uses the locale’s default short time styleUpdate your App.tsx so it includes a section showing the user’s last login (I've skipped irrelevant lines of code):
// ... imports ...
function App() {
const [lastLogin] = useState(() => new Date());
return (
<main
style={{
maxWidth: 600,
margin: "2rem auto",
fontFamily: "system-ui, sans-serif",
}}
>
<section style={{ marginTop: "2rem" }}>
<p>
<FormattedMessage id="app.lastLogin" values={{ ts: lastLogin }} />
</p>
</section>
</main>
);
}
export default App;Here’s what matters:
Date object to ICU: values={{ ts: lastLogin }}main.tsx automatically updates the output without touching any React codeThis separation (data in React, formatting in ICU) is the whole point.
React-intl gives you two approaches to formatting dates:
{
"app.lastLogin": "Last login: {ts, date, medium} at {ts, time, short}"
}Advantages:
<p>
Last login:
<FormattedDate value={lastLogin} dateStyle="medium" />{' '}
<FormattedTime value={lastLogin} timeStyle="short" />
</p>Use this only when the structure must remain the same across all languages. For real text that translators may need to rearrange → ICU is better.
Modern best practice: When a sentence contains human-readable text, put the formatting inside the message (ICU). When the UI structure is fixed, use formatting components.
By default, react-intl formats dates using the user’s local time zone. If you need to force a specific time zone (e.g., always UTC), do it at the provider:
<IntlProvider locale={locale} messages={messages} timeZone="UTC">
<App />
</IntlProvider>This is optional; for most apps, the default is exactly what users expect.
Formatting money is where “just throw a $ in front of it” dies instantly. Different locales use different currency symbols, spacing, decimal separators, and even position of the currency (before/after the number). React-intl sits on top of the Intl API and knows how to format all of that per locale and currency, so you don’t have to.
Golden rule: Store prices as raw numbers in your code, let react-intl format them. No manual string building.
We’ll add a new message app.cartTotal that shows the total price in the user’s cart. For this tutorial, we’ll assume:
We’ll use ICU number skeletons so that formatting rules are fully controlled by the message.
src/i18n/messages/en.json
Extend your existing file with:
{
"app.cartTotal": "Cart total: {total, number, ::currency/USD}"
}src/i18n/messages/fr.json
{
"app.cartTotal": "Total du panier : {total, number, ::currency/EUR}"
}src/i18n/messages/ar.json
{
"app.cartTotal": "إجمالي السلة: {total, number, ::currency/AED}"
}What ::currency/USD does here:
number → tells ICU we’re formatting a number (yeah, I'm playing captain Obvious here, I know)::currency/USD → formats the number as money in USD using the correct pattern for the active locale (grouping, decimals, symbol, spacing)So 1234.5 might become:
en (US): "Cart total: $1,234.50"fr (FR): "Total du panier : 1 234,50 €" (different grouping and decimal separators)ar: same idea, but with RTL and localized digits depending on the environmentNow let’s render this in App.tsx. We’ll pretend the cart total is 1234.5 (like $1234.50).
Add a “Cart total” section to your app:
// src/App.tsx
function App() {
const [cartTotal] = useState(1234.5);
return (
<main
style={{
maxWidth: 600,
margin: "2rem auto",
fontFamily: "system-ui, sans-serif",
}}
>
{/* Currency / cart total */}
<section style={{ marginTop: "2rem" }}>
<p>
<FormattedMessage id="app.cartTotal" values={{ total: cartTotal }} />
</p>
</section>
</main>
);
}
export default App;Key points:
total: cartTotal as a number, not a string.locale in main.tsx changes formatting automatically (symbol, separators, spacing) without touching your component.Real apps often store money in the smallest unit (cents) to avoid floating point issues, like: 123450 (cents) instead of 1234.5 (dollars).
Best practice in that case:
Example:
const [cartTotalInCents] = useState(123450)
const cartTotal = cartTotalInCents / 100
<FormattedMessage id="app.cartTotal" values={{ total: cartTotal }} />Don’t try to manually add symbols or separators. Let the formatter own it.
Just like with dates, you have two ways to handle currency:
{
"app.cartTotal": "Cart total: {total, number, ::currency/USD}"
}Pros:
import { FormattedNumber } from 'react-intl'
<p>
<FormattedNumber value={cartTotal} style="currency" currency="USD" />
</p>This is useful when:
Rule of thumb: If there’s real text around the price, put everything in the message. If you’re just showing a naked number, FormattedNumber is fine.
It only formats numbers. So, if you need USD → EUR → AED → etc., you must convert the value yourself before formatting.
Floats cause rounding issues. Store amounts in the smallest unit (like cents), then divide before formatting:
const displayValue = cents / 100Use messages like:
{
"app.cartTotal": "Cart total: {total, number, ::currency/USD}"
}so translators control the whole sentence.
Some languages change whole sentence structure depending on the user’s gender. Even in English, you can’t always avoid he/she/they.
The key rule here: Don’t do gender logic in React components. Let ICU decide the sentence.
React-intl uses the select keyword in ICU MessageFormat for this.
We’ll use message ID app.userAction. It will say something like: “Ann logged in, she updated her profile.”
src/i18n/messages/en.json
{
"app.userAction": "{gender, select, female {{name} logged in, she updated her profile.} male {{name} logged in, he updated his profile.} other {{name} logged in, they updated their profile.}}"
}What’s happening here:
gender is the variable we pass from React.select picks a branch based on the value.female, male, other are case labels.{name} gets injected normally (this is a placeholder and we basically use interpolation)The other branch covers:
src/i18n/messages/fr.json
{
"app.userAction": "{gender, select, female {{name} s'est connectée et a mis à jour son profil.} male {{name} s'est connecté et a mis à jour son profil.} other {{name} s'est connecté·e et a mis à jour son profil.}}"
}src/i18n/messages/ar.json
{
"app.userAction": "{gender, select, female {{name} قامت بتسجيل الدخول وقامت بتحديث ملفها.} male {{name} قام بتسجيل الدخول وقام بتحديث ملفه.} other {{name} قام/قامت بتسجيل الدخول وقام/قامت بتحديث ملفه/ملفها.}}"
}(Arabic gender rules can be way more nuanced, so if you know the language well, feel free to tweak further.)
Now let's update our App.tsx once again:
// ... imports ...
function App() {
// ... other variables ...
const [user] = useState({
name: "Ann",
gender: "female", // change to 'male' or 'other' and watch the text change
});
// and then inside <main>...
<section style={{ marginTop: '2rem' }}>
<p>
<FormattedMessage
id="app.userAction"
values={{ name: user.name, gender: user.gender }}
/>
</p>
</section>No if/else inside components. Don't write stuff like:
{ user.gender === 'female' ? 'she' : 'he' }That breaks instantly in other languages. Gender affects:
Translators must control the full sentence. ICU handles it correctly for each locale.
Here's our goal for this part:
messages/*.json filesVite makes the “scan a folder at build time” part easy with import.meta.glob.
Create a file src/i18n/locales.ts and let Vite load all *.json files under src/i18n/messages:
// src/i18n/locales.ts
const modules = import.meta.glob('./messages/*.json', {
eager: true
}) as Record<string, { default: Record<string, string> }>
export const messagesMap: Record<string, Record<string, string>> = {}
for (const path in modules) {
const match = path.match(/\.\/messages\/([a-z0-9-]+)\.json$/i)
if (!match) continue
const locale = match[1]
messagesMap[locale] = modules[path].default
}
export const supportedLocales = Object.keys(messagesMap).sort()
export const defaultLocale =
supportedLocales.includes('en') ? 'en' : supportedLocales[0]What this gives you:
messagesMap[LOCALE] → contents of the corresponding JSON filesupportedLocales → ['ar', 'en', 'fr'] (sorted)defaultLocale → 'en' if present, otherwise the first oneThe cool part: If you later drop de.json into src/i18n/messages, it’s automatically picked up without extra code changes.
Now we build a small and pretty dumb component that:
selectonChange(locale) when user picks somethingCreate src/i18n/LanguageSwitcher.tsx:
// src/i18n/LanguageSwitcher.tsx
import type React from "react";
import { supportedLocales } from "./locales";
const labels: Record<string, string> = {
en: "English",
fr: "Français",
ar: "العربية",
// fallback: show locale code if not listed here
};
type LanguageSwitcherProps = {
locale: string;
onChange: (locale: string) => void;
};
export const LanguageSwitcher: React.FC<LanguageSwitcherProps> = ({
locale,
onChange,
}) => {
if (supportedLocales.length <= 1) {
// No point showing a switcher if there is only one locale
return null;
}
return (
<div style={{ marginBottom: "1rem", display: "flex", gap: "0.5rem" }}>
{supportedLocales.map((code) => (
<button
key={code}
type="button"
onClick={() => onChange(code)}
disabled={code === locale}
style={{
padding: "0.25rem 0.75rem",
borderRadius: 4,
border: "1px solid #ccc",
opacity: code === locale ? 0.7 : 1,
cursor: code === locale ? "default" : "pointer",
}}
>
{labels[code] ?? code}
</button>
))}
</div>
);
};You can later swap buttons for a select or fancy UI, but the behavior stays the same: it’s a pure presentational component with locale + onChange.
Up to this point, we've been hard-coding the locale inside main.tsx. That works for a static demo, but a language switcher needs actual React state. Since main.tsx can't use hooks, we create a tiny Root component that wraps the entire app with IntlProvider and keeps the current locale in state.
Create src/Root.tsx:
// src/Root.tsx
import { useState } from "react";
import { IntlProvider } from "react-intl";
import App from "./App";
import { LanguageSwitcher } from "./i18n/LanguageSwitcher";
import { defaultLocale, messagesMap } from "./i18n/locales";
export function Root() {
const [locale, setLocale] = useState<string>(defaultLocale);
const messages = messagesMap[locale];
return (
<IntlProvider locale={locale} messages={messages}>
<div
style={{
maxWidth: 600,
margin: "2rem auto",
fontFamily: "system-ui, sans-serif",
}}
>
<LanguageSwitcher locale={locale} onChange={setLocale} />
<App />
</div>
</IntlProvider>
);
}What this does:
locale is now a piece of state instead of a hard-coded value.setLocale() triggers a re-render, and IntlProvider updates every translated string automatically.messagesMap gives us the right translation bundle based on the selected locale.Finally, simplify src/main.tsx:
// src/main.tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import "./index.css";
import { Root } from "./Root";
createRoot(document.getElementById("root") as HTMLElement).render(
<StrictMode>
<Root />
</StrictMode>,
);main.tsx is now boring again (which is good). All i18n logic lives in:
src/i18n/messages/*.json — actual translationssrc/i18n/locales.ts — discovery and wiring of messagessrc/i18n/LanguageSwitcher.tsx — UI componentsrc/Root.tsx — locale state + IntlProviderFrom a DX point of view this feels nice:
xx.json into messages.supportedLocales.LanguageSwitcher, it gets a human-friendly name.React-intl will translate your text and format numbers/dates, but it will not automatically flip your layout or fix the html attributes for you. If you add Arabic, Hebrew, or any other RTL language, you have to handle two things yourself:
html lang="...")dir="ltr" vs dir="rtl")If you skip this, your Arabic text will still show up, but:
First, decide which locales are RTL. For our demo (en, fr, ar) it’s simple: only ar is RTL.
In src/i18n/locales.ts (where we already discover locales), we can export a small helper:
export function getDirection(locale: string): 'ltr' | 'rtl' {
const normalized = locale.toLowerCase()
if (normalized.startsWith('ar')) return 'rtl'
return 'ltr'
}You can extend this later with he, fa, ur, etc.
Now we hook into the selected locale in Root and sync it with the real document. This keeps SEO, accessibility, and layout direction honest.
Update src/Root.tsx:
// src/Root.tsx
import { useEffect, useState } from 'react'
import { IntlProvider } from 'react-intl'
import App from './App'
import { LanguageSwitcher } from './i18n/LanguageSwitcher'
import { defaultLocale, messagesMap, getDirection } from './i18n/locales'
export function Root() {
const [locale, setLocale] = useState<string>(defaultLocale)
const messages = messagesMap[locale]
const dir = getDirection(locale)
useEffect(() => {
const html = document.documentElement
html.lang = locale
html.dir = dir
}, [locale, dir])
return (
// ... return here ...
);
}What this does:
en to ar, html lang="en" dir="ltr" becomes html lang="ar" dir="rtl".Our demo layout is very neutral: centered column, no explicit left/right alignment, so it survives RTL pretty well. In real apps, though, you'll often have things like:
For RTL-friendly CSS, aim for:
dir="rtl" to catch weird layout issuesMost users never touch a language switcher. They rely on the browser to tell websites which languages they prefer. React-intl doesn't auto-detect this for you, but grabbing that preference is easy, as long as you add proper fallback logic.
Our goal is:
"en").Modern browsers expose the user's preferred languages as an ordered list.
navigator.languages // e.g. ["fr-CA", "fr", "en-US", "en"]
navigator.language // e.g. "fr-CA"navigator.languages is the better one because it gives multiple fallback options.
Your translation files are named like: en.json, fr.json, and so on. But browser locales may come as: en-US, fr-CA, etc.
So we normalize them to their base language:
// src/i18n/locales.ts
function normalizeLocale(locale: string): string {
return locale.toLowerCase().split('-')[0]
}Create a helper in src/i18n/locales.ts:
// src/i18n/locales.ts
export function detectUserLocale(): string {
const browserLocales =
navigator.languages && navigator.languages.length > 0
? navigator.languages
: [navigator.language]
for (const raw of browserLocales) {
const base = normalizeLocale(raw)
if (supportedLocales.includes(base)) {
return base
}
}
return defaultLocale
}
function normalizeLocale(locale: string): string {
return locale.toLowerCase().split('-')[0]
}What this does:
fr-CA → fr).defaultLocale if none match.This means:
Update Root.tsx:
// src/Root.tsx
import { useEffect, useState } from "react";
import { IntlProvider } from "react-intl";
import App from "./App";
import { LanguageSwitcher } from "./i18n/LanguageSwitcher";
import { messagesMap, getDirection, detectUserLocale } from "./i18n/locales";
export function Root() {
const initial = detectUserLocale();
const [locale, setLocale] = useState(initial);
const messages = messagesMap[locale];
const dir = getDirection(locale);
useEffect(() => {
const html = document.documentElement;
html.lang = locale;
html.dir = dir;
}, [locale, dir]);
return (
// ... your return ...
);
}Use navigator.languages instead of navigator.language: you get the user’s full preference list.
Normalize locale codes (pt-BR → pt, en-GB → en) so they match your file structure.
Don't rely on geolocation! Users travel, use VPNs, or live abroad; location ≠ language.
Always fallback to a safe default locale if you can’t match anything.
Never break the UI on unknown locales (yes, some people actually have tlh-KLINGON).
Let the user’s manual choice override auto-detection every time.
Detect locale once at startup and keep it stable; don’t re-detect during rendering.
Make switching easy because some users intentionally jump between languages.
Auto-detecting the user's locale is nice for the first visit, but after that you should respect the user's choice. If they manually switch from English to French, the app should remember it, even after a page refresh.
Our goal:
In src/i18n/locales.ts, add:
const STORAGE_KEY = 'app-locale'
export function loadStoredLocale(): string | null {
try {
return localStorage.getItem(STORAGE_KEY)
} catch {
return null
}
}
export function storeLocale(locale: string): void {
try {
localStorage.setItem(STORAGE_KEY, locale)
} catch {
// ignore storage errors (private mode, disabled cookies, etc.)
}
}This safely interacts with localStorage without blowing up if storage is blocked.
We combine three sources:
Let's add this function:
export function getInitialLocale(): string {
// 1. User preference (if valid)
const saved = loadStoredLocale()
if (saved && supportedLocales.includes(saved)) {
return saved
}
// 2. Browser preference
const detected = detectUserLocale()
if (supportedLocales.includes(detected)) {
return detected
}
// 3. Hard fallback
return defaultLocale
}In Root, replace your old locale initialization:
// src/Root.tsx
// Make sure to update imports:
import { messagesMap, getDirection, getInitialLocale, storeLocale } from "./i18n/locales";
// ...
// And inside the function:
const initial = getInitialLocale()
const [locale, setLocale] = useState(initial)And anytime locale changes, store it:
useEffect(() => {
storeLocale(locale);
}, [locale]);Now the app:
html lang and dir properlyAll the good stuff.
If your app supports more than a couple of languages, loading all translation files upfront is a waste. In a Vite + React app you can:
We’ll use import.meta.glob with dynamic imports to do that. Update src/i18n/locales.ts:
// src/i18n/locales.ts
const STORAGE_KEY = 'app-locale'
const messageModules = import.meta.glob('./messages/*.json')
type Messages = Record<string, string>
export async function loadMessages(locale: string): Promise<Messages> {
const key = `./messages/${locale}.json`
const loader = messageModules[key]
if (!loader) {
throw new Error(`No messages found for locale "${locale}"`)
}
const mod = (await loader()) as { default: Messages }
return mod.default
}
// Discover supported locales from file names
const localeFromPathRegex = /\.\/messages\/([a-z0-9-]+)\.json$/i
export const supportedLocales: string[] = Object.keys(messageModules)
.map((path) => {
const match = path.match(localeFromPathRegex)
return match ? match[1] : null
})
.filter((v): v is string => Boolean(v))
.sort()
export const defaultLocale =
supportedLocales.includes('en') ? 'en' : supportedLocales[0] ?? 'en'
// ... getDirection, locale detection, and local storage-related functions stay in place ...What changed compared to the eager version:
en.json, fr.json, ar.json directly.loadMessages(locale) dynamically imports only the requested locale file.supportedLocales is still derived from file names, but now we use the keys from messageModules.Now we need to:
getInitialLocale()),IntlProvider and the rest of the app.We’ll keep this logic in Root, so update src/Root.tsx:
// src/Root.tsx
import { useEffect, useState } from "react";
import { IntlProvider } from "react-intl";
import App from "./App";
import { LanguageSwitcher } from "./i18n/LanguageSwitcher";
import {
getDirection,
getInitialLocale,
loadMessages,
storeLocale,
} from "./i18n/locales";
type LocaleState = {
locale: string;
messages: Record<string, string> | null;
loading: boolean;
error: string | null;
};
export function Root() {
const [state, setState] = useState<LocaleState>(() => ({
locale: getInitialLocale(),
messages: null,
loading: true,
error: null,
}));
const { locale, messages, loading, error } = state;
const dir = getDirection(locale);
// Load messages whenever locale changes
useEffect(() => {
let cancelled = false;
setState((prev) => ({ ...prev, loading: true, error: null }));
loadMessages(locale)
.then((msgs) => {
if (cancelled) return;
setState((prev) => ({
...prev,
messages: msgs,
loading: false,
error: null,
}));
storeLocale(locale);
})
.catch((err) => {
if (cancelled) return;
setState((prev) => ({
...prev,
loading: false,
error: err instanceof Error ? err.message : String(err),
}));
});
return () => {
cancelled = true;
};
}, [locale]);
// Keep <html> in sync
useEffect(() => {
const html = document.documentElement;
html.lang = locale;
html.dir = dir;
}, [locale, dir]);
const handleLocaleChange = (nextLocale: string) => {
if (nextLocale === locale) return;
setState((prev) => ({
...prev,
locale: nextLocale,
}));
};
if (loading || !messages) {
return (
<div
style={{
maxWidth: 600,
margin: "2rem auto",
fontFamily: "system-ui, sans-serif",
}}
>
<p>Loading translations…</p>
</div>
);
}
if (error) {
return (
<div
style={{
maxWidth: 600,
margin: "2rem auto",
fontFamily: "system-ui, sans-serif",
}}
>
<p>Failed to load translations: {error}</p>
</div>
);
}
return (
<IntlProvider locale={locale} messages={messages}>
<div
style={{
maxWidth: 600,
margin: "2rem auto",
fontFamily: "system-ui, sans-serif",
}}
>
<LanguageSwitcher locale={locale} onChange={handleLocaleChange} />
<App />
</div>
</IntlProvider>
);
}What’s happening:
getInitialLocale() but messages is null until we finish loading.loadMessages(locale), update messages, and store the locale in localStorage.html lang and dir on every locale change.Good news: LanguageSwitcher doesn’t care if messages are lazy or eager. It only needs:
onChange(locale) callback.So you can keep it exactly as it was.
Short version:
xx.json file is usually enough.So far we've used FormattedMessage and friends to render translated text directly inside JSX. That works great for simple UI, but real apps often need translated values inside logic, not just as JSX elements. That’s where the useIntl hook comes in.
Take advantage of useIntl when you need translations as values, for example:
aria- labels or metadataBasically:
FormatteduseIntl()formatMessage, formatNumber, formatDate, formatTimeThe hook gives you an intl object:
import { useIntl } from 'react-intl'
const intl = useIntl()Now you can format anything:
Messages:
const label = intl.formatMessage({ id: 'app.buttons.save' })Numbers
const amount = intl.formatNumber(total, {
style: 'currency',
currency: 'USD'
})Dates and times
const lastSeen = intl.formatDate(date, { dateStyle: 'medium' })
const time = intl.formatTime(date, { timeStyle: 'short' })You get the same locale-aware results as <FormattedNumber /> et al., but now it's all available in your logic layer.
If you're just rendering static text inside JSX, FormattedMessage is simpler:
<FormattedMessage id="app.header.title" />Stick to useIntl only when you need values, not components.
Sometimes your translations aren’t just plain text. You might need to style part of a sentence, insert a link, wrap something in strong, or even drop in a React component without hardcoding markup inside your messages. React-intl solves this with pseudo-tags and value functions.
The idea: Your translation contains tags like <bold> or <link>. Not real HTML, just markers. Then you tell react-intl how to render them.
Example message:
{
"app.learnMore": "Click <link>here</link> to learn more."
}Rendering it:
<FormattedMessage
id="app.learnMore"
values={{
link: (chunks) => <a href="/docs">{chunks}</a>
}}
/>React-intl replaces <link> with whatever function you provide. chunks is the text between the tags.
Everything is easy when you have en.json, fr.json, ar.json and 20 translation keys. But once you start dealing with:
Here are the patterns real-world apps use these days.
Instead of this:
src/i18n/messages/en.json
src/i18n/messages/fr.json
src/i18n/messages/ar.jsonUse this structure:
src/i18n/messages/
en/
common.json
homepage.json
dashboard.json
errors.json
fr/
common.json
homepage.json
dashboard.json
errors.json
ar/
common.json
homepage.json
dashboard.json
errors.jsonAdvantages:
Then you slightly change your loader. Instead of scanning messages/*.json, you scan messages/LOCALE/*.json. Vite makes that easy:
// src/i18n/locales.ts
// A single locale bundle in our app is just a flat key -> string map
// (react-intl expects messages in this shape).
type Messages = Record<string, string>
// Vite will turn this into a map of lazy import functions.
// Keys look like: "./messages/en/common.json", "./messages/fr/errors.json", etc.
const messageModules = import.meta.glob('./messages/*/*.json') as Record<
string,
() => Promise<{ default: Messages }>
>
// We store locales in directory names, e.g. "./messages/en/common.json" -> "en"
const localeDirRegex = /\.\/messages\/([a-z0-9-]+)\//i
// Build the list of supported locales by scanning all matched file paths,
// extracting the locale directory name, then deduping via Set.
export const supportedLocales: string[] = Array.from(
new Set(
Object.keys(messageModules)
.map((path) => path.match(localeDirRegex)?.[1] ?? null)
.filter((v): v is string => Boolean(v))
)
).sort()
// Load ALL namespace JSON files for a given locale (e.g. en/common.json + en/errors.json)
// and merge them into a single messages object for react-intl.
export async function loadMessages(locale: string): Promise<Messages> {
// Only match files inside the selected locale folder.
const prefix = `./messages/${locale}/`
// Get all loaders for that locale.
const loaders = Object.entries(messageModules).filter(([path]) =>
path.startsWith(prefix)
)
// If there are no files for this locale, we can't load it.
if (loaders.length === 0) {
throw new Error(`No messages found for locale "${locale}"`)
}
// Dynamically import every namespace file for this locale.
const modules = await Promise.all(loaders.map(([, loader]) => loader()))
// Merge all namespaces into one flat object.
// Note: if two namespaces reuse the same key, the later one will overwrite the earlier one.
return Object.assign({}, ...modules.map((m) => m.default))
}When you use messages/LOCALE/NAMESPACE.json, the locale comes from the folder name. At runtime we load every JSON file inside that locale folder (like messages/fr/*), merge them into one flat object, and pass that to IntlProvider. So you keep translations split into sane chunks, but react-intl still gets the single messages map it expects.
If your team is bigger than one developer, or you support more than 3–4 languages, hand-editing JSON isn’t just annoying, it becomes a source of bugs and missed translations.
Modern teams use a TMS like Lokalise:
TMS ≠ luxury. TMS = “I don’t want to break the whole app because someone forgot a comma in fr.json.”
Good message keys are:
dashboard.welcomeMessageBad keys generate translator pain and future tech debt.
If your team uses inline ICU in code, consider automatic extraction tools:
FormattedMessage id="...".This prevents “translation drift” when one locale has 250 keys and another has 237 because someone forgot to add something.
When your app grows, loading all languages and all namespaces is expensive. The scalable pattern:
Example:
/dashboard → load dashboard.json/settings → load settings.json/billing → load billing.json only when that route opensThis keeps your bundle small and initial load fast.
Big teams need shared rules so translations don’t turn into chaos. A typical i18n guidelines doc includes:
When your app starts growing, consistency becomes a real problem. Teams often end up with:
This is where proper TMS tooling makes a huge difference. A system like Lokalise gives you:
Define canonical translations for important words (“user”, “profile”, “billing”, “admin dashboard”, etc.). Translators never guess; they follow the glossary.
Set a consistent tone of voice, formality level, punctuation rules, capitalization rules, emoji policy, and UI wording conventions.
This ensures that all translations sound like one product, not fifty people freelancing blindfolded.
Any sentence translated once becomes a stored memory. Next time a similar string appears, the TMS suggests the existing translation. This:
Modern TMS platforms (including Lokalise) let AI:
This is exponentially better than “AI but raw.”
When your app supports 10+ locales, consistency is more important than speed. Glossaries, style guides, TM, and context-aware AI:
When you localize a real product, translating code strings isn’t enough. The real trouble starts earlier: at the design stage. Text expands, contracts, moves differently in RTL, and sometimes just breaks the layout. Connecting your design tool (Figma) with a TMS like Lokalise makes the whole workflow smoother and far less painful.
If you design in English only and translate at the end, you get the classic mess:
When you sync Figma with your TMS, you fix all of that upfront. You can:
Designers, developers, and translators finally work on the same page instead of guessing what each other meant.
Strings without context force translators to guess. Guessing leads to:
Once your Figma ↔ Lokalise pipeline is running:
src/i18n/messages/LOCALE foldersAt this point you’ve got a modern setup that actually holds up in real apps: clean message structure, proper plurals and formatting, RTL support, locale detection with safe fallbacks, a language switcher, persistence, and lazy-loaded translation bundles. From here, the main work is just adding more messages and keeping your translation workflow consistent as the project grows.
Thank you for staying with me, and until next time!
If you want a stable, standards-based solution with strong ICU formatting, pick react-intl. If you need a plugin-heavy ecosystem (language detection, backend loaders, tons of integrations), react-i18next is often a better fit.
react-intl focuses on ICU message formatting and the Intl API. react-i18next is more ecosystem-driven and flexible, especially for async translation loading and plugin-based features.
Yes. It’s mature, actively maintained, works well with React + Vite, and handles plurals, dates, numbers, and currency reliably via Intl.
Lingui is often the simplest to start with if you want low runtime overhead and a dev-friendly workflow.
No. You can bundle JSON files with your app, or lazy-load them on demand to keep the initial bundle smaller.
Yes. ICU is the safest way to handle plurals, gender, and locale-specific rules without writing language logic in your components.
Keep the current locale in React state, swap the messages passed to IntlProvider, and persist the choice (localStorage is the common default).
Use navigator.languages, normalize locale codes (fr-CA → fr), and always fall back to a default if the locale isn’t supported.
It supports RTL text formatting, but you must set dir="rtl" and update html lang="ar" yourself when switching locales.
Use Vite dynamic imports (import.meta.glob) to load only the initial locale on startup, then fetch other locales when the user switches.
Author
Ilya is the lead for content, documentation, and onboarding at Lokalise, where he focuses on helping engineering teams build reliable internationalization workflows. With a background at Microsoft and Cisco, he combines practical development experience with a deep understanding of global product delivery, localization systems, and developer education.
He specializes in i18n architectures across modern frameworks — including Vue, Angular, Rails, and custom localization pipelines — and has hands-on experience with Ruby, JavaScript, Python, Elixir, Go, Rust, and Solidity. His work often centers on improving translation workflows, automation, and cross-team collaboration between engineering, product, and localization teams.
Beyond his role at Lokalise, Ilya is an IT educator and author who publishes technical guides, best-practice breakdowns, and hands-on tutorials. He regularly contributes to open-source projects and maintains a long-standing passion for teaching, making complex internationalization topics accessible to developers of all backgrounds.
Outside of work, he keeps learning new technologies, writes educational content, stays active through sports, and plays music. His goal is simple: help developers ship globally-ready software without unnecessary complexity.
In our previous discussions, we explored localization strategies for backend frameworks like Rails and Phoenix. Today, we shift our focus to the front-end and talk about JavaScript translation and localization. The landscape here is packed with options, which makes many developers a
In this guide, we’ll walk through building a fully automated translation pipeline using GitLab CI/CD and Lokalise. From upload to download, with tagging, version control, and merge requests. Here’s the high-level flow: Upload your source language files (e.g. English JSON files) to Lokalise from GitLab using a CI pipeline.Tag each uploaded key with your Git branch name. This helps keep translations isolated per feature or pull request
Internationalization can sometimes feel like a massive headache. Juggling multiple JSON files, keeping translations in sync, and redeploying every time you tweak a string… What if you could offload most of that grunt work to a modern toolchain and let your CI/CD do the heavy lifting? In this guide, we’ll wire up a Next.js 15 project hosted on Vercel. It will load translation files on demand f
Behind the scenes of localization with one of Europe’s leading digital health providers
Read more Case studies
Localization workflow for your web and mobile apps, games and digital content.
©2017-2026
All Rights Reserved.
