Миграция с vue-i18n на Intlayer

Почему стоит перейти с vue-i18n на Intlayer?

Стратегии миграции

Существует две дополняющие друг друга стратегии миграции с vue-i18n на Intlayer:

1. Адаптер совместимости (рекомендуется для существующих приложений) — Установите @intlayer/vue-i18n (для компонентов Vue). Этот пакет предоставляет абсолютно тот же API, что и vue-i18n, но перенаправляет всю логику переводов в Intlayer. Ваши текущие вызовы $t, useI18n() и <i18n-t> остаются нетронутыми — изменяется только путь импорта и инициализация.

2. Полная миграция — Постепенно заменяйте API vue-i18n на нативный хук Intlayer (useIntlayer) и переводите ваш контент в файлы .content.ts, размещая их рядом с компонентами.

В этом руководстве сначала рассматривается Стратегия 1 (адаптер совместимости), а затем — опциональная полная миграция.

Оглавление

Быстрая миграция

Следующие шаги — это необходимый минимум для запуска вашего приложения vue-i18n с Intlayer без изменений в коде компонентов.

1. 1

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

   Установите основные пакеты Intlayer и адаптер совместимости:

   npm install intlayer vue-intlayer @intlayer/vue-i18n @intlayer/sync-json-plugin
   npx intlayer init

   pnpm add intlayer vue-intlayer @intlayer/vue-i18n @intlayer/sync-json-plugin
   pnpm intlayer init

   yarn add intlayer vue-intlayer @intlayer/vue-i18n @intlayer/sync-json-plugin
   yarn intlayer init

   bun add intlayer vue-intlayer @intlayer/vue-i18n @intlayer/sync-json-plugin
   bun x intlayer init

   Вы можете смело оставить установленным vue-i18n — адаптер совместимости использует его как devDependency / peerDependency для типов TypeScript.

2. 2

   Настройка Intlayer

   Команда intlayer init создает базовый файл intlayer.config.ts. Обновите его, указав ваши текущие локали, и настройте плагин syncJSON на ваши файлы сообщений:

   import { Locales, type IntlayerConfig } from "intlayer";
   import { syncJSON } from "@intlayer/sync-json-plugin";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [
         Locales.ENGLISH,
         Locales.FRENCH,
         Locales.SPANISH,
         // Добавьте все ваши текущие локали сюда
       ],
       defaultLocale: Locales.ENGLISH,
     },
     plugins: [
       syncJSON({
         // соответствует синтаксису плейсхолдеров vue-i18n: {name}
         format: "icu",
         source: ({ locale }) => `./src/locales/${locale}.json`,
         location: "src/locales",
       }),
     ],
   };
   
   export default config;

   source сопоставляет локаль с путем к соответствующему JSON-файлу. location сообщает вотчеру (watcher) Intlayer, за какой папкой нужно следить для отслеживания изменений. Настройка format: 'icu' гарантирует правильную обработку плейсхолдеров вроде vue-i18n.

3. 3

   Добавление плагинов Intlayer в сборщик

   Оберните вашу текущую конфигурацию сборщика плагином совместимости. Это подключает базовый плагин Intlayer, включает отслеживание контента и, что самое важное, внедряет алиасы модулей, так что во время сборки все импорты import … from 'vue-i18n' прозрачно перенаправляются на @intlayer/vue-i18n. Никаких изменений в исходном коде не требуется.

   Для Vite:

   import { defineConfig } from "vite";
   import vue from "@vitejs/plugin-vue";
   import { vueI18nVitePlugin } from "@intlayer/vue-i18n/plugin";
   
   export default defineConfig({
     plugins: [vue(), vueI18nVitePlugin()],
   });

   vueI18nVitePlugin() оборачивает плагин intlayer() из vite-intlayer и автоматически добавляет алиасы для vue-i18n. Использование обычного плагина intlayer() из vite-intlayer скомпилирует словари, но не добавит алиасы — в таком случае вам придется вручную переименовать импорты в @intlayer/vue-i18n (см. шаг 4).

   Для Nuxt:

   Если вы используете @nuxtjs/i18n (Nuxt интеграция), установите nuxt-intlayer и добавьте его в nuxt.config.ts:

   npm install nuxt-intlayer

   export default defineNuxtConfig({
     modules: ["nuxt-intlayer"],
     // Модуль @nuxtjs/i18n можно смело удалять
   });

   Вызов createI18n() или ручная загрузка провайдеров больше не требуются. Intlayer компилирует все словари на этапе сборки (build-time), удаляя шаг загрузки "на лету" (runtime). Подмененный Provider заботится об инициализации.

На этом быстрая миграция завершена. Теперь ваше приложение работает на Intlayer, при этом все ваши импорты и API vue-i18n остаются нетронутыми.

