入门指南

创建一个具有 Vue + Vue I18n 的全局应用程序非常简单。使用 Vue.js，我们已经在使用组件构建应用程序。当加入 Vue I18n 时，我们只需要准备好资源消息并使用 Vue I18n 提供的本地化 API。

注意

本指南将假设您已经熟悉 Vue 本身。您不需要成为 Vue 专家，但有时可能需要参考 核心 Vue 文档 来了解某些功能的更多信息。

一个示例

我们将考虑这个示例：

• StackBlitz 示例

让我们从查看根组件 App.vue 开始。

App.vue

<template>
  <h1>{{ $t('message.hello') }}</h1>
</template>

在模板中，我们使用 Vue I18n 注入的 $t 翻译 API 进行本地化。这允许 Vue I18n 在不重写模板的情况下更改语言环境，同时支持全局应用程序。

您将得到以下输出：

<h1>你好，世界</h1>

让我们来看看这是如何在 JavaScript 中实现的！

创建 i18n 实例

通过调用函数 createI18n 创建 i18n 实例。

const i18n = createI18n({
  locale: 'ja',
  fallbackLocale: 'en',
  messages: {
    en: {
      message: {
        hello: 'hello world'
      }
    },
    ja: {
      message: {
        hello: '你好，世界'
      }
    }
  }
})

我们可以为 createI18n 指定一些选项。 重要选项是 locale、fallbackLocale 和 messages 选项。

locale 是要本地化的 Vue 应用程序的语言。

fallbackLocale 是当 $t 翻译 API 中指定的键资源在 locale 语言中找不到时回退到的语言。

messages 是使用 $t 翻译 API 进行翻译的本地消息。本地消息的结构是以每个语言作为顶级属性的分层对象结构。

注册 i18n 插件

一旦我们创建了 i18n 实例，我们需要通过在我们的应用程序上调用 use 来将其注册为插件：

const app = createApp(Vue)
app.use(i18n)
app.mount('#app')

像大多数 Vue 插件一样，对 use 的调用需要在对 mount 的调用之前发生。

如果您好奇这个插件的作用，其职责包括：

1. 添加全局属性和方法，如 $t、$i18n
2. 启用 useI18n 组合式函数
3. 全局注册 i18n-t、i18n-d 和 i18n-n 组件。

本指南中的约定

单文件组件

Vue I18n 最常用于使用打包工具（例如 Vite）和 SFCs（即 .vue 文件）构建的应用程序中。本指南中的大多数示例将以这种样式编写，但 Vue I18n 本身并不要求您使用构建工具或 SFCs。

例如，如果您使用的是 Vue 和 Vue I18n 的 全局构建，这些库通过全局对象暴露，而不是导入：

const { createApp } = Vue
const { createI18n, useI18n } = VueI18n

组件 API 风格

Vue I18n 可以与组合式 API 和选项式 API 一起使用。相关示例将在本指南中展示两种风格的组件。组合式 API 示例通常使用 <script setup>，而不是显式的 setup 函数。

如果您需要重温这两种风格，请参见 Vue - API 风格。

Vue I18n 与 Vue 组合式 API 和选项式 API 都兼容。Vue I18n 有两种 API 风格，就像 Vue 一样，组合式 API 和用于选项式 API 的旧式 API。

重要

在 Vue I18n v9 及更高版本中，Vue I18n v8.x 提供的 API 被称为 旧式 API 模式。 旧式 API 在 Vue I18n v11 中已弃用，并在 Vue I18n v12 中移除。我们建议使用组合式 API 模式。

以下部分将使用旧式 API 进行解释。

如果您希望在组合式 API 风格中使用它并且已经理解 Vue I18n，可以跳转到 这里。