Як правильно обрати бібліотеку Vue i18n

"Vue i18n" є як загальним терміном, так і назвою бібліотеки, яку встановлюють майже всі. Це водночас зручно та оманливо: vue-i18n — хороший варіант за замовчуванням, але це не єдиний вибір, і питання, які мали б визначати рішення (наявність SSR, кількість сторінок, хто саме пише переклади), рідко ставлять перед виконанням npm install.

Цей посібник спочатку розглядає ці запитання, а потім зіставляє відповіді з відповідними бібліотеками як для звичайного Vite + Vue, так і для Nuxt.

Зміст

Шість запитань, на які варто відповісти перед порівнянням бібліотек

1. Vite SPA чи Nuxt? У SPA вартість каталогу є проблемою JS bundle. У Nuxt це також проблема розміру HTML payload, оскільки повідомлення серіалізуються в стан SSR та гідратуються. Більшість скарг на те, що "vue-i18n працює повільно", надходять саме від додатків на Nuxt з цієї причини.
2. Хто пише переклади? Розробники, TMS, агентство, що надає рядки у форматі ICU, або AI pipeline. vue-i18n використовує власний синтаксис множини з роздільником pipe, а не ICU. Це має значення, якщо рядки надходять ззовні.
3. Скільки локалей і сторінок? Дві локалі та п'ять сторінок дозволяють завантажувати все одразу. Десять локалей і сорок маршрутів цього не дозволяють, і стратегія завантаження стає головною статтею витрат.
4. Чи потрібні типи для ключів? t("cart.totl") компілюється у vue-i18n, якщо ви не передасте generic для схеми повідомлень, і ця схема конфліктує з каталогами з lazy loading.
5. Що містить контент? Лише мітки інтерфейсу (UI labels), чи markdown, посилання всередині речень і блоки для окремих локалей. Складний багатий контент (rich content) — це саме те, де використання t(), що повертає звичайний рядок, стає незручним.
6. Чи є CSP обмеженням? Збірка vue-i18n за замовчуванням компілює повідомлення в браузері за допомогою new Function. Збірки runtime-only потребують @intlify/unplugin-vue-i18n для попередньої компіляції під час build time.

Запишіть відповіді. Усе викладене нижче посилається на них.

Загальна картина в одній ілюстрації

Екосистема Vue має менше бібліотек i18n, ніж React, і вони походять з різних архітектурних хвиль.

Стаття про історію JavaScript i18n детально розглядає кожну хвилю.

Рішення, яке має найбільше значення: де зберігається контент і коли він завантажується

Два структурні рішення визначають більшу частину різниці в розмірі bundle між підходами:

• Централізований або ізольований (scoped) контент. Один спільний файл locales/en.json для всього додатку або окрема декларація для кожного компонента.
• Статичний чи динамічний імпорт. Усе завантажується під час старту, або активна локаль (і в ідеалі активний маршрут) завантажується за запитом.

Графік оцінює payload для теоретичного додатку від 1 до 10 сторінок, перекладеного на кількість локалей від 1 до 10, із приблизно 30 КБ тексту на сторінку.

vue-i18n підтримує динамічну вісь: виклик setLocaleMessage після import() дозволяє припинити завантаження дев'яти локалей, які ніхто не читає. Проте він не надає оптимізації за віссю сторінок. Каталог локалі є єдиним об'єктом, і його завантаження підтягує тексти для кожної сторінки. У SPA цього ніхто не помічає. У Nuxt з @nuxtjs/i18n за наявності понад десяти сторінок кожен маршрут тягне за собою тексти всіх інших маршрутів двічі: у JS chunk та в SSR payload.

Бенчмарк Vue вимірює це як "витік з інших маршрутів" (leakage from other routes) та "витік з інших локалей" (leakage from other locales). Якщо вашою відповіддю на запитання 3 було "багато сторінок", цей розділ важливіший за будь-які переваги API. Стаття про покомпонентний та централізований i18n розглядає аспект підтримки цього ж компромісу.

