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:
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:
// 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:
// 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:
// 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:
// 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:
// 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:
<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:
// 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:
// 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?