# Installation

::callout{icon="i-heroicons-light-bulb"}
Nuxt i18n module configures 

**Vue I18n v11**

 for your project, see the 

[Vue i18n documentation](https://vue-i18n.intlify.dev/){rel=""nofollow""}

 for in depth guides on the functionalities it provides.
::

## Quick Start

1. Install `@nuxtjs/i18n` as a dev dependency to your project:

```bash
npx nuxi@latest module add @nuxtjs/i18n
```

2. Add `@nuxtjs/i18n` to your `nuxt.config` modules:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/i18n']
})
```

## Configuration

You can set the module options by using the `i18n` property in `nuxt.config` root.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/i18n'],
  i18n: {
    // Module Options
  }
})
```

## Edge Channel

### Opting in

You can opt in to the latest commits on the `main` branch to avoid waiting for the next release and helping the module by beta testing changes.

Update `@nuxtjs/i18n` dependency in your `package.json`:

```diff [package.json]
{
  "devDependencies": {
-   "@nuxtjs/i18n": "^9.0.0"
+   "@nuxtjs/i18n": "npm:@nuxtjs/i18n-edge"
  }
}
```

Remove lockfile (`package-lock.json`, `yarn.lock`, or `pnpm-lock.yaml`) and reinstall dependencies.

### Opting out

Update `@nuxtjs/i18n` dependency in your `package.json`:

```diff [package.json]
{
  "devDependencies": {
-   "@nuxtjs/i18n": "npm:@nuxtjs/i18n-edge"
+   "@nuxtjs/i18n": "^9.0.0"
  }
}
```

Remove lockfile (`package-lock.json`, `yarn.lock`, or `pnpm-lock.yaml`) and reinstall dependencies.


# 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.

```ts [nuxt.config.ts]
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.

::code-group
```json [i18n/locales/en.json]
{
  "welcome": "Welcome"
}
```

```json [i18n/locales/nl.json]
{
  "welcome": "Welkom"
}
```
::

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

```vue [pages/index.vue]
<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](https://nuxt.com/docs/guide/concepts/auto-imports#auto-imports){rel="&#x22;nofollow&#x22;"}.
If you have disabled `autoImports` you will need to import these explicitly from `#imports` as follows:

```vue
<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

::code-group
```vue [page.vue (global function)]
<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>
```

```vue [page.vue (composable)]
<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](https://nuxt.com/docs/guide/directory-structure/pages){rel="&#x22;nofollow&#x22;"}.

### 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.

::code-group
```vue [page.vue (global function)]
<template>
  <NuxtLink :to="$switchLocalePath('en')">English</NuxtLink>
  <NuxtLink :to="$switchLocalePath('nl')">Nederlands</NuxtLink>
</template>
```

```vue [page.vue (composable)]
<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).

```vue
<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>
```


# Vue I18n Configuration

## Vue I18n Configuration

While some options are shared between Nuxt I18n and Vue I18n, there is a range of options which are specific to Vue I18n, for example:

- `fallbackWarn`: To control fallback warnings.
- `missingWarn`: To control missing localization warnings.
- `formatter`: To provide a custom message formatting function.
- `numberFormats`: To configure custom number formatting.
- `datetimeFormats`: To configure custom date time formatting.
- ... more!

These are just a few examples of the runtime options available in Vue I18n, please check out [the documentation of Vue I18n](https://vue-i18n.intlify.dev/){rel="&#x22;nofollow&#x22;"} to explore the full range of available options.

Vue I18n specific options cannot be configured in `nuxt.config` and have no overlap with the features used by or provided by Nuxt I18n.

## Adding a Vue I18n config file

To configure the options you can create a `i18n.config.ts` file in the `<rootDir>/i18n` directory, this file should have a default export with a function returning the Vue I18n options.

Nuxt I18n provides a macro function `defineI18nConfig` to improve the types, but a plain function would suffice too:

```ts [i18n/i18n.config.ts]
export default defineI18nConfig(() => {
  return {
    // vue-i18n options
  }
})
```

The config file is resolved from `<rootDir>/i18n`, and automatically looks for and loads the config file using the default filename of `i18n.config`. This can be configured using the `vueI18n` options.

## When to use

Use `i18n.config.ts` when you need to configure Vue I18n options that involve runtime functions or data that cannot be serialized for build-time processing. This is often the case when:

- You need to dynamically load or manipulate localization data based on user input or external APIs.
- You are using custom formatting functions or other non-serializable options.
- You need to use Vue I18n options that are not supported by Nuxt I18n's build-time configuration.

## Nuxt config benefits

While it is possible to configure the same (or functionally the same) options configurable in `i18n.config.ts` (`messages` - instead of `locales`, `defaultLocale`, etc.) it is recommended to keep as much of the configuration as Nuxt I18n supports on the `i18n` key inside `nuxt.config`.

Nuxt I18n will use these options during the build step and can configure and optimize functionalities by integrating with other libraries such as `@intlify/unplugin-vue-i18n`.

The Vue I18n config file will be loaded at runtime on each request which can increase server response times, especially in high-traffic applications. This is because the server needs to parse and process the configuration for every incoming request and merge them with those set by Nuxt I18n, rather than doing it once at build time.


# Routing Strategies

::callout{icon="i-heroicons-light-bulb"}
This feature is built on top of 

[Nuxt's routing](https://nuxt.com/docs/getting-started/routing){rel=""nofollow""}

 which requires your project to have a 

`pages`

 directory for it to be enabled.
::

## Routing

**Nuxt i18n module** overrides Nuxt default routes to add locale prefixes to every URL (except in `'no_prefix'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} strategy).

Say your app supports two languages: French and English as the default language, and you have the following pages in your project:

::code-group
```bash [Directory structure]
-| pages/
---| about.vue
---| index.vue
---| posts/
-----| [id].vue
```

```js [Generated routes (simplified)]
[
  {
    path: "/",
    name: "index___en",
  },
  {
    path: "/fr",
    name: "index___fr",
  },
  {
    path: "/about",
    name: "about___en",
  },
  {
    path: "/fr/about",
    name: "about___fr",
  },
  {
    path: "/posts/:id",
    name: "posts-id___en",
  },
  {
    path: "/fr/posts/:id",
    name: "posts-id___fr",
  }
]
```
::

Note that routes for the English version do not have any prefix because it is the default language, see the routing strategies section for more details.

## Strategies

There are 4 supported strategies that affect how app's routes are generated:

### `'no_prefix'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

With this strategy, your routes won't have a locale prefix added. The locale will be detected & changed without changing the URL. This implies that you have to rely on browser & cookie detection, and implement locale switches by calling the i18n API.

::callout{icon="i-heroicons-light-bulb"}
This strategy doesn't support 

[Custom paths](https://i18n.nuxtjs.org/docs/guide/custom-paths)

 and 

[Ignore routes](https://i18n.nuxtjs.org/docs/guide/ignoring-localized-routes)

 features unless you're also using 

[`differentDomains`](https://i18n.nuxtjs.org/docs/guide/different-domains)

.
::

### `'prefix_except_default'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Using this strategy, all of your routes will have a locale prefix added except for the default language.

### `'prefix'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

With this strategy, all routes will have a locale prefix.

### `'prefix_and_default'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

This strategy combines both previous strategies behaviours, meaning that you will get URLs with prefixes for every language, but URLs for the default language will also have a non-prefixed version (though the prefixed version will be preferred when `detectBrowserLanguage` is enabled).

## Configuration

To configure the strategy, use the `strategy` option.
Make sure that you have a `defaultLocale` defined, especially if using `prefix_except_default`, `prefix_and_default` or `no_prefix` strategy. For other strategies it's also recommended to set this as it will be used as a fallback when attempting to redirect from a 404 page.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  // ...

  i18n: {
    strategy: 'prefix_except_default',
    defaultLocale: 'en'
  }

  // ...
})
```


# Runtime Hooks

**Nuxt i18n module** provides runtime hooks to perform specific tasks based on your app's language.

## Hooks

### `'i18n:beforeLocaleSwitch'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Called before the app's locale is switched, the `newLocale` property can be overridden to change the locale being switched to.

Parameters:

- `oldLocale`
  - type: `string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
  - The app's locale before the switch
- `newLocale`
  - type: `string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
  - The app's locale after the switch
- `initialSetup`
  - type: `string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
  - Set to `true` if it's the initial locale switch that triggers on app load. It's a special case since the locale is not technically set yet so we're switching from no locale to locale.
- `context`
  - type: `NuxtApp`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
  - The Nuxt app, this property is deprecated, the same can be achieved by using `const context = useNuxtApp()` outside the hook scope instead.

Returns: `string | null`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

### `'i18n:localeSwitched'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Called right after the app's locale has been switched.

Parameters:

- `oldLocale`
  - type: `string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
  - The app's locale before the switch
- `newLocale`
  - type: `string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
  - The app's locale after the switch

## Usage

A typical usage would be to define those callbacks via a plugin where you can access the app's context (useful if you need to change Axios' config when the language changes for example).

```ts [/plugins/i18n.ts]
export default defineNuxtPlugin(nuxtApp => {
  // called right before setting a new locale
  nuxtApp.hook('i18n:beforeLocaleSwitch', (options) => {
    console.log('onBeforeLanguageSwitch', options.oldLocale, options.newLocale, options.initialSetup)

    // You can override the new locale by setting it to a different value
    if(options.newLocale === 'fr') {
      options.newLocale = 'en'
    }
  })

  // called right after a new locale has been set
  nuxtApp.hook('i18n:localeSwitched', (options) => {
    console.log('onLanguageSwitched', options.oldLocale, options.newLocale)
  })
})
```


# Custom Route Paths

In some cases, you might want to translate URLs in addition to having them prefixed with the locale code. There are two methods of configuring custom paths, through [Module configuration](https://i18n.nuxtjs.org/#module-configuration) or from within each [Page component](https://i18n.nuxtjs.org/#definepagemeta).

Which method is used is configured by setting the [`customRoutes` options](https://i18n.nuxtjs.org/docs/api/options#customroutes) this is set to `'page'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} by default. Using both methods at the same time is not possible.

::callout{color="warning" icon="i-heroicons-exclamation-triangle"}
Custom paths are not supported when using the 

`'no_prefix'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

 

[strategy](https://i18n.nuxtjs.org/docs/guide)

 unless combined with 

[`differentDomains`](https://i18n.nuxtjs.org/docs/guide/different-domains)

.
::

## Module configuration

Make sure you set the `customRoutes` option to `'config'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} and add your custom paths in the `pages` option:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  i18n: {
    customRoutes: 'config', // disable custom route with page components
    pages: {
      about: {
        en: '/about-us', // -> accessible at /about-us (no prefix since it's the default locale)
        fr: '/a-propos', // -> accessible at /fr/a-propos
        es: '/sobre' // -> accessible at /es/sobre
      }
    }
  }
})
```

Note that each key within the `pages` object should **correspond to the route name of the route to localize**.

Customized route paths &#x2A;*must start with a `/`** and **must not include the locale prefix**.

You can now use the `localePath()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} function or the `<NuxtLinkLocale>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="html"} component but be sure to use named routes. For example route `'/services/advanced'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} should be `'services-advanced'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}:

```vue
<script setup>
const { t } = useI18n()
</script>

<template>
  <NuxtLinkLocale to="about"> {{ t('about') }} </NuxtLinkLocale>
  <NuxtLinkLocale to="services-advanced"> {{ t('advanced') }} </NuxtLinkLocale>
</template>
```

Or:

```vue
<script setup>
const { t } = useI18n()
const localePath = useLocalePath()
</script>

<template>
  <NuxtLink :to="localePath('about')"> {{ t('about') }} </NuxtLink>
  <NuxtLink :to="localePath('services-advanced')"> {{ t('advanced') }} </NuxtLink>
</template>
```

::callout{color="warning" icon="i-heroicons-exclamation-triangle"}
Passing a path to 

`localePath()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

 is currently not supported.
::

### Example 1: Basic URL localization

You have some routes with the following `pages` directory:

```bash [Directory structure]
-| pages/
---| parent/
-----| child.vue
---| parent.vue
```

::callout{icon="i-heroicons-light-bulb"}
Nested/child routes rely on there being a page component with the same name as the folder that renders the child routes. 

:br


For more details, see 

[Nested Routes](https://nuxt.com/docs/guide/directory-structure/pages#nested-routes){rel=""nofollow""}

.
::

You would need to set up your `pages` property as follows:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  i18n: {
    customRoutes: 'config',
    pages: {
      parent: {
        en: '/parent',
        ca: '/pare'
      },
      'parent-child': {
        en: '/parent/child',
        ca: '/pare/fill'
      }
    }
  }
})
```

::callout{color="warning" icon="i-heroicons-exclamation-triangle"}
All URLs must start with 

`/`
::

### Example 2: Localize the part of URL

You have some routes with the following `pages` directory:

```bash [Directory structure]
-| pages/
---| about.vue
---| services/
-----| index.vue
-----| coaching.vue
-----| development/
-------| app.vue
-------| website.vue
-----| development.vue
---| services.vue
```

You would need to set up your `pages` property as follows:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  i18n: {
    customRoutes: 'config',
    pages: {
      about: {
        fr: '/a-propos'
      },
      services: {
        fr: '/offres'
      },
      'services-development': {
        fr: '/offres/developement'
      },
      'services-development-app': {
        fr: '/offres/developement/app'
      },
      'services-development-website': {
        fr: '/offres/developement/site-web'
      },
      'services-coaching': {
        fr: '/offres/formation'
      }
    }
  }
})
```

If a custom path is missing for one of the locales, the `defaultLocale` custom path is used, if set.

### Example 3: Dynamic Routes

Say you have some dynamic routes like:

```bash [Directory structure]
-| pages/
---| blog/
-----| [date]/
-------| [slug].vue
```

Here's how you would configure these particular pages in the configuration:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  i18n: {
    customRoutes: 'config',
    pages: {
      'blog-date-slug': {
        // params need to be put back here as you would with Nuxt Dynamic Routes
        // https://nuxt.com/docs/guide/directory-structure/pages#dynamic-routes
        ja: '/blog/tech/[date]/[slug]'
        // ...
      }
    }
  }
})
```

## `definePageMeta`

You can use the `i18n` property in `definePageMeta()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} to set custom paths for each page component.

To use this feature you will need to set `customRoutes: 'meta'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} in your `nuxt.config.ts`:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  i18n: {
    customRoutes: 'meta'
  }
})
```

Each page can then define its own localized paths like so:

```vue [pages/about.vue]
<script setup>
definePageMeta({
  i18n: {
    paths: {
      en: '/about-us', // -> accessible at /about-us (no prefix since it's the default locale)
      fr: '/a-propos', // -> accessible at /fr/a-propos
      es: '/sobre' // -> accessible at /es/sobre
    }
  }
})
</script>
```

To configure a custom path for a dynamic route, you need to use it in double square brackets in the paths similar to how you would do it in [Nuxt Dynamic Routes](https://nuxt.com/docs/guide/directory-structure/pages#dynamic-routes){rel="&#x22;nofollow&#x22;"}:

```vue [pages/articles/[name\\].vue]
<script setup>
definePageMeta({
  i18n: {
    paths: {
      en: '/articles/[name]',
      es: '/artículo/[name]'
    }
  }
})
</script>
```

## `defineI18nRoute`

::callout
---
color: warning
icon: i-heroicons-exclamation-triangle
title: notice
---
This method is deprecated in favor of 

`definePageMeta()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

 described above, and will be removed in v11.
::

You can use the `defineI18nRoute()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} compiler macro to set custom paths for each page component.

