Creation:2026-03-23Last update:2026-05-31

    Перекладіть свій веб-сайт Vite та Vanilla JS за допомогою Intlayer | Інтернаціоналізація (i18n)

    ide.intlayer.org

    Зміст

    Чому варто обрати Intlayer, а не альтернативи?

    Порівняно з основними рішеннями, такими як i18next або i18n.js, Intlayer — це рішення, яке поставляється з інтегрованою оптимізацією, як-от:

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

    Замість того, щоб завантажувати великі файли JSON на свої сторінки, завантажуйте лише необхідний вміст. Intlayer допомагає зменшити розмір бандлу і сторінок до 50%.

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

    Спільне розміщення вмісту зменшує контекст, необхідний для великих мовних моделей (LLM). Intlayer також постачається з набором інструментів, наприклад CLI для перевірки відсутніх перекладів,LSP, MCP і навички агента, щоб зробити роботу розробника (DX) ще зручнішою для агентів ШІ.

    Використовуйте автоматизацію для перекладу в конвеєрі CI/CD за допомогою LLM за вашим вибором за рахунок вашого постачальника штучного інтелекту. Intlayer також пропонує компілятор для автоматизації екстракція вмісту, а також веб-платформу, щоб допомогти перекладати у фоновому режимі.

    Підключення великих файлів JSON до компонентів може призвести до проблем з продуктивністю та реакцією. Intlayer оптимізує завантаження вмісту під час збірки (build time).

    Більше ніж просто рішення i18n, Intlayer пропонує власний візуальний редактор і повний CMS, щоб допомогти вам керувати своїм багатомовним вмістом у реальному часі, спрощуючи співпрацю з перекладачами, копірайтерами та іншими членами команди. Контент можна зберігати локально та/або віддалено.

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

    1. Встановлення залежностей

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

      bash
      npm install intlayer vanilla-intlayernpm install vite-intlayer --save-devnpx intlayer init

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

      • vanilla-intlayer Пакет, який інтегрує Intlayer із чистими додатками JavaScript / TypeScript. Він надає pub/sub синглтон (IntlayerClient) та помічники на основі колбеків (useIntlayer, useLocale тощо), щоб будь-яка частина вашого додатка могла реагувати на зміни локалі незалежно від фреймворку інтерфейсу.

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

    2. Конфігурація вашого проекту

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

      intlayer.config.ts
      import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.FRENCH,
      Locales.SPANISH,
      // Ваші інші локалі
    ],
    defaultLocale: Locales.ENGLISH,
  },
};

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

    3. Інтегруйте Intlayer у вашу конфігурацію Vite

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

      vite.config.ts
      import { defineConfig } from "vite";
import { intlayer } from "vite-intlayer";

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [intlayer()],
});
      Плагін Vite intlayer() використовується для інтеграції Intlayer із Vite. Він забезпечує побудову файлів декларації вмісту та відстежує їх у режимі розробки. Він визначає змінні середовища Intlayer у додатку Vite. Крім того, він надає псевдоніми (aliases) для оптимізації продуктивності.

    4. Запустіть Intlayer у вашій точці входу

      Викличте installIntlayer() перед візуалізацією будь-якого вмісту, щоб глобальний синглтон локалі був готовий.

      src/main.ts
      import { installIntlayer } from "vanilla-intlayer";// Має бути викликано перед візуалізацією будь-якого вмісту i18n.installIntlayer();// Імпортуйте та запустіть модулі програми.import "./app.js";

      Якщо ви також використовуєте декларації вмісту md() (Markdown), встановіть також рендерер markdown:

      src/main.ts
      import { installIntlayer, installIntlayerMarkdown } from "vanilla-intlayer";installIntlayer();installIntlayerMarkdown();import "./app.js";

    5. Декларуйте ваш контент

      Створюйте та керуйте деклараціями вмісту для зберігання перекладів:

      src/app.content.ts
      import { insert, t, type Dictionary } from "intlayer";

const appContent = {
  key: "app",
  content: {
    title: "Vite + Vanilla",

    viteLogoLabel: t({
      en: "Vite Logo",
      fr: "Logo Vite",
      es: "Logo Vite",
    }),

    count: insert(
      t({
        en: "count is {{count}}",
        fr: "le compte est {{count}}",
        es: "el recuento es {{count}}",
      })
    ),

    readTheDocs: t({
      en: "Click on the Vite logo to learn more",
      fr: "Cliquez sur le logo Vite pour en savoir plus",
      es: "Натисніть на логотип Vite, щоб дізнатися більше",
    }),
  },
} satisfies Dictionary;

