Skip to main content
Vuetify0 is now in alpha!
Vuetify0 Logo
Theme
Mode
Palettes
Accessibility
Vuetify One
Sign in to Vuetify One

Access premium tools across the Vuetify ecosystem — Bin, Play, Studio, and more.

Not a subscriber? See what's included

useLocale

Edit this page
Report a Bug
Open issues
View on GitHub
Copy Markdown
IntermediateApr 5, 2026

i18n plugin with message translation, number formatting, and locale switching.

Installation

Install the Locale plugin in your app’s entry point:

main.ts
import { createApp } from 'vue'
import { createLocalePlugin } from '@vuetify/v0'
import App from './App.vue'

const app = createApp(App)

app.use(
  createLocalePlugin({
    default: 'en',
    messages: {
      en: {
        hello: 'Hello',
        welcome: 'Welcome, {name}!',
      },
      es: {
        hello: 'Hola',
        welcome: '¡Bienvenido, {name}!',
      },
    },
  })
)

app.mount('#app')

Usage

Once the plugin is installed, use the useLocale composable in any component:

vue
<script setup lang="ts">
  import { useLocale } from '@vuetify/v0'

  const locale = useLocale()

  function changeLocale(id: string) {
    locale.select(id)
  }
</script>

<template>
  <div>
    <h1>{{ locale.t('hello') }}</h1>
    <p>{{ locale.t('welcome', { name: 'John' }) }}</p>

    <button @click="changeLocale('en')">English</button>
    <button @click="changeLocale('es')">Español</button>
    <button @click="changeLocale('fr')">Français</button>
  </div>
</template>

Architecture

useLocale extends createSingle for locale selection with message interpolation:

Locale Hierarchy

Use controls to zoom and pan. Click outside or press Escape to close.

Locale Hierarchy

Reactivity

Locale selection is reactive via createSingle. Translation methods return static strings.

PropertyReactiveNotes
selectedIdCurrent locale ID
selectedItemCurrent locale ticket
selectedValueCurrent locale value
selectedIndexIndex in registry

Examples

Locale Switcher

Switch between English, Spanish, and Japanese — translated strings, navigation items, and formatted numbers all update reactively.

welcome

greeting

items

status

nav.homenav.settingsnav.profile

Number format: 1234567.89

Adapters

Adapters let you swap the underlying i18n implementation without changing your application code.

AdapterImportDescription
Vuetify0LocaleAdapter@vuetify/v0Token-based translation with fallback chain (default)
VueI18nLocaleAdapter@vuetify/v0/locale/adapters/vue-i18nvue-i18n↗︎ v10+ integration

v0 (default)

The built-in Vuetify0LocaleAdapter is used when no adapter option is provided. It handles the full translation pipeline using the token registry:

  • Key lookup — resolves locale.t('key') against createTokens using the selected locale

  • Fallback chain — falls back to the fallback locale when a key is missing

  • Message linking — resolves token references like {nav.home} within messages, with circular reference protection

  • Placeholder interpolation — named ({name}) and positional ({0}) replacement

  • Number formatting — locale.n(value) delegates to Intl.NumberFormat with the selected locale

This is the adapter powering the Installation and Usage examples above — no extra configuration needed.

vue-i18n

Requires vue-i18n↗︎ v10+ (Composition API mode).

bash
pnpm add vue-i18n
src/plugins/zero.ts
import { createI18n } from 'vue-i18n'
import { VueI18nLocaleAdapter } from '@vuetify/v0/locale/adapters/vue-i18n'
import { createLocalePlugin } from '@vuetify/v0'

const i18n = createI18n({
  locale: 'en',
  messages: {
    en: { hello: 'Hello', welcome: 'Welcome, {name}!' },
    es: { hello: 'Hola', welcome: '¡Bienvenido, {name}!' },
  },
})

app.use(i18n)
app.use(
  createLocalePlugin({
    adapter: new VueI18nLocaleAdapter(i18n),
  })
)
Tip

When using the vue-i18n adapter, message storage and resolution are handled entirely by vue-i18n. The messages option on createLocalePlugin is not needed — all translations live in your vue-i18n instance.

Custom Adapters

Create custom adapters by implementing the LocaleAdapter interface:

src/adapters/custom-locale-adapter.ts
import type { LocaleAdapter } from '@vuetify/v0'

class MyLocaleAdapter implements LocaleAdapter {
  t (key: string, ...params: unknown[]): string {
    // Delegate to your i18n provider
    return myProvider.translate(key, params)
  }

  n (value: number): string {
    return new Intl.NumberFormat('en-US').format(value)
  }
}

// Use with plugin
app.use(
  createLocalePlugin({
    adapter: new MyLocaleAdapter(),
  })
)

Adapter Interface

The adapter pattern decouples translation from the underlying i18n library. When you call locale.t(), the request flows through the provided adapter:

Adapter Data Flow

Use controls to zoom and pan. Click outside or press Escape to close.

