useLocale

The useLocale composable provides comprehensive internationalization (i18n) capabilities, allowing you to manage multiple locales, switch between them dynamically, and translate messages with variable replacement and message linking. Built on createSingle for single-locale selection and supports custom adapters for integration with different i18n libraries.

Copy Page as Markdown

Intermediate97.9% coverageJan 11, 2026

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:

UseLocale

<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:

API Reference

The following API details are for the useLocale composable.

Functions

createLocale

(_options?: LocaleOptions<TokenCollection>) => R

Creates a new locale instance.

createLocaleFallback

() => R

createLocaleContext

(_options?: LocaleContextOptions) => ContextTrinity<R>

Creates a new locale context.

createLocalePlugin

(_options?: LocalePluginOptions) => any

Creates a new locale plugin.

useLocale

(namespace?: string) => R

Returns the current locale instance.

Options

events

boolean

Enable event emission for registry operations

Default: false

reactive

boolean

Enable reactive behavior for registry operations

Default: false

disabled

MaybeRefOrGetter<boolean>

When true, the entire selection instance is disabled.

enroll

MaybeRefOrGetter<boolean>

When true, newly registered items are automatically selected if not disabled. Useful for pre-selecting items in multi-select scenarios.

mandatory

MaybeRefOrGetter<boolean | "force">

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

multiple

MaybeRefOrGetter<boolean>

When true, treats the selection as an array

adapter

LocaleAdapter

default

ID

fallback

ID

messages

Record<ID, Z>

Properties

collection

ReadonlyMap<ID, Z>

The collection of tickets in the registry

size

number

The number of tickets in the registry

selectedIds

Reactive<Set<ID>>

Set of selected ticket IDs

selectedItems

ComputedRef<Set<E>>

Set of selected ticket instances

selectedValues

ComputedRef<Set<unknown>>

Set of selected ticket values

disabled

MaybeRef<boolean>

Disable state for the entire selection instance

selectedId

ComputedRef<any>

selectedIndex

ComputedRef<number>

selectedItem

ComputedRef<E>

selectedValue

ComputedRef<E["value"]>

Methods

clear

() => void

Clear the entire registry

has

(id: ID) => boolean

Check if a ticket exists by ID

keys

() => ID[]

Get all registered IDs

browse

(value: unknown) => ID[] | undefined

Browse for an ID(s) by value

lookup

(index: number) => ID | undefined

lookup a ticket by index number

get

(id: ID) => Z | undefined

Get a ticket by ID

upsert

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

Update or insert a ticket by ID

values

() => Z[]

Get all values of registered tickets

entries

() => [ID, Z][]

Get all entries of registered tickets

unregister

(id: ID) => void

Unregister an ticket by ID

reindex

() => void

Reset the index directory and update all tickets

seek

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

Seek for a ticket based on direction and optional predicate

on

(event: string, cb: RegistryEventCallback) => void

Listen for registry events

off

(event: string, cb: RegistryEventCallback) => void

Stop listening for registry events

emit

(event: string, data: unknown) => 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

Clear all selected IDs and reindexes

select

(id: ID) => void

Select a ticket by ID (Toggle ON)

unselect

(id: ID) => void

Unselect a ticket by ID (Toggle OFF)

toggle

(id: ID) => void

Toggles a ticket ON and OFF by ID

selected

(id: ID) => boolean

Check if a ticket is selected by ID

mandate

() => void

Mandates selected ID based on "mandatory" Option

onboard

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

Onboard multiple tickets at once

t

(key: string, params?: Record<string, unknown>, fallback?: string) => string

Translate a message key with optional parameters and fallback.

n

(value: number) => string

register

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