Skip to content
Derar Sattouf

Adding Arabic and RTL to a Next.js App Router Site

Next.js & frontend

This site is now in English and Arabic. The English addresses did not move: /about is still /about, and the Arabic page is /ar/about. Blog posts stay English only.

I have built right-to-left interfaces before, for storefronts and for the Arabic point-of-sale apps in Pythagoras Apps, so I expected the CSS work. What I did not expect was how many small things in a Next.js App Router project quietly assume one language. This is the list, in the order I hit them.

One document per language

The resume builder on this site already had an Arabic page. It set lang="ar" and dir="rtl" on a wrapper div, inside a document whose root element still said <html lang="en">. That works visually. It is also wrong in two ways: a screen reader starts in the wrong language, and anything rendered in a portal outside the wrapper (dialogs, toasts) comes out left-to-right.

The language belongs on <html>, and in the App Router that element lives in the root layout. A root layout cannot read the pathname, so one root layout cannot serve two languages unless the language is a route parameter.

The documented way is to move everything under app/[lang]/ and use the proxy to send /about to /en/about. I did not want every English request to pass through a rewrite just to keep URLs that already worked. So the site has two root layouts instead:

app/
  (en)/layout.tsx     <html lang="en" dir="ltr">   everything without a prefix
  ar/layout.tsx       <html lang="ar" dir="rtl">   everything under /ar
  globals.css
  sitemap.ts, robots.ts, api/

Both layouts render the same shell component and pass it a locale:

export default function ArabicRootLayout({ children }: LayoutProps<"/ar">) {
  return (
    <RootShell locale="ar" fontClassName={arabicFont.variable}>
      {children}
    </RootShell>
  );
}

The pages are shared too. HomePage, AboutPage and the rest take a locale prop, and each route file is five lines that picks one. The route group (en) does not appear in URLs, so moving the English routes into it changed no address.

The cost is that switching language is a full page load, because the two halves of the site do not share a root layout. For a language switch that is fine, and I use a plain <a> for it so nobody expects otherwise.

The 404 that stopped rendering

This one is not in most RTL guides.

Before the change, an unknown URL returned my styled 404 page as normal server-rendered HTML. After removing app/layout.tsx, the same URL returned a 404 status with this:

<html id="__next_error__">

The page still appeared in a browser, because the client rendered it. The HTML a crawler received was an empty error shell. With two root layouts there is no single layout to build the "no route matched" page from, so the framework falls back.

Next.js 16 has an answer, behind an experimental flag: a global-not-found.tsx file at the root of app/ that returns the whole document itself.

// next.config.ts
experimental: { globalNotFound: true }
// app/global-not-found.tsx
import "./globals.css";

export default function GlobalNotFound() {
  return (
    <RootShell locale="en">
      <NotFoundPage locale="en" />
    </RootShell>
  );
}

It bypasses layouts, so it has to import the global stylesheet and render the header and footer on its own. Unknown English URLs are server-rendered again. I checked with curl, not with a browser, because the browser hides exactly this problem.

If you split a site into several root layouts for any reason, test an address that does not exist before you ship.

Hreflang, and what it is not for

Each translated page declares its alternates in metadata:

alternates: {
  canonical: "/ar/about",
  languages: { en: "/about", ar: "/ar/about", "x-default": "/about" },
}

Three rules from Google's documentation shaped the code:

  • Every version lists itself and all the others. If two pages do not point at each other, the annotations are ignored. I generate the map from one function so the English and Arabic pages cannot disagree.
  • URLs must be fully qualified. Next.js resolves the relative paths above against metadataBase, so the rendered tags are absolute.
  • Only pages that exist in both languages get the annotation. Blog posts have no Arabic version, so they have no hreflang at all. Pointing hreflang="ar" at an English page is worse than saying nothing.

The same alternates go into the sitemap, where each language is its own <url> entry with xhtml:link children.

One thing that is easy to get wrong: Google does not use hreflang or the lang attribute to work out what language a page is in. It reads the content. The lang and dir attributes are for browsers and assistive technology, and hreflang is for choosing between versions it already understands. So a half-translated page gains nothing from correct tags. That is why the Arabic tools index lists only the toolkits, and not sixty links to tool pages that are still in English.

