简体中文

English
日本語

简体中文

English
日本語

国际化文档 - 多语言支持和配置 ​

概述 ​

本文档详细介绍了 VJSP Vue3 框架的国际化（i18n）支持机制，包括多语言配置、语言切换、翻译文件管理以及在实际开发中的应用。

国际化架构 ​

核心特性 ​

  • 模块化翻译管理：采用模块化方式组织翻译文件，便于维护和扩展
  • 动态语言切换：支持运行时动态切换语言，无需刷新页面
  • Element Plus 集成：与 Element Plus 组件库深度集成，确保 UI 组件多语言一致性
  • 类型安全：提供类型安全的翻译函数调用
  • 持久化存储：语言偏好设置自动保存到本地存储

技术栈 ​

  • Vue I18n v11：核心国际化库
  • Element Plus 国际化：UI 组件库多语言支持
  • Pinia 状态管理：语言状态持久化
  • 动态导入：按需加载语言包，优化性能

配置机制 ​

语言配置 ​

项目支持三种语言环境：

  • 简体中文 (zh-CN)：默认语言
  • 英文 (en)：国际化支持

语言包映射 ​

Element Plus 语言包与项目语言配置的映射关系：

  • zh-CN → Element Plus zh-cn
  • en → Element Plus en

存储配置 ​

语言设置使用 localStorage 进行持久化存储，键名为 lang，确保用户偏好设置在不同会话间保持一致。

实现机制 ​

初始化流程 ​

  1. 应用启动：从 localStorage 读取用户语言偏好
  2. 插件初始化：配置 Vue I18n 实例
  3. 语言包加载：动态导入对应语言的翻译文件
  4. Element Plus 配置：设置 UI 组件库语言包
  5. 全局注册：将翻译函数注册为全局属性

语言切换机制 ​

  1. 状态更新：更新 Pinia store 中的语言状态
  2. DOM 更新：设置 HTML 页面的 lang 属性
  3. 事件通知：触发全局语言变更事件
  4. 组件响应：相关组件自动响应语言变化

翻译文件加载 ​

采用动态导入方式加载翻译文件，实现按需加载和代码分割：

  • 基础翻译文件（common 模块）
  • 系统模块翻译文件（system 模块）
  • 业务模块翻译文件（按需加载）

翻译文件结构 ​

模块化组织 ​

翻译文件按照功能模块进行组织，每个模块包含独立的翻译资源：

shell
src/locales/
├── common/          # 通用翻译
│   ├── zh-CN.ts     # 中文通用翻译
│   └── en.ts        # 英文通用翻译
├── system/          # 系统模块翻译
│   ├── zh-CN.ts     # 中文系统翻译
│   └── en.ts        # 英文系统翻译
└── module/          # 业务模块翻译

命名空间约定 ​

  • common：通用操作、表单、验证等基础翻译
  • system：系统管理相关模块翻译
  • 业务模块名：具体业务功能的翻译资源

开发指南 ​

在组件中使用翻译 ​

组合式 API 使用 ​

使用 useI18n hook 获取翻译函数：

typescript
import { useI18n } from '@/hooks/web/useI18n'

const { t } = useI18n()

// 基础翻译使用
const title = t('common.add')

// 带命名空间的翻译
const userTitle = t('system.user.pageTitle')

选项式 API 使用 ​

通过全局属性访问翻译函数：

typescript
export default {
  computed: {
    title() {
      return this.$t('common.add')
    },
  },
}

业务模块开发示例（Product 模块） ​

1. 创建翻译文件 ​

在 src/locales/module/product/ 目录下创建语言文件：

zh-CN.ts

typescript
export default {
  product: {
    pageTitle: '产品管理',
    productName: '产品名称',
    productCode: '产品编码',
    price: '价格',
    status: '状态',
    addProduct: '新增产品',
    editProduct: '编辑产品',
    deleteProduct: '删除产品',
    deleteConfirm: '确认删除产品"{name}"吗？',
    addSuccess: '产品新增成功',
    updateSuccess: '产品更新成功',
    deleteSuccess: '产品删除成功',
  },
}

en.ts

