Vue 3 项目实现国际化指南 i18n

引言

在开发现代 Web 应用时，国际化（Internationalization，简称 i18n）已经成为一个不可或缺的功能。无论是面向全球用户的商业网站，还是需要支持多语言的企业应用，良好的国际化支持都能显著提升用户体验。本文将深入介绍如何在 Vue 3 项目中实现国际化，从基础概念到实践细节，帮助你构建一个真正的多语言应用。

基础概念

什么是国际化（i18n）？

国际化（i18n）是指设计和开发软件时，使其能够适应不同语言和地区的过程。"i18n" 这个缩写来源于 "internationalization" 这个词，其中 18 表示首字母 'i' 和末字母 'n' 之间有 18 个字母。

为什么需要 JSON 文件？

在 Vue 3 的国际化实现中，我们使用 JSON 文件来存储不同语言的翻译文本。选择 JSON 格式有以下几个原因：

结构化数据：JSON 提供了清晰的层次结构，便于组织和管理翻译文本
易于维护：可以方便地添加、修改和删除翻译内容
跨平台兼容：JSON 是一种通用的数据格式，可以被各种工具和平台处理
支持嵌套：可以创建层次化的翻译结构，更好地组织大型应用的翻译

JSON 文件的来源

翻译文件（JSON）可以通过以下几种方式获得：

手动创建：

适合小型项目或初始开发阶段

开发者直接编写翻译文本

示例

     {
       "nav": {
         "home": "首页",
         "about": "关于"
       }
     }

2.翻译工具生成：

使用专业的翻译管理系统（TMS）

支持批量翻译和导出

常用工具：

POEditor

Lokalise

Crowdin

3.自动化脚本生成：

使用脚本从其他格式转换

从数据库导出

详细安装步骤

1. 创建 Vue 3 项目

# 使用 Vite 创建项目
npm create vite@latest my-vue-app -- --template vue-ts

# 进入项目目录
cd my-vue-app

# 安装依赖
npm install

2. 安装 vue-i18n

npm install vue-i18n@9

3. 项目结构设置

src/
├── locales/          # 翻译文件目录
│   ├── en.json      # 英文翻译
│   └── zh.json      # 中文翻译
├── i18n/            # i18n 配置目录
│   ├── index.ts     # 主配置文件
│   └── messages.ts  # 消息加载器
├── components/      # 组件目录
└── App.vue         # 根组件

4. 创建基础翻译文件

src/locales/zh.json:

{
  "nav": {
    "home": "首页",
    "blog": "博客",
    "about": "关于",
    "contact": "联系"
  },
  "home": {
    "welcome": "欢迎来到我的网站",
    "description": "这是一个使用 Vue 3 和 i18n 构建的多语言网站",
    "features": {
      "title": "主要特点",
      "list": {
        "1": "支持多语言切换",
        "2": "响应式设计",
        "3": "用户友好界面"
      }
    }
  },
  "common": {
    "loading": "加载中...",
    "error": "发生错误",
    "success": "操作成功",
    "buttons": {
      "submit": "提交",
      "cancel": "取消",
      "save": "保存"
    }
  }
}

src/locales/en.json:

{
  "nav": {
    "home": "Home",
    "blog": "Blog",
    "about": "About",
    "contact": "Contact"
  },
  "home": {
    "welcome": "Welcome to my website",
    "description": "This is a multilingual website built with Vue 3 and i18n",
    "features": {
      "title": "Key Features",
      "list": {
        "1": "Multi-language support",
        "2": "Responsive design",
        "3": "User-friendly interface"
      }
    }
  },
  "common": {
    "loading": "Loading...",
    "error": "An error occurred",
    "success": "Operation successful",
    "buttons": {
      "submit": "Submit",
      "cancel": "Cancel",
      "save": "Save"
    }
  }
}

5. 配置 i18n

src/i18n/messages.ts:

import en from '../locales/en.json'
import zh from '../locales/zh.json'

export const messages = {
  en,
  zh
}

// 类型定义
export type MessageSchema = typeof zh

src/i18n/index.ts:

import { createI18n } from 'vue-i18n'
import { messages } from './messages'
import type { MessageSchema } from './messages'

// 获取浏览器语言设置
const getBrowserLanguage = (): string => {
  const lang = navigator.language
  return lang.toLowerCase().startsWith('zh') ? 'zh' : 'en'
}

