hreflang y canonical para 20 idiomas en Next.js 15: API de metadatos, mapa del sitio y errores de tipo
Dos tareas diferentes
canonical y hreflang a menudo se confunden y, debido a esto, la indexación de traducciones no funciona.
- canonical dice: “del grupo de páginas idénticas, esta es la principal”. Las traducciones no son páginas idénticas.
- hreflang dice: “esta página tiene versiones en otros idiomas, aquí están sus direcciones”.
De ahí la regla principal: cada versión lingüística apunta canónicamente a sí misma. Si /kk/blog/post establece canónico en /en/blog/post, Google considera la versión kazaja como un duplicado de la inglesa y no la muestra en los resultados.
Requisitos de marcado
- hreflang recíproco: si la página A enlaza con B, entonces B debe enlazar con A. Google ignora los enlaces no recíprocos.
- Cada página se incluye en el conjunto.
- Códigos - ISO 639-1 para idioma y, si es necesario, ISO 3166-1 alfa-2 para región separada por un guión:
ru,kk,en,pt-BR. El guión bajo (pt_BR) no es adecuado. x-default- página para usuarios cuyo idioma no se encuentra en la lista: generalmente selección de idioma o versión principal.- Sólo URL absolutas, y exactamente aquellas que devuelven 200 y se consideran canónicas. El enlace hreflang a una dirección con redireccionamiento es un error.
Fuente única de verdad
La lista de configuraciones regionales y la disponibilidad de traducción para una página específica deben tomarse de un solo lugar:
// lib/i18n/config.ts
export const SITE = "https://example.com";
export const LOCALES = ["ru", "en", "kk", "uz", "tr", "de", "fr", "es", "pt-BR", "it",
"pl", "uk", "ar", "hi", "id", "ja", "ko", "zh", "vi", "th"] as const;
export type Locale = (typeof LOCALES)[number];
export const DEFAULT_LOCALE: Locale = "en";
export function localizedUrl(locale: Locale, path: string) {
return `${SITE}/${locale}${path === "/" ? "" : path}`;
}generarMetadatos
// app/[locale]/blog/[slug]/page.tsx
import type { Metadata } from "next";
import { LOCALES, type Locale, localizedUrl, DEFAULT_LOCALE } from "@/lib/i18n/config";
import { getPostTranslations } from "@/lib/posts";
export async function generateMetadata({
params,
}: {
params: Promise<{ locale: Locale; slug: string }>;
}): Promise<Metadata> {
const { locale, slug } = await params;
const translations = await getPostTranslations(slug); // только реально переведённые локали
const path = `/blog/${slug}`;
const languages: Record<string, string> = {};
for (const l of LOCALES) {
if (translations.includes(l)) languages[l] = localizedUrl(l, path);
}
if (translations.includes(DEFAULT_LOCALE)) {
languages["x-default"] = localizedUrl(DEFAULT_LOCALE, path);
}
return {
alternates: {
canonical: localizedUrl(locale, path), // сама на себя
languages,
},
};
}En Next.js 15, params es una Promesa, entonces await. Establezca metadataBase en el diseño raíz si está utilizando rutas relativas; aquí las direcciones son absolutas y es más confiable.
Páginas sin traducir
El problema más común con los sitios multilingües: 5 están traducidos a 20 idiomas y las 15 direcciones restantes proporcionan texto en inglés bajo /de/, /ja/, etc. Son 15 tomas para cada artículo. Opciones:
- 1.No genere tales rutas:
generateStaticParamsdevuelve solo los pares existentes, y enpage.tsxpara los que faltan -notFound(). - 2.Si la ruta debe existir (por ejemplo, la interfaz general está traducida, pero el artículo no), proporcione la página con
robots: { index: false }y no la incluya en hreflang ni en el mapa del sitio.
El código anterior ya tiene esto en cuenta: solo las configuraciones regionales de translations se incluyen en languages.
Mapa del sitio con alternativas
hreflang también se puede especificar en el mapa del sitio; esto es conveniente cuando hay muchas páginas:
// app/sitemap.ts
import type { MetadataRoute } from "next";
import { localizedUrl, type Locale } from "@/lib/i18n/config";
import { getAllPostsWithTranslations } from "@/lib/posts";
export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
const posts = await getAllPostsWithTranslations();
return posts.flatMap((post) =>
post.locales.map((locale: Locale) => ({
url: localizedUrl(locale, `/blog/${post.slug}`),
lastModified: post.updatedAt,
alternates: {
languages: Object.fromEntries(
post.locales.map((l: Locale) => [l, localizedUrl(l, `/blog/${post.slug}`)])
),
},
}))
);
}Elija un método: en <head> o en el mapa del sitio. Ambos son válidos al mismo tiempo, pero si divergen, obtendrás señales contradictorias. Con 20 idiomas y miles de páginas, considere el límite de 50.000 URL por archivo y divida el mapa del sitio mediante generateSitemaps.
Diagnóstico
- Search Console → Indexación de páginas → “Duplicado, Google ha elegido una página canónica diferente” en traducciones: verifica canónica y que el texto esté realmente traducido y no sea el mismo que el original.
- Ver el HTML fuente, no el DOM en DevTools:
curl -s https://example.com/kk/blog/post | grep -E 'hreflang|canonical'. Las etiquetas deben estar en la respuesta del servidor. - Compruebe la reciprocidad con un script: para cada página, cargue todas las URL desde su hreflang y asegúrese de que cada una de ellas enlace.
- Redirecciones por idioma del navegador. Si
/redirige automáticamente aAccept-Language, es posible que el robot (que normalmente no envía este encabezado) nunca vea algunas de las versiones. Ofrezca selección de idioma, pero no fuerce las redirecciones desde las URL de idioma.
Limitaciones
hreflang es una pista, no una directiva: Google puede mostrar una versión diferente si la considera más relevante. Yandex admite hreflang, pero para la audiencia de habla rusa, la vinculación regional en Webmaster puede significar más. Y si las traducciones están hechas a máquina y son de mala calidad, un marcado adecuado no las salvará de una calificación de baja calidad.
Нужна реализация под ваш проект или аудит архитектуры?
Разрабатываем сайты на Next.js, Telegram-ботов, интеграции с CRM и ИИ-агентов под ключ.