Canonical URLs & Multilingual Hreflang in Next.js: alternates and localized routes

+-----------------------------------------------------------------------------------+
|                        Bidirectional Hreflang Alternate Matrix                    |
+-----------------------------------------------------------------------------------+
             │                                                         │
             ▼ (Canonical URL: /es-es/courses)                         ▼ (Canonical URL: /en-us/courses)
+------------------------------------------+       +------------------------------------------+
|          Locale Page: ES-ES              |       |          Locale Page: EN-US              |
|                                          |       |                                          |
|  <link rel="canonical"                   |       |  <link rel="canonical"                   |
|        href="https://.../es-es/courses"> |       |        href="https://.../en-us/courses"> |
|                                          |       |                                          |
|  <link rel="alternate" hreflang="es-ES"  |◄─────►|  <link rel="alternate" hreflang="es-ES"  |
|        href="https://.../es-es/courses"> |       |        href="https://.../es-es/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: URLs normalize WITHOUT trailing slashes (/blog/post)
  // true: URLs normalize WITH trailing slashes (/blog/post/)
  trailingSlash: false,

  // Strict production security headers
  poweredByHeader: false,
  reactStrictMode: true,
};

export default nextConfig;

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

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

interface AlternatesConfigOptions {
  pathname: string; // Relative path without locale prefix, e.g., '/courses/nextjs-15'
  currentLocale: AppLocale;
}

export function buildLocalizedAlternates({
  pathname,
  currentLocale,
}: AlternatesConfigOptions) {
  const baseUrl = process.env.NEXT_PUBLIC_APP_URL || 'https://agenticlab.dev';
  // Strip leading and trailing slashes for clean URL concatenation
  const cleanPath = pathname.replace(/^\/+|\/+$/g, '');

  // 1. Resolve canonical URL for the current active locale
  const canonicalPath = cleanPath ? `/${currentLocale}/${cleanPath}` : `/${currentLocale}`;
  const canonicalUrl = `${baseUrl}${canonicalPath}`;

  // 2. Generate reciprocal hreflang links for all supported locales
  const languages: Record<string, string> = {};

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

  // 3. Inject x-default fallback (pointing to the global English 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;

  // Validate locale parameter against supported configurations
  if (!SUPPORTED_LOCALES.includes(locale as AppLocale)) {
    notFound();
  }

  const typedLocale = locale as AppLocale;

  // Construct canonical URL and symmetric hreflang matrix
  const alternates = buildLocalizedAlternates({
    pathname: `/courses/${slug}`,
    currentLocale: typedLocale,
  });

  return {
    title: `Next.js 15 Platform Engineering (${typedLocale.toUpperCase()})`,
    description: 'Deep-dive architectural training covering Metadata API, Server Components, and Core Web Vitals.',
    // Alternates configuration compiled into HTML head links
    alternates: {
      canonical: alternates.canonical,
      languages: alternates.languages,
    },
    openGraph: {
      title: 'Next.js 15: Architecture and Enterprise 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: {locale}
        </span>
        <h1 className="text-3xl font-bold mt-2">Course: {slug}</h1>
      </header>
      <div className="mt-6 text-text-muted leading-relaxed">
        Interactive educational module with in-depth source code analysis.
      </div>
    </article>
  );
}