Skip to content

hreflang in Next.js: set up a bilingual site correctly

From the work/ 9 min read

hreflang in Next.js with alternates.languages and the sitemap: return links, x-default, es versus es-MX, and a Node script that checks real pages.

  • SEO
  • Next.js
In this article (9)
  1. What problem hreflang solves
  2. Return links: every version lists all of them
  3. x-default: the version for when nothing matches
  4. How to implement it in Next.js
  5. es or es-MX: which code to use
  6. How to validate hreflang
  7. Common mistakes
  8. Frequently asked questions
  9. Checklist

hreflang tells Google which page is the other-language version of the one it is reading. In Next.js you declare it with alternates.languages in each page's metadata, and every version must list all the others and itself, with full URLs and, optionally, an x-default.

Below is the code for an English and Spanish site, the difference between es and es-MX, and a Node script that checks the tags of real pages. We ran the code through the metadata resolvers of a Next.js 15 install, and the script on the public HTML of ecomlabs.dev.

What problem hreflang solves

A bilingual site has two URLs per page: /blog/lcp-hero-image and /es/blog/lcp-imagen-principal-lenta. To Google they are different pages. hreflang tells it they are the same page in two languages, so each person gets the version that fits. Per Google Search Central, localized versions only count as duplicates if the main content stays untranslated; if you translated it, they do not compete with each other.

There are three ways to declare it: tags in the HTML, HTTP headers or the sitemap. Google treats them as equivalent, lets you pick the most convenient and says using all three at once gives no benefit in Search. In Next.js the most direct is HTML through alternates; the sitemap works as a second channel if you have many pages.

Google's central rule: each version must list itself and all the others, and if two pages do not point to each other, the tags are ignored. URLs must be fully qualified, with https://. These are the public tags of the English version of one of our articles, as they appear in its HTML:

<link rel="canonical" href="https://ecomlabs.dev/blog/lcp-hero-image"/>
<link rel="alternate" hrefLang="en" href="https://ecomlabs.dev/blog/lcp-hero-image"/>
<link rel="alternate" hrefLang="es" href="https://ecomlabs.dev/es/blog/lcp-imagen-principal-lenta"/>
<link rel="alternate" hrefLang="x-default" href="https://ecomlabs.dev/blog/lcp-hero-image"/>
  1. canonical points to the page itself: each language is canonical for itself, not for the other version.
  2. hrefLang="en" is the page itself, because each version must list itself.
  3. hrefLang="es" points to the Spanish version, which has a different slug: slugs change between languages, so you cannot build them by adding a prefix.
  4. x-default points to English. The Spanish version carries the same three alternate tags; only its canonical differs.
two versions that point at each otherEnglish version/blog/hero-imageenthis pageesthe otherx-defaultEnglishSpanish version/es/blog/imagen-principalenthe otheresthis pagex-defaultEnglishboth pages carry the same three tagsno return link, Google ignores the tagsURLs must be fully qualified, with https://every version lists all of them, itself includedGoogle Search Central rule on localized versions

Scroll the figure sideways to see all of it

x-default: the version for when nothing matches

The reserved x-default value is used when no other version matches the searcher's browser language. Google's example points it at a country selector page. A two-language site does not need that page: point x-default at the default version, which on the example site is English. Google describes it as the value for when nothing matches and does not say it is mandatory, so the script below flags it as a warning, not an error.

How to implement it in Next.js

In the App Router, alternates is part of the metadata object or of generateMetadata (documentation), and Next.js turns it into <link rel="alternate" hreflang>. If you use relative paths, set metadataBase in the root layout; without it, a relative path breaks the build. This is the helper we used, with a page and the layout:

// lib/hreflang.ts
import type { Metadata } from "next";

export type Locale = "en" | "es";

// English lives at the root and Spanish under /es. Each version's whole path is
// passed in, because the slug can differ between languages.
export function pageAlternates(paths: Record<Locale, string>, current: Locale): Metadata["alternates"] {
  return {
    canonical: paths[current],
    languages: { en: paths.en, es: paths.es, "x-default": paths.en },
  };
}

// app/blog/[slug]/page.tsx (the English page; the Spanish page passes "es")
export async function generateMetadata({ params }: Props): Promise<Metadata> {
  const { slug } = await params;
  const post = await getPost(slug); // { slug: { en, es } } from your data layer
  return {
    title: post.title,
    alternates: pageAlternates(
      { en: `/blog/${post.slug.en}`, es: `/es/blog/${post.slug.es}` },
      "en",
    ),
  };
}

// app/layout.tsx: lets the relative paths above resolve to full URLs
export const metadata: Metadata = { metadataBase: new URL("https://example.com") };
  1. pageAlternates takes the path of each language and the current language, and returns the alternates object.
  2. canonical is the current page's path: each version is canonical for itself.
  3. languages lists en, es and x-default. The same list comes out on both pages, so reciprocity holds by construction.
  4. generateMetadata loads the post and builds the two paths from each language's slug.
  5. metadataBase turns the relative paths into absolute URLs.

With this helper, Next.js's resolvers produced the four tags of the previous example, with example.com as the base. The sitemap is the second channel. Since v14.2.0, each entry accepts alternates.languages (sitemap documentation):

// app/sitemap.ts
import type { MetadataRoute } from "next";

const BASE = "https://example.com";

// One entry per page, with the path of each language version.
const pages = [
  { en: "/", es: "/es" },
  { en: "/services", es: "/es/servicios" },
];

