Type-Safe Internationalization: next-intl, rootParams, and Seamless Locale Switching

Входящий HTTP-запрос (/de/checkout):
           │
           ▼
┌────────────────────────────────────────────────────────┐
│ Edge Middleware / i18n Routing Layer                   │
│ 1. Анализ Accept-Language & Cookie (NEXT_LOCALE)       │
│ 2. Определение локали: 'de'                            │
│ 3. Валидация в белом списке: ['en', 'de', 'fr', 'es']  │
└────────────────────────────────────────────────────────┘
           │
           ▼
┌────────────────────────────────────────────────────────┐
│ Server Components Lifecycle (RSC + next-intl)          │
│ 1. setRequestLocale('de') -> фиксация контекста        │
│ 2. getTranslations({ locale: 'de', namespace })        │
│ 3. Динамический импорт словаря: messages/de.json       │
│ 4. Серверная ICU-интерполяция (валюта EUR, плюрал)     │
└────────────────────────────────────────────────────────┘
           │
           ▼
Вывод в браузер:
  - Готовый HTML: "Gesamtsumme: 1.499,00 €"
  - Клиентский JS-бандл: 0 КБ библиотек перевода!

Архитектура разделения словарей между RSC и Client
                 
               [Запрос к странице /es/products/42]
                                │
                                ▼
                   ┌──────────────────────────┐
                   │  app/[locale]/page.tsx   │
                   │  (React Server Component)│
                   └────────────┬─────────────┘
                                │
        ┌───────────────────────┴───────────────────────┐
        │                                               │
Серверные переводы (RSC)                      Клиентские переводы (Client)
  - Каталог товаров                             - Интерактивная корзина
  - Описание и характеристики                   - Валидация ввода количества
  - SEO-метаданные & hreflang                   - Модальные уведомления
        │                                               │
        ▼                                               ▼
  getTranslations('Catalog')                  <NextIntlClientProvider
  Словарь остается на сервере!                  messages={{ Cart: ... }}>
  В бандл клиента: 0 КБ JS                      В бандл клиента: < 2 КБ JSON

import { getRequestConfig } from 'next-intl/server';
import { notFound } from 'next/navigation';
import { routing } from './routing';

export default getRequestConfig(async ({ requestLocale }) => {
  // Асинхронное получение локали из контекста входящего запроса (Next.js 16)
  let locale = await requestLocale;

  // Валидация: если локаль отсутствует или не поддерживается, прерываем выполнение
  if (!locale || !routing.locales.includes(locale as any)) {
    locale = routing.defaultLocale;
  }

  return {
    locale,
    // Динамический импорт строго требуемого словаря
    messages: (await import(`../messages/${locale}.json`)).default,
    // Глобальные форматы дат, времени и валют
    formats: {
      dateTime: {
        short: {
          day: 'numeric',
          month: 'short',
          year: 'numeric',
        },
        fullWithTime: {
          day: 'numeric',
          month: 'long',
          year: 'numeric',
          hour: '2-digit',
          minute: '2-digit',
        },
      },
      number: {
        currencyEUR: {
          style: 'currency',
          currency: 'EUR',
        },
        currencyUSD: {
          style: 'currency',
          currency: 'USD',
        },
        percentage: {
          style: 'percent',
          minimumFractionDigits: 1,
        },
      },
    },
  };
});

import { defineRouting } from 'next-intl/routing';
import { createNavigation } from 'next-intl/navigation';

export const routing = defineRouting({
  // Список всех поддерживаемых языковых локалей
  locales: ['en', 'de', 'es', 'ru', 'ja'] as const,

  // Локаль по умолчанию при обращении к корневому URL
  defaultLocale: 'en',

  // Стратегия префикса в URL: 'always' (/en/about) или 'as-needed' (about для default)
  localePrefix: 'always',

  // Определение локали по заголовкам браузера при первом визите
  localeDetection: true,
});

export type Locale = (typeof routing.locales)[number];

// Генерация типобезопасных оберток над навигационными компонентами Next.js
export const { Link, redirect, usePathname, useRouter, getPathname } =
  createNavigation(routing);

import createMiddleware from 'next-intl/middleware';
import { routing } from './i18n/routing';

export default createMiddleware(routing);

