intelligent-etmf-system-applet/i18n/README.md

国际化使用指南

目录结构

├── i18n/                   # i18n 配置目录
│   ├── index.js           # i18n 初始化配置
│   └── README.md          # 使用文档
├── locales/               # 语言包目录（按模块分组）
│   ├── common/           # 通用模块
│   │   ├── zh_CN.js     # 中文翻译
│   │   └── en_US.js     # 英文翻译
│   ├── pages/            # 页面模块
│   │   └── home/        # 首页模块
│   │       ├── zh_CN.js # 中文翻译
│   │       └── en_US.js # 英文翻译
│   ├── index.js          # 语言包导出
│   └── README.md         # 语言包管理文档
├── store/                 # 状态管理
│   └── locale.js         # 语言切换 store
└── components/            # 组件
    └── LanguageSwitcher/ # 语言切换组件

快速开始

1. 在页面中使用

<template>
  <view>
    <!-- 使用 t 函数翻译 -->
    <text>{{ t('home.title') }}</text>
    
    <!-- 使用嵌套的翻译键 -->
    <text>{{ t('common.button.confirm') }}</text>
  </view>
</template>

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

const { t } = useI18n()
</script>

2. 在 JS 中使用

import { useI18n } from 'vue-i18n'

const { t } = useI18n()

// 使用翻译
const message = t('common.message.success')

// 使用参数
const greeting = t('common.greeting', { name: '张三' })

3. 切换语言

<script setup>
import { useLocaleStore } from '@/store/locale'

const localeStore = useLocaleStore()

// 切换到指定语言
localeStore.setLocale('en-US')

// 切换到下一个语言
localeStore.toggleLocale()

// 获取当前语言
const currentLang = localeStore.currentLocale
</script>

4. 使用语言切换组件

<template>
  <view>
    <!-- 直接使用组件 -->
    <LanguageSwitcher />
  </view>
</template>

<script setup>
import LanguageSwitcher from '@/components/LanguageSwitcher/index.vue'
</script>

添加新的语言模块

1. 创建新模块文件

在对应目录下创建语言文件：

// locales/pages/user/zh_CN.js
export default {
  profile: '个人资料',
  settings: '设置',
  logout: '退出登录'
}

// locales/pages/user/en_US.js
export default {
  profile: 'Profile',
  settings: 'Settings',
  logout: 'Logout'
}

2. 在索引文件中导入

// locales/index.js
import commonZhCN from './common/zh_CN'
import commonEnUS from './common/en_US'
import homeZhCN from './pages/home/zh_CN'
import homeEnUS from './pages/home/en_US'
import userZhCN from './pages/user/zh_CN'  // 新增
import userEnUS from './pages/user/en_US'  // 新增

export const messages = {
  'zh-CN': {
    common: commonZhCN,
    home: homeZhCN,
    user: userZhCN  // 新增
  },
  'en-US': {
    common: commonEnUS,
    home: homeEnUS,
    user: userEnUS  // 新增
  }
}

3. 在页面中使用

<template>
  <text>{{ t('user.profile') }}</text>
</template>

添加新的语言

1. 创建新语言文件

为每个现有模块添加新语言翻译：

locales/
  ├── common/
  │   ├── zh_CN.js
  │   ├── en_US.js
  │   └── ja_JP.js        # 新增日文
  └── pages/
      └── home/
          ├── zh_CN.js
          ├── en_US.js
          └── ja_JP.js    # 新增日文

2. 更新语言配置

// locales/index.js
import commonZhCN from './common/zh_CN'
import commonEnUS from './common/en_US'
import commonJaJP from './common/ja_JP'  // 新增

import homeZhCN from './pages/home/zh_CN'
import homeEnUS from './pages/home/en_US'
import homeJaJP from './pages/home/ja_JP'  // 新增

export const messages = {
  'zh-CN': {
    common: commonZhCN,
    home: homeZhCN
  },
  'en-US': {
    common: commonEnUS,
    home: homeEnUS
  },
  'ja-JP': {  // 新增
    common: commonJaJP,
    home: homeJaJP
  }
}

export const localeList = [
  { label: '简体中文', value: 'zh-CN' },
  { label: 'English', value: 'en-US' },
  { label: '日本語', value: 'ja-JP' }  // 新增
]

最佳实践

1. 命名规范

• 使用小驼峰命名法：userName、submitButton
• 使用有意义的名称，避免使用 text1、label2 等
• 保持中英文翻译键一致

2. 模块划分

• 按功能模块划分：common、home、user、order 等
• common 模块存放通用文本：按钮、提示信息等
• 每个页面或功能一个独立模块

3. 翻译键结构

// ✅ 推荐
{
  user: {
    profile: {
      title: '个人资料',
      name: '姓名',
      email: '邮箱'
    }
  }
}

// ❌ 不推荐
{
  userProfileTitle: '个人资料',
  userProfileName: '姓名',
  userProfileEmail: '邮箱'
}

4. 带参数的翻译

// locales/zh-CN/common.js
export default {
  greeting: '你好，{name}！',
  itemCount: '共 {count} 项'
}

// 使用
t('common.greeting', { name: '张三' })
t('common.itemCount', { count: 10 })

API 文档

useLocaleStore

const localeStore = useLocaleStore()

// 属性
localeStore.currentLocale        // 当前语言
localeStore.availableLocales     // 可用语言列表

// 方法
localeStore.initLocale()         // 初始化语言设置
localeStore.setLocale(locale)    // 设置语言
localeStore.toggleLocale()       // 切换到下一个语言
localeStore.getCurrentLocaleName() // 获取当前语言名称

useI18n

const { t, locale } = useI18n()

// 翻译文本
t('home.title')
t('common.greeting', { name: 'John' })

// 获取当前语言
console.log(locale.value)

注意事项

1. uni-app 兼容性：确保使用的 i18n 特性在小程序环境中可用
2. 性能优化：语言包会在应用启动时全部加载，注意控制大小
3. 持久化：语言设置会自动保存到本地存储
4. SSR 支持：使用 createSSRApp 时需要特别配置（已完成）

故障排查

问题：翻译不生效

检查：

1. 是否正确导入了模块
2. 翻译键是否正确
3. i18n 是否正确注册

问题：语言切换后部分文本未更新

原因：可能使用了非响应式的方式获取翻译 解决：确保使用 t() 函数或 computed 包装

问题：小程序中报错

检查：

1. 确保使用 legacy: false 配置
2. 确保正确配置了 globalInjection