Skip to main content

i18n Vue: полная настройка интернационализации с vue-i18n

От установки до рабочей среды: настройте vue-i18n с Composition API, обработайте формы множественного числа по правилам CLDR, используйте интерполяцию компонентов и добавьте умные цепочки резервных локалей.

1

Установить vue-i18n

vue-i18n — официальный плагин интернационализации Vue.js. Он предоставляет реактивные переводы, множественное число в стиле ICU, интерполяцию компонентов, форматирование даты и времени и чисел, а также поддерживает Options API и Composition API.

Terminal
npm install vue-i18n@9
2

Настроить vue-i18n

Создайте экземпляр i18n с помощью createI18n() и зарегистрируйте его как плагин Vue. Определите сообщения локалей, задайте стандартную и резервную локали. vue-i18n поддерживает режимы legacy (Options API) и composition (Composition API).

src/i18n.ts
// src/i18n.ts
import { createI18n } from 'vue-i18n'
import en from './locales/en.json'
import de from './locales/de.json'

const i18n = createI18n({
  legacy: false,           // Use Composition API mode
  locale: 'en',            // Default locale
  fallbackLocale: 'en',   // Fallback locale
  messages: { en, de },
})

export default i18n
src/main.ts
// src/main.ts
import { createApp } from 'vue'
import App from './App.vue'
import i18n from './i18n'

const app = createApp(App)
app.use(i18n)
app.mount('#app')
Ошибки 'Not available in legacy mode' означают, что Вы смешиваете вызовы i18n Composition API (useI18n()) с конфигурацией режима legacy. Задайте legacy: false в createI18n(), чтобы использовать Composition API, либо последовательно применяйте синтаксис $t() из Options API.
3

Использовать переводы в шаблонах

vue-i18n предоставляет функцию $t() в шаблонах (Options API) и функцию t() из useI18n() (Composition API). Обе принимают ключ перевода и необязательные именованные или списковые параметры для интерполяции.

src/locales/en.json
// src/locales/en.json
{
  "nav": {
    "home": "Home",
    "about": "About",
    "settings": "Settings"
  },
  "greeting": "Hello, {name}!",
  "cart": {
    "itemCount": "no items | one item | {count} items"
  }
}

// src/locales/de.json
{
  "nav": {
    "home": "Startseite",
    "about": "Über uns",
    "settings": "Einstellungen"
  },
  "greeting": "Hallo, {name}!",
  "cart": {
    "itemCount": "keine Artikel | ein Artikel | {count} Artikel"
  }
}
4

Обработать формы множественного числа

vue-i18n поддерживает формы множественного числа через варианты с вертикальной чертой и функцию $tc() в режиме legacy либо t() с параметром count в Composition API. Определите формы в сообщениях локали с помощью разделителя: 'no items | one item | {count} items'.

MyComponent.vue
<template>
  <div>
    <!-- Simple translation -->
    <h1>{{ $t('nav.home') }}</h1>

    <!-- With variables -->
    <p>{{ $t('greeting', { name: userName }) }}</p>

    <!-- In attributes -->
    <input :placeholder="$t('nav.settings')" />

    <!-- Composition API -->
    <p>{{ greeting }}</p>
  </div>
</template>

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

const { t } = useI18n()
const userName = 'Alice'
const greeting = t('greeting', { name: userName })
</script>
Синтаксис с вертикальной чертой поддерживает только количественное множественное число максимум с тремя формами (zero | one | other). Для языков со сложными правилами CLDR, таких как арабский, русский и польский, используйте ICU MessageFormat или модификатор @.plural с явным сопоставлением категорий CLDR.
5

Добавить цепочки резервных локалей

Встроенный fallbackLocale в vue-i18n поддерживает только плоский список резервных локалей, а не отдельные цепочки. Пользователь pt-BR при отсутствии ключа переходит на английский вместо pt-PT. vue-i18n-locale-chain добавляет настраиваемые цепочки глубокого объединения, чтобы региональные пользователи всегда видели ближайший доступный перевод.

