Kurs Next.js · Moduł 9: Integracje i zaawansowane funkcje

Internacjonalizacja z next-intl

10 min czytania ·
W tej lekcji9

Sklep Metropolii Quantum 2150 odwiedzają mieszkańcy z Warszawy, Nowego Jorku i Berlina. Jeśli teksty są wpisane na sztywno w komponentach, każdy nowy język oznacza kopiowanie całej aplikacji, a daty i ceny i tak wyświetlają się w złym formacie. Neo-Bot, tłumacz Metropolii, rozwiązuje to biblioteką next-intl - najpopularniejszym narzędziem do internacjonalizacji (i18n) w Next.js App Router.

Dlaczego next-intl?

Next.js nie dostarcza wbudowanej biblioteki i18n dla App Router, a jedynie wzorce routingu. next-intl wypełnia tę lukę, oferując:

  • Pełne wsparcie dla Server Components
  • Type-safe tłumaczenia z TypeScript
  • Formatowanie dat, liczb i walut
  • Obsługa pluralizacji
  • ICU Message Format
  • Routing oparty na locale

Wdrożenie zawsze przebiega w tej kolejności: definiujesz obsługiwane języki, tworzysz pliki tłumaczeń, konfigurujesz middleware wykrywające język i dopiero wtedy wyświetlasz tłumaczenia w komponentach.

Instalacja i konfiguracja

Krok 1: Instalacja

Biblioteka to jeden pakiet, który działa zarówno w komponentach serwerowych, jak i klienckich:

npm install next-intl

Po instalacji nic się jeszcze nie zmienia, bo next-intl trzeba skonfigurować w kilku plikach.

Krok 2: Struktura plików tłumaczeń

Tłumaczenia trzymamy w katalogu messages, jeden plik JSON na każdy język (locale):

messages/
├── pl.json
├── en.json
└── de.json

Klucze są pogrupowane w przestrzenie nazw, np. common czy products. Tak wygląda polski plik:

// messages/pl.json
{
  "common": {
    "welcome": "Witaj w Metropolii Quantum!",
    "login": "Zaloguj się",
    "logout": "Wyloguj się",
    "loading": "Ładowanie..."
  },
  "home": {
    "title": "Strona główna",
    "description": "Odkryj przyszłość technologii",
    "cta": "Rozpocznij przygodę"
  },
  "products": {
    "title": "Produkty",
    "price": "Cena: {price, number, ::currency/PLN}",
    "inStock": "{count, plural, =0 {Brak w magazynie} one {# sztuka} few {# sztuki} many {# sztuk} other {# sztuk}}",
    "addToCart": "Dodaj do koszyka"
  }
}

Wartości w klamrach to ICU Message Format. {price, number, ::currency/PLN} formatuje liczbę jako walutę, a plural wybiera formę zależną od liczby. Polski potrzebuje kategorii one, few i many, bo mówimy "1 sztuka", "3 sztuki", "5 sztuk".

Angielski plik ma te same klucze, ale prostszą pluralizację, bo angielski zna tylko one i other:

// messages/en.json
{
  "common": {
    "welcome": "Welcome to Quantum Metropolis!",
    "login": "Log in",
    "logout": "Log out",
    "loading": "Loading..."
  },
  "home": {
    "title": "Home",
    "description": "Discover the future of technology",
    "cta": "Start your journey"
  },
  "products": {
    "title": "Products",
    "price": "Price: {price, number, ::currency/USD}",
    "inStock": "{count, plural, =0 {Out of stock} one {# item} other {# items}}",
    "addToCart": "Add to cart"
  }
}

Klucze muszą być identyczne we wszystkich plikach, zmieniają się tylko wartości.

Krok 3: Konfiguracja next-intl

Najpierw jedno źródło prawdy o językach. as const zamienia tablicę w krotkę literałów, z której wyprowadzamy typ Locale:

// i18n/config.ts
export const locales = ['pl', 'en', 'de'] as const;
export const defaultLocale = 'pl' as const;

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

Teraz TypeScript wie, że Locale to dokładnie 'pl' | 'en' | 'de'.

Plik i18n/request.ts mówi bibliotece, jakie tłumaczenia załadować dla danego żądania. Funkcja getRequestConfig dostaje requestLocale, czyli obietnicę z językiem odczytanym z adresu:

// i18n/request.ts
import { getRequestConfig } from 'next-intl/server';
import { locales, defaultLocale } from './config';

export default getRequestConfig(async ({ requestLocale }) => {
  // Walidacja locale
  let locale = await requestLocale;
  if (!locale || !locales.includes(locale as any)) {
    locale = defaultLocale;
  }

  return {
    locale,
    messages: (await import(`../messages/${locale}.json`)).default,
    timeZone: 'Europe/Warsaw',
    now: new Date(),
  };
});

