指南
迁移指南
按照本指南从 v9.x 升级到 v10.x
升级到 Vue I18n v11
我们已从 Vue I18n v10 升级到 v11，此次重大版本更新废弃了 Legacy API 模式和自定义的 v-t 指令，并从 Legacy API 模式中移除了 tc() 和 $tc()。
请查看详细说明断代码变更的文档 这里。
配置选项
以下配置选项已被更改、废弃或移除。
| 状态 | 选项 | 说明 |
|---|---|---|
| promoted | experimental.hmr | 默认启用并重命名为 hmr |
| promoted | experimental.switchLocalePathLinkSSR | 默认启用，且已移除禁用此功能的选项。 |
| promoted | experimental.autoImportTranslationFunctions | 默认启用并重命名为 autoDeclare |
| changed | restructureDir | 不再支持禁用。 我们建议保持未设置状态以使用默认值 'i18n'。 |
| deprecated | types | v11 仅支持 'composition' 类型，与 Vue I18n v12 保持一致。 |
| deprecated | baseUrl | 仅允许字符串值配置，不再支持函数配置。 对于复杂场景，请使用运行时配置或依赖多域本地化来设置基础 URL。 |
| deprecated | routesNameSeparator | 文档中标记为内部使用，最终用户使用场景不明确。 |
| deprecated | defaultLocaleRouteNameSuffix | 文档中标记为内部使用，最终用户使用场景不明确。 |
| removed | lazy | 现已对所有本地化文件默认启用懒加载。 |
| removed | bundle.optimizeTranslationDirective | 功能已禁用并完全移除，详情见 该问题讨论。 |
| removed | experimental.generatedLocaleFilePathFormat | 本模块配置的文件路径（如 locale 文件、vue-i18n 配置）已完全从构建中移除，此选项已无效。 |
I18n 函数
以下组合式函数和I18n 函数已被更改、废弃或移除。
| 状态 | 函数 | 说明 |
|---|---|---|
| changed | useLocaleHead() | options 参数中的 key 属性已移除且不能再配置，为了实现头部标签的可预测且一致的本地化管理。 |
| removed | onLanguageSwitched() | 请改用 'i18n:languageSwitched' 钩子。该函数实际上是调用钩子而非订阅钩子，导致行为不可预测。 |
| removed | onBeforeLanguageSwitch() | 请改用 'i18n:beforeLanguageSwitch' 钩子。该函数实际上是调用钩子而非订阅钩子，导致行为不可预测。 |
上下文函数
以下上下文函数已被更改、废弃或移除。
| 状态 | 函数 | 说明 |
|---|---|---|
| changed | $localeHead() | options 参数中的 key 属性已移除且不能再配置，为了实现头部标签的可预测且一致的本地化管理。 |
| deprecated | $localeHead() | 请改用 useLocaleHead() 组合式函数。因使用场景有限被废弃， useLocaleHead() 提供相同功能且与 useHead() 配合使用更方便。 |
| deprecated | $getRouteBaseName() | 请改用 $routeBaseName()。此功能仅更名为 $routeBaseName() ，以与其他上下文函数及其组合式函数保持一致。 |
| removed | $resolveRoute() | 请改用 $localeRoute()。 |
| removed | $localeLocation() | 请改用 $localeRoute()。 |
运行时配置
某些在运行时配置中设置的选项仅用于将构建时配置传递到运行时，且在运行时更改这些选项可能导致问题。
我们不再在运行时配置中设置这些选项，而是将它们视作编译器常量，这样可以对项目构建中未使用的逻辑进行摇树优化。
以下选项已从运行时配置中移除：
| 移除的运行时配置选项 |
|---|
lazy |
strategy |
trailingSlash |
differentDomains |
defaultDirection |
multiDomainLocales |
routeNameSeparator |
defaultLocaleRouteNameSuffix |
生成的选项
项目中的生成选项文件仅供本模块在运行时内部使用，切勿直接使用。未来可能移除更多属性。
以下导出已从生成的选项文件（#build/i18n.options.mjs 和 #internal/i18n/options.mjs）中移除：
| 移除的导出 |
|---|
isSSG |
hasPages |
parallelPlugin |
nuxtI18nOptions |
DEFAULT_COOKIE_KEY |
DYNAMIC_PARAMS_KEY |
NUXT_I18N_MODULE_ID |
SWITCH_LOCALE_PATH_LINK_IDENTIFIER |
移除原因：
- 这些导出已不再被模块使用且可能在最终构建中暴露脆弱信息
- 部分选项现用作静态值以支持更好的摇树优化，减少项目构建体积
旧版迁移
v7 和 v8 的迁移指南请参见旧版文档。