Создание:2026-03-31Последнее обновление:2026-05-31

    Переведите ваш сайт на Vanilla JS с помощью Intlayer | Интернационализация (i18n)

    Содержание

    Почему Intlayer лучше альтернатив?

    По сравнению с основными решениями, такими как i18next или i18n.js, Intlayer — это решение, которое включает в себя встроенные оптимизации, такие как:

    Intlayer оптимизирован для идеальной работы с Vanilla JavaScript, предлагая независимое от платформы управление контентом, поддержку TypeScript и все функции, необходимые для масштабирования интернационализации (i18n).

    Вместо загрузки огромных файлов JSON на свои страницы загружайте только необходимый контент. Intlayer помогает уменьшить размер бандла и страниц до 50 %.

    Определение области содержимого вашего приложения облегчает обслуживание крупномасштабных приложений. Вы можете дублировать или удалить отдельную папку функций, не утруждав себя мысленным бременем проверки всей кодовой базы контента. Кроме того, Intlayer полностью типизирован, что обеспечивает точность вашего контента.

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

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

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

    Intlayer — это больше, чем просто решение i18n. Он предоставляет автономный визуальный редактор и полный CMS, чтобы помочь вам управлять многоязычным контентом в реальном времени, упрощая сотрудничество с переводчиками, копирайтерами и другими членами команды. Контент может храниться локально и/или удаленно.

    Пошаговое руководство по настройке Intlayer в приложении на Vanilla JS

    1. Установка зависимостей

      Установите необходимые пакеты с помощью npm:

      # Создание автономной сборки intlayer и vanilla-intlayer
# Этот файл будет импортирован в ваш HTML-файл
npx intlayer standalone --packages intlayer vanilla-intlayer --outfile intlayer.js

# Инициализация intlayer с файлом конфигурации
npx intlayer init --no-gitignore

# Сборка словарей
npx intlayer build
      # Создание автономной сборки intlayer и vanilla-intlayer
# Этот файл будет импортирован в ваш HTML-файл
pnpm intlayer standalone --packages intlayer vanilla-intlayer --outfile intlayer.js

# Инициализация intlayer с файлом конфигурации
pnpm intlayer init --no-gitignore

# Сборка словарей
pnpm intlayer build
      # Создание автономной сборки intlayer и vanilla-intlayer
# Этот файл будет импортирован в ваш HTML-файл
yarn intlayer standalone --packages intlayer vanilla-intlayer --outfile intlayer.js

# Инициализация файла конфигурации intlayer, TypeScript (если настроен), переменных окружения
yarn intlayer init --no-gitignore

# Сборка словарей
yarn intlayer build
      # Создание автономной сборки intlayer и vanilla-intlayer
# Этот файл будет импортирован в ваш HTML-файл
bun x intlayer standalone --packages intlayer vanilla-intlayer --outfile intlayer.js

# Инициализация intlayer с файлом конфигурации
bun x intlayer init --no-gitignore

# Сборка словарей
bun x intlayer build

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

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

      Экспорт сборки (bunding) CLI intlayer standalone создает оптимизированную сборку за счет исключения неиспользуемого кода (tree-shaking) неиспользуемых пакетов, локалей и второстепенной логики (такой как редиректы или префиксы), специфичной для вашей конфигурации.

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

      Создайте файл конфигурации для настройки языков вашего приложения:

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

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.FRENCH,
      Locales.SPANISH,
      // Ваши другие языки
    ],
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;
      Через этот файл конфигурации вы можете настроить локализованные URL, перенаправление через middleware, имена куки, расположение и расширение ваших объявлений контента, отключить логи Intlayer в консоли и многое другое. Полный список доступных параметров см. в документации по конфигурации.

    3. Импорт сборки в ваш HTML

      После того как вы сгенерировали сборку intlayer.js, вы можете импортировать ее в свой HTML-файл:

      <!DOCTYPE html>
<html lang="ru">
  <head>
    <meta charset="UTF-8" />

    <!-- Импорт сборки -->
    <script src="./intlayer.js" defer></script>
    <!-- Импорт вашего основного скрипта -->
    <script src="./src/main.js" defer></script>
  </head>
  <body>
    <h1 id="title"></h1>
    <p class="read-the-docs"></p>
  </body>
</html>

      Сборка предоставляет Intlayer и VanillaIntlayer в качестве глобальных объектов на window.

    4. Инициализация Intlayer в точке входа

      В вашем src/main.js вызовите installIntlayer() до того, как какой-либо контент будет отрисован, чтобы глобальный синглтон языка был готов.

      const { installIntlayer } = window.VanillaIntlayer;

// Должно быть вызвано перед отрисовкой любого i18n-контента.
installIntlayer();

      Если вы также хотите использовать рендерер markdown, вызовите installIntlayerMarkdown():

      const { installIntlayer, installIntlayerMarkdown } = window.VanillaIntlayer;

