next-intl Routing in Next.js: i18n for Beginners

export const routing = defineRouting({
  locales,
  defaultLocale: "en",
  localePrefix: "always",
  // Locale is always in the URL path, so the NEXT_LOCALE cookie is redundant.
  // Disabling it removes the per-response Set-Cookie that blocks Cloudflare
  // from edge-caching the static HTML.
  localeCookie: false,

  // Every page already emits hreflang in <head> via `alternates.languages`
  // (see buildLanguageAlternates in lib/seo.ts). Leaving this on made the
  // middleware emit a SECOND set as an HTTP Link header whose x-default
  // pointed at the unprefixed "/blog/<slug>/" — a URL that 307-redirects,
  // and a different target from the "/en/blog/<slug>/" in the HTML. Google
  // may discard hreflang entirely when the annotations conflict, which on a
  // bilingual site risks losing the en/id pairing.
  alternateLinks: false,
});

The whole routing contract. localePrefix always means /en/... and /id/..., never a bare path. The cookie is off because the locale is already in the URL, and a per-response Set-Cookie blocks edge caching. alternateLinks is off because the HTML already carries hreflang.

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

  // Ensure that a valid locale is used
  if (!locale || !routing.locales.includes(locale as any)) {
    locale = routing.defaultLocale;
  }

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

Per-request config. requestLocale is a promise, so it is awaited, and an invalid value falls back to the default. The dynamic import loads only the messages for that locale. The current next-intl docs mark requestLocale as legacy in favor of a locale argument, and this site has not migrated.

import { createNavigation } from 'next-intl/navigation';
import { routing } from './routing';

export const { Link, redirect, usePathname, useRouter, getPathname } =
  createNavigation(routing);

The only place these five wrappers are created. Every Link, useRouter and usePathname on the site is imported from here, never from next/link or next/navigation, so each carries the locale.

  const { locale } = await params;
  setRequestLocale(locale);
  const pageLocale = asSiteLocale(locale);

  const t = await getTranslations({ locale, namespace: "aboutPage" });

An async Server Component page. It sets the request locale first, then awaits getTranslations with a namespace. Hooks are not allowed here. The Header, a Client Component, calls the hook version, useTranslations with the nav namespace.

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

One entry per locale, so the [locale] segment is prerendered for en and id. Just below it in the file, export const dynamicParams = false turns every other locale into a 404 before anything renders.

export function buildLanguageAlternates(path = ""): Record<string, string> {
  return {
    en: buildCanonical("en", path),
    id: buildCanonical("id", path),
    "x-default": buildCanonical("en", path),
  };
}

The single source of hreflang. Three absolute URLs for every page, and x-default points at English. Pages pass it to alternates.languages, which Next.js renders as link tags in head.