π οΈ Methods β
π $getLocale
β
- Type:
() => string
- Description: Returns the current locale code.
- Example:
const locale = $getLocale()
// Output: 'en' (assuming the current locale is English)
π $getLocaleName
β
Version introduced: v1.28.0
- Type:
() => string | null
- Description: Returns the current locale name from displayName config.
- Example:
const locale = $getLocaleName()
// Output: 'English'
π $getLocales
β
- Type:
() => Array<{ code: string; iso?: string; dir?: string }>
- Description: Returns an array of all available locales configured in the module.
- Example:
const locales = $getLocales()
// Output: [{ code: 'en', iso: 'en-US', dir: 'ltr' }, { code: 'fr', iso: 'fr-FR', dir: 'ltr' }]
π $getRouteName
β
Version introduced: v1.28.0
- Type:
(route?: RouteLocationNormalizedLoaded | RouteLocationResolvedGeneric, locale?: string) => string
- Description: Retrieves the base route name without any locale-specific prefixes or suffixes.
- Parameters:
- route:
RouteLocationNormalizedLoaded | RouteLocationResolvedGeneric | undefined
β Optional. The route object from which to extract the name. - locale:
string | undefined
β Optional. The locale code to consider when extracting the route name.
- route:
- Example:
const routeName = $getRouteName(routeObject, 'fr')
// Output: 'index' (assuming the base route name is 'index')
π $t
β
Type:
(key: string, params?: Record<string, any>, defaultValue?: string) => string | number | boolean | Translations | PluralTranslations | unknown | null
Description: Fetches a translation for the given key. Optionally interpolates parameters.
Parameters:
- key:
string
β The translation key. - params:
Record<string, any> | undefined
β Optional. A record of key-value pairs to interpolate into the translation. - defaultValue:
string | undefined
β Optional. The default value to return if the translation is not found.
- key:
Example:
const welcomeMessage = $t('welcome', { username: 'Alice', unreadCount: 5 })
// Output: "Welcome, Alice! You have 5 unread messages."
π $ts
β
- Type:
(key: string, params?: Record<string, any>, defaultValue?: string) => string
- Description: A variant of
$t
that always returns a string. Fetches a translation for the given key and optionally interpolates parameters. - Parameters:
- key:
string
β The translation key. - params:
Record<string, any> | undefined
β Optional. A record of key-value pairs to interpolate into the translation. - defaultValue:
string | undefined
β Optional. The default value to return if the translation is not found.
- key:
- Example:
const welcomeMessage = $ts('welcome', { username: 'Alice', unreadCount: 5 })
// Output: "Welcome, Alice! You have 5 unread messages."
π’ $tc
β
- Type:
(key: string, count: number, defaultValue?: string) => string
- Description: Fetches a pluralized translation for the given key based on the count.
- Parameters:
- key:
string
β The translation key. - params:
number | Record<string, any>
β The count for pluralization or a record of key-value pairs with a 'count' property and additional values to interpolate into the translation. - defaultValue:
string | undefined
β Optional. The default value to return if the translation is not found.
- key:
- Example:
const appleCountMessage = $tc('apples', 10)
// Output: "10 apples" (assuming the plural rule for 'apples' is defined correctly)
π’ $tn
β
- Type:
(value: number, options?: Intl.NumberFormatOptions) => string
- Description: Formats a number according to the current locale using
Intl.NumberFormat
. - Parameters:
- value:
number
β The number to format. - options:
Intl.NumberFormatOptions | undefined
β Optional.Intl.NumberFormatOptions
to customize the formatting.
- value:
- Example:
const formattedNumber = $tn(1234567.89, { style: 'currency', currency: 'USD' })
// Output: "$1,234,567.89" in the 'en-US' locale
Use Cases: β
- Formatting numbers as currency, percentages, or decimals in the appropriate locale format.
- Customizing the number format using
Intl.NumberFormatOptions
such as currency, minimum fraction digits, etc.
π
$td
β
- Type:
(value: Date | number | string, options?: Intl.DateTimeFormatOptions) => string
- Description: Formats a date according to the current locale using
Intl.DateTimeFormat
. - Parameters:
- value:
Date | number | string
β The date to format, which can be aDate
object, a timestamp, or a date string. - options:
Intl.DateTimeFormatOptions | undefined
β Optional.Intl.DateTimeFormatOptions
to customize the formatting.
- value:
- Example:
const formattedDate = $td(new Date(), { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' })
// Output: "Friday, September 1, 2023" in the 'en-US' locale
Use Cases: β
- Displaying dates in a format that aligns with the user's locale, including long or short date formats.
- Customizing date output using options like weekday names, time formats, and timezone settings.
π $switchLocaleRoute
β
- Type:
(locale: string) => RouteLocationRaw
- Description: Return current route with the given locale
- Parameters:
- locale:
string
β Target locale.
- locale:
- Example:
// on /en/news
const routeFr = $switchLocaleRoute('fr')
// Output: A route object with the new locale applied, e.g., { name: 'localized-news', params: { locale: 'fr' } }
π $switchLocalePath
β
- Type:
(locale: string) => string
- Description: Return url of current route with the given locale
- Parameters:
- locale:
string
β Target locale.
- locale:
- Example:
// on /en/news
const routeFr = $switchLocalePath('fr')
window.location.href = routeFr
// Output: url with new locale applied, e.g., '/fr/nouvelles'
π $switchLocale
β
- Type:
(locale: string) => void
- Description: Switches to the given locale and redirects the user to the appropriate localized route.
- Parameters:
- locale:
string
β The locale to switch to.
- locale:
- Example:
$switchLocale('fr')
// Output: Redirects the user to the French version of the route
π $switchRoute
β
Version introduced: v1.27.0
- Type:
(route: RouteLocationNormalizedLoaded | RouteLocationResolvedGeneric | string, toLocale?: string) => void
- Description: Switches the route to a new specified destination and changes the locale if needed, redirecting the user to the appropriate localized route.
- Parameters:
- route:
RouteLocationNormalizedLoaded | RouteLocationResolvedGeneric | string
β The route to which you want to switch. It can be:- A
RouteLocationNormalizedLoaded
orRouteLocationResolvedGeneric
object. - A string representing the route path.
- A
- route:
- toLocale (optional):
string
β The locale to switch to for the target route. If not provided, the current locale is used.
Info: This method facilitates seamless switching between routes, accommodating the current locale configuration. Depending on the input, it resolves the intended route and determines the appropriate locale for redirecting the user to a localized route.
Examples:
String Path:
typescript// Switches to the given path with the current locale switchRoute('/about')
String Path with Locale:
typescript// Switches to the given path with French locale switchRoute('/about', 'fr')
Named Route:
typescript// Switches to a named route with the current locale switchRoute({ name: 'page' })
Named Route with Locale:
typescript// Switches to a named route and changes the locale to Spanish switchRoute({ name: 'page' }, 'es')
π $setI18nRouteParams
β
- Type:
(value: Record<LocaleCode, Record<string, string>> | null) => Record<LocaleCode, Record<string, string>> | null
- Description: set localized versions of params for all switchLocale* methods and returns passed value. MUST be called inside useAsyncData
- Parameters:
- value:
Record<LocaleCode, Record<string, string>> | null
β params of current route for other locale
- value:
- Example:
// in pages/news/[id].vue
// for en/news/1-first-article
const { $switchLocaleRoute, $setI18nRouteParams, $defineI18nRoute } = useI18n();
// OR
const { $switchLocaleRoute, $setI18nRouteParams, $defineI18nRoute } = useNuxtApp();
$defineI18nRoute({
localeRoutes: {
en: '/news/:id()',
fr: '/nouvelles/:id()',
de: '/Nachricht/:id()',
},
})
const { data: news } = await useAsyncData(`news-${params.id}`, async () => {
let response = await $fetch("/api/getNews", {
query: {
id: params.id,
},
});
if (response?.localeSlugs) {
response.localeSlugs = {
en: {
id: '1-first-article'
}
fr: {
id: '1-premier-article'
}
de: {
id: '1-erster-Artikel'
}
}
$setI18nRouteParams(response?.localeSlugs);
}
return response;
});
$switchLocalePath('fr') // === 'fr/nouvelles/1-premier-article'
$switchLocalePath('de') // === 'de/Nachricht/1-erster-Artikel'
π $localeRoute
β
- Type:
(to: RouteLocationRaw, locale?: string) => RouteLocationResolved
- Description: Generates a localized route object based on the target route.
- Parameters:
- to:
RouteLocationRaw
β The target route object. - locale:
string | undefined
β Optional. The locale for the generated route.
- to:
- Example:
const localizedRoute = $localeRoute({ name: 'index' })
// Output: A route object with the current locale applied, e.g., { name: 'index', params: { locale: 'fr' } }
π $localePath
β
- Type:
(to: RouteLocationRaw, locale?: string) => string
- Description: Return url based on the target route
- Parameters:
- to:
RouteLocationRaw
β The target route object. - locale:
string | undefined
β Optional. The locale for the generated route.
- to:
- Example:
const localizedRoute = $localeRoute({ name: 'news' })
// Output: url with new locale applied, e.g., '/en/nouvelles'
ποΈ $mergeTranslations
β
- Type:
(newTranslations: Record<string, string>) => void
- Description: Merges new translations into the existing translation cache for the current route and locale.
- Parameters:
- newTranslations:
Record<string, string>
β The new translations to merge.
- newTranslations:
- Example:
$mergeTranslations({
welcome: 'Bienvenue, {username}!'
})
// Output: Updates the translation cache with the new French translation
π¦ $defineI18nRoute
β
- Type:
(routeDefinition: { locales?: string[] | Record<string, Record<string, TranslationObject>>, localeRoutes?: Record<string, string> }) => void
- Description: Defines route behavior based on the current locale. This method can be used to control access to specific routes based on available locales, provide translations for specific locales, or set custom routes for different locales.
- Parameters:
- locales:
string[] | Record<string, Record<string, TranslationObject>>
β This property determines which locales are available for the route. - localeRoutes:
Record<string, string> | undefined
β Optional. Custom routes for specific locales.
- locales:
- Example:
$defineI18nRoute({
locales: {
en: { greeting: 'Hello', farewell: 'Goodbye' },
ru: { greeting: 'ΠΡΠΈΠ²Π΅Ρ', farewell: 'ΠΠΎ ΡΠ²ΠΈΠ΄Π°Π½ΠΈΡ' },
},
localeRoutes: {
ru: '/localesubpage',
},
})
Use Cases: β
Controlling Access: By specifying available locales, you can control which routes are accessible based on the current locale, ensuring that users only see content relevant to their language.
Providing Translations: The
locales
object allows for providing specific translations for each route, enhancing the user experience by delivering content in the user's preferred language.Custom Routing: The
localeRoutes
property offers flexibility in defining different paths for specific locales, which can be particularly useful in cases where certain languages or regions require unique navigational flows or URLs.
This function offers a flexible way to manage routing and localization in your Nuxt application, making it easy to tailor the user experience based on the language and region settings of your audience.
Example 1: Controlling Access Based on Locales β
import { useNuxtApp } from '#imports'
const { $defineI18nRoute } = useNuxtApp()
$defineI18nRoute({
locales: ['en', 'fr', 'de'] // Only these locales are allowed for this route
})
Example 2: Providing Translations for Locales β
import { useNuxtApp } from '#imports'
const { $defineI18nRoute } = useNuxtApp()
$defineI18nRoute({
locales: {
en: { greeting: 'Hello', farewell: 'Goodbye' },
fr: { greeting: 'Bonjour', farewell: 'Au revoir' },
de: { greeting: 'Hallo', farewell: { aaa: { bbb: "Auf Wiedersehen" } } },
ru: {} // Russian locale is allowed but no translations are provided
}
})
π Explanation: β
- Locales Array: If you only want to specify which locales are allowed for a route, pass an array of locale codes. The user will only be able to access this route if the current locale is in this list.
- Locales Object: If you want to provide specific translations for each locale, pass an object where each key is a locale code. The value should be an object with key-value pairs for translations. If you do not wish to provide translations for a locale but still want to allow access, pass an empty object (
{}
) for that locale.
π» Example Usage in a Component β
Here's an example of how to use these methods in a Nuxt component:
<template>
<div>
<p>{{ $t('key2.key2.key2.key2.key2') }}</p>
<p>Current Locale: {{ $getLocale() }}</p>
<div>
{{ $t('welcome', { username: 'Alice', unreadCount: 5 }) }}
</div>
<div>
{{ $tc('apples', 10) }}
</div>
<div>
<button
v-for="locale in $getLocales()"
:key="locale"
:disabled="locale === $getLocale()"
@click="() => $switchLocale(locale.code)"
>
Switch to {{ locale.code }}
</button>
</div>
<div>
<NuxtLink :to="$localeRoute({ name: 'index' })">
Go to Index
</NuxtLink>
</div>
</div>
</template>
<script setup>
import { useI18n } from '#imports'
const { $getLocale, $switchLocale, $getLocales, $localeRoute, $t, $tc } = useI18n()
</script>
π οΈ useNuxtApp
β
Example:
import { useNuxtApp } from '#imports'
const { $getLocale, $switchLocale, $getLocales, $localeRoute, $t } = useNuxtApp()
𧩠useI18n
Composable β
Example:
import { useI18n } from '#imports'
const { $getLocale, $switchLocale, $getLocales, $localeRoute, $t } = useI18n()
// or
const i18n = useI18n()