Composables

Composition API for Nuxt i18n module.

useLocalePath

The useLocalePath composable returns a function that resolves a path according to the current locale. useLocalePath is powered by vue-i18n-routing.

Example:

<script setup>
const localePath = useLocalePath()
</script>

<template>
  <NuxtLink :to="localePath('index')">{{ $t('home') }}</NuxtLink>
</template>

Type

declare function useLocalePath(options?: I18nCommonRoutingOptionsWithComposable): (route: RawLocation | RouteLocation, locale?: Locale) => string;

useLocaleRoute

The useLocaleRoute composable returns a function that resolves the route according to the current locale. useLocaleRoute is powered by vue-i18n-routing.

Example:

<script setup>
const localeRoute = useLocaleRoute()
const { locale } = useI18n()
const linkPath = computed(() => {
  const route = localeRoute('blog', locale.value)
  return route != null ? route.path : '/'
})
</script>

<template>
  <NuxtLink :to="linkPath">{{ $t('blog') }}</NuxtLink>
</template>

Type

declare function useLocaleRoute(options?: I18nCommonRoutingOptionsWithComposable): (route: RawLocation | RouteLocation, locale?: Locale) => Route | RouteLocation & { href: string; } | undefined;

useSwitchLocalePath

The useSwitchLocalePath composable returns a function that allows to switch the locale. useSwitchLocalePath is powered by vue-i18n-routing.

Example:

<script setup>
const switchLocalePath = useSwitchLocalePath()
</script>

<template>
  <NuxtLink :to="switchLocalePath('en')">English</NuxtLink>
  <NuxtLink :to="switchLocalePath('fr')">Français</NuxtLink>
</template>

Type

declare function useSwitchLocalePath(options?: I18nCommonRoutingOptionsWithComposable): (locale?: Locale) => string;

useLocaleHead

The useLocaleHead composable returns localized head properties for locale-related aspects. useLocaleHead is powered by vue-i18n-routing.

Example:

<script setup>
const i18nHead = useLocaleHead({
  addSeoAttributes: {
    canonicalQueries: ['foo']
  }
})
useHead({
  htmlAttrs: {
    lang: i18nHead.value.htmlAttrs!.lang
  },
  link: [...(i18nHead.value.link || [])],
  meta: [...(i18nHead.value.meta || [])]
})
</script>

Type

declare function useLocaleHead(options: I18nHeadOptions): Ref<I18nHeadMetaInfo>;

Parameters

options

An object accepting the following optional fields:

• addDirAttribute
  Type: Boolean
  Adds a dir attribute to the HTML element. default false.
• addSeoAttributes
  Type: boolean | SeoAttributesOptions
  Adds various SEO attributes. default false.
• identifierAttribute
  Type: String
  Identifier attribute of <meta> tag, default 'hid'.

useRouteBaseName

The useRouteBaseName composable returns a function that gets the route's base name. useRouteBaseName is powered by vue-i18n-routing.

Example:

<script setup>
const route = useRoute()
const getRouteBaseName = useRouteBaseName()
const baseRouteName = computed(() => {
  return getRouteBaseName(route)
})
</script>

<template>
  <p>route base name: {{ baseRouteName }}
</template>

Type

declare function useRouteBaseName(options?: I18nCommonRoutingOptionsWithComposable): (givenRoute?: Route | RouteLocationNormalizedLoaded) => string | undefined;

useBrowserLocale

The useBrowserLocale composable returns the browser locale.

If this composable function is called on client-side, it detects the locale from the value of navigator.languages.

Else on the server side, the locale is detected from the value of accept-language header.

Type

declare function useBrowserLocale(): string | null;

useCookieLocale

The useCookieLocale composable returns the cookie locale.

If this composable function is called on client-side, it detects the locale from the value of document.cookie via useCookie. else on the server side, the locale is detected from the value of cookie header.

Note that if the value of detectBrowserLanguage.useCookie is false, an empty string is always returned.

Type

declare function useCookieLocale(): Ref<string>;

defineI18nConfig

The defineI18nConfig defines a composable function to vue-i18n configuration.

This function is used to pass the createI18n options on nuxt i18n module.

For more details about configuration, see the Vue I18n documentation.

You need return vue-i18n options object that will be resolved by Promise.

Type

export function defineI18nConfig<Config extends I18nOptions>(loader: () => Config | Promise<Config>): () => Config | Promise<Config>;

for example, define simple vue-i18n options object:

export default defineI18nConfig(() => ({
  legacy: false,
  locale: 'en',
  messages: {
    en: {
      welcome: 'Welcome'
    },
    fr: {
      welcome: 'Bienvenue'
    }
  }
}))

Parameters

loader

A function that is the vue-i18n optionss loading.

defineI18nLocale

The defineI18nLocale defines a composable function to dynamically load locale messages.

This function is used to dynamically load a locale with lazy-load translations.

You can use at JavaScript and TypeScript extension formats.

You need return locale messags object that will be resolved by Promise.

Type

declare function defineI18nLocale<Messages = LocaleMessages<DefineLocaleMessage>, Locales = Locale>(loader: (locale: Locales) => Messages | Promise<Messages>): (locale: Locales) => Messages | Promise<Messages>;

for example, locale loading with fetch:

export default defineI18nLocale(locale => {
  return $fetch(`https://your-company-product/api/${locale}`)
})

Parameters

loader

A function that is the dynamic locale messages loading, that has the following parameters:

• locale
  Type: Locale
  A target locale that is passed from nuxt i18n module. That is passed when the locale is switched in the following cases:
  • when you switch the locale with setLocale.
  • when the locale is switched with <NuxtLink>. for example, the route path resolved by useSwitchLocalePath or $switchLocalePath.