Usage

Basic setup

Let's start by configuring the project locales and the defaultLocale in the nuxt config.

For this project we configure the locales with the following properties:

• code: required property, the locale code is used throughout Nuxt I18n and is used as the identifier for the locale.
• name: name of the locale, this is a user-friendly way to identify the locale.
• file: a file that provides translation messages in the form of an object.

The defaultLocale should be set to the code of one of the configured locales, setting this is optional but recommended as it will be used as fallback when navigating to a non-existent route.

export default defineNuxtConfig({
  modules: ['@nuxtjs/i18n'],
  i18n: {
    defaultLocale: 'en',
    locales: [
      { code: 'en', name: 'English', file: 'en.json' },
      { code: 'nl', name: 'Nederlands', file: 'nl.json' }
    ]
  }
})

A typical project has at least one file for each configured locale, this file provides the translation messages in the form of an object.

Nuxt I18n has a (configurable) folder structure from which the locale files are sourced, the locale files should be created in <rootDir>/i18n/locales by default.

{
  "welcome": "Welcome"
}

{
  "welcome": "Welkom"
}

With this configuration we can add a basic language switcher and translate our first message using:

<script setup>
const { locales, setLocale } = useI18n()
</script>

<template>
  <div>
    <button v-for="locale in locales" @click="setLocale(locale.code)">
      {{ locale.name }}
    </button>
    <h1>{{ $t('welcome') }}</h1>
  </div>
</template>

Using the configured locales we created a simple language-switcher, by clicking a <button> element you can switch between English and Dutch and see the "welcome" message and page URL change to its corresponding language.

You now have a basic setup to get started with fully localizing your Nuxt Application!

Auto Imports

Some composable functions such as useI18n are auto-imported by Nuxt. If you have disabled autoImports you will need to import these explicitly from #imports as follows:

<script setup>
import { useI18n, useLocalePath } from '#imports'
// ...
</script>

Route localization

Nuxt I18n generates localized routes for each locale, in the most basic setup this comes in the form of a prefixed variant of each route with a locale code.

When linking to routes within your app, you will need to get the localized route for the current locale. This is done with utility functions provided by Nuxt I18n.

Resolving a localized route with $localePath

The $localePath function is used to get the localized route for a given route, this function is returned by useLocalePath for usage outside <template>.

This function accepts two parameters:

• route: name of a route or a route object with a name property
• locale: locale code in which the route should be localized, defaults to the current locale

<template>
  <NuxtLink :to="$localePath('index')">{{ $t('home') }}</NuxtLink>
  <NuxtLink :to="$localePath('index', 'en')">Homepage in English</NuxtLink>
  <NuxtLink :to="$localePath('user-profile')">Route to {{ $t('profile') }}</NuxtLink>
  <NuxtLink :to="$localePath({ name: 'category-slug', params: { slug: category.slug } })">
    {{ category.title }}
  </NuxtLink>
</template>

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

<template>
  <NuxtLink :to="localePath('index')">{{ $t('home') }}</NuxtLink>
  <NuxtLink :to="localePath('index', 'en')">Homepage in English</NuxtLink>
  <NuxtLink :to="localePath('user-profile')">Route to {{ $t('profile') }}</NuxtLink>
  <NuxtLink :to="localePath({ name: 'category-slug', params: { slug: category.slug } })">
    {{ category.title }}
  </NuxtLink>
</template>

Since localized routes can change based on your configuration, using route names ensures accurate resolution. Nuxt I18n generates types to facilitate this, providing type safety and improved developer experience. To utilize these types, enable typedPages in your Nuxt configuration.

The route name corresponds to the names Nuxt generates when parsing your pages directory, more info in Nuxt docs.

Switching between languages

The $switchLocalePath function returns the localized version of the route to the current page, it accepts a locale code in which the current route should be localized.

<template>
  <NuxtLink :to="$switchLocalePath('en')">English</NuxtLink>
  <NuxtLink :to="$switchLocalePath('nl')">Nederlands</NuxtLink>
</template>

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

<template>
  <NuxtLink :to="switchLocalePath('en')">English</NuxtLink>
  <NuxtLink :to="switchLocalePath('nl')">Nederlands</NuxtLink>
</template>

URL path with Route object

You can localize advanced URL paths using useLocaleRoute. This is useful if you would to control internal links programmatically.

useLocaleRoute is a composable function that returns a Route object for a given page.

It works like useLocalePath but returns a route resolved by Vue Router rather than a full route path. This can be useful as the path returned from useLocalePath may not carry all information from the provided input (for example, 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>