Jak uczynić istniejącą aplikację Vite i React wielojęzyczną (i18n) po fakcie (Przewodnik i18n 2026)

Dodanie internacjonalizacji (i18n) do projektu Vite i React od samego początku jest stosunkowo 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 react-i18next czy react-intl, proces ten bywa koszmarem:

• Ręczne wyszukiwanie zahardkodowanych tekstów w setkach plików JSX i TSX.
• Tworzenie zagnieżdżonych plików JSON i wymyślanie sztucznych kluczy (components.header.title itp.).
• Zastępowanie tekstów w kodzie skomplikowanymi wywołaniami hooków (t('...')).
• Przebudowa routingu po stronie klienta, zarządzania stanem oraz logiki przełączania języków.

W 2026 roku nie musisz przepisywać bazy kodu. Z Intlayer wdrożysz internacjonalizację w kilka minut dzięki automatycznej ekstrakcji, tłumaczeniom AI i bezproblemowej integracji z Vite.

Szukasz pełnego przewodnika technicznego krok po kroku dla Vite i React? Sprawdź naszą dokumentację: Tłumaczenie Vite i React z Intlayer.

Spis treści

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

Podczas internacjonalizacji istniejącej aplikacji Vite i React programiści napotykają trzy główne przeszkody:

1. Zakłócenie bazy kodu: Ręczne wyciąganie tekstów do słowników JSON wymaga edycji niemal każdego komponentu. Generuje to ogromne diffy w gicie, konflikty scalania i ryzyko regresji wizualnych.
2. Narzut związany z kluczami: Wymyślanie kluczy typu dashboard.hero.ctaButton dla każdego fragmentu tekstu spowalnia pracę i obciąża pamięć przy każdej modyfikacji interfejsu.
3. Żmudna praca translatorska: Po wyodrębnieniu tekstów ich tłumaczenie na 5, 10 lub 20 języków wiąże się z monotonnym kopiowaniem i wklejaniem lub kosztownymi usługami zewnętrznymi.

Intlayer rozwiązuje te problemy na poziomie architektury za pomocą ekstrakcji wspomaganej kompilatorem, deklaratywnych słowników na poziomie komponentów oraz natywnej integracji z Vite.

Automatyczna ekstrakcja treści (bez ręcznego szukania tekstów)

Zamiast ręcznie wyciągać każdy łańcuch znaków z JSX, Intlayer oferuje dwie wygodne ścieżki:

Opcja A: Ekstraktor CLI (npx intlayer extract)

Możesz uruchomić narzędzie do ekstrakcji Intlayer bezpośrednio w swojej bazie kodu:

npx intlayer extract

To polecenie analizuje komponenty React, wykrywa teksty widoczne dla użytkownika i automatycznie tworzy pliki deklaracji zawartości (.content.ts) tuż obok poszczególnych komponentów. Logika pozostaje deklaratywna, czytelna i w pełni bezpieczna typologicznie.

Opcja B: Kompilator Intlayer (Ekstrakcja w trakcie budowania)

Gdy kompilator Intlayer jest włączony w konfiguracji, możesz nadal pisać komponenty ze zwykłym tekstem w języku domyślnym. W trakcie budowania kompilator automatycznie ekstrahuje teksty i wstrzykuje zlokalizowaną zawartość:

// Pisz normalny kod React. Kompilator automatycznie wyodrębni tekst
export default function App() {
  return (
    <section>
      <h1>Witamy na naszej platformie</h1>
      <p>Zacznij odkrywać nowoczesne funkcje już dziś.</p>
    </section>
  );
}

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

W tym przypadku wygenerowany zostanie plik deklaracji src/App.content.ts o następującej strukturze:

import { Dictionary } from "intlayer";

const content = {
  key: "app",
  content: {
    witamyNaNaszejPlatformie: t({
      pl: "Witamy na naszej platformie",
    }),
    zacznijOdkrywacNowoczesneFunkcje: t({
      pl: "Zacznij odkrywać nowoczesne funkcje już dziś.",
    }),
  },
};

export default content;

Tłumaczenia oparte na sztucznej inteligencji z Twoim ulubionym modelem LLM

Po wyodrębnieniu treści tłumaczenie na dziesiątki języków nie powinno zajmować dni. Intlayer zawiera wbudowane narzędzie CLI do tłumaczeń AI, które łączy się bezpośrednio z OpenAI, Anthropic, DeepSeek lub Mistral przy użyciu Twoich własnych kluczy API:

npx intlayer fill

Skonfiguruj obsługiwane języki i dostawcę AI w pliku intlayer.config.ts:

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

const config: IntlayerConfig = {
  internationalization: {
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH, Locales.POLISH],
    defaultLocale: Locales.POLISH,
  },
  ai: {
    provider: "openai",
    model: "gpt-4o-mini",
    apiKey: process.env.OPENAI_API_KEY,
    applicationContext:
      "Nowoczesna aplikacja SaaS i panel zarządzania stworzone przy użyciu Vite i React",
  },
};

