Канонічні URL та багатомовні hreflang у Next.js: alternates та localized routes

+-----------------------------------------------------------------------------------+
|                        Матриця перехресних зв'язків hreflang                      |
+-----------------------------------------------------------------------------------+
             │                                                         │
             ▼ (Канонічний URL: /uk-ua/courses)                        ▼ (Канонічний URL: /en-us/courses)
+------------------------------------------+       +------------------------------------------+
|          Сторінка локалі: UK-UA          |       |          Сторінка локалі: EN-US          |
|                                          |       |                                          |
|  <link rel="canonical"                   |       |  <link rel="canonical"                   |
|        href="https://.../uk-ua/courses"> |       |        href="https://.../en-us/courses"> |
|                                          |       |                                          |
|  <link rel="alternate" hreflang="uk-UA"  |◄─────►|  <link rel="alternate" hreflang="uk-UA"  |
|        href="https://.../uk-ua/courses"> |       |        href="https://.../uk-ua/courses"> |
|                                          |       |                                          |
|  <link rel="alternate" hreflang="en-US"  |◄─────►|  <link rel="alternate" hreflang="en-US"  |
|        href="https://.../en-us/courses"> |       |        href="https://.../en-us/courses"> |
|                                          |       |                                          |
|  <link rel="alternate"                   |◄─────►|  <link rel="alternate"                   |
|        hreflang="x-default"              |       |        hreflang="x-default"              |
|        href="https://.../en-us/courses"> |       |        href="https://.../en-us/courses"> |
+------------------------------------------+       +------------------------------------------+

import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  // false: нормалізація адрес БЕЗ кінцевого слеша (/blog/post)
  // true: нормалізація адрес ІЗ кінцевим слешем (/blog/post/)
  trailingSlash: false,

  // Вимкнення службових заголовків та увімкнення суворого режиму
  poweredByHeader: false,
  reactStrictMode: true,
};

export default nextConfig;

export const SUPPORTED_LOCALES = ['uk-ua', 'en-us', 'es-es', 'de-de'] as const;
export type AppLocale = (typeof SUPPORTED_LOCALES)[number];

export const DEFAULT_LOCALE: AppLocale = 'en-us';

interface AlternatesConfigOptions {
  pathname: string; // Відносний шлях без префікса локалі, наприклад: '/courses/nextjs-15'
  currentLocale: AppLocale;
}

export function buildLocalizedAlternates({
  pathname,
  currentLocale,
}: AlternatesConfigOptions) {
  const baseUrl = process.env.NEXT_PUBLIC_APP_URL || 'https://agenticlab.dev';
  // Очищення зайвих слешів на початку та в кінці рядка
  const cleanPath = pathname.replace(/^\/+|\/+$/g, '');

  // 1. Формування канонічної адреси для активної локалі
  const canonicalPath = cleanPath ? `/${currentLocale}/${cleanPath}` : `/${currentLocale}`;
  const canonicalUrl = `${baseUrl}${canonicalPath}`;

  // 2. Генерація перехресних мовних зв'язків для всіх підтримуваних локалей
  const languages: Record<string, string> = {};

  for (const locale of SUPPORTED_LOCALES) {
    const localePath = cleanPath ? `/${locale}/${cleanPath}` : `/${locale}`;
    languages[locale] = `${baseUrl}${localePath}`;
  }

  // 3. Додавання резервного x-default (за замовчуванням глобальна англійська версія)
  const defaultPath = cleanPath ? `/${DEFAULT_LOCALE}/${cleanPath}` : `/${DEFAULT_LOCALE}`;
  languages['x-default'] = `${baseUrl}${defaultPath}`;

  return {
    canonical: canonicalUrl,
    languages,
  };
}

import type { Metadata } from 'next';
import { notFound } from 'next/navigation';
import {
  buildLocalizedAlternates,
  SUPPORTED_LOCALES,
  type AppLocale,
} from '@/lib/seo/alternates';

interface Props {
  params: Promise<{
    locale: string;
    slug: string;
  }>;
}

export async function generateMetadata({ params }: Props): Promise<Metadata> {
  const { locale, slug } = await params;

  // Перевірка підтримки запитуваної локалі
  if (!SUPPORTED_LOCALES.includes(locale as AppLocale)) {
    notFound();
  }

  const typedLocale = locale as AppLocale;

  // Побудова канонічної адреси та симетричної матриці hreflang
  const alternates = buildLocalizedAlternates({
    pathname: `/courses/${slug}`,
    currentLocale: typedLocale,
  });

  return {
    title: `Архітектура Next.js 15 (${typedLocale.toUpperCase()})`,
    description: 'Глибокий інженерний курс: Metadata API, серверні компоненти та оптимізація Core Web Vitals.',
    // Блок alternates для пошукових краулерів
    alternates: {
      canonical: alternates.canonical,
      languages: alternates.languages,
    },
    openGraph: {
      title: 'Курс Next.js 15: Архітектура та SEO',
      url: alternates.canonical,
      locale: typedLocale.replace('-', '_'),
    },
  };
}

export default async function CoursePage({ params }: Props) {
  const { locale, slug } = await params;

  return (
    <article className="max-w-4xl mx-auto py-10 px-4">
      <header>
        <span className="text-xs uppercase font-mono text-accent-cyan">
          Локаль: {locale}
        </span>
        <h1 className="text-3xl font-bold mt-2">Курс: {slug}</h1>
      </header>
      <div className="mt-6 text-text-muted leading-relaxed">
        Інтерактивний навчальний модуль із детальним аналізом вихідного коду.
      </div>
    </article>
  );
}