Кандидати

Розміри бібліотек наведено на основі бенчмарку Vue: плагін плюс composable у порожньому компоненті після збирання, tree-shaking та мініфікації в додатку на 10 сторінок і 10 локалей. Обсяг контенту вимірюється окремо.

Цифри є знімком стану версій із бенчмарку. Протестуйте їх на власному додатку, перш ніж приймати рішення виключно на основі розміру.

Майже нульовий розмір бібліотеки Paraglide досягається за рахунок її структури: runtime генерується безпосередньо у ваш репозиторій, що вимагає кроку регенерації перед кожним push та спричиняє merge conflicts у згенерованих файлах. Intlayer потребує vite-intlayer (або модуля Nuxt), тому він не може працювати без етапу збирання.

Зіставте свої відповіді з бібліотекою

Слабкі місця кожної бібліотеки

• vue-i18n: найважча з представлених, власний формат множини, типізація є опціональною та вразливою за використання lazy loading, відсутня ізоляція за маршрутами, невикористовувані ключі непомітно накопичуються. Збереження legacy: true у додатку на Vue 3 залишає шар сумісності з Vue 2 і позбавляє типізації useI18n().
• @nuxtjs/i18n: успадковує всі перераховані недоліки, а SSR payload містить тексти кожної сторінки, якщо кількість маршрутів перевищує десяток.
• fluent-vue: чудовий синтаксис повідомлень, відсутність типізації ключів, а плагін для Vite завантажує весь контент усіма мовами на кожну сторінку. Найважча бібліотека в бенчмарку.
• Paraglide: згенеровані файли додаються до репозиторію, регенерація перед кожним push, а локаль зчитується з cookie або storage при кожному виклику повідомлення, а не з реактивного сховища, що створює додаткове навантаження під час зміни локалі.
• Intlayer: обов'язковий плагін для збирання, менша екосистема, часткова підтримка ICU та контент, розподілений по кодовій базі за дизайном, тому експорт єдиного JSON для перекладача потребує додаткових інструментів.

Як кожен варіант виглядає в коді

Один і той самий компонент, підсумок кошика із заголовком та формою множини, написаний для кожного кандидата. Найцікавіша частина полягає не в шаблоні, а в тому, де зберігається контент і що про нього відомо vue-tsc.

{
  "cart": {
    "title": "Your cart",
    "items": "no item | one item | {count} items"
  }
}

<script setup lang="ts">
import { useI18n } from "vue-i18n";

const props = defineProps<{ count: number }>();
const { t } = useI18n();
</script>

<template>
  <section>
    <h2>{{ t("cart.title") }}</h2>
    <p>{{ t("cart.items", { count: props.count }, props.count) }}</p>
  </section>
</template>

cart-title = Your cart
cart-items = { $count ->
    [one] { $count } item
   *[other] { $count } items
}

<script setup lang="ts">
import { useFluent } from "fluent-vue";

const props = defineProps<{ count: number }>();
const { $t } = useFluent();
</script>

<template>
  <section>
    <h2>{{ $t("cart-title") }}</h2>
    <p>{{ $t("cart-items", { count: props.count }) }}</p>
  </section>
</template>

{
  "cart_title": "Your cart",
  "cart_items": "{count} items"
}

<script setup lang="ts">
import { m } from "../paraglide/messages.js";

const props = defineProps<{ count: number }>();
</script>

<template>
  <section>
    <h2>{{ m.cart_title() }}</h2>
    <p>{{ m.cart_items({ count: props.count }) }}</p>
  </section>
</template>

import { plural, t, type Dictionary } from "intlayer";

const cartSummaryContent = {
  key: "cart-summary",
  content: {
    title: t({ en: "Your cart", fr: "Votre panier", es: "Tu carrito" }),
    items: t({
      en: plural({ one: "{{count}} item", other: "{{count}} items" }),
      fr: plural({ one: "{{count}} article", other: "{{count}} articles" }),
      es: plural({ one: "{{count}} artículo", other: "{{count}} artículos" }),
    }),
  },
} satisfies Dictionary;