```vue [pages/about.vue]
<script setup>
defineI18nRoute({
  paths: {
    en: '/about-us', // -> accessible at /about-us (no prefix since it's the default locale)
    fr: '/a-propos', // -> accessible at /fr/a-propos
    es: '/sobre' // -> accessible at /es/sobre
  }
})
</script>
```

To configure a custom path for a dynamic route, you need to use it in double square brackets in the paths similar to how you would do it in [Nuxt Dynamic Routes](https://nuxt.com/docs/guide/directory-structure/pages#dynamic-routes){rel="&#x22;nofollow&#x22;"}:

```vue [pages/articles/[name\\].vue]
<script setup>
defineI18nRoute({
  paths: {
    en: '/articles/[name]',
    es: '/artículo/[name]'
  }
})
</script>
```

::callout{icon="i-heroicons-light-bulb"}
`defineI18nRoute()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

 compiler macro is tree-shaken out at build time and is not included in the dist files.
::

## Dynamic route parameters

Dealing with dynamic route parameters requires a bit more work because you need to provide parameters translations to **Nuxt i18n module**. The composable `useSetI18nParams` can be used to set translations for route parameters, this is used to set SEO tags as well as changing the routes rendered by `<SwitchLocalePathLink>`.

::callout{color="warning" icon="i-heroicons-exclamation-triangle"}
The 

`switchLocalePath`

 will return localized routes using the translated params from 

`setI18nParams`

 this can cause hydration issues for previously rendered links using 

`switchLocalePath`

.
Use the 

`<SwitchLocalePathLink>`

 component instead, its routes are updated before sending out the rendered response.
::

An example (replace `slug` with the applicable route parameter):

```vue
<script setup>
// fetch product from API... (red mug)

const setI18nParams = useSetI18nParams()
setI18nParams({
  en: { slug: data.slugs.en }, // slug: 'red-mug'
  nl: { slug: data.slugs.nl } // slug: 'rode-mok'
})

const switchLocalePath = useSwitchLocalePath()
switchLocalePath('en') // /products/red-mug
switchLocalePath('nl') // /nl/products/rode-mok
</script>

<template>
  <!-- pages/products/[slug].vue -->
</template>
```

Note that for the special case of a catch-all route named like `[...pathMatch].vue`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="bash"}, the key of the object needs to say `pathMatch`. For example:

```vue
<script>
const setI18nParams = useSetI18nParams()
setI18nParams({
  en: { pathMatch: ['not-found-my-post'] },
  fr: { pathMatch: ['not-found-mon-article'] }
})
</script>

<template>
  <!-- pages/[...pathMatch].vue -->
</template>
```

Note that a catch all route is defined **as an array**. In this case, there is only one element, but if you want to use a sub-path, for example `'/not-found/post'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, define multiple elements as in `['not-found', 'post']`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}. You will need to define more than one, e.g. `['not-found', 'post']`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}.

::callout{icon="i-heroicons-light-bulb"}
**Nuxt i18n module**

 won't reset parameters translations for you, this means that if you use identical parameters for different routes, navigating between those routes might result in conflicting parameters. Make sure you always set params translations in such cases.
::

## `definePageMeta({ name: '...' })`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} caveat

By default Nuxt overwrites generated route values at build time which breaks custom named routes (setting `name` with `definePageMeta()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}) when resolving localized paths.

Nuxt v3.10 introduced the experimental feature [`scanPageMeta`](https://nuxt.com/docs/guide/going-further/experimental-features#scanpagemeta){rel="&#x22;nofollow&#x22;"}, this needs to be enabled for custom named routes to work when using Nuxt I18n.

This experimental feature can be enabled as shown here:

```typescript [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    scanPageMeta: true
  }
})
```


# Ignoring Localized Routes

::callout{color="warning" icon="i-heroicons-exclamation-triangle"}
This feature is not supported when using the 

`'no_prefix'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

 

[strategy](https://i18n.nuxtjs.org/docs/guide)

 unless you're also using 

[`differentDomains`](https://i18n.nuxtjs.org/docs/guide/different-domains)

.
::

If you'd like some pages to be available in some languages only, you can configure the list of supported languages to override the global settings. The options can be specified within either the page components themselves or globally, within the module configuration.

### Pick localized routes

::code-group
```vue [about-meta.vue]
// pages/about.vue
<script setup>
definePageMeta({
  i18n: { locales: ['fr', 'es'] }
})
</script>
```

```vue [about-macro.vue]
// pages/about.vue
<script setup>
defineI18nRoute({
  locales: ['fr', 'es']
})
</script>
```

```ts [nuxt.config.ts]
i18n: {
  pages: {
    about: {
      en: false,
    }
  }
}
```
::

### Disable localized routes

::code-group
```vue [about-meta.vue]
// pages/about.vue
<script setup>
definePageMeta({ i18n: false })
</script>
```

```vue [about-macro.vue]
// pages/about.vue
<script setup>
defineI18nRoute(false)
</script>
```

```ts [nuxt.config.ts]
i18n: {
  customRoutes: 'config',
  pages: {
    about: false
  }
}
```
::


# Browser language detection

By default, Nuxt i18n module attempts to redirect users to their preferred language by detecting their browser's language. This is controlled by the `detectBrowserLanguage` option.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  i18n: {
    detectBrowserLanguage: {
      useCookie: true,
      cookieKey: 'i18n_redirected',
      redirectOn: 'root' // recommended
    }
  }
})
```

::callout{icon="i-heroicons-light-bulb"}
For better SEO, it's recommended to set 

`redirectOn`

 to 

`root`

 (which is the default value). When set, the language detection is only attempted when the user visits the root path (

`'/'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

) of the site. This allows crawlers to access the requested page rather than being redirected away based on detected locale. It also allows linking to pages in specific locales.
::

Browser language is detected either from `navigator` when running on client-side, or from the `accept-language` HTTP header. Configured `locales` (or locales `language` and/or `code` when locales are specified in object form) are matched against locales reported by the browser (for example `en-US,en;q=0.9,no;q=0.8`). If there is no exact match for the full locale, the language code (letters before `-`) are matched against configured locales.

To prevent redirecting users every time they visit the app, **Nuxt i18n module** sets a cookie using the detected locale. You can change the cookie's name by setting `detectBrowserLanguage.cookieKey` option to whatever you'd like, the default is *i18n\_redirected*.

```ts [nuxt.config.ts]
i18n: {
  detectBrowserLanguage: {
    useCookie: true,
    cookieKey: 'my_custom_cookie_name'
  }
}
```

If you'd rather have users be redirected to their browser's language every time they visit the app, disable the cookie by setting `detectBrowserLanguage.useCookie` to `false`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  i18n: {
    detectBrowserLanguage: {
      useCookie: false
    }
  }
})
```

To completely disable the browser's language detection feature, set `detectBrowserLanguage` to `false`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  i18n: {
    // ...
    detectBrowserLanguage: false
  }
})
```

To redirect the user every time they visit the app and keep their selected choice, enable `alwaysRedirect`:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  i18n: {
    // ...
    detectBrowserLanguage: {
      useCookie: true,
      alwaysRedirect: true
    }
  }
})
```

To use the cookie within a cross-origin environment (e.g. in an iFrame), you can set `cookieCrossOrigin: true`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}. This will change the cookie settings from `'SameSite=Lax'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} to `'SameSite=None; Secure'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  i18n: {
    detectBrowserLanguage: {
      useCookie: true,
      cookieCrossOrigin: true
    }
  }
})
```


# SEO

**Nuxt i18n module** provides the `useLocaleHead()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} composable function. Calling this composable function returns a function which you can use to generate SEO metadata to optimize locale-related aspects of the app for the search engines.

Here are the specific optimizations and features that it enables:

- `lang` attribute for the `<html>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="html"} tag
- `hreflang` alternate link generation
- OpenGraph locale tag generation
- canonical link generation

[Read more about those features below](https://i18n.nuxtjs.org/#feature-details)

## Requirements

To leverage the SEO benefits, you must configure the `locales` option as an array of objects, where each object has an `language` option set to the locale language tags:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  i18n: {
    locales: [
      {
        code: 'en',
        language: 'en-US'
      },
      {
        code: 'es',
        language: 'es-ES'
      },
      {
        code: 'fr',
        language: 'fr-FR'
      }
    ]
  }
})
```

You must also set the `baseUrl` option to your production domain in order to make alternate URLs fully-qualified:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  i18n: {
    baseUrl: 'https://my-nuxt-app.com'
  }
})
```

(Note that `baseUrl` can also be set to a function. Check [`baseUrl` documentation](https://i18n.nuxtjs.org/docs/api/options#baseurl).)

## Setup

The `useLocaleHead()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} is a composable function, Calling that composable function returns a function that returns metadata that is handled by [Head management](https://nuxt.com/docs/getting-started/seo-meta){rel="&#x22;nofollow&#x22;"} that is integrated within Nuxt. That metadata can be specified by the `setup` function in various places within Nuxt:

- [`app.vue`](https://nuxt.com/docs/guide/directory-structure/app){rel="&#x22;nofollow&#x22;"}
- Vue components of [`pages`](https://nuxt.com/docs/guide/directory-structure/pages){rel="&#x22;nofollow&#x22;"} directory
- Vue components of [`layouts`](https://nuxt.com/docs/guide/directory-structure/layouts){rel="&#x22;nofollow&#x22;"} directory

To enable SEO metadata, declare a `setup` function in one of the places specified above and make it return the result of a `useLocaleHead()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} function call.

To avoid duplicating the code, it's recommended to set globally with [Meta Components](https://nuxt.com/docs/getting-started/seo-meta#components){rel="&#x22;nofollow&#x22;"} in [layout components](https://nuxt.com/docs/guide/directory-structure/layouts){rel="&#x22;nofollow&#x22;"} and override some values per-page Vue component like [`definePageMeta()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}](https://nuxt.com/docs/guide/directory-structure/pages#page-metadata){rel="&#x22;nofollow&#x22;"}, if necessary.

::code-group
```vue [app.vue]
<template>
  <NuxtLayout>
    <NuxtPage />
  </NuxtLayout>
</template>
```

```vue [layouts/default.vue]
<script setup>
const route = useRoute()
const { t } = useI18n()
const head = useLocaleHead()
const title = computed(() => t(route.meta.title ?? 'TBD', t('layouts.title'))
);
</script>

<template>
  <div>
    <Html :lang="head.htmlAttrs.lang" :dir="head.htmlAttrs.dir">
      <Head>
        <Title>{{ title }}</Title>
        <template v-for="link in head.link" :key="link.key">
          <Link :id="link.key" :rel="link.rel" :href="link.href" :hreflang="link.hreflang" />
        </template>
        <template v-for="meta in head.meta" :key="meta.key">
          <Meta :id="meta.key" :property="meta.property" :content="meta.content" />
        </template>
      </Head>
      <Body>
        <slot />
      </Body>
    </Html>
  </div>
</template>
```

```vue [pages/index.vue]
<script setup>
definePageMeta({
  title: 'pages.title.top' // set resource key
})

const { locale, locales, t } = useI18n()
const switchLocalePath = useSwitchLocalePath()

const availableLocales = computed(() => {
  return locales.value.filter(i => i.code !== locale.value)
})
</script>

<template>
  <div>
    <p>{{ t('pages.top.description') }}</p>
    <p>{{ t('pages.top.languages') }}</p>
    <nav>
      <template v-for="(locale, index) in availableLocales" :key="locale.code">
        <span v-if="index"> | </span>
        <NuxtLink :to="switchLocalePath(locale.code)">
          {{ locale.name ?? locale.code }}
        </NuxtLink>
      </template>
    </nav>
  </div>
</template>
```
::

Check out the options you can pass to the `useLocaleHead()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} in the [composable documentation](https://i18n.nuxtjs.org/docs/composables/use-locale-head#options)

That's it!

If you also want to add your own metadata, you have to call `useHead()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}. When you call `useHead()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} with the additional metadata, `useHead()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} will merge it global metadata that has already defined.

```vue [pages/about/index.vue]
<script setup>
// define page meta for layouts/default.vue
definePageMeta({
  title: 'pages.title.about'
})

useHead({
  meta: [{ property: 'og:title', content: 'this is og title for about page' }]
})
</script>

<template>
  <h2>{{ $t('pages.about.description') }}</h2>
</template>
```

## Feature details

- `lang` attribute for the `<html>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="html"} tag :br Sets the correct `lang` attribute, equivalent to the current locale's `language` value, in the `<html>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="html"} tag.
- `hreflang` alternate link :br Generates `<link rel="alternate" hreflang="x">`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="html"} tags for every configured locale. The locales' `language` value are used as `hreflang` values. :br A "catchall" locale hreflang link is provided for each locale group (e.g. `en-*`). By default, it is the first locale provided, but another locale can be selected by setting `isCatchallLocale` to `true`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} on that specific locale object in your **Nuxt i18n module** configuration. [More on hreflang](https://support.google.com/webmasters/answer/189077){rel="&#x22;nofollow&#x22;"}:br An example without selected "catchall" locale:
  ```ts \[nuxt.config.ts]
  export default defineNuxtConfig({
    i18n: {
      locales: [
        {
          code: 'en',
          language: 'en-US' // Will be used as "catchall" locale by default
        },
        {
          code: 'gb',
          language: 'en-GB'
        }
      ]
    }
  })
  ```
  :brHere is how you'd use `isCatchallLocale` to selected another locale:
  ```ts \[nuxt.config.ts]
  export default defineNuxtConfig({
    i18n: {
      locales: [
        {
          code: 'en',
          language: 'en-US'
        },
        {
          code: 'gb',
          language: 'en-GB',
          isCatchallLocale: true // This one will be used as catchall locale
        }
      ]
    }
  })
  ```
  :brIn case you already have an `en` locale `language` set, it'll be used as the "catchall" without doing anything
  ```ts \[nuxt.config.ts]
  export default defineNuxtConfig({
    i18n: {
      locales: [
        {
          code: 'gb',
          language: 'en-GB'
        },
        {
          code: 'en',
          language: 'en' // will be used as "catchall" locale
        }
      ]
    }
  })
  ```
- OpenGraph Locale tag generation :br Generates `og:locale` and `og:locale:alternate` meta tags as defined in the [Open Graph protocol](http://ogp.me/#optional){rel="&#x22;nofollow&#x22;"}.
- Canonical link :br Generates `rel="canonical"` link on all pages to specify the "main" version of the page that should be indexed by search engines. This is beneficial in various situations:
  - When using the `prefix_and_default` strategy there are technically two sets of pages generated for the default locale -- one prefixed and one unprefixed. The canonical link will be set to the unprefixed version of the page to avoid duplicate indexation.
  - When the page contains query parameters, the canonical link will **not include** the query params by default. This is typically the right thing to do as various query params can be inserted by trackers and should not be part of the canonical link. This can be overridden by using the `canonicalQueries` option. For example:
    ```vue
    <script setup>
    const i18nHead = useLocaleHead({ seo: { canonicalQueries: ['foo'] } })
    useHead(() => ({
      htmlAttrs: {
        lang: i18nHead.value.htmlAttrs.lang
      },
      link: [...(i18nHead.value.link || [])],
      meta: [...(i18nHead.value.meta || [])]
    }))
    </script>
    ```
  :br[More on canonical](https://support.google.com/webmasters/answer/182192#dup-content){rel="&#x22;nofollow&#x22;"}


# Lazy-load translations

For apps with a lot of translated content, it is preferable not to bundle all the messages in the main bundle but rather lazy-load only the language that the users selected.
This can be achieved with **Nuxt i18n module** by letting the module know where your translation files are located so it can dynamically import them when the app loads or when the user switches to another language.
To enable translations lazy-loading, follow these steps when configuring **Nuxt i18n module**:

- Configure `locales` option as an array of objects, where each object has a `file` or `files` key whose value is the translation file corresponding to the locale.
- Optionally, remove all messages that you might have passed to Vue I18n via the `vueI18n` option.
- Each `file` or `files` can return either an `Object`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, or a function that returns `Promise`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} which must return an `Object`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}.

