Composables

useLocale

Returns the current locale, a switcher function, a loading flag, and the active locale's metadata.

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

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

Return value	Type	Description
locale	Ref<string>	Currently active locale code (reactive).
setLocale	(lang: string) => Promise<void>	Switch to a different locale. Lazy-loads the JSON if needed, then updates locale. Throws if lang is not registered.
isLoading	Ref<boolean>	true while a locale's JSON is being fetched.
localeMeta	ComputedRef<Record<string, unknown> | undefined>	Metadata of the active locale from its LocaleDefinition.meta. Updates reactively on locale switch.

Pass a generic type for typed localeMeta without manual casting:

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

const { localeMeta } = useLocale<AppLocaleMeta>()
localeMeta.value?.display // string | undefined — fully typed

Example — locale switcher:

<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

The primary translation composable. Returns two methods — t for plain strings and tm for ICU-pluralized strings. Both are locale-reactive and update automatically when the active locale changes.

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

const { t, tm } = useT()

t(key, vars?)

Looks up a key in the active locale file and interpolates named {placeholder} tokens.

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

Argument	Type	Description
key	string	Dot-separated path in the locale file ('buttons.submit', 'greeting').
vars	object	Optional. Named values substituted into {placeholder} tokens.

tm(key, vars)

Looks up a key whose value is an ICU plural template, then selects the correct plural form using Intl.PluralRules for the active locale.

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

ICU template syntax:

Construct	Description
{varName, plural, …}	Plural form selector. varName must be a key in vars; its numeric value determines the CLDR category.
one {…} few {…} many {…} other {…}	Form for each CLDR category. other is required — used as fallback.
# inside a form	Replaced with the variable's numeric value.
{varName} outside plural	Simple interpolation — replaced with vars.varName.

Examples:

// Display + plural in one template
tm('balance', { points: 21 })
// locale: "{points} {points, plural, one {рубль} few {рубля} many {рублей} other {рублей}}"
// → '21 рубль'

// Multiple variables
tm('score', { user: 'Даня', score: 21 })
// locale: "{user} набрал {score} {score, plural, one {балл} few {балла} many {баллов} other {баллов}}"
// → 'Даня набрал 21 балл'

// Multiple plural constructs in one string
tm('report', { files: 2, errors: 5 })
// → '2 файла (5 ошибок)'

CLDR categories by language:

Language	Categories used
English, Turkish	one, other
Russian, Polish	one, few, many, other
Arabic	zero, one, two, few, many, other
Japanese, Chinese	other (no grammatical plural)

Full rules: CLDR Plural Rules

useAvailableLocales

Returns a computed list of all locales registered in the plugin config. Each item is a LocaleInfo object containing the locale code and its metadata.

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

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

Return value	Type	Description
availableLocales	ComputedRef<LocaleInfo[]>	All locales in declaration order. Each item has code: string and meta: TMeta | undefined.

Pass a generic type to get typed meta without casting:

interface AppLocaleMeta {
  display: string
  flag: string
}

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

useFormat

Provides locale-aware formatting using the native Intl APIs. All formatters automatically use the currently active locale and update when the locale is switched.

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 code (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

For ICU pluralization use tm() from useT() — it is the primary API. usePluralize exposes one additional utility: pluralCategory, which returns the raw CLDR category for a count value.

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

const { pluralCategory } = usePluralize()

pluralCategory(count)

Returns the raw CLDR plural category string for count in the active locale. Useful for applying CSS classes or driving conditional rendering.

// English locale
pluralCategory(1) // 'one'
pluralCategory(5) // 'other'

// Russian locale
pluralCategory(1) // 'one'
pluralCategory(3) // 'few'
pluralCategory(5) // 'many'