export const config = {
  // Исключаем системные файлы, картинки и API-роуты
  matcher: ['/', '/(en|de|es|ru|ja)/:path*', '/((?!_next|_vercel|.*\\..*).*)'],
};

import { notFound } from 'next/navigation';
import { setRequestLocale } from 'next-intl/server';
import { routing, Locale } from '@/i18n/routing';
import { Metadata } from 'next';

interface RootLocaleLayoutProps {
  children: React.ReactNode;
  params: Promise<{ locale: string }>;
}

export function generateStaticParams() {
  return routing.locales.map((locale) => ({ locale }));
}

export async function generateMetadata(props: RootLocaleLayoutProps): Promise<Metadata> {
  const { locale } = await props.params;

  return {
    title: {
      template: '%s | Global Enterprise SaaS',
      default: 'Global Enterprise SaaS',
    },
    // Формирование hreflang ссылок для SEO
    alternates: {
      canonical: `https://acme.org/${locale}`,
      languages: {
        en: 'https://acme.org/en',
        de: 'https://acme.org/de',
        es: 'https://acme.org/es',
        ru: 'https://acme.org/ru',
        ja: 'https://acme.org/ja',
        'x-default': 'https://acme.org/en',
      },
    },
  };
}

export default async function RootLocaleLayout(props: RootLocaleLayoutProps) {
  const { locale } = await props.params;

  // Валидация переданного сегмента локали
  if (!routing.locales.includes(locale as Locale)) {
    notFound();
  }

  // Фиксация локали для статического рендеринга (SSG / Static Rendering)
  setRequestLocale(locale);

  return (
    <html lang={locale} dir={locale === 'ar' || locale === 'he' ? 'rtl' : 'ltr'}>
      <body className="antialiased bg-bg-base text-text-primary">
        {props.children}
      </body>
    </html>
  );
}

import { getTranslations, setRequestLocale } from 'next-intl/server';
import { getFormatter } from 'next-intl/server';
import { InteractivePaymentButton } from '@/components/checkout/interactive-payment-button';

interface CheckoutPageProps {
  params: Promise<{ locale: string }>;
}

export default async function CheckoutPage(props: CheckoutPageProps) {
  const { locale } = await props.params;
  
  // Включаем поддержку статической генерации для текущего маршрута
  setRequestLocale(locale);

  // Извлекаем строго изолированное пространство имен перевода 'Checkout'
  const t = await getTranslations('Checkout');
  const format = await getFormatter();

  const totalAmount = 1499.50;
  const itemsCount = 3;
  const deliveryDate = new Date(Date.now() + 3 * 24 * 60 * 60 * 1000);

  return (
    <main className="max-w-4xl mx-auto p-8 space-y-6">
      <h1 className="text-3xl font-extrabold">{t('pageTitle')}</h1>
      
      {/* Плюрализация по правилам ICU */}
      <p className="text-text-muted">
        {t('summaryItemsCount', { count: itemsCount })}
      </p>

      {/* Форматирование валюты с учетом локали */}
      <div className="p-4 rounded-xl border border-border bg-bg-surface flex justify-between items-center">
        <span className="font-medium text-lg">{t('totalToPay')}:</span>
        <span className="font-mono text-2xl font-bold text-accent-cyan">
          {format.number(totalAmount, { style: 'currency', currency: locale === 'en' ? 'USD' : 'EUR' })}
        </span>
      </div>

      {/* Форматирование даты */}
      <p className="text-sm text-text-subtle">
        {t('estimatedDelivery', {
          date: format.dateTime(deliveryDate, { dateStyle: 'long' }),
        })}
      </p>

      {/* Интерактивный клиентский компонент: передаем только нужные ключи */}
      <InteractivePaymentButton 
        buttonLabel={t('payButton')}
        processingLabel={t('processing')}
        amount={totalAmount}
      />
    </main>
  );
}

{
  "Checkout": {
    "pageTitle": "Оформление заказа",
    "summaryItemsCount": "{count, plural, one {# товар} few {# товара} many {# товаров} other {# товара}} в корзине",
    "totalToPay": "Итого к оплате",
    "estimatedDelivery": "Ориентировочная дата доставки: {date}",
    "payButton": "Оплатить заказ",
    "processing": "Обработка платежа..."
  }
}