Nuxt i18n

https://i18n.nuxtjs.org/docs
Admin
Nuxt i18n is an internationalization (i18n) module for Nuxt applications powered by Vue I18n,...
Tokens:54,388
Snippets:446
Trust Score:9.9
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Example 3: Dynamic Routes - directory structure

Source: https://i18n.nuxtjs.org/docs/guide/custom-paths

Directory structure for dynamic routes example, showing a blog with date and slug parameters.

```text
-| pages/
---| blog/
-----| [date]/
-------| [slug].vue

```

--------------------------------

### Example 1: Basic URL localization - directory structure

Source: https://i18n.nuxtjs.org/docs/guide/custom-paths

Directory structure for the basic URL localization example, showing nested pages.

```text
-| pages/
---| parent/
-----| child.vue
---| parent.vue

```

--------------------------------

### Example 2: Localize the part of URL - directory structure

Source: https://i18n.nuxtjs.org/docs/guide/custom-paths

Directory structure for the URL localization example, showing nested services and development pages.

```text
-| pages/
---| about.vue
---| services/
-----| coaching.vue
-----| development/
-------| app.vue
-------| website.vue
-----| development.vue
---| services.vue

```

--------------------------------

### Example: globalSFCScope with defaultSFCLang

Source: https://i18n.nuxtjs.org/docs/api/options

Shows a custom i18n block without lang attribute, which is equivalent to the previous examples when both globalSFCScope and defaultSFCLang are set.

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

--------------------------------

### Install @nuxtjs/i18n with nuxi

Source: https://i18n.nuxtjs.org/docs/getting-started

Installs the @nuxtjs/i18n module as a dev dependency using the Nuxt CLI.

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

```

--------------------------------

### Switch locale with useSwitchLocalePath composable

Source: https://i18n.nuxtjs.org/docs/getting-started/usage

Use the useSwitchLocalePath composable in script setup to get localized paths for switching languages.

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

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

```

--------------------------------

### Generated routes for default language example

Source: https://i18n.nuxtjs.org/docs/guide

Generated routes for the example pages with English as default language. English routes have no prefix, French routes have '/fr' prefix.

```javascript
[
  {
    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",
  }
]

```

--------------------------------

### Usage with useHeadSafe

Source: https://i18n.nuxtjs.org/docs/composables/use-locale-head

Example of passing the returned value directly to useHeadSafe().

```vue
<script setup>
useHeadSafe(useLocaleHead())
</script>

```

--------------------------------

### Install I18n module with nuxi

Source: https://i18n.nuxtjs.org

Adds the I18n module to a Nuxt project using the Nuxt CLI. Run this command in the project root to install and configure the module.

```bash
npx nuxi@latest module add i18n

```

--------------------------------

### useRouteBaseName()

Source: https://i18n.nuxtjs.org/docs/composables/use-route-base-name

Documentation for the useRouteBaseName composable, including its type signature and usage example.

```APIDOC
## useRouteBaseName()

### Description
Returns a function that gets the route's base name.

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

### Parameters
- **options** (I18nCommonRoutingOptionsWithComposable) - Optional - Options for the composable.

### Return Value
A function that accepts a route (string, Route, or RouteLocationNormalizedLoaded) and returns the base name as a string or 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>
```
```

--------------------------------

### Example 1: Basic URL localization - nuxt.config.ts

Source: https://i18n.nuxtjs.org/docs/guide/custom-paths

Configuration for basic URL localization, mapping route names to localized paths.

```typescript
export default defineNuxtConfig({
  i18n: {
    customRoutes: 'config',
    pages: {
      parent: {
        en: '/parent',
        ca: '/pare'
      },
      'parent-child': {
        en: '/parent/child',
        ca: '/pare/fill'
      }
    }
  }
})

```

--------------------------------

### Example 3: Dynamic Routes - nuxt.config.ts

Source: https://i18n.nuxtjs.org/docs/guide/custom-paths

Configuration for dynamic routes, using placeholders like `[date]` and `[slug]` in the path.

```typescript
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]'
        // ...
      }
    }
  }
})

```

--------------------------------

### Usage example with NuxtLink

Source: https://i18n.nuxtjs.org/docs/composables/use-locale-path

Shows how to use useLocalePath in a Vue component. The composable is called in the script setup and the returned function is used in a NuxtLink to generate a localized path for the 'index' route.

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

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

```

--------------------------------

### Example file structure for lazy-loaded translations

Source: https://i18n.nuxtjs.org/docs/guide/lazy-load-translations

