Next.js Internationalization with next-intl: App Router, Locale Detection, Translated Routes, and Pluralization

Adding internationalization to a Next.js App Router project is an architectural decision — the route structure, component patterns, and metadata generation all change once you have multiple locales. next-intl is the most mature i18n library for Next.js App Router, with full support for Server Components, typed message keys, pluralization, and rich text formatting.

This guide walks through the complete setup with locale detection, translated routes, and SEO hreflang tags.

Installation

npm install next-intl

Directory Structure

app/
  [locale]/
    layout.tsx         # Locale-aware root layout
    page.tsx           # Home page
    blog/
      page.tsx
      [slug]/
        page.tsx
    (auth)/
      login/page.tsx
middleware.ts          # Locale detection and routing
i18n/
  request.ts           # Server-side locale config
messages/
  en.json
  de.json
  fr.json
  es.json

Locale Configuration

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

// Human-readable locale names for UI
export const LOCALE_LABELS: Record<Locale, string> = {
  en: "English",
  de: "Deutsch",
  fr: "Français",
  es: "Español",
};

Middleware: Locale Detection

// middleware.ts
import createMiddleware from "next-intl/middleware";
import { locales, defaultLocale } from "@/i18n/config";

export default createMiddleware({
  locales,
  defaultLocale,

  // Strategy: 'always' | 'as-needed' | 'never'
  // 'as-needed': default locale has no prefix (/about), others prefixed (/de/about)
  // 'always': all locales prefixed (/en/about, /de/about) — cleaner for SEO
  localePrefix: "always",

  // Locale detection order: cookie → Accept-Language header → default
  localeDetection: true,
});

export const config = {
  // Run middleware on all paths except static files and API routes
  matcher: ["/((?!api|_next|_vercel|.*\\..*).*)"],
};

Server-Side Locale Config

// i18n/request.ts
import { getRequestConfig } from "next-intl/server";
import { locales, defaultLocale, type Locale } from "./config";

export default getRequestConfig(async ({ requestLocale }) => {
  let locale = await requestLocale;

  // Validate locale — fall back to default if invalid
  if (!locale || !locales.includes(locale as Locale)) {
    locale = defaultLocale;
  }

  return {
    locale,
    messages: (await import(`../messages/${locale}.json`)).default,
  };
});

next.config.ts Integration

// next.config.ts
import createNextIntlPlugin from "next-intl/plugin";

const withNextIntl = createNextIntlPlugin("./i18n/request.ts");

export default withNextIntl({
  // Your other Next.js config
});

Message Files

// messages/en.json
{
  "nav": {
    "home": "Home",
    "blog": "Blog",
    "pricing": "Pricing",
    "contact": "Contact"
  },
  "hero": {
    "headline": "Build better software, faster",
    "subheadline": "We design and ship production-ready SaaS applications for ambitious founders.",
    "cta": "Start your project"
  },
  "pricing": {
    "title": "Simple, transparent pricing",
    "seats": "{count, plural, one {# seat} other {# seats}}",
    "perMonth": "{price}/month",
    "features": "{count, plural, one {# feature} other {# features}} included"
  },
  "blog": {
    "readMore": "Read article",
    "publishedOn": "Published on {date, date, long}",
    "readTime": "{minutes, plural, one {# minute read} other {# minute read}}"
  },
  "errors": {
    "notFound": "Page not found",
    "notFoundDesc": "The page you're looking for doesn't exist or has been moved."
  }
}

// messages/de.json
{
  "nav": {
    "home": "Startseite",
    "blog": "Blog",
    "pricing": "Preise",
    "contact": "Kontakt"
  },
  "hero": {
    "headline": "Bessere Software, schneller entwickeln",
    "subheadline": "Wir entwickeln produktionsreife SaaS-Anwendungen für ambitionierte Gründer.",
    "cta": "Projekt starten"
  },
  "pricing": {
    "title": "Einfache, transparente Preise",
    "seats": "{count, plural, one {# Platz} other {# Plätze}}",
    "perMonth": "{price}/Monat",
    "features": "{count, plural, one {# Funktion} other {# Funktionen}} enthalten"
  },
  "blog": {
    "readMore": "Artikel lesen",
    "publishedOn": "Veröffentlicht am {date, date, long}",
    "readTime": "{minutes, plural, one {# Minute Lesezeit} other {# Minuten Lesezeit}}"
  },
  "errors": {
    "notFound": "Seite nicht gefunden",
    "notFoundDesc": "Die gesuchte Seite existiert nicht oder wurde verschoben."
  }
}

App Router Layout

// app/[locale]/layout.tsx
import { NextIntlClientProvider } from "next-intl";
import { getMessages } from "next-intl/server";
import { notFound } from "next/navigation";
import { locales, type Locale } from "@/i18n/config";

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

export default async function LocaleLayout({
  children,
  params,
}: {
  children: React.ReactNode;
  params: { locale: string };
}) {
  const { locale } = await params;

  // Validate locale — 404 if not in list
  if (!locales.includes(locale as Locale)) notFound();

  // Load messages for this locale (passed to client provider)
  const messages = await getMessages();

  return (
    <html lang={locale} dir={locale === "ar" ? "rtl" : "ltr"}>
      <body>
        <NextIntlClientProvider messages={messages}>
          {children}
        </NextIntlClientProvider>
      </body>
    </html>
  );
}

