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

Zobacz Szablon aplikacji na GitHubie.

Spis treści

Dlaczego internacjonalizacja istniejącej aplikacji jest trudna?

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

Następnie przychodzi ryzykowna część: zastąpienie całego tego tekstu hookami w kodzie bez psuciu układu lub logiki. To rodzaj pracy, który wstrzymuje rozwój nowych funkcji na tygodnie i wydaje się niekończącym się refaktoryzacją.

Co to jest Intlayer Compiler?

Intlayer Compiler został stworzony, aby pominąć tę ręczną, żmudną pracę. Zamiast ręcznego wyodrębniania ciągów znaków, kompilator robi to za Ciebie. Skanuje Twój kod, znajduje tekst i używa AI do generowania słowników w tle. Następnie modyfikuje Twój kod podczas budowania, aby wstrzyknąć niezbędne hooki i18n. Zasadniczo piszesz aplikację tak, jakby była jednojęzyczna, a kompilator automatycznie zajmuje się wielojęzyczną transformacją.

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 to spowolnić proces budowania Twojej aplikacji.

Aby złagodzić ten wpływ podczas programowania, możesz skonfigurować kompilator tak, aby działał w trybie 'build-only' lub wyłączyć go, gdy nie jest potrzebny.

Przewodnik krok po kroku po konfiguracji Intlayer w aplikacji Vite i React

Krok 1: Instalacja zależności

Zainstaluj niezbędne pakiety za pomocą npm:

npm install intlayer react-intlayernpm install vite-intlayer --save-devnpx intlayer init

• intlayer Podstawowy pakiet dostarczający narzędzia do internacjonalizacji do zarządzania konfiguracją, tłumaczeń, deklaracji treści, transpilacji i poleceń CLI.

• react-intlayer Pakiet integrujący Intlayer z aplikacją React. Dostarcza dostawców kontekstu i hooki dla internacjonalizacji Reacta.

• vite-intlayer Zawiera wtyczkę Vite do integracji Intlayer z bundlerem Vite, a także middleware do wykrywania preferowanego języka użytkownika, zarządzania plikami cookie i obsługi przekierowań URL.

Krok 2: Skonfiguruj swój projekt

Utwórz plik konfiguracyjny, aby ustawić języki Twojej aplikacji:

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [Locales.ENGLISH, Locales.POLISH, Locales.FRENCH],    defaultLocale: Locales.ENGLISH,  },  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 aplikacja mapowa", // Uwaga: możesz spersonalizować ten opis aplikacji  },};export default config;

Uwaga: Upewnij się, że masz ustawiony klucz OPEN_AI_API_KEY w zmiennych środowiskowych.

Poprzez ten plik konfiguracyjny możesz skonfigurować zlokalizowane adresy URL, przekierowania middleware, nazwy plików cookie, lokalizację i rozszerzenia deklaracji treści, wyłączyć logi Intlayer w konsoli i wiele więcej. Pełną listę dostępnych parametrów znajdziesz w dokumentacji konfiguracji.

Krok 3: Zintegruj Intlayer w konfiguracji Vite

Dodaj wtyczkę intlayer do swojej konfiguracji.

import { defineConfig } from "vite";import react from "@vitejs/plugin-react-swc";import { intlayer, intlayerCompiler } from "vite-intlayer";// https://vitejs.dev/config/export default defineConfig({  plugins: [react(), intlayer(), intlayerCompiler()],});

Wtyczka Vite intlayer() służy do integracji Intlayer z Vite. Zapewnia budowanie plików deklaracji treści i monitoruje je w trybie deweloperskim. Definiuje zmienne środowiskowe Intlayer w aplikacji Vite. Dodatkowo zapewnia aliasy w celu optymalizacji wydajności.

Wtyczka Vite intlayerCompiler() służy do wyodrębniania treści z komponentów i zapisywania plików .content.

Krok 4: Skompiluj swój kod

Po prostu pisz swoje 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 { useState, type FC } from "react";import reactLogo from "./assets/react.svg";import viteLogo from "/vite.svg";import "./App.css";import { IntlayerProvider } from "react-intlayer";const AppContent: FC = () => { const [count, setCount] = useState(0); return (   <>     <div>       <a href="https://vitejs.dev" target="_blank">         <img src={viteLogo} className="logo" alt="Vite logo" />       </a>       <a href="https://react.dev" target="_blank">         <img src={reactLogo} className="logo react" alt="React logo" />       </a>     </div>     <h1>Vite + React</h1>     <div className="card">       <button onClick={() => setCount((count) => count + 1)}>         count is {count}       </button>       <p>         Edit <code>src/App.tsx</code> and save to test HMR       </p>     </div>     <p className="read-the-docs">       Click on the Vite and React logos to learn more     </p>   </> );};const App: FC = () => ( <IntlayerProvider>   <AppContent /> </IntlayerProvider>);export default App;

