i18n.md

i18n

The kit's built-in component strings (placeholders, ARIA labels, button text) are localized via a single context provider.

Default

Without a provider, all components use the Russian locale (ru). Component strings like Очистить, Поиск..., Готово come from there.

Switch to English

Wrap your app in UidLocaleProvider with the built-in en locale:

<script setup lang="ts">
import { UidLocaleProvider, en } from '@dskripchenko/ui'
</script>

<template>
  <UidLocaleProvider :locale="en">
    <App />
  </UidLocaleProvider>
</template>

That's it. All built-in strings (clear button, search placeholder, tour navigation, etc.) become English.

Built-in locales

import { ru, en } from '@dskripchenko/ui'

• ru — default. Russian.
• en — English.

Both implement the full UidLocale interface.

Partial overrides

You don't have to provide a full locale. The provider deep-merges your override on top of the default ru:

<UidLocaleProvider :locale="{ tour: { next: 'Forward', prev: 'Back' } }">
  <App />
</UidLocaleProvider>

Any keys you don't specify keep their ru values. Same for English:

<script setup lang="ts">
import { en } from '@dskripchenko/ui'
const locale = { ...en, tour: { ...en.tour, finish: 'All done!' } }
</script>

<template>
  <UidLocaleProvider :locale="locale">
    <App />
  </UidLocaleProvider>
</template>

Custom locale

Provide a full locale by implementing UidLocale:

import type { UidLocale } from '@dskripchenko/ui'

export const fr: UidLocale = {
  common: {
    clear: 'Effacer',
    close: 'Fermer',
    search: 'Rechercher...',
    confirm: 'Confirmer',
    cancel: 'Annuler',
    loading: 'Chargement...',
    noResults: 'Aucun résultat',
  },
  copy: { copy: 'Copier', copied: 'Copié' },
  select: { placeholder: 'Sélectionner...', noResults: 'Aucun résultat' },
  combobox: {
    placeholder: 'Commencez à taper...',
    noResults: 'Aucun résultat',
    create: (label) => `+ Créer "${label}"`,
  },
  datePicker: {
    placeholder: 'Choisir une date',
    months: ['Janvier', 'Février', 'Mars', /* … */],
    weekdaysShort: ['Lu', 'Ma', 'Me', 'Je', 'Ve', 'Sa', 'Di'],
    prevMonth: 'Mois précédent',
    nextMonth: 'Mois suivant',
  },
  // … see UidLocale type for full shape
}

Use it like the built-in ones:

<UidLocaleProvider :locale="fr">
  <App />
</UidLocaleProvider>

Reading the locale from your code

If you build a component on top of the kit and want to use the active locale:

<script setup lang="ts">
import { useLocale } from '@dskripchenko/ui'

const locale = useLocale()
</script>

<template>
  <span>{{ locale.common.clear }}</span>
</template>

useLocale() returns a ComputedRef<UidLocale> that auto-unwraps in the template.

Programmatic provide

If you need to provide the locale programmatically (e.g. switching languages with a dropdown):

<script setup lang="ts">
import { ref, computed } from 'vue'
import { provideLocale, ru, en } from '@dskripchenko/ui'

const lang = ref<'ru' | 'en'>('ru')
provideLocale(computed(() => (lang.value === 'ru' ? ru : en)))
</script>

<template>
  <select v-model="lang">
    <option value="ru">Русский</option>
    <option value="en">English</option>
  </select>
  <App />
</template>

Coverage

All component strings (placeholders, ARIA labels, button text) are localized through the provider. Components covered:

Select, Combobox, DatePicker, DateRangePicker, TimePicker, TreeSelect, NumberInput, TagsInput, FileUpload, Mention, BackTop, Tour, TreeView, Pagination, Modal, Drawer, Toast, Alert, Tag, Code, DescriptionList, ColorPicker, Cascader, Calendar, and others.

Per-prop overrides

Prop-level customizations still take precedence over the locale. For example, on UidSelect:

<UidSelect placeholder="Pick one of three..." :options="options" />

The placeholder prop wins over locale.select.placeholder. The locale only kicks in when the prop is omitted.

Locale shape

interface UidLocale {
  common: {
    clear: string
    close: string
    search: string
    confirm: string
    cancel: string
    loading: string
    noResults: string
  }
  copy: { copy: string; copied: string }
  select: { placeholder: string; noResults: string }
  combobox: { placeholder: string; noResults: string; create: (label: string) => string }
  datePicker: {
    placeholder: string
    months: readonly string[]
    weekdaysShort: readonly string[]
    prevMonth: string
    nextMonth: string
  }
  dateRangePicker: { placeholder: string; presetLast: (days: number) => string }
  timePicker: { placeholder: string; now: string; confirm: string }
  colorPicker: { placeholder: string }
  numberInput: { increment: (step: number | string) => string; decrement: (step: number | string) => string }
  tagsInput: { remove: (label: string) => string }
  treeView: { expand: string; collapse: string }
  treeSelect: { placeholder: string; removeTag: (label: string) => string }
  fileUpload: { primaryText: string; secondaryText: string; remove: (name: string) => string }
  backTop: { label: string }
  tour: { next: string; prev: string; finish: string; skip: string }
  rating: { label: (current: number, max: number) => string }
  mention: { noResults: string }
  modal: { close: string }
  drawer: { close: string }
  toast: { close: string }
  pagination: {
    first: string; prev: string; next: string; last: string
    page: (n: number) => string
    pageSize: (n: number) => string
  }
}

For partial overrides, use UidPartialLocale — every nested key becomes optional.