国际化：集成 i18n 基础用法
安装 vue-i18n
vue-i18n 是 Vue.js 官方的国际化插件。Vue 3 对应的是 vue-i18n@9 版本。
pnpm install vue-i18n@9
bash
当前最新稳定版为 9.14.x。注意 Vue 2 使用
vue-i18n@8，Vue 3 使用vue-i18n@9。
VS Code 插件安装
安装 i18n Ally 插件，提供以下能力：
- 翻译进度可视化
- 快捷键提取文案（
Cmd/Ctrl + .） - 内联显示翻译内容
- 支持多种翻译引擎
在 VS Code 扩展中搜索 i18n Ally 并安装即可。
基础配置（main.ts）
1. 创建 i18n 实例
// src/main.ts
import { createApp } from 'vue'
import { createI18n } from 'vue-i18n'
import App from './App.vue'
// 创建 i18n 实例
const i18n = createI18n({
legacy: false, // 必须设为 false 以启用 Composition API 模式
locale: 'zh-CN', // 默认语言
fallbackLocale: 'en', // 回退语言（找不到翻译时的保底）
messages: {
'zh-CN': {
hello: '你好，我是 mock'
},
en: {
hello: 'Hello, I am mock'
}
}
})
const app = createApp(App)
app.use(i18n) // 注册 i18n 插件
app.mount('#app')
typescript
2. 配置项说明
| 选项 | 类型 | 说明 |
|---|---|---|
legacy | boolean | false 使用 Composition API，true 使用 Options API（默认） |
locale | string | 当前激活的语言标识 |
fallbackLocale | string | 当 locale 对应的翻译缺失时使用的回退语言 |
messages | Record<string, object> | 各语言的翻译内容对象 |
在组件中使用
Composition API 方式（推荐）
<!-- src/pages/index.vue -->
<template>
<div>
<p>{{ t('hello') }}</p>
<button @click="switchLanguage('zh-CN')">中文</button>
<button @click="switchLanguage('en')">English</button>
</div>
</template>
<script setup lang="ts">
import { useI18n } from 'vue-i18n'
// 从 useI18n 中解构出 t 函数和 locale
const { t, locale } = useI18n()
function switchLanguage(lang: string) {
locale.value = lang
}
</script>
vue
Options API 方式（不推荐）
<template>
<p>{{ $t('hello') }}</p>
</template>
vue
官方推荐使用 Composition API 方式。
legacy: false时，$t仍然可用，但useI18n更灵活。
语言切换核心代码
import { useI18n } from 'vue-i18n'
// 在 setup 中使用
const { t, locale } = useI18n()
// 切换语言
function changeLocale(lang: string) {
locale.value = lang
}
typescript
关键点：
legacy: false时，locale是一个ref，需要通过.value修改legacy: true（默认）时，locale是一个普通字符串- 修改
locale.value后，模板中所有t()调用会自动更新
实现效果
[中文] [English] ← 语言切换按钮
默认显示：你好，我是 mock
点击 English：Hello, I am mock
点击中文：你好，我是 mock
text
当前方案的不足
将所有翻译内容写在 main.ts 中存在以下问题：
- 难以维护：随着翻译内容增多，
main.ts会变得臃肿 - 缺乏组织：无法按模块/页面拆分翻译文件
- 性能问题：所有语言一次性加载，无法按需加载
推荐的文件结构
src/
├── locales/ # 翻译文件目录
│ ├── zh-CN.js # 中文翻译
│ ├── en.js # 英文翻译
│ └── ja.js # 日文翻译（按需）
├── modules/ # 功能模块
│ └── i18n.ts # i18n 插件配置
└── main.ts # 入口文件
text
vue-i18n 仓库说明
vue-i18n 在 GitHub 上有两个仓库：
| 仓库 | 版本 | 说明 |
|---|---|---|
vue-i18n | v8.x | Vue 2 版本 |
vue-i18n-next | v9.x | Vue 3 版本 |
开发 Vue 3 项目时，请参考 vue-i18n-next 仓库的文档和示例。
总结
- vue-i18n@9 是 Vue 3 的国际化方案，必须设置
legacy: false - 使用
useI18n()解构t和locale进行翻译和语言切换 fallbackLocale作为保底翻译，当目标语言缺少翻译时回退使用- 基础集成只需
createI18n()+app.use(i18n)两步 - 生产项目需要将翻译文件独立管理（下节课进阶用法）
↑