优化

性能

如“不同的发行版文件”部分所述，Vue I18n 为打包器提供以下两个构建的 ES 模块。

消息编译器 + 运行时：vue-i18n.esm-bundler.js
仅运行时：vue-i18n.runtime.esm-bundler.js

对于打包器，默认配置为将 vue-i18n.esm-bundler.js 与 @intlify/unplugin-vue-i18n 打包在一起。如果你想进一步减小包大小，可以将打包器配置为使用 vue-i18n.runtime.esm-bundler.js，它是仅运行时的。

使用 ES 模块 vue-i18n.runtime.esm-bundler.js 意味着 所有语言环境消息都必须预编译为消息函数或 AST 资源。这意味着，它提高了性能，因为 vue-i18n 仅执行消息函数，因此无需编译。

注意

在 v9.3 之前，语言环境消息将被编译为消息函数，在 v9.3 或更高版本之后，这些将使用 @intlify/bundle-tools 编译为 AST。

注意

在 v9.3 之前，所有语言环境消息都使用 @intlify/unplugin-vue-i18n 编译，因此消息编译器未打包，包大小可以减小。

在 v9.3 之后，由于消息编译器也已打包，因此无法减小包大小。这是一种权衡。关于原因，请参阅 JIT 编译详情。

注意

如果在 v9.3 之前启用了 CSP，vue-i18n.esm-bundler.js 将无法与编译器一起工作，因为使用了 eval 语句。这些语句违反了 default-src 'self' 标头。相反，你需要使用 vue-i18n.runtime.esm-bundler.js。

注意

从 v9.3 开始，可以通过 vue-i18n 消息编译器的 JIT 编译来解决 CSP 问题。请参阅 JIT 编译详情。

如何配置

我们可以使用某些打包器的模块解析别名功能（例如 resolve.alias vite 和 webpack）配置这些模块路径，但这需要时间和精力。为了简单起见，Intlify 项目为某些打包器提供了插件/加载器

unplugin-vue-i18n

unplugin 是一个用于打包工具（如 vite、webpack、rollup、esbuild 等）的统一插件系统。

Intlify 项目正在为 vite 和 webpack 提供 unplugin-vue-i18n。

如果你进行生产构建，Vue I18n 将自动打包仅运行时模块

安装插件

npmyarnpnpm

npm install @intlify/unplugin-vue-i18n -D

yarn add @intlify/unplugin-vue-i18n -D

pnpm add -D @intlify/unplugin-vue-i18n

为 vite 配置插件

// vite.config.ts
import { defineConfig } from 'vite'
import { resolve, dirname } from 'node:path'
import { fileURLToPath } from 'url'
import VueI18nPlugin from '@intlify/unplugin-vue-i18n/vite'

export default defineConfig({
  /* ... */
  plugins: [
    /* ... */
    VueI18nPlugin({
      /* options */
      // locale messages resource pre-compile option
      include: resolve(dirname(fileURLToPath(import.meta.url)), './path/to/src/locales/**'),
    }),
  ],
})

为 webpack 配置插件

// webpack.config.js
const path = require('path')
const VueI18nPlugin = require('@intlify/unplugin-vue-i18n/webpack')

module.exports = {
  /* ... */
  plugins: [
    /* ... */
    VueI18nPlugin({
      /* options */
      // locale messages resource pre-compile option
      include: path.resolve(__dirname, './path/to/src/locales/**'),
    })
  ]
}

重要选项

`include`

include 选项指定在构建时应预编译的区域设置消息资源的文件路径。您必须配置此选项以覆盖所有区域设置消息文件，否则未预编译的消息在生产构建中将无法正常工作（例如，{name} 等插值占位符不会被替换）。

VueI18nPlugin({
  include: resolve(dirname(fileURLToPath(import.meta.url)), './src/locales/**'),
})

`runtimeOnly`

默认情况下，@intlify/unplugin-vue-i18n 在生产环境中使用仅运行时构建，不包含消息编译器以减小包大小。这意味着所有区域设置消息必须在构建时预编译。

如果您在运行时动态加载区域设置消息（例如，从 API 或数据库），则需要设置 runtimeOnly: false 以包含运行时消息编译器：

