Vue I18n 中文文档

简体中文

English

简体中文

English

Appearance

从 Vue 2 迁移 ​

vue-i18n-bridge ​

注意

由于 Vue 2 到生命周期末期，vue-i18n-bridge 将在 v10 中不再提供。v9.13 将是最后一个版本。

什么是 vue-i18n-bridge？ ​

vue-i18n-bridge 是一个桥接工具，旨在让从 [email protected] 或更高版本升级到 [email protected] 尽可能简单。

它可以在你已经使用 [email protected] 或更高版本构建的 Vue 2 应用程序中使用。

此外，一些特性是从 [email protected] 回溯移植的：

  • Vue I18n 组合 API，由 @vue/composition-api 和 vue-demi 强力驱动
  • 消息格式语法，由 @intlify/message-compiler 强力驱动

安装 ​

包管理器 ​

sh
npm install vue-i18n-bridge
sh
yarn add vue-i18n-bridge
sh
pnpm add vue-i18n-bridge

在使用此库之前，你必须安装以下包：

  • vue-i18n: >= v8.26.1 < v9
  • vue-demi: >= v0.13.5
  • @vue/composition-api: >= v1.2.0 (如果你要使用 Vue 2.6)

CDN ​

对于 Vue 2.7:

在 vue、vue-demi 之后包含 vue-i18n-bridge，它将自动安装。

html
<script src="https://cdn.jsdelivr.net/npm/[email protected]"></script>
<script src="https://unpkg.com/vue-i18n@8/dist/vue-i18n.min.js"></script>
<script src="https://unpkg.com/[email protected]/lib/index.iife.js"></script>
<script src="https://unpkg.com/[email protected]/dist/vue-i18n-bridge.global.prod.js"></script>

对于 Vue 2.6:

在 vue、@vue/composition-api、vue-demi 之后包含 vue-i18n-bridge，它将自动安装。

html
<script src="https://cdn.jsdelivr.net/npm/[email protected]"></script>
<script src="https://unpkg.com/vue-i18n@8/dist/vue-i18n.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@vue/[email protected]"></script>
<script src="https://unpkg.com/[email protected]/lib/index.iife.js"></script>
<script src="https://unpkg.com/[email protected]/dist/vue-i18n-bridge.global.prod.js"></script>

使用 ​

组合 API ​

对于 Vue 2.7:

js
import Vue from 'vue'
import { createApp } from 'vue-demi'
import { createI18n, useI18n } from 'vue-i18n-bridge'

Vue.use(VueI18n, { bridge: true }) // 在安装 vue-i18n 时必须指定 '{ bridge: true }' 插件选项

// `createI18n` 选项几乎与 vue-i18n ([email protected]) API 相同
const i18n = createI18n({
  legacy: false,
  locale: 'ja',
  messages: {
    en: {
      message: {
        hello: 'hello, {name}!'
      }
    },
    ja: {
      message: {
        hello: 'こんにちは、{name}！'
      }
    }
  }
}, VueI18n) // `vue-i18n-bridge` 提供的 `createI18n` 有第二个参数，你**必须**传递 `vue-i18n` 提供的 `VueI18n` 构造函数

const app = createApp({
 setup() {
   // `useI18n` 选项几乎与 vue-i18n ([email protected]) API 相同
   const { t, locale } = useI18n()
   // ... 做一些事情

   return { t, locale }
 }
})

app.use(i18n) // 你必须安装由 `createI18n` 创建的 `i18n` 实例
app.mount('#app')

对于 Vue 2.6:

js
import Vue from 'vue'
import VueCompositionAPI, { createApp } from '@vue/composition-api'
import { createI18n, useI18n } from 'vue-i18n-bridge'

Vue.use(VueCompositionAPI)
Vue.use(VueI18n, { bridge: true }) // 在安装 vue-i18n 时必须指定 '{ bridge: true }' 插件选项

// `createI18n` 选项几乎与 vue-i18n ([email protected]) API 相同
const i18n = createI18n({
  legacy: false,
  locale: 'ja',
  messages: {
    en: {
      message: {
        hello: 'hello, {name}!'
      }
    },
    ja: {
      message: {
        hello: 'こんにちは、{name}！'
      }
    }
  }
}, VueI18n) // `vue-i18n-bridge` 提供的 `createI18n` 有第二个参数，你**必须**传递 `vue-i18n` 提供的 `VueI18n` 构造函数

