Building a multilingual Next.js site with the App Router

A multilingual Next.js 16 site step by step: routes under app/[lang], a proxy, dictionaries, hreflang via metadata, RTL for Arabic and a language switcher.

By Sohail Hussain21 November 20265 min read

In Next.js 16 with the App Router, a multilingual site is built from a few pieces you write yourself: a [lang] dynamic segment that holds the root layout and every page, a proxy.ts file that sends unprefixed URLs to a language, dictionaries or CMS content per language loaded in Server Components, alternates.languages in the metadata for hreflang, and lang and dir attributes on the html element so Arabic renders right to left. There is no built-in i18n configuration for the App Router; the i18n option in next.config belongs to the Pages Router.

The code below follows the official internationalization guide and was built and tested with Next.js 16.4, as of October 2026. It is the structure we use for bilingual English and Arabic sites in our Arabic and multilingual websites work; why we build company websites with Next.js explains the choice of framework. The non-technical side of the same project, from fonts to translation, is in the guide to building an Arabic website.

How should the URLs and folders be laid out?

Start by choosing the languages and the URL pattern. The simplest pattern, and the one the Next.js guide uses, gives every language a prefix: /en/services and /ar/services. Every route then lives under one dynamic segment:

text
app/
  [lang]/
    layout.tsx
    page.tsx
    dictionaries.ts
    dictionaries/
      en.json
      ar.json
    services/
      page.tsx
  sitemap.ts
components/
  language-switcher.tsx
i18n.ts
proxy.ts

The root layout sits inside [lang], so there is no app/layout.tsx. Keep the language list in one file that the proxy, layouts and sitemap all import:

ts
// i18n.ts
export const locales = ["en", "ar"] as const;
export type Locale = (typeof locales)[number];
export const defaultLocale: Locale = "en";

export const isLocale = (value: string): value is Locale =>
  (locales as readonly string[]).includes(value);

export const dir = (locale: Locale) => (locale === "ar" ? "rtl" : "ltr");

// "/services" in Arabic is "/ar/services"; the home page is "/ar".
export const localePath = (locale: Locale, path: string) =>
  `/${locale}${path === "/" ? "" : path}`;

export function alternates(locale: Locale, path: string) {
  return {
    canonical: localePath(locale, path),
    languages: {
      en: localePath("en", path),
      ar: localePath("ar", path),
      "x-default": localePath(defaultLocale, path),
    },
  };
}

If you are adding Arabic to an existing English site, you may prefer to keep English unprefixed so no existing URL changes. That works too, with a rewrite instead of a redirect in the proxy; internationalised routing in Next.js has that version of the code. Subdomain vs subfolder vs ccTLD explains why a subfolder per language is the right default.

How does the proxy pick a language?

In Next.js 16 the middleware file convention is deprecated and renamed proxy. The proxy.ts reference covers the details. This one redirects any path without a language prefix to the default language:

ts
// proxy.ts
import { NextResponse, type NextRequest } from "next/server";
import { defaultLocale, locales } from "./i18n";

export function proxy(request: NextRequest) {
  const { pathname } = request.nextUrl;
  const hasLocale = locales.some(
    (locale) => pathname === `/${locale}` || pathname.startsWith(`/${locale}/`)
  );
  if (hasLocale) return;

  // /services -> /en/services. A fixed default, not a guess from the browser.
  request.nextUrl.pathname = `/${defaultLocale}${pathname === "/" ? "" : pathname}`;
  return NextResponse.redirect(request.nextUrl);
}

export const config = {
  // Skip Next.js internals, API routes and files with an extension (images, sitemap.xml).
  matcher: ["/((?!_next|api|.*\\..*).*)"],
};

The official guide shows a version that picks the language from the browser's Accept-Language header. That is reasonable for the bare homepage. Do not extend it to URLs that already contain a language: Google advises against redirecting people between language versions based on a guess, and a link someone shares should open in the language of the link. A fixed default plus a visible switcher is simpler and safer.

