soilgd12/语言切换.txt

## 项目中英文转换逻辑说明

### 一、国际化(i18n)架构概述

本项目采用 **Vue I18n** 实现中英文双语切换，核心架构包含配置层、语言包层和组件调用层三个层次。

---

### 二、核心文件结构

| 文件路径 | 功能说明 |
|---------|---------|
| `src/i18n.ts` | Vue I18n 核心配置，注册语言包 |
| `src/i18n.d.ts` | TypeScript 类型定义文件 |
| `src/locales/zh.json` | 中文语言包（键值对存储） |
| `src/locales/en.json` | 英文语言包（与中文键结构一致） |
| `src/locales/index.js` | 备用语言管理模块 |
| `scripts/extract-i18n.js` | 自动提取国际化标记的脚本 |

---

### 三、中英文转换核心逻辑

#### 3.1 配置初始化 (`src/i18n.ts`)

```typescript
import { createI18n } from 'vue-i18n';
import zh from './locales/zh.json';
import en from './locales/en.json';

const i18n = createI18n({
legacy: false,           // 使用 Composition API 模式
locale: 'zh',            // 默认语言：中文
fallbackLocale: 'en',    // 回退语言：英文
messages: { zh, en },    // 语言包映射对象
});

export default i18n;
```

**关键配置说明：**
- `legacy: false` - 启用 Vue 3 Composition API 兼容模式
- `locale` - 当前活跃语言标识
- `fallbackLocale` - 当某个 key 在当前语言包不存在时，使用回退语言

#### 3.2 语言包结构

语言包采用**嵌套 JSON 结构**，支持层级键路径：

```json
// src/locales/zh.json
{
"Header": {
    "title": "土壤酸化智能预测专家系统",
    "welcome": "欢迎",
    "logout": "退出登录"
},
"login": {
    "userTitle": "用户登录",
    "loginButton": "登录",
    "loginFailed": "登录失败，请检查用户名或密码"
},
"validation": {
    "usernameRequired": "请输入账号",
    "passwordLength": "密码长度为 3 到 16 个字符"
}
}
```

#### 3.3 组件调用方式

**Vue 模板中的使用：**

```vue
<template>
<!-- 直接使用 t() 函数 -->
<h2>{{ t('login.userTitle') }}</h2>

<!-- 表单验证 -->
<el-input :placeholder="t('validation.usernameRequired')" />

<!-- 动态文本 -->
<el-button>{{ t('login.loginButton') }}</el-button>
</template>

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

const { t, locale } = useI18n();

// 切换语言
const toggleLanguage = () => {
locale.value = locale.value === 'zh' ? 'en' : 'zh';
localStorage.setItem('lang', locale.value);
};
</script>
```

**TypeScript 文件中的使用：**

```typescript
// 在组合式函数中使用
import { useI18n } from 'vue-i18n';

const { t } = useI18n();

// 用于消息提示
ElMessage.success(t('login.loginSuccess'));

// 用于动态文本
const errorMsg = t('login.loginFailed');
```

---

### 四、语言切换流程

#### 4.1 完整切换流程（以登录页为例）

```typescript
// src/views/login/loginView.vue
const toggleLanguage = async () => {
// 1. 计算新语言
const newLocale = locale.value === "zh" ? "en" : "zh";

// 2. 更新 Vue I18n locale（触发视图自动更新）
locale.value = newLocale;

// 3. 持久化到 localStorage（刷新页面保持语言设置）
localStorage.setItem("lang", newLocale);

// 4. 可选：同步到后端（保存用户语言偏好）
try {
    await changeLanguageAPI({
    language: newLocale,
    userId: store.userInfo?.userId,
    timestamp: Date.now(),
    });
} catch (error) {
    console.error("语言切换同步失败:", error);
}
};
```

#### 4.2 初始化时的语言恢复

在应用启动时，从 localStorage 读取上次保存的语言：

```typescript
// src/main.ts
const savedLang = localStorage.getItem('lang') || 'zh';
const i18n = createI18n({
locale: savedLang,
// ... 其他配置
});
```

---

### 五、国际化标记提取脚本

#### 5.1 脚本位置和功能

**脚本文件：** `scripts/extract-i18n.js`

**核心功能：**
- 自动扫描 `.vue` 和 `.ts` 文件
- 识别特定标记格式的中文文本
- 自动生成/更新语言包文件

#### 5.2 使用方法