Server Component Usage

// app/[locale]/page.tsx — Server Component, no "use client"
import { useTranslations } from "next-intl";
import { getTranslations } from "next-intl/server";
import type { Metadata } from "next";

// Typed metadata using translations
export async function generateMetadata({
  params,
}: {
  params: { locale: string };
}): Promise<Metadata> {
  const t = await getTranslations({ locale: params.locale, namespace: "hero" });

  return {
    title: t("headline"),
    description: t("subheadline"),
  };
}

export default function HomePage() {
  // useTranslations works in Server Components
  const t = useTranslations("hero");
  const nav = useTranslations("nav");

  return (
    <main>
      <h1>{t("headline")}</h1>
      <p>{t("subheadline")}</p>
      <a href="/contact">{t("cta")}</a>
    </main>
  );
}

Client Component Usage

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

import { useLocale } from "next-intl";
import { useRouter, usePathname } from "next/navigation";
import { locales, LOCALE_LABELS } from "@/i18n/config";

export function LanguageSwitcher() {
  const currentLocale = useLocale();
  const router = useRouter();
  const pathname = usePathname();

  function switchLocale(newLocale: string) {
    // Replace the locale segment in the current path
    // Pathname: /de/blog/my-post → /en/blog/my-post
    const segments = pathname.split("/");
    segments[1] = newLocale; // [locale] is always the first segment
    router.push(segments.join("/"));
  }

  return (
    <select
      value={currentLocale}
      onChange={(e) => switchLocale(e.target.value)}
      className="text-sm border border-gray-200 rounded-md px-2 py-1 bg-white"
      aria-label="Select language"
    >
      {locales.map((locale) => (
        <option key={locale} value={locale}>
          {LOCALE_LABELS[locale]}
        </option>
      ))}
    </select>
  );
}

Pluralization and Formatting

// components/blog-meta.tsx
"use client";

import { useTranslations, useFormatter } from "next-intl";

interface BlogMetaProps {
  publishedAt: Date;
  readTimeMinutes: number;
}

export function BlogMeta({ publishedAt, readTimeMinutes }: BlogMetaProps) {
  const t = useTranslations("blog");
  const format = useFormatter();

  return (
    <div className="flex items-center gap-4 text-sm text-gray-500">
      {/* Locale-aware date formatting */}
      <span>
        {t("publishedOn", { date: publishedAt })}
        {/* en: "Published on April 17, 2027" */}
        {/* de: "Veröffentlicht am 17. April 2027" */}
      </span>

      {/* Pluralization via ICU message format */}
      <span>
        {t("readTime", { minutes: readTimeMinutes })}
        {/* en: "12 minute read" (singular if 1) */}
        {/* de: "12 Minuten Lesezeit" */}
      </span>
    </div>
  );
}

// Formatting numbers and currencies per locale
function PriceDisplay({ amount, currency }: { amount: number; currency: string }) {
  const format = useFormatter();

  return (
    <span>
      {format.number(amount, { style: "currency", currency })}
      {/* en: "$49.00" */}
      {/* de: "49,00 $" (German convention) */}
    </span>
  );
}

SEO: hreflang Tags

// app/[locale]/blog/[slug]/page.tsx
import { getTranslations } from "next-intl/server";
import type { Metadata } from "next";
import { locales } from "@/i18n/config";

const APP_URL = process.env.NEXT_PUBLIC_APP_URL!;

export async function generateMetadata({
  params,
}: {
  params: { locale: string; slug: string };
}): Promise<Metadata> {
  const t = await getTranslations({ locale: params.locale, namespace: "blog" });

  // Build hreflang alternates for all locales
  const languages: Record<string, string> = {};
  for (const locale of locales) {
    languages[locale] = `${APP_URL}/${locale}/blog/${params.slug}`;
  }
  // x-default points to the default locale
  languages["x-default"] = `${APP_URL}/en/blog/${params.slug}`;

  return {
    alternates: {
      languages,
    },
  };
  // Next.js renders these as <link rel="alternate" hreflang="..." href="..." />
}

Type Safety for Message Keys

// Create global TypeScript types for messages
// types/next-intl.d.ts
import en from "@/messages/en.json";

declare module "next-intl" {
  interface AppConfig {
    Messages: typeof en;
  }
}

// Now useTranslations("nav") is typed:
// t("home") ✅
// t("hoem") ❌ TypeScript error: "hoem" does not exist in "nav"

Cost and Timeline Estimates

Translation costs (not included above): Professional translation ~$0.10–0.20/word; machine translation + review ~$0.05–0.10/word.

See Also

• Next.js App Router Caching Strategies
• Next.js Performance Optimization
• Next.js Multi-Tenant Subdomain Routing
• Next.js Static Generation with ISR
• React Accessibility and ARIA Patterns

---

Working With Viprasol

Internationalization done right means more than running strings through Google Translate. Our team sets up next-intl with typed message keys, ICU pluralization, locale-aware date and number formatting, and hreflang metadata — so your site is genuinely localized, not just translated.

What we deliver:

• next-intl middleware with locale detection and prefix strategy
• [locale] App Router structure with generateStaticParams
• Typed message keys with TypeScript global declaration
• Pluralization and date/number formatting per locale
• Language switcher preserving current path
• hreflang alternates for all locales (SEO)

Talk to our team about internationalizing your Next.js app →

Or explore our web development services.