The Complete Guide to React Internationalization (i18n) in 2024

Introduction to React Internationalization

Building a React application for a global audience requires proper internationalization (i18n). This guide covers everything you need to know about implementing i18n in React applications, from basic setup to advanced patterns.

Why Internationalization Matters

Choosing an i18n Library

react-intl (FormatJS)

import { IntlProvider, FormattedMessage } from 'react-intl';

function App() {
  return (
    <IntlProvider messages={messages} locale="en">
      <FormattedMessage id="greeting" defaultMessage="Hello, World!" />
    </IntlProvider>
  );
}

Pros:

Cons:

react-i18next

import { useTranslation } from 'react-i18next';

function App() {
  const { t } = useTranslation();
  return <h1>{t('greeting')}</h1>;
}

Pros:

Cons:

next-intl (for Next.js)

import { useTranslations } from 'next-intl';

function HomePage() {
  const t = useTranslations('home');
  return <h1>{t('title')}</h1>;
}

Pros:

Setting Up Your Project

Step 1: Install Dependencies

npm install react-i18next i18next

Step 2: Create Translation Files

/locales
  /en
    common.json
    home.json
  /es
    common.json
    home.json
  /fr
    common.json
    home.json

Step 3: Configure i18next

// i18n.js
import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';

i18n
  .use(initReactI18next)
  .init({
    resources: {
      en: { translation: require('./locales/en/common.json') },
      es: { translation: require('./locales/es/common.json') },
    },
    lng: 'en',
    fallbackLng: 'en',
    interpolation: { escapeValue: false },
  });

export default i18n;

Step 4: Wrap Your App

import './i18n';

function App() {
  return (
    <Suspense fallback="Loading...">
      <YourApp />
    </Suspense>
  );
}

Advanced Patterns

Handling Pluralization

{
  "items": "You have {{count}} item",
  "items_plural": "You have {{count}} items"
}

t('items', { count: 5 }) // "You have 5 items"

Interpolation with Components

<Trans i18nKey="welcome">
  Welcome, <strong>{{name}}</strong>!
</Trans>

Context-Based Translations

{
  "friend": "A friend",
  "friend_male": "A boyfriend",
  "friend_female": "A girlfriend"
}

Lazy Loading Translations

i18n.use(Backend).init({
  backend: {
    loadPath: '/locales/{{lng}}/{{ns}}.json',
  },
});

Managing Translations at Scale

As your app grows, managing JSON files manually becomes painful:

The Solution: Translation Management Systems

A TMS like IntlPull solves these problems:

# Pull latest translations
npx intlpull pull

# Push new strings
npx intlpull push

# Scan code for hardcoded strings
npx intlpull scan

Benefits:

Best Practices

1. Extract All Strings

Never leave hardcoded text:

// Bad
<button>Submit</button>

// Good
<button>{t('form.submit')}</button>

2. Use Meaningful Keys

// Bad
{
  "text1": "Welcome",
  "text2": "Sign up"
}

// Good
{
  "home.hero.title": "Welcome",
  "auth.signup.button": "Sign up"
}

3. Include Context

{
  "save": "Save",
  "save_description": "Button to save user profile changes"
}

4. Handle RTL Languages

<div dir={isRTL ? 'rtl' : 'ltr'}>
  {children}
</div>

5. Format Dates and Numbers Properly

const formattedDate = new Intl.DateTimeFormat(locale).format(date);
const formattedPrice = new Intl.NumberFormat(locale, {
  style: 'currency',
  currency: 'USD',
}).format(price);

Common Mistakes to Avoid

Performance Optimization

Code Splitting Translations

const HomeTranslations = lazy(() => import('./locales/home'));

Using Suspense

<Suspense fallback={<Skeleton />}>
  <TranslatedComponent />
</Suspense>

Memoizing Formatted Values

const formattedPrice = useMemo(
  () => formatCurrency(price, locale),
  [price, locale]
);

Testing Internationalized Apps

// test-utils.js
import { render } from '@testing-library/react';
import { I18nextProvider } from 'react-i18next';
import i18n from './i18n-test';

function renderWithI18n(ui, locale = 'en') {
  i18n.changeLanguage(locale);
  return render(
    <I18nextProvider i18n={i18n}>{ui}</I18nextProvider>
  );
}

Conclusion

React internationalization doesn't have to be complex. Start with a solid foundation, follow best practices, and use the right tools to manage translations at scale.

Next steps:

Ready to simplify your React i18n workflow? Start your free IntlPull trial and manage translations like a pro.