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)
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.
Return links: every version lists all of them
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"/>
canonicalpoints to the page itself: each language is canonical for itself, not for the other version.hrefLang="en"is the page itself, because each version must list itself.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.x-defaultpoints to English. The Spanish version carries the same threealternatetags; only itscanonicaldiffers.
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") };
pageAlternatestakes the path of each language and the current language, and returns thealternatesobject.canonicalis the current page's path: each version is canonical for itself.languageslistsen,esandx-default. The same list comes out on both pages, so reciprocity holds by construction.generateMetadataloads the post and builds the two paths from each language's slug.metadataBaseturns 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 } },
];
});
}
pagesstores the path of each version; URLs must be absolute, here withBASE.languagesis the page's full list, own version included. The example in the Next.js documentation lists onlyesanddefor the base URL; since Google asks each version to list itself, we addenas well.flatMapwrites 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.
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.
| Code | Supported? | When |
|---|---|---|
es | Yes | All Spanish, no region |
es-MX | Yes | A version specific to Mexico |
es-419 | No | Not ISO 639-1 plus ISO 3166-1 |
MX | No | A region cannot stand alone |
x-default | Yes (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.
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
- The first batch is the English and Spanish home pages: both pass.
- 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. - The English home page fails because it lists
/esand that page does not point back. - The broken page collects three errors and the
x-defaultwarning.
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,metadataBasecompletes 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-419or 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-defaultpoints to the default version.- You use
es, ores-MXonly if there is a Mexico version; noes-419. - Each language's slugs are stored, not computed with a prefix.
metadataBaseis 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

Published November 12, 2026 · updated November 18, 2026