Composables

useLocale

Возвращает текущую локаль, функцию переключения, флаг загрузки и метаданные активной локали.

import { useLocale } from 'vue-i18n-kit'

const { locale, setLocale, isLoading, localeMeta } = useLocale()

Возвращаемое значение	Тип	Описание
locale	Ref<string>	Код текущей активной локали (реактивный).
setLocale	(lang: string) => Promise<void>	Переключиться на другую локаль. Ленивая загрузка JSON при необходимости, затем обновляет locale. Бросает исключение, если lang не зарегистрирован.
isLoading	Ref<boolean>	true, пока идёт загрузка JSON локали.
localeMeta	ComputedRef<Record<string, unknown> | undefined>	Метаданные активной локали из её LocaleDefinition.meta. Обновляются реактивно при переключении локали.

Передайте generic-тип, чтобы получить типизированный localeMeta без ручного приведения типов:

interface AppLocaleMeta {
  display: string
  flag: string
  author?: string
}

const { localeMeta } = useLocale<AppLocaleMeta>()
localeMeta.value?.display // string | undefined — полностью типизировано

Пример — переключатель локали:

<script setup lang="ts">
import { useLocale, useAvailableLocales } from 'vue-i18n-kit'

const { locale, setLocale, isLoading, localeMeta } = useLocale()
const { availableLocales } = useAvailableLocales()

async function handleChange(code: string) {
  try {
    await setLocale(code)
  } catch (err) {
    console.error('Failed to load locale:', err)
  }
}
</script>

<template>
  <span>{{ localeMeta?.flag }} {{ localeMeta?.display ?? locale }}</span>

  <select :value="locale" @change="handleChange(($event.target as HTMLSelectElement).value)">
    <option v-for="loc in availableLocales" :key="loc.code" :value="loc.code">
      {{ loc.meta?.flag }} {{ loc.meta?.display ?? loc.code }}
    </option>
  </select>

  <span v-if="isLoading">Loading…</span>
</template>

useT

Основной composable для перевода. Возвращает два метода — t для простых строк и tm для ICU-плюрализованных строк. Оба реактивны к локали и обновляются автоматически при смене активной локали.

import { useT } from 'vue-i18n-kit'

const { t, tm } = useT()

t(key, vars?)

Ищет ключ в файле активной локали и интерполирует именованные плейсхолдеры {placeholder}.

t('buttons.submit') // → 'Submit'
t('greeting', { name: 'Alice' }) // → 'Hello, Alice!'

Аргумент	Тип	Описание
key	string	Путь через точку в файле локали ('buttons.submit', 'greeting').
vars	object	Опционально. Именованные значения, подставляемые в плейсхолдеры {placeholder}.

tm(key, vars)

Ищет ключ, значение которого является ICU-шаблоном множественного числа, затем выбирает правильную форму множественного числа с помощью Intl.PluralRules для активной локали.

tm('items', { count: 1 }) // → '1 item'
tm('items', { count: 5 }) // → '5 items'
tm('balance', { points: 3 }) // → '3 рубля'
tm('balance', { points: 11 }) // → '11 рублей'

Синтаксис ICU-шаблона:

Конструкция	Описание
{varName, plural, …}	Селектор формы множественного числа. varName должен быть ключом в vars; его числовое значение определяет CLDR-категорию.
one {…} few {…} many {…} other {…}	Форма для каждой CLDR-категории. other обязательна — используется как запасной вариант.
# внутри формы	Заменяется числовым значением переменной.
{varName} вне plural	Простая интерполяция — заменяется на vars.varName.

Примеры:

// Отображение + множественное число в одном шаблоне
tm('balance', { points: 21 })
// locale: "{points} {points, plural, one {рубль} few {рубля} many {рублей} other {рублей}}"
// → '21 рубль'

// Несколько переменных
tm('score', { user: 'Даня', score: 21 })
// locale: "{user} набрал {score} {score, plural, one {балл} few {балла} many {баллов} other {баллов}}"
// → 'Даня набрал 21 балл'

// Несколько конструкций plural в одной строке
tm('report', { files: 2, errors: 5 })
// → '2 файла (5 ошибок)'

CLDR-категории по языкам:

Язык	Используемые категории
Английский, турецкий	one, other
Русский, польский	one, few, many, other
Арабский	zero, one, two, few, many, other
Японский, китайский	other (грамматической категории множественности нет)

Полные правила: CLDR Plural Rules

useAvailableLocales

Возвращает вычисляемый список всех локалей, зарегистрированных в конфигурации плагина. Каждый элемент — объект LocaleInfo, содержащий код локали и её метаданные.

import { useAvailableLocales } from 'vue-i18n-kit'

const { availableLocales } = useAvailableLocales()
// availableLocales.value →
// [
//   { code: 'en', meta: { display: 'English', flag: '🇬🇧' } },
//   { code: 'ru', meta: { display: 'Русский', flag: '🇷🇺' } },
// ]

Возвращаемое значение	Тип	Описание
availableLocales	ComputedRef<LocaleInfo[]>	Все локали в порядке объявления. У каждого элемента есть code: string и meta: TMeta | undefined.

Передайте generic-тип, чтобы получить типизированный meta без приведения типов:

interface AppLocaleMeta {
  display: string
  flag: string
}

const { availableLocales } = useAvailableLocales<AppLocaleMeta>()
availableLocales.value[0].meta?.display // string | undefined

useFormat

Предоставляет локале-зависимое форматирование через нативные API Intl. Все форматтеры автоматически используют текущую активную локаль и обновляются при её переключении.

import { useFormat } from 'vue-i18n-kit'

const { formatDate, formatNumber, formatCurrency } = useFormat()

formatDate(value, options?)

// value: Date | number (timestamp) | string (ISO)
// options: Intl.DateTimeFormatOptions

formatDate(new Date()) // '28.03.2026'  (ru)
formatDate(new Date(), { dateStyle: 'long' }) // '28 марта 2026 г.'  (ru)
formatDate(new Date(), { dateStyle: 'long' }) // 'March 28, 2026'  (en)
formatDate(new Date(), { hour: '2-digit', minute: '2-digit' }) // '19:45'

formatNumber(value, options?)

formatNumber(1_234_567.89) // '1 234 567,89'  (ru)
formatNumber(1_234_567.89) // '1,234,567.89'  (en)
formatNumber(0.42, { style: 'percent' }) // '42 %'

formatCurrency(value, currency, options?)

// currency: ISO 4217 код (USD, EUR, RUB, ...)

formatCurrency(1999.99, 'USD') // '$1,999.99'   (en)
formatCurrency(1999.99, 'EUR') // '1 999,99 €'  (ru)
formatCurrency(1999, 'USD', { minimumFractionDigits: 0 }) // '$1,999'

usePluralize

Для ICU-плюрализации используйте tm() из useT() — это основной API. usePluralize предоставляет одну дополнительную утилиту: pluralCategory, которая возвращает сырую CLDR-категорию для числового значения.

import { usePluralize } from 'vue-i18n-kit'

const { pluralCategory } = usePluralize()

pluralCategory(count)

Возвращает строку сырой CLDR-категории множественного числа для count в активной локали. Полезно для применения CSS-классов или условного рендеринга.

// Английская локаль
pluralCategory(1) // 'one'
pluralCategory(5) // 'other'

// Русская локаль
pluralCategory(1) // 'one'
pluralCategory(3) // 'few'
pluralCategory(5) // 'many'