Nieznany język zamieniamy na domyślny, a funkcja zwraca locale razem z komunikatami, strefą czasową i bieżącą datą. requestLocale działa w next-intl 4, choć dokumentacja najnowszych wydań oznacza go jako rozwiązanie starsze i w Next.js 16.3+ odczytuje język przez next/root-params.

Krok 4: Middleware

Middleware wykrywa język z adresu lub nagłówków przeglądarki i przekierowuje na właściwą ścieżkę. W Next.js 16 ten plik nazywa się proxy.ts:

// middleware.ts (w Next.js 16: proxy.ts)
import createMiddleware from 'next-intl/middleware';
import { locales, defaultLocale } from './i18n/config';

export default createMiddleware({
  locales,
  defaultLocale,
  localePrefix: 'as-needed', // lub 'always' lub 'never'
});

export const config = {
  matcher: [
    // Wszystkie ścieżki oprócz API, _next, plików statycznych
    '/((?!api|_next|_vercel|.*\..*).*)',
  ],
};

localePrefix: 'as-needed' ukrywa prefiks dla języka domyślnego, więc polska strona ma adres /products, a angielska /en/products. matcher pomija API, pliki Next.js i pliki statyczne.

Krok 5: Struktura folderów z [locale]

Wszystkie strony przenosimy do dynamicznego segmentu [locale], dzięki czemu język jest częścią adresu:

app/
├── [locale]/
│   ├── layout.tsx
│   ├── page.tsx
│   ├── products/
│   │   ├── page.tsx
│   │   └── [id]/
│   │       └── page.tsx
│   └── about/
│       └── page.tsx
├── api/
└── globals.css

Katalog api zostaje poza segmentem, bo endpointy nie potrzebują wersji językowych.

Krok 6: Root Layout z locale

Layout w [locale] staje się głównym layoutem aplikacji. generateStaticParams generuje statyczne wersje dla wszystkich języków, a params jest od Next.js 15 obietnicą (w Next.js 16 nie da się go już odczytać synchronicznie):

// app/[locale]/layout.tsx
import { NextIntlClientProvider } from 'next-intl';
import { getMessages } from 'next-intl/server';
import { locales } from '@/i18n/config';
import { notFound } from 'next/navigation';

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

export default async function LocaleLayout({
  children,
  params,
}: {
  children: React.ReactNode;
  params: Promise<{ locale: string }>;
}) {
  const { locale } = await params;

  // Walidacja locale
  if (!locales.includes(locale as any)) {
    notFound();
  }

  const messages = await getMessages();

  return (
    <html lang={locale}>
      <body>
        <NextIntlClientProvider messages={messages}>
          {children}
        </NextIntlClientProvider>
      </body>
    </html>
  );
}

Nieobsługiwany język kończy się stroną 404. NextIntlClientProvider udostępnia tłumaczenia komponentom klienckim, a w next-intl 4 dziedziczy komunikaty automatycznie, więc prop messages jest opcjonalny.

Używanie tłumaczeń

W Server Components

W komponentach serwerowych używasz asynchronicznej funkcji getTranslations z nazwą przestrzeni:

// app/[locale]/page.tsx
import { getTranslations } from 'next-intl/server';

export default async function HomePage() {
  const t = await getTranslations('home');
  const tCommon = await getTranslations('common');

  return (
    <main>
      <h1>{t('title')}</h1>
      <p>{t('description')}</p>
      <button>{t('cta')}</button>
      <p>{tCommon('welcome')}</p>
    </main>
  );
}

// Generowanie metadanych z tłumaczeniami
export async function generateMetadata({ params }: Props) {
  const { locale } = await params;
  const t = await getTranslations({ locale, namespace: 'home' });

  return {
    title: t('title'),
    description: t('description'),
  };
}

Funkcja t zwraca tekst dla klucza w wybranej przestrzeni. generateMetadata używa jej z jawnym locale, więc tytuł strony też jest przetłumaczony.

W Client Components

W komponentach klienckich ten sam interfejs daje hook useTranslations:

// components/ProductCard.tsx
'use client';

import { useTranslations } from 'next-intl';

interface ProductCardProps {
  product: {
    id: string;
    name: string;
    price: number;
    stock: number;
  };
}

export function ProductCard({ product }: ProductCardProps) {
  const t = useTranslations('products');

  return (
    <div className="product-card">
      <h3>{product.name}</h3>
      <p>{t('price', { price: product.price })}</p>
      <p>{t('inStock', { count: product.stock })}</p>
      <button>{t('addToCart')}</button>
    </div>
  );
}

Drugi argument t przekazuje zmienne do komunikatu, więc { count: product.stock } wybierze właściwą formę liczby mnogiej. Komponent nie wie, jaki jest język, wie to provider.

Formatowanie

