hreflang en Next.js: cómo declarar un sitio bilingüe (es y en)
En la práctica/ 9 min de lectura
hreflang en Next.js con alternates.languages y el sitemap: etiquetas recíprocas, x-default, es contra es-MX y un script en Node que revisa páginas reales.
- SEO
- Next.js
En este artículo (9)
hreflang le dice a Google cuál es la versión en otro idioma de la página que está leyendo. En Next.js lo declaras con alternates.languages en la metadata de cada página, y cada versión debe listar a todas las demás y a sí misma, con URLs completas y, si quieres, un x-default.
Aquí tienes el código para un sitio en inglés y español, la diferencia entre es y es-MX, y un script en Node que revisa las etiquetas de páginas reales. Corrimos el código con los resolvers de metadata de una instalación de Next.js 15 y el script con el HTML público de ecomlabs.dev.
Qué problema resuelve hreflang
Un sitio bilingüe tiene dos URLs por página: /blog/lcp-hero-image y /es/blog/lcp-imagen-principal-lenta. Para Google son páginas distintas. hreflang le dice que son la misma página en dos idiomas, para que muestre a cada persona la versión que le corresponde. Según Google Search Central, las versiones localizadas solo se consideran duplicadas si el contenido principal sigue sin traducir; si lo tradujiste, no compiten entre sí.
Hay tres formas de declararlo: etiquetas en el HTML, cabeceras HTTP o el sitemap. Google las considera equivalentes, te deja elegir la más cómoda y dice que usar las tres a la vez no aporta nada en Search. En Next.js lo más directo es el HTML con alternates; el sitemap sirve de segundo canal si tienes muchas páginas.
Etiquetas recíprocas: cada versión lista a todas
La regla central de Google: cada versión debe listarse a sí misma y a todas las demás, y si dos páginas no se apuntan una a la otra, las etiquetas se ignoran. Las URLs tienen que ser completas, con https://. Estas son las etiquetas públicas de la versión en inglés de uno de nuestros artículos, tal como salen en su 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"/>
canonicalapunta a la propia página: cada idioma es canónico de sí mismo, no de la otra versión.hrefLang="en"es la propia página, porque cada versión debe listarse a sí misma.hrefLang="es"apunta a la versión en español, con otro slug: los slugs cambian entre idiomas, así que no se construyen sumando un prefijo.x-defaultapunta al inglés. La versión en español tiene las mismas tres etiquetasalternate; solo cambia sucanonical.
Desliza la figura para verla completa
x-default: la versión para cuando nada coincide
El valor reservado x-default se usa cuando ninguna otra versión coincide con el idioma del navegador de quien busca. El ejemplo de Google lo apunta a una página para elegir país. En un sitio de dos idiomas no necesitas esa página: apunta x-default a la versión por defecto, que en el sitio de ejemplo es la inglesa. Google lo describe como el valor para cuando nada coincide y no dice que sea obligatorio, así que el script de abajo lo marca como aviso y no como error.
Cómo implementarlo en Next.js
En el App Router, alternates forma parte del objeto metadata o de generateMetadata (documentación), y Next.js lo convierte en <link rel="alternate" hreflang>. Si usas rutas relativas, define metadataBase en el layout raíz; sin él, una ruta relativa rompe el build. Esta es la ayuda que usamos, junto con una página y el 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") };
pageAlternatesrecibe la ruta de cada idioma y el idioma actual, y devuelve el objetoalternates.canonicales la ruta de la página actual: cada versión es canónica de sí misma.languageslistaen,esyx-default. Como la misma lista sale en ambas páginas, la reciprocidad queda garantizada por construcción.generateMetadatabusca el artículo y arma las dos rutas con el slug de cada idioma.metadataBasecompleta las rutas relativas hasta URLs absolutas.
Con esta ayuda, los resolvers de Next.js generaron las cuatro etiquetas del ejemplo anterior, con example.com como base. El sitemap es el segundo canal. Desde la v14.2.0, cada entrada acepta alternates.languages (documentación del sitemap):
// 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 } },
];
});
}
pagesguarda la ruta de cada versión; las URLs deben ser absolutas, aquí conBASE.languageses la lista completa de la página, con la propia versión incluida. El ejemplo de la documentación de Next.js solo listaesydepara la URL base; como Google pide que cada versión se liste a sí misma, aquí añadimos tambiénen.- El
flatMapescribe un<url>por versión, y las dos llevan la misma lista.
La función generó un <url> por versión, con un xhtml:link por cada entrada de languages.
Desliza la figura para verla completa
es o es-MX: qué código poner
Según Google, el primer código es el idioma, en formato ISO 639-1, y el segundo, opcional, la región, en ISO 3166-1 alfa-2. Puedes usar solo el idioma; no puedes usar solo el país; y códigos que no estén en esos estándares, como es-419, no se admiten. Por eso es cubre todo el español y es-MX solo tiene sentido si de verdad tienes una versión para México distinta de otra para el resto: entonces listas ambas, como en el ejemplo de Google con en-GB, en-US y en.
| Código | ¿Se admite? | Cuándo |
|---|---|---|
es | Sí | Todo el español, sin región |
es-MX | Sí | Una versión específica para México |
es-419 | No | No es ISO 639-1 más ISO 3166-1 |
MX | No | La región no puede ir sola |
x-default | Sí (reservado) | Cuando ninguna otra versión coincide |
Ojo: los tipos de Next.js no te protegen. Probamos languages: { "es-419": "/es" } con tsc --strict y compila sin quejas, porque el tipo acepta cualquier xx-algo. El error aparece en Google, no en tu editor.
Desliza la figura para verla completa
Cómo validar hreflang
Un script en Node sin dependencias, check-hreflang.mjs, lee el HTML guardado de cada página que le pases y comprueba lo que pide Google: que haya etiquetas, que los códigos sean válidos, que las URLs sean completas, que la página se liste a sí misma y que las demás páginas del lote le apunten de vuelta. Sin x-default avisa, no falla. El script completo va en la guía. Esto dio con el HTML público guardado de dos páginas del sitio y con una página rota que escribimos a mano:
$ 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
- El primer lote es la portada en inglés y en español: las dos pasan.
- El segundo lote cambia la portada en español por una página rota,
broken-es.html, que escribimos con un código no admitido y una URL relativa. - La portada en inglés falla porque lista a
/esy esa página no le apunta de vuelta. - La página rota acumula tres errores y el aviso de
x-default.
También pasaron la portada, el blog y un artículo con su par en español, y las etiquetas que genera el código de arriba. En producción, abre la página, mira el HTML fuente y pasa el script por cada tipo de página.
Errores comunes
- Etiquetas sin enlace de vuelta. Si dos páginas no se apuntan, Google las ignora.
- No listar la propia página. Cada versión debe incluirse a sí misma.
- URLs relativas. Deben ser completas con
https://; en metadata,metadataBaselas completa. - Canonical de la versión en español hacia el inglés. Le dices a Google que una es copia de la otra; cada idioma debe ser canónico de sí mismo.
- Códigos no admitidos como
es-419o una región sola. TypeScript los deja pasar. - Construir la URL del otro idioma con un prefijo. Si el slug cambia, el enlace apunta a una página que no existe; guarda la ruta de cada idioma.
- Declarar una versión que no existe. Esa URL no te apuntará de vuelta, así que la etiqueta se ignora.
Preguntas frecuentes
¿Necesito hreflang si mi sitio solo tiene dos idiomas?
Si las dos versiones existen como páginas separadas, sí es útil: es el método que documenta Google para declararlas como equivalentes. Sin él, cada página se evalúa por su cuenta.
¿HTML, sitemap o cabecera HTTP?
Google dice que los tres métodos son equivalentes y que usarlos todos no aporta nada en Search. En Next.js, alternates en la metadata es lo más simple. El sitio de ejemplo publica etiquetas en el HTML y también en el sitemap, pero con uno basta.
¿Qué pasa si falta el enlace de vuelta en una de las páginas?
Google ignora las etiquetas de las dos. Por eso conviene generar la lista desde un solo lugar, como pageAlternates, en lugar de escribirla a mano en cada página.
¿Dónde apunto x-default si no tengo una página para elegir idioma?
A la versión por defecto. El sitio de ejemplo lo apunta a la versión en inglés de cada página. Google lo describe como el valor para cuando ningún idioma coincide.
Checklist
- Cada página lista todas sus versiones y a sí misma, con URLs completas.
- La lista sale de un solo lugar y las dos versiones usan la misma.
- Cada idioma tiene su propio
canonical. x-defaultapunta a la versión por defecto.- Usas
es, oes-MXsolo si hay una versión para México; nada dees-419. - Los slugs de cada idioma se guardan, no se calculan con un prefijo.
metadataBaseestá en el layout raíz.- El script pasa en una página de cada tipo.
Con hreflang bien puesto, Google sabe qué versión mostrar. Para que además entienda qué vendes, revisa los datos estructurados de producto.
¿Viste esto en Instagram? Comenta HREFLANG en el Reel y te mando la guía.
Escrito por

Publicado el 12 de noviembre de 2026 · actualizado el 18 de noviembre de 2026