Adapter Data Flow
ts
interface LocaleAdapter {
  t: (key: string, ...params: unknown[]) => string
  n: (value: number) => string
}

API Reference

The following API details are for the useLocale composable.

Functions

createLocale

(_options?: LocaleOptions<TokenCollection>) => LocaleContext<LocaleTicketInput, LocaleTicket<LocaleTicketInput>>

Creates a new locale instance.

createLocaleFallback

() => LocaleContext<LocaleTicketInput, LocaleTicket<LocaleTicketInput>>

createLocaleContext

<_E>(_options?: LocalePluginOptions | undefined) => ContextTrinity<_E>

createLocalePlugin

(_options?: LocalePluginOptions | undefined) => Plugin

useLocale

<_E>(namespace?: string) => _E

Options

events

boolean | undefined

Enable event emission for registry operations

Default: false

reactive

boolean | undefined

Enable reactive behavior for registry operations

Default: false

disabled

MaybeRefOrGetter<boolean> | undefined

Disabled state for the entire model instance

Default: false

enroll

MaybeRefOrGetter<boolean> | undefined

Auto-select tickets on registration

Default: true

multiple

MaybeRefOrGetter<boolean> | undefined

Allow multiple tickets to be selected simultaneously

Default: false

mandatory

MaybeRefOrGetter<boolean | "force"> | undefined

Controls mandatory selection behavior: - `false` (default): No mandatory selection enforcement - `true`: Prevents deselecting the last selected item - `'force'`: Automatically selects the first non-disabled item on registration

adapter

LocaleAdapter | undefined

default

ID | undefined

fallback

ID | undefined

messages

Record<ID, Z> | undefined

Properties

collection

ReadonlyMap<ID, E>

The collection of tickets in the registry

size

number

The number of tickets in the registry

selectedIds

Reactive<Set<ID>>

Set of currently selected ticket IDs

selectedItems

ComputedRef<Set<E>>

Computed Set of selected ticket instances

selectedValues

ComputedRef<Set<E["value"] extends Ref<infer U, infer U> ? U : E["value"]>>

Computed Set of selected ticket values

disabled

MaybeRefOrGetter<boolean>

Disabled state for the entire model instance

multiple

MaybeRefOrGetter<boolean>

Whether the selection allows multiple selections

selectedId

ComputedRef<ID | undefined>

selectedIndex

ComputedRef<number>

selectedItem

ComputedRef<E | undefined>

selectedValue

ComputedRef<E["value"] | undefined>

Methods

clear

() => void

Clear the entire registry

has

(id: ID) => boolean

Check if a ticket exists by ID

keys

() => readonly ID[]

Get all registered IDs

browse

(value: E["value"]) => ID[] | undefined

Browse for an ID(s) by value

lookup

(index: number) => ID | undefined

lookup a ticket by index number

get

(id: ID) => E | undefined

Get a ticket by ID

upsert

(id: ID, ticket?: Partial<Z>, event?: string) => E

Update or insert a ticket by ID

values

() => readonly E[]

Get all values of registered tickets

entries

() => readonly [ID, E][]

Get all entries of registered tickets

unregister

(id: ID) => void

Unregister a ticket by ID

reindex

() => void

Reset the index directory and update all tickets

move

(id: ID, toIndex: number) => E | undefined

Seek for a ticket based on direction and optional predicate

seek

(direction?: "first" | "last", from?: number, predicate?: (ticket) => boolean) => E | undefined

on

<K extends Extensible<RegistryEventName>>(event: K, cb: EventHandler<E, K>) => void

Listen for registry events

off

<K extends Extensible<RegistryEventName>>(event: K, cb: EventHandler<E, K>) => void

Stop listening for registry events

emit

<K extends Extensible<RegistryEventName>>(event: K, data: EventPayload<E, K>) => void

Emit an event with data

dispose

() => void

Clears the registry and removes all listeners

offboard

(ids: ID[]) => void

Offboard multiple tickets at once

batch

<R>(fn: () => R) => R

Execute operations in a batch, deferring cache invalidation and event emission until complete

reset

() => void

Reset selection state without destroying the registry

select

(id: ID) => void

Select a ticket by ID

unselect

(id: ID) => void

Unselect a ticket by ID

toggle

(id: ID) => void

Toggle a ticket's selection state

selected

(id: ID) => boolean

Check if a ticket is currently selected

apply

(values: unknown[], options?: { multiple?) => void

Apply external values to the model

mandate

() => void

Mandate selected ID based on "mandatory" option

onboard

(registrations: Partial<Z>[]) => E[]

Onboard multiple tickets at once

t

(key: string, ...params: unknown[]) => string

Translate a message key with optional parameters.

n

(value: number) => string

register

(registration?: Partial<Z>) => E

Register a locale with optional messages. When `messages` is provided, flattens them to dot-notation tokens and onboards them into the token registry before registering the locale for selection.

Was this page helpful?
© 2016-1970 Vuetify, LLC
Ctrl+/