VueI18nPlugin({
  runtimeOnly: false,  // 包含运行时消息编译器
  include: resolve(dirname(fileURLToPath(import.meta.url)), './src/locales/**'),
})

故障排除

如果您的翻译在开发环境中有效，但插值占位符在生产环境中未被替换（例如，显示 {name} 而不是值），可能是以下原因之一：

include 选项未覆盖所有区域设置消息文件 — 不匹配 include 的消息不会被预编译
您在运行时动态加载消息 — 设置 runtimeOnly: false 以包含消息编译器

Quasar CLI

无需做任何事情。Quasar CLI 会为你处理优化。

功能构建标志

使用 tree-shaking 减小包大小

esm-bundler 构建现在公开了可以在编译时覆盖的全局功能标志：

__VUE_I18N_FULL_INSTALL__（启用/禁用，除了 vue-i18n API 之外，组件和指令全部完全支持安装：true）
__VUE_I18N_LEGACY_API__（启用/禁用 vue-i18n 传统风格 API 支持。传统 API 已在 v12 中移除，默认：false）

构建将在不配置这些标志的情况下工作，但是 强烈建议 正确配置它们，以便在最终包中获得适当的 tree shaking。

关于如何为打包器配置，请参阅这里。

JIT 编译

支持版本

🆕 9.3+

在 v9.3 之前，vue-i18n 消息编译器像 AOT（提前）一样预编译语言环境消息。

但是，它有以下问题：

CSP 问题：很难在 service/web workers、CDN 的边缘运行时等上工作。
后端集成：很难通过 API 从数据库等后端获取消息并动态本地化它们

为了解决这些问题，JIT（即时）风格编译被支持为消息编译器。

每次在应用程序中使用 $t 或 t 函数执行本地化时，消息资源将在消息编译器上编译。

你需要使用 esm-bundler 构建和 vite 等打包器配置以下功能标志：

__INTLIFY_JIT_COMPILATION__（启用/禁用 JIT 风格的消息编译器，默认：false）
__INTLIFY_DROP_MESSAGE_COMPILER__（启用/禁用我们在打包时是否对消息编译器进行 tree-shake，当启用 __INTLIFY_JIT_COMPILATION__ 时此标志起作用。默认：false）

注意

此功能默认为选择退出，因为与 v9.3 之前的版本兼容。

注意

从 v10 开始，默认启用 JIT 编译，因此不再需要在打包器中设置 __INTLIFY_JIT_COMPILATION__ 标志。

关于如何为打包器配置，请参阅这里。

为打包器配置功能标志

webpack: 使用 DefinePlugin
Rollup: 使用 @rollup/plugin-replace
Vite: 默认配置，但可以使用 define 选项覆盖
Quasar CLI: 默认配置，但可以使用 quasar.conf.js > build > rawDefine 覆盖

注意

替换值 必须是布尔字面量，不能是字符串，否则打包器/压缩器将无法正确评估条件。

使用扩展进行预翻译

你可以使用 vue-i18n-extensions 包进行预翻译（服务器端渲染）。

关于如何使用，请参阅这里。

SSR (服务器端渲染)

为 SSR 配置插件

对于 SSR 应用程序，你需要在 @intlify/unplugin-vue-i18n 中配置 ssr 选项：

// vite.config.ts
import { defineConfig } from 'vite'
import VueI18nPlugin from '@intlify/unplugin-vue-i18n/vite'

export default defineConfig({
  plugins: [
    VueI18nPlugin({
      ssr: true, // 启用 SSR 支持
    }),
  ],
})

优化 ​

性能 ​

如何配置 ​

unplugin-vue-i18n ​

安装插件 ​

为 vite 配置插件 ​

为 webpack 配置插件 ​

重要选项 ​

include ​

runtimeOnly ​

更多配置 ​

Quasar CLI ​

功能构建标志 ​

使用 tree-shaking 减小包大小 ​

JIT 编译 ​

为打包器配置功能标志 ​

使用扩展进行预翻译 ​

SSR (服务器端渲染) ​

为 SSR 配置插件 ​

优化

性能