Shows the recommended directory layout for lazy-loading translations, with locale files placed under i18n/locales and the Nuxt config at the project root.

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

--------------------------------

### Usage with useHead

Source: https://i18n.nuxtjs.org/docs/composables/use-locale-head

Example of using useLocaleHead with the seo option and passing the result to useHead to set htmlAttrs, link, and meta.

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

```

--------------------------------

### useLocaleRoute()

Source: https://i18n.nuxtjs.org/docs/composables/use-locale-route

Documentation for the useLocaleRoute composable, including its type signature and usage example.

```APIDOC
## useLocaleRoute()

### Description
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
```

### Parameters
- **options** (I18nCommonRoutingOptionsWithComposable) - Optional - Options for the composable.

### Returns
A function that takes a route (RawLocation | RouteLocation) and an optional locale (Locale) and returns a Route or (RouteLocation & { href: string }) or 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>
```
```

--------------------------------

### Example 2: Localize the part of URL - nuxt.config.ts

Source: https://i18n.nuxtjs.org/docs/guide/custom-paths

Configuration for localizing parts of URLs, mapping route names to French paths.

```typescript
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'
      }
    }
  }
})

```

--------------------------------

### useTranslation

Source: https://i18n.nuxtjs.org/docs/composables/use-translation

Documentation for the useTranslation composable, including its type signature and usage example.

```APIDOC
## useTranslation(event)

### Description
Returns the translation function for the given H3 event. The locale used is determined by the `experimental.localeDetector` option. This composable is experimental and server-side only.

### Method
useTranslation

### Parameters
- **event** (H3Event) - Required - The H3 event object.

### Returns
- **Promise<TranslationFunction<Schema, DefineLocaleMessage>>** - A promise that resolves to the translation function.

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

--------------------------------

### useLocalePath

Source: https://i18n.nuxtjs.org/docs/composables/use-locale-path

Documentation for the useLocalePath composable, including its type signature and usage example.

```APIDOC
## useLocalePath

### Description
Returns a function that resolves a path according to the current locale. The returned function always resolves a path on the current domain and does not consider which domain serves a locale. Under `differentDomains` or `multiDomainLocales`, a path it returns for a locale served elsewhere is redirected to that domain when the URL is loaded.

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

### Parameters
- `options` (I18nCommonRoutingOptionsWithComposable) - Optional - Options for the composable.

### Return Value
- A function that takes a route (`RawLocation | RouteLocation`) and an optional locale (`Locale`) and returns a string path.

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

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

--------------------------------

### useSetI18nParams()

Source: https://i18n.nuxtjs.org/docs/composables/use-set-i18n-params

Documentation for the useSetI18nParams composable, including its type signature, parameters, and usage example.

```APIDOC
## useSetI18nParams()

### Description
Returns a function to set translated parameters for the current route. This is useful for generating localized URLs, especially in a language switcher.

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

### Parameters
- **options** (`SeoAttributesOptions | undefined`) - Optional. An `SeoAttributesOptions` object, default `undefined`. See the SEO guide for more details.

### Returns
A function that accepts a record mapping locale codes to an object of route parameters. The function sets the translated parameters for the current route.

### Usage Example
```typescript
<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>
```
```

--------------------------------

### useLocaleHead

Source: https://i18n.nuxtjs.org/docs/composables/use-locale-head

Documentation for the useLocaleHead composable, including its type signature, parameters, return value, and usage examples.

```APIDOC
## useLocaleHead

### Description
The `useLocaleHead()` composable returns localized head properties for locale-related aspects. It can be used to set the `lang` and `dir` attributes on the HTML element and to add SEO-related meta and link tags.

### Signature
```typescript
declare function useLocaleHead(options: I18nHeadOptions): Ref<I18nHeadMetaInfo>
```

### Parameters
#### `options` (I18nHeadOptions) - Optional
An object accepting the following optional fields:
- **`dir`** (boolean) - Optional - Default: `true` - Adds a `dir` attribute to the HTML element.
- **`lang`** (boolean) - Optional - Default: `true` - Adds a `lang` attribute to the HTML element.
- **`seo`** (boolean | SeoAttributesOptions) - Optional - Adds various SEO attributes.

### Return Value
Returns a `Ref<I18nHeadMetaInfo>` containing localized head properties, including `htmlAttrs`, `link`, and `meta`.

### Usage 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>
```

The returned value can also be passed to `useHeadSafe()` directly:
```vue
<script setup>
useHeadSafe(useLocaleHead())
</script>
```
```

--------------------------------

### rootRedirect option example

Source: https://i18n.nuxtjs.org/docs/api/options

