Kurs Next.js · Moduł 9: Integracje i zaawansowane funkcje
Internacjonalizacja z next-intl
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-intlPo 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.jsonKlucze 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.cssKatalog 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. next-intl w Next.js służy do:
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