export default appContent;

      Ваші декларації вмісту можна визначити будь-де у вашому додатку, якщо вони включені до каталогу contentDir (за замовчуванням ./src) і відповідають розширенню файлу декларації вмісту (за замовчуванням .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).

      Докладніше див. у документації з декларації вмісту.

    6. Використовуйте Intlayer у вашому JavaScript

      vanilla-intlayer відображає API поверхні react-intlayer: useIntlayer(key, locale?) повертає перекладений вміст безпосередньо. Приєднайте .onChange() до результату, щоб підписатися на зміни локалі - явний еквівалент перерендерингу в React.

      src/main.ts
      import { installIntlayer, useIntlayer } from "vanilla-intlayer";installIntlayer();// Отримайте початковий контент для поточної локалі.// Приєднайте .onChange(), щоб отримувати сповіщення при кожній зміні локалі.const content = useIntlayer("app").onChange((newContent) => {  // Перерендерить або оновіть лише зачеплені вузли DOM  document.querySelector<HTMLHeadingElement>("h1")!.textContent = String(    newContent.title  );  document.querySelector<HTMLParagraphElement>(".read-the-docs")!.textContent =    String(newContent.readTheDocs);});// Початковий рендерингdocument.querySelector<HTMLHeadingElement>("h1")!.textContent = String(  content.title);document.querySelector<HTMLParagraphElement>(".read-the-docs")!.textContent =  String(content.readTheDocs);

      Отримуйте доступ до кінцевих значень як до рядків, загорнувши їх у String(), що викликає метод toString() вузла та повертає перекладений текст.

      Якщо вам потрібне значення для нативного атрибута HTML (наприклад, alt, aria-label), використовуйте безпосередньо .value:

      typescript
      img.alt = content.viteLogoLabel.value;

    7. Змініть мову вашого вмісту

      Необов'язково

      Щоб змінити мову вмісту, використовуйте функцію setLocale, надану useLocale.

      src/locale-switcher.ts
      import { getLocaleName } from "intlayer";import { useLocale } from "vanilla-intlayer";export function setupLocaleSwitcher(container: HTMLElement): () => void {  const { locale, availableLocales, setLocale, subscribe } = useLocale();  const select = document.createElement("select");  select.setAttribute("aria-label", "Language");  const render = (currentLocale: string) => {    select.innerHTML = availableLocales      .map(        (loc) =>          `<option value="${loc}"${loc === currentLocale ? " selected" : ""}>            ${getLocaleName(loc)}          </option>`      )      .join("");  };  render(locale);  container.appendChild(select);  select.addEventListener("change", () => setLocale(select.value as any));  // Тримайте випадаючий список синхронізованим, коли локаль змінюється деінде  return subscribe((newLocale) => render(newLocale));}

    8. Рендеринг вмісту Markdown та HTML

      Необов'язково

      Intlayer підтримує декларації вмісту md() та html(). У чистому JS скомпільований вихідний код вставляється як необроблений HTML через innerHTML.

      Скомпілюйте та вставте HTML:

      src/main.ts
      import {  compileMarkdown,  installIntlayerMarkdown,  useIntlayer,} from "vanilla-intlayer";installIntlayerMarkdown();const content = useIntlayer("app").onChange((newContent) => {  const el = document.querySelector<HTMLDivElement>(".edit-note")!;  el.innerHTML = compileMarkdown(String(newContent.editNote));});document.querySelector<HTMLDivElement>(".edit-note")!.innerHTML =  compileMarkdown(String(content.editNote));
      TIP
      String(content.editNote) викликає toString() на IntlayerNode, що повертає необроблений рядок Markdown. Передайте його в compileMarkdown, щоб отримати рядок HTML, а потім встановіть через innerHTML.
      WARNING

      Використовуйте innerHTML лише з довіреним вмістом. Якщо markdown надходить від користувача, спочатку очистіть його (наприклад, за допомогою DOMPurify). Ви можете встановити рендерер очищення динамічно:

      typescript
      import { installIntlayerMarkdownDynamic } from "vanilla-intlayer";await installIntlayerMarkdownDynamic(async () => {  const DOMPurify = await import("dompurify");  return (markdown) => DOMPurify.sanitize(compileMarkdown(markdown));});

    9. Додайте локалізовану маршрутизацію (Localized Routing) до свого додатка

      Необов'язково

      Щоб створити унікальні маршрути для кожної мови (корисно для SEO), ви можете використовувати intlayerProxy у вашій конфігурації Vite для визначення локалі на стороні сервера.

      Спочатку додайте intlayerProxy до вашої конфігурації Vite:

      Зверніть увагу, що для використання intlayerProxy у продуктовому середовищі вам потрібно перемістити vite-intlayer із devDependencies до dependencies.
      vite.config.ts
      import { defineConfig } from "vite";
import { intlayer, intlayerProxy } from "vite-intlayer";

export default defineConfig({
  plugins: [
    intlayerProxy(), // має бути розміщено першим
    intlayer(),
  ],
});

    10. Зміна URL при зміні локалі

      Необов'язково

      Щоб оновити URL браузера при зміні локалі, викличте useRewriteURL() після встановлення Intlayer:

      src/main.ts
      import { installIntlayer, useRewriteURL } from "vanilla-intlayer";installIntlayer();// Переписує URL негайно та при кожній наступній зміні локалі.// Повертає функцію скасування підписки для очищення.const stopRewriteURL = useRewriteURL();

    11. Перемикання атрибутів мови та напрямку HTML

      Необов'язково

      Оновлюйте атрибути lang та dir тегу <html> відповідно до поточної локалі для підтримки доступності та SEO.

      src/main.ts
      import { getHTMLTextDir } from "intlayer";import { installIntlayer, useLocale } from "vanilla-intlayer";installIntlayer();useLocale({  onLocaleChange: (locale) => {    document.documentElement.lang = locale;    document.documentElement.dir = getHTMLTextDir(locale);  },});

    12. Ліниве завантаження словників за локалями

      Необов'язково

      Для великих додатків ви можете розділити словник кожної локалі на власний фрагмент (chunk). Використовуйте useDictionaryDynamic разом із динамічним import() від Vite:

      src/app.ts
      import { installIntlayer, useDictionaryDynamic } from "vanilla-intlayer";installIntlayer();const unsubscribe = useDictionaryDynamic(  {    en: () => import("../.intlayer/dictionaries/en/app.mjs"),    fr: () => import("../.intlayer/dictionaries/fr/app.mjs"),    es: () => import("../.intlayer/dictionaries/es/app.mjs"),  },  "app").onChange((content) => {  document.querySelector("h1")!.textContent = String(content.title);});
      Пакет кожної локалі завантажується лише тоді, коли ця локаль стає активною, а результат кешується - наступні перемикання на ту саму локаль відбуваються миттєво.

    13. Отримайте вміст ваших компонентів

      Необов'язково

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

      Щоб полегшити цей процес, Intlayer пропонує компілятор / екстрактор для перетворення ваших компонентів та екстракція вмісту.

      Для налаштування ви можете додати розділ compiler у ваш файл intlayer.config.ts:

      intlayer.config.ts
      import { type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  // ... Решта вашої конфігурації  compiler: {    /**     * Вказує, чи має бути включений компілятор.     */    enabled: true,    /**     * Визначає шлях вихідних файлів     */    output: ({ fileName, extension }) => `./${fileName}${extension}`,    /**     * Вказує, чи потрібно зберігати компоненти після перетворення.     * Таким чином компілятор можна запустити лише один раз для перетворення програми, а потім видалити.     */    saveComponents: false,    /**     * Префікс ключа словника     */    dictionaryKeyPrefix: "",  },};export default config;

      Запустіть екстрактор, щоб перетворити ваші компоненти та витягти вміст

      bash
      npx intlayer extract

    (Опційно) 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 у корені проєкту

    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

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

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

    Налаштування TypeScript

    Переконайтеся, що ваша конфігурація TypeScript включає автоматично згенеровані типи.

    tsconfig.json
    {  "compilerOptions": {    // ...  },  "include": ["src", ".intlayer/**/*.ts"],}

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

    Ми рекомендуємо ігнорувати файли, згенеровані Intlayer. Це дозволить вам уникнути їх фіксації (commit) у вашому репозиторії Git.

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

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

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

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

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

    Це розширення забезпечує:

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

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

    Йдіть далі

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

    Vite та Preact
    Vite та Lit