Shows the object form of the rootRedirect option, which redirects users from the root URL to a localized path with a custom status code.

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

--------------------------------

### defineI18nRoute

Source: https://i18n.nuxtjs.org/docs/compiler-macros/define-i18n-route

Documentation for the defineI18nRoute compiler macro, including its type signature, parameters, and usage example.

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

### Description
Sets custom route paths for page components in the `pages/` directory. This macro is deprecated in favor of `definePageMeta()` and will be removed in v11.

### Method
Compiler Macro

### Parameters
#### `route` (I18nRoute | false) - Required
- **`false`** - Disables localization for the target page component route.
- **`I18nRoute`** - An object with the following properties:
  - **`paths`** (Record<Locale, `/${string}`>) - Optional - Customizes page component routes per locale. Supports static and dynamic paths for vue-router.
  - **`locales`** (Locale[]) - Optional - Specifies locales to which the page component should be localized.

### Example
```vue
<script setup>
defineI18nRoute({
  paths: {
    en: '/about-us',
    fr: '/a-propos',
    ja: '/about-ja'
  }
})
</script>
```
```

--------------------------------

### Locale detector using tryQueryLocale, tryCookieLocale, tryHeaderLocale

Source: https://i18n.nuxtjs.org/docs/composables/define-i18n-locale-detector

Example locale detector that checks query, cookie, and header in order, falling back to config.defaultLocale. Uses auto-imported @intlify/h3 utilities.

```typescript
// 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
})

```

--------------------------------

### locales array with language codes

Source: https://i18n.nuxtjs.org/docs/api/options

Example of the `locales` option as an array of language codes.

```javascript
['en', 'fr', 'es']
```

--------------------------------

### Example: globalSFCScope true with lang attribute

Source: https://i18n.nuxtjs.org/docs/api/options

Shows a custom i18n block with global attribute and lang="yaml", and its equivalent without the global attribute when globalSFCScope is true.

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

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

--------------------------------

### defineI18nConfig

Source: https://i18n.nuxtjs.org/docs/composables/define-i18n-config

Documentation for the defineI18nConfig composable, including its type signature, parameters, and usage example.

```APIDOC
## defineI18nConfig

### Description
Defines a function that returns the vue-i18n configuration passed to the `createI18n()` options on the Nuxt I18n module. The loader function must return a Function or Promise that resolves a vue-i18n options object.

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

### Parameters
- **loader** (Function) - Required - A function that loads the vue-i18n options.

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

--------------------------------

### Locale translation files en.json and nl.json

Source: https://i18n.nuxtjs.org/docs/getting-started/usage

Translation message files for English and Dutch locales. Each file provides translation messages as an object; the 'welcome' key is used in the example page.

```json
{
  "welcome": "Welcome"
}

```

```json
{
  "welcome": "Welkom"
}

```

--------------------------------

### locales array with locale objects

Source: https://i18n.nuxtjs.org/docs/api/options

Example of the `locales` option as an array of locale objects, showing the `code`, `language`, `file`, and `dir` properties.

```javascript
[
  { "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" }
]
```

--------------------------------

### Loader using $fetch

Source: https://i18n.nuxtjs.org/docs/composables/define-i18n-locale

Example loader function using $fetch to load locale messages from an API endpoint. The loader must return a Promise that resolves a messages object.

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

```

--------------------------------

### Locale file using useNuxtApp

Source: https://i18n.nuxtjs.org/docs/composables/define-i18n-locale

Example locale file (i18n/locales/en.ts) that uses a Nuxt app composable (useNuxtApp) to keep the loader inside the Nuxt app. This is detected at build time by reading the calls the locale file makes itself.

```typescript
export default defineI18nLocale(async locale => {
  // loaded in the Nuxt app, not through the messages endpoint
  const { $tenant } = useNuxtApp()
  return $fetch(`/api/messages/${$tenant.id}/${locale}`)
})

```

--------------------------------

### Set canonicalQueries in Nuxt useLocaleHead

Source: https://i18n.nuxtjs.org/docs/guide/seo

Uses useLocaleHead with the canonicalQueries option to include the 'foo' query parameter in the generated canonical link. The setup script then applies the HTML attributes, links, and meta tags to the head using useHead.

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

--------------------------------

### Module configuration with customRoutes: 'config'

Source: https://i18n.nuxtjs.org/docs/guide/custom-paths

Set `customRoutes` to `'config'` and define custom paths in the `pages` option. Each key corresponds to a route name, and paths must start with `/` and not include the locale prefix.

```typescript
export default defineNuxtConfig({
  i18n: {
    customRoutes: 'config', // enable custom routes from the `pages` option
    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
      }
    }
  }
})

