Vue I18n 中文文档

简体中文

English

简体中文

English

Appearance

优化 ​

性能 ​

如"不同发行文件"部分所述，Vue I18n 为构建工具提供了以下两个内置 ES 模块。

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

对于构建工具，默认配置为使用 @intlify/unplugin-vue-i18n 来打包 vue-i18n.esm-bundler.js。如果要进一步减少包大小，您可以配置构建工具使用仅运行时的 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 开始，由于消息编译器也被打包，包大小无法减少。这是一个权衡。 有关原因，请参见即时编译详情。

注意

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

注意

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

如何配置 ​

我们可以使用某些构建工具的模块解析别名功能（例如 vite 和 webpack 的 resolve.alias）来配置这些模块路径，但这需要时间和精力。

Intlify 项目为一些构建工具提供了插件/加载器，以简化操作。

unplugin-vue-i18n ​

unplugin 是一个统一的插件系统，适用于 vite、webpack、rollup、esbuild 等构建工具。

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

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

安装插件 ​

sh
npm install @intlify/unplugin-vue-i18n -D
sh
yarn add @intlify/unplugin-vue-i18n -D
sh
pnpm add -D @intlify/unplugin-vue-i18n

为 vite 配置插件 ​

js
// 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({
      /* 选项 */
      // 本地化消息资源预编译选项
      include: resolve(dirname(fileURLToPath(import.meta.url)), './path/to/src/locales/**'),
    }),
  ],
})

为 webpack 配置插件 ​

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

module.exports = {
  /* ... */
  plugins: [
    /* ... */
    VueI18nPlugin({
      /* 选项 */
      // 本地化消息资源预编译选项
      include: path.resolve(__dirname, './path/to/src/locales/**'),
    })
  ]
}

更多配置 ​

关于选项和功能，请参见详细页面

Quasar CLI ​

无需任何操作。Quasar CLI 会为您处理优化。

功能构建标志 ​

通过 Tree-shaking 减少包大小 ​

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

  • __VUE_I18N_FULL_INSTALL__（启用/禁用，除了 vue-i18n API，组件和指令全部完全支持安装：true）
  • __VUE_I18N_LEGACY_API__（启用/禁用 vue-i18n 传统风格 API 支持，默认：true）

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

关于如何为构建工具配置，请参见此处。

即时编译 ​

支持版本

🆕 9.3+

在 v9.3 之前，vue-i18n 消息编译器预编译本地化消息，类似于 AOT（提前编译）。

然而，它存在以下问题：

  • CSP 问题：难以在服务/网页工作者、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 开始，默认启用了即时编译，因此不再需要在构建工具中设置 __INTLIFY_JIT_COMPILATION__ 标志。

关于如何为构建工具配置，请参见此处。

为构建工具配置功能标志 ​

注意

替换值必须是布尔字面量，不能是字符串，否则构建工具/压缩工具无法正确评估条件。

使用扩展进行预翻译 ​

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

关于使用方法，请参见这里。

SSR（服务端渲染） ​

为 SSR 配置插件 ​

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

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

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

Copyright © 2026-present allyouneed.tools