hreflang і канонічний для 20 мов у Next.js 15: API метаданих, карта сайту та помилки типу
Дві різні завдання
canonical та hreflang часто плутають, і через це ламають індексацію перекладів.
- canonical каже: «з групи однакових сторінок головна ось ця». Переклади – не однакові сторінки.
- hreflang каже: «ця сторінка має версії іншими мовами, ось їхні адреси».
Звідси головне правило: кожна мовна версія вказує canonical на себе. Якщо /kk/blog/post ставить canonical на /en/blog/post, Google вважає казахську версію дублем англійською і не показує її у видачі.
Вимоги до розмітки
- hreflang взаємний: якщо сторінка A посилається на B, B повинна посилатися на A. Невзаємні посилання Google ігнорує.
- Кожна сторінка включає набір і саму себе.
- Коди - ISO 639-1 для мови і, при необхідності, ISO 3166-1 alpha-2 для регіону через дефіс:
ru,kk,en,pt-BR. Підкреслення (pt_BR) не підходить. x-default— сторінка для користувачів, чия мова не знайдена у списку: зазвичай вибір мови або основна версія.- Тільки абсолютні URL, і ті, що віддають 200 і самі себе вважають канонічними. Посилання hreflang на адресу з редиректом помилка.
Єдине джерело правди
Список локалей та наявність перекладу для конкретної сторінки повинні братися з одного місця:
// 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}`;
}generateMetadata
// 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,
},
};
}У Next.js 15 params - Promise, тому await. Задайте metadataBase у кореневому layout, якщо використовуєте відносні шляхи; тут адреси абсолютні, і це надійніше.
Неперекладені сторінки
Найчастіша проблема багатомовних сайтів: для 20 мов перекладено 5, а решта 15 адрес віддають англійський текст під /de/, /ja/ і так далі. Це 15 дублів на кожну статтю. Варіанти:
- 1.Не генерувати такі маршрути:
generateStaticParamsповертає лише існуючі пари, аpage.tsxдля відсутніх —notFound(). - 2.Якщо маршрут повинен існувати (наприклад, загальний інтерфейс переведений, а стаття ні), віддавати сторінку з
robots: { index: false }і не включати її у hreflang та sitemap.
Код вище вже враховує це: в languages потрапляють лише локалі з translations.
Sitemap з альтернативами
hreflang можна вказувати і в sitemap - це зручно, коли сторінок багато:
// 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}`)])
),
},
}))
);
}Вибирайте один спосіб - в <head> або в sitemap. Обидва одночасно допустимі, але якщо вони розходяться, ви отримаєте суперечливі сигнали. При 20 мовах і тисячах сторінок враховуйте ліміт 50 000 URL на файл і діліть sitemap через generateSitemaps.
Діагностика
- Search Console → Індексування сторінок → «Дублікат, Google вибрав іншу канонічну сторінку» на перекладах: перевірте canonical і що текст дійсно перекладено, а не збігається з оригіналом.
- Погляньте вихідний HTML, а не DOM у DevTools:
curl -s https://example.com/kk/blog/post | grep -E 'hreflang|canonical'. Теги мають бути у серверній відповіді. - Перевірте взаємність скриптом: для кожної сторінки завантажте всі URL з її hreflang і переконайтеся, що кожна з них посилається назад.
- Редиректи з мови браузера. Якщо
/автоматично перенаправляє поAccept-Language, робот (який зазвичай не надсилає цей заголовок) може ніколи не побачити частину версій. Пропонуйте вибір мови, але не пересилайте примусово з мовних URL-адрес.
Обмеження
hreflang - підказка, а не директива: Google може показати іншу версію, якщо вважає її більш релевантною. Яндекс підтримує hreflang, але для російськомовної аудиторії регіональна прив'язка у Вебмайстрі може означати більше. І якщо переклади машинні та неякісні, правильна розмітка не врятує їх від низької оцінки якості.
Нужна реализация под ваш проект или аудит архитектуры?
Разрабатываем сайты на Next.js, Telegram-ботов, интеграции с CRM и ИИ-агентов под ключ.