How do you load translations and set the direction?

The root layout sets lang and dir on the html element, loads both fonts, and lists the languages for static generation:

tsx
// app/[lang]/layout.tsx
import type { Metadata } from "next";
import { notFound } from "next/navigation";
import { IBM_Plex_Sans, IBM_Plex_Sans_Arabic } from "next/font/google";
import { dir, isLocale, locales } from "../../i18n";
import { LanguageSwitcher } from "../../components/language-switcher";

const latin = IBM_Plex_Sans({ subsets: ["latin"], variable: "--font-latin" });
const arabic = IBM_Plex_Sans_Arabic({
  subsets: ["arabic"],
  weight: ["400", "600"],
  variable: "--font-arabic",
});

export const metadata: Metadata = {
  metadataBase: new URL("https://example.com"),
};

export function generateStaticParams() {
  return locales.map((lang) => ({ lang }));
}

export default async function RootLayout({ children, params }: LayoutProps<"/[lang]">) {
  const { lang } = await params;
  if (!isLocale(lang)) notFound();

  return (
    <html lang={lang} dir={dir(lang)} className={`${latin.variable} ${arabic.variable}`}>
      <body>
        <header>
          <LanguageSwitcher lang={lang} />
        </header>
        {children}
      </body>
    </html>
  );
}

IBM Plex Sans Arabic is not a variable font, so next/font needs the weights listed. In CSS, use the variables as a font stack, var(--font-latin), var(--font-arabic), sans-serif, so Latin characters use the Latin font and Arabic characters fall through to the Arabic one. Best Arabic web fonts lists other pairs.

For translations, the guide's dictionary pattern works well. Since Next.js 16.3, next/root-params lets any Server Component read the language without passing it down as a prop:

ts
// app/[lang]/dictionaries.ts
import { lang } from "next/root-params";
import { notFound } from "next/navigation";

const dictionaries = {
  en: () => import("./dictionaries/en.json").then((m) => m.default),
  ar: () => import("./dictionaries/ar.json").then((m) => m.default),
};

export async function getDictionary() {
  const locale = await lang();
  if (!(locale in dictionaries)) notFound();
  return dictionaries[locale as keyof typeof dictionaries]();
}

Pages call getDictionary() with no arguments. Because this runs only on the server, the dictionaries never reach the browser bundle.

With dir="rtl" on the html element, layouts written with CSS logical properties mirror on their own. In Tailwind, use ms-, me-, ps-, pe-, start- and end- utilities instead of left and right ones. RTL web design covers what mirrors and what must not.

How do you add hreflang and a multilingual sitemap?

Return the alternates from each page's generateMetadata:

tsx
// app/[lang]/services/page.tsx
import type { Metadata } from "next";
import { getDictionary } from "../dictionaries";
import { alternates, isLocale } from "../../../i18n";

export async function generateMetadata({
  params,
}: PageProps<"/[lang]/services">): Promise<Metadata> {
  const { lang } = await params;
  if (!isLocale(lang)) return {};
  const dict = await getDictionary();
  return {
    title: dict.services.title,
    description: dict.services.description,
    alternates: alternates(lang, "/services"),
  };
}

export default async function ServicesPage() {
  const dict = await getDictionary();
  return <h1>{dict.services.title}</h1>;
}

On /ar/services this renders a self-referencing canonical and three alternate links, with full URLs built from metadataBase, which is what Google requires. HTML attribute names are case-insensitive, so hrefLang is read as hreflang:

html
<link rel="canonical" href="https://example.com/ar/services"/>
<link rel="alternate" hrefLang="en" href="https://example.com/en/services"/>
<link rel="alternate" hrefLang="ar" href="https://example.com/ar/services"/>
<link rel="alternate" hrefLang="x-default" href="https://example.com/en/services"/>

The helper assumes the same slug in both languages. If you translate slugs, store each page's slug per language in the CMS and build the languages object from that mapping instead. Compare the output with our hreflang tag generator if you are unsure, and see hreflang explained for the rules.