export default function sitemap(): MetadataRoute.Sitemap {
  return pages.flatMap((p) => {
    const languages = { en: BASE + p.en, es: BASE + p.es, "x-default": BASE + p.en };
    // Both versions get a <url>, and both carry the same full list.
    return [
      { url: languages.en, alternates: { languages } },
      { url: languages.es, alternates: { languages } },
    ];
  });
}
  1. pages stores the path of each version; URLs must be absolute, here with BASE.
  2. languages is the page's full list, own version included. The example in the Next.js documentation lists only es and de for the base URL; since Google asks each version to list itself, we add en as well.
  3. flatMap writes one <url> per version, and both carry the same list.

The function generated one <url> per version, with one xhtml:link per entry in languages.

one site, two URL trees linked pair by pairEnglish · rootSpanish · /eshreflang//es/services/es/servicios/blog/es/blog/blog/lcp-hero-image/es/blog/lcp-imagen-principal-lentax-default → the English version of each pairslugs change between languages: /services and /es/serviciosevery URL knows its pairreal pairs of a bilingual site, public tags

Scroll the figure sideways to see all of it

es or es-MX: which code to use

Per Google, the first code is the language, in ISO 639-1 format, and the optional second one is the region, in ISO 3166-1 alpha-2. You can use the language alone; you cannot use the country alone; and codes outside those standards, such as es-419, are not supported. So es covers all Spanish, and es-MX only makes sense if you really have a Mexico version that differs from one for the rest: then you list both, as in Google's example with en-GB, en-US and en.

CodeSupported?When
esYesAll Spanish, no region
es-MXYesA version specific to Mexico
es-419NoNot ISO 639-1 plus ISO 3166-1
MXNoA region cannot stand alone
x-defaultYes (reserved)When no other version matches

Careful: Next.js's types do not protect you. We tried languages: { "es-419": "/es" } with tsc --strict and it compiles without complaint, because the type accepts any xx-something. The error shows up in Google, not in your editor.

hreflang codes: which ones are supportedcodesupported?whenesyesall Spanish, no regiones-MXyesa version for Mexicoes-419nonot ISO 639-1 + ISO 3166-1MXnoa region cannot stand alonex-defaultyes (reserved)no other version matchesNext.js types accept es-419: it compiles, Google does not support itISO 639-1 language, optional ISO 3166-1 regionsource: Google Search Central, localized versions

Scroll the figure sideways to see all of it

How to validate hreflang

A dependency-free Node script, check-hreflang.mjs, reads the saved HTML of each page you pass and checks what Google asks for: that tags exist, that codes are valid, that URLs are fully qualified, that the page lists itself and that the other pages in the batch point back to it. A missing x-default warns instead of failing. The full script is in the guide. This is what it gave on the saved public HTML of two pages of the site and on a broken page we wrote by hand:

$ node check-hreflang.mjs fixtures/home.html fixtures/home-es.html
OK   fixtures/home.html
OK   fixtures/home-es.html

$ node check-hreflang.mjs fixtures/home.html fixtures/broken-es.html
FAIL fixtures/home.html
     - es -> https://ecomlabs.dev/es: that page does not link back
FAIL fixtures/broken-es.html
     - unsupported code "es-419"
     - href is not fully qualified: "/es"
     - the page does not list itself
     ! no x-default
  1. The first batch is the English and Spanish home pages: both pass.
  2. The second batch swaps the Spanish home page for a broken page, broken-es.html, which we wrote with an unsupported code and a relative URL.
  3. The English home page fails because it lists /es and that page does not point back.
  4. The broken page collects three errors and the x-default warning.

The home page, the blog and an article with its Spanish pair also passed, and so did the tags the code above generates. In production, open the page, view the HTML source and run the script on one page of each type.

Common mistakes

  • Tags with no return link. If two pages do not point to each other, Google ignores them.
  • Not listing the page itself. Each version must include itself.
  • Relative URLs. They must be fully qualified with https://; in metadata, metadataBase completes them.
  • The Spanish canonical pointing to English. You tell Google one is a copy of the other; each language must be canonical for itself.
  • Unsupported codes such as es-419 or a region on its own. TypeScript lets them through.
  • Building the other language's URL with a prefix. If the slug changes, the link points to a page that does not exist; store each language's path.
  • Declaring a version that does not exist. That URL will not point back, so the tag is ignored.

Frequently asked questions

Do I need hreflang if my site has only two languages?

If both versions exist as separate pages, it is useful: it is the method Google documents for declaring them as equivalent. Without it, each page is judged on its own.

HTML, sitemap or HTTP header?

Google says the three methods are equivalent and that using them all gives no benefit in Search. In Next.js, alternates in the metadata is the simplest. The example site publishes tags in the HTML and also in the sitemap, but one is enough.

What happens if one page is missing the return link?

Google ignores the tags on both pages. That is why you should generate the list from one place, like pageAlternates, instead of writing it by hand on each page.

Where do I point x-default if I have no language selector page?

At the default version. The example site points it at the English version of each page. Google describes it as the value for when no language matches.

Checklist

  • Every page lists all its versions and itself, with full URLs.
  • The list comes from one place and both versions use the same one.
  • Each language has its own canonical.
  • x-default points to the default version.
  • You use es, or es-MX only if there is a Mexico version; no es-419.
  • Each language's slugs are stored, not computed with a prefix.
  • metadataBase is set in the root layout.
  • The script passes on one page of each type.

With hreflang in place, Google knows which version to show. For it to also understand what you sell, review product structured data.

Saw this on Instagram? Comment HREFLANG on the Reel and I'll send you the guide.

Written by

Luis Morales

Luis Morales

Frontend and Shopify developer, EcomLabs

@luismoralesdev on Instagram

Published November 12, 2026 · updated November 18, 2026

← Blog