```bash
# 扫描整个 src 目录（默认）
node scripts/extract-i18n.js

# 扫描指定目录
node scripts/extract-i18n.js src/views/User

# 扫描单个文件
node scripts/extract-i18n.js src/components/layout/AppLayout.vue
```

#### 5.3 提取标记格式

在 Vue/TS 文件中使用以下格式标记需要国际化的文本：

```vue
<!--i18n:模块名.键名-->中文文本内容
```

**示例：**

```vue
<!--i18n:Header.title-->土壤酸化智能预测专家系统
<!--i18n:login.userTitle-->用户登录
<!--i18n:Menu.dataManagement-->数据管理
```

#### 5.4 脚本处理流程

```
1. 解析命令行参数 → 确定扫描路径
2. 读取已有语言包 → 保留历史翻译
3. 递归扫描文件 → 收集 .vue/.ts 文件
4. 正则匹配标记 → 提取键名和中文文本
5. 构建嵌套对象 → 处理键路径（如 Menu.subMenu.item）
6. 写入语言包 → 更新 zh.json 和 en.json
```

#### 5.5 脚本核心代码解析

**标记匹配正则：**
```javascript
const regex = /<!--i18n:(\S+)-->([\u4e00-\u9fa5\w\s,.，。；;！!？?：:()（）]+?)(?=\r?\n|['"<]|$)/g;
```

**嵌套键设置函数：**
```javascript
function setNestedValue(obj, keyPath, value) {
const keys = keyPath.split('.');
let current = obj;

for (let i = 0; i < keys.length - 1; i++) {
    const key = keys[i];
    if (typeof current[key] === 'string') {
    console.warn(`键名冲突："${key}" 已作为字符串存在`);
    return;
    }
    if (!current[key] || typeof current[key] !== 'object') {
    current[key] = {};
    }
    current = current[key];
}

const lastKey = keys[keys.length - 1];
if (current[lastKey] === undefined) {
    current[lastKey] = value;
}
}
```

---

### 六、语言包维护规范

| 规范项 | 说明 |
|-------|------|
| **键命名** | 使用 `模块名.子模块.键名` 格式，如 `Menu.dataManagement` |
| **结构对齐** | 中英文语言包必须保持**完全相同的键结构** |
| **值处理** | 中文包存储中文原文，英文包存储对应英文翻译 |
| **新增翻译** | 同时在 `zh.json` 和 `en.json` 中添加键值对 |
| **标记规范** | 使用 `<!--i18n:键名-->` 标记便于脚本提取 |
| **避免硬编码** | 所有用户可见文本必须通过 `t()` 函数获取 |

---

### 七、现有翻译覆盖范围

| 模块 | 说明 |
|-----|------|
| **Header** | 顶部导航栏文本 |
| **login/register/logout** | 登录、注册、退出相关 |
| **Menu** | 侧边栏菜单项 |
| **validation** | 表单验证提示 |
| **AcidModelMap** | 酸化模型地图相关 |
| **PhPrediction** | pH 预测模型相关 |
| **Calculation** | 计算模块相关 |
| **DetectionStatistics** | 检测统计相关 |
| **SoilCdStatistics** | 土壤镉统计相关 |
| **LandCultivatedStatistics** | 耕地统计相关 |

---

### 八、Element Plus 组件国际化

Element Plus 组件默认使用中文，如需支持英文需额外配置：

```typescript
// src/main.ts
import ElementPlus from 'element-plus';
import zhCn from 'element-plus/es/locale/lang/zh-cn';
import en from 'element-plus/es/locale/lang/en';

// 根据当前语言动态切换 Element Plus 语言
app.use(ElementPlus, {
locale: locale.value === 'zh' ? zhCn : en,
});
```

---

### 九、扩展说明

#### 9.1 添加新翻译流程

1. **标记文本**：在 Vue/TS 文件中添加 `<!--i18n:键名-->` 标记
2. **运行脚本**：执行 `node scripts/extract-i18n.js` 提取标记
3. **翻译英文**：在 `en.json` 中填写对应英文翻译
4. **使用翻译**：在组件中使用 `t('键名')` 获取文本

#### 9.2 语言切换事件通知

通过自定义事件通知其他组件语言变化：

```typescript
// 触发语言切换事件
window.dispatchEvent(new CustomEvent('languageChanged', { 
detail: { locale: locale.value } 
}));

// 监听语言切换事件
window.addEventListener('languageChanged', (e) => {
console.log('语言已切换为:', e.detail.locale);
});
```