Daty i czas

Hook useFormatter formatuje daty według zasad bieżącego języka, korzystając z API Intl przeglądarki:

import { useFormatter } from 'next-intl';

function EventDate({ date }: { date: Date }) {
  const format = useFormatter();

  return (
    <div>
      {/* Pełna data */}
      <p>{format.dateTime(date, { dateStyle: 'full' })}</p>

      {/* Tylko data */}
      <p>{format.dateTime(date, {
        year: 'numeric',
        month: 'long',
        day: 'numeric'
      })}</p>

      {/* Czas względny */}
      <p>{format.relativeTime(date)}</p>

      {/* Zakres dat */}
      <p>{format.dateTimeRange(startDate, endDate, {
        dateStyle: 'medium'
      })}</p>
    </div>
  );
}

Ten sam kod da "sobota, 26 września 2026" po polsku i "Saturday, September 26, 2026" po angielsku.

Liczby i waluty

Te same zasady dotyczą liczb, procentów, jednostek i list. Separator tysięcy, symbol waluty i spójnik w liście zależą od języka:

import { useFormatter } from 'next-intl';

function PriceDisplay({ amount }: { amount: number }) {
  const format = useFormatter();

  return (
    <div>
      {/* Waluta */}
      <p>{format.number(amount, { style: 'currency', currency: 'PLN' })}</p>

      {/* Procenty */}
      <p>{format.number(0.25, { style: 'percent' })}</p>

      {/* Jednostki */}
      <p>{format.number(1500, {
        style: 'unit',
        unit: 'kilometer',
        unitDisplay: 'long'
      })}</p>

      {/* Listy */}
      <p>{format.list(['React', 'Next.js', 'TypeScript'], { type: 'conjunction' })}</p>
    </div>
  );
}

format.list wstawi "i" po polsku i "and" po angielsku, bez żadnego warunku w kodzie.

Przełącznik języków

Nawigacja świadoma języka pochodzi z funkcji createNavigation. Tworzysz ją raz, w osobnym pliku:

// i18n/navigation.ts
import { createNavigation } from 'next-intl/navigation';
import { locales, defaultLocale } from './config';

export const { Link, redirect, usePathname, useRouter } = createNavigation({
  locales,
  defaultLocale,
});

Te wersje Link, useRouter i usePathname znają listę języków i same dodają prefiks do adresu. Przełącznik korzysta z nich tak:

// components/LocaleSwitcher.tsx
'use client';

import { useLocale } from 'next-intl';
import { usePathname, useRouter } from '@/i18n/navigation';
import { locales } from '@/i18n/config';

const localeNames: Record<string, string> = {
  pl: 'Polski',
  en: 'English',
  de: 'Deutsch',
};

export function LocaleSwitcher() {
  const locale = useLocale();
  const router = useRouter();
  const pathname = usePathname();

  const handleChange = (newLocale: string) => {
    router.replace(pathname, { locale: newLocale });
  };

  return (
    <select
      value={locale}
      onChange={(e) => handleChange(e.target.value)}
      className="bg-gray-800 text-white px-3 py-2 rounded"
    >
      {locales.map((loc) => (
        <option key={loc} value={loc}>
          {localeNames[loc]}
        </option>
      ))}
    </select>
  );
}

router.replace(pathname, { locale: newLocale }) zostaje na tej samej stronie i zmienia tylko język. Stary import z next-intl/client nie istnieje w aktualnych wersjach biblioteki.

Linki z zachowaniem locale

Link z tego samego pliku automatycznie dopisuje prefiks aktualnego języka:

import { Link } from '@/i18n/navigation';

function Navigation() {
  return (
    <nav>
      {/* Link automatycznie dodaje prefix locale */}
      <Link href="/">Home</Link>
      <Link href="/products">Products</Link>
      <Link href="/about">About</Link>

      {/* Link do konkretnego locale */}
      <Link href="/about" locale="en">About (EN)</Link>
    </nav>
  );
}

Prop locale pozwala wskazać inny język, np. w stopce z listą wersji językowych.

Type-safe tłumaczenia

Typ komunikatów możemy wyprowadzić z polskiego pliku JSON i zarejestrować w next-intl przez rozszerzenie interfejsu AppConfig:

// types/messages.ts
import pl from '../messages/pl.json';

// Automatyczne typowanie z pliku JSON
type Messages = typeof pl;

declare module 'next-intl' {
  interface AppConfig {
    Messages: Messages;
  }
}

Teraz TypeScript będzie podpowiadać dostępne klucze, a także sprawdzi, czy przekazujesz wymagane parametry komunikatu:

const t = useTranslations('products');
t('title');     // OK
t('price', { price: 100 }); // OK z parametrem
t('nonExistent'); // TypeScript error!