```

--------------------------------

### Example: custom block with lang attribute

Source: https://i18n.nuxtjs.org/docs/api/options

Shows a custom i18n block with lang="yaml" and its equivalent without the lang attribute when defaultSFCLang is set to "yaml" or "yml".

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

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

--------------------------------

### useRouteBaseName usage in Vue component

Source: https://i18n.nuxtjs.org/docs/composables/use-route-base-name

Usage example for useRouteBaseName in a Vue component. It shows how to get the route base name from the current route object or its name property, and display it in the template.

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

```

--------------------------------

### defineI18nConfig usage example

Source: https://i18n.nuxtjs.org/docs/composables/define-i18n-config

Example usage of defineI18nConfig to define a vue-i18n options object with legacy mode disabled, a default locale, and messages for English and French.

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

```

--------------------------------

### Basic usage of <SwitchLocalePathLink> and equivalent <NuxtLink> with useSwitchLocalePath()

Source: https://i18n.nuxtjs.org/docs/components/switch-locale-path-link

Shows how to use <SwitchLocalePathLink> with the locale prop to create language switcher links, and the equivalent implementation using useSwitchLocalePath() and <NuxtLink> with the :to prop. The component is recommended for language-switchers because it correctly updates routes with dynamic parameters during SSR.

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

--------------------------------

### Usage example for useLocaleRoute

Source: https://i18n.nuxtjs.org/docs/composables/use-locale-route

Example of using useLocaleRoute in a Vue component to generate a localized link path. It computes a link path based on the current locale and uses it in a NuxtLink.

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

```

--------------------------------

### Define per-component translations with YAML i18n block

Source: https://i18n.nuxtjs.org/docs/guide/per-component-translations

Use an `<i18n lang="yaml">` block in a Vue file to define translations. The script and template are the same as the JSON example. This example includes English and Japanese translations.

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

```

--------------------------------

### Create cross-domain locale switcher with useSwitchLocalePath

Source: https://i18n.nuxtjs.org/docs/guide/different-domains

Build a cross-domain language switcher using `<SwitchLocalePathLink>` or a plain `<a>` tag with `useSwitchLocalePath()`. This writes the locale cookie so the choice survives the switch when `detectBrowserLanguage.cookieDomain` spans your domains. Avoid `<NuxtLink>` because it adds `rel="noreferrer"` to external links, preventing detection from recognizing the arrival as your own.

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

```

--------------------------------

### Setting translated route parameters with useSetI18nParams

Source: https://i18n.nuxtjs.org/docs/composables/use-set-i18n-params

Usage example showing how to set translated route parameters for the current route. It uses useSetI18nParams with canonicalQueries option and then calls the returned function with locale-specific slug values. The example also demonstrates using useSwitchLocalePath to generate localized paths.

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

--------------------------------

### Layout component using useLocaleHead for SEO metadata

Source: https://i18n.nuxtjs.org/docs/guide/seo

Declares a setup function that returns the result of useLocaleHead() to generate SEO metadata. Uses Html, Head, and Body components to apply lang, dir, link, and meta tags.

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

```

--------------------------------

### Route generation with and without compactRoutes

Source: https://i18n.nuxtjs.org/docs/guide/new-features

Shows the route generation for the /about page with three locales (en, fr, ja) and the prefix strategy. The first block lists the three separate routes normally generated, and the second shows the single compacted route when compactRoutes is enabled.

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

```

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

```

--------------------------------

### defineI18nLocaleDetector

Source: https://i18n.nuxtjs.org/docs/composables/define-i18n-locale-detector

Documentation for the defineI18nLocaleDetector composable, including its type signature, parameters, and usage example.

```APIDOC
## defineI18nLocaleDetector

### Description
Defines a function that detects the locale on the server-side. It is called per request on the server and must return a locale string.

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

### Parameters
#### `detector`
- **type**: `(event: H3Event, config: LocaleConfig) => string`
- **Required** - A function that is the locale detector.

##### `event`
- **type**: `H3Event`
- An H3 event. See details in H3 API docs.

