选项 - Nuxt I18n 中文文档

vueI18n

type: string
default: ''

用于此模块内部的 Vue I18n 选项的构建时配置。有关完整文档，请参见这里

createI18n() 的配置可以通过配置文件传递。默认情况下，模块会扫描 i18n.config{.js,.mjs,.ts}，如果没有指定则 fallback。

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['@nuxtjs/i18n'],
  i18n: {
    vueI18n: './nuxt-i18n.js' // 自定义路径示例
  }
})

你需要使用 普通对象 或函数 export default。

使用普通对象的导出示例：

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

使用函数的导出示例：

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

// 你可以使用 `defineI18nConfig` 来获取类型推断，以传递给 vue-i18n 的选项。
export default defineI18nConfig(() => {
  return {
    legacy: false,
    locale: 'en',
    messages: {
      en,
      fr
    }
  }
})

Vue I18n 的 messages 选项应通过 普通对象 返回。这将在 nuxt i18n 模块中通过 vue-i18n 消息编译器预编译为 vue-i18n 运行时中的可执行消息。

baseUrl

type: string | Function
default: ''

用作 hreflang 标签中备用 URL 的前缀的回退基本 URL。默认情况下，将使用 VueRouter 的基本 URL，只有在不可用时才会使用回退 URL。

也可以是一个函数（将传递 Nuxt 上下文作为参数）返回一个字符串。根据请求头动态获取基本 URL 时非常有用。

此属性还可以使用 runtimeConfig 来设置。

在使用 SEO 功能时，设置此选项特别重要，此时必须确保生成的 SEO 标签使用完全限定的 URL。

locales

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

应用程序支持的区域列表。可以是语言代码的数组（['en', 'fr', 'es']）或区域对象的数组，以进行更复杂的配置：

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

使用对象形式时，属性可以是：

`code`

type: string
区域的唯一标识符

`language`

type: undefined | string
在使用 SEO 功能时必需
用于 SEO 功能和使用 detectBrowserLanguage 功能时匹配浏览器区域的语言范围。应使用语言标签语法，如 IETF 的 BCP47 所定义，例如：
- 'en'（英文的 language 子标签）
- 'fr-CA'（在加拿大使用的法语的 language+region 子标签）
- 'zh-Hans'（使用简体字书写的中文的 language+script 子标签）

`file`

type: null | string | { path: string; cache: string; }
文件的名称。当从文件加载区域消息时，相对于 langDir 路径进行解析。

`files`

type: null | string[] | { path: string; cache: string; }[]
定义多个区域消息的文件名。当从文件加载区域消息时，相对于 langDir 路径进行解析。

`dir`

type: null | 'rtl' | 'ltr' | 'auto'
dir 属性指定元素和内容的方向，值可以是 'rtl'、'ltr' 或 'auto'。

`domain`

type: null | string
你希望为该区域使用的域名（如果使用，则包括端口）。此属性还可以使用 runtimeConfig 来设置。使用 differentDomains 时，这个属性是必需的。

`domains`

type: null | string[]
domain 的数组。当使用 multiDomainLocales 时，如果多个域具有同一地区则此属性是必需的。

`defaultForDomains`

type: null | string[]
（在使用 multiDomainLocales 时是可选的）
用于该区域的 domain 数组，在使用 domains 时该区域应为默认区域。

`domainDefault`

type: null | boolean
将 domainDefault 设置为 true，以使每个区域在特定域中充当默认区域。使用 differentDomains 时如果多个域具有多个区域，这个属性是必需的。

`...`

在对象上设置的任何自定义属性将在运行时暴露。这可以用于示例中，定义页面上语言选择器所需的语言名称。

你可以通过 localeProperties 属性访问当前区域的所有属性。当使用代码数组时，只会包含 code 属性。

defaultDirection

type: string
default: ltr

应用的默认方向。只有在未指定 dir 时使用。

defaultLocale

type: string | null
default: null

应用的默认区域。应与定义的 locales 中的语言代码匹配。

在使用 prefix_except_default 策略时，这里指定的区域链接不会有前缀。 建议将其设置为某个区域，无论选择的策略是什么，因为在导航到不存在的路由时将用作回退区域。

strategy

type: 'no_prefix' | 'prefix_except_default' | 'prefix' | 'prefix_and_default'
default: 'prefix_except_default'

路由生成策略。可以设置为以下之一：

'no_prefix'：路由将没有区域前缀
'prefix_except_default'：每个区域添加区域前缀，默认情况除外
'prefix'：每个区域添加区域前缀
'prefix_and_default'：每个区域和默认区域添加区域前缀

customRoutes

type: 'page' | 'config'
default: 'page'

是否从页面文件中提取自定义路径

skipSettingLocaleOnNavigate

type: boolean
default: false

如果 true，在导航到新区域时不会设置区域。如果你想在设置区域之前等待页面过渡结束，使用 finalizePendingLocaleChange 自行设置区域，则此功能非常有用。有关更多信息，请参见等待页面过渡。

defaultLocaleRouteNameSuffix

type: string
default: 'default'