CSS: logical properties, and two things that are not about direction

Most of the mirroring is mechanical. Every physical property becomes a logical one:

.prose ul { padding-inline-start: 1.4em; }      /* was padding-left */
.prose blockquote { border-inline-start: 2px solid var(--primary); }
.prose th { text-align: start; }                 /* was left */

In Tailwind that means ms-, ps-, start- and text-start in place of ml-, pl-, left- and text-left. Flex and grid layouts mirror on their own. Arrows that mean "forward" need rtl:rotate-180, and a timeline dot that was centered on a left border with -translate-x-1/2 needs the opposite translation in RTL.

Two problems had nothing to do with direction.

Letter spacing breaks Arabic. My headings use tight tracking and my small labels use wide tracking. Arabic letters join, and any letter spacing pulls the joins apart or crushes them. I already had a base rule setting letter-spacing: 0 for Arabic, but Tailwind's tracking utilities sit in a later cascade layer and won. The fix is blunt:

:lang(ar) {
  letter-spacing: 0 !important;
}

:lang(ar) matches every element in an Arabic subtree, and English fragments inside it opt out by carrying lang="en".

The heading font had no Arabic letters. Headings use a Latin serif. In Arabic the browser silently fell back to a system font for them, so headings and body text were in two unrelated typefaces. Because the font utilities read CSS variables, I override the variables once:

[lang="ar"] {
  --font-sans: var(--font-arabic), ui-sans-serif, system-ui, sans-serif;
  --font-serif: var(--font-arabic), ui-serif, serif;
  --font-mono: var(--font-jetbrains), var(--font-arabic), ui-monospace, monospace;
}

Code keeps its monospace face and falls back to the Arabic one for Arabic words inside it. The Arabic font is loaded only by the Arabic root layout, so English pages do not preload it.

Small things that assumed English

  • Heading anchors. The slug function stripped everything outside \w, which removes every Arabic letter, so all Arabic headings got an empty id. The class is now [^\p{L}\p{N}_-] with the u flag.
  • Dates. toLocaleString("ar") can return Arabic-Indic digits. The pages mix dates with figures like "10+" and "60%", so I use the ar-u-nu-latn locale to keep one set of digits.
  • Mixed content. The Arabic home page lists the latest posts, which are in English. That list carries lang="en" dir="ltr", so titles align and punctuate correctly. The same goes for my name, which stays in Latin script.
  • Analytics sections. Events are labeled by site section from the pathname. /ar/tools did not start with /tools, so it would have been counted as portfolio traffic. The prefix is now stripped first.

Translations hold text and nothing else

An Arabic case study is a file with a title, a summary and a body. Dates, images, links and ordering are always read from the English file:

return {
  ...post,
  content,
  locale,
  metadata: { ...post.metadata, title: data.title, summary },
};

Two files that both carry a publish date will disagree within a month. With this shape there is nothing to keep in sync except the words. A project without a translation falls back to English and marks its own lang, so the page is still correct.

The legal pages are translated as well, with a line at the top saying the English text is the one that counts. I am comfortable translating a privacy policy. I am not comfortable having two of them that could be argued against each other.

What I check after it ships

Search Console has no hreflang report any more, so I verify the annotations myself and use the console for the outcome:

  • curl an English page and its Arabic twin and confirm each lists both URLs plus x-default.
  • In URL Inspection, the Google-selected canonical for /ar/about should be /ar/about. If Google picks the English URL, it has decided the two pages are duplicates, which usually means the translation is too thin.
  • In the Pages report, Arabic URLs should not pile up under "Alternate page with proper canonical tag" or "Duplicate, Google chose different canonical than user".
  • In the Performance report, filter by pages containing /ar/ once there is data. Arabic queries are the reason to do any of this.

The Arabic pages are days old as I write, so I have no ranking numbers to show, and I would not trust anyone who had them this early. What I can say is that the English pages kept their URLs, titles and content, and that was the constraint I cared most about.

The rest of the metadata setup is in the Next.js technical SEO checklist. The Arabic version of this site starts at derar.dev/ar.

Sources