Автор:
    Aymeric PINEAU
    Создание:2026-03-31Последнее обновление:2026-08-30

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

    ide.intlayer.org
    intlayer-vanilla-template.vercel.app

    Содержание

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

      Архитектура

      В этой архитектуре ядро intlayer предоставляет API JavaScript для объявления и использования словарей в стандартных средах JavaScript или TypeScript без интерфейсного фреймворка.

      bash
      .
├── src
│   ├── app.content.mjs
│   └── main.js
├── index.html
├── intlayer.config.mjs
└── package.json

      Конфигурация

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

      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, перенаправление через middleware, имена куки, расположение и расширение ваших объявлений контента, отключить логи Intlayer в консоли и многое другое. Полный список доступных параметров см. в документации по конфигурации.

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

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

      index.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() до того, как какой-либо контент будет отрисован, чтобы глобальный синглтон языка был готов.

      src/main.js
      const { installIntlayer } = window.VanillaIntlayer;

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

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

      src/main.js
      const { installIntlayer, installIntlayerMarkdown } = window.VanillaIntlayer;

installIntlayer();
installIntlayerMarkdown();

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

export default appContent;

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

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

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

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

      src/main.js
      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 напрямую:

      javascript
      img.alt = content.viteLogoLabel.value;

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

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

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

      src/locale-switcher.js
      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.

      src/main.js
      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.

      src/app.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 включает автоматически генерируемые типы.

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

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

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

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

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

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

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

    Идите дальше

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

    Часто задаваемые вопросы

    Да. Это то, что охватывает данное руководство. Вы импортируете бандл vanilla-intlayer напрямую в ваш HTML, как показано в шаге 3, инициализируете его в вашей точке входа и читаете ваш контент с помощью useIntlayer. Ни Vite, ни webpack, ни какой-либо конвейер сборки не требуются.

    Гораздо меньше, чем каталог во время выполнения, потому что страница никогда не загружает язык, который не отображает. Контент разрешается из словарей, скомпилированных заранее, а ленивая загрузка по локали держит остальные языки вне начальной полезной нагрузки, пока посетитель не переключится. По сравнению с обычными альтернативами Intlayer сокращает размер бандла и страницы до 50%. См. оптимизацию бандла, динамические словари и бенчмарк.

    В значительной степени. Следуйте руководству по миграции с i18next, чтобы перенести контент. Вы также можете мигрировать постепенно: плагин синхронизации JSON сохраняет ваши существующие каталоги JSON как источник истины и генерирует из них словари Intlayer, поэтому оба слоя остаются синхронизированными, пока вы переносите скрипты по одному.

    Да. Плагин синхронизации JSON сохраняет ваши файлы /messages/{locale}/{namespace}.json как источник истины и генерирует из них словари Intlayer, в обоих направлениях. Плагин синхронизации PO делает то же самое для каталогов gettext, а файлы по локали позволяют разделить контент по языкам вместо группировки локалей в одном файле.

    Нет. Запустите npx intlayer extract, и Intlayer прочитает ваши исходные файлы, извлечёт строки, видимые пользователю, и запишет файл .content рядом с каждым из них, так что вы просматриваете diff вместо копирования строк в каталог по одной. См. команду extract.

    Для полностью автоматизированного конвейера Компилятор Intlayer делает то же самое во время сборки на исходном коде JSX, TSX, Vue и Svelte, генерируя словари при каждом изменении, поэтому нет ключей, которые нужно поддерживать вручную. Он работает через статический анализ, поэтому строки, существующие только во время выполнения, остаются недоступными, и ему нужно несколько аннотаций, чтобы отличать текст, видимый пользователю, от логики приложения.

    Пять компонентов, все опциональные:

    • Расширение для VS Code: переход от ключа useIntlayer к файлу контента, который его объявляет, извлечение контента из компонента и запуск build, fill, test, push и pull из палитры команд или отдельной вкладки Intlayer.
    • LSP-сервер: та же осведомлённость в любом редакторе, который говорит на LSP, с переходом к определению, поиском всех ссылок, предпросмотром переведённого значения при наведении, автодополнением ключей и полей и предупреждением, когда ключ нигде не объявлен. Он также разрешает вызовы i18next, react-i18next, next-intl и use-intl, что помогает при миграции.
    • MCP-сервер: предоставляет документацию и CLI Intlayer для Cursor, VS Code, Claude Desktop, Claude Code и ChatGPT, чтобы ассистент отвечал по актуальной документации, а не гадал, и мог сам запускать команды вроде intlayer fill.
    • Навыки агентов: сфокусированные навыки, такие как intlayer-config, intlayer-cli и intlayer-content, плюс по одному на фреймворк, которые обучают агента вашей настройке маршрутизации и типам узлов контента.
    • Плагин ESLint: no-raw-text помечает жёстко закодированные строки, с дополнительными правилами для статических ключей словаря и неиспользуемого контента.
    Vite и Vanilla JSVite и Lit