Миграция с 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 и адаптер совместимости:

   bash

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   npm install intlayer vue-intlayer @intlayer/vue-i18n @intlayer/sync-json-pluginnpx intlayer init

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

2. 2

   Настройка Intlayer

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

   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({
         // соответствует синтаксису плейсхолдеров 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:

   vite.config.ts

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   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:

   bash

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   npm install nuxt-intlayer

   nuxt.config.ts

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

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

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

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

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

ts

Копировать содержимое

Копировать код

Копировать код в буфер обмена

// '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 для автоматического заполнения недостающих переводов:

   bash

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

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

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

   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