// 获取存储的语言设置
const getSavedLanguage = (): string => {
  return localStorage.getItem('language') || getBrowserLanguage()
}

export const i18n = createI18n<[MessageSchema], 'en' | 'zh'>({
  legacy: false, // 启用 Composition API 模式
  locale: getSavedLanguage(),
  fallbackLocale: 'en',
  messages,
  // 数字格式化选项
  numberFormats: {
    en: {
      currency: {
        style: 'currency',
        currency: 'USD'
      }
    },
    zh: {
      currency: {
        style: 'currency',
        currency: 'CNY'
      }
    }
  },
  // 日期格式化选项
  datetimeFormats: {
    en: {
      short: {
        year: 'numeric',
        month: 'short',
        day: 'numeric'
      }
    },
    zh: {
      short: {
        year: 'numeric',
        month: 'long',
        day: 'numeric'
      }
    }
  }
})

实际使用示例

1. 基础组件使用

src/components/LanguageSwitcher.vue:

<template>
  <div class="language-switcher">
    <select v-model="currentLocale" @change="handleLanguageChange">
      <option value="zh">中文</option>
      <option value="en">English</option>
    </select>
  </div>
</template>

<script setup lang="ts">
import { ref, watch } from 'vue'
import { useI18n } from 'vue-i18n'

const { locale } = useI18n()
const currentLocale = ref(locale.value)

const handleLanguageChange = () => {
  // 更新语言设置
  locale.value = currentLocale.value
  // 保存到本地存储
  localStorage.setItem('language', currentLocale.value)
  // 可选：刷新页面以应用新语言
  // window.location.reload()
}

// 监听语言变化
watch(locale, (newLocale) => {
  document.documentElement.setAttribute('lang', newLocale)
})
</script>

<style scoped>
.language-switcher {
  padding: 8px;
}

select {
  padding: 4px 8px;
  border-radius: 4px;
  border: 1px solid #ddd;
}
</style>

2. 在页面中使用翻译

src/components/HomePage.vue:

<template>
  <div class="home">
    <h1>{{ t('home.welcome') }}</h1>
    <p>{{ t('home.description') }}</p>
    
    <div class="features">
      <h2>{{ t('home.features.title') }}</h2>
      <ul>
        <li v-for="(feature, index) in features" :key="index">
          {{ t(`home.features.list.${index + 1}`) }}
        </li>
      </ul>
    </div>

    <!-- 数字格式化示例 -->
    <div class="price">
      {{ n(1234.56, 'currency') }}
    </div>

    <!-- 日期格式化示例 -->
    <div class="date">
      {{ d(new Date(), 'short') }}
    </div>
  </div>
</template>

<script setup lang="ts">
import { useI18n } from 'vue-i18n'

const { t, n, d } = useI18n()

const features = [1, 2, 3] // 对应 features.list 中的键
</script>

3. 动态加载翻译

src/utils/i18n-loader.ts:

import { nextTick } from 'vue'
import { i18n } from '../i18n'

export async function loadLanguageAsync(locale: string) {
  // 动态导入语言文件
  const messages = await import(`../locales/${locale}.json`)
  
  // 设置语言包
  i18n.global.setLocaleMessage(locale, messages.default)
  
  // 切换语言
  i18n.global.locale.value = locale
  
  // 设置 html lang 属性
  document.documentElement.setAttribute('lang', locale)
  
  return nextTick()
}

最佳实践与进阶技巧

1. 翻译文件管理

模块化组织

对于大型项目，建议按模块组织翻译文件：

locales/
├── zh/
│   ├── common.json
│   ├── auth.json
│   └── dashboard.json
└── en/
    ├── common.json
    ├── auth.json
    └── dashboard.json

自动合并翻译文件

创建一个脚本来合并翻译文件：

// scripts/merge-translations.ts
import * as fs from 'fs'
import * as path from 'path'

const LOCALES_DIR = path.join(__dirname, '../src/locales')

function mergeTranslations(locale: string) {
  const localeDir = path.join(LOCALES_DIR, locale)
  const files = fs.readdirSync(localeDir)
  
  const merged = files.reduce((acc, file) => {
    if (file.endsWith('.json')) {
      const content = JSON.parse(
        fs.readFileSync(path.join(localeDir, file), 'utf-8')
      )
      return { ...acc, ...content }
    }
    return acc
  }, {})
  
  fs.writeFileSync(
    path.join(LOCALES_DIR, `${locale}.json`),
    JSON.stringify(merged, null, 2)
  )
}