Plurals.vue
<template>
  <div>
    <!-- Pipe-separated plurals -->
    <p>{{ $t('cart.itemCount', count) }}</p>

    <!-- Named plurals (recommended for complex languages) -->
    <p>{{ $t('orders', { n: orderCount }) }}</p>
  </div>
</template>

<!-- In your locale file: -->
<!-- "orders": "{n} order | {n} orders" -->
vue-i18n-locale-chain глубоко объединяет сообщения при загрузке. Объединённый набор кешируется системой реактивности vue-i18n, поэтому резервные поиски не снижают производительность во время выполнения.
6

Автоматизировать перевод

После настройки vue-i18n переведите файлы локалей JSON с помощью ИИ. Попросите ИИ-помощника перевести исходный файл из IDE или интегрируйте перевод в конвейер CI/CD для полностью автоматизированной локализации.

LanguageSwitcher.vue
<template>
  <select v-model="locale">
    <option v-for="lang in availableLocales" :key="lang" :value="lang">
      {{ lang }}
    </option>
  </select>
</template>

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

const { locale, availableLocales } = useI18n()
</script>
src/i18n.ts (lazy loading)
// src/i18n.ts
import { createI18n } from 'vue-i18n'

const i18n = createI18n({
  legacy: false,
  locale: 'en',
  fallbackLocale: 'en',
  messages: {},
})

export async function loadLocale(locale: string) {
  const messages = await import(`./locales/${locale}.json`)
  i18n.global.setLocaleMessage(locale, messages.default)
  i18n.global.locale.value = locale
}

export default i18n
7

Конфигурация цепочки резервных локалей

Настройте отдельные резервные цепочки для локалей, чтобы региональные пользователи видели ближайший доступный перевод вместо немедленного перехода на английский. vue-i18n поддерживает объектный fallbackLocale для определения цепочек каждой локали.

src/i18n.ts
// src/i18n.ts
import { createI18n } from 'vue-i18n'

const i18n = createI18n({
  legacy: false,
  locale: 'pt-BR',
  fallbackLocale: {
    'pt-BR': ['pt', 'en'],
    'zh-Hant-TW': ['zh-Hant', 'zh', 'en'],
    'es-419': ['es', 'en'],
    default: ['en'],
  },
  messages: {
    en: { /* ... */ },
    pt: { /* ... */ },
    'pt-BR': { /* ... */ },
  },
})
Объект fallbackLocale позволяет определять разные цепочки для разных локалей. Пользователь pt-BR переходит на pt, затем en, а пользователь zh-Hant-TW — на zh-Hant, zh и en.

Распространённые ошибки

Смешение режимов Legacy и Composition API

Использование useI18n() с legacy: true, заданным по умолчанию, вызывает ошибки. Задайте legacy: false в createI18n() для Composition API либо используйте только $t() в шаблонах с Options API. Не смешивайте оба режима в одном приложении.

Использование v-html для переведённых строк

Отрисовка переводов с HTML через v-html создаёт риск XSS, если значения интерполяции поступают от пользователя. Для переводов со встроенным HTML или компонентами Vue используйте &lt;i18n-t&gt;: он безопасен по умолчанию и поддерживает реактивное встраивание компонентов.

Региональные пользователи видят английский вместо родительской локали

fallbackLocale в vue-i18n — плоский список, а не отдельная цепочка каждой локали. pt-BR переходит на указанное в списке значение, обычно 'en', полностью пропуская pt-PT. Используйте vue-i18n-locale-chain для правильного регионального резервного механизма с глубоким объединением.

Попробовать i18n Agent

Перетащите сюда файл перевода

JSON, YAML, PO, XML, CSV, Markdown, Properties

или нажмите, чтобы выбрать

Целевые языки

Регистрация не требуетсяМгновенный расчёт

Частые вопросы об i18n Vue