## Basic usage

Example files structure:

```bash
-| nuxt-project/
---| i18n/
-----| locales/
-------| en-US.json
-------| es-ES.js
-------| fr-FR.ts
---| nuxt.config.ts
```

Configuration example:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  i18n: {
    locales: [
      {
        code: 'en',
        file: 'en-US.json'
      },
      {
        code: 'es',
        file: 'es-ES.js'
      },
      {
        code: 'fr',
        file: 'fr-FR.ts'
      }
    ],
    defaultLocale: 'en'
  }
})
```

```ts [i18n/locales/fr-FR.ts]
export default defineI18nLocale(async locale => {
  return {
    welcome: 'Bienvenue'
  }
})

// or

export default {
  welcome: 'Bienvenue'
}
```

::callout{icon="i-heroicons-light-bulb"}
If your function returns an object of locale messages, **you must define it in the `defineI18nLocale()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} composable function**.

About `defineI18nLocale()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} details, see the [here](https://i18n.nuxtjs.org/docs/composables/define-i18n-locale).
::

If the function returns an Object available in nuxt i18n module, you can configure the dynamic locale messages, like the API (including external API) or back-end, via fetch:

```ts
export default defineI18nLocale(locale => {
  // for example, fetch locale messages from nuxt server
  return $fetch(`/api/${locale}`)
})
```

## Multiple files lazy loading

The `files` property can be used to lazy load multiple files.

This is useful because it is efficient to manage multiple files that only define differences without duplicating locale messages.

For example, let’s take the case of supporting the Spanish language. According to [wikipedia](https://en.wikipedia.org/wiki/Spanish_language#Geographical_distribution){rel="&#x22;nofollow&#x22;"}, there are **20 countries** where Spanish is spoken as an official language!

If these countries are all configured using `file`, it would be difficult to maintain due to the duplication of locale messages for each country.

In this scenario, it would be easier to keep all shared (common) locale messages for the target language in a separate file and define dialectal variations for each country separately is well to prevent duplication, which is easier to maintain.

The following is an example of a lang directory containing locale files for the Spanish language:

```bash
-| nuxt-project/
---| i18n/
-----| locales/
-------| es.json    # locale messages for common Spanish
-------| es-AR.json # locale messages for Argentina
-------| es-UY.json # locale messages for Uruguay
-------| es-US.json # locale messages for Estados Unidos
-------| ...        # other countries
---| nuxt.config.ts
```

The following is an example of the configuration in `nuxt.config.ts`:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  i18n: {
    locales: [
      /**
       * Example definition with `files` for Spanish speaking countries
       */
      {
        code: 'es-AR',
        name: 'Español (Argentina)',
        // lazy loading order: `es.json` -> `es-AR.json`, and then merge 'es-AR.json' with 'es.json'
        files: ['es.json', 'es-AR.json']
      },
      {
        code: 'es-UY',
        name: 'Español (Uruguay)',
        // lazy loading order: `es.json` -> `es-UY.json`, and then merge 'es-UY.json' with 'es.json'
        files: ['es.json', 'es-UY.json']
      },
      {
        code: 'es-US',
        name: 'Español (Estados Unidos)',
        // lazy loading order: `es.json` -> `es-US.json`, and then merge 'es-US.json' with 'es.json'
        files: ['es.json', 'es-US.json']
      }
    ],
    defaultLocale: 'en'
  }
})
```

Please note the usage of the `files` property, as the above configuration specifies an array containing multiple file names.

@nuxtjs/i18n will load locale messages with lazy loading in the order of the array specified in `files`. It then overrides the locale messages in the order in which they were loaded.

In the above `es-AR` example, which has `es.json` and `es-AR.json` defined in `files`. In this case, @nuxtjs/i18n lazy-loads `es.json`, then it lazy-loads `es-AR.json` and overrides `es.json` locale messages.

In the example above, only two files are defined for `files`, of course you can specify more files over 2 files. In that case, the files will be loaded and override in array order too.

By taking advantage of the characteristic that locale messages are overridden in sequence, it's possible to manage locale messages by defining them on a differential basis. By adding shared (common) locale messages as the first entry of `files`, followed by file entries of regional/dialectal locale messages, it's possible to manage resources while avoiding the duplication of locale messages.

## Caching

Lazy loaded locale messages are cached based on their filename, `file` and `files` shared across locales will be used from cache once loaded. By default caching is enabled for static files, and disabled for files that return messages via a function.

Caching can be configured per file by setting `file` or entries of `files` to objects with the following type signature `{ path: string, cache?: boolean}`. The example below demonstrates several valid file configurations.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  i18n: {
    locales: [
      /**
       * Example definition with `files` for Spanish speaking countries
       */
      {
        code: 'es-ES',
        name: 'Español (Spain)',
        // file with cache disabled
        file: { path: 'es.js', cache: false }
      },
      {
        code: 'es-AR',
        name: 'Español (Argentina)',
        // files with cache disabled
        files: [
          { path: 'es.js', cache: false },
          { path: 'es-AR.js', cache: false }
        ]
      },
      {
        code: 'es-UY',
        name: 'Español (Uruguay)',
        // strings and object configurations can be mixed
        files: [{ path: 'es.js', cache: false }, 'es-UY.json']
      }
    ],
    defaultLocale: 'en'
  }
})
```

## Using translations of non-loaded locale

As only the current locale translations are loaded you have to manually load a locale to be able to use its translations.

Nuxt i18n extends Vue i18n to provide the `loadLocaleMessages` function to manually load locale messages, the example below demonstrates its usage.

```ts
const { loadLocaleMessages, t } = useI18n()

await loadLocaleMessages('nl')

const welcome = computed(() => t('welcome')) // Welcome!
const welcomeDutch = computed(() => t('welcome', 1, { locale: 'nl' })) // Welkom!
```

::callout{icon="i-heroicons-light-bulb"}
As messages could be loaded from a remote API invoking the 

`loadLocaleMessages`

 function will always load messages, unnecessary loading can impact performance.
::


# Lang Switcher

When **Nuxt i18n module** is loaded in your app, it adds your `locales` configuration to `nuxtApp.$i18n` (or `this.$i18n`), which makes it really easy to display a lang switcher anywhere in your app.

Here's an example of a lang switcher where a `name` key has been added to each locale object in order to display friendlier titles for each link:

```vue
<script setup>
const { locale, locales } = useI18n()
const switchLocalePath = useSwitchLocalePath()

const availableLocales = computed(() => {
  return locales.value.filter(i => i.code !== locale.value)
})
</script>

<template>
  <NuxtLink v-for="locale in availableLocales" :key="locale.code" :to="switchLocalePath(locale.code)">
    {{ locale.name }}
  </NuxtLink>
</template>
```

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  i18n: {
    locales: [
      {
        code: 'en',
        name: 'English'
      },
      {
        code: 'es',
        name: 'Español'
      },
      {
        code: 'fr',
        name: 'Français'
      }
    ]
  }
})
```

::callout{icon="i-heroicons-light-bulb"}
To persist the locale on a route change when using 

`detectBrowserLanguage`

, you must explicitly update the stored locale cookie. This is done with 

[`setLocaleCookie(locale)`](https://i18n.nuxtjs.org/docs/api/vue-i18n#setlocalecookie)

 or 

[`setLocale(locale)`](https://i18n.nuxtjs.org/docs/api/vue-i18n#setlocale)

, which sets the cookie and switches to the route of the specified locale. Not doing so can cause redirects based on the locale set on the locale cookie during navigation.
::

The template code might look like this, for example:

```vue
<script setup>
const { locale, locales, setLocale } = useI18n()

const availableLocales = computed(() => {
  return locales.value.filter(i => i.code !== locale.value)
})
</script>

<template>
  ...
  <a href="#" v-for="locale in availableLocales" :key="locale.code" @click.prevent.stop="setLocale(locale.code)">
    {{ locale.name }}
  </a>
  ...
</template>
```

## Wait for page transition

By default, the locale will be changed right away when navigating to a route with a different locale which means that if you have a page transition, it will fade out the page with the text already switched to the new language and fade back in with the same content.

To work around the issue, you can set the option [`skipSettingLocaleOnNavigate`](https://i18n.nuxtjs.org/docs/api/options#skipsettinglocaleonnavigate) to `true`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} and handle setting the locale yourself from a `onBeforeEnter` transition hook defined in a plugin.

### Global transition

If you would like to transition the entire Nuxt app, you can use the [`transition` of `NuxtPage`](https://nuxt.com/docs/getting-started/transitions#transition-with-nuxtpage){rel="&#x22;nofollow&#x22;"} to control it as follows:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  i18n: {
    // ... your other options
    skipSettingLocaleOnNavigate: true
  }
}
```

```vue [pages/app.vue]
<script setup lang="ts">
const { finalizePendingLocaleChange } = useI18n()

const onBeforeEnter = async () => {
  await finalizePendingLocaleChange()
}
</script>

<template>
  <NuxtLayout>
    <NuxtPage
      :transition="{
        name: 'my',
        mode: 'out-in',
        onBeforeEnter
      }"
    />
  </NuxtLayout>
</template>

<style>
.my-enter-active,
.my-leave-active {
  transition: opacity 0.3s;
}
.my-enter,
.my-leave-active {
  opacity: 0;
}
</style>
```

Optional, wait for locale before scrolling for a smoother transition with [Router Options](https://nuxt.com/docs/guide/directory-structure/pages#router-options){rel="&#x22;nofollow&#x22;"}:

```ts [app/router.options.ts]
import type { RouterConfig } from '@nuxt/schema'

export default <RouterConfig>{
  async scrollBehavior(to, from, savedPosition) {
    const nuxtApp = useNuxtApp()

    // make sure the route has changed.
    if (nuxtApp.$i18n && to.name !== from.name) {
      // `$i18n` is injected in the `setup` of the nuxtjs/i18n module.
      // `scrollBehavior` is guarded against being called even when it is not completed
      await nuxtApp.$i18n.waitForPendingLocaleChange()
    }

    return savedPosition || { top: 0 }
  }
}
```

### Per page component transition

If you have a specific transition defined in a page component with [`definePageMeta()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}](https://nuxt.com/docs/guide/directory-structure/pages#page-metadata){rel="&#x22;nofollow&#x22;"} and need to add `finalizePendingLocaleChange` at `onBeforeEnter` hook for `pageTransition`.

Example:

```vue [pages/about.vue]
<script setup lang="ts">
const route = useRoute()
const { finalizePendingLocaleChange } = useI18n()

definePageMeta({
  pageTransition: {
    name: 'page',
    mode: 'out-in'
  }
})

route.meta.pageTransition.onBeforeEnter = async () => {
  await finalizePendingLocaleChange()
}
</script>

<style scoped>
.page-enter-active,
.page-leave-active {
  transition: opacity 1s;
}
.page-enter,
.page-leave-active {
  opacity: 0;
}
</style>
```

## Vue i18n caveat

In contrast to Vue i18n you should not directly set `locale`, switch language by using [`setLocale()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}](https://i18n.nuxtjs.org/docs/api/vue-i18n#setlocale) or navigating to a route returned by [`switchLocalePath()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}](https://i18n.nuxtjs.org/docs/composables/use-switch-locale-path). This loads translations, triggers hooks and updates the locale cookie if used.


# Different Domains

You might want to use a different domain name for each language your app supports.

Here is how to achieve this:

- Set `differentDomains` option to `true`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}
- Configure the `locales` option as an array of objects, where each object has a `domain` key whose value is the domain name you'd like to use for that locale. Optionally include a port (if non-standard) and/or a protocol. If the protocol is not provided then an attempt will be made to auto-detect it but that might not work correctly in some cases like when the pages are statically generated.
- Optionally set `detectBrowserLanguage` to `false`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}. When enabled (which it is by default), user can get redirected to a different domain on first visit. Set to `false`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} if you want to ensure that visiting given domain always shows page in the corresponding locale.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  i18n: {
    locales: [
      {
        code: 'en',
        domain: 'mydomain.com'
      },
      {
        code: 'es',
        domain: 'es.mydomain.com'
      },
      {
        code: 'fr',
        domain: 'fr.mydomain.com'
      },
      {
        code: 'pl',
        domain: 'http://pl.mydomain.com'
      },
      {
        code: 'ua',
        domain: 'https://ua.mydomain.com'
      }
    ],
    differentDomains: true
    // Or enable the option in production only
    // differentDomains: (process.env.NODE_ENV === 'production')
  }
})
```

When using different domain names, your lang switcher should use regular `<a>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="html"} tags:

```vue
<script setup>
const { locale, locales } = useI18n()
const switchLocalePath = useSwitchLocalePath()

const availableLocales = computed(() => {
  return locales.value.filter(i => i.code !== locale.value)
})
</script>

<template>
  ...
  <a v-for="locale in availableLocales" :href="switchLocalePath(locale.code)" :key="locale.code">
    {{ locale.code }}
  </a>
  ...
</template>
```

## Runtime environment variables

Sometimes there's a need to change domains in different environments, e.g. staging and production.
As `nuxt.config.ts` is used at build time it would be necessary to create different builds for different environments.

```ts [locale-domains.config.ts]
export const localeDomains = {
  uk: process.env.DOMAIN_UK,
  fr: process.env.DOMAIN_FR
}
```

```ts [nuxt.config.ts]
import { localeDomains } from './locale-domains.config'

export default defineNuxtConfig({
  modules: ['@nuxtjs/i18n'],

  i18n: {
    differentDomains: process.env.NODE_ENV === 'production',
    locales: [
      {
        code: 'uk',
        domain: localeDomains.uk
      },
      {
        code: 'fr',
        domain: localeDomains.fr
      }
    ]
  }
})
```

With the above config, a build would have to be run for staging and production with different .env files that specify `DOMAIN_UK` and `DOMAIN_FR`.

Alternatively, to avoid the need for multiple builds, the locale domains can be overridden via runtime environment variables. The variable name should follow the format `NUXT_PUBLIC_I18N_DOMAIN_LOCALES_{code}_DOMAIN`

For example:

```shell [production.env]
NUXT_PUBLIC_I18N_DOMAIN_LOCALES_UK_DOMAIN=uk.example.test
NUXT_PUBLIC_I18N_DOMAIN_LOCALES_FR_DOMAIN=fr.example.test
```

```shell [staging.env]
NUXT_PUBLIC_I18N_DOMAIN_LOCALES_UK_DOMAIN=uk.staging.example.test
NUXT_PUBLIC_I18N_DOMAIN_LOCALES_FR_DOMAIN=fr.staging.example.test
```

## Using different domains for only some of the languages

If one or more of the domains need to host multiple languages, the default language of each domain needs to have `domainDefault: true`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} so there is a per domain fallback locale.
The option `differentDomains` still need to be set to `true`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} though.

```js [nuxt.config.js]
export default defineNuxtConfig({
  // ...
  i18n: {
    locales: [
      {
        code: 'en',
        domain: 'mydomain.com',
        domainDefault: true
      },
      {
        code: 'pl',
        domain: 'mydomain.com'
      },
      {
        code: 'ua',
        domain: 'mydomain.com'
      },
      {
        code: 'es',
        domain: 'es.mydomain.com',
        domainDefault: true
      },
      {
        code: 'fr',
        domain: 'fr.mydomain.com',
        domainDefault: true
      }
    ],
    strategy: 'prefix',
    differentDomains: true
    // Or enable the option in production only
    // differentDomains: (process.env.NODE_ENV === 'production')
  },
  // ...
})
```

