Internationalization (i18n): Intl API and RTL Layouts
On this page
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.
| Concern | Tool | Example |
|---|---|---|
| Messages and plurals | ICU MessageFormat, Intl.PluralRules | {count, plural, one {...} other {...}} |
| Dates and times | Intl.DateTimeFormat | Locale order, time zones, calendars |
| Numbers and currency | Intl.NumberFormat | 1.234,56 € versus €1,234.56 |
| Relative time | Intl.RelativeTimeFormat | in 2 days, 3 hours ago |
| Lists | Intl.ListFormat | A, B, and C or A, B y C |
| Sorting | Intl.Collator | Correct order for accented letters |
| Right-to-left | dir attribute, logical CSS | margin-inline-start, text-align: start |
| Mixed direction text | bdi, 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.
// 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, otherimport { 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>;
}/* 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.
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.
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.