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

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

## 一、环境准备与安装

### 1. 安装最新版vue-i18n
```bash
# 安装适用于Vue3的版本（当前最新9.x）
npm install vue-i18n@9

2. 版本兼容说明

二、项目配置详解

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 = lang
  localStorage.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: string
      username: string
    }
  }
}

八、完整示例项目结构

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

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

1. 自动检测用户语言偏好
2. 支持动态切换语言
3. 完善的TypeScript类型支持
4. 优化的生产环境构建
5. 良好的开发者体验

建议将i18n配置封装为Vue插件，便于在不同项目中复用。实际开发中可以根据项目规模选择适合的方案，小型项目可以直接使用JSON文件，大型项目可以考虑将翻译内容存储在CMS中动态加载。