Given above configuration with the `'prefix'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} strategy, following requests will be:

- <https://mydomain.com>{rel="&#x22;nofollow&#x22;"} -> <https://mydomain.com/en>{rel="&#x22;nofollow&#x22;"} (en language)
- <https://mydomain.com/pl>{rel="&#x22;nofollow&#x22;"} -> <https://mydomain.com/pl>{rel="&#x22;nofollow&#x22;"} (pl language)
- <https://mydomain.com/ua>{rel="&#x22;nofollow&#x22;"} -> <https://mydomain.com/ua>{rel="&#x22;nofollow&#x22;"} (ua language)
- <https://es.mydomain.com>{rel="&#x22;nofollow&#x22;"} -> <https://es.mydomain.com/es>{rel="&#x22;nofollow&#x22;"} (es language)
- <https://fr.mydomain.com>{rel="&#x22;nofollow&#x22;"} -> <https://fr.mydomain.com/fr>{rel="&#x22;nofollow&#x22;"} (fr language)

The same requests when using the `'prefix_except_default'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} strategy, will be:

- <https://mydomain.com>{rel="&#x22;nofollow&#x22;"} -> <https://mydomain.com>{rel="&#x22;nofollow&#x22;"} (en language)
- <https://mydomain.com/pl>{rel="&#x22;nofollow&#x22;"} -> <https://mydomain.com/pl>{rel="&#x22;nofollow&#x22;"} (pl language)
- <https://mydomain.com/ua>{rel="&#x22;nofollow&#x22;"} -> <https://mydomain.com/ua>{rel="&#x22;nofollow&#x22;"} (ua language)
- <https://es.mydomain.com>{rel="&#x22;nofollow&#x22;"} -> <https://es.mydomain.com>{rel="&#x22;nofollow&#x22;"} (es language)
- <https://fr.mydomain.com>{rel="&#x22;nofollow&#x22;"} -> <https://fr.mydomain.com>{rel="&#x22;nofollow&#x22;"} (fr language)

## Caching considerations with different domains

When using different domains, make sure to configure caching properly so that
responses are correctly separated per domain.

Because the same route may be served under multiple domains (e.g. `en.mydomain.com`
and `fr.mydomain.com`), caches need to vary by the request host. Otherwise,
a response generated for one domain could be reused on another, causing the wrong language to render,
leading to hydration mismatches and visible flashes on the client.

The recommended setup is to use `cache.varies: ['host']` in your route rules,
so that the `host` header is included in the cache key:

```diff [nuxt.config.ts]
export default defineNuxtConfig({
  routeRules: {
-    '/': { swr: 60 },
+    '/': { swr: 60, cache: { varies: ['host'] } },
  },
  // ...
})
```


# Multi domain locales

How to set up multi domain locales:

- Set the `multiDomainLocales` option to `true`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}
- Configure the `locales`option as an array of objects:
  - Each object has a `domains` key whose value is a array of the domains you'd like to use for that locale. Optionally include a port (if non-standard) and/or a protocol. If the protocol is not provided then an attempt will be made to auto-detect it but that might not work correctly in some cases like when the pages are statically generated.
  - Optionally set for each object a `defaultForDomains` key whose value is a array of the default domains you'd like to use for that locale. Optionally include a port (if non-standard) and/or a protocol. If the protocol is not provided then an attempt will be made to auto-detect it but that might not work correctly in some cases like when the pages are statically generated.
- Optionally set `detectBrowserLanguage` to `false`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}. When enabled (which it is by default), user can get redirected to a different domain on first visit. Set to `false`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} if you want to ensure that visiting given domain always shows page in the corresponding locale.

```ts [nuxt.config.ts]
const i18nDomains = ['mydomain.com', 'es.mydomain.com', 'fr.mydomain.com', 'http://pl.mydomain.com', 'https://ua.mydomain.com']

export default defineNuxtConfig({
  i18n: {
    locales: [
      {
        code: 'en',
        domains: i18nDomains,
        defaultForDomains: ['mydomain.com']
      },
      {
        code: 'es',
        domains: i18nDomains,
        defaultForDomains: ['es.mydomain.com']
      },
      {
        code: 'fr',
        domains: i18nDomains,
        defaultForDomains: ['fr.mydomain.com']
      },
      {
        code: 'pl',
        domains: i18nDomains,
        defaultForDomains: ['http://pl.mydomain.com']
      },
      {
        code: 'ua',
        domains: i18nDomains,
        defaultForDomains: ['https://ua.mydomain.com']
      },
      {
        code: 'nl',
        domains: i18nDomains
      },
      {
        code: 'de',
        domains: i18nDomains
      },
    ],
    multiDomainLocales: true
  }
})
```

## Runtime environment variables

Sometimes there's a need to change domains in different environments, e.g. staging and production.
As `nuxt.config.ts` is used at build time it would be necessary to create different builds for different environments.

```ts [locale-domains.config.ts]
export const localeDomains = {
  uk: process.env.DOMAIN_UK,
  fr: process.env.DOMAIN_FR
}
```

```ts [nuxt.config.ts]
import { localeDomains } from './locale-domains.config'

const i18nDomains = [localeDomains.uk, localeDomains.fr]

export default defineNuxtConfig({
  modules: ['@nuxtjs/i18n'],

  i18n: {
    multiDomainLocales: true,
    locales: [
      {
        code: 'uk',
        domains: i18nDomains,
        defaultForDomains: [localeDomains.uk]
      },
      {
        code: 'fr',
        domains: i18nDomains,
        defaultForDomains: [localeDomains.fr]
      }
    ]
  }
})
```

With the above config, a build would have to be run for staging and production with different .env files that specify `DOMAIN_UK` and `DOMAIN_FR`.

## Using different domains for only some of the languages

If multiple domains share the same default language, you can specify them all using `defaultForDomains`, which supports multiple domains.

```js [nuxt.config.js]
const i18nDomains = ['mydomain.com', 'en.mydomain.com', 'es.mydomain.com', 'fr.mydomain.com', 'http://pl.mydomain.com', 'https://ua.mydomain.com']

export default defineNuxtConfig({
  // ...
  i18n: {
    locales: [
      {
        code: 'en',
        domains: i18nDomains,
        defaultForDomains: ['mydomain.com', 'en.mydomain.com']
      },
      {
        code: 'es',
        domains: i18nDomains,
        defaultForDomains: ['es.mydomain.com']
      },
      {
        code: 'fr',
        domains: i18nDomains,
        defaultForDomains: ['fr.mydomain.com']
      },
      {
        code: 'pl',
        domains: i18nDomains,
        defaultForDomains: ['http://pl.mydomain.com']
      },
      {
        code: 'ua',
        domains: i18nDomains,
        defaultForDomains: ['https://ua.mydomain.com']
      },
      {
        code: 'nl',
        domains: i18nDomains
      },
      {
        code: 'de',
        domains: i18nDomains
      },
    ],
    strategy: 'prefix',
    multiDomainLocales: true
  },
  // ...
})
```

Given above configuration with the `'prefix'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} strategy, following requests will be:

- <https://mydomain.com>{rel="&#x22;nofollow&#x22;"} -> <https://mydomain.com/en>{rel="&#x22;nofollow&#x22;"} (en language)
- <https://mydomain.com/pl>{rel="&#x22;nofollow&#x22;"} -> <https://mydomain.com/pl>{rel="&#x22;nofollow&#x22;"} (pl language)
- <https://mydomain.com/ua>{rel="&#x22;nofollow&#x22;"} -> <https://mydomain.com/ua>{rel="&#x22;nofollow&#x22;"} (ua language)
- <https://mydomain.com/nl>{rel="&#x22;nofollow&#x22;"} -> <https://mydomain.com/nl>{rel="&#x22;nofollow&#x22;"} (nl language)
- <https://en.mydomain.com>{rel="&#x22;nofollow&#x22;"} -> <https://en.mydomain.com/en>{rel="&#x22;nofollow&#x22;"} (en language)
- <https://es.mydomain.com>{rel="&#x22;nofollow&#x22;"} -> <https://es.mydomain.com/es>{rel="&#x22;nofollow&#x22;"} (es language)
- <https://fr.mydomain.com>{rel="&#x22;nofollow&#x22;"} -> <https://fr.mydomain.com/fr>{rel="&#x22;nofollow&#x22;"} (fr language)
- <https://fr.mydomain.com/de>{rel="&#x22;nofollow&#x22;"} -> <https://fr.mydomain.com/de>{rel="&#x22;nofollow&#x22;"} (de language)

The same requests when using the `'prefix_except_default'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} strategy, will be:

- <https://mydomain.com>{rel="&#x22;nofollow&#x22;"} -> <https://mydomain.com>{rel="&#x22;nofollow&#x22;"} (en language)
- <https://mydomain.com/pl>{rel="&#x22;nofollow&#x22;"} -> <https://mydomain.com/pl>{rel="&#x22;nofollow&#x22;"} (pl language)
- <https://mydomain.com/ua>{rel="&#x22;nofollow&#x22;"} -> <https://mydomain.com/ua>{rel="&#x22;nofollow&#x22;"} (ua language)
- <https://mydomain.com/nl>{rel="&#x22;nofollow&#x22;"} -> <https://mydomain.com/nl>{rel="&#x22;nofollow&#x22;"} (nl language)
- <https://en.mydomain.com>{rel="&#x22;nofollow&#x22;"} -> <https://en.mydomain.com>{rel="&#x22;nofollow&#x22;"} (en language)
- <https://es.mydomain.com>{rel="&#x22;nofollow&#x22;"} -> <https://es.mydomain.com>{rel="&#x22;nofollow&#x22;"} (es language)
- <https://fr.mydomain.com>{rel="&#x22;nofollow&#x22;"} -> <https://fr.mydomain.com>{rel="&#x22;nofollow&#x22;"} (fr language)
- <https://fr.mydomain.com/de>{rel="&#x22;nofollow&#x22;"} -> <https://fr.mydomain.com/de>{rel="&#x22;nofollow&#x22;"} (de language)


# Locale fallback

**Nuxt i18n module** takes advantage of **Vue I18n** ability to handle localization fallback. It is possible to define a single fallback locale, an array of locales,
or a decision map for more specific needs.

```js [i18n/i18n.config.ts]
export default {
  fallbackLocale: 'en',
  // or
  fallbackLocale: ['en', 'fr'],
  // or
  fallbackLocale: {
    'de-CH': ['fr', 'it'],
    'zh-Hant': ['zh-Hans'],
    'es-CL': ['es-AR'],
    es: ['en-GB'],
    pt: ['es-AR'],
    default: ['en', 'da']
  }
  // ...
}
```