The sitemap lists every URL in every language with its alternates:

ts
// app/sitemap.ts
import type { MetadataRoute } from "next";
import { localePath, locales } from "../i18n";

const base = "https://example.com";
const paths = ["/", "/services"];

export default function sitemap(): MetadataRoute.Sitemap {
  return paths.flatMap((path) =>
    locales.map((locale) => ({
      url: `${base}${localePath(locale, path)}`,
      alternates: {
        languages: Object.fromEntries(
          locales.map((l) => [l, `${base}${localePath(l, path)}`])
        ),
      },
    }))
  );
}

Next.js writes these as xhtml:link entries in /sitemap.xml. Google treats hreflang in tags and in the sitemap as equivalent and needs only one. If you keep both, build them from the same helper so they can never disagree.

How do you build the language switcher?

A small client component swaps the first path segment, so the link always points to the same page in the other language:

tsx
// components/language-switcher.tsx
"use client";

import Link from "next/link";
import { usePathname } from "next/navigation";
import type { Locale } from "../i18n";

const labels: Record<Locale, string> = { en: "English", ar: "العربية" };

export function LanguageSwitcher({ lang }: { lang: Locale }) {
  const pathname = usePathname();
  const other: Locale = lang === "en" ? "ar" : "en";
  // Swap the first path segment: /en/services -> /ar/services
  const href = pathname.replace(/^\/(en|ar)(?=\/|$)/, `/${other}`);

  return (
    <Link href={href} hrefLang={other} lang={other}>
      {labels[other]}
    </Link>
  );
}

The lang attribute makes screen readers pronounce "العربية" in Arabic. For three or more languages, render a list of links instead of a single one. Language switcher design covers placement and labels.

What else does a production multilingual site need?

Content from a CMS. Labels belong in dictionaries; pages, services and posts belong in the CMS, stored per language. Most headless CMSs support localised fields or a document per language. Pick one that shows editors which pages are missing a translation. Adding a CMS to a Next.js site covers the integration.

Plurals and formatting. Arabic has six plural forms, and numbers, prices and dates need the right digits and calendar. For a site with many such strings, a library such as next-intl, listed in the official guide's resources, saves writing it yourself. Numbers, dates and currency in Arabic interfaces covers the formatting rules.

A build check. After next build, the route list should show each page prerendered once per language, such as /en/services and /ar/services. View the source of one page in each language and confirm the lang, dir, canonical and alternate tags. The routing details, including domain-based routing, are covered in internationalised routing in Next.js.

Was this guide useful?

Questions

Frequently asked.

Do I need a library such as next-intl?

Not for a company site with dictionaries of labels and content from a CMS; the pattern in this post is enough. Use a library when the interface has many strings with plurals, variables and formatted numbers. Arabic has six plural forms, and a library with ICU message support handles them properly.

Can I keep English URLs without the /en prefix?

Yes. In the proxy, rewrite unprefixed paths to /en internally instead of redirecting, and redirect any /en/... request to the unprefixed URL so each page has one address. The Next.js docs warn that usePathname can cause hydration mismatches on prerendered pages reached through a rewrite, so build the switcher link on the server.

Does this work with a static export?

Mostly. The [lang] routes, dictionaries, metadata and sitemap all work with output: "export". The proxy does not run in a static export, so the redirect from / to /en has to be set up on the host instead, for example as a redirect rule in the hosting configuration.

Sohail Hussain

Founder, MSH Technologies

Sohail has designed and built websites, web apps and AI products for over 12 years, for clients from Singapore-based industrial groups to early-stage SaaS startups. He writes about what actually worked.

Keep reading

Related guides.

All posts

Your next move

Like what you see? Tell us about it.

A process that takes too long, a website that undersells you, or an idea ready to take shape. Tell us where you are and we will suggest a useful next step.

India · Working with clients worldwide

Sohail, Founder, replies within 1 working day (Mon–Sat, IST). Free and no obligation.