Перехід з vue-i18n на Intlayer

Чому перейти з vue-i18n на Intlayer?

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

Існує дві взаємодоповнюючі стратегії для міграції з vue-i18n на Intlayer:

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

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

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

Table of Contents

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

Наступні кроки є мінімально необхідними для запуску вашого існуючого vue-i18n застосунку на Intlayer без змін коду в ваших компонентах.

1. 1

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

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

   bash

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

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

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

   npx intlayer-cli init --interactive

   прапор --interactive є опціональним. Використовуйте intlayer-cli init, якщо ви AI агент.

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

   bash

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

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

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

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

   Ви можете залишити встановленим 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 повідомляє спостерігачу 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 компілює всі словники під час збирання, тому немає етапу завантаження під час виконання. Псевдонімований провайдер обробляє ініціалізацію для вас.

На цьому швидка міграція завершена. Ваш застосунок тепер працює на 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, типізовані файли контенту, автоматизований переклад на основі AI та інше.

1. 4

   Явне перейменування імпортів (optional)

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

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

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

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

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

   Before	After
   import { useI18n } from 'vue-i18n'	import { useI18n } from '@intlayer/vue-i18n'
   import { createI18n } from 'vue-i18n'	import { createI18n } from '@intlayer/vue-i18n'

   Це drop-in замінники — змін у сигнатурах функцій, аргументах або типах повернення не потрібно.

2. 5

   Увімкніть автоматизацію перекладу на основі AI

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

   Після того як 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 }) => `./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 для всіх доступних опцій.

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

Як тільки адаптери сумісності запущені, наступний boilerplate vue-i18n можна видалити:

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

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

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

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

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

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

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

Йти далі

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