const app = createApp({
 setup() {
   // `useI18n` 选项几乎与 vue-i18n ([email protected]) API 相同
   const { t, locale } = useI18n()
   // ... 做一些事情

   return { t, locale }
 }
})

app.use(i18n) // 你必须安装由 `createI18n` 创建的 `i18n` 实例
app.mount('#app')

传统 API ​

对于 Vue 2.7:

js
import Vue from 'vue'
import { createI18n, useI18n } from 'vue-i18n-bridge'

Vue.use(VueI18n, { bridge: true }) // 在安装 vue-i18n 时必须指定 '{ bridge: true }' 插件选项

// `createI18n` 选项几乎与 vue-i18n ([email protected]) API 相同
const i18n = createI18n({
  locale: 'ja',
  messages: {
    en: {
      message: {
        hello: 'hello, {name}!'
      }
    },
    ja: {
      message: {
        hello: 'こんにちは、{name}！'
      }
    }
  }
}, VueI18n) // `vue-i18n-bridge` 提供的 `createI18n` 有第二个参数，你**必须**传递 `vue-i18n` 提供的 `VueI18n` 构造函数

Vue.use(i18n) // 你必须安装由 `createI18n` 创建的 `i18n` 实例

const app = new Vue({ i18n })
app.$mount('#app')

对于 Vue 2.6:

js
import Vue from 'vue'
import VueCompositionAPI from '@vue/composition-api'
import { createI18n, useI18n } from 'vue-i18n-bridge'

Vue.use(VueCompositionAPI)
Vue.use(VueI18n, { bridge: true }) // 在安装 vue-i18n 时必须指定 '{ bridge: true }' 插件选项

// `createI18n` 选项几乎与 vue-i18n ([email protected]) API 相同
const i18n = createI18n({
  locale: 'ja',
  messages: {
    en: {
      message: {
        hello: 'hello, {name}!'
      }
    },
    ja: {
      message: {
        hello: 'こんにちは、{name}！'
      }
    }
  }
}, VueI18n) // `vue-i18n-bridge` 提供的 `createI18n` 有第二个参数，你**必须**传递 `vue-i18n` 提供的 `VueI18n` 构造函数

Vue.use(i18n) // 你必须安装由 `createI18n` 创建的 `i18n` 实例

const app = new Vue({ i18n })
app.$mount('#app')

对于 TypeScript:

ts
import Vue from 'vue'
import VueCompositionAPI from '@vue/composition-api'
import { createI18n, useI18n, castToVueI18n } from 'vue-i18n-bridge'

Vue.use(VueCompositionAPI)
Vue.use(VueI18n, { bridge: true })

// 你需要转换 `i18n` 实例
const i18n = castToVueI18n(createI18n({
  locale: 'ja',
  messages: {
    en: {
      message: {
        hello: 'hello, {name}!'
      }
    },
    ja: {
      message: {
        hello: 'こんにちは、{name}！'
      }
    }
  }
}, VueI18n))

Vue.use(i18n)

const app = new Vue({ i18n })
app.$mount('#app')

在浏览器中使用 UMD 模块 ​

对于 Vue 2.7 ​

js
const { createApp } = VueDemi // 以 `VueDemi` 命名导出的 UMD
const { createI18n, useI18n } = VueI18nBridge // 以 `VueI18nBridge` 命名导出的 UMD

Vue.use(VueI18n, { bridge: true })

const i18n = createI18n({
  locale: 'ja',
  messages: {
    // ...
  }
}, VueI18n)

const app = createApp({}, {
  // ...
})
app.use(i18n)
app.mount('#app') // Vue 应用宿主容器元素

对于 Vue 2.6 ​

js
const { createApp } = VueCompositionAPI // 以 `VueCompositionAPI` 命名导出的 UMD
const { createI18n, useI18n } = VueI18nBridge // 以 `VueI18nBridge` 命名导出的 UMD

Vue.use(VueCompositionAPI)
Vue.use(VueI18n, { bridge: true })

const i18n = createI18n({
  locale: 'ja',
  messages: {
    // ...
  }
}, VueI18n)

const app = createApp({}, {
  // ...
})
app.use(i18n)
app.mount('#app') // Vue 应用宿主容器元素