Literówka w kluczu zatrzyma build, zamiast pokazać użytkownikowi surowy tekst products.nonExistent.

Praktyczny przykład - E-commerce

Strona produktów łączy tłumaczenie po stronie serwera z komponentem klienckim ProductCard z wcześniejszej sekcji:

// app/[locale]/products/page.tsx
import { getTranslations } from 'next-intl/server';
import { ProductCard } from '@/components/ProductCard';

export default async function ProductsPage() {
  const t = await getTranslations('products');
  const products = await getProducts();

  return (
    <div className="container mx-auto py-8">
      <h1 className="text-3xl font-bold mb-8">{t('title')}</h1>

      <div className="grid grid-cols-1 md:grid-cols-3 gap-6">
        {products.map((product) => (
          <ProductCard key={product.id} product={product} />
        ))}
      </div>
    </div>
  );
}

Nagłówek tłumaczy serwer, a karty same tłumaczą swoje etykiety. Rozszerzony plik polski dodaje filtry, sortowanie i licznik wyników:

// Rozszerzony messages/pl.json
{
  "products": {
    "title": "Nasze produkty",
    "filters": {
      "all": "Wszystkie",
      "inStock": "Dostępne",
      "onSale": "W promocji"
    },
    "sort": {
      "label": "Sortuj",
      "priceAsc": "Cena: od najniższej",
      "priceDesc": "Cena: od najwyższej",
      "newest": "Najnowsze"
    },
    "empty": "Nie znaleziono produktów",
    "results": "{count, plural, =0 {Brak wyników} one {# produkt} few {# produkty} many {# produktów} other {# produktów}}"
  }
}

Zagnieżdżone obiekty, jak filters czy sort, odczytasz kluczem z kropką, np. t('filters.all').

Podsumowanie

next-intl oferuje kompletne rozwiązanie i18n dla Next.js:

  • Server Components - pełne wsparcie z getTranslations
  • Client Components - hooki useTranslations, useFormatter
  • Type Safety - TypeScript podpowiada dostępne klucze
  • Formatowanie - daty, liczby, waluty, listy
  • Routing - automatyczne prefixy locale w URL
  • Pluralizacja - poprawna odmiana dla każdego języka

Moja rada: od pierwszego dnia trzymaj teksty w plikach JSON, nawet jeśli dziś obsługujesz jeden język. W następnej lekcji zapakujesz aplikację w kontener Docker.

Zapamiętaj: w Metropolii Quantum komponent zna tylko klucze, a język, formy liczby mnogiej i format dat dobiera za niego next-intl.

Kod do tej lekcji: App.tsx
import React, { useState } from 'react';

// Stworz API route dla Checkout Session

export default function CheckoutSessionAPI() {
  const [requestBody, setRequestBody] = useState(JSON.stringify({
    priceId: 'price_1234',
    quantity: 1,
    successUrl: '/success',
    cancelUrl: '/cancel',
  }, null, 2));
  const [response, setResponse] = useState<any>(null);
  const [isLoading, setIsLoading] = useState(false);

  // TODO: Zaimplementuj simulateCreateSession
  // Parsuj requestBody, waliduj, zwroc session URL

  return (
    <div style={{ background: '#0f0f23', minHeight: '100vh', padding: 20, color: '#e0e0e0', fontFamily: 'monospace' }}>
      <h1 style={{ color: '#64ffda' }}>Checkout Session API</h1>
      <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 20 }}>
        <div>
          <h3>Request Body</h3>
          <textarea value={requestBody} onChange={e => setRequestBody(e.target.value)}
            style={{ width: '100%', height: 200, background: '#0d1117', color: '#e0e0e0', border: '1px solid #333',
              borderRadius: 8, padding: 10, fontFamily: 'monospace', fontSize: 12 }} />
          {/* TODO: Przycisk "Wyslij request" */}
        </div>
        <div>
          <h3>Response</h3>
          {/* TODO: Wyswietl response JSON */}
        </div>
      </div>
    </div>
  );
}

Hasła z dokumentacji w tej lekcji

Widzisz błąd w tej lekcji?

Sprawdź się

Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.

  1. 1. next-intl w Next.js służy do:

  2. 2. Co zapewnia biblioteka next-intl w aplikacjach Next.js?

Zadania praktyczne w grze

  • Edytor kodu

    Zbuduj interfejs z wielojęzycznym wsparciem (i18n)

  • Układanie w pionie

    Ułóż kroki wdrożenia internacjonalizacji (i18n) w Next.js

  1. PytanieZaawansowane: Biblioteka next-intl
  2. PytanieZaawansowane: Internacjonalizacja z next-intl
  3. Zadanie z kodemZaawansowane: Praktyka: Wielojęzyczne wsparcie (i18n)
  4. Ułóż w kolejnościKonfiguracja i18n w Next.js

Przydatne artykuły