Options

vueI18n

• type: string
• default: ''

Build-time configuration for Vue I18n options that is used internally by this module. See full documentation at here

Configuration for createI18n() can be passed using a configuration file. By default, the module will scan for a i18n.config{.js,.mjs,.ts} if nothing is specified.

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:

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

Export with function example:

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
    }
  }
})

baseUrl

• type: string | Function
• default: ''

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.

locales

• type: string[] | LocaleObject[]
• default: []

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:

[
  { "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
• Unique identifier of the locale

language

• type: undefined | string
• Required when using SEO features
• A language-range used for SEO features and for matching browser locales when using detectBrowserLanguage functionality. Should use the language tag syntax as defined by the IETF's BCP47, 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; }
• 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; }[]
• 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 to learn more.

dir

• type: null | 'rtl' | 'ltr' | 'auto'
• The dir property specifies the direction of the elements and content, value could be 'rtl', 'ltr' or 'auto'.

domain

• type: null | string
• The domain name you'd like to use for that locale (including the port if used). This property can also be set using runtimeConfig. This property is required when using differentDomains

domains

• type: null | string[]
• An array of domain. This property is required when using multiDomainLocales while one or more of the domains having multiple of the same locales

defaultForDomains

• type: null | string[]
• (optional when using multiDomainLocales)
• An array of domain for which the locale should be the default locale when using domains.

domainDefault

• type: null | boolean
• 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 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
• default: ltr

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

defaultLocale

• type: string | null
• 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'
• default: 'prefix_except_default'

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

• 'no_prefix': routes won't have a locale prefix
• 'prefix_except_default': locale prefix added for every locale except default
• 'prefix': locale prefix added for every locale
• 'prefix_and_default': locale prefix added for every locale and default

customRoutes

• type: 'meta' | 'page' | 'config'
• default: 'page'

Whether custom paths are extracted from page files or configured in the module configuration:

• 'meta': custom paths are extracted from the definePageMeta() function in page components.
• 'page': custom paths are extracted from the defineI18nRoute() macro in page components.
• 'config': custom paths are configured in the pages option of the module configuration.

pages

• type: object
• default: {}

If customRoutes option is disabled with config, the module will look for custom routes in the pages option. Refer to the Routing for usage.

skipSettingLocaleOnNavigate

• type: boolean
• default: false

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. See more information in Wait for page transition.

defaultLocaleRouteNameSuffix

• type: string
• default: 'default'

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
• default: '___'

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
• default: null

Set to a path to which you want to redirect users accessing the root URL ('/'). Accepts either a string or an object with statusCode and path properties. E.g

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

redirectStatusCode

• type: number
• default: 302

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

langDir

• type: string
• default: locales

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' by default).

detectBrowserLanguage

• type: object | boolean

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 for a guide.

Set to false to disable.

Supported properties:

alwaysRedirect

• type: boolean
• default: false

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

fallbackLocale

• type: string | null

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

redirectOn

• type: string
• default: 'root'

Supported options:

• 'all' - detect browser locale on all paths.
• 'root' (recommended for improved SEO) - only detect the browser locale on the root path ('/') of the site. Only effective when using strategy other than 'no_prefix'.
• 'no prefix' - a more permissive variant of 'root' that will detect the browser locale on the root path ('/') and also on paths that have no locale prefix (like '/foo'). Only effective when using strategy other than 'no_prefix'.

useCookie

• type: boolean
• default: true

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
• default: 'i18n_redirected'

Cookie name.

cookieDomain

• type: string | null
• default: null

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

cookieCrossOrigin

• type: boolean
• default: false

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
• default: false

Sets the Secure flag for the cookie.

differentDomains

• type: boolean
• default: false

Set this to true 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 for more information.

multiDomainLocales

• type: boolean
• default: false

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 for more information.

compilation

• type: object
• default: { strictMessage: true, escapeHtml: false }

Configure flags that sets the behavior compilation of locale messages.

Supported properties:

strictMessage

• type: boolean
• default: true

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

escapeHtml

• type: boolean
• default: false

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

bundle

• type: object
• default: { compositionOnly: true, runtimeOnly: false, fullInstall: true, dropMessageCompiler: false }

Configure the bundling optimization for nuxt i18n module.

Supported properties:

compositionOnly

• type: boolean
• default: true

Whether to make vue-i18n API only composition API. By default the legacy API is tree-shaken. For more details, See here

runtimeOnly

• type: boolean
• default: false

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

fullInstall

• type: boolean
• default: true

Whether to install the full set of APIs, components, etc. By default, all of them will be installed. If false is specified, built-in components (<i18n-t>, <i18n-d> and <i18n-n>) and directive (v-t) will not be installed in vue and will be tree-shaken. For more details, See here

dropMessageCompiler

• type: boolean
• default: false

Whether to tree-shake message compiler when bundling.

onlyLocales

• type: string | string[]
• default: undefined

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) for several similar projects using different languages.

experimental

Experimental configuration property is an object with the following properties:

localeDetector

• type: string
• default: ''
• 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.

strictSeo

• type: boolean | SeoAttributesOptions
• default: false
• Enables strict SEO mode.

typedPages

• type: boolean
• default: true
• Generates route types used in composables and configuration, this feature is enabled by default when Nuxt's experimental.typedRoutes is enabled.

typedOptionsAndMessages

• type: false | 'default' | 'all'
  • false - disables type generation
  • 'default' - generate types based on configured defaultLocale
  • 'all' - generate types based on all configured locales
• default: false
• 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
• default: true
• Remove non-canonical query parameters from alternate link meta tags

httpCacheDuration

• type: number
• default: 10
• 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.

hmr

• type: boolean
• default: true
• Hot module replacement for locale message files and vue-i18n configuration in dev mode.

customBlocks

Configure the i18n custom blocks of SFC.

Supported properties:

defaultSFCLang

• type: 'json' | 'json5' | 'yaml' | 'yml'
• default: 'json'
• Specify the content for all your inlined i18n custom blocks on your SFC. For more details refer to unplugin-vue-i18n documentation

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

For example, with defaultSFCLang: "yaml" or defaultSFCLang: "yml", this custom block:

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

Would be equivalent to this:

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

globalSFCScope

• type: boolean
• default: false
• Whether to include all i18n custom blocks on your SFC on global scope. For more details refer to unplugin-vue-i18n documentation

For example, with globalSFCScope: true, this custom block:

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

Would be equivalent to this:

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

This combines with defaultSFCLang, with defaultSFCLang: "yaml" the following would be equivalent to the previous examples:

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

types

• type: 'composition' | 'legacy'
• default: 'composition'

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

• Set to 'composition', Composition API types provided by Vue I18n and @nuxtjs/i18n are supported,
• Set to 'legacy', Options API types are supported.

debug

• type: boolean | 'verbose'
• default: false

Whether to use @nuxtjs/i18n debug mode. If true or 'verbose', logs will be output to the console, setting this to 'verbose' will also log loaded messages objects.

parallelPlugin

• type: boolean
• default: false

Set the plugin as parallel. See nuxt plugin loading strategy.

restructureDir

• type: string
• default: 'i18n'

Used to configure the directory used to resolve i18n files.

autoDeclare

• type: boolean
• default: true
• Automatically imports/initializes $t(), $rt(), $d(), $n(), $tm() and $te() functions in <script setup> when used.

serverRoutePrefix

• type string
• default: '/_i18n'

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