Catalog My learning Blog
Frontend Developer Course: 100 Concepts in 100 Days · Phase 10 · Lesson 99 · 6 min read

Internationalization (i18n): Intl API and RTL Layouts

On this page
  1. Learning Objective
  2. Concept Explanation
  3. Worked Example: Messages, Formatting and Direction in a React App
  4. Real-World Examples
  5. Review Questions & Answers

Learning Objective

Prepare an application for multiple languages and regions: externalize messages with ICU MessageFormat for plurals and gender, format dates, numbers, currencies and lists with the Intl APIs, support right-to-left scripts with logical CSS and the dir attribute, handle text expansion and fonts, and choose how locales are detected and stored.

Concept Explanation

Internationalization, i18n, is engineering an application so it can be adapted to languages and regions without code changes; localization, l10n, is the adaptation itself: translations, formats and cultural details. Retrofitting i18n into an existing product is expensive, because language assumptions hide in every string concatenation, date format and layout. Building with i18n in mind from the start costs little, even if only one language ships at first.

The first rule is that user-facing text lives in message catalogs, not in components, and that messages are whole sentences with placeholders rather than fragments glued together. Word order differs between languages, so "You have " + n + " new messages" cannot be translated correctly. Plurals are harder than they look: English has two forms, one and other, but Arabic has six plural categories, Polish distinguishes few and many, and Japanese has only one. ICU MessageFormat expresses this declaratively, as in {count, plural, one {# new message} other {# new messages}}, with select for gender or other variants, and libraries such as FormatJS with react-intl, i18next with its ICU plugin, and Lingui implement it. Intl.PluralRules exposes the rules directly.

Values must be formatted for the locale, never by hand. Intl.DateTimeFormat formats dates and times with the right order, month names, calendar, 12 or 24 hour clock and time zone. Intl.NumberFormat handles decimal and grouping separators, percentages, units, compact notation and currencies, for example 1.234,56 € in German and €1,234.56 in Irish English. Intl.RelativeTimeFormat produces phrases such as 3 days ago, Intl.ListFormat joins lists with the right conjunction, and Intl.Collator sorts strings correctly for a language, since sorting by code point puts accented letters in the wrong place. Store dates in UTC and amounts with their currency, and format only at display time.

Right-to-left scripts such as Arabic, Hebrew, Persian and Urdu mirror the whole layout. Set lang and dir="rtl" on the html element, and the browser flips text direction, the order of inline content and the starting side of layouts. Your CSS should use logical properties, margin-inline-start, padding-inline, inset-inline-end, text-align: start (Day 22), so layouts mirror automatically. Flexbox and grid already follow the writing direction. Directional icons such as arrows and progress indicators must be mirrored, while icons like a clock or a checkmark should not. User-generated content of unknown direction should use dir="auto", and the bdi element isolates names or values embedded in surrounding text so mixed-direction strings render correctly.

Design for text expansion: German and Finnish strings are often 30 to 40 percent longer than English, and short labels can double, so avoid fixed widths, test with pseudo-localization that lengthens and accents strings, and check that fonts include the needed glyphs. For locale selection, use an explicit choice stored in the user's profile or a cookie first, then the URL, such as /fr/ paths, which also helps search engines with hreflang annotations, and the Accept-Language header or navigator.languages only as a default. Never infer language from IP geography alone, and always let users change it.

ConcernToolExample
Messages and pluralsICU MessageFormat, Intl.PluralRules{count, plural, one {...} other {...}}
Dates and timesIntl.DateTimeFormatLocale order, time zones, calendars
Numbers and currencyIntl.NumberFormat1.234,56 € versus €1,234.56
Relative timeIntl.RelativeTimeFormatin 2 days, 3 hours ago
ListsIntl.ListFormatA, B, and C or A, B y C
SortingIntl.CollatorCorrect order for accented letters
Right-to-leftdir attribute, logical CSSmargin-inline-start, text-align: start
Mixed direction textbdi, dir="auto"User names inside sentences

Worked Example: Messages, Formatting and Direction in a React App

The provider loads messages for the active locale and sets the document language and direction. Components use ICU messages and Intl-based formatting instead of concatenation.

Code
// messages/en.json
{
  "inbox.unread": "{count, plural, =0 {No new messages} one {# new message} other {# new messages}}",
  "order.shipped": "{name} shipped your order on {date, date, medium}",
  "cart.total": "Total: {amount, number, ::currency/EUR}"
}
// messages/ar.json uses all six Arabic plural categories: zero, one, two, few, many, other
TypeScript
import { IntlProvider, FormattedMessage, useIntl } from 'react-intl';

const RTL = new Set(['ar', 'he', 'fa', 'ur']);

export function I18nRoot({ locale, messages, children }: { locale: string; messages: Record<string, string>; children: React.ReactNode }) {
  useEffect(() => {
    document.documentElement.lang = locale;
    document.documentElement.dir = RTL.has(locale.split('-')[0]) ? 'rtl' : 'ltr';
  }, [locale]);
  return <IntlProvider locale={locale} messages={messages} defaultLocale="en">{children}</IntlProvider>;
}

function InboxBadge({ count }: { count: number }) {
  return <FormattedMessage id="inbox.unread" values={{ count }} />;    // never 'You have ' + count + ...
}

function OrderLine({ seller, shippedAt }: { seller: string; shippedAt: string }) {
  return (
    <p>
      <FormattedMessage id="order.shipped"
        values={{ name: <bdi>{seller}</bdi>, date: new Date(shippedAt) }} />   {/* bdi isolates mixed-direction names */}
    </p>
  );
}

function PriceSummary({ items }: { items: string[] }) {
  const intl = useIntl();
  const list = new Intl.ListFormat(intl.locale, { type: 'conjunction' }).format(items);
  const sorted = items.toSorted(new Intl.Collator(intl.locale).compare);
  return <p title={sorted.join(', ')}>{list}</p>;
}
Code
/* Logical properties mirror automatically in right-to-left */
.card { padding-inline: 1rem; border-inline-start: 4px solid var(--color-accent); text-align: start; }
.icon-forward { transform: scaleX(1); }
[dir="rtl"] .icon-forward { transform: scaleX(-1); }       /* mirror directional icons only */

Switching the locale to Arabic flips the layout, the card's accent border moves to the right edge, plural messages pick the correct Arabic form and prices use Arabic number formatting, all without changing component code.

With ICU messages, Intl formatting and logical CSS, the same component renders correctly in English and Arabic: plurals use each language's categories, numbers and dates follow the locale, and the layout mirrors because spacing uses inline-start and inline-end.
With ICU messages, Intl formatting and logical CSS, the same component renders correctly in English and Arabic: plurals use each language's categories, numbers and dates follow the locale, and the layout mirrors because spacing uses inline-start and inline-end.

Real-World Examples

  • The Unicode Common Locale Data Repository, CLDR, provides the plural rules, date and number patterns and other locale data for hundreds of locales, and it is the data behind the browser Intl APIs, ICU libraries and the localization of major operating systems.
  • Wikipedia serves more than 300 language editions, including right-to-left languages such as Arabic, Hebrew and Persian, and its MediaWiki software uses CSSJanus to flip stylesheets for right-to-left interfaces automatically, a task that logical CSS properties now handle natively in the browser.
Key TakeawaysKeep every user-facing string in message catalogs as complete ICU messages, with plural and select rules instead of string concatenation. Format dates, numbers, currencies, lists and relative times with the Intl APIs. Set lang and dir, use logical CSS, mirror only directional icons and isolate mixed-direction text with bdi. Design for longer strings, test with pseudo-localization, and choose locales from explicit user choice and URLs before browser defaults.

Review Questions & Answers

Translators cannot reorder fragments, and different languages need different word orders and plural forms. Complete messages with placeholders and plural rules let each language express the whole sentence correctly.

Languages have different numbers of plural categories and different rules for which numbers use which form. English has two, Arabic has six including forms for zero, two, few and many, and Polish distinguishes few from many. ICU plural syntax and Intl.PluralRules handle these rules per locale.

Setting dir="rtl" and lang on the document, using logical CSS properties such as margin-inline-start and text-align: start instead of left and right, and relying on flexbox and grid, which follow the writing direction. Only directional icons need explicit mirroring.

Prefer an explicit choice saved in the user's settings or a cookie, then the locale in the URL, and use Accept-Language or navigator.languages only as an initial default. Always offer a visible way to change the language, and avoid inferring language from IP location.