附加到默认区域生成的路由名称的内部后缀，如果策略为 prefix_and_default。你不应该需要更改这个。

routesNameSeparator

type: string
default: '___'

生成的每个区域的路由名称使用的内部分隔符。你不应该需要更改这个。

rootRedirect

type: string | { statusCode: number; path: string; } | null
default: null

设置为希望重定向到的路径，以便用户访问根 URL（'/'）。接受字符串或带有 statusCode 和 path 属性的对象。例如：

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

lazy

type: boolean | LazyOptions
default: false

另请参见延迟加载翻译。

翻译是否应该延迟加载。如果启用，则区域必须是对象数组，每个对象都包含 file 或 files 键。

懒加载区域消息意味着仅在页面加载时加载当前使用区域的消息（以及与当前区域不同的回退区域）。

langDir

type: string
default: locales

加载的翻译文件所在目录的相对路径。可以与延迟加载（lazy 选项）一起使用，也可以单独使用。

路径是相对于项目的根目录中的 restructureDir 解析的（默认是 'i18n'）。

绝对路径在生产中会失败（例如：'/locales' 应更改为 'locales' 或 './locales'）

detectBrowserLanguage

type: object | boolean

启用浏览器语言检测，以自动将访问者重定向到其首选区域，因为他们第一次访问您的网站。

另请参见浏览器语言检测的指南。

请注意，为了更好的 SEO，建议将 redirectOn 设置为 'root'。

设置为 false 以禁用。

支持的属性：

`alwaysRedirect`

type: boolean
default: false

设置为始终重定向到存储在 cookie 中的值，而不仅仅是在首次访问时。

`fallbackLocale`

type: string | null

如果没有区域与浏览器的区域匹配，则使用此作为后备。

`redirectOn`

type: string
default: 'root'

支持的选项：

'all' - 在所有路径上检测浏览器区域。
'root'（为了提升 SEO 的推荐） - 仅在网站的根路径（'/'）上检测浏览器区域。仅在使用非 'no_prefix' 策略时有效。
'no prefix' - 更宽松的 'root' 变体，将在根路径（'/'）和没有区域前缀的路径（如 '/foo'）上检测浏览器区域。仅在使用非 'no_prefix' 策略时有效。

`useCookie`

type: boolean
default: true

如果启用，一旦用户被重定向到浏览器的首选区域，将设置一个 cookie，以防止后续的重定向。设置为 false 以每次重定向。

`cookieKey`

type: string
default: 'i18n_redirected'

Cookie 名称。

`cookieDomain`

type: string | null
default: null

设置以覆盖 cookie 的默认域。默认值为站点的主机。

`cookieCrossOrigin`

type: boolean
default: false

当为 true 时，在 cookie 上设置标志 SameSite=None; Secure 以允许跨域使用 cookie（当应用嵌入在 iframe 中时所需）。

`cookieSecure`

type: boolean
default: false

为 cookie 设置 Secure 标志。

differentDomains

type: boolean
default: false

当为每个区域使用不同的域时，将此设置为 true，启用此功能后，你必须将区域配置为包含 domain 键的对象数组。有关更多信息，请参见不同域。

multiDomainLocales

type: boolean
default: false

当使用不同的域和不同的区域时，将此设置为 true。如果启用，则你必须将区域配置为包含 domains 和 defaultForDomains 键的对象数组。有关更多信息，请参见多域区域。

compilation

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

配置设置区域消息编译的行为。

支持的属性：

`strictMessage`

type: boolean
default: true

严格检查区域消息中是否不包含 HTML 标签。如果包含 HTML 标签，则抛出错误。

如果你不希望抛出错误，可以通过将其设置为 false 来解决此问题。然而，这意味着区域消息可能导致 XSS 的安全问题。在这种情况下，建议将 escapeHtml 选项设置为 true。

`escapeHtml`

type: boolean
default: false

确定是否在区域消息中包括 HTML 标签时转义 HTML 标签。

如果通过将 strictMessage 设置为 false 来禁用，它强烈建议启用此选项。

bundle

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

配置 nuxt i18n 模块的打包优化。

支持的属性：

`compositionOnly`

type: boolean
default: true

是否仅将 vue-i18n API 作为组合 API。默认情况下，旧版 API 会被树摇。更多详细信息，请参见这里

如果你希望使用 Vue I18n 的旧版 API，必须将 compositionOnly 设置为 false。请注意，设置此值将禁用 Vue I18n 组合 API。请注意，旧版 API 也可以通过在 i18n.config 中将 Vue I18n 选项设置为 allowComposition: true 来混合使用，但这是有限制的。有关详细信息，请查看这里。

`runtimeOnly`

type: boolean
default: false

在构建时是否自动使用仅限运行时的 Vue I18n。

当你启用此选项时，将不会捆绑 vue-i18n 消息编译器。这意味着你将无法通过 fetch 从后端 API 动态检索用于应用程序的区域消息，或以编程方式组合区域消息。也就是说，你必须能够在构建时完全解析区域消息。

`fullInstall`

type: boolean
default: true

