Міграція з @nuxtjs/i18n на Intlayer

Чому мігрувати з @nuxtjs/i18n на Intlayer?

Стратегії міграції

Оскільки @nuxtjs/i18n використовує vue-i18n під капотом, існує дві взаємодоповнюючі стратегії для міграції на Intlayer:

1. Compat adapter (рекомендується для існуючих додатків) — Встановіть @intlayer/vue-i18n та nuxt-intlayer. Це надає той самий API, що й vue-i18n, але делегує всю роботу перекладу на Intlayer під капотом. Ви зберігаєте свої існуючі $t, useI18n() та маршрутизацію Nuxt без змін — єдина зміна — це ініціалізація.

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

Цей посібник охоплює Стратегію 1 спочатку (drop-in compat adapter), а потім розглядає необов'язкову повну міграцію.

Зміст

Швидка міграція

Наступні кроки — це мінімум, необхідний для запуску вашого існуючого додатка Nuxt на Intlayer без змін коду в компонентах.

1. 1

   Встановлення залежностей

   Встановіть основні пакети Intlayer та адаптер сумісності:

   bash

   Копіювати вміст

   Копіювати код

   Скопіюйте код у буфер обміну

   npx intlayer-cli init --interactive

   прапор --interactive необов'язковий. Використовуйте intlayer-cli init, якщо ви — агент AI.

   Ця команда визначить ваше середовище та встановить необхідні пакети. Приклад:

   bash

   Копіювати вміст

   Копіювати код

   Скопіюйте код у буфер обміну

   npm install intlayer vue-intlayer nuxt-intlayer @intlayer/vue-i18n @intlayer/sync-json-plugin

   Ви можете безпечно залишити встановленим @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 повідомляє спостерігачу 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"],
   });

   Вам більше не потрібно визначати об'єкти конфігурації Nuxt i18n. Intlayer компілює всі словники під час build time, безпроблемно обробляючи виявлення локалей, маршрутизацію та завантаження словників.

На цьому швидка міграція завершена. Ваш додаток Nuxt тепер працює на Intlayer, зберігаючи всі $t та useI18n() без змін.

Повна міграція

Наведені нижче кроки є необов'язковими та можуть виконуватися поступово. Вони розблоковують повний набір функцій Intlayer: візуальний редактор, CMS, типізовані файли вмісту, переклад на базі штучного інтелекту та інше.

1. 4

   Явне перейменування імпортів (необов'язково)

   Необов'язково

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

   Показати весь вміст таблиці

   Показати весь вміст таблиці

   Відкрийте таблицю в модальному вікні, щоб чітко переглянути всі дані

   Раніше	Після
   import { useI18n } from 'vue-i18n'	import { useI18n } from '@intlayer/vue-i18n'

   Це drop-in replacements — не потрібні жодні зміни до сигнатур викликів, аргументів або типів повернення.

2. 5

   Включення автоматизації перекладу на базі штучного інтелекту

   Необов'язково

   Після того, як Intlayer налаштовано, використовуйте його CLI для автоматичного заповнення відсутніх перекладів:

   bash

   Копіювати вміст

   Копіювати код

   Скопіюйте код у буфер обміну

   # Тест на відсутні перекладу (додати до CI)npx intlayer test# Заповнити відсутні перекладу за допомогою AInpx intlayer fill

   Додайте конфігурацію AI до 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;

   Див. документацію CLI Intlayer для всіх доступних опцій.

Що можна видалити після міграції

Після встановлення compat adapter можна видалити наступний boilerplate:

Коли ви будете готові йти далі, Intlayer автоматично виявляє всі файли .content.ts і .content.json будь-де в вашому codebase (за замовчуванням, будь-де всередині ./src). Ви можете розмістити файл my-component.content.ts прямо поруч з вашим MyComponent.vue, і Intlayer виявить його під час збірки без будь-якої додаткової конфігурації — не потрібні імпорти, реєстрація чи централізований файл індексу. Це робить co-locating перекладів зі сторінками та компонентами абсолютно безпроблемним.

Налаштування TypeScript

Intlayer використовує module augmentation для надання повної TypeScript intellisense для ваших ключів перекладу. Переконайтеся, що ваш tsconfig.json включає автоматично згенеровані типи:

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

Конфігурація Git

Додайте згенерований Intlayer директорій до вашого .gitignore:

# Ігнорувати файли, генеровані Intlayer.intlayer

Йдіть далі

• Visual Editor — Керуйте перекладами візуально у вашому браузері: Intlayer Visual Editor
• CMS — Зберігайте та керуйте контентом віддалено: Intlayer CMS
• VS Code Extension — Отримайте автодоповнення та виявлення помилок перекладу в реальному часі: Intlayer VS Code Extension
• CLI Reference — Повний список команд CLI: Intlayer CLI
• Intlayer with Nuxt — Повний посібник налаштування для Nuxt: intlayerwithnuxt.md
• Intlayer with Vue — Повний посібник налаштування для Vue: intlayerwithvite+vue.md