Jak uczynić istniejącą aplikację Next.js wielojęzyczną (i18n) po fakcie (Przewodnik i18n 2026)

Dodanie internacjonalizacji (i18n) do projektu Next.js od samego początku jest dość proste. Ale co zrobić, gdy masz już dojrzałą aplikację wdrożoną w jednym języku i musisz uczynić ją wielojęzyczną po fakcie?

Z tradycyjnymi bibliotekami, takimi jak next-intl czy next-i18next, to prawdziwy koszmar:

• Ręczne wyszukiwanie zahardkodowanych tekstów w setkach plików JSX/TSX.
• Tworzenie zagnieżdżonych plików JSON i wymyślanie sztucznych kluczy (pages.dashboard.header.title).
• Zastępowanie tekstów wywołaniami hooków (t('...')).
• Przebudowa całego katalogu app/ do app/[locale]/..., co niszczy istniejące linki i SEO.

W 2026 roku nie musisz przepisywać swojej bazy kodu. Z Intlayer wdrożysz wielojęzyczność w kilka minut dzięki automatycznej ekstrakcji, tłumaczeniom AI i elastycznemu routingowi.

Szukasz pełnego przewodnika technicznego krok po kroku dla Next.js 16 App Router? Sprawdź naszą dokumentację: Tłumaczenie Next.js 16 z Intlayer.

Spis treści

Dylemat retrofittingu: Dlaczego tłumaczenie istniejącej aplikacji bywa trudne

Trzy główne wyzwania:

1. Destrukcja kodu: Ręczne przenoszenie tekstów wymaga edycji niemal każdego komponentu.
2. Wymuszony routing: Konieczność przenoszenia stron do folderu [locale].
3. Żmudna praca nad tłumaczeniami: Tłumaczenie setek kluczy na wiele języków.

Intlayer rozwiązuje te problemy dzięki wsparciu kompilatora, deklaratywnym słownikom i elastycznemu routingowi.

Zautomatyzowana ekstrakcja treści (bez ręcznego szukania)

Opcja A: Narzędzie CLI (npx intlayer extract)

Uruchom narzędzie ekstrakcji bezpośrednio w swoim projekcie:

npx intlayer extract

Narzędzie wygeneruje deklaracje (.content.ts) obok Twoich komponentów.

Opcja B: Kompilator Intlayer (Ekstrakcja w czasie budowania)

Pisz zwykły tekst w komponentach. Kompilator wyodrębni go w czasie budowania i wstawi przetłumaczony kod:

// Write normal React code. The compiler extracts the text automatically
export default function HomePage() {
  return (
    <section>
      <h1>Welcome to our platform</h1>
      <p>Start exploring our modern features today.</p>
    </section>
  );
}

Za kulisami Intlayer buduje słownik i łączy komponent ze zlokalizowaną treścią, całkowicie eliminując etap ręcznego refaktoryzowania.

W takim przypadku wygenerowany zostanie plik src/app/page.content.ts o następującej zawartości:

import { Dictionary } from "intlayer";

const content = {
  key: "home-page",
  content: {
    welcomeToOurPlatform: t({ en: "Welcome to our platform" }),
    startExploringOurModernFeaturesToday: t({
      en: "Start exploring our modern features today.",
    }),
  },
};

export default content;

Tłumaczenie AI z Twoim ulubionym LLM

Błyskawicznie tłumacz słowniki za pomocą OpenAI, Anthropic, DeepSeek lub Mistral:

npx intlayer fill

import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH, Locales.GERMAN],
    defaultLocale: Locales.ENGLISH,
  },
  ai: {
    provider: "openai",
    model: "gpt-4o-mini",
    apiKey: process.env.OPENAI_API_KEY,
    applicationContext: "Panel SaaS dla produktywności i współpracy zespołowej",
  },
};

export default config;

Uruchomienie npx intlayer fill automatycznie uzupełnia deklaracje .content.ts o tłumaczenia dla wszystkich skonfigurowanych języków:

import { Dictionary } from "intlayer";

const content = {
  key: "home-page",
  content: {
    welcomeToOurPlatform: t({
      en: "Welcome to our platform",
      fr: "Bienvenue sur notre plateforme",
      es: "Bienvenido a nuestra plataforma",
      pl: "Witamy na naszej platformie",
    }),
    startExploringOurModernFeaturesToday: t({
      en: "Start exploring our modern features today.",
      fr: "Découvrez nos fonctionnalités modernes dès aujourd'hui.",
      es: "Comience a explorar nuestras funciones modernas hoy.",
      pl: "Odkryj nasze nowoczesne funkcje już dziś.",
    }),
  },
};

export default content;

Ponieważ Intlayer dostarcza modelowi LLM ogólny applicationContext, wygenerowane tłumaczenia znacznie lepiej zachowują niuanse techniczne, ton marki i kontekst gramatyczny niż tradycyjne narzędzia automatyczne.

Aby upewnić się, że żaden tekst nie został pominięty przed wdrożeniem na produkcję:

npx intlayer test

Routing wielojęzyczny bez naruszania istniejących URL

Intlayer zapewnia:

• Tryb parametrów / ciasteczek (search-params): Brak konieczności przenoszenia plików do [locale].
• Tryb prefiksów (prefix / prefix-all-locales): Prosta obsługa ścieżek URL przyjaznych dla SEO.

Skonfiguruj integrację z Next.js w kilka sekund:

import type { NextConfig } from "next";
import { withIntlayer } from "next-intlayer/server";

const nextConfig: NextConfig = {/* Your existing Next.js config */};

export default withIntlayer(nextConfig);

Owiń swój główny layout za pomocą IntlayerProvider:

import type { ReactNode } from "react";
import { IntlayerProvider } from "next-intlayer";
import { getLocale } from "next-intlayer/server";
import { getHTMLTextDir } from "intlayer";

export default async function RootLayout({
  children,
}: {
  children: ReactNode;
}) {
  const locale = await getLocale();

  return (
    <html lang={locale} dir={getHTMLTextDir(locale)}>
      <body>
        <IntlayerProvider defaultLocale={locale}>{children}</IntlayerProvider>
      </body>
    </html>
  );
}

Wielojęzyczne SEO

Zapewnij automatyczne generowanie zlokalizowanych metadanych i tagów hreflang:

import type { Metadata } from "next";
import { getLocale } from "next-intlayer/server";
import { getIntlayer } from "intlayer";

export const generateMetadata = async (): Promise<Metadata> => {
  const locale = await getLocale();
  const content = getIntlayer("home-page-metadata", locale);

  return {
    title: content.title,
    description: content.description,
  };
};

Więcej szczegółów: Gotowy na pełny przewodnik?

Szczegółową instrukcję krok po kroku z obsługą middleware, SSG (generateStaticParams) i komponentów serwerowych znajdziesz w dokumentacji:

👉 Kompletny przewodnik po tłumaczeniu Next.js 16 z Intlayer

Najczęściej zadawane pytania (FAQ)