Як постфактум зробити наявний додаток Vite і React багатомовним (i18n посібник 2026)

Додати інтернаціоналізацію (i18n) у проєкт Vite і React із самого початку відносно легко. Але що робити, коли у вас вже є готовий production-додаток однією мовою, і вам потрібно зробити його багатомовним постфактум?

З класичними бібліотеками на кшталт react-i18next або react-intl це перетворюється на виснажливий процес:

• Пошук захардкодженного тексту в сотнях файлів JSX і TSX.
• Створення вкладених JSON-словників і вигадування довільних ключів перекладу (components.header.title тощо).
• Заміна тексту інтерфейсу на громіздкі виклики хуків (t('...')).
• Перебудова маршрутизації на клієнті, керування станом та логіки перемикання мов.

У 2026 році вам не потрібно переписувати кодову базу. З Intlayer ви можете інтегрувати інтернаціоналізацію в наявний додаток Vite і React за кілька хвилин завдяки автоматичному вилученню тексту, перекладу за допомогою ШІ та безшовній інтеграції.

Шукаєте повний покроковий технічний посібник для Vite і React? Перегляньте нашу документацію: Переклад Vite і React з Intlayer.

Зміст

Дилема доопрацювання: Чому інтернаціоналізація наявного додатку є складною

Під час інтернаціоналізації наявного додатку Vite і React розробники стикаються з трьома суттєвими перешкодами:

1. Порушення кодової бази: Ручне вилучення рядків у JSON-словники потребує модифікації майже кожного файлу компонента. Це призводить до гігантських Git-diffs, ризиків конфліктів злиття та можливих регресій у верстці.
2. Накладні витрати на керування ключами: Вигадування ключів на кшталт dashboard.hero.ctaButton для кожного фрагмента тексту уповільнює розробку та додає когнітивне навантаження при кожній зміні тексту.
3. Монотонний переклад: Після вилучення рядків їх переклад 5, 10 чи 20 мовами вимагає нескінченного копіювання або замовлення дорогих зовнішніх сервісів локалізації.

Intlayer розв'язує ці проблеми на рівні архітектури за допомогою вилучення на базі компілятора, декларативних словників на рівні компонентів та нативної інтеграції з Vite.

Автоматичне вилучення контенту (без ручного пошуку тексту)

Замість того щоб вручну вилучати кожен рядок із JSX, Intlayer пропонує два прості варіанти:

Варіант A: Інструмент вилучення CLI (npx intlayer extract)

Ви можете запустити інструмент вилучення Intlayer безпосередньо у вашому проєкті:

npx intlayer extract

Ця команда сканує ваші компоненти React, знаходить видимий для користувача текст і автоматично створює файли декларацій контенту (.content.ts) поруч із кожним компонентом. Логіка залишається декларативною, зрозумілою та суворо типізованою.

Варіант B: Компілятор Intlayer (Вилучення під час збирання)

Увімкнувши компілятор Intlayer у конфігурації, ви можете продовжувати писати компоненти зі звичайним текстом вашою стандартною мовою. Під час збирання компілятор вилучає текст і автоматично вставляє локалізований контент:

// Пишіть звичайний React-код. Компілятор автоматично вилучить текст
export default function App() {
  return (
    <section>
      <h1>Ласкаво просимо на нашу платформу</h1>
      <p>Почніть відкривати сучасні можливості вже сьогодні.</p>
    </section>
  );
}

У фоновому режимі Intlayer будує словник і пов'язує компонент із локалізованим контентом, повністю виключаючи ручний рефакторинг.

У цьому випадку буде створено файл декларації src/App.content.ts із такою структурою:

import { Dictionary } from "intlayer";

const content = {
  key: "app",
  content: {
    laskavoProsymoNaNashuPlatformu: t({
      uk: "Ласкаво просимо на нашу платформу",
    }),
    pochnitVidkryvatySuchasniMozhlyvosti: t({
      uk: "Почніть відкривати сучасні можливості вже сьогодні.",
    }),
  },
};

export default content;

Переклад за допомогою ШІ та вашої улюбленої LLM

Після вилучення контенту його переклад десятками мов не повинен тривати днями. Intlayer має вбудовану CLI для перекладу через OpenAI, Anthropic, DeepSeek або Mistral за допомогою ваших власних ключів API:

npx intlayer fill

Налаштуйте мови та ШІ-провайдера у файлі intlayer.config.ts:

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

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.FRENCH,
      Locales.SPANISH,
      Locales.UKRAINIAN,
    ],
    defaultLocale: Locales.UKRAINIAN,
  },
  ai: {
    provider: "openai",
    model: "gpt-4o-mini",
    apiKey: process.env.OPENAI_API_KEY,
    applicationContext:
      "Сучасний SaaS-додаток і панель керування, створені на базі Vite та React",
  },
};

export default config;

Виконання npx intlayer fill наповнить ваші файли декларацій якісними перекладами для всіх налаштованих мов:

import { Dictionary } from "intlayer";

const content = {
  key: "app",
  content: {
    laskavoProsymoNaNashuPlatformu: t({
      uk: "Ласкаво просимо на нашу платформу",
      en: "Welcome to our platform",
      fr: "Bienvenue sur notre plateforme",
      es: "Bienvenido a nuestra plataforma",
    }),
    pochnitVidkryvatySuchasniMozhlyvosti: t({
      uk: "Почніть відкривати сучасні можливості вже сьогодні.",
      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;

Оскільки Intlayer передає applicationContext моделі, створені переклади зберігають технічний контекст, стилістику бренду та граматичні особливості значно краще за стандартні інструменти.

Щоб перед релізом перевірити, чи не залишилося неперекладених рядків:

npx intlayer test

Інтеграція з Vite та налаштування Provider

Інтеграція Intlayer у Vite потребує лише додавання плагіна у vite.config.ts та огортання кореневого компонента в IntlayerProvider:

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

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

Починаючи з Intlayer v9, компілятор включений безпосередньо в плагін intlayer() і активується автоматично після налаштування compiler.enabled у intlayer.config.ts.

Огорніть свій додаток компонентом IntlayerProvider у кореневому компоненті:

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

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

export default App;

Динамічне перемикання мови

Легко перемикайте мову в будь-якій частині додатку за допомогою хука 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>
  );
};

Багатомовне SEO (Sitemap та Robots.txt)

Intlayer містить форматери, такі як generateSitemap та getMultilingualUrls, які генерують оптимізовані для пошукових роботів файли sitemap.xml та robots.txt для статичних розгортань 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("SEO-файли успішно згенеровано.");

Додайте скрипт prebuild у ваш package.json, щоб запускати його перед vite build:

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

Докладніше: Готові до повного покрокового впровадження?

Цей посібник надав концептуальний огляд того, як додати інтернаціоналізацію до наявного додатку Vite і React у 2026 році без ускладнень у кодовій базі.

Якщо ви готові налаштувати кожен елемент детально, включаючи сувору типізацію TypeScript, динамічні словники та візуальний редактор, перейдіть до нашого повного посібника:

👉 Повний посібник з перекладу Vite і React з Intlayer

Часті запитання (FAQ)