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

Дивіться Шаблон додатка на GitHub.

Зміст

Чому важко інтернаціоналізувати існуючий додаток?

Якщо ви коли-небудь пробували додати підтримку кількох мов у додаток, створений лише для однієї, ви знаєте цей біль. Це не просто «важко», це нудно. Вам доводиться перебирати кожен окремий файл, вишукувати кожен рядок тексту і переносити їх в окремі файли словників.

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

Що таке Intlayer Compiler?

Intlayer Compiler був створений, щоб пропустити цю ручну рутинну роботу. Замість того, щоб ви вручну витягували рядки, компілятор робить це за вас. Сканує ваш код, знаходить текст і використовує ШІ для створення словників у фоновому режимі. Потім він змінює ваш код під час збірки, щоб вставити необхідні хуки i18n. По суті, ви продовжуєте писати свій додаток так, ніби він одномовний, а компілятор автоматично обробляє багатомовну трансформацію.

Документація компілятора: /uk/doc/compiler

Обмеження

Оскільки компілятор виконує аналіз і трансформацію кода (вставку хуків і генерацію словників) під час компіляції, це може сповільнити процес збірки вашого додатка.

Щоб пом'якшити цей вплив під час розробки, ви можете налаштувати компілятор для роботи в режимі 'build-only' або вимкнути його, коли він не потрібен.

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

Крок 1: Встановлення залежностей

Встановіть необхідні пакети за допомогою npm:

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

• intlayer Основний пакет, який надає інструменти інтернаціоналізації для керування конфігурацією, перекладу, декларації вмісту, транспіляції та команд CLI.

• react-intlayer Пакет, який інтегрує Intlayer з додатком React. Він надає провайдери контексту та хуки для інтернаціоналізації React.

• vite-intlayer Включає плагін Vite для інтеграції Intlayer з бандлером Vite, а також проміжне програмне забезпечення для визначення бажаної мови користувача, керування файлами cookie та обробки перенаправлення URL-адрес.

Крок 2: Налаштування вашого проєкту

Створіть файл конфігурації, щоб налаштувати мови вашого додатка:

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [Locales.ENGLISH, Locales.UKRAINIAN, Locales.FRENCH],    defaultLocale: Locales.ENGLISH,  },  compiler: {    /**     * Вказує, чи має бути увімкнено компілятор.     */    enabled: true,    /**     * Вихідний каталог для оптимізованих словників.     */    output: ({ locale, key }) => `compiler/${locale}/${key}.json`,    /**     * Вставте лише вміст у згенерований файл, без ключа.     */    noMetadata: false,    /**     * Префікс ключа словника     */    dictionaryKeyPrefix: "", // Remove base prefix    /**     * Вказує, чи мають компоненти зберігатися після трансформації.     * Таким чином компілятор можна запустити лише один раз для трансформації додатка, а потім видалити.     */    saveComponents: false,  },  ai: {    provider: "openai",    model: "gpt-5-mini",    apiKey: process.env.OPEN_AI_API_KEY,    applicationContext: "Цей додаток, це карта", // Примітка: ви можете налаштувати цей опис додатка  },};export default config;

Примітка: Переконайтеся, що ваш OPEN_AI_API_KEY встановлений у змінних середовища.

Через цей файл конфігурації ви можете налаштувати локалізовані URL-адреси, перенаправлення проміжного програмного забезпечення, назви файлів cookie, розташування та розширення ваших декларацій вмісту, вимкнути логи Intlayer у консолі тощо. Повний список доступних параметрів дивіться в документації з конфігурації.

Крок 3: Інтеграція Intlayer у вашу конфігурацію Vite

Додайте плагін intlayer у вашу конфігурацію.

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()],});

Плагін Vite intlayer() використовується для інтеграції Intlayer з Vite. Він забезпечує збірку файлів декларації вмісту та відстежує їх у режимі розробки. Він визначає змінні середовища Intlayer у додатку Vite. Крім того, він надає аліаси для оптимізації продуктивності.