export default cartSummaryContent;

<script setup lang="ts">
import { useIntlayer } from "vue-intlayer";

const props = defineProps<{ count: number }>();
const { title, items } = useIntlayer("cart-summary");
</script>

<template>
  <section>
    <h2><title /></h2>
    <p>{{ items(props.count) }}</p>
  </section>
</template>

Вже використовуєте vue-i18n? Адаптер сумісності @intlayer/vue-i18n створює alias для пакета на рівні бандлера, тому useI18n(), $t, множина через pipe та v-t продовжують працювати, поки Intlayer надає контент. Посібник із міграції пояснює подальшу відмову від адаптера, також є окремий посібник для Nuxt.

Перш ніж зробити вибір

Таблиця функціоналу показує, що бібліотека вміє сьогодні. Наведені нижче пункти описують, яким буде її щоденне використання.

Перевірте активність репозиторію.

Коміти, час реакції на issues та наявність мінорного релізу в поточному році. Продумана архітектура без супроводу — це неминуча майбутня міграція.

Не обирайте за кількістю завантажень в npm.

Найчастіше встановлюють бібліотеку, яка з'явилася першою, а не ту, що найкраще підходить для кодової бази Vue у 2026 році. Завантаження відображають історію, а не відповідність вимогам.

Дізнайтеся, хто фінансує розробку та що вони продають.

vue-i18n підтримується Crowdin, як і next-intl та svelte-i18n. i18next підтримується Locize. Tolgee, Paraglide (inlang) та Intlayer розвивають власні платформи. Постачальник, чий дохід базується на платному хостингу перекладів, має мало стимулів робити переклад безкоштовним всередині вашого інструментарію. Intlayer є єдиним серед них, хто надає AI-переклад через CLI з використанням вашого власного API key, а також CMS, яку можна хостити самостійно.

Чи готова бібліотека до взаємодії з AI-агентами?

Агенти все ще стикаються з труднощами в i18n: вони забувають локалі, вигадують неіснуючі ключі та плутають синтаксис повідомлень. Чи надає бібліотека Agent Skills або сервер MCP, щоб агент міг переглядати, заповнювати та тестувати контент? І чи оптимізовано завантаження контенту за замовчуванням, чи комусь доведеться щокварталу перевіряти namespaces та lazy imports?

Типобезпека з коробки.

Не "можна типізувати за допомогою додаткового коду", а "неправильний ключ призводить до помилки tsc одразу після встановлення". Перевірте поведінку з ключем, якого не існує, та з локаллю, де відсутній один переклад.

Виявлення невикористовуваного контенту.

Каталоги лише розростаються. Збірка Intlayer видаляє невикористовувані поля та записує їх у логи (build.purge). Paraglide досягає цього завдяки архітектурі, оскільки невикликана функція повідомлення видаляється через tree-shaking. Усі інші рішення залишають очищення на вас.

Досвід розробника (Developer Experience).

Час від налаштування до першого перекладеного рядка, LSP або розширення VS Code, яке показує переклад при наведенні курсору та переходить до декларації, CLI для заповнення, тестування та відправки, а також можливість редагування контенту без участі розробників (візуальний редактор або CMS) без відкриття pull request.

Часті запитання

Додаткові матеріали

• Бенчмарк Vue i18n: розмір bundle, витоки та час перемикання локалі
• Vue i18n: як працює vue-i18n та де виникають проблеми та публікація про Nuxt i18n
• vue-i18n проти Intlayer: детальне порівняння функцій та бенчмарк vue-i18n проти Intlayer
• Чи застарів vue-i18n?
• Історія JavaScript i18n
• Компіляторний чи декларативний i18n
• Покомпонентний чи централізований i18n
• Налаштування i18n у додатку Vite + Vue та в додатку Nuxt
• Аналогічні посібники для React, Svelte та Solid