string
''
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
}
}
})
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.string | Function
''
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
.
string[] | LocaleObject[]
[]
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
string
language
undefined | string
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
null | string | { path: string; cache: string; }
langDir
path when loading locale messages from file.files
null | string[] | { path: string; cache: string; }[]
langDir
path when loading locale messages from file.dir
null | 'rtl' | 'ltr' | 'auto'
'rtl'
, 'ltr'
or 'auto'
.domain
null | string
runtimeConfig
. This property is required when using differentDomains
domains
null | string[]
domain
. This property is required when using multiDomainLocales
while one or more of the domains having multiple of the same localesdefaultForDomains
null | string[]
multiDomainLocales
)domain
for which the locale should be the default locale when using domains
.domainDefault
null | boolean
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...
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.
string
ltr
The app's default direction. Will only be used when dir
is not specified.
string | null
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.
'no_prefix' | 'prefix_except_default' | 'prefix' | 'prefix_and_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'page' | 'config'
'page'
Whether custom paths are extracted from page files
object
{}
If customRoutes
option is disabled with config
, the module will look for custom routes in the pages
option. Refer to the Routing for usage.
boolean
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.
string
'default'
Internal suffix added to generated route names for default locale, if strategy is prefix_and_default
. You shouldn't need to change this.
string
'___'
Internal separator used for generated route names for each locale. You shouldn't need to change this.
string | { statusCode: number; path: string; } | null
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"
}
boolean | LazyOptions
false
See also Lazy-load translations.
Whether the translations should be lazy-loaded. If this is enabled, locales must be an array of objects, each containing a file
or files
key.
Loading locale messages lazily means that only messages for currently used locale (and for the fallback locale, if different from current locale) will be loaded on page loading.
string
locales
A relative path to a directory containing translation files to load. Can be used with or without lazy-loading (the lazy
option).
The path is resolved relative to the project restructureDir
at the root of a project ('i18n'
by default).
'/locales'
should be changed into either 'locales'
or './locales'
)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.
redirectOn
to 'root'
.Set to false
to disable.
Supported properties:
alwaysRedirect
boolean
false
Set to always redirect to the value stored in the cookie, not just on first visit.
fallbackLocale
string | null
If none of the locales match the browser's locale, use this one as a fallback.
redirectOn
string
'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
boolean
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
string
'i18n_redirected'
Cookie name.
cookieDomain
string | null
null
Set to override the default domain of the cookie. Defaults to the host of the site.
cookieCrossOrigin
boolean
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
boolean
false
Sets the Secure
flag for the cookie.
boolean
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.
boolean
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.
object
{ strictMessage: true, escapeHtml: false }
Configure flags that sets the behavior compilation of locale messages.
Supported properties:
strictMessage
boolean
true
Strictly check that the locale message does not contain HTML tags. If HTML tags are included, an error is thrown.
escapeHtml
option to true
.escapeHtml
boolean
false
Determine whether to escape HTML tags if they are included in the locale message.
strictMessage
is disabled by setting it to false
, we recommend enabling this option.object
{ compositionOnly: true, runtimeOnly: false, fullInstall: true, dropMessageCompiler: false }
Configure the bundling optimization for nuxt i18n module.
Supported properties:
compositionOnly
boolean
true
Whether to make vue-i18n API only composition API. By default the legacy API is tree-shaken. For more details, See here
compositionOnly: false
. 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
in i18n.config, but this is limited. See here for details.runtimeOnly
boolean
false
Whether or not to automatically use Vue I18n runtime-only in build.
fullInstall
boolean
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
boolean
false
Whether to tree-shake message compiler when bundling.
compilation.jit
option.onlyLocales
string | string[]
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 configuration property is an object with the following properties:
localeDetector
string
''
defineI18nLocaleDetector()
APIswitchLocalePathLinkSSR
boolean
false
SwitchLocalePathLink
component.autoImportTranslationFunctions
boolean
false
$t()
, $rt()
, $d()
, $n()
, $tm()
and $te()
functions in <script setup>
when used.typedPages
boolean
true
experimental.typedRoutes
is enabled.experimental.typedRoutes
and will not work if this is not enabled.typedOptionsAndMessages
false | 'default' | 'all'
false
- disables type generation'default'
- generate types based on configured defaultLocale
'all'
- generate types based on all configured localesfalse
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.generatedLocaleFilePathFormat
'absolute' | 'relative'
'absolute'
- locale file and langDir paths contain the full absolute path'relative'
- locale file and langDir paths are converted to be relative to the rootDir
'absolute'
locales
returned by useI18n()
.Configure the i18n
custom blocks of SFC.
Supported properties:
defaultSFCLang
'json' | 'json5' | 'yaml' | 'yml'
'json'
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
boolean
false
i18n
custom blocks on your SFC on global scope. For more details refer to unplugin-vue-i18n documentationglobalSFCScope: true
, all i18n
custom blocks in all your SFC
will be on global
scope.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>
'composition' | 'legacy'
'composition'
Enforces the type definition of the API style to be used.
'composition'
, Composition API types provided by Vue I18n and @nuxtjs/i18n
are supported,'legacy'
, Options API types are supported.nuxi prepare
for the generated types to update.boolean | 'verbose'
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.
@nuxtjs/i18n
.You should not enable this option in production as it will negatively impact performance.boolean
false
Set the plugin as parallel
. See nuxt plugin loading strategy.
string
'i18n'
Can be used to configure the directory used to resolve i18n files.