Basic Usage
The basics to get started with the Nuxt i18n module is to translate with Vue I18n via the vueI18n
option.
Translate with Vue I18n
The basic to get started with Nuxt i18n module is to translate with Vue I18n via the vueI18n
option
So, let's get started configuring the following nuxt.config
:
export default defineNuxtConfig({ modules: [ '@nuxtjs/i18n' ], i18n: { // add `vueI18n` option to `@nuxtjs/i18n` module options vueI18n: { legacy: false, locale: 'en', messages: { en: { welcome: 'Welcome' }, fr: { welcome: 'Bienvenue' } } } }})
The vueI18n
option is the same as createI18n
function option of Vue I18n. vueI18n
option is passed to the createI18n
function via the nuxt plugin of this module internally.
For more details about the vueI18n
option, see the Vue I18n documentation.
Now, put (or edit) the following the page component in pages
directory of you project:
<script setup>const { locale } = useI18n()</script><template> <div> <form> <select v-model="locale"> <option value="en">en</option> <option value="fr">fr</option> </select> <p>{{ $t('welcome') }}</p> </form> </div></template>
useI18n
are auto-imported by Nuxt.If you want to import them explicitly, you can use #imports
as follows:<script setup>import { useI18n, useLocalePath } from '#imports'// ...</script>
You now have a really simple Vue I18n based translation environment ready to go! The <form>
element that contains both English and French options, choosing either languages from the dropdown, you can see the word "welcome" change in its corresponding language.
For more information about Vue I18n, you can refer to its documentation here.
Link localizing
The Nuxt i18n module extends the integrated Vue I18n to give us some i18n features for Nuxt application. In here, we introduce one of those features, the link localization with extending Nuxt pages and routing.
Configurations
You'll need to additionally set the defaultLocale
and locales
options, as in the following configuration.
For localizing links, you can use the code provided from the locales
option as the URL path prefix, except for defaultLocale
(read more on routing).
export default defineNuxtConfig({ modules: [ '@nuxtjs/i18n' ], i18n: {+ locales: ['en', 'fr'], // used in URL path prefix+ defaultLocale: 'en', // default locale of your project for Nuxt pages and routings vueI18n: { legacy: false, locale: 'en', messages: { en: { welcome: 'Welcome' }, fr: { welcome: 'Bienvenue' } } } } })
When rendering internal links in your app using <NuxtLink>
, you need to get proper URLs for the current locale. To do this, the Nuxt i18n module provides some helper composables:
URL path
You can localize URL path with using useLocalePath
.
useLocalePath
is a composable which returns a function used to get the localized URL for a given page. The first parameter can be either the path or name of the route or an object for more complex routes. A locale code can be passed as the second parameter to generate a link for a specific language:
<script setup>const localePath = useLocalePath()</script><template> <NuxtLink :to="localePath('index')">{{ $t('home') }}</NuxtLink> <NuxtLink :to="localePath('/')">{{ $t('home') }}</NuxtLink> <NuxtLink :to="localePath('index', 'en')">Homepage in English</NuxtLink> <NuxtLink :to="localePath('/user/profile')">Route by path to: {{ $t('profile') }}</NuxtLink> <NuxtLink :to="localePath('user-profile')">Route by name to: {{ $t('profile') }}</NuxtLink> <NuxtLink :to="localePath({ name: 'category-slug', params: { slug: category.slug } })"> {{ category.title }} </NuxtLink></template>
Note that localePath
can use the route's unprefixed path, which must start with '/'
or the route's base name to generate the localized URL. The base name corresponds to the names Nuxt generates when parsing your pages
directory, more info in Nuxt's doc.
this.localePath
. This API is kept for migration from Nuxt 2.Language switching path
You can localize language path with using useSwitchLocalePath
.
useSwitchLocalePath
is a composable function which returns a link to the current page in another language:
<script setup>const switchLocalePath = useSwitchLocalePath()</script><template> <NuxtLink :to="switchLocalePath('en')">English</NuxtLink> <NuxtLink :to="switchLocalePath('fr')">Français</NuxtLink></template>
this.switchLocalePath
. This API is kept for migration from Nuxt 2.URL path with Route object
You can localize advanced URL path with using useLocaleRoute
. This is useful if you would to control internal link programmatically.
useLocaleRoute
is a composable function that returns a Route
object for a given page.
It works like useLocalePath
but returns route resolved by Vue Router rather than just a full route path. This can be useful since full path returned from useLocalePath
might not carry all information from the provided input (for example, the route params that the page doesn't specify).
<script setup>const localeRoute = useLocaleRoute()function onClick() { const route = localeRoute({ name: 'user-profile', query: { foo: '1' } }) if (route) { return navigateTo(route.fullPath) }}</script><template> <button @click="onClick">Show profile</button></template>
this.localeRoute
. This API is kept for migration from Nuxt 2.