Hreflang in Next.js and Nuxt

Start from one locale map

Both frameworks already hold a list of locales somewhere: in next.config.js, in a library such as next-intl, or in the i18n block of nuxt.config.ts. Hreflang errors appear when the annotations are built from something else, such as a hand-typed list in a layout. Put the facts hreflang needs in one module and import it everywhere:

// i18n/locales.ts
export const SITE = "https://example.com";
export const LOCALES = {
  "en-gb": { hreflang: "en-GB", prefix: "" },     // default, no prefix
  "en-ie": { hreflang: "en-IE", prefix: "/ie" },
  "fr":    { hreflang: "fr",    prefix: "/fr" },
} as const;
export const DEFAULT_LOCALE = "en-gb";
export type Locale = keyof typeof LOCALES;

Keep the routing segment and the hreflang value separate. The route segment can be anything convenient, like ie; the hreflang value must be a valid language code with an optional region, like en-IE. Many Next.js sites use the route segment directly as the hreflang value, which works only if the segments happen to be valid codes.

If pages have translated slugs, such as /fr/tarifs for /pricing, the map also needs a path for each page in each locale. Store that with the page content, or in a routes file, and look it up rather than assuming the path is the same in every language.

Next.js App Router: the metadata API

The App Router has no built-in i18n routing. Most sites put a [locale] segment at the top of the app directory and use middleware or a library to choose it. Hreflang goes in the alternates field of the metadata you return from generateMetadata:

// app/[locale]/pricing/page.tsx
import type { Metadata } from "next";
import { LOCALES, DEFAULT_LOCALE, type Locale } from "@/i18n/locales";
import { pathFor } from "@/i18n/paths"; // returns the localised path for a page key

export async function generateMetadata(
  { params }: { params: Promise<{ locale: Locale }> }
): Promise<Metadata> {
  const { locale } = await params;
  const languages: Record<string, string> = {};
  for (const [key, cfg] of Object.entries(LOCALES)) {
    languages[cfg.hreflang] = cfg.prefix + pathFor("pricing", key as Locale);
  }
  languages["x-default"] = pathFor("pricing", DEFAULT_LOCALE);
  return {
    alternates: {
      canonical: LOCALES[locale].prefix + pathFor("pricing", locale),
      languages,
    },
  };
}

Next.js renders each entry as a <link rel="alternate" hreflang="…" href="…"> in the head, including the current locale, so the self-reference comes for free as long as your loop includes every locale. In older versions params is a plain object rather than a promise; awaiting it works in both.

Set metadataBase, or the addresses are wrong

The paths above are relative. Next.js turns them into absolute addresses using metadataBase, which you set once in the root layout:

// app/layout.tsx
export const metadata = { metadataBase: new URL("https://example.com") };

Without it, Next.js warns at build time and falls back to a local address during development, and in some deployments to the platform's own hostname. Hreflang pointing at a preview domain is a common result.

Layouts and pages do not merge alternates

Metadata from layouts and pages is merged shallowly. If the layout sets alternates and the page also sets alternates, the page's object replaces the layout's entirely. A page that sets only a canonical therefore wipes out the layout's hreflang. Generate the whole alternates object in one place for each page, using a shared helper, rather than splitting it between levels.

Next.js Pages Router: i18n config and next/head

The Pages Router has i18n routing built in through next.config.js, with sub-path or domain routing. It sets the lang attribute and handles locale prefixes, but it does not print hreflang. You add it in a shared component with next/head:

// components/Hreflang.tsx
import Head from "next/head";
import { useRouter } from "next/router";

const SITE = "https://example.com";
const CODES = { "en-GB": "en-GB", fr: "fr", de: "de" };