More information in [Vue I18n documentation](https://vue-i18n.intlify.dev/guide/essentials/fallback.html){rel="&#x22;nofollow&#x22;"}


# Per-Component Translations

If you'd like to define translations per-page or per-component you can take advantage of the i18n custom block.

You can now define translations using i18n custom blocks in your Vue files:

```vue [page.vue]
<script setup lang="ts">
const { t } = useI18n({
  useScope: 'local'
})
</script>

<template>
  <p>{{ t('hello') }}</p>
</template>

<i18n lang="json">
{
  "en": {
    "hello": "hello world!"
  },
  "ja": {
    "hello": "こんにちは、世界!"
  }
}
</i18n>
```

or using the Yaml syntax:

```vue [page.vue]
<!-- same script and template as above  -->
<i18n lang="yaml">
en:
  hello: 'hello world!'
ja:
  hello: 'こんにちは、世界!'
</i18n>
```

::callout{icon="i-heroicons-light-bulb"}
Read more about 

[i18n custom blocks](https://vue-i18n.intlify.dev/guide/advanced/sfc.html){rel=""nofollow""}
::

::callout{color="warning" icon="i-heroicons-exclamation-triangle"}
When you use per-component translations, you will need to use 

`t()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

 exported by 

`useI18n()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

, 

**not `$t()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}**

.
To read more about 

`$t()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

 which isn't used in per-component translation, see the 

["implicit with injected properties and functions" section of Vue I18n docs](https://vue-i18n.intlify.dev/guide/advanced/composition.html#implicit-with-injected-properties-and-functions){rel=""nofollow""}

.
::


# Extending messages hook

If you're a **module author** and want that module to provide extra messages for your project, you can merge them into the normally loaded messages by using the `'i18n:registerModule'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} hook.

This is particularly useful if your module uses translated content and you want to offer nice default translations.

In your module's setup file listen to the Nuxt `'i18n:registerModule'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} hook and
register your i18n configuration, this is similar to how [lazy-load translations](https://i18n.nuxtjs.org/docs/guide/lazy-load-translations) are configured.

Translations added this way will be loaded after those added in your project, and before extended layers.

Example:

::code-group
```ts [my-module-example/module.ts]
import { createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  async setup(options, nuxt) {
    const { resolve } = createResolver(import.meta.url)

    nuxt.hook('i18n:registerModule', register => {
      register({
        // langDir path needs to be resolved
        langDir: resolve('./lang'),
        locales: [
          {
            code: 'en',
            file: 'en.json',
          },
          {
            code: 'fr',
            file: 'fr.json',
          },
        ]
      })
    })
  }
})
```

```json [en.json]
{
  "my-module-example": {
    "hello": "Hello from external module"
  }
}
```

```json [fr.json]
{
  "my-module-example": {
    "hello": "Bonjour depuis le module externe"
  }
}
```
::

Now the project has access to new messages and can use them through `$t('my-module-example.hello')`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}.

::callout{icon="i-heroicons-light-bulb"}
Because module's messages are merged with the project's ones, it's safer to prefix them. Main project messages 

**will always override**

 messages provided by modules.
::


# Extending pages

If you're a **module author** and want your module to add extra pages to your project, you can add these by using the `'pages:extend'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} Nuxt hook.

```ts [modules/example-module/index.ts]
import { defineNuxtModule, createResolver } from '@nuxt/kit'

export default defineNuxtModule({
  setup(options, nuxt) {
    const { resolve } = createResolver(import.meta.url)

    nuxt.hook('pages:extend', pages => {
      pages.push({
        name: 'example-page',
        path: '/example-page',
        file: resolve(__dirname, './pages/example-page.vue')
      })
    })
  }
})
```


# Layers

Nuxt i18n module supports layers and will automatically combine i18n configuration of all extended layers. [Read more about layers here](https://nuxt.com/docs/getting-started/layers){rel="&#x22;nofollow&#x22;"}

## Merging strategy

As described in the [Nuxt layer authoring guide](https://nuxt.com/docs/guide/going-further/layers#multi-layer-support-for-nuxt-modules){rel="&#x22;nofollow&#x22;"}

> - Earlier items in the `_layers` array have higher priority and override later ones
> - The user's project is the first item in the `_layers` array

Mixing locale configuration such as lazy loading objects and strings may not work as expected, Nuxt i18n will attempt to merge layers as best it can. Consistency of i18n configuration between layers will be most effective.

## Pages & Routing

Pages in the `pages` directory from extended layers will automatically be merged and have i18n support as if they were part of your project.

Page routes defined in `i18n.pages` in each layer configuration will be merged as well.

## Locales

A project extending a layer set up with the Nuxt i18n module needs no additional set up as shown in this example:

::code-group
```ts [nuxt.config.ts]
export default defineNuxtConfig({
  extends: ['my-layer']
})
```

```ts [my-layer/nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/i18n'],
  i18n: {
    locales: [
      { code: 'en', file: 'en.json' },
      { code: 'nl', file: 'nl.json' }
    ]
  }
})
```
::

The project is able to use i18n functionality and the configured locales would be loaded provided by the extended layer.

### Merging locales

Locales provided by a project will be merged with those provided by extended layers, this can be done as follows:

::code-group
```ts [nuxt.config.ts]
export default defineNuxtConfig({
  extends: ['my-layer'],
  i18n: {
    locales: [{ code: 'en', file: 'en.json' }]
  }
})
```

```ts [my-layer/nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/i18n'],
  i18n: {
    locales: [
      { code: 'en', file: 'en.json' },
      { code: 'nl', file: 'nl.json' }
    ]
  }
})
```
::

This example would result in the project supporting two locales (`'en'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, `'nl'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}) and would add the additional messages added for the `'en'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} locale.

::code-group
```ts [project/i18n/locales/en.json]
{
  "title": "foo"
}
```

```ts [project/my-layer/i18n/locales/en.json]
{
  "title": "layer title",
  "description": "bar"
}
```
::

The above will result in the following

```jsonc
{
  // earlier layers take priority
  "title": "foo",
  "description": "bar"
}
```

## VueI18n options

Options defined in VueI18n configuration files within layers are merged and override each other according to their layers priority.


# Server-Side Translations

You can do the translation on the server-side and return it as a response. The locale messages defined in nuxt i18n module options are integrated, so all you need to do is configure the locale detector.

::callout{color="warning" icon="i-heroicons-exclamation-triangle"}
**This feature is experimental,**

 that is supported from v8 RC8.
::

## Define locale detector

For server-side translation, you need to define a locale detector.

Nuxt i18n exports the `defineI18nLocaleDetector()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} composable function to define it.

The following is an example of how to define a detector that detects locale using query, cookie, and header:

```ts [i18n/localeDetector.ts]
// Detect based on query, cookie, header
export default defineI18nLocaleDetector((event, config) => {
  // try to get locale from query
  const query = tryQueryLocale(event, { lang: '' }) // disable locale default value with `lang` option
  if (query) {
    return query.toString()
  }

  // try to get locale from cookie
  const cookie = tryCookieLocale(event, { lang: '', name: 'i18n_locale' }) // disable locale default value with `lang` option
  if (cookie) {
    return cookie.toString()
  }

  // try to get locale from header (`accept-header`)
  const header = tryHeaderLocale(event, { lang: '' }) // disable locale default value with `lang` option
  if (header) {
    return header.toString()
  }

  // If the locale cannot be resolved up to this point, it is resolved with the value `defaultLocale` of the locale config passed to the function
  return config.defaultLocale
})
```

The locale detector function is used to detect the locale on the server-side. It's called per request on the server.

When you define the locale detector, you need to pass the path to the locale detector to the `experimental.localeDetector` option.

The following is an example of a locale detector configuration defined directly in the Nuxt application:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  i18n: {
    experimental: {
      localeDetector: 'localeDetector.ts'
    }
  }
})
```

For details on the locale detector function defined by `defineI18nLocaleDetector()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}, see [here](https://i18n.nuxtjs.org/docs/composables/define-i18n-locale-detector).

## `useTranslation()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} on eventHandler

To translate on the server-side , you need to call `useTranslation()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}.

Example:

```ts
// you need to define `async` event handler
export default defineEventHandler(async event => {
  // call `useTranslation`, so it return the translation function
  const t = await useTranslation(event)
  return {
    // call translation function with key of locale messages,
    // and translation function has some overload
    hello: t('hello')
  }
})
```

::callout{icon="i-heroicons-light-bulb"}
For the key of the translation function, you can specify the locale messages set in the nuxt-i18n options inside the nuxt.config, or the locale loaded in the i18n.config messages.
::


# Module integration

If your module depends on Nuxt i18n, you can use `moduleDependencies`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} to declare the dependency and define default or override options. See Nuxt's [Module Author Guide](https://nuxt.com/docs/4.x/guide/modules/recipes-basics#use-other-modules){rel="&#x22;nofollow&#x22;"} for more information.

You will need to resolve paths for `vueI18n`, `langDir`, and those configured in `locales` to absolute paths:

```ts
import { createResolver, defineNuxtModule } from '@nuxt/kit'

const resolver = createResolver(import.meta.url)

export default defineNuxtModule({
  moduleDependencies: {
    '@nuxtjs/i18n': {
      defaults: {
        vueI18n: resolver.resolve('./i18n.config.ts'),
        langDir: resolver.resolve('./lang'),
        locales: [
          { code: 'en', file: resolver.resolve('./lang/en.json') },
          { code: 'fr', file: resolver.resolve('./lang/fr.json') },
        ]
      }
    }
  },
  // ...
})
```


# Migration Guide

## Upgraded to Vue I18n v11

We have upgraded from Vue I18n v10 to v11, this major version bump deprecates the Legacy API mode and custom `v-t` directive, and removes `tc()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} and `$tc()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} from Legacy API mode.

Check the documentation detailing the breaking changes [here](https://vue-i18n.intlify.dev/guide/migration/breaking11.html){rel="&#x22;nofollow&#x22;"}.

## Configuration options

The following [Configuration options](https://i18n.nuxtjs.org/docs/api/options) have been changed, deprecated, or removed.

| Status | Option                                                                                                                                                                                                              | Notes                                                                                                                                                                                                                  |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|        | `experimental.hmr`{.language-yml.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="yml"}                                                                                      | Enabled by default and renamed to [`hmr`{.language-yml.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="yml"}](https://i18n.nuxtjs.org/docs/api/options#hmr)                    |
|        | `experimental.switchLocalePathLinkSSR`{.language-yml.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="yml"}                                                                  | Enabled by default and the option to disable it has been removed.                                                                                                                                                      |
|        | `experimental.autoImportTranslationFunctions`{.language-yml.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="yml"}                                                           | Enabled by default and renamed to [`autoDeclare`{.language-yml.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="yml"}](https://i18n.nuxtjs.org/docs/api/options#autodeclare)    |
|        | [`restructureDir`{.language-yml.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="yml"}](https://i18n.nuxtjs.org/docs/api/options#restructuredir)                             | This can no longer be disabled. :br:br We recommend leaving this unset to use the default value of `'i18n'`{.language-ts.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts"}. |
|        | [`types`{.language-yml.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="yml"}](https://i18n.nuxtjs.org/docs/api/options#types)                                               | Only `'composition'`{.language-yml.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="yml"} types will be supported in v11, in line with Vue I18n v12.                            |
|        | [`baseUrl`{.language-yml.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="yml"}](https://i18n.nuxtjs.org/docs/api/options#baseurl)                                           | Will only allow string values and will no longer support function configuration in v11. :br:br Use runtime config or rely on multi domain locales to set the base URL for complex setups.                              |
|        | [`routesNameSeparator`{.language-yml.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="yml"}](https://i18n.nuxtjs.org/docs/api/options#routesnameseparator)                   | This was documented as internal, use cases for end-users are unclear.                                                                                                                                                  |
|        | [`defaultLocaleRouteNameSuffix`{.language-yml.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="yml"}](https://i18n.nuxtjs.org/docs/api/options#defaultlocaleroutenamesuffix) | This was documented as internal, use cases for end-users are unclear.                                                                                                                                                  |
|        | `lazy`{.language-yml.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="yml"}                                                                                                  | Lazy loading of locale messages is now enabled for all locale files.                                                                                                                                                   |
|        | `bundle.optimizeTranslationDirective`{.language-yml.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="yml"}                                                                   | This feature has been disabled and fully removed, see [the discussion in this issue](https://github.com/nuxt-modules/i18n/issues/3238#issuecomment-2672492536){rel="&#x22;nofollow&#x22;"} for context on this change. |
|        | `experimental.generatedLocaleFilePathFormat`{.language-yml.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="yml"}                                                            | File paths (e.g. locale files, vue-i18n configs) configured for this module are now removed from the build entirely making this option obsolete.                                                                       |

## Behavior Changes

### Browser Language Detection

Language detection and redirection have been improved to follow documented behavior strictly. In v9, some combinations of `strategy`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="yml"} and `redirectOn`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="yml"} options worked unexpectedly, which has been corrected in v10.

**Key Change**: When using `strategy: 'prefix'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} with `redirectOn: 'root'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} , non-root paths (e.g., `'/search'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}) will no longer automatically redirect to their localized versions (e.g., `'/zh/search'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}).

**Migration**: If you need redirection for all paths with a prefix strategy, update your configuration:

```diff
export default defineNuxtConfig({
  i18n: {
    strategy: 'prefix',
    detectBrowserLanguage: {
-      // redirectOn: 'root', // ⚠️ In v10 this will only redirect the root path
+      redirectOn: 'all',  // Redirects all paths as documented
    }
  }
})
```

**Impact**: This affects projects using `strategy: 'prefix'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} that relied on the previous unintended behavior where `redirectOn: 'root'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} also handled non-root paths.

See the [`redirectOn`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="yml"} documentation](https://i18n.nuxtjs.org/docs/api/options#redirecton) for more details about the available options.

## I18n functions

The following composables and [I18n functions](https://i18n.nuxtjs.org/docs/api/vue-i18n) have been changed, deprecated, or removed.

| Status | Function                                                                                                                                                                                | Notes                                                                                                                                                                                                                                                                                                                          |
| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|        | [`useLocaleHead()`{.language-ts.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts"}](https://i18n.nuxtjs.org/docs/composables/use-locale-head) | The `key`{.language-yml.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="yml"} property on the options parameter has been removed and can no longer be configured, this is necessary for predictable and consistent localized head tag management.                                      |
|        | `onLanguageSwitched()`{.language-ts.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts"}                                                        | Use the [`'i18n:localeSwitched'`{.language-ts.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts"}](https://i18n.nuxtjs.org/docs/guide/runtime-hooks) hook instead. :br:br This function actually called the hook instead of subscribing to it, leading to unpredictable behavior.     |
|        | `onBeforeLanguageSwitch()`{.language-ts.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts"}                                                    | Use the [`'i18n:beforeLocaleSwitch'`{.language-ts.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts"}](https://i18n.nuxtjs.org/docs/guide/runtime-hooks) hook instead. :br:br This function actually called the hook instead of subscribing to it, leading to unpredictable behavior. |

## Context functions

The following [context functions](https://i18n.nuxtjs.org/docs/api/nuxt) have been changed, deprecated, or removed.

| Status | Function                                                                                                                                                                      | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|        | [`$localeHead()`{.language-ts.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts"}](https://i18n.nuxtjs.org/docs/api/nuxt#localehead) | The `key`{.language-yml.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="yml"} property on the options parameter has been removed and can no longer be configured, this is necessary for predictable and consistent localized head tag management.                                                                                                                                                                                                                                                                                                                |
|        | [`$localeHead()`{.language-ts.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts"}](https://i18n.nuxtjs.org/docs/api/nuxt#localehead) | Use the `useLocaleHead()`{.language-ts.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts"} composable instead. :br:br Deprecated due to limited use cases, the [`useLocaleHead()`{.language-ts.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts"}](https://i18n.nuxtjs.org/docs/composables/use-locale-head) composable offers the same functionality and is easier to use in combination with `useHead()`{.language-ts.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts"}. |
|        | `$getRouteBaseName()`{.language-ts.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts"}                                               | Use [`$routeBaseName()`{.language-ts.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts"}](https://i18n.nuxtjs.org/docs/api/nuxt#routebasename) instead. :br:br Deprecated in favor of the same function under a new name: [`$routeBaseName()`{.language-ts.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts"}](https://i18n.nuxtjs.org/docs/api/nuxt#routebasename), to be consistent with the other context functions and their composable counterparts.                                                             |
|        | `$resolveRoute()`{.language-ts.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts"}                                                   | Use [`$localeRoute()`{.language-ts.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts"}](https://i18n.nuxtjs.org/docs/api/nuxt#localeroute) instead                                                                                                                                                                                                                                                                                                                                                                                                              |
|        | `$localeLocation()`{.language-ts.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts"}                                                 | Use [`$localeRoute()`{.language-ts.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts"}](https://i18n.nuxtjs.org/docs/api/nuxt#localeroute) instead                                                                                                                                                                                                                                                                                                                                                                                                              |

## Runtime config

Several options set in the runtime config were only used to transfer build-time configuration to runtime and changing these at runtime could cause issues.

Instead of setting these on runtime config we now treat them as compiler constants, this way we can tree-shake any unused logic from a project build.

The following options have been removed from runtime config:

| Removed runtime config option                                                                                                              |
| ------------------------------------------------------------------------------------------------------------------------------------------ |
| `lazy`{.language-yml.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="yml"}                         |
| `strategy`{.language-yml.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="yml"}                     |
| `trailingSlash`{.language-yml.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="yml"}                |
| `differentDomains`{.language-yml.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="yml"}             |
| `defaultDirection`{.language-yml.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="yml"}             |
| `multiDomainLocales`{.language-yml.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="yml"}           |
| `routeNameSeparator`{.language-yml.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="yml"}           |
| `defaultLocaleRouteNameSuffix`{.language-yml.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="yml"} |

## Generated options

The generated options files in your projects are meant for internal use by this module at runtime and should never be used, more properties may be removed in the future.

Future changes to these internal options will not be documented in the migration guide. If you have use cases for these options, please open an issue describing your use case so we can evaluate if we can support it differently.

The generated option files have been renamed:

| Old Name                                                                                                                                 | New Name                                                                                                                                 |
| ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `#build/i18n-options.mjs`{.language-yml.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="yml"}    | `#build/i18n-options.mjs`{.language-yml.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="yml"}    |
| `#internal/i18n/options.mjs`{.language-yml.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="yml"} | `#internal/i18n-options.mjs`{.language-yml.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="yml"} |

The following exports have been removed from the generated options:

| Removed Export                                                                                                                                   |
| ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `isSSG`{.language-yml.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="yml"}                              |
| `hasPages`{.language-yml.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="yml"}                           |
| `parallelPlugin`{.language-yml.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="yml"}                     |
| `nuxtI18nOptions`{.language-yml.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="yml"}                    |
| `DEFAULT_COOKIE_KEY`{.language-yml.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="yml"}                 |
| `DYNAMIC_PARAMS_KEY`{.language-yml.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="yml"}                 |
| `NUXT_I18N_MODULE_ID`{.language-yml.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="yml"}                |
| `SWITCH_LOCALE_PATH_LINK_IDENTIFIER`{.language-yml.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="yml"} |

Reasons for removal:

- These are no longer used by the module and might expose vulnerable information in the final build
- Some options are now used as static values for better tree-shaking resulting in a smaller project build.

## Legacy migration

The migration guides for v7 and v8 can be found in the [legacy documentation](https://v9.i18n.nuxtjs.org/docs/guide/migrating){rel="&#x22;nofollow&#x22;"}


# New features

### Custom routes via `definePageMeta()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

We have added support for setting custom routes for pages using the `definePageMeta()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} API, which is now the recommended way to set custom routes for pages.
This method is enabled by setting `customRoutes: 'meta'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} in the module options.

To migrate from the `defineI18nRoute()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} macro, you can simply replace it with `definePageMeta()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} and set the `i18n` property with the same options:

```vue [pages/about.vue]
<script setup>
definePageMeta({
  i18n: {
    paths: {
      en: '/about-us',
      fr: '/a-propos',
    }
  }
})
</script>
```

### Nitro-side language detection and redirection

Language detection and redirection has been reimplemented to be handled from the Nitro server, this allows us to redirect requests earlier in the request lifecycle which improves performance.

The previous implementation did not work correctly when combined with prerendering which this new implementation does.

While this change makes detection and redirection more accurate and should better match the documented behavior, if this causes issues in your project it can be disabled by setting `experimental.nitroContextDetection: false`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="yml"} in the module options. The option to disable this feature is temporary and will be removed in a future version.