typescript
export default {
  product: {
    pageTitle: 'Product Management',
    productName: 'Product Name',
    productCode: 'Product Code',
    price: 'Price',
    status: 'Status',
    addProduct: 'Add Product',
    editProduct: 'Edit Product',
    deleteProduct: 'Delete Product',
    deleteConfirm: 'Confirm delete product "{name}"?',
    addSuccess: 'Product added successfully',
    updateSuccess: 'Product updated successfully',
    deleteSuccess: 'Product deleted successfully',
  },
}

2. 注册模块翻译 ​

在 src/plugins/vueI18n/index.ts 中添加模块名：

typescript
const otherModules: string[] = ['product']

3. 在组件中使用 ​

vue
<template>
  <div>
    <h2>{{ t('product.pageTitle') }}</h2>
    <el-button @click="handleAdd">
      {{ t('product.addProduct') }}
    </el-button>
  </div>
</template>

<script setup lang="ts">
import { useI18n } from '@/hooks/web/useI18n'

const { t } = useI18n()

const handleAdd = () => {
  // 产品新增逻辑
}
</script>

语言切换功能 ​

功能视图描述 ​

项目提供了直观的语言切换界面，用户可以通过顶部导航栏的语言选择器快速切换应用语言。语言选择器采用下拉菜单形式，显示当前语言名称并提供所有支持语言的选项列表。

工具类文件路径 ​

语言切换功能涉及以下核心文件：

  • 状态管理：src/stores/modules/locale.ts - 语言状态和配置管理
  • 工具函数：src/utils/i18n.ts - 提供语言切换和查询功能
  • 插件配置：src/plugins/vueI18n/index.ts - 国际化插件核心实现
  • 组件集成：src/layout/components/Navbar.vue - 语言选择器组件位置

切换机制 ​

语言切换采用事件驱动机制，当用户选择新语言时：

  1. 状态更新：通过 Pinia store 更新全局语言状态
  2. DOM 同步：自动更新 HTML 页面的 lang 属性
  3. 组件响应：触发全局语言变更事件，所有使用翻译的组件自动重新渲染
  4. 持久化存储：用户语言偏好自动保存到本地存储，确保下次访问时保持一致

切换过程无需页面刷新，提供流畅的用户体验，同时确保 Element Plus 组件库的语言包同步更新。

最佳实践 ​

翻译键命名规范 ​

  1. 模块前缀：使用模块名作为命名空间前缀
  2. 语义化命名：键名应清晰表达其含义
  3. 一致性：相同含义的文本使用相同的翻译键

动态参数处理 ​

使用 Vue I18n 的参数插值功能：

typescript
// 翻译文件
deleteConfirm: '确认删除"{name}"吗？'

// 组件中使用
const message = t('product.deleteConfirm', { name: productName })

复数形式处理 ​

对于需要处理复数形式的文本：

typescript
// 翻译文件
itemCount: '{count} 项 | {count} 项'

// 组件中使用
const message = t('common.itemCount', { count: itemCount }, itemCount)

错误处理 ​

  1. 键不存在处理：提供默认回退文本
  2. 加载失败处理：优雅降级到默认语言
  3. 类型安全：使用 TypeScript 确保翻译键的正确性

性能优化 ​

缓存策略 ​

  • 本地存储用户语言偏好：通过 localStorage 持久化存储用户选择的语言设置
  • 避免重复设置：语言切换时检查当前语言状态，避免不必要的更新操作

构建优化 ​

  • 压缩翻译文件：Vite 构建时自动压缩资源文件
  • 分包策略：通过 vendor 分包优化加载性能

故障排除 ​

常见问题 ​

  1. 翻译键未找到：检查键名拼写和命名空间
  2. 语言切换无效：确认语言包加载成功
  3. Element Plus 语言不匹配：检查语言包映射配置

调试技巧 ​

  1. 使用 Vue Devtools 检查翻译状态
  2. 查看浏览器控制台的语言包加载日志
  3. 验证 localStorage 中的语言设置

扩展指南 ​

添加新语言 ​

  1. 在 src/locales/ 下创建对应语言目录
  2. 添加语言包映射配置
  3. 更新语言选择器支持
  4. 测试新语言功能

自定义翻译加载器 ​

可通过修改 loadModuleMessages 函数实现自定义翻译加载逻辑，支持从远程服务器或 CDN 加载翻译资源。