@intlayer/docs 9.5.5 → 9.5.7

package/blog/ru/vue-i18n_vs_intlayer-vue-i18n.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-09-13
-updatedAt: 2026-09-13
+updatedAt: 2026-09-22
 title: "vue-i18n vs @intlayer/vue-i18n: Одинаковый API, Разные Bundle"
 description: Что меняется, когда приложение Vue 3 сохраняет свои вызовы vue-i18n, но обслуживает их через адаптер совместимости @intlayer/vue-i18n. JavaScript на странице, размер runtime, размер компонента и утечки, измеренные на одном коде Vite + Vue, плюс то, что адаптер сохраняет, игнорирует и не может заменить.
 keywords:
@@ -25,17 +25,19 @@ author: aymericzip
 
 # vue-i18n VS @intlayer/vue-i18n | Одинаковый API, Разные Bundle
 
-`@intlayer/vue-i18n` — это адаптер совместимости: он предоставляет API `vue-i18n` (`createI18n`, `useI18n`, `t()`, `d()`, `n()`, `$t`, `v-t`, `i18n.global.locale`...) и обслуживает его из словарей, скомпилированных Intlayer. Ваши файлы `.vue` не изменяются. Только то, к чему привязан `t("footer.github")`, меняется.
+![Vue i18n library ecosystem](https://github.com/aymericzip/intlayer/blob/main/docs/assets/cloud_i18n_logo.webp?raw=true)
+
+`@intlayer/vue-i18n`, это адаптер совместимости: он предоставляет API `vue-i18n` (`createI18n`, `useI18n`, `t()`, `d()`, `n()`, `$t`, `v-t`, `i18n.global.locale`...) и обслуживает его из словарей, скомпилированных Intlayer. Ваши файлы `.vue` не изменяются. Только то, к чему привязан `t("footer.github")`, меняется.
 
 В этой статье измеряется эта замена в одном и том же приложении Vite + Vue 3, собранном один раз с `vue-i18n` и один раз с адаптером. Цифры взяты из [Benchmark Bloom](https://github.com/intlayer-org/benchmark-bloom). Для сравнения `vue-i18n` и Intlayer как библиотек прочитайте [vue-i18n vs Intlayer](https://intlayer.org/blog/vue-i18n-vs-intlayer) и [бенчмарк vue-i18n vs Intlayer](https://intlayer.org/blog/vue-i18n-vs-intlayer-benchmark). Это о том, какие изменения вносит адаптер, когда вы оставляете свои компоненты как они есть.
 
 <TOC/>
 
-> **tl;dr**: На том же приложении Vite + Vue 3 замена `vue-i18n` на `@intlayer/vue-i18n` снизила JavaScript на страницу с **134.9 KB до 47.0 KB** gzip (приложение без i18n весит 41.3 KB), runtime с **24.3 KB до 7.9 KB**, средний компонент с **196 KB до 8.4 KB**, и утечку строк на иностранных страницах с **90% на 0%**, без редактирования файлов `.vue`. `createI18n({ messages })` продолжает работать как fallback; удалите импорты JSON для получения указанных выше значений. SFC блоки `<i18n>` и runtime `setLocaleMessage()` — это два функционала, которые не переносятся.
+> **tl;dr**: На том же приложении Vite + Vue 3 замена `vue-i18n` на `@intlayer/vue-i18n` снизила JavaScript на страницу с **134.9 KB до 47.0 KB** gzip (приложение без i18n весит 41.3 KB), runtime с **24.3 KB до 7.9 KB**, средний компонент с **196 KB до 8.4 KB**, и утечку строк на иностранных страницах с **90% на 0%**, без редактирования файлов `.vue`. `createI18n({ messages })` продолжает работать как fallback; удалите импорты JSON для получения указанных выше значений. SFC блоки `<i18n>` и runtime `setLocaleMessage()`, это два функционала, которые не переносятся.
 
 ## Что такое `@intlayer/vue-i18n`
 
-`vue-i18n` — это runtime. `createI18n({ messages: { en, fr, ... } })` создает глобальный экземпляр, содержащий все сообщения для каждой локали; `useI18n()` привязывает каждый компонент к нему; `t("footer.github")` проходит по дереву во время рендеринга. Такой дизайн позволяет использовать SFC `<i18n>` блоки и `setLocaleMessage()`, и он же является причиной того, что граф зависимостей каждого компонента включает все дерево.
+`vue-i18n`, это runtime. `createI18n({ messages: { en, fr, ... } })` создает глобальный экземпляр, содержащий все сообщения для каждой локали; `useI18n()` привязывает каждый компонент к нему; `t("footer.github")` проходит по дереву во время рендеринга. Такой дизайн позволяет использовать SFC `<i18n>` блоки и `setLocaleMessage()`, и он же является причиной того, что граф зависимостей каждого компонента включает все дерево.
 
 `@intlayer/vue-i18n` сохраняет API и заменяет дерево:
 
@@ -105,6 +107,10 @@ const { t } = useI18n(_dicHash_footer);
 
 ### Результаты на Vite + Vue 3
 
+Выберите метрики и библиотеки, которые вас интересуют:
+
+<I18nBenchmark framework="vite-vue" vertical/>
+
 | Setup                    | Strategy | Lib size (gz) | Lib size (min) | Page JS avg (gz) | Locale leak | Page leak | Component avg (gz) | E2E reactivity |  Page load |
 | ------------------------ | -------- | ------------: | -------------: | ---------------: | ----------: | --------: | -----------------: | -------------: | ---------: |
 | **base** (без i18n)      | -        |        0.0 KB |         0.0 KB |          41.3 KB |        0.0% |         - |             1.1 KB |         1.8 ms |    10.8 ms |
@@ -117,18 +123,31 @@ const { t } = useI18n(_dicHash_footer);
 
 **Как это читать**
 
-- **88 KB меньше на страницу, те же компоненты.** `vue-i18n` берет приложение 41.3 KB и доводит его до **134.9 KB**. Адаптер сборки тех же компонентов приземляется на **47.0 KB**, на 5.7 KB больше, чем базовое приложение. Большая часть разницы — это 74.9 KB из `src/locales`, которые `createI18n({ messages })` втягивает на каждую страницу, а адаптер никогда не бундлит как блок.
+- **88 KB меньше на страницу, те же компоненты.** `vue-i18n` берет приложение 41.3 KB и доводит его до **134.9 KB**. Адаптер сборки тех же компонентов приземляется на **47.0 KB**, на 5.7 KB больше, чем базовое приложение. Большая часть разницы, это 74.9 KB из `src/locales`, которые `createI18n({ messages })` втягивает на каждую страницу, а адаптер никогда не бундлит как блок.
 - **Runtime сжимается в 3 раза.** Пустой компонент, который только импортирует `vue-i18n`, стоит **24.3 KB gzip / 83.2 KB minified**: `@intlify/core-base`, компилятор сообщений и runtime. Адаптер стоит **7.9 KB / 23.2 KB**, большую часть составляет ядро Intlayer плюс поверхность API `vue-i18n`.
 - **Компоненты: в 23 раза меньше.** Компонент `useI18n()`, скомпилированный изолированно, в среднем занимает **196 KB**, потому что `t` привязана к экземпляру, который содержит каждое сообщение каждой локали. С адаптером тот же компонент в среднем занимает **8.4 KB**: он обращается к собственному словарю.
-- **Утечка.** `vue-i18n` поставляет все локали и строки каждой страницы на каждой странице: 50% утечка локали (по двум отпечатанным локалям; при десяти объединённых локалях реальные потери выше), 90% утечка страницы. Адаптер снижает утечку страницы до **0%**, потому что каждый компонент импортирует только свои словари. Утечка локали составляет 15% в этом запуске `static`; `importMode: 'dynamic'` — это параметр, который её устраняет, и эта конфигурация не была частью этого запуска Vue.
+- **Утечка.** `vue-i18n` поставляет все локали и строки каждой страницы на каждой странице: 50% утечка локали (по двум отпечатанным локалям; при десяти объединённых локалях реальные потери выше), 90% утечка страницы. Адаптер снижает утечку страницы до **0%**, потому что каждый компонент импортирует только свои словари. Утечка локали составляет 15% в этом запуске `static`; `importMode: 'dynamic'`, это параметр, который её устраняет, и эта конфигурация не была частью этого запуска Vue.
 - **Реактивность и загрузка страницы.** Переключение локали дешёво для обоих (1,5-2,8 мс); система реактивности Vue делает это возможным, как только сообщения находятся в памяти. Загрузка страницы уменьшается с 13,6 мс до **9,3 мс**, что соответствует 88 КБ меньше JavaScript для парсинга.
-- **О нативных строках.** `vue-intlayer` в этом запуске собрал все локали в режиме `static` и достиг размера 57,1 КБ с runtime в 3,9 КБ; синхронизированные словари адаптера содержали меньше строк иностранных локалей, отсюда и меньший показатель на одну страницу. Нативный runtime остается самым легким из трех, а его модель `.content.ts` — это эквивалент SFC `<i18n>` блоков.
+- **О нативных строках.** `vue-intlayer` в этом запуске собрал все локали в режиме `static` и достиг размера 57,1 КБ с runtime в 3,9 КБ; синхронизированные словари адаптера содержали меньше строк иностранных локалей, отсюда и меньший показатель на одну страницу. Нативный runtime остается самым легким из трех, а его модель `.content.ts`, это эквивалент SFC `<i18n>` блоков.
+
+<ClickToOpenIframe
+src="https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-vite_vue.md"
+width="100%"
+height="600px"
+style="border:none;"
+/>
+
+> Полная таблица, каждая библиотека и каждая стратегия, в [отчете о бенчмарке Vue](https://intlayer.org/ru/doc/benchmark/vue).
 
 ## Почему меняются цифры
 
+![The Intlayer compiler extracts content from components](https://github.com/aymericzip/intlayer/blob/main/docs/assets/compiler.webp?raw=true)
+
 Ничего в `src/components/` не изменилось, поэтому улучшения исходят из того, к чему привязан `useI18n`.
 
-**С `vue-i18n`** связывание осуществляется через глобальный экземпляр. `createI18n({ messages: { en, fr, ... } })` — это один импорт, который содержит всё; каждый компонент, вызывающий `useI18n()`, может получить доступ ко всему этому, поэтому bundler не может разделить ниже уровня экземпляра. Оптимизация означает, что _вы_ разделяете `en.json` по маршрутам, вызываете `setLocaleMessage()` в guard маршрутизатора и поддерживаете корректность карты маршрут-к-файлу по мере перемещения компонентов.
+**С `vue-i18n`** связывание осуществляется через глобальный экземпляр. `createI18n({ messages: { en, fr, ... } })`, это один импорт, который содержит всё; каждый компонент, вызывающий `useI18n()`, может получить доступ ко всему этому, поэтому bundler не может разделить ниже уровня экземпляра. Оптимизация означает, что _вы_ разделяете `en.json` по маршрутам, вызываете `setLocaleMessage()` в guard маршрутизатора и поддерживаете корректность карты маршрут-к-файлу по мере перемещения компонентов. Утечки растут сразу по двум осям, страницы и локали:
+
+![Theoretical content leakage by architecture](https://github.com/aymericzip/intlayer/blob/main/docs/assets/theorical_content_leakage.webp?raw=true)
 
 ```bash
 .
@@ -158,7 +177,7 @@ const { t } = useI18n(_dicHash_footer);
         └── Footer.vue             # useI18n(); t("footer.github")  ← без изменений
 ```
 
-Импорт `messages` в `i18n.ts` — это одна строка, которую нужно удалить. Это 88 KB.
+Импорт `messages` в `i18n.ts`, это одна строка, которую нужно удалить. Это 88 KB.
 
 ## Миграция в три шага
 
@@ -235,7 +254,7 @@ import { createI18n } from "vue-i18n";
 export const i18n = createI18n({ locale: "en" });
 ```
 
-`vueI18nVitePlugin()` оборачивает `vite-intlayer` (наблюдение за содержимым, компиляция словаря, шаг оптимизации) и создает алиас `vue-i18n` на адаптер. Удаление импорта `messages` — это то, что уменьшает размер на 88 KB; если оставить его, приложение продолжит работать, но будет содержать оба варианта.
+`vueI18nVitePlugin()` оборачивает `vite-intlayer` (наблюдение за содержимым, компиляция словаря, шаг оптимизации) и создает алиас `vue-i18n` на адаптер. Удаление импорта `messages`, это то, что уменьшает размер на 88 KB; если оставить его, приложение продолжит работать, но будет содержать оба варианта.
 
 </Step>
 </Steps>
@@ -251,38 +270,119 @@ export const i18n = createI18n({ locale: "en" });
 
 ### Что вы получите кроме сокращения размера
 
-- **Типизированные ключи.** `t("footer.github")` типизируется против скомпилированного словаря `footer`; неправильный путь — это ошибка TypeScript вместо отображения ключа как текста.
+- **Типизированные ключи.** `t("footer.github")` типизируется против скомпилированного словаря `footer`; неправильный путь, это ошибка TypeScript вместо отображения ключа как текста.
 - **`npx intlayer test`** прерывает CI при отсутствии ключа в любой локали. **`npx intlayer fill`** переводит отсутствующие ключи с помощью вашего поставщика (OpenAI, Anthropic, Mistral, Gemini...) и записывает их обратно в `locales/{locale}.json`.
 - **Visual Editor и CMS** работают с одним и тем же JSON, поэтому не разработчики могут редактировать через UI, а файлы обновляются автоматически.
 - **Постепенный переход на `.content.ts`.** Любой компонент может переключиться с `useI18n()` на `useIntlayer("footer")` с сопутствующим файлом контента. JSON и `.content.ts` словари сосуществуют и объединяются.
 
 ## Ограничения, которые нужно знать перед началом
 
-- **SFC `<i18n>` блоки не читаются.** Если ваши сообщения находятся внутри компонентов, они должны переместиться в файлы локалей (или в `.content.ts`, что является тем же самым с типами).
-- **Загрузка сообщений во время выполнения исчезла.** `setLocaleMessage()` и `mergeLocaleMessage()` выдают предупреждение и возвращают результат. Переводы, полученные из CMS во время выполнения, требуют CMS Intlayer или команд `intlayer pull` / `push`.
-- **`messages` — это fallback, не бесплатно.** Сохранение импортов JSON в `createI18n()` оставляет 75 KB в бандле. Удалите их после того, как пройдёт `intlayer test`.
-- **Адаптер не является нативным runtime.** 7.9 KB против 3.9 KB для `vue-intlayer`. Как только каждый компонент переместится на `useIntlayer`, удалите его.
+<AccordionGroup>
+<Accordion header="Блоки SFC <i18n> не считываются">
+
+Если ваши сообщения находятся внутри компонентов, их необходимо перенести в файлы локалей или в файл `.content.ts`, что является той же идеей со сгенерированными типами.
+
+</Accordion>
+<Accordion header="Загрузка сообщений во время выполнения удалена">
+
+`setLocaleMessage()` и `mergeLocaleMessage()` выводят предупреждение и завершают работу. Переводы, получаемые из CMS во время выполнения, требуют [Intlayer CMS](https://intlayer.org/ru/doc/concept/cms) или команд `intlayer pull` / `push`.
+
+</Accordion>
+<Accordion header="messages является запасным вариантом, но не бесплатным">
+
+Сохранение импорта JSON в `createI18n()` оставляет 75 КБ в бандле. Удалите их, как только `intlayer test` пройдет успешно.
+
+</Accordion>
+<Accordion header="Адаптер не является нативным рантаймом">
+
+7.9 КБ против 3.9 КБ у `vue-intlayer`. Как только каждый компонент перейдет на `useIntlayer`, удалите его.
+
+</Accordion>
+</AccordionGroup>
 
 ## Когда что использовать?
 
-- **Оставайтесь на `vue-i18n`**, если ваше приложение зависит от SFC `<i18n>` блоков, от runtime потоков `setLocaleMessage()`, или если 90 KB на странице не являются проблемой для вашей аудитории.
-- **Используйте `@intlayer/vue-i18n`**, если вы работаете с `vue-i18n` и хотите снизить размер на 88 KB, иметь компоненты меньше в 23 раза, 0% утечки страниц, типизированные ключи и CI проверки без редактирования файла `.vue`. Это точка входа для существующей `vue-i18n` codebase.
-- **Переходите на native (`vue-intlayer`)** для новых проектов или когда адаптер выполнит свою роль. Он имеет самый легкий runtime (3.9 KB) и модель `.content.ts` на компонент, который заменяет `<i18n>` блоки типизированным контентом.
+<AccordionGroup>
+<Accordion header="Остаться на vue-i18n">
+
+Ваше приложение зависит от блоков SFC `<i18n>`, от процессов `setLocaleMessage()` во время выполнения, или 90 КБ на страницу не имеют значения для вашей аудитории.
+
+</Accordion>
+<Accordion header="Использовать @intlayer/vue-i18n">
+
+Вы используете `vue-i18n` и хотите получить экономию 88 КБ, в 23 раза меньшие компоненты, 0% утечки страниц, типизированные ключи и проверки CI без редактирования файлов `.vue`. Это точка входа для существующей кодовой базы `vue-i18n`.
+
+</Accordion>
+<Accordion header="Перейти на нативный (vue-intlayer)">
+
+Для новых проектов или когда адаптер выполнил свою задачу. Он имеет самый легкий рантайм (3.9 КБ) и модель `.content.ts` для каждого компонента, заменяющую блоки `<i18n>` типизированным содержимым. Начните с [Intlayer с Vue](https://intlayer.org/ru/doc/environment/vite-and-vue) или [с Nuxt](https://intlayer.org/ru/doc/environment/nuxt-and-vue).
+
+</Accordion>
+</AccordionGroup>
+
+## Часто задаваемые вопросы
+
+<FAQ>
+
+<Question title="Нужно ли мне редактировать мои файлы .vue?">
+
+Нет. Сборка бенчмарка изменила только `vite.config.ts`, `intlayer.config.ts` и одну строку в `src/i18n.ts`, импорт `messages`. Все вызовы `useI18n()`, `$t`, `v-t` и Options API остались без изменений.
+
+</Question>
+
+<Question title="Почему размер компонента в 23 раза меньше?">
+
+Потому что `useI18n()` больше не обращается к глобальному экземпляру. `createI18n({ messages })` содержит все сообщения всех локалей, поэтому компонент, скомпилированный изолированно, тянет 196 КБ. С адаптером он обращается только к собственному словарю: 8.4 КБ.
+
+</Question>
+
+<Question title="Что насчет форматирования с помощью d() и n()?">
+
+Сохранено. Конфигурации `datetimeFormats` и `numberFormats`, переданные в `createI18n()`, учитываются и поддерживаются нативным `Intl`. См. [форматирование даты, времени и чисел](https://intlayer.org/ru/blog/date-time-number-formatting-locales).
+
+</Question>
+
+<Question title="Работает ли это с Nuxt?">
+
+`@intlayer/vue-i18n` ориентирован на Vite + Vue. Для `@nuxtjs/i18n` используйте [адаптер совместимости Nuxt i18n](https://intlayer.org/ru/doc/compatibility/nuxtjs-i18n) и ознакомьтесь с [Intlayer с Nuxt](https://intlayer.org/ru/doc/environment/nuxt-and-vue) для нативной настройки.
+
+</Question>
+
+<Question title="Могу ли я мигрировать покомпонентно?">
+
+Да. Любой компонент может переключиться с `useI18n()` на `useIntlayer("footer")` с расположенным рядом файлом контента. Словари JSON и `.content.ts` сосуществуют и объединяются.
+
+</Question>
+
+</FAQ>
 
 ## Связанные сравнения
 
-- [vue-i18n vs Intlayer](https://intlayer.org/blog/vue-i18n-vs-intlayer) (возможности и DX)
-- [vue-i18n vs Intlayer benchmark](https://intlayer.org/blog/vue-i18n-vs-intlayer-benchmark) (библиотеки, одинаковый benchmark)
-- [next-intl vs @intlayer/next-intl](https://intlayer.org/blog/next-intl-vs-intlayer-next-intl) (одна серия адаптеров)
-- [i18next vs @intlayer/i18next](https://intlayer.org/blog/i18next-vs-intlayer-i18next) (одна серия адаптеров)
-- [Lingui vs @intlayer/lingui](https://intlayer.org/blog/lingui-vs-intlayer-lingui) (одна серия адаптеров)
-- [Руководство по миграции: vue-i18n на Intlayer](https://intlayer.org/doc/migration/vue-i18n)
-- [Compat adapter reference: vue-i18n](https://intlayer.org/doc/compatibility/vue-i18n), [Nuxt i18n](https://intlayer.org/doc/compatibility/nuxtjs-i18n)
+Та же серия адаптеров:
+
+- [next-intl vs @intlayer/next-intl](https://intlayer.org/ru/blog/next-intl-vs-intlayer-next-intl)
+- [i18next vs @intlayer/i18next](https://intlayer.org/ru/blog/i18next-vs-intlayer-i18next)
+- [Lingui vs @intlayer/lingui](https://intlayer.org/ru/blog/lingui-vs-intlayer-lingui)
+
+Прямое сравнение библиотек:
+
+- [vue-i18n vs Intlayer](https://intlayer.org/ru/blog/vue-i18n-vs-intlayer), функции и DX
+- [vue-i18n vs Intlayer benchmark](https://intlayer.org/ru/blog/vue-i18n-vs-intlayer-benchmark)
+- [Is vue-i18n outdated?](https://intlayer.org/ru/blog/is-vue-i18n-outdated)
+- [How to pick a Vue i18n library](https://intlayer.org/ru/blog/how-to-pick-vue-i18n-library)
+
+Справочная документация:
+
+- [Compat adapter: vue-i18n](https://intlayer.org/ru/doc/compatibility/vue-i18n) and [Nuxt i18n](https://intlayer.org/ru/doc/compatibility/nuxtjs-i18n)
+- [Руководство по миграции: vue-i18n на Intlayer](https://intlayer.org/ru/doc/migration/vue-i18n)
+- [Отчет о бенчмарке Vue](https://intlayer.org/ru/doc/benchmark/vue)
+- [Оптимизация бандла](https://intlayer.org/ru/doc/concept/bundle-optimization) и [компилятор Intlayer](https://intlayer.org/ru/doc/compiler)
+- [Визуальный редактор](https://intlayer.org/ru/doc/concept/editor), [CMS](https://intlayer.org/ru/doc/concept/cms) и [ИИ-перевод](https://intlayer.org/ru/doc/concept/auto-fill)
 
 ## Заключение
 
-`@intlayer/vue-i18n` изменяет то, к чему привязан `useI18n()`: от глобального экземпляра, содержащего все сообщения каждой локали, к словарю, скомпилированному для этого компонента. На том же приложении Vite + Vue 3 это дает **88 KB меньше на странице**, **runtime в 3 раза меньше**, **компоненты в 23 раза меньше** и **0% утечек страницы**, при этом требуя только файл конфигурации, одну строку плагина и одно удаленное импортирование. SFC блоки `<i18n>` и загрузка сообщений во время выполнения — это две вещи, которые он не поддерживает, и native `vue-intlayer` runtime при этом остается вполовину меньше по размеру.
+`@intlayer/vue-i18n` изменяет то, к чему привязан `useI18n()`: от глобального экземпляра, содержащего все сообщения каждой локали, к словарю, скомпилированному для этого компонента. На том же приложении Vite + Vue 3 это дает **88 KB меньше на странице**, **runtime в 3 раза меньше**, **компоненты в 23 раза меньше** и **0% утечек страницы**, при этом требуя только файл конфигурации, одну строку плагина и одно удаленное импортирование. SFC блоки `<i18n>` и загрузка сообщений во время выполнения, это две вещи, которые он не поддерживает, и native `vue-intlayer` runtime при этом остается вполовину меньше по размеру.
 
 Все исходные данные, тестовые приложения и сценарии находятся в [репозитории Benchmark Bloom](https://github.com/intlayer-org/benchmark-bloom). Запустите его самостоятельно.
 
-Обратитесь к документации ['Почему Intlayer?'](https://intlayer.org/doc/why) для получения дополнительной информации.
+Обратитесь к документации ['Почему Intlayer?'](https://intlayer.org/ru/doc/why) для получения дополнительной информации.