### Experimental strict SEO mode

We have added a new experimental option `strictSeo`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="yml"} that enables strict SEO mode, which changes the way i18n head tags are handled.

With strict SEO mode enabled, the i18n head tags are managed internally, this allows for some much requested improvements:

- The module will no longer add alternate tags for unsupported locales when setting localized dynamic route params.
- Unsupported locale links used with `<SwitchLocalePathLink>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} are disabled, their links will be set to `'#'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} and will have a `data-i18n-disabled`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} attribute for styling purposes.
- The `useLocaleHead()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} is no longer needed in strict SEO mode, i18n tags are automatically set by the module and usage will throw an error.
- Canonical query parameters are configured globally with `experimental.strictSeo.canonicalQueryParams`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="yml"}.
- The `useSetI18nParams()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} inherits the global canonical query parameter config which can be overridden through its options parameter.

If this mode proves stable it will become the default in v11, please try it out and report any issues you encounter.

### Compact routes

We have added a new experimental option `compactRoutes`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="yml"} that changes how locale-prefixed routes are generated. Instead of creating a separate route for every locale, eligible routes are compacted into a single route using a regex parameter for the locale segment.

For example, with three locales (`en`, `fr`, `ja`) and the `prefix` strategy, the `/about` page would normally produce three routes:

```text
/en/about
/fr/about
/ja/about
```

With `compactRoutes` enabled, these are compacted into a single route:

```text
/:locale(en|fr|ja)/about
```

This can be enabled in `nuxt.config.ts`:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  i18n: {
    experimental: {
      compactRoutes: true
    }
  }
})
```

**Why this is an improvement:**

- **Fewer routes** — Applications with many pages and locales can generate a large number of routes (pages × locales). Compact routes significantly reduces this, resulting in a smaller route table and faster route matching.
- **Smaller bundle size** — The router configuration shipped to the client is more compact, which reduces the JavaScript payload.
- **Better scalability** — The number of routes stays proportional to the number of pages rather than growing multiplicatively with the number of locales.

**How it works with different strategies:**

- `prefix` — All locales are compacted into a single route.
- `prefix_except_default` — The default locale keeps its unprefixed route, while all other locales are compacted into a single route.
- `prefix_and_default` — The default locale keeps its unprefixed route, and all locales (including the default) are compacted into a single route.

**When routes cannot be compacted:**

Not all routes are eligible for compaction. A route will still be generated per locale when:

- It has custom per-locale paths defined (e.g., `/about` in English but `/a-propos` in French).
- It is not available for all configured locales (e.g., a route is disabled for certain locales).

In these cases, the module automatically falls back to the standard per-locale route generation for that specific route, while still compacting all eligible routes.

::callout{icon="i-heroicons-light-bulb"}
This option is opt-in for now but is expected to become the default in v11. Please try it out and report any issues you encounter.
::

::callout{color="warning" icon="i-heroicons-exclamation-triangle"}
This option is not compatible with 

`no_prefix`

 strategy, 

`differentDomains`

, or 

`multiDomainLocales`

.
::


# Options

## vueI18n

- type: `string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- default: `''`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Build-time configuration for Vue I18n options that is used internally by this module. See full documentation at [here](https://vue-i18n.intlify.dev/api/general.html#createi18n){rel="&#x22;nofollow&#x22;"}

Configuration for `createI18n()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} can be passed using a configuration file. By default, the module will scan for a `i18n.config{.js,.mjs,.ts}` if nothing is specified.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/i18n'],
  i18n: {
    vueI18n: './nuxt-i18n.js' // custom path example
  }
})
```

You need to `export default` with **plain object** or **function**.

Export with plain object example:

```ts
export default {
  legacy: false,
  locale: 'en',
  messages: {
    en: {
      welcome: 'Welcome'
    },
    fr: {
      welcome: 'Bienvenue'
    }
  }
}
```

Export with function example:

```ts
import en from '../locales/en.json'
import fr from '../locales/fr.yaml'

// You can use `defineI18nConfig` to get type inferences for options to pass to vue-i18n.
export default defineI18nConfig(() => {
  return {
    legacy: false,
    locale: 'en',
    messages: {
      en,
      fr
    }
  }
})
```

::callout{color="warning" icon="i-heroicons-exclamation-triangle"}
The Vue I18n `messages` option should be returned **by the plain object**.

That will be pre-compiled in the nuxt i18n module via vue-i18n message-compiler as an executable message in the vue-i18n runtime.
::

## baseUrl

- type: `string | Function`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- default: `''`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

The fallback base URL to use as a prefix for alternate URLs in `hreflang` tags. By default VueRouter's base URL will be used and only if that is not available, fallback URL will be used.

Can also be a function (will be passed a Nuxt Context as a parameter) that returns a string. Useful to make base URL dynamic based on request headers.

This property can also be set using [`runtimeConfig`](https://i18n.nuxtjs.org/docs/api/runtime-config).

::callout{icon="i-heroicons-light-bulb"}
It's especially important to set this option when using SEO features, in which case it's required that generated SEO tags use fully-qualified URLs.
::

## locales

- type: `string[] | LocaleObject[]`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- default: `[]`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

List of locales supported by your app. Can either be an array of language codes (`['en', 'fr', 'es']`) or an array of locale objects for more complex configurations:

```json
[
  { "code": "en", "language": "en-US", "file": "en.js", "dir": "ltr" },
  { "code": "ar", "language": "ar-EG", "file": "ar.js", "dir": "rtl" },
  { "code": "fr", "language": "fr-FR", "file": "fr.js" }
]
```

When using an object form, the properties can be:

### `code`

- type: `string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- Unique identifier of the locale

### `language`

- type: `undefined | string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- **Required when using SEO features**
- A language-range used for SEO features and for matching browser locales when using [`detectBrowserLanguage`](https://i18n.nuxtjs.org/docs/api/options#detectbrowserlanguage) functionality. Should use the [language tag syntax](https://www.w3.org/International/articles/language-tags/){rel="&#x22;nofollow&#x22;"} as defined by the IETF's [BCP47](https://www.rfc-editor.org/info/bcp47){rel="&#x22;nofollow&#x22;"}, for example:
  - `'en'` (`language` subtag for English)
  - `'fr-CA'` (`language+region` subtags for French as used in Canada)
  - `'zh-Hans'` (`language+script` subtags for Chinese written with Simplified script)

### `file`

- type: `null | string | { path: string; cache: string; }`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- The name of the file. Will be resolved relative to `langDir` path when loading locale messages from file.

### `files`

- type: `null | string[] | { path: string; cache: string; }[]`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- The name of the file in which multiple locale messages are defined. Will be resolved relative to `langDir` path when loading locale messages from file.

See also [Multiple files lazy loading](https://i18n.nuxtjs.org/docs/guide/lazy-load-translations#multiple-files-lazy-loading) to learn more.

### `dir`

- type: `null | 'rtl' | 'ltr' | 'auto'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- The dir property specifies the direction of the elements and content, value could be `'rtl'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, `'ltr'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} or `'auto'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}.

### `domain`

- type: `null | string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- The domain name you'd like to use for that locale (including the port if used). This property can also be set using [`runtimeConfig`](https://i18n.nuxtjs.org/docs/api/runtime-config). This property is required when using [`differentDomains`](https://i18n.nuxtjs.org/docs/api/options#differentdomains)

### `domains`

- type: `null | string[]`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- An array of `domain`. This property is required when using [`multiDomainLocales`](https://i18n.nuxtjs.org/docs/api/options#multiDomainLocales) while one or more of the domains having multiple of the same locales

### `defaultForDomains`

- type: `null | string[]`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- (optional when using [`multiDomainLocales`](https://i18n.nuxtjs.org/docs/api/options#multiDomainLocales))
- An array of `domain` for which the locale should be the default locale when using `domains`.

### `domainDefault`

- type: `null | boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- Set `domainDefault` to `true` for each locale that should act as a default locale for the particular domain. This property is required when using [`differentDomains`](https://i18n.nuxtjs.org/docs/api/options#differentdomains) while one or more of the domains having multiple locales

### `...`

- any custom property set on the object will be exposed at runtime. This can be used, for example, to define the language name for the purpose of using it in a language selector on the page.

You can access all the properties of the current locale through the `localeProperties` property. When using an array of codes, it will only include the `code` property.

## defaultDirection

- type: `string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- default: `ltr`

The app's default direction. Will only be used when `dir` is not specified.

## defaultLocale

- type: `string | null`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- default: `null`

The app's default locale. Should match the language code of one of the defined `locales`.

When using `prefix_except_default` strategy, URLs for locale specified here won't have a prefix. **It's recommended to set this to some locale** regardless of chosen strategy, as it will be used as a fallback locale when navigating to a non-existent route.

## strategy

- type: `'no_prefix' | 'prefix_except_default' | 'prefix' | 'prefix_and_default'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- default: `'prefix_except_default'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Routes generation strategy. Can be set to one of the following:

- `'no_prefix'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}: routes won't have a locale prefix
- `'prefix_except_default'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}: locale prefix added for every locale except default
- `'prefix'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}: locale prefix added for every locale
- `'prefix_and_default'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}: locale prefix added for every locale and default

## customRoutes

- type: `'meta' | 'page' | 'config'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- default: `'page'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Whether [custom paths](https://i18n.nuxtjs.org/docs/guide/custom-paths) are extracted from page files or configured in the module configuration:

- `'meta'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}: custom paths are extracted from the `definePageMeta()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} function in page components.
- `'page'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}: custom paths are extracted from the `defineI18nRoute()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} macro in page components.
- `'config'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}: custom paths are configured in the `pages` option of the module configuration.

## pages

- type: `object`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- default: `{}`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

If `customRoutes` option is disabled with `config`, the module will look for custom routes in the `pages` option. Refer to the [Routing](https://i18n.nuxtjs.org/docs/guide) for usage.

## skipSettingLocaleOnNavigate

- type: `boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- default: `false`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

If `true`, the locale will not be set when navigating to a new locale. This is useful if you want to wait for the page transition to end before setting the locale yourself using [`finalizePendingLocaleChange`](https://i18n.nuxtjs.org/docs/api/vue-i18n#finalizependinglocalechange). See more information in [Wait for page transition](https://i18n.nuxtjs.org/docs/guide/lang-switcher#wait-for-page-transition).

## defaultLocaleRouteNameSuffix

- type: `string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- default: `'default'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Internal suffix added to generated route names for default locale, if strategy is `prefix_and_default`. You shouldn't need to change this.

## routesNameSeparator

- type: `string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- default: `'___'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Internal separator used for generated route names for each locale. You shouldn't need to change this.

## rootRedirect

- type: `string | { statusCode: number; path: string; } | null`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- default: `null`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

Set to a path to which you want to redirect users accessing the root URL (`'/'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}). Accepts either a string or an object with `statusCode` and `path` properties. E.g

```json
{
  "statusCode": 301,
  "path": "about-us"
}
```

## redirectStatusCode

- type: `number`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- default: `302`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

Specifies the HTTP status code to use when redirecting to a localized route from any URL except the root URL ('/').

## langDir

- type: `string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- default: `locales`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

A relative path to a directory containing translation files to load.

The path is resolved relative to the project `restructureDir` at the root of a project (`'i18n'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} by default).

::callout{color="warning" icon="i-heroicons-exclamation-triangle"}
Absolute paths will fail in production (eg. 

`'/locales'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

 should be changed into either 

`'locales'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

 or 

`'./locales'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

)
::

## detectBrowserLanguage

- type: `object | boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Enables browser language detection to automatically redirect visitors to their preferred locale as they visit your site for the first time.

See also [Browser language detection](https://i18n.nuxtjs.org/docs/guide/browser-language-detection) for a guide.

::callout{icon="i-heroicons-light-bulb"}
Note that for better SEO it's recommended to set 

`redirectOn`

 to 

`'root'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

.
::

Set to `false`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} to disable.

Supported properties:

### `alwaysRedirect`

- type: `boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- default: `false`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

Set to always redirect to the value stored in the cookie, not just on first visit.

### `fallbackLocale`

- type: `string | null`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

If none of the locales match the browser's locale, use this one as a fallback.

### `redirectOn`

- type: `string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- default: `'root'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Supported options:

- `'all'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} - detect browser locale on all paths.
- `'root'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} (recommended for improved SEO) - only detect the browser locale on the root path (`'/'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}) of the site. Only effective when using strategy other than `'no_prefix'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}.
- `'no prefix'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} - a more permissive variant of `'root'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} that will detect the browser locale on the root path (`'/'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}) and also on paths that have no locale prefix (like `'/foo'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}). Only effective when using strategy other than `'no_prefix'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}.

### `useCookie`

- type: `boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- default: `true`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

If enabled, a cookie is set once the user has been redirected to browser's preferred locale, to prevent subsequent redirects. Set to `false` to redirect every time.

### `cookieKey`

- type: `string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- default: `'i18n_redirected'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Cookie name.

### `cookieDomain`

- type: `string | null`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- default: `null`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

Set to override the default domain of the cookie. Defaults to the **host** of the site.

### `cookieCrossOrigin`

- type: `boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- default: `false`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

When `true`, sets the flags `SameSite=None; Secure` on the cookie to allow cross-domain use of the cookie (required when app is embedded in an iframe).

### `cookieSecure`

- type: `boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- default: `false`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

Sets the `Secure` flag for the cookie.

## differentDomains

- type: `boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- default: `false`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

Set this to `true`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} when using different domains for each locale, with this enabled you MUST configure locales as an array of objects, each containing a `domain` key. Refer to the [Different domains](https://i18n.nuxtjs.org/docs/guide/different-domains) for more information.

## multiDomainLocales

- type: `boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- default: `false`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