限制 ​

  • 在传统 API 模式下，你不能使用从 vue-i18n 回溯移植的新消息格式语法
    • 仅在组合 API 模式下可用
  • 在传统 API 模式下，你不能使用从 vue-i18n 回溯移植的组件
    • 翻译组件：<i18n-t>
    • 日期时间格式化组件：<i18n-d>
    • 数字格式化组件：<i18n-n>
  • 在组合 API 模式下，以下 API 以 $ 为前缀是全局作用域
    • $t
    • $d
    • $n

不同构建的解释 ​

在 npm 包的 dist/ 目录 中，你会找到 vue-i18n-bridge 的许多不同构建版本。根据使用场景，以下是对应该使用哪个 dist 文件的概述。

通过 CDN 或无捆绑器使用 ​

  • vue-i18n-bridge(.runtime).global(.prod).js:
    • 用于直接通过 <script src="..."> 在浏览器中使用。暴露了 VueI18nBridge 全局变量
    • 浏览器内消息格式编译:
      • vue-i18n-bridge.global.js 是"完整"构建，包含编译器和运行时，因此支持实时编译消息格式
      • vue-i18n-bridge.runtime.global.js 仅包含运行时，需要在构建步骤期间预编译消息格式
    • 内联所有 Vue I18n 核心内部包 - 即它是一个单文件，不依赖其他文件。这意味着你必须从该文件导入所有内容并仅使用该文件以确保获得相同代码实例
    • 包含硬编码的生产和开发分支，生产构建提前被压缩。在生产环境中使用 *.prod.js 文件

注意

全局构建不是 UMD 构建。它们是 IIFEs 构建，仅用于通过 <script src="..."> 直接使用。

  • vue-i18n-bridge(.runtime).esm-browser(.prod).js:
    • 通过原生 ES 模块导入 (浏览器通过 <script type="module">) 使用
    • 与全局构建共享相同的运行时编译、依赖内联和硬编码的生产和开发行为

使用捆绑器 ​

  • vue-i18n-bridge(.runtime).esm-bundler.js:
    • 用于 webpack、rollup 和 parcel 等捆绑器
    • 保留生产和开发分支，使用 process.env.NODE_ENV 保护 (必须由捆绑器替换)
    • 不提供压缩构建 (应在捆绑后与其他代码一起压缩)
    • 导入依赖项 (例如 @intlify/core-base, @intlify/message-compiler)
      • 导入的依赖项也是 esm-bundler 构建，反过来会导入它们的依赖项 (例如 @intlify/message-compiler 导入 @intlify/shared)
      • 这意味着你可以单独安装/导入这些依赖项而不会最终出现不同实例，但你必须确保它们都解析到相同版本
    • 浏览器内本地化消息编译:
      • vue-i18n-bridge.runtime.esm-bundler.js 仅包含运行时，需要所有本地化消息预先编译。这是捆绑器的默认入口 (通过 package.json 中的 module 字段)，因为使用捆绑器时模板通常是预先编译的 (例如在 *.json 文件中)
      • vue-i18n-bridge.esm-bundler.js (默认): 包含运行时编译器。如果你使用捆绑器但仍希望本地化消息编译 (例如通过内联 JavaScript 字符串的模板)，请使用此构建。要使用此构建，请将导入语句更改为: import { createI18n } from "vue-i18n-bridge/dist/vue-i18n-bridge.esm-bundler.js";

注意

如果你使用 vue-i18n-bridge.runtime.esm-bundler.js，你需要预先编译所有本地化消息，你可以使用 .json (.json5) 或 .yaml、i18n 自定义块来管理 i18n 资源。因此，你可以使用捆绑器和以下加载器/插件预先编译所有本地化消息。

对于 Node.js (服务器端) ​

  • vue-i18n-bridge.cjs(.prod).js:
    • 用于通过 require() 在 Node.js 中使用
    • 如果你使用 target: 'node' 的 webpack 捆绑你的应用并正确外部化 vue-i18n-bridge，则将加载此构建
    • 生产/开发文件是预构建的，但根据 process.env.NODE_ENV 自动选择适当文件

vue-i18n-composable ​

从 Vue 3 开始支持组合 API，你可以使用官方 @vue/composition-api 插件，使组合 API 可用于 Vue 2。

Vue I18n 组合 API 也可以在 Vue 2 中使用 vue-i18n-composable 插件。

使用方法，请参见 这里

注意

vue-i18n-composable 允许 Vue I18n v8.x 的主要 API 与组合 API 一起使用。Vue I18n v9 中提供的所有组合 API 都不可用。

Copyright © 2026-present allyouneed.tools