##### `config`
- **type**: `object`
- A locale config that is passed from Nitro.
- **Properties**:
  - `defaultLocale`
    - **type**: `Locale`
    - 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'` is used.
  - `fallbackLocale`
    - **type**: `FallbackLocale`
    - 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`.

### Usage
An example of a locale detector:
```typescript
// 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
})
```

### Notes
- This composable is experimental. You need to configure filepath to `experimental.localeDetector` option.
- You can use `@intlify/h3` utilities in the locale detector function, these are auto imported.
- The composable and the utilities can also be imported explicitly from `#imports` (e.g. when auto imports are disabled):
```typescript
import { defineI18nLocaleDetector, tryCookieLocale, tryHeaderLocale, tryQueryLocale } from '#imports'
```
```

--------------------------------

### useBrowserLocale()

Source: https://i18n.nuxtjs.org/docs/composables/use-browser-locale

Documentation for the useBrowserLocale composable function.

```APIDOC
## useBrowserLocale()

### Description
Returns the browser locale. On the client-side, it detects the locale from `navigator.languages`. On the server-side, it detects the locale from the `accept-language` header.

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

### Returns
- **string | null** - The browser locale string, or `null` if it cannot be determined.
```

--------------------------------

### defineI18nLocale

Source: https://i18n.nuxtjs.org/docs/composables/define-i18n-locale

Documentation for the defineI18nLocale composable, including its type signature, parameters, usage examples, and execution context.

```APIDOC
## defineI18nLocale

### Description
Defines a function to dynamically load locale messages for lazy-loading translations. The loader function must return a Promise that resolves to 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`
- **Type**: `(locale: Locales) => Messages | Promise<Messages>`
- **Required**: Yes
- **Description**: A function that dynamically loads locale messages. It receives a `locale` parameter of type `Locale` which is passed from the nuxt i18n module when the locale is switched (e.g., via `setLocale()` or `<NuxtLink>` with `useSwitchLocalePath()` or `$switchLocalePath()`).

### Usage
Example using a fetch request to load locale messages:
```ts
export default defineI18nLocale(locale => {
  return $fetch(`https://your-company-product/api/${locale}`)
})
```

### Where the loader runs
- The loader runs on the server and in the browser.
- In production, the server runs it outside the Nuxt app, so it can only use APIs available in both places (e.g., `$fetch()`, `useRuntimeConfig()`).
- Nitro-only APIs (h3 utilities, `useStorage()`) are not available in the browser or in development.
- Nuxt app composables (`useNuxtApp()`, `useState()`, `useCookie()`, `useRequestHeaders()`) are an exception: if a locale file calls one, the loader stays inside the Nuxt app and is loaded there on both server and client. This is decided at build time by reading the calls the locale file makes itself. Composables reached through imported helpers are not visible and will fail when the server loads that locale.

Example with Nuxt app composable:
```ts
// i18n/locales/en.ts
export default defineI18nLocale(async locale => {
  // loaded in the Nuxt app, not through the messages endpoint
  const { $tenant } = useNuxtApp()
  return $fetch(`/api/messages/${$tenant.id}/${locale}`)
})
```

Messages for such a locale are produced per request during SSR and again in the browser, and the locale file ships in the client bundle. A loader that reads server-only resources (e.g., a database, an internal service) must not use these composables.
```

--------------------------------

### Resolve localized routes with useLocalePath composable

Source: https://i18n.nuxtjs.org/docs/getting-started/usage

Use the useLocalePath composable in script setup to resolve localized routes outside the template.

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

```

--------------------------------

### Basic usage of NuxtLinkLocale with localePath

Source: https://i18n.nuxtjs.org/docs/components/nuxt-link-locale

Shows the basic usage of <NuxtLinkLocale> with a route name or a route object, and the equivalent <NuxtLink> with localePath(). The to prop accepts a route name or a route object using the name property.

```html
<template>
  <NuxtLinkLocale to="index">{{ $t('home') }}</NuxtLinkLocale>
  <NuxtLinkLocale :to="{ name: 'index' }">{{ $t('home') }}</NuxtLinkLocale>
</template>

<!-- equivalent to -->

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

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

--------------------------------

### Import useI18n and useLocalePath from '#imports'

Source: https://i18n.nuxtjs.org/docs/getting-started/usage

Import auto-imported composables explicitly when autoImports is disabled in Nuxt configuration.

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

```

--------------------------------

### Pages directory structure

Source: https://i18n.nuxtjs.org/docs/guide

Shows the project's pages directory structure with about.vue, index.vue, and a dynamic posts/[id].vue page.

```text
-| pages/
---| about.vue
---| index.vue
---| posts/
-----| [id].vue

```

--------------------------------

### Localize URL path with useLocaleRoute

Source: https://i18n.nuxtjs.org/docs/getting-started/usage

Use useLocaleRoute to get a Vue Router route object for a localized URL, useful for programmatic navigation with query parameters.

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

```
Tokens:
Raw