Shipping an English-only UI is fine until the first Arabic, Hebrew or Urdu customer opens it and sees a left-to-right layout with hardcoded strings. React internationalization is the work of keeping copy in message catalogs, selecting a locale at runtime, and flipping the document direction for RTL scripts. This post builds a small, tested set of helpers for those three jobs, then shows how they sit in a React tree.
It fits the front-end layering in my guide to structuring large React applications: locale and copy belong in a dedicated module, not sprinkled through components as raw strings. For locale-aware URLs and hreflang, I already wrote a separate post on internationalized routing in Next.js; this one is about the messages and the RTL direction once you are on a page.
What this post covers
- Tested versions
- Message catalogs
- Translating and choosing direction
- A React provider that sets lang and dir
- RTL support for Arabic UIs
- Where next-intl fits in a Next.js app
- FAQ
Tested versions
| Tool | Version |
|---|---|
| React | 19.3.1 |
| react-dom | 19.3.1, renderToString from react-dom/server |
| Node.js | v24.22.1 |
| Tests | test-i18n.mjs: direction, interpolation, catalogs, English and Arabic markup — all passing |
The copy in the sample catalogs is invented UI text for a deals list, not client or product copy. The Arabic strings were written for the test and checked so the markup assertions match them exactly.
Message catalogs
A message catalog is a flat map of stable keys to strings, one file (or object) per locale. Keys stay the same across languages; only the values change. Interpolation uses {name} placeholders so a translator can move the number or the name in the sentence, which matters in Arabic as much as in English.
/** Example product-UI catalogs used in the tests. Not client copy. */
export const catalogs = {
en: {
"deal.heading": "Deals",
"deal.openCount": "{count} open deals",
"deal.save": "Save",
"deal.cancel": "Cancel",
},
ar: {
"deal.heading": "الصفقات",
"deal.openCount": "{count} صفقات مفتوحة",
"deal.save": "حفظ",
"deal.cancel": "إلغاء",
},
};
I keep keys dotted by feature, not by the English sentence. If the English copy changes, the key should not. Missing keys should fail loudly in development, not silently fall back to the raw key in production UI. The translator below throws if a key is absent from both the active locale and the fallback.
Translating and choosing direction
Three functions do the non-React work, so they can be unit-tested without mounting a component. directionFor maps a locale tag to ltr or rtl. interpolate fills placeholders and leaves unknown ones visible. createTranslator binds a locale to a catalog and returns t, dir and locale.
/**
* Small i18n helpers for React: message catalogs, interpolation,
* and document direction for RTL locales such as Arabic.
*/
export const RTL_LOCALES = new Set([
"ar", "ar-SA", "ar-EG", "ar-AE", "he", "he-IL", "fa", "fa-IR", "ur", "ur-PK",
]);
export function languageOf(locale) {
return String(locale || "").split("-")[0].toLowerCase();
}
export function directionFor(locale) {
const tag = String(locale || "").toLowerCase();
if (RTL_LOCALES.has(tag) || RTL_LOCALES.has(languageOf(tag))) return "rtl";
return "ltr";
}
/**
* Replace {name} placeholders. Unknown placeholders are left intact
* so a missing value is obvious in a screenshot or test.
*/
export function interpolate(template, values = {}) {
return String(template).replace(/\{(\w+)\}/g, (match, key) =>
Object.prototype.hasOwnProperty.call(values, key) ? String(values[key]) : match
);
}
export function createTranslator(catalogs, locale, fallbackLocale = "en") {
const messages = catalogs[locale] || catalogs[fallbackLocale] || {};
const fallback = catalogs[fallbackLocale] || {};
function t(key, values) {
const raw = messages[key] ?? fallback[key];
if (raw == null) throw new Error(`Missing translation: ${key} (${locale})`);
return interpolate(raw, values);
}
return {
locale,
dir: directionFor(locale),
t,
};
}
RTL is a property of the writing system, not of the country. ar, ar-SA and he are all RTL in this list. If you add a locale, add it to RTL_LOCALES (or to a more complete library list) rather than guessing from the region subtag.
A React provider that sets lang and dir
The provider creates a translator once per locale, puts it on React context, and wraps children in an element with lang and dir set. That is what makes the browser, CSS logical properties and assistive tech agree on direction. A T component is a thin wrapper around t() for use in JSX.
The tested module uses createElement so Node can run it without a JSX transform. The equivalent JSX looks like this:
<I18nProvider catalogs={catalogs} locale={locale}>
<DealHeading count={4} />
</I18nProvider>
// inside the provider:
<div lang={locale} dir={i18n.dir} data-locale={locale}>
{children}
</div>
I rendered that tree with renderToString. For locale="en" the markup includes lang="en", dir="ltr", the heading “Deals” and “4 open deals”. For locale="ar" it includes lang="ar", dir="rtl", “الصفقات” and “4 صفقات مفتوحة”, and it does not include dir="ltr".
Forms in a translated UI still need the same validation rules you would use in English. The pattern in my post on React Hook Form with Zod works alongside this: keep schema keys stable, put the user-facing messages through t(). Server state, as in TanStack Query, should stay in a canonical locale (usually your API’s language) and only be formatted at the edge of the UI.
RTL support for Arabic UIs
Setting dir="rtl" on the wrapper is the required start, not the whole job. Use CSS logical properties — margin-inline-start instead of margin-left, inset-inline-end instead of right — so spacing and alignment flip with the direction. Icons that imply a direction (a chevron for “next”) should also flip; decorative icons that have no direction should not.
Input fields for email addresses, URLs and numbers often stay left-to-right even inside an Arabic page. You can set dir="ltr" on those controls without changing the page direction. Isolated Latin words inside Arabic copy usually follow the Unicode bidirectional algorithm once the parent dir is correct; test the actual strings, especially mixed names and IDs.
Do not implement RTL by translating the whole layout with transform: scaleX(-1). It mirrors images, breaks shadows and is a headache for screenshots and tests. Direction on the document, logical CSS, and a catalog are enough for a clean first version.
Where next-intl fits in a Next.js app
In a Next.js App Router project, next-intl is a common way to load catalogs per locale, hook them into server components, and work with the locale segment you already set up for routing. The helpers in this post are deliberately small and library-agnostic: you can use them as-is in a Vite or CRA tree, or treat them as the model of what next-intl is doing for you — catalogs, a t function, and a dir value you put on <html>.
If you adopt next-intl, put dir and lang on the root layout from the active locale, keep catalogs in a single folder, and do not duplicate routing logic that already lives in the hreflang post. The policy I care about is the same either way: no raw user-facing strings in components, and RTL is a first-class locale property, not a CSS afterthought.
FAQ
Should dir go on the html element or a wrapper?
On the html element in a real app, so the whole page including portals and dialogs inherits it. The tests use a wrapper div because they render a subtree with renderToString. The attribute and the value are the same.
What if a key is missing in Arabic but present in English?
The translator falls back to the fallback locale (English here) and still returns a string. If the key is missing in both, it throws. That is deliberate: a missing English source string is a bug, not something to hide.
Do I have to use next-intl?
No. next-intl is a good fit for the Next.js App Router. The catalog-plus-direction model works with other libraries, or with the small helpers in this post, as long as one module owns the locale.
Does RTL require a different font?
You need a font that actually contains the Arabic (or Hebrew, or Urdu) glyphs you display. That is a font-loading concern, not a direction concern. Direction and glyphs are separate; you need both.
I’m Shahrukh Akhtar (Shaz3e), CTO & Co-Founder of Diligent Creators Pvt. Ltd., a Technology Executive & Product Builder. I run client delivery and build SaaS products, including EloSync. You can find me on X, LinkedIn, Peerlist and GitHub.