Плагін Vite intlayerCompiler() використовується для витягування вмісту з компонентів і запису файлів .content.

Крок 4: Компіляція вашого коду

Просто пишіть свої компоненти з жорстко закодованими рядками вашою мовою за замовчуванням. Компілятор зробить усе інше.

Приклад того, як може виглядати ваша сторінка:

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",     },     uk: {       viteLogo: "Логотип Vite",       reactLogo: "Логотип React",       title: "Vite + React",       countButton: "рахунок дорівнює",       editMessage: "Редагувати",       hmrMessage: "і зберегти для перевірки HMR",       readTheDocs: "Натисніть на логотипи Vite та React, щоб дізнатися більше",     },   } }}

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 використовується для надання локалі вкладеним компонентам.

(Опціонально) Крок 6: Зміна мови вашого вмісту

Щоб змінити мови вашого вмісту, ви можете використовувати функцію setLocale, яку надає хук useLocale. Ця функція дозволяє встановити локаль додатка та відповідним чином оновити вміст.

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)}>      Змінити мову на англійську    </button>  );};

Щоб дізнатися більше про хук useLocale, зверніться до документації.

(Опціонально) Крок 7: Заповнити відсутні переклади

Intlayer надає інструмент CLI, щоб допомогти вам заповнити відсутні переклади. Ви можете використовувати команду intlayer для тестування та заповнення відсутніх перекладів у вашому коді.

npx intlayer test         # Перевірити, чи є відсутні переклади

npx intlayer fill         # Заповнити відсутні переклади

Для отримання більш детальної інформації зверніться до документації CLI

(Опційно) Sitemap і robots.txt (генерація під час збірки)

Intlayer надає generateSitemap і getMultilingualUrls - утиліти для формування багатомовних sitemap.xml і robots.txt для краулерів та автоматичного запису в public/. Зазвичай запускають невеликий Node-скрипт перед Vite (наприклад, npm-хуки predev / prebuild).

Sitemap

Генератор sitemap враховує локалі й додає метадані для краулерів.

Підтримується простір імен xhtml:link (hreflang). Замість плоского списку URL Intlayer пов’язує всі мовні версії сторінки в обидва боки (наприклад /about, /fr/about або /about?lang=fr залежно від режиму маршрутизації).

Robots.txt

Використовуйте getMultilingualUrls, щоб правила Disallow покривали всі локалізовані варіанти шляхів.

1. Файл generate-seo.mjs у корені проєкту

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.");

Пакет intlayer має бути встановлений. У продакшені задайте SITE_URL у середовищі (наприклад у CI).

Для Node ESM краще generate-seo.mjs. Для generate-seo.js додайте "type": "module" у package.json або ввімкніть ESM інакше.

2. Запуск скрипта перед Vite

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

Підлаштуйте команди для pnpm або yarn. Можна викликати скрипт із CI.

Конфігурація Git

Рекомендується ігнорувати файли, створені Intlayer. Це дозволяє уникнути їхнього коміту у ваш Git-репозиторій.

Для цього ви можете додати наступні інструкції до вашого файлу .gitignore:

# Ігнорувати файли, створені Intlayer.intlayer

Розширення VS Code

Щоб покращити ваш досвід розробки з Intlayer, ви можете встановити офіційне розширення Intlayer для VS Code.

Встановити з VS Code Marketplace

Це розширення надає:

• Автодоповнення для ключів перекладу.
• Виявлення помилок у реальному часі для відсутніх перекладів.
• Вбудований попередній перегляд перекладеного вмісту.
• Швидкі дії для легкого створення та оновлення перекладів.

Для отримання додаткової інформації про те, як користуватися розширенням, зверніться до документації розширення Intlayer для VS Code.

Йти далі

Щоб піти далі, ви можете впровадити візуальний редактор або винести свій вміст назовні за допомогою CMS.