@intlayer/docs 5.7.8 → 5.8.0

package/blog/ru/vue-i18n_vs_intlayer.md

@@ -0,0 +1,268 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-08-23
+title: vue-i18n против Intlayer
+description: Сравнение vue-i18n и Intlayer для интернационализации (i18n) в приложениях Vue/Nuxt
+keywords:
+  - vue-i18n
+  - Intlayer
+  - Интернационализация
+  - i18n
+  - Блог
+  - Vue
+  - Nuxt
+  - JavaScript
+slugs:
+  - blog
+  - vue-i18n-vs-intlayer
+---
+
+# vue-i18n ПРОТИВ Intlayer | Интернационализация Vue (i18n)
+
+Это руководство сравнивает два популярных варианта i18n для **Vue 3** (и **Nuxt**): **vue-i18n** и **Intlayer**.
+Мы сосредотачиваемся на современном инструментировании Vue (Vite, Composition API) и оцениваем:
+
+1. **Архитектуру и организацию контента**
+2. **TypeScript и безопасность**
+3. **Обработку отсутствующих переводов**
+4. **Маршрутизацию и стратегию URL**
+5. **Производительность и поведение загрузки**
+6. **Опыт разработчика (DX), инструменты и сопровождение**
+7. **SEO и масштабируемость для крупных проектов**
+
+> **кратко**: Оба решения могут локализовать приложения Vue. Если вам нужен **контент, ограниченный компонентом**, **строгие типы TypeScript**, **проверка отсутствующих ключей во время сборки**, **деревья сжатые словари**, а также **встроенные помощники для маршрутизации и SEO** плюс **Визуальный редактор и AI-переводы**, то **Intlayer** - более полный и современный выбор.
+
+---
+
+## Общее позиционирование
+
+- **vue-i18n** - де-факто библиотека i18n для Vue. Гибкое форматирование сообщений (стиль ICU), блоки SFC `<i18n>` для локальных сообщений и большая экосистема. Безопасность и масштабное сопровождение в основном на вашей стороне.
+- **Intlayer** - компонентно-ориентированная модель контента для Vue/Vite/Nuxt с **строгой типизацией TS**, **проверками во время сборки**, **деревьями сжатия**, **помощниками для маршрутизации и SEO**, опциональным **Визуальным редактором/CMS** и **AI-поддержкой переводов**.
+
+---
+
+## Сравнение функций бок о бок (с фокусом на Vue)
+
+| Функция                                                   | **Intlayer**                                                                           | **vue-i18n**                                                                                      |
+| --------------------------------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| **Переводы рядом с компонентами**                         | ✅ Да, контент расположен рядом с компонентом (например, `MyComp.content.ts`)          | ✅ Да, через SFC-блоки `<i18n>` (опционально)                                                     |
+| **Интеграция с TypeScript**                               | ✅ Продвинутая, автоматически сгенерированные **строгие** типы и автозаполнение ключей | ✅ Хорошая типизация; **строгая безопасность ключей требует дополнительной настройки/дисциплины** |
+| **Обнаружение отсутствующих переводов**                   | ✅ Предупреждения/ошибки во время сборки и отображение в TS                            | ⚠️ Запасные варианты и предупреждения во время выполнения                                         |
+| **Богатый контент (компоненты/Markdown)**                 | ✅ Прямая поддержка сложных узлов и файлов с содержимым Markdown                       | ⚠️ Ограничено (компоненты через `<i18n-t>`, Markdown через внешние плагины)                       |
+| **Перевод с использованием ИИ**                           | ✅ Встроенные рабочие процессы с использованием ваших ключей провайдера ИИ             | ❌ Не встроено                                                                                    |
+| **Визуальный редактор / CMS**                             | ✅ Бесплатный визуальный редактор и опциональная CMS                                   | ❌ Не встроено (используйте внешние платформы)                                                    |
+| **Локализованная маршрутизация**                          | ✅ Хелперы для Vue Router/Nuxt для генерации локализованных путей, URL и `hreflang`    | ⚠️ Не является ядром (используйте Nuxt i18n или кастомную настройку Vue Router)                   |
+| **Динамическая генерация маршрутов**                      | ✅ Да                                                                                  | ❌ Не предоставляется (предоставляется Nuxt i18n)                                                 |
+| **Плюрализация и форматирование**                         | ✅ Шаблоны перечислений; форматтеры на основе Intl                                     | ✅ Сообщения в стиле ICU; форматтеры Intl                                                         |
+| **Форматы контента**                                      | ✅ `.ts`, `.js`, `.json`, `.md`, `.txt` (YAML в разработке)                            | ✅ `.json`, `.js` (плюс SFC-блоки `<i18n>`)                                                       |
+| **Поддержка ICU**                                         | ⚠️ В разработке                                                                        | ✅ Да                                                                                             |
+| **SEO-хелперы (sitemap, robots, метаданные)**             | ✅ Встроенные хелперы (независимые от фреймворка)                                      | ❌ Не является ядром (Nuxt i18n/сообщество)                                                       |
+| **SSR/SSG**                                               | ✅ Работает с Vue SSR и Nuxt; не блокирует статическую генерацию                       | ✅ Работает с Vue SSR/Nuxt                                                                        |
+| **Tree-shaking (отгрузка только используемого контента)** | ✅ По компонентам во время сборки                                                      | ⚠️ Частично; требует ручного разделения кода/асинхронных сообщений                                |
+| **Ленивая загрузка**                                      | ✅ По локалям / по словарям                                                            | ✅ Поддержка асинхронных сообщений локалей                                                        |
+| **Удаление неиспользуемого контента**                     | ✅ Да (во время сборки)                                                                | ❌ Не встроено                                                                                    |
+| **Поддерживаемость крупных проектов**                     | ✅ Поощряет модульную структуру, удобную для дизайн-систем                             | ✅ Возможно, но требует строгой дисциплины в работе с файлами/пространствами имён                 |
+| **Экосистема / сообщество**                               | ⚠️ Меньше, но быстро растёт                                                            | ✅ Большое и зрелое в экосистеме Vue                                                              |
+
+---
+
+## Глубокое сравнение
+
+### 1) Архитектура и масштабируемость
+
+- **vue-i18n**: Обычно используется **централизованные каталоги** для каждой локали (опционально разделённые на файлы/пространства имён). Блоки SFC `<i18n>` позволяют использовать локальные сообщения, но по мере роста проектов команды часто возвращаются к общим каталогам.
+- **Intlayer**: Продвигает использование **словарей для каждого компонента**, хранящихся рядом с самим компонентом. Это снижает конфликты между командами, облегчает поиск контента и естественным образом ограничивает расхождение и неиспользуемые ключи.
+
+**Почему это важно:** В больших Vue-приложениях или дизайн-системах **модульный контент** масштабируется лучше, чем монолитные каталоги.
+
+---
+
+### 2) TypeScript и безопасность
+
+- **vue-i18n**: Хорошая поддержка TS; для **строгой типизации ключей** обычно требуются пользовательские схемы/дженерики и тщательные соглашения.
+- **Intlayer**: **Генерирует строгие типы** из вашего контента, обеспечивая **автодополнение в IDE** и **ошибки на этапе компиляции** для опечаток/отсутствующих ключей.
+
+**Почему это важно:** Строгая типизация выявляет ошибки **до** выполнения программы.
+
+---
+
+### 3) Обработка отсутствующих переводов
+
+- **vue-i18n**: **Время выполнения** - предупреждения/запасные варианты (например, fallback локаль или ключ).
+- **Intlayer**: **Время сборки** - обнаружение с предупреждениями/ошибками по локалям и ключам.
+
+**Почему это важно:** Контроль на этапе сборки поддерживает чистый и согласованный UI в продакшене.
+
+---
+
+### 4) Маршрутизация и стратегия URL (Vue Router/Nuxt)
+
+- **Обе** системы могут работать с локализованными маршрутами.
+- **Intlayer** предоставляет помощники для **генерации локализованных путей**, **управления префиксами локалей** и генерации **`<link rel="alternate" hreflang>`** для SEO. В Nuxt он дополняет маршрутизацию фреймворка.
+
+**Почему это важно:** Меньше пользовательских прослоек и **чище SEO** для разных локалей.
+
+---
+
+### 5) Производительность и поведение загрузки
+
+- **vue-i18n**: Поддерживает асинхронные сообщения локалей; избегать избыточного объединения бандлов - ваша задача (аккуратно разделяйте каталоги).
+- **Intlayer**: Выполняет **tree-shaking** на этапе сборки и **ленивую загрузку по словарю/локали**. Неиспользуемый контент не включается в сборку.
+
+**Почему это важно:** Меньшие бандлы и более быстрая загрузка для многоязычных Vue-приложений.
+
+---
+
+### 6) Опыт разработчика и инструменты
+
+- **vue-i18n**: Зрелая документация и сообщество; обычно вы будете полагаться на **внешние платформы локализации** для редакционных процессов.
+- **Intlayer**: В комплекте **бесплатный визуальный редактор**, опциональная **CMS** (дружелюбная к Git или внешняя), расширение для **VSCode**, утилиты **CLI/CI** и **переводы с помощью ИИ** с использованием ваших собственных ключей провайдера.
+
+**Почему это важно:** Меньше затрат на эксплуатацию и более короткий цикл разработка–контент.
+
+---
+
+### 7) SEO, SSR и SSG
+
+- **Обе** работают с Vue SSR и Nuxt.
+- **Intlayer**: Добавляет **SEO помощники** (карты сайта/метаданные/`hreflang`), которые не зависят от фреймворка и хорошо интегрируются с Vue/Nuxt сборками.
+
+**Почему это важно:** Международное SEO без сложных настроек.
+
+---
+
+## Почему Intlayer? (Проблема и подход)
+
+Большинство i18n стеков (включая **vue-i18n**) начинают с **централизованных каталогов**:
+
+```bash
+.
+├── locales
+│   ├── en.json
+│   ├── es.json
+│   └── fr.json
+└── src
+    └── components
+        └── MyComponent.vue
+```
+
+Или с папками для каждого языка:
+
+```bash
+.
+├── locales
+│   ├── en
+│   │  ├── footer.json
+│   │  └── navbar.json
+│   ├── fr
+│   │  ├── footer.json
+│   │  └── navbar.json
+│   └── es
+│      ├── footer.json
+│      └── navbar.json
+└── src
+    └── components
+        └── MyComponent.vue
+```
+
+Это часто замедляет разработку по мере роста приложений:
+
+1. **Для нового компонента** вы создаёте/редактируете удалённые каталоги, настраиваете пространства имён и переводите (часто вручную копируя/вставляя из AI-инструментов).
+2. **При изменении компонентов** вы ищете общие ключи, переводите, синхронизируете локали, удаляете неиспользуемые ключи и выравниваете структуры JSON.
+
+**Intlayer** ограничивает область видимости контента **на уровне компонента** и хранит его **рядом с кодом**, как мы уже делаем с CSS, историями, тестами и документацией:
+
+```bash
+.
+└── components
+    └── MyComponent
+        ├── MyComponent.content.ts
+        └── MyComponent.vue
+```
+
+**Объявление контента** (на компонент):
+
+```ts fileName="./components/MyComponent/MyComponent.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+const componentExampleContent = {
+  key: "component-example",
+  content: {
+    greeting: t({
+      en: "Hello World",
+      es: "Hola Mundo",
+      fr: "Bonjour le monde",
+    }),
+  },
+} satisfies Dictionary;
+
+export default componentExampleContent;
+```
+
+**Использование во Vue** (Composition API):
+
+```vue fileName="./components/MyComponent/MyComponent.vue"
+<script setup lang="ts">
+import { useIntlayer } from "vue-intlayer"; // Интеграция с Vue
+const { greeting } = useIntlayer("component-example");
+</script>
+
+<template>
+  <span>{{ greeting }}</span>
+</template>
+```
+
+Этот подход:
+
+- **Ускоряет разработку** (объявляйте один раз; автозаполнение в IDE/ИИ).
+- **Очищает кодовую базу** (1 компонент = 1 словарь).
+- **Облегчает дублирование/миграцию** (копируйте компонент вместе с его содержимым).
+- **Избегает "мертвых" ключей** (неиспользуемые компоненты не импортируют содержимое).
+- **Оптимизирует загрузку** (лениво загружаемые компоненты приносят с собой своё содержимое).
+
+---
+
+## Дополнительные возможности Intlayer (актуально для Vue)
+
+- **Поддержка нескольких фреймворков**: работает с Vue, Nuxt, Vite, React, Express и другими.
+- **Управление содержимым на базе JavaScript**: объявляйте в коде с полной гибкостью.
+- **Файл декларации для каждого локаля**: Задайте все локали и позвольте инструментам сгенерировать остальное.
+- **Типобезопасная среда**: Сильная конфигурация TypeScript с автодополнением.
+- **Упрощённый доступ к контенту**: Один хук/композабл для получения всего контента словаря.
+- **Организованная кодовая база**: 1 компонент = 1 словарь в одной папке.
+- **Расширенная маршрутизация**: Хелперы для локализованных путей и метаданных **Vue Router/Nuxt**.
+- **Поддержка Markdown**: Импорт удалённого/локального Markdown по локалям; доступ к frontmatter из кода.
+- **Бесплатный визуальный редактор и опциональная CMS**: Создание контента без платной платформы локализации; синхронизация, удобная для Git.
+- **Контент с поддержкой tree-shaking**: Поставляется только используемый контент; поддержка ленивой загрузки.
+- **Дружелюбность к статической генерации**: Не блокирует SSG.
+- **Переводы с поддержкой ИИ**: Переводите на 231 язык, используя собственного провайдера ИИ/ключ API.
+- **Сервер MCP и расширение VSCode**: Автоматизируйте рабочие процессы i18n и создание контента прямо в вашей IDE.
+- **Взаимодействие**: Интеграция с **vue-i18n**, **react-i18next** и **react-intl** при необходимости.
+
+---
+
+## Когда что выбирать?
+
+- **Выбирайте vue-i18n**, если хотите использовать **стандартный подход Vue**, вам удобно самостоятельно управлять каталогами/пространствами имён, и ваше приложение **маленькое или среднего размера** (или вы уже используете Nuxt i18n).
+- **Выбирайте Intlayer**, если для вас важны **контент, ограниченный компонентом**, **строгий TypeScript**, **гарантии на этапе сборки**, **tree-shaking** и **встроенные инструменты маршрутизации/SEO/редактирования** - особенно для **больших, модульных кодовых баз Vue/Nuxt**.
+
+---
+
+## Практические заметки по миграции (vue-i18n → Intlayer)
+
+- **Начинайте по функциям**: Переносите по одному маршруту/виду/компоненту за раз в локальные словари Intlayer.
+- **Промежуточный мост во время миграции**: Сохраняйте каталоги vue-i18n параллельно; постепенно заменяйте обращения к переводам.
+- **Включайте строгие проверки**: Позвольте обнаружению на этапе сборки выявлять отсутствующие ключи/локали на раннем этапе.
+- **Используйте помощники для роутера/SEO**: Стандартизируйте определение локали и теги `hreflang`.
+- **Измеряйте размеры бандлов**: Ожидайте **снижения размера бандла** за счёт исключения неиспользуемого контента.
+
+---
+
+## Заключение
+
+И **vue-i18n**, и **Intlayer** хорошо локализуют Vue-приложения. Разница в том, **сколько вам нужно построить самостоятельно**, чтобы получить надёжную и масштабируемую систему:
+
+- С **Intlayer** вы получаете **модульный контент**, **строгую типизацию TS**, **безопасность на этапе сборки**, **оптимизированные бандлы с tree-shaking**, а также **инструменты для роутера, SEO и редактора** прямо «из коробки».
+- Если ваша команда ставит в приоритет **поддерживаемость и скорость** в многоязычном приложении на Vue/Nuxt с компонентной архитектурой, Intlayer предлагает сегодня **самый полный** опыт.
+
+Обратитесь к документу ['Почему Intlayer?'](https://intlayer.org/doc/why) для получения дополнительной информации.

package/blog/zh/intlayer_with_next-i18next.md

@@ -1,6 +1,6 @@
 ---
-createdAt: 2024-08-11
-updatedAt: 2025-06-29
+createdAt: 2025-08-23
+updatedAt: 2025-08-23
 title: Intlayer和next-i18next
 description: 与Next.js应用程序的next-i18next集成Intlayer
 keywords:
@@ -24,7 +24,6 @@ both next-i18next 和 Intlayer 是为 Next.js 应用程序设计的开源国际
 这两种解决方案包括三个主要概念：
 
 1. **内容声明**：定义应用程序可翻译内容的方法。
-
    - 在 `i18next` 的情况下称为 `resource`，内容声明是一个结构化的 JSON 对象，包含一种或多种语言翻译的键值对。有关更多信息，请参阅 [i18next 文档](https://www.i18next.com/translation-function/essentials)。
    - 在 `Intlayer` 的情况下称为 `content declaration file`，内容声明可以是导出结构化数据的 JSON、JS 或 TS 文件。有关更多信息，请参阅 [Intlayer 文档](https://intlayer.org/fr/doc/concept/content)。
 
@@ -213,8 +212,8 @@ const content = {
   content: {
     myTranslatedContent: t({
       en: "Hello World",
-      fr: "Bonjour le monde",
       es: "Hola Mundo",
+      fr: "Bonjour le monde",
     }),
   },
 } satisfies Dictionary;
@@ -231,8 +230,8 @@ const content = {
   content: {
     myTranslatedContent: t({
       en: "Hello World",
-      fr: "Bonjour le monde",
       es: "Hola Mundo",
+      fr: "Bonjour le monde",
     }),
   },
 };
@@ -246,8 +245,8 @@ module.exports = {
   content: {
     myTranslatedContent: t({
       en: "Hello World",
-      fr: "Bonjour le monde",
       es: "Hola Mundo",
+      fr: "Bonjour le monde",
     }),
   },
 };

package/blog/zh/intlayer_with_next-intl.md

@@ -23,7 +23,6 @@ next-intl 和 Intlayer 是为 Next.js 应用程序设计的开源国际化 (i18n
 它们共享三个主要概念：
 
 1. **内容声明**: 定义应用程序可翻译内容的方法。
-
    - 在 Intlayer 中称为 `content declaration file`，可以是导出结构化数据的 JSON、JS 或 TS 文件。有关更多信息，请参见 [Intlayer 文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/concept/content.md)。
    - 在 next-intl 中称为 `messages` 或 `locale messages`，通常在 JSON 文件中。有关更多信息，请参见 [next-intl 文档](https://github.com/amannn/next-intl/blob/main/docs/zh/introduction.md)。
 
@@ -170,8 +169,8 @@ const content = {
   content: {
     helloWorld: t({
       en: "Hello World",
-      fr: "Bonjour le monde",
       es: "Hola Mundo",
+      fr: "Bonjour le monde",
     }),
   },
 } satisfies Dictionary;
@@ -188,8 +187,8 @@ const content = {
   content: {
     helloWorld: t({
       en: "Hello World",
-      fr: "Bonjour le monde",
       es: "Hola Mundo",
+      fr: "Bonjour le monde",
     }),
   },
 };
@@ -205,8 +204,8 @@ module.exports = {
   content: {
     helloWorld: t({
       en: "Hello World",
-      fr: "Bonjour le monde",
       es: "Hola Mundo",
+      fr: "Bonjour le monde",
     }),
   },
 };

package/blog/zh/intlayer_with_react-i18next.md

@@ -247,8 +247,8 @@ const content = {
     // 每个“t”调用是一个单独的翻译节点
     heading: t({
       en: "Hello World",
-      fr: "Bonjour le monde",
       es: "Hola Mundo",
+      fr: "Bonjour le monde",
     }),
     description: t({
       en: "My i18n description text...",

package/blog/zh/intlayer_with_react-intl.md

@@ -118,8 +118,8 @@ const content = {
     // 每次调用 t() 声明一个可翻译的字段
     helloWorld: t({
       en: "Hello World",
-      fr: "Bonjour le monde",
       es: "Hola Mundo",
+      fr: "Bonjour le monde",
     }),
     description: t({
       en: "This is a description",