当前位置：首页 > news >正文

Vue3 使用 i18n 实现国际化完整指南

news 2025/7/2 7:24:04

# Vue3 使用 i18n 实现国际化完整指南## 一、环境准备与安装### 1. 安装最新版vue-i18n
```bash
# 安装适用于Vue3的版本（当前最新9.x）
npm install vue-i18n@9

2. 版本兼容说明

Vue版本	vue-i18n版本	备注
Vue 2.x	vue-i18n@8	传统Options API
Vue 3.x	vue-i18n@9	支持Composition API

二、项目配置详解

1. 基础配置结构

推荐的项目目录结构：

src/
├── i18n/
│   ├── index.js        # 主配置文件
│   └── locales/
│       ├── en.json     # 英文翻译
│       ├── zh.json     # 中文翻译
│       └── ja.json     # 日文翻译

2. 完整配置文件示例

// i18n/index.js
import { createI18n } from 'vue-i18n'
import en from './locales/en.json'
import zh from './locales/zh.json'
import ja from './locales/ja.json'// 类型检查的配置对象
const i18nConfig = {legacy: false,          // 必须关闭Vue2兼容模式locale: navigator.language.split('-')[0] || 'zh', // 自动检测浏览器语言fallbackLocale: 'en',   // 回退语言globalInjection: true,  // 全局注入$t方法messages: { en, zh, ja },pluralizationRules: {   // 复数规则ru: function(choice) {// 俄语复数规则}}
}export default createI18n(i18nConfig)

三、多语言文件规范

1. 标准JSON结构

// zh.json
{"common": {"cancel": "取消","confirm": "确认"},"login": {"title": "用户登录","username": "用户名","password": "密码"}
}

2. 支持动态参数

{"welcome": "欢迎{name}访问我们的平台！","unread": "您有{count}条未读消息"
}

四、组件中使用方案

1. 模板中使用

<template><!-- 基础用法 --><h1>{{ $t('login.title') }}</h1><!-- 带参数 --><p>{{ $t('welcome', { name: userName }) }}</p><!-- 复数形式 --><span>{{ $tc('unread', messageCount) }}</span>
</template>

2. Composition API使用

<script setup>
import { useI18n } from 'vue-i18n'const { t, tc, d, n, locale } = useI18n()// 动态翻译
const pageTitle = computed(() => t('page.title'))// 切换语言
const changeLang = (lang) => {locale.value = langlocalStorage.setItem('user_lang', lang)
}
</script>

五、高级功能实现

1. 语言切换器组件

<template><div class="language-switcher"><button v-for="lang in availableLocales":key="lang"@click="changeLanguage(lang)":class="{ active: locale === lang }">{{ getLanguageName(lang) }}</button></div>
</template><script setup>
import { useI18n } from 'vue-i18n'const { availableLocales, locale } = useI18n()const languageNames = {en: 'English',zh: '中文',ja: '日本語'
}const getLanguageName = (code) => languageNames[code] || code
</script>

2. 异步加载语言包

// i18n/index.js
export async function loadLocaleMessages(i18n, locale) {if (i18n.global.availableLocales.includes(locale)) {return Promise.resolve()}const messages = await import(`./locales/${locale}.json`)i18n.global.setLocaleMessage(locale, messages.default)return nextTick()
}

六、最佳实践与优化

1. 性能优化建议

按需加载语言包
使用Webpack的代码分割

// 动态导入语言文件
const messages = {en: () => import('./locales/en.json'),zh: () => import('./locales/zh.json')
}

2. SEO优化方案

// 在路由守卫中设置html lang属性
router.beforeEach((to) => {document.documentElement.lang = i18n.global.locale
})

七、常见问题解决

1. 热更新问题

// 开发环境下监听语言文件变化
if (import.meta.hot) {import.meta.hot.accept(['./locales/en.json'], () => {i18n.global.setLocaleMessage('en', require('./locales/en.json'))})
}

2. TypeScript支持

// types/i18n.d.ts
declare module 'vue-i18n' {export interface DefineLocaleMessage {login: {title: stringusername: string}}
}

八、完整示例项目结构

src/
├── assets/
├── components/
│   └── LanguageSwitcher.vue
├── i18n/
│   ├── index.ts
│   └── locales/
│       ├── en.json
│       ├── zh.json
│       └── index.ts      # 统一导出语言包
├── plugins/
│   └── i18n.ts          # 插件封装
├── App.vue
└── main.ts

通过以上完整配置，可以实现：