export default config;

Uruchomienie npx intlayer fill wypełnia pliki deklaracji wysokiej jakości tłumaczeniami dla wszystkich skonfigurowanych języków:

import { Dictionary } from "intlayer";

const content = {
  key: "app",
  content: {
    witamyNaNaszejPlatformie: t({
      pl: "Witamy na naszej platformie",
      en: "Welcome to our platform",
      fr: "Bienvenue sur notre plateforme",
      es: "Bienvenido a nuestra plataforma",
    }),
    zacznijOdkrywacNowoczesneFunkcje: t({
      pl: "Zacznij odkrywać nowoczesne funkcje już dziś.",
      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.",
    }),
  },
};

export default content;

Ponieważ Intlayer przekazuje applicationContext do modelu językowego, generowane tłumaczenia zachowują kontekst techniczny, ton marki i niuanse gramatyczne znacznie lepiej niż tradycyjne narzędzia.

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

npx intlayer test

Integracja z Vite i konfiguracja Providera

Integracja Intlayer z Vite sprowadza się do dodania wtyczki w vite.config.ts i otoczenia głównego komponentu za pomocą IntlayerProvider:

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react-swc";
import { intlayer } from "vite-intlayer";

export default defineConfig({
  plugins: [react(), intlayer()],
});

Od wersji Intlayer v9 kompilator jest bezpośrednio zintegrowany z wtyczką intlayer() i uruchamia się automatycznie po skonfigurowaniu compiler.enabled w intlayer.config.ts.

Otocz aplikację komponentem IntlayerProvider:

import { FC } from "react";
import { IntlayerProvider } from "react-intlayer";
import { MainContent } from "./MainContent";

const App: FC = () => {
  return (
    <IntlayerProvider>
      <MainContent />
    </IntlayerProvider>
  );
};

export default App;

Dynamiczna zmiana języka

Zmieniaj język w dowolnym miejscu aplikacji za pomocą hooka useLocale:

import { FC } from "react";
import { Locales } from "intlayer";
import { useLocale } from "react-intlayer";

export const LocaleSwitcher: FC = () => {
  const { locale, setLocale, availableLocales } = useLocale();

  return (
    <select
      value={locale}
      onChange={(e) => setLocale(e.target.value as Locales)}
    >
      {availableLocales.map((loc) => (
        <option key={loc} value={loc}>
          {loc}
        </option>
      ))}
    </select>
  );
};

Wielojęzyczne SEO (Sitemap i Robots.txt)

Intlayer zawiera narzędzia formatujące, takie jak generateSitemap i getMultilingualUrls, które generują pliki sitemap.xml i robots.txt dla statycznych wdrożeń w Vite:

import fs from "fs";
import path from "path";
import { fileURLToPath } from "url";
import { generateSitemap, getMultilingualUrls } from "intlayer";

const __dirname = path.dirname(fileURLToPath(import.meta.url));
const SITE_URL = (process.env.SITE_URL || "https://example.com").replace(
  /\/$/,
  ""
);

const pathList = [
  { path: "/", changefreq: "daily", priority: 1.0 },
  { path: "/about", changefreq: "monthly", priority: 0.7 },
];

const sitemapXml = generateSitemap(pathList, { siteUrl: SITE_URL });
fs.writeFileSync(path.join(__dirname, "public", "sitemap.xml"), sitemapXml);

const getAllMultilingualUrls = (urls) =>
  urls.flatMap((url) => Object.values(getMultilingualUrls(url)));

const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);

const robotsTxt = [
  "User-agent: *",
  "Allow: /",
  ...disallowedPaths.map((path) => `Disallow: ${path}`),
  "",
  `Sitemap: ${SITE_URL}/sitemap.xml`,
].join("\n");

fs.writeFileSync(path.join(__dirname, "public", "robots.txt"), robotsTxt);
console.log("Pliki SEO zostały pomyślnie wygenerowane.");

Dodaj skrypt prebuild w package.json, aby uruchamiał się przed vite build:

{
  "scripts": {
    "dev": "vite",
    "prebuild": "node generate-seo.mjs",
    "build": "vite build",
    "preview": "vite preview"
  }
}

Dowiedz się więcej: Gotowy na pełną konfigurację krok po kroku?

Ten przewodnik przedstawił koncepcyjne podejście do wdrożenia internacjonalizacji w istniejącej aplikacji Vite i React w 2026 roku bez konieczności kosztownego przepisywania kodu.

Jeśli chcesz skonfigurować wszystkie szczegóły (w tym pełne wsparcie TypeScript, dynamiczne słowniki i edytor wizualny), przejdź do naszej kompletnej dokumentacji:

👉 Kompletny przewodnik po tłumaczeniu Vite i React z Intlayer

Często zadawane pytania (FAQ)