['en', 'zh'].forEach(mergeTranslations)

2. 类型安全

使用 TypeScript 类型来确保翻译键的类型安全

// types/i18n.d.ts
import { MessageSchema } from '@/i18n/messages'

declare module 'vue-i18n' {
  export interface DefineLocaleMessage extends MessageSchema {}
}

3. 翻译缺失检查

创建一个工具函数来检查翻译是否完整：

// utils/check-translations.ts
import en from '../locales/en.json'
import zh from '../locales/zh.json'

function findMissingKeys(obj1: any, obj2: any, path: string[] = []): string[] {
  const missing: string[] = []
  
  Object.keys(obj1).forEach(key => {
    const currentPath = [...path, key]
    if (!(key in obj2)) {
      missing.push(currentPath.join('.'))
    } else if (
      typeof obj1[key] === 'object' && 
      typeof obj2[key] === 'object'
    ) {
      missing.push(...findMissingKeys(obj1[key], obj2[key], currentPath))
    }
  })
  
  return missing
}

// 检查中文翻译是否完整
const missingInZh = findMissingKeys(en, zh)
console.log('Missing in zh:', missingInZh)

// 检查英文翻译是否完整
const missingInEn = findMissingKeys(zh, en)
console.log('Missing in en:', missingInEn)

4. 性能优化

按需加载语言包

const loadedLanguages = ['zh'] // 默认加载的语言

async function loadLanguage(lang: string) {
  // 如果语言已经加载，直接返回
  if (loadedLanguages.includes(lang)) {
    return Promise.resolve()
  }
  
  // 动态导入语言包
  const messages = await import(`./locales/${lang}.json`)
  i18n.global.setLocaleMessage(lang, messages.default)
  loadedLanguages.push(lang)
  return messages
}

5.缓存翻译结果

const loadedLanguages = ['zh'] // 默认加载的语言

async function loadLanguage(lang: string) {
  // 如果语言已经加载，直接返回
  if (loadedLanguages.includes(lang)) {
    return Promise.resolve()
  }
  
  // 动态导入语言包
  const messages = await import(`./locales/${lang}.json`)
  i18n.global.setLocaleMessage(lang, messages.default)
  loadedLanguages.push(lang)
  return messages
}

常见问题与解决方案

1. 翻译未更新

问题：切换语言后，某些组件的翻译没有更新

解决方案

<script setup>
import { watch } from 'vue'
import { useI18n } from 'vue-i18n'

const { locale } = useI18n()

// 监听语言变化，强制更新组件
watch(locale, () => {
  nextTick(() => {
    // 触发组件重新渲染
  })
})
</script>

2. 数字格式化

问题：不同地区的数字格式不一致

解决方案：使用 numberFormats 配置：

const i18n = createI18n({
  numberFormats: {
    zh: {
      currency: {
        style: 'currency',
        currency: 'CNY',
        notation: 'standard'
      },
      decimal: {
        style: 'decimal',
        minimumFractionDigits: 2,
        maximumFractionDigits: 2
      }
    },
    en: {
      currency: {
        style: 'currency',
        currency: 'USD',
        notation: 'standard'
      },
      decimal: {
        style: 'decimal',
        minimumFractionDigits: 2,
        maximumFractionDigits: 2
      }
    }
  }
})

3. 日期本地化

问题：日期格式因地区而异

解决方案：使用 datetimeFormats 配置

const i18n = createI18n({
  datetimeFormats: {
    zh: {
      short: {
        year: 'numeric',
        month: 'short',
        day: 'numeric'
      },
      long: {
        year: 'numeric',
        month: 'long',
        day: 'numeric',
        weekday: 'long',
        hour: 'numeric',
        minute: 'numeric'
      }
    },
    en: {
      short: {
        year: 'numeric',
        month: 'short',
        day: 'numeric'
      },
      long: {
        year: 'numeric',
        month: 'long',
        day: 'numeric',
        weekday: 'long',
        hour: 'numeric',
        minute: 'numeric',
        hour12: true
      }
    }
  }
})