Jak sprawić, by istniejąca aplikacja Next.js stała się wielojęzyczna (i18n) (przewodnik i18n 2026)

Zobacz Szablon Aplikacji na GitHubie.

Spis treści

Dlaczego umiędzynarodowienie istniejącej aplikacji jest trudne?

Jeśli kiedykolwiek próbowałeś dodać wiele języków do aplikacji, która była budowana tylko dla jednego języka, to znasz ten ból. To nie jest tylko „trudne”, to żmudne. Musisz przejrzeć każdy plik, znaleźć każdy ciąg tekstowy i przenieść je do oddzielnych plików słownikowych.

Potem nadchodzi ryzykowna część: zastąpienie całego tego tekstu wywołaniami do kodu (hookami) bez psucia układu czy logiki. To ten rodzaj pracy, który wstrzymuje rozwój nowych funkcji na tygodnie i wydaje się być niekończącym się refaktoringiem.

Czym jest Kompilator Intlayer?

Kompilator Intlayer został stworzony po to, by pominąć tę ręczną pracę. Zamiast zmuszać Cię do ręcznego wyciągania ciągów znaków, kompilator robi to za Ciebie. Skanuje Twój kod, znajduje tekst i wykorzystuje AI do generowania słowników w tle. Następnie modyfikuje Twój kod podczas kompilacji (build), automatycznie wstrzykując potrzebne wywołania i18n. Zasadniczo nadal piszesz aplikację tak, jakby była w jednym języku, a kompilator zajmuje się wielojęzyczną transformacją natywnie.

Dokumentacja kompilatora: /pl/doc/compiler

Ograniczenia

Ponieważ kompilator wykonuje analizę i transformację kodu (wstawianie hooków i generowanie słowników) w czasie kompilacji, może on spowolnić proces budowania Twojej aplikacji.

Aby ograniczyć ten wpływ podczas programowania (development), możesz ustawić kompilator w trybie 'build-only' lub całkowicie go wyłączyć, gdy nie jest potrzebny.

Przewodnik krok po kroku, jak skonfigurować Intlayer w aplikacji Next.js

Krok 1: Instalacja zależności

Zainstaluj potrzebne pakiety za pomocą npm:

npm install intlayer next-intlayernpm install @intlayer/babel --save-devnpx intlayer init

• intlayer

  Główny pakiet dostarczający narzędzia do umiędzynarodowienia, takie jak zarządzanie konfiguracją, tłumaczenia, deklaracja treści, transpilacja oraz komendy CLI.

• next-intlayer

  Pakiet integrujący Intlayer z frameworkiem Next.js. Dostarcza context providery oraz hooki dla Next.js. Ponadto zawiera wtyczkę Next.js pozwalającą połączyć Intlayer z Webpackiem lub Turbopackiem, a także middleware do wykrywania języka, zarządzania cookies i obsługi przekierowań URL.

Krok 2: Konfiguracja projektu