Set this to `true` when using different domains with different locales. If enabled, you MUST configure locales as an array of objects, each containing a `domains` and `defaultForDomains` key. Refer to the [Multi Domain Locales](https://i18n.nuxtjs.org/docs/guide/multi-domain-locales) for more information.

## compilation

- type: `object`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- default: `{ strictMessage: true, escapeHtml: false }`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

Configure flags that sets the behavior compilation of locale messages.

Supported properties:

### `strictMessage`

- type: `boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- default: `true`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

Strictly check that the locale message does not contain HTML tags. If HTML tags are included, an error is thrown.

::callout{color="warning" icon="i-heroicons-exclamation-triangle"}
If you do not want the error to be thrown, you can work around it by setting it to false. However, 

**this means that the locale message might cause security issues with XSS**

. In that case, we recommend setting the 

`escapeHtml`

 option to 

`true`

.
::

### `escapeHtml`

- type: `boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- default: `false`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

Determine whether to escape HTML tags if they are included in the locale message.

::callout{color="warning" icon="i-heroicons-exclamation-triangle"}
If 

`strictMessage`

 is disabled by setting it to 

`false`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

, we recommend enabling this option.
::

## bundle

- type: `object`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- default: `{ compositionOnly: true, runtimeOnly: false, fullInstall: true, dropMessageCompiler: false }`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

Configure the bundling optimization for nuxt i18n module.

Supported properties:

### `compositionOnly`

- type: `boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- default: `true`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

Whether to make vue-i18n API only composition API. By default the legacy API is tree-shaken. For more details, See [here](https://vue-i18n.intlify.dev/guide/advanced/optimization.html#reduce-bundle-size-with-feature-build-flags){rel="&#x22;nofollow&#x22;"}

::callout{color="warning" icon="i-heroicons-exclamation-triangle"}
If you would like to use Vue I18n's Legacy API, you must set `compositionOnly: false`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}. **Note that setting this value will disable Vue I18n Composition API**.

Note that the Legacy API can also be used in hybrid by setting the Vue I18n option to `allowComposition: true`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} in i18n.config, but this is limited. See [here](https://vue-i18n.intlify.dev/guide/migration/vue3.html){rel=""nofollow""} for details.
::

### `runtimeOnly`

- type: `boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- default: `false`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

Whether or not to automatically use Vue I18n runtime-only in build.

::callout{color="warning" icon="i-heroicons-exclamation-triangle"}
When you will enable this option, vue-i18n message compiler is not bundled. This means that you will not be able to dynamically retrieve locale messages for use in your application from back-end APIs via fetch, or programmatically compose the locale messages. That is to say, 

**you must be able to fully resolve locale messages at build time.**
::

### `fullInstall`

- type: `boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- default: `true`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

Whether to install the full set of APIs, components, etc. By default, all of them will be installed. If `false`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} is specified, built-in components (`<i18n-t>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="html"}, `<i18n-d>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="html"} and `<i18n-n>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="html"}) and directive (`v-t`) will not be installed in vue and will be tree-shaken. For more details, See [here](https://vue-i18n.intlify.dev/guide/advanced/optimization.html#reduce-bundle-size-with-feature-build-flags){rel="&#x22;nofollow&#x22;"}

### `dropMessageCompiler`

- type: `boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- default: `false`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

Whether to tree-shake message compiler when bundling.

::callout{color="warning" icon="i-heroicons-exclamation-triangle"}
If you enable this option, 

**you should check that resources in your application are pre-compiled with nuxt i18n module**

. If you will be loading resources dynamically from the back-end via the API, enabling this option will not work because there is no message compiler.
::

### `onlyLocales`

- type: `string | string[]`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- default: `undefined`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

Specify the locales codes that need to be included, the rest will be removed.

It can be useful if you have one code base (e.g. [Nuxt Layers](https://nuxt.com/docs/getting-started/layers){rel="&#x22;nofollow&#x22;"}) for several similar projects using different languages.

::callout{color="warning" icon="i-heroicons-exclamation-triangle"}
The value of this 

**option will not be merged with other Nuxt Layers**

. This option should only be specified in the final project config.
::

## experimental

Experimental configuration property is an object with the following properties:

### `localeDetector`

- type: `string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- default: `''`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}
- Specify the locale detector to be called per request on the server side. You need to specify the filepath where the locale detector is defined.

::callout{color="warning" icon="i-heroicons-exclamation-triangle"}
For more details on how to define the locale detector, see the 

[`defineI18nLocaleDetector()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} API](https://i18n.nuxtjs.org/docs/composables/define-i18n-locale-detector)
::

### `strictSeo`

- type: `boolean | SeoAttributesOptions`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- default: `false`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}
- Enables strict SEO mode.

### `typedPages`

- type: `boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- default: `true`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}
- Generates route types used in composables and configuration, this feature is enabled by default when Nuxt's `experimental.typedPages` is enabled.

::callout{color="warning" icon="i-heroicons-exclamation-triangle"}
This feature relies on 

[Nuxt's `experimental.typedPages`](https://nuxt.com/docs/guide/going-further/experimental-features#typedpages){rel=""nofollow""}

 and will not work if this is not enabled.
::

### `typedOptionsAndMessages`

- type: `false | 'default' | 'all'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
  - `false`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} - disables type generation
  - `'default'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} - generate types based on configured `defaultLocale`
  - `'all'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} - generate types based on all configured locales
- default: `false`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}
- Generate `vue-i18n` and message types used in translation functions and `vue-i18n` configuration. Can be configured to use the `defaultLocale` (better performance) or all locales for type generation.

### `alternateLinkCanonicalQueries`

- type: `boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- default: `true`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}
- Remove non-canonical query parameters from alternate link meta tags

### `httpCacheDuration`

- type: `number`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- default: `10`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}
- HTTP cache duration for the messages API endpoint in seconds. This controls how long browsers cache the translation data. Set to a higher value (e.g., `86400` for 24 hours) to reduce redundant network requests for unchanged translations.

### `compactRoutes`

- type: `boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- default: `false`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}
- Consolidates locale-prefixed routes into a single regex route instead of generating separate routes for each locale. This option is not compatible with `no_prefix` strategy, `differentDomains`, or `multiDomainLocales`.

::callout{icon="i-heroicons-light-bulb"}
This option is opt-in for now but is expected to become the default in v11. See 

[Compact routes](https://i18n.nuxtjs.org/docs/guide/new-features#compact-routes)

 for more details.
::

## `hmr`

- type: `boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- default: `true`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}
- Hot module replacement for locale message files and vue-i18n configuration in dev mode.

::callout{color="warning" icon="i-heroicons-exclamation-triangle"}
This functionality is only supported for projects using vite.
::

## customBlocks

Configure the `i18n` custom blocks of SFC.

Supported properties:

### `defaultSFCLang`

- type: `'json' | 'json5' | 'yaml' | 'yml'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- default: `'json'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- Specify the content for all your inlined i18n custom blocks on your SFC. For more details refer to [unplugin-vue-i18n documentation](https://github.com/intlify/bundle-tools/blob/main/packages/unplugin-vue-i18n/README.md#defaultsfclang){rel="&#x22;nofollow&#x22;"}

On inlined `i18n` custom blocks that have specified the `lang` attribute, the `defaultSFCLang` is not applied.

For example, with `defaultSFCLang: "yaml"`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} or `defaultSFCLang: "yml"`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}, this custom block:

```vue
<i18n lang="yaml">
en:
  hello: Hello
es:
  hello: Hola
</i18n>
```

Would be equivalent to this:

```vue
<i18n>
en:
  hello: Hello
es:
  hello: Hola
</i18n>
```

### `globalSFCScope`

- type: `boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- default: `false`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}
- Whether to include all `i18n` custom blocks on your SFC on global scope. For more details refer to [unplugin-vue-i18n documentation](https://github.com/intlify/bundle-tools/blob/main/packages/unplugin-vue-i18n/README.md#globalsfcscope){rel="&#x22;nofollow&#x22;"}

::callout{color="warning" icon="i-heroicons-exclamation-triangle"}
beware enabling 

`globalSFCScope: true`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

, all 

`i18n`

 custom blocks in all your 

`SFC`

 will be on 

`global`

 scope.
::

For example, with `globalSFCScope: true`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}, this custom block:

```vue
<i18n lang="yaml" global>
en:
  hello: Hello
es:
  hello: Hola
</i18n>
```

Would be equivalent to this:

```vue
<i18n lang="yaml">
en:
  hello: Hello
es:
  hello: Hola
</i18n>
```

This combines with `defaultSFCLang`, with `defaultSFCLang: "yaml"`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} the following would be equivalent to the previous examples:

```vue
<i18n>
en:
  hello: Hello
es:
  hello: Hola
</i18n>
```

## types

- type: `'composition' | 'legacy'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- default: `'composition'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Enforces the type definition of the API style to be used.

- Set to `'composition'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, Composition API types provided by Vue I18n and `@nuxtjs/i18n` are supported,
- Set to `'legacy'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, Options API types are supported.

::callout{color="warning" icon="i-heroicons-exclamation-triangle"}
You may need to run 

`nuxi prepare`

 for the generated types to update.
::

## debug

- type: `boolean | 'verbose'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- default: `false`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

Whether to use `@nuxtjs/i18n` debug mode. If `true` or `'verbose'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, logs will be output to the console, setting this to `'verbose'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} will also log loaded messages objects.

::callout{color="warning" icon="i-heroicons-exclamation-triangle"}
The purpose of this option is to help identify any problems with `@nuxtjs/i18n`.

You should not enable this option in production as it will negatively impact performance.
::

## parallelPlugin

- type: `boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- default: `false`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

Set the plugin as `parallel`. See [nuxt plugin loading strategy](https://nuxt.com/docs/guide/directory-structure/plugins#loading-strategy){rel="&#x22;nofollow&#x22;"}.

## restructureDir

- type: `string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- default: `'i18n'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Used to configure the directory used to resolve i18n files.

## autoDeclare

- type: `boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- default: `true`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}
- Automatically imports/initializes `$t()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}, `$rt()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}, `$d()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}, `$n()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}, `$tm()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} and `$te()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} functions in `<script setup>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="html"} when used.

::callout{color="warning" icon="i-heroicons-exclamation-triangle"}
This feature relies on 

[Nuxt's Auto-imports](https://nuxt.com/docs/guide/concepts/auto-imports){rel=""nofollow""}

 and will not work if this has been disabled.
::

## serverRoutePrefix

- type `string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- default: `'/_i18n'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

Sets the prefix for the server route used for loading locale messages.


# Vue I18n

::callout{icon="i-heroicons-light-bulb"}
Instance of 

[Composer (for Composition API)](https://vue-i18n.intlify.dev/api/composition.html#composer){rel=""nofollow""}

 or 

[VueI18n (for Legacy API)](https://vue-i18n.intlify.dev/api/legacy.html#vuei18n){rel=""nofollow""}

 is exposed as 

`$i18n`

 on Vue instance.
::

### `getLocaleCookie()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

- **Arguments**:
  - no arguments
- **Returns**: `string | undefined`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Returns locale code from stored locale cookie.

### `setLocaleCookie()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