{ key: "app-content", content: {   nodeType: "translation",   translation: {     en: {       viteLogo: "Vite logo",       reactLogo: "React logo",       title: "Vite + React",       countButton: "count is",       editMessage: "Edit",       hmrMessage: "and save to test HMR",       readTheDocs: "Click on the Vite and React logos to learn more",     },     pl: {       viteLogo: "Logo Vite",       reactLogo: "Logo React",       title: "Vite + React",       countButton: "licznik wynosi",       editMessage: "Edytuj",       hmrMessage: "i zapisz, aby przetestować HMR",       readTheDocs: "Kliknij logo Vite i React, aby dowiedzieć się więcej",     },   } }}

import { useState, type FC } from "react";import reactLogo from "./assets/react.svg";import viteLogo from "/vite.svg";import "./App.css";import { IntlayerProvider, useIntlayer } from "react-intlayer";const AppContent: FC = () => { const [count, setCount] = useState(0); const content = useIntlayer("app-content"); return (   <>     <div>       <a href="https://vitejs.dev" target="_blank">         <img src={viteLogo} className="logo" alt={content.viteLogo.value} />       </a>       <a href="https://react.dev" target="_blank">         <img           src={reactLogo}           className="logo react"           alt={content.reactLogo.value}         />       </a>     </div>     <h1>{content.title}</h1>     <div className="card">       <button onClick={() => setCount((count) => count + 1)}>         {content.countButton} {count}       </button>       <p>         {content.editMessage} <code>src/App.tsx</code> {content.hmrMessage}       </p>     </div>     <p className="read-the-docs">{content.readTheDocs}</p>   </> );};const App: FC = () => ( <IntlayerProvider>   <AppContent /> </IntlayerProvider>);export default App;

• IntlayerProvider służy do dostarczania ustawień regionalnych do zagnieżdżonych komponentów.

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

Aby zmienić język treści, możesz użyć funkcji setLocale dostarczonej przez hook useLocale. Funkcja ta pozwala ustawić język aplikacji i odpowiednio zaktualizować treść.

import type { FC } from "react";import { Locales } from "intlayer";import { useLocale } from "react-intlayer";const LocaleSwitcher: FC = () => {  const { setLocale } = useLocale();  return (    <button onClick={() => setLocale(Locales.English)}>      Zmień język na angielski    </button>  );};

Aby dowiedzieć się więcej o hooku useLocale, zapoznaj się z dokumentacją.

(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 w swoim kodzie.

npx intlayer test         # Sprawdź, czy brakuje tłumaczeń

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

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

(Opcjonalnie) Sitemap i robots.txt (generacja przy buildzie)

Intlayer udostępnia generateSitemap i getMultilingualUrls - narzędzia do formatowania wielojęzycznych plików sitemap.xml i robots.txt dla crawlerów i automatycznego zapisu do public/. Zwykle uruchamia się mały skrypt Node przed Vite (np. hooki npm predev / prebuild).

Sitemap

Generator sitemap uwzględnia locale i dodaje metadane dla crawlerów.

Sitemap obsługuje przestrzeń nazw xhtml:link (hreflang). Zamiast płaskiej listy URL Intlayer tworzy dwukierunkowe powiązania wszystkich wersji językowych strony (np. /about, /fr/about lub /about?lang=fr w zależności od routingu).

Robots.txt

Użyj getMultilingualUrls, by reguły Disallow obejmowały wszystkie zlokalizowane warianty ścieżek.

1. Plik generate-seo.mjs w katalogu głównym

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 || "http://localhost:5173").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("SEO files generated successfully.");

Pakiet intlayer musi być zainstalowany. W produkcji ustaw SITE_URL w środowisku (np. w CI).

Preferuj generate-seo.mjs dla ESM w Node. Przy generate-seo.js ustaw "type": "module" w package.json lub włącz ESM inaczej.

2. Uruchom skrypt przed Vite

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

Dostosuj polecenia dla pnpm lub yarn. Możesz też wywołać skrypt z CI.

Konfiguracja Git

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

Aby to zrobić, możesz dodać następujące instrukcje do pliku .gitignore:

# Ignoruj pliki wygenerowane przez Intlayer.intlayer

Rozszerzenie VS Code

Aby usprawnić proces programowania 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 w przypadku brakujących tłumaczeń.
• Podgląd na żywo 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.

Idź dalej

Aby pójść dalej, możesz zaimplementować edytor wizualny lub wyeksportować treść za pomocą CMS.