Строгая типизация ключей перевода — автоматически. Как только Intlayer скомпилирует словари, useI18n будет типизирован на основе вашего реального контента, если вы передадите опцию namespace. Ключи будут автодополняться в вашей IDE, а недействительные пути приведут к ошибкам TypeScript при компиляции — дополнительная настройка не требуется.

// 'about' — зарегистрированный ключ словаря
const { t } = useI18n({ namespace: "about" });
t("counter.label"); // ✓ автодополнение
t("does.not.exist"); // ✗ Ошибка TypeScript

Полная миграция

Следующие шаги необязательны и могут выполняться постепенно. Они открывают доступ ко всему набору функций Intlayer: визуальному редактору, CMS, строго типизированным файлам контента, ИИ-автоматизации переводов и многому другому.

1. 4

   Явное переименование импортов (Опционально)

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

   Плагин Intlayer уже справляется с подменой алиасов на уровне сборщика. Если вы хотите сделать зависимости явными в ваших исходных файлах, вы можете переименовать импорты вручную:

   Показать все данные таблицы

   Показать все данные таблицы

   Открыть таблицу в модальном окне для четкого просмотра всех данных

   Было	Стало
   import { useI18n } from 'vue-i18n'	import { useI18n } from '@intlayer/vue-i18n'
   import { createI18n } from 'vue-i18n'	import { createI18n } from '@intlayer/vue-i18n'

   Это прямые замены — вам не нужно менять сигнатуры вызовов, аргументы или возвращаемые типы.

2. 5

   Включение ИИ-автоматизации перевода

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

   Когда Intlayer настроен, вы можете использовать CLI для автоматического заполнения недостающих переводов:

   # Проверить отсутствующие переводы (добавьте в CI)
   npx intlayer test
   
   # Заполнить недостающие переводы с помощью ИИ
   npx intlayer fill

   pnpm intlayer test
   pnpm intlayer fill

   yarn intlayer test
   yarn intlayer fill

   bun x intlayer test
   bun x intlayer fill

   Добавьте конфигурацию ИИ в ваш intlayer.config.ts:

   import { Locales, type IntlayerConfig } from "intlayer";
   import { syncJSON } from "@intlayer/sync-json-plugin";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
       defaultLocale: Locales.ENGLISH,
     },
     plugins: [
       syncJSON({
         format: "icu",
         source: ({ locale }) => `./src/locales/${locale}.json`,
         location: "src/locales",
       }),
     ],
     ai: {
       apiKey: process.env.OPENAI_API_KEY,
       // provider: "openai",     // по умолчанию
       // model: "gpt-4o-mini",   // по умолчанию
     },
   };
   
   export default config;

   Ознакомьтесь с Документацией по Intlayer CLI, чтобы изучить все доступные возможности.

Что можно удалить после миграции

После настройки адаптера совместимости следующий стандартный бойлерплейт vue-i18n можно удалить:

Когда вы будете готовы двигаться дальше, Intlayer автоматически обнаружит все файлы .content.ts и .content.json в любом месте вашей кодовой базы (по умолчанию, в любом месте внутри ./src). Вы можете поместить файл my-component.content.ts прямо рядом с вашим кодом MyComponent.vue, и Intlayer обнаружит его на этапе сборки без дополнительной настройки — не нужно никаких импортов, регистрации или центрального index-файла. Это делает совместное размещение переводов невероятно удобным.

Настройка TypeScript

Intlayer использует расширение модулей (module augmentation), чтобы предоставить полноценный IntelliSense в TypeScript для ключей перевода. Убедитесь, что ваш tsconfig.json включает автоматически сгенерированные типы:

{
  // ... Ваша текущая конфигурация TypeScript
  "include": [
    // ... Ваша текущая конфигурация TypeScript
    ".intlayer/**/*.ts", // Включает автосгенерированные типы
  ],
}

Настройка Git

Добавьте сгенерированную директорию Intlayer в ваш .gitignore:

# Игнорировать файлы, сгенерированные Intlayer
.intlayer

Узнать больше

• Визуальный редактор — Управляйте переводами визуально прямо в браузере: Intlayer Visual Editor
• CMS — Вынесите контент за пределы кода и управляйте им удаленно: Intlayer CMS
• VS Code Расширение — Получите автодополнение и обнаружение ошибок в реальном времени: Intlayer VS Code Extension
• Справочник по CLI — Полный список команд интерфейса командной строки: Intlayer CLI
• Intlayer с Vue — Полное руководство по настройке в Vue: intlayerwithvite+vue.md
• Intlayer с Nuxt — Полное руководство по настройке в Nuxt: intlayerwithnuxt.md