Skip to main content

​
Overview

The useLocale() composable provides access to Vuetify’s localization system, including translation functions, current locale management, and RTL (right-to-left) support.

​
Import

import { useLocale } from 'vuetify'

​
Signature

function useLocale(): LocaleInstance & RtlInstance

​
Return Value

Returns a combined LocaleInstance and RtlInstance object:

​
Locale Properties

​
name
string
The adapter name identifier
​
current
Ref<string>
Currently active locale code (e.g., ‘en’, ‘es’, ‘fr’)
​
fallback
Ref<string>
Fallback locale code when translation is not found
​
messages
Ref<LocaleMessages>
All available translation messages
interface LocaleMessages {
  [key: string]: LocaleMessages | string
}
​
decimalSeparator
ShallowRef<string>
Decimal separator character for the current locale

​
Translation Methods

​
t
(key: string, ...params: unknown[]) => string
Translate a message keyParameters:
  • key - Translation key (e.g., ‘close’, ‘dataIterator.rowsPerPageText’)
  • ...params - Optional parameters to interpolate into the translation
Returns: Translated string or the key if translation not found
​
n
(value: number) => string
Format a number according to current localeParameters:
  • value - Number to format
Returns: Formatted number string
​
provide
(props: LocaleOptions) => LocaleInstance
Create a scoped locale instance with custom options

​
RTL Properties

​
isRtl
Ref<boolean>
Whether the current locale uses right-to-left text direction
​
rtl
Ref<Record<string, boolean>>
RTL configuration for all locales
​
rtlClasses
Ref<string>
CSS class for current text direction (e.g., ‘v-locale—is-ltr’)

​
Locale Options

interface LocaleOptions {
  decimalSeparator?: string
  messages?: LocaleMessages
  locale?: string
  fallback?: string
  adapter?: LocaleInstance
}

​
RTL Languages

The following locales default to RTL:
  • ar - Arabic
  • fa - Persian/Farsi
  • he - Hebrew

​
Usage Examples

​
Basic Translation

<script setup>
import { useLocale } from 'vuetify'

const { t, current } = useLocale()
</script>

<template>
  <div>
    <h1>{{ t('welcome') }}</h1>
    <p>Current locale: {{ current }}</p>
    
    <v-btn>{{ t('close') }}</v-btn>
    <v-btn>{{ t('save') }}</v-btn>
  </div>
</template>

​
Change Locale

<script setup>
import { useLocale } from 'vuetify'

const { current, t } = useLocale()

function switchToSpanish() {
  current.value = 'es'
}

function switchToEnglish() {
  current.value = 'en'
}
</script>

<template>
  <div>
    <v-btn @click="switchToEnglish">English</v-btn>
    <v-btn @click="switchToSpanish">Español</v-btn>
    
    <h1>{{ t('greeting') }}</h1>
  </div>
</template>

​
RTL Support

<script setup>
import { useLocale } from 'vuetify'

const { isRtl, rtlClasses, current } = useLocale()

function toggleRtl() {
  current.value = isRtl.value ? 'en' : 'ar'
}
</script>

<template>
  <div :class="rtlClasses">
    <p>Is RTL: {{ isRtl }}</p>
    <v-btn @click="toggleRtl">
      Switch to {{ isRtl ? 'LTR' : 'RTL' }}
    </v-btn>
  </div>
</template>

​
Number Formatting

<script setup>
import { useLocale } from 'vuetify'

const { n, current } = useLocale()

const price = 1234.56
</script>

<template>
  <div>
    <p>Price: {{ n(price) }}</p>
    <p>Locale: {{ current }}</p>
  </div>
</template>

​
Custom Messages

<script setup>
import { useLocale } from 'vuetify'

const locale = useLocale()

// Add custom translations
locale.messages.value = {
  en: {
    welcome: 'Welcome',
    goodbye: 'Goodbye',
    greeting: 'Hello, {name}!'
  },
  es: {
    welcome: 'Bienvenido',
    goodbye: 'Adiós',
    greeting: '¡Hola, {name}!'
  }
}
</script>

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

​
Locale Selector

<script setup>
import { useLocale } from 'vuetify'
import { ref } from 'vue'

const { current, t } = useLocale()

const locales = [
  { code: 'en', label: 'English' },
  { code: 'es', label: 'Español' },
  { code: 'fr', label: 'Français' },
  { code: 'de', label: 'Deutsch' },
  { code: 'ar', label: 'العربية' },
]
</script>

<template>
  <v-select
    v-model="current"
    :items="locales"
    item-title="label"
    item-value="code"
    :label="t('selectLanguage')"
  />
</template>

​
Fallback Locale

<script setup>
import { useLocale } from 'vuetify'

const { t, fallback } = useLocale()

// Set fallback to English
fallback.value = 'en'

// If a translation isn't found in current locale,
// it will fall back to English
</script>

<template>
  <div>
    <p>{{ t('someKey') }}</p>
  </div>
</template>

​
Built-in Translation Keys

Vuetify components use these translation keys:
  • close - Close button text
  • dataIterator.rowsPerPageText - Data table rows per page
  • dataIterator.pageText - Data table page text
  • noDataText - No data available message
  • carousel.prev - Carousel previous button
  • carousel.next - Carousel next button
  • calendar.today - Calendar today button
  • And many more…

​
Notes

  • Must be called within a component setup function or composable
  • Throws an error if the Vuetify locale provider is not found
  • Locale changes are reactive and will update all dependent components
  • RTL is automatically applied based on current locale
  • Custom locale adapters can be provided for integration with i18n libraries

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us