installIntlayer();
installIntlayerMarkdown();

    5. Объявление вашего контента

      Создавайте и управляйте объявлениями контента для хранения переводов:

      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: "Haga clic en el logotipo de Vite para obtener más información",
    }),
  },
} satisfies Dictionary;

export default appContent;
      {
  "$schema": "https://intlayer.org/schema.json",
  "key": "app",
  "content": {
    "title": "Vite + Vanilla",
    "viteLogoLabel": {
      "nodeType": "translation",
      "translation": {
        "en": "Vite Logo",
        "fr": "Logo Vite",
        "es": "Logo Vite"
      }
    },
    "count": {
      "nodeType": "insertion",
      "insertion": {
        "nodeType": "translation",
        "translation": {
          "en": "count is {{count}}",
          "fr": "le compte est {{count}}",
          "es": "el recuento es {{count}}"
        }
      }
    },
    "readTheDocs": {
      "nodeType": "translation",
      "translation": {
        "en": "Click on the Vite logo to learn more",
        "fr": "Cliquez sur le logo Vite pour en savoir plus",
        "es": "Haga clic en el logotipo de Vite para obtener más información"
      }
    }
  }
}

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

      Для получения более подробной информации см. документацию по объявлению контента.

    6. Использование Intlayer в вашем JavaScript

      Объект window.VanillaIntlayer предоставляет вспомогательные функции API: useIntlayer(key, locale?) возвращает переведенный контент для заданного ключа.

      const { installIntlayer, useIntlayer } = window.VanillaIntlayer;

installIntlayer();

// Получение начального контента для текущего языка.
// Соедините с .onChange(), чтобы получать уведомления при смене языка.
const content = useIntlayer("app").onChange((newContent) => {
  // Перерисовываем или обновляем только затронутые DOM-узлы
  document.querySelector("h1").textContent = String(newContent.title);
  document.querySelector(".read-the-docs").textContent = String(
    newContent.readTheDocs
  );
});

// Начальная отрисовка
document.querySelector("h1").textContent = String(content.title);
document.querySelector(".read-the-docs").textContent = String(
  content.readTheDocs
);

      Получайте дочерние значения в виде строк, оборачивая их в String(), что вызывает метод toString() узла и возвращает переведенный текст.

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

      img.alt = content.viteLogoLabel.value;

    7. Изменение языка вашего контента

      Необязательно

      Чтобы изменить язык вашего контента, используйте функцию setLocale, предоставляемую useLocale.

      const { getLocaleName } = window.Intlayer;
const { useLocale } = window.VanillaIntlayer;

export function setupLocaleSwitcher(container) {
  const { locale, availableLocales, setLocale, subscribe } = useLocale();

  const select = document.createElement("select");
  select.setAttribute("aria-label", "Язык");

  const render = (currentLocale) => {
    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));

  // Поддерживаем список в актуальном состоянии, если язык был изменен в другом месте
  return subscribe((newLocale) => render(newLocale));
}

    8. Переключение атрибутов языка и направления текста HTML

      Необязательно

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

      const { getHTMLTextDir } = window.Intlayer;
const { installIntlayer, useLocale } = window.VanillaIntlayer;

installIntlayer();

useLocale({
  onLocaleChange: (locale) => {
    document.documentElement.lang = locale;
    document.documentElement.dir = getHTMLTextDir(locale);
  },
});

    9. Ленивая загрузка словарей по языкам

      Необязательно

      Если вы хотите загружать словари лениво для каждого языка, вы можете использовать useDictionaryDynamic. Это полезно, если вы не хотите включать все переводы в начальный файл intlayer.js.

      const { installIntlayer, useDictionaryDynamic } = window.VanillaIntlayer;

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);
});

      Примечание: useDictionaryDynamic требует, чтобы словари были доступны в виде отдельных файлов ESM. Этот подход обычно используется, если у вас есть веб-сервер, раздающий словари.

    Настройка TypeScript

    Убедитесь, что ваша конфигурация TypeScript включает автоматически генерируемые типы.

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

    Расширение для VS Code

    Чтобы улучшить процесс разработки с Intlayer, вы можете установить официальное расширение Intlayer для VS Code.

    Установить из VS Code Marketplace

    Это расширение предоставляет:

    • Автодополнение для ключей переводов.
    • Обнаружение ошибок в реальном времени для недостающих переводов.
    • Встроенный предпросмотр переведенного контента.
    • Быстрые действия для легкого создания и обновления переводов.

    Для получения более подробной информации об использовании расширения см. документацию расширения Intlayer для VS Code.

    Идите дальше

    Чтобы пойти дальше, вы можете внедрить визуальный редактор или вынести ваш контент во внешнюю среду с помощью CMS.

    Почему Intlayer?