Миграция с @nuxtjs/i18n на Intlayer

Почему стоит перейти с @nuxtjs/i18n на Intlayer?

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

Поскольку @nuxtjs/i18n работает поверх vue-i18n, существуют две взаимодополняющие стратегии миграции на Intlayer:

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

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

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

Оглавление

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

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

1. 1

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

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

   bash

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

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

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

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

   Вы можете безопасно оставить установленным пакет @nuxtjs/i18n во время миграции (мы удалим его из конфигурации Nuxt позже).

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 }) => `./locales/${locale}.json`,
         location: "locales",
       }),
     ],
   };
   
   export default config;

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

3. 3

   Обновление конфигурации Nuxt

   Замените модуль @nuxtjs/i18n на nuxt-intlayer в файле nuxt.config.ts. Плагин Intlayer автоматически внедряет алиасы модулей, так что ваши текущие импорты import { useI18n } from 'vue-i18n' прозрачно перенаправляются в @intlayer/vue-i18n.

   nuxt.config.ts

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

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

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

   export default defineNuxtConfig({
     // Удалите '@nuxtjs/i18n'
     modules: ["nuxt-intlayer"],
   });

   Вам больше не нужно определять объект конфигурации i18n для Nuxt. Intlayer компилирует все словари на этапе сборки (build-time), бесшовно обрабатывая определение локали, маршрутизацию и загрузку словарей.

На этом быстрая миграция завершена. Теперь ваше приложение Nuxt работает на Intlayer, при этом все ваши вызовы $t и useI18n() остаются без изменений.

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

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

1. 4

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

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

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

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

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

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

   Было	Стало
   import { useI18n } from 'vue-i18n'	import { useI18n } 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 }) => `./locales/${locale}.json`,
         location: "locales",
       }),
     ],
     ai: {
       apiKey: process.env.OPENAI_API_KEY,
       // provider: "openai",     // по умолчанию
       // model: "gpt-4o-mini",   // по умолчанию
     },
   };
   
   export default config;

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

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

После настройки адаптера совместимости следующий стандартный бойлерплейт @nuxtjs/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 с Nuxt — Полное руководство по настройке для Nuxt: intlayerwithnuxt.md
• Intlayer с Vue — Полное руководство по настройке для Vue: intlayerwithvite+vue.md