Utwórz plik konfiguracyjny, by zdefiniować dostępne języki aplikacji:

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [Locales.ENGLISH, Locales.POLISH],    defaultLocale: Locales.POLISH,  },  routing: {    mode: "search-params",  },  compiler: {    /**     * Wskazuje, czy kompilator powinien być włączony.     */    enabled: true,    /**     * Katalog wyjściowy dla zoptymalizowanych słowników.     */    output: ({ locale, key }) => `compiler/${locale}/${key}.json`,    /**     * Wstaw tylko zawartość do wygenerowanego pliku, bez klucza.     */    noMetadata: false,    /**     * Prefiks klucza słownika     */    dictionaryKeyPrefix: "", // Remove base prefix    /**     * Wskazuje, czy komponenty powinny być zapisywane po transformacji.     * W ten sposób kompilator można uruchomić tylko raz, aby przetransformować aplikację, a następnie go usunąć.     */    saveComponents: false,  },  ai: {    provider: "openai",    model: "gpt-5-mini",    apiKey: process.env.OPEN_AI_API_KEY,    applicationContext: "Ta aplikacja to prosty przykład aplikacji mapowej",  },};export default config;

Uwaga: Upewnij się, że Twój OPEN_AI_API_KEY jest ustawiony w zmiennych środowiskowych.

Za pomocą tego pliku konfiguracyjnego możesz ustawić zlokalizowane adresy URL, przekierowania proxy, nazwy ciasteczek, lokalizację i rozszerzenie deklaracji treści, wyłączyć logi konsoli Intlayer i wiele więcej. Pełną listę parametrów znajdziesz w dokumentacji konfiguracji.

Krok 3: Integracja Intlayer z konfiguracją Next.js

Skonfiguruj swoje ustawienia Next.js, aby używać Intlayer:

import type { NextConfig } from "next";import { withIntlayer } from "next-intlayer/server";const nextConfig: NextConfig = {  /* opcjonalna dodatkowa konfiguracja Next.js tutaj */};export default withIntlayer(nextConfig);

Plugin withIntlayer() służy do integracji Intlayer z Next.js. Zapewnia budowanie plików słowników i monitoruje je w trybie deweloperskim. Definiuje zmienne środowiskowe Intlayer w środowiskach Webpack lub Turbopack. Ponadto dostarcza aliasy w celu optymalizacji wydajności i zapewnia pełną współpracę z Server Components.

Krok 4: Konfiguracja Babel

Kompilator Intlayer wymaga Babel do wyodrębniania i optymalizacji treści. Zaktualizuj swój plik babel.config.js (lub babel.config.json), aby zawierał wtyczki Intlayer:

const {  intlayerExtractBabelPlugin,  intlayerOptimizeBabelPlugin,  getExtractPluginOptions,  getOptimizePluginOptions,} = require("@intlayer/babel");module.exports = {  presets: ["next/babel"],  plugins: [    [intlayerExtractBabelPlugin, getExtractPluginOptions()],    [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()],  ],};

Krok 5: Wykrywanie języka na stronach

Wyczyść zawartość swojego RootLayout i zastąp ją poniższym przykładem:

import type { Metadata } from "next";import type { ReactNode } from "react";import "./globals.css";import { IntlayerClientProvider, LocalPromiseParams } from "next-intlayer";import { getHTMLTextDir, getIntlayer } from "intlayer";import { getLocale } from "next-intlayer/server";export { generateStaticParams } from "next-intlayer";export const generateMetadata = async (): Promise<Metadata> => {  const locale = await getLocale();  const { title, description, keywords } = getIntlayer("metadata", locale);  return {    title,    description,    keywords,  };};const RootLayout = async ({  children,}: Readonly<{  children: ReactNode;}>) => {  const locale = await getLocale();  return (    <html lang={locale} dir={getHTMLTextDir(locale)}>      <IntlayerClientProvider defaultLocale={locale}>        <body>{children}</body>      </IntlayerClientProvider>    </html>  );};export default RootLayout;

Krok 6: Kompilacja komponentów

Z włączonym kompilatorem absolutnie nie masz wymogu ręcznego deklarowania słowników treści (takich jak pliki .content.ts).

Zamiast tego po prostu wpisujesz treść jako standardowe ciągi znaków (hardcoded) bezpośrednio w kodzie. Intlayer przeskanuje kod źródłowy, wygeneruje tłumaczenia przy użyciu skonfigurowanego dostawcy AI i po cichu zastąpi te ciągi zlokalizowaną treścią podczas kroku kompilacji. Wszystko to jest w pełni zautomatyzowane.

Wystarczy pisać komponenty z zakodowanymi na sztywno ciągami znaków w domyślnym języku. Kompilator zajmie się resztą.

Przykład tego, jak może wyglądać Twoja strona:

import type { FC } from "react";import { IntlayerServerProvider } from "next-intlayer/server";import { getLocale } from "next-intlayer/server";const PageContent: FC = () => {return (  <>    <p>Zacznij od edytowania</p>    <code>src/app/page.tsx</code>  </>);};export default async function Page() {const locale = await getLocale();return (  <IntlayerServerProvider locale={locale}>    <PageContent />  </IntlayerServerProvider>);}

{key: "page-content",content: {  nodeType: "translation",  translation: {    en: {      getStartedByEditing: "Get started by editing",    },    fr: {      getStartedByEditing: "Commencez par éditer",    },    pl: {      getStartedByEditing: "Zacznij od edytowania",    },  }}}

import { type FC } from "react";import { IntlayerServerProvider, useIntlayer } from "next-intlayer/server";import { getLocale } from "next-intlayer/server";const PageContent: FC = () => {const content = useIntlayer("page-content");return (  <>    <p>{content.getStartedByEditing}</p>    <code>src/app/page.tsx</code>  </>);};export default async function Page() {const locale = await getLocale();return (  <IntlayerServerProvider locale={locale}>    <PageContent />  </IntlayerServerProvider>);}

• IntlayerClientProvider służy do dostarczania języka dzięcom po stronie klienta (Client Side).

• IntlayerServerProvider służy do dostarczania języka dzięcom po stronie serwera (Server Side).

  Layout and page cannot share a common server context because the server context system is based on a per-request data store (via React's cache mechanism), causing each "context" to be re-created for different segments of the application. Placing the provider in a shared layout would break this isolation, preventing the correct propagation of the server context values to your server components.

(Opcjonalnie) Krok 7: Uzupełnij brakujące tłumaczenia

Intlayer udostępnia narzędzie CLI, które pomaga uzupełnić brakujące tłumaczenia. Możesz użyć polecenia intlayer, aby przetestować i uzupełnić brakujące tłumaczenia ze swojego kodu.

npx intlayer test         # Przetestuj, czy brakuje tłumaczeń

npx intlayer fill         # Uzupełnij brakujące tłumaczenia

Więcej szczegółów znajdziesz w dokumentacji CLI

(Opcjonalnie) Krok 8: Konfiguracja Proxy do wykrywania języka

Skonfiguruj proxy w celu automatycznego wykrywania preferowanego języka użytkownika:

export { intlayerProxy as proxy } from "next-intlayer/proxy";export const config = {  matcher:    "/((?!api|static|assets|robots|sitemap|sw|service-worker|manifest|.*\\..*|_next).*)",};

intlayerProxy służy do wykrywania preferowanego języka użytkownika i przekierowywania go na odpowiedni adres URL, zgodnie z ustawieniami w pliku konfiguracyjnym. Dodatkowo umożliwia zapisanie preferowanego języka w ciasteczku (cookie).

(Opcjonalnie) Krok 8: Zmiana języka treści

Aby zmienić język treści w Next.js, zalecanym sposobem jest użycie komponentu Link w celu przekierowania użytkowników na odpowiednią zlokalizowaną stronę. Komponent Link umożliwia prefetching stron, co pomaga uniknąć pełnego odświeżenia witryny.

"use client";import type { FC } from "react";import { Locales, getHTMLTextDir, getLocaleName } from "intlayer";import { useLocale } from "next-intlayer";export const LocaleSwitcher: FC = () => {  const { locale, availableLocales, setLocale } = useLocale();  return (    <div>      <button popoverTarget="localePopover">{getLocaleName(locale)}</button>      <div id="localePopover" popover="auto">        {availableLocales.map((localeItem) => (          <button            key={localeItem}            aria-current={locale === localeItem ? "page" : undefined}            onClick={() => setLocale(localeItem)}          >            <span>              {/* Lokalizacja - np. PL */}              {localeItem}            </span>            <span>              {/* Język w swoim własnym Locale - np. Polski */}              {getLocaleName(localeItem, locale)}            </span>            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>              {/* Język w bieżącym Locale - np. Francés, jeśli bieżące locale to Locales.SPANISH */}              {getLocaleName(localeItem)}            </span>            <span dir="ltr" lang={Locales.ENGLISH}>              {/* Język po angielsku - np. French */}              {getLocaleName(localeItem, Locales.ENGLISH)}            </span>          </button>        ))}      </div>    </div>  );};

Alternatywnym sposobem jest użycie funkcji setLocale dostarczanej przez hook useLocale. Ta funkcja nie pozwala na prefetching strony. Więcej szczegółów znajdziesz w dokumentacji hooka useLocale.

(Opcjonalnie) Krok 10: Optymalizacja rozmiaru bundle'a

Podczas korzystania z next-intlayer słowniki są domyślnie dołączane do bundle'a dla każdej strony. Aby zoptymalizować rozmiar bundle'a, Intlayer udostępnia opcjonalną wtyczkę SWC, która inteligentnie zastępuje wywołania useIntlayer za pomocą makr. Zapewnia to, że słowniki są dołączane tylko do bundle'i stron, które faktycznie z nich korzystają.

Aby włączyć tę optymalizację, zainstaluj pakiet @intlayer/swc. Po zainstalowaniu next-intlayer automatycznie wykryje i użyje wtyczki:

npm install @intlayer/swc --save-dev

Uwaga: Ta optymalizacja jest dostępna tylko dla Next.js 13 i nowszych.

Uwaga: Ten pakiet nie jest instalowany domyślnie, ponieważ wtyczki SWC w Next.js są wciąż eksperymentalne. Może to ulec zmianie w przyszłości.

Uwaga: Jeśli ustawisz opcję importMode: 'dynamic' lub importMode: 'fetch' (w konfiguracji słownika), będzie ona polegać na Suspense, więc będziesz musiał owinąć wywołania useIntlayer w granicę Suspense. Oznacza to, że nie będziesz mógł używać useIntlayer bezpośrednio na najwyższym poziomie komponentu Strony / Layoutu.

Konfiguracja TypeScript

Intlayer używa rozszerzania modułów (module augmentation), aby czerpać korzyści z TypeScript i uczynić Twoją bazę kodu bardziej solidną.

Upewnij się, że Twoja konfiguracja TypeScript zawiera automatycznie generowane typy.

{  // ... Twoje istniejące konfiguracje TypeScript  "include": [    // ... Twoje istniejące konfiguracje TypeScript    ".intlayer/**/*.ts", // Uwzględnij autogenerowane typy  ],}

Konfiguracja Git

Zaleca się ignorowanie plików generowanych przez Intlayer. Pozwala to uniknąć ich commitowania do repozytorium Git.

Aby to zrobić, dodaj poniższe instrukje do pliku .gitignore:

# Ignoruj pliki generowane przez Intlayer.intlayer

Rozszerzenie VS Code

Aby usprawnić proces tworzenia aplikacji z Intlayer, możesz zainstalować oficjalne rozszerzenie Intlayer dla VS Code.

Zainstaluj z VS Code Marketplace

To rozszerzenie zapewnia:

• Autouzupełnianie kluczy tłumaczeń.
• Wykrywanie błędów w czasie rzeczywistym dla brakujących tłumaczeń.
• Podgląd inline przetłumaczonej treści.
• Szybkie akcje do łatwego tworzenia i aktualizowania tłumaczeń.

Więcej szczegółów na temat korzystania z rozszerzenia znajdziesz w dokumentacji rozszerzenia Intlayer dla VS Code.

(Opcjonalnie) Krok 11 : Wyodrębnij zawartość swoich komponentów

Jeśli masz istniejącą bazę kodu, transformacja tysięcy plików może być czasochłonna.

Aby ułatwić ten proces, Intlayer proponuje kompilator / ekstraktor, aby przetransformować komponenty i wyodrębnić zawartość.

Aby go skonfigurować, możesz dodać sekcję compiler w pliku intlayer.config.ts:

import { type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  // ... Reszta Twojej konfiguracji
  compiler: {
    /**
     * Wskazuje, czy kompilator powinien być włączony.
     */
    enabled: true,

    /**
     * Definiuje ścieżkę plików wyjściowych
     */
    output: ({ fileName, extension }) => `./${fileName}${extension}`,

    /**
     * Wskazuje, czy komponenty powinny zostać zapisane po transformacji. W ten sposób kompilator można uruchomić tylko raz, aby przetransformować aplikację, a następnie go usunąć.
     */
    saveComponents: false,

    /**
     * Prefiks klucza słownika
     */
    dictionaryKeyPrefix: "",
  },
};

export default config;

npx intlayer extract

npm install @intlayer/babel --save-dev

const { intlayerExtractBabelPlugin, getExtractPluginOptions,} = require("@intlayer/babel");module.exports = { presets: ["next/babel"], plugins: [   // Wyodrębnij zawartość z komponentów do słowników   [intlayerExtractBabelPlugin, getExtractPluginOptions()], ],};

npm run build # Lub npm run dev

Idź dalej

Aby pójść o krok dalej, możesz wdrożyć edytor wizualny lub wyeksportować swoją treść za pomocą CMS.