是否安装完整的 API、组件等默认情况下，将安装所有内容。如果指定为 false，内置组件（<i18n-t>, <i18n-d> 和 <i18n-n>）以及指令（v-t）将不会在 Vue 中进行安装并将被树摇。更多详细信息，请参见这里

`dropMessageCompiler`

type: boolean
default: false

在打包时是否树摇消息编译器。

如果使用此选项，则需要启用 compilation.jit 选项。

如果启用此选项，你应该检查应用程序中的资源是否已使用 nuxt i18n 模块预编译。如果你通过 API 从后端动态加载资源，则启用此选项将无法工作，因为没有消息编译器。

`onlyLocales`

type: string | string[]
default: undefined

指定需要包含的区域代码，其余的将被移除。

如果你有一个代码库（例如 Nuxt Layers）用于多个使用不同语言的类似项目，这很有用。

此 选项的值不会与其他 Nuxt Layers 合并。此选项应仅在最终项目配置中指定。

`optimizeTranslationDirective`

type: boolean
default: true

是否通过将其用法转换为 vue-i18n 翻译函数来优化 v-t 指令，此选项需要在使用 SSR 的项目中启用 v-t 指令。

experimental

实验性配置属性是一个对象，具有以下属性：

`localeDetector`

type: string
default: ''
指定对每个请求在服务器端调用的区域探测器。你需要指定定义区域探测器的文件路径。

有关如何定义区域探测器的更多详细信息，请参见 defineI18nLocaleDetector() API。

`switchLocalePathLinkSSR`

type: boolean
default: false
修改动态路由参数的跟踪和更新方式，提高使用 SwitchLocalePathLink 组件时的语言切换 SSR。

`autoImportTranslationFunctions`

type: boolean
default: false
当使用时，在 <script setup> 中自动导入/初始化 $t()、$rt()、$d()、$n()、$tm() 和 $te() 函数。

此功能依赖于 Nuxt 的自动导入，如果禁用，则无法工作。

`typedPages`

type: boolean
default: true
生成在组合和配置中使用的路由类型，当 Nuxt 的 experimental.typedRoutes 启用时，此功能默认启用。

此功能依赖于 Nuxt 的 experimental.typedRoutes，如果未启用，则无法工作。

`typedOptionsAndMessages`

type: false | 'default' | 'all'
- false - 禁用类型生成
- 'default' - 基于配置的 defaultLocale 生成类型
- 'all' - 基于所有配置的区域生成类型
default: false
生成用于翻译函数和 vue-i18n 配置的 vue-i18n 和消息类型。可以配置为使用 defaultLocale（更好的性能）或所有区域进行类型生成。

`generatedLocaleFilePathFormat`

type: 'absolute' | 'relative'
- 'absolute' - 区域文件和 langDir 路径包含完整的绝对路径
- 'relative' - 区域文件和 langDir 路径被转换为相对于 rootDir
default: 'absolute'
这将改变生成的区域文件和 langDir 路径，这些路径在 v9（及更低版本）中默认为绝对路径，可能会在生产环境中暴露敏感路径信息。

更改此配置还将更改通过 useI18n() 返回的 locales 中的路径。

customBlocks

配置 SFC 的 i18n 自定义块。

支持的属性：

`defaultSFCLang`

type: 'json' | 'json5' | 'yaml' | 'yml'
default: 'json'
指定你所有内联 i18n 自定义块的内容所用的语言。有关更多详细信息，请参见 unplugin-vue-i18n 文档

对于指定了 lang 属性的内联 i18n 自定义块，defaultSFCLang 不会被应用。

例如，使用 defaultSFCLang: "yaml" 或 defaultSFCLang: "yml"，此自定义块：

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

将等价于：

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

`globalSFCScope`

type: boolean
default: false
是否在全局范围内包含 SFC 上的所有 i18n 自定义块。有关更多详细信息，请参见 unplugin-vue-i18n 文档

当启用 globalSFCScope: true 时，所有 SFC 中的 i18n 自定义块将处于全局作用域。

例如，使用 globalSFCScope: true，此自定义块：

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

将等价于：

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

这与 defaultSFCLang 结合使用，使用 defaultSFCLang: "yaml"，以下将等价于前面的示例：

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

types

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

强制使用的 API 样式的类型定义。

设置为 'composition'，支持 Vue I18n 和 @nuxtjs/i18n 提供的组合 API 类型，
设置为 'legacy'，支持选项 API 类型。

你可能需要运行 nuxi prepare 以更新生成的类型。

debug

type: boolean | 'verbose'
default: false

是否使用 @nuxtjs/i18n 调试模式。如果为 true 或 'verbose'，将输出日志到控制台，将其设置为 'verbose' 还将记录加载的消息对象。

此选项的目的是帮助识别 @nuxtjs/i18n 的任何问题。你不应该在生产环境中启用此选项，因为会对性能产生负面影响。

parallelPlugin

type: boolean
default: false

将插件设置为 parallel。请参见 nuxt 插件加载策略。

restructureDir

type: string
default: 'i18n'

可用于配置用于解析 i18n 文件的目录。

迁移指南

按照本指南从一个主要版本升级到另一个版本。

Vue I18n

Vue I18n 的扩展