export default function Hreflang() {
  const { asPath, locales = [], defaultLocale } = useRouter();
  const path = asPath.split(/[?#]/)[0];
  const href = (l: string) => SITE + (l === defaultLocale ? "" : "/" + l) + path;
  return (
    <Head>
      {locales.map((l) => (
        <link key={l} rel="alternate" hrefLang={CODES[l]} href={href(l)} />
      ))}
      <link rel="alternate" hrefLang="x-default" href={href(defaultLocale!)} />
    </Head>
  );
}

Two details matter. The query string and fragment are stripped from asPath, so tracking parameters never leak into the tags. And this version assumes the same path in every locale; if your slugs are translated, look the paths up instead. With domain routing, build each address from the locale's domain rather than SITE.

Note that the Pages Router's i18n routing does not work with static export (output: "export"). Statically exported multilingual sites generate each locale's pages themselves and must add hreflang in the same way.

Nuxt with @nuxtjs/i18n

The official Nuxt i18n module can generate hreflang, canonical and og:locale tags from its own configuration. It needs two things to get them right: a baseUrl, so addresses are absolute, and a valid language code on each locale.

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ["@nuxtjs/i18n"],
  i18n: {
    baseUrl: "https://example.com",
    strategy: "prefix_except_default",
    defaultLocale: "en",
    locales: [
      { code: "en", language: "en-GB" },
      { code: "ie", language: "en-IE" },
      { code: "fr", language: "fr-FR" },
    ],
  },
});

Older versions of the module call the language field iso rather than language. Then add the generated tags in app.vue or your default layout with the useLocaleHead composable, passing it to useHead. The option that switches on the hreflang and canonical output has been renamed between major versions, so check the documentation for the version in your lock file and confirm the output in the rendered HTML.

• Missing baseUrl produces relative addresses or ones built from the request host, which may be a preview domain.
• Invalid codes come from putting a route code like ie where the language code belongs.
• Pages without translations still appear in every locale's hreflang if the module thinks the route exists everywhere. If some content exists only in some languages, handle those routes explicitly so the cluster lists only real pages.
• x-default may be generated from the default locale. Check whether your version does this and that it points where you want.

Middleware, redirects and crawlers

Locale detection is where framework sites most often hide pages from Google. A common Next.js middleware reads the Accept-Language header and redirects to a locale prefix. Google's documentation says Googlebot usually crawls without an Accept-Language header and mostly from United States addresses, so this logic sends Google to the default locale, or loops it, however many locales you have.

• Only redirect a request that has no locale in the path, such as the bare root. Never redirect a request for /fr/tarifs to /pricing because the browser prefers English.
• In the Pages Router, set localeDetection: false in the i18n config if automatic detection is redirecting crawlers from the root.
• Prefer a banner suggesting another language over an automatic redirect, and remember the choice in a cookie only after the visitor clicks.
• Make sure every locale page returns 200 when requested directly with no cookies and no language header.

You can reproduce what Google receives with curl, which sends no language header by default:

curl -sI https://example.com/fr/tarifs | head -1     # expect 200, not 307 or 308
curl -sI https://example.com/ | grep -i "^location"  # see where the root sends visitors

Sitemaps, Link headers and libraries: one source only

Framework projects can end up declaring hreflang in three places without anyone deciding to. The App Router's app/sitemap.ts accepts an alternates.languages object per entry in recent versions, which writes xhtml:link entries. The next-intl library's middleware can send hreflang as an HTTP Link response header, controlled by its alternateLinks option. And your metadata writes head tags. If these are built from different data, they disagree.

Pick one. For most projects the head tags from the metadata API or the Nuxt head helper are easiest to test. If you use a library that adds a Link header, either switch that off or remove your own tags, and make sure any sitemap alternates are generated from the same locale map. The sitemap mismatch guide covers choosing between sources.

The fix, step by step

Keeping it right as the project grows

• Test the rendered head in CI. A small test that builds the site, fetches a page per locale and checks the hreflang block catches regressions from framework upgrades and refactors.
• Watch major upgrades. Changes to how params is passed, how metadata is merged or what i18n module options are called can alter the output silently.
• Never hard-code hosts. Read the production base URL from configuration and fail the build if it is missing, so preview hosts cannot leak into tags.
• Add new locales in one place. A new market should mean one entry in the locale map and translated content, nothing else.

For other head tags in the same framework, see fixing meta tags in Next.js.