- **Arguments**:
  - locale (type: `string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"})
- **Returns**: `undefined`

Updates stored locale cookie with specified locale code. Consider using `setLocale` instead if you want to switch locale.

### `setLocale()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

- **Arguments**:
  - locale (type: `string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"})
- **Returns**: `Promise<void>`

Switches locale of the app to specified locale code. If `useCookie` option is enabled, locale cookie will be updated with new value. If prefixes are enabled (`strategy` other than `no_prefix`), will navigate to new locale's route.

### `loadLocaleMessages()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

- **Arguments**:
  - locale (type: `string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"})
- **Returns**: `Promise<void>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Loads the translation messages of the specified locale code, this is relevant for when using translations from a non-loaded locale.

### `getBrowserLocale()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

- **Arguments**:
  - no arguments
- **Returns**: `string | undefined`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Returns browser locale code filtered against the ones defined in options.

### `finalizePendingLocaleChange()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

- **Arguments**:
  - no arguments
- **Returns**: `Promise<void>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Switches locale to the pending locale, used when navigation locale switch is prevented by the [`skipSettingLocaleOnNavigate`](https://i18n.nuxtjs.org/docs/api/options#skipsettinglocaleonnavigate) option. See [Wait for page transition](https://i18n.nuxtjs.org/docs/guide/lang-switcher#wait-for-page-transition) for more information.

### `waitForPendingLocaleChange()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

- **Arguments**:
  - no arguments
- **Returns**: `Promise<void>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Returns a promise that will be resolved once the pending locale is set.

### strategy

- type: `Strategies`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Routing strategy as specified in options.

### defaultDirection

- **Type**: `Directions`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Default direction as specified in options.

### defaultLocale

- **Type**: `string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Default locale as specified in options.

### localeCodes

- **Type**: `Array<string>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

List of locale codes of registered locales.

### locales

- **Type**: `Array<string | LocaleObject>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

List of locales as defined in options.

### localeProperties

- **Type**: `LocaleObject`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Object of the current locale properties.

### differentDomains

- **Type**: `boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Whether `differentDomains` option is enabled.


# Vue

## Extension of Vue

::callout{color="warning" icon="i-heroicons-exclamation-triangle"}
The APIs listed are available in the Options API. They are kept for Nuxt2 to migration from 

`@nuxtjs/i18n`

. we will be deprecated in the future.
::

### `routeBaseName()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

- **Arguments**:
  - route (type: `string | Route`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"})
- **Returns**: `string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Returns base name of the passed route. The base name of a route is its name without a locale suffix or other metadata added by `@nuxtjs/i18n`.

### `switchLocalePath()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

- **Arguments**:
  - locale: (type: `Locale`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"})
- **Returns**: `string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Returns path of the current route for specified `locale`.

See also [Link localizing](https://i18n.nuxtjs.org/docs/getting-started/usage)

### `localePath()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

- **Arguments**:
  - route (type: `string | Location`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"})
  - locale (type: `Locale`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, default: current locale)
- **Returns**: `string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Returns localized path for the passed `route`. Uses the current `locale` by default.

See also [Link localizing](https://i18n.nuxtjs.org/docs/getting-started/usage)

### `localeRoute()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

- **Arguments**:
  - route (type: `string | Location`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"})
  - locale (type: `Locale`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, default: current locale)
- **Returns**: `Route | undefined`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Returns localized route for the passed `route`. Uses the current `locale` by default.

See also [Link localizing](https://i18n.nuxtjs.org/docs/getting-started/usage)

### `localeHead()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

- **Arguments**:
  - options: (type: `I18nHeadOptions`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"})
- **Returns**: `I18nHeadMetaInfo`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

The `options` object accepts these optional properties:

- `dir` (type: `boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}) - Adds a `dir` attribute to the HTML element. Default: `false`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}
- `seo` (type: `boolean | SeoAttributesOptions`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}) - Adds various SEO attributes. Default: `false`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

See also [SEO](https://i18n.nuxtjs.org/docs/guide/seo)


# Nuxt

## Extension of Nuxt runtime app context

The following APIs are exposed both on `NuxtApp`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}.

### `$i18n`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

- **Type**: [`VueI18n | Composer`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}]

See also [NuxtApp](https://nuxt.com/docs/guide/going-further/nuxt-app#accessing-nuxtapp){rel="&#x22;nofollow&#x22;"}

`$i18n`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} is the global `Composer`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} or global `VueI18n`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} instance of Vue I18n. See about details [here](https://vue-i18n.intlify.dev/api/general.html#i18n){rel="&#x22;nofollow&#x22;"}

If you set `i18n.vueI18n.legacy` option to `false`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} in your `@nuxtjs/i18n` configuration, `$i18n`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} is a global `Composer`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} instance. Otherwise, it is a global `VueI18n`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} instance.

Example use:

```ts
export default defineNuxtPlugin(nuxtApp => {
  nuxtApp.$i18n.onBeforeLanguageSwitch = (oldLocale, newLocale, isInitialSetup, nuxtApp) => {
    console.log('onBeforeLanguageSwitch', oldLocale, newLocale, isInitialSetup)
  }
})
```

### `$routeBaseName()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

### `$switchLocalePath()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

### `$localePath()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

### `$localeRoute()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

### `$localeHead()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

See more info about those in [Extension of Vue](https://i18n.nuxtjs.org/docs/api/vue) section.

## Extension of NuxtHooks

### `'i18n:registerModule'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} Hook

- **Arguments**:
  - registerModule (type: `({ langDir: string, locales: LocaleObject[] }) => void`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"})

```ts [my-module-example/module.ts]
import { createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  async setup(options, nuxt) {
    const { resolve } = createResolver(import.meta.url)
    nuxt.hook('i18n:registerModule', register => {
      register({
        // langDir path needs to be resolved
        langDir: resolve('./lang'),
        locales: [
          {
            code: 'en',
            file: 'en.json',
          },
          {
            code: 'fr',
            file: 'fr.json',
          },
        ]
      })
    })
  }
})
```

See also [Extending messages hook](https://i18n.nuxtjs.org/docs/guide/extend-messages)


# Runtime config

Some options can be set via the `runtimeConfig`, setting options this way makes it possible to override these after building using environment variables.

## Usage

If you want to use environment variables to change [supported options](https://i18n.nuxtjs.org/#supported-options), you will have to set these in `runtimeConfig.public.i18n`.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
    modules: ['@nuxtjs/i18n'],
    i18n: {
        // Leave options unset that you want to set using `runtimeConfig`
        // baseUrl: 'https://example.com',
    },
    runtimeConfig: {
        public: {
            i18n: {
                baseUrl: 'https://example.com',
                domainLocales: {}
                // other options ...
            }
        }
    }
})
```

You can read more about how this works in the [Nuxt documentation](https://nuxt.com/docs/guide/going-further/runtime-config#environment-variables){rel="&#x22;nofollow&#x22;"}.

::callout{type="warning"}
Only 

[serializable values are supported](https://nuxt.com/docs/guide/going-further/runtime-config#serialization){rel=""nofollow""}

 in 

`runtimeConfig`

, options set this way may not support all available types (such as functions) as would normally be possible using the default configuration.
::

::callout{type="info"}
If you would like other options to be supported, open an issue describing your use case, or open a PR adding to add support yourself!
::

## Supported options

The module configuration takes precedence, options set through `runtimeConfig` will only be used if they are unset.

These options can be set using `runtimeConfig`:

### `baseUrl`

- key: `NUXT_PUBLIC_I18N_BASE_URL`

This runtime config option is the same as the [`baseUrl`](https://i18n.nuxtjs.org/docs/api/options#baseUrl) module option.

::callout{type="warning"}
Note that the 

`baseUrl`

 module option allows you to set the function, but the runtime config does not due to limitations.
::

### `domainLocales`

- property: `domainLocales[code].domain`
- key: `NUXT_PUBLIC_I18N_DOMAIN_LOCALES_{code}_DOMAIN`

This runtime config option allows overriding the domain set in the [`locales`](https://i18n.nuxtjs.org/docs/api/options#locales) module option.


# <NuxtLinkLocale>

This component is built on top of [`<NuxtLink>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="html"}](https://nuxt.com/docs/api/components/nuxt-link#nuxtlink){rel="&#x22;nofollow&#x22;"} but changes the default behavior by internally using [`localePath()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}](https://i18n.nuxtjs.org/docs/api/vue#localepath) to make it easier to link to localized routes.

### Props

This component supports all [props documented for `<NuxtLink>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="html"}](https://nuxt.com/docs/api/components/nuxt-link#props){rel="&#x22;nofollow&#x22;"} in addition to props described below.

| Prop     | Description                                                                                                                                                                                                                                            |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `locale` | Optional prop to force localization using passed Locale, it defaults to the current locale. Identical to `locale` argument of `localePath()`{.language-ts.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts"} |

### Examples

#### Basic usage

```vue
<template>
  <NuxtLinkLocale to="/">{{ $t('home') }}</NuxtLinkLocale>
</template>

<!-- equivalent to -->

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

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

#### Forcing locale resolution

```vue
<template>
  <NuxtLinkLocale to="/" locale="nl">{{ $t('home') }}</NuxtLinkLocale>
</template>

<!-- equivalent to -->

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

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


# <SwitchLocalePathLink>

This component acts as a constrained [`<NuxtLink>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="html"}](https://nuxt.com/docs/api/components/nuxt-link#nuxtlink){rel="&#x22;nofollow&#x22;"} which internally uses `switchLocalePath()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} to link to the same page in the provided locale.

We especially recommend using this component for language-switchers since it will correctly update routes using dynamic route parameters during server-side rendering.

### Props

This component supports most, but not all [props documented for `<NuxtLink>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="html"}](https://nuxt.com/docs/api/components/nuxt-link#props){rel="&#x22;nofollow&#x22;"} (does not support `to` or `href`) in addition to props described below.

| Prop     | Description                                                                                                                                                                                                                                                  |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `locale` | Optional prop to force localization using passed Locale, it defaults to the current locale. Identical to `locale` argument of `switchLocalePath()`{.language-ts.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts"} |

### Examples

#### Basic usage

```vue
<template>
  <SwitchLocalePathLink locale="nl">Dutch</SwitchLocalePathLink>
  <SwitchLocalePathLink locale="en">English</SwitchLocalePathLink>
</template>

<!-- equivalent to -->

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

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


# useLocalePath

The `useLocalePath()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} composable returns a function that resolves a path according to the current locale.

## Type

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

## Usage

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

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


# useLocaleRoute

The `useLocaleRoute()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} composable returns a function that resolves the route according to the current locale.

## Type

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

## Usage

```vue
<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>
```


# useSwitchLocalePath

The `useSwitchLocalePath()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} composable returns a function that allows to switch the locale.

## Type

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

## Usage

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

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


# useLocaleHead

The `useLocaleHead()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} composable returns localized head properties for locale-related aspects.

## Type

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

## Parameters

### `options`

An object accepting the following optional fields:

- `dir`
  - type: `boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}
  - default: `true`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}
  - Adds a `dir` attribute to the HTML element.
- `lang`
  - type: `boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}
  - default: `true`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}
  - Adds a `lang` attribute to the HTML element.
- `seo`
  - type: `boolean | SeoAttributesOptions`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}
  - Adds various SEO attributes.

## Usage

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


# useSetI18nParams

The `useSetI18nParams()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} returns a function to set translated parameters for the current route.
For more details on its usage see the [Lang Switcher guide](https://i18n.nuxtjs.org/docs/guide/lang-switcher#dynamic-route-parameters).

## Type

```ts
declare function useSetI18nParams(options?: SeoAttributesOptions): (locale: Record<Locale, unknown>) => void
```

## Parameters

### `options`

**Type**: `SeoAttributesOptions | undefined`

An `SeoAttributesOptions` object, default `undefined`. See the [SEO guide](https://i18n.nuxtjs.org/docs/guide/seo#feature-details) for more details.

## Usage

```vue
<script setup>
// fetch product from API... (red mug)

const setI18nParams = useSetI18nParams({
  canonicalQueries: ['foo']
})
setI18nParams({
  en: { slug: data.slugs.en }, // slug: 'red-mug'
  nl: { slug: data.slugs.nl } // slug: 'rode-mok'
})

const switchLocalePath = useSwitchLocalePath()
switchLocalePath('en') // /products/red-mug
switchLocalePath('nl') // /nl/products/rode-mok
</script>

<template>
  <!-- pages/products/[slug].vue -->
</template>
```


# useRouteBaseName

The `useRouteBaseName()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} composable returns a function that gets the route's base name.

## Type

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

## Usage

```vue
<script setup>
const route = useRoute()
const routeBaseName = useRouteBaseName()
const baseRouteName = computed(() => routeBaseName(route))
// or
const baseRouteNameString = computed(() => routeBaseName(route.name))
</script>

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


# useBrowserLocale

The `useBrowserLocale()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} 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

```ts
declare function useBrowserLocale(): string | null
```


# useCookieLocale

The `useCookieLocale()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} 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()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}. 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`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}, an **empty string** is always returned.

## Type

```ts
declare function useCookieLocale(): Ref<string>
```


# useTranslation

The `useTranslation()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} composable returns the translation function.

The locale used by the translation function is the locale detected by the function defined in [`experimental.localeDetector` option](https://i18n.nuxtjs.org/docs/api/options#experimental).

::callout{color="warning" icon="i-heroicons-exclamation-triangle"}
**This composable is experimental and server-side only.**
::

## Type

```ts
declare function useTranslation<Schema extends Record<string, any> = {}, Event extends H3Event = H3Event>(
  event: Event
): Promise<TranslationFunction<Schema, DefineLocaleMessage>>
```

## Usage

```ts
export default defineEventHandler(async event => {
  const t = await useTranslation(event)
  return {
    hello: t('hello')
  }
})
```


# defineI18nConfig

The `defineI18nConfig()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} composables is used to define a function which returns the vue-i18n configuration which is passed to the `createI18n()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} options on the Nuxt I18n module.

The loader function needs to return a Function or Promise that resolves a vue-i18n options object.

For more details on configuring vue-i18n, see the [Vue I18n documentation](https://vue-i18n.intlify.dev/api/general.html#createi18n){rel="&#x22;nofollow&#x22;"}.

## Type

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

## Parameters

### `loader`

A function that is the vue-i18n options loading.

## Usage

An example defining a simple vue-i18n options object:

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


# defineI18nLocale

The `defineI18nLocale()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} composable is used to define a function to dynamically load locale messages used for [lazy-loading translations](https://i18n.nuxtjs.org/docs/guide/lazy-load-translations).

The loader function needs to return a `Promise`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} that resolves a messages object.

## Type

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

## Parameters

### `loader`

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

- `locale`:br**Type**: `Locale`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}:br 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()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}.
  - when the locale is switched with `<NuxtLink>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="html"}. for example, the route path resolved by `useSwitchLocalePath()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} or `$switchLocalePath()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}.

## Usage

An example of a loader function using a fetch request to load locale messages:

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


# defineI18nLocaleDetector

The `defineI18nLocaleDetector()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} is composable used to define a function which detects the locale on the server-side, it's called per request on the server.

The function needs to return a locale string.

You can use [`@intlify/h3` utilities](https://github.com/intlify/h3#%EF%B8%8F-utilites--helpers){rel="&#x22;nofollow&#x22;"} in the locale detector function, these are auto imported.

::callout{color="warning" icon="i-heroicons-exclamation-triangle"}
**This composable is experimental.**

 You need to configure filepath to 

[`experimental.localeDetector` option](https://i18n.nuxtjs.org/docs/api/options#experimental)

.
::

## Type

```ts
type LocaleConfig = {
  defaultLocale: Locale
  fallbackLocale: FallbackLocale
}
declare function defineI18nLocaleDetector(
  detector: (event: H3Event, config: LocaleConfig) => string
): (event: H3Event, config: LocaleConfig) => string
```

## Parameters

### `detector`

A function that is the locale detector, that has the following parameters:

- `event`
  - type: `H3Event`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
  - An H3 event. see details [H3 API docs](https://www.jsdocs.io/package/h3#H3Event){rel="&#x22;nofollow&#x22;"}
- `config`
  - type: `object`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
  - A locale config that is passed from Nitro.
  - Properties:
    - `defaultLocale`
      - type: `Locale`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
      - This value is set to the `defaultLocale` option of Nuxt i18n. If unset, it is set to the `locale` option loaded from the Vue I18n configuration (`i18n.config` file set on the `vueI18n` option). If neither of these are set, the default value of `'en-US'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} is used.
    - `fallbackLocale`
      - type: `FallbackLocale`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
      - This value is set to the `fallbackLocale` option loaded from the Vue I18n configuration (`i18n.config` file set on the `vueI18n` option). If no fallback locale has been configured this will default to `false`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}.

## Usage

An example of a locale detector:

```ts
// Detect based on query, cookie, header
export default defineI18nLocaleDetector((event, config) => {
  const query = tryQueryLocale(event, { lang: '' })
  if (query) {
    return query.toString()
  }

  const cookie = tryCookieLocale(event, { lang: '', name: 'i18n_locale' })
  if (cookie) {
    return cookie.toString()
  }

  const header = tryHeaderLocale(event, { lang: '' })
  if (header) {
    return header.toString()
  }

  return config.defaultLocale
})
```


# defineI18nRoute

::callout
---
color: warning
icon: i-heroicons-exclamation-triangle
title: notice
---
This macro is deprecated in favor of setting localized paths using `definePageMeta()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} and will be removed in v11.

:br

See its [section in Custom Paths](https://i18n.nuxtjs.org/docs/guide/custom-paths#definepagemeta) for more details.
::

`defineI18nRoute()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} is a compiler macro that you can use to set custom route paths for your **page** components located in the `pages/` directory (unless [set otherwise](https://nuxt.com/docs/api/configuration/nuxt-config#pages-1){rel="&#x22;nofollow&#x22;"}). This way you can set custom route paths for each static or dynamic route of your Nuxt application.

```vue [pages/some-page.vue]
<script setup>
defineI18nRoute({
  paths: {
    en: '/about-us',
    fr: '/a-propos',
    ja: '/about-ja'
  }
})
</script>
```

## Type

```ts
defineI18nRoute(route: I18nRoute | false) => void

interface I18nRoute {
  paths?: Record<Locale, `/${string}`>
  locales?: Locale[]
}
```

## Parameters

### `false`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}

Disable localize for the target page component route.

### `I18nRoute`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

An object accepting the following i18n route settings:

- **`paths`**
  - **Type**: `Record<Locale, `/${string}`>`:br Customize page component routes per locale. You can specify static and dynamic paths for vue-router.
- **`locales`**
  - **Type**: `Locale[]`:br Some locales to which the page component should be localized.


# I18n for Nuxt Applications

::u-page-hero
---
links:
  - label: Get Started
    trailingIcon: i-heroicons-arrow-right-20-solid
    to: /docs/getting-started
    size: lg
  - label: Star on GitHub
    icon: i-simple-icons-github
    size: lg
    variant: ghost
    color: neutral
    to: https://github.com/nuxt-modules/i18n
    target: _blank
ui:
  container: relative overflow-hidden py-10 flex flex-col md:flex-row items-center gap-4
  description: dark:text-gray-400 text-xl max-w-2xl leading-normal mb-10
orientation: horizontal
---
#top
  :::div
  ---
  class: absolute z-[-1] rounded-full bg-(--ui-primary) blur-[300px] size-60
    sm:size-80 transform -translate-x-1/2 left-1/2 -translate-y-80
  ---
  :::

  :::div
  ---
  class: absolute -z-10 inset-0 h-full w-full
    bg-[radial-gradient(circle,var(--ui-color-primary-900)_1px,transparent_1px)]
    bg-[size:20px_20px]
  ---
  :::

#title
[I18n]{.lg:hidden!.inline}[Internationalization]{.hidden.lg:inline!} for [Nuxt Applications]{.text-primary}

#description
I18n (Internationalization) module for your Nuxt project powered by Vue I18n.

```bash [Terminal]
npx nuxi@latest module add i18n
```
::

::u-page-section{title="Build i18n-ready apps in seconds!"}
  :::u-page-grid
    ::::u-page-card
    ---
    icon: i-simple-icons-i18next
    to: https://i18n.nuxtjs.org/docs/getting-started
    ---
    #title
    Vue I18n Integration

    #description
    Powered by Nuxt 3 for optimal performances and SEO.
    ::::

    ::::u-page-card
    ---
    icon: i-heroicons-sparkles-20-solid
    to: https://i18n.nuxtjs.org/docs/guide
    ---
    #title
    Automatic Routes Generation

    #description
    Auto override of Nuxt default routes to add your locales prefixes to every URL.
    ::::

    ::::u-page-card
    ---
    icon: i-heroicons-presentation-chart-line
    to: https://i18n.nuxtjs.org/docs/guide/seo
    ---
    #title
    Search Engine Optimization

    #description
    Composables to add SEO metadata based on current locale.
    ::::

    ::::u-page-card
    ---
    icon: i-heroicons-rocket-launch
    to: https://i18n.nuxtjs.org/docs/guide/lazy-load-translations
    ---
    #title
    Messages Lazy-Loading

    #description
    Lazy-load only the language that the users selected instead of bundling all the messages.
    ::::

    ::::u-page-card
    ---
    icon: i-heroicons-arrows-right-left
    to: https://i18n.nuxtjs.org/docs/components/nuxt-link-locale
    ---
    #title
    Locale-Aware Redirection

    #description
    Ready to use composables to redirect based on current locale.
    ::::

    ::::u-page-card
    ---
    icon: i-heroicons-globe-alt
    to: https://i18n.nuxtjs.org/docs/guide/different-domains
    ---
    #title
    Locales Specific Domains

    #description
    Set a different domain name for each locale your app supports.
    ::::
  :::
::

::u-page-section
---
style: "max-width: 1000px; margin-left: auto; margin-right: auto;"
title: Sponsors
---
![Sponsors](https://raw.githubusercontent.com/bobbiegoede/static/main/sponsors.svg)
::