mes-ui-d2/docs/i18n-rules.md

# i18n 国际化规范文档

> **版本**：v1.0  
> **适用项目**：`mes-ui`  
> **语言包文件**：`src/locales/zh-chs.json` / `src/locales/en.json` / `src/locales/zh-cht.json` / `src/locales/ja.json`  
> **配合使用**：`src/composables/useI18n.js`（`i18nMixin`）

---

## 目录

1. [语言包文件规范](#1-语言包文件规范)
2. [Key 命名规范（三层层级）](#2-key-命名规范三层层级)
3. [公共 Key 规范（page.common）](#3-公共-key-规范pagecommon)
4. [页面中如何使用（i18nMixin）](#4-页面中如何使用i18nmixin)
5. [常见场景 Key 模板](#5-常见场景-key-模板)
6. [旧项目 Key 迁移对照](#6-旧项目-key-迁移对照)
7. [翻译格式规范](#7-翻译格式规范)
8. [新增页面 Checklist](#8-新增页面-checklist)

---

## 1. 语言包文件规范

### 1.1 文件清单

| 文件 | 语言 | `_element` 值 |
|------|------|--------------|
| `src/locales/zh-chs.json` | 简体中文 | `"zh-CN"` |
| `src/locales/zh-cht.json` | 繁体中文 | `"zh-TW"` |
| `src/locales/en.json` | 英文 | `"en"` |
| `src/locales/ja.json` | 日文 | `"ja"` |

### 1.2 文件格式

- **编码**：UTF-8
- **格式**：标准 JSON（不允许尾逗号，不允许注释）
- **顶层结构**：

```json
{
  "_element": "zh-CN",
  "_name": "简体中文",
  "page": { ... }
}
```

- `_element`：对应 `element-ui/lib/locale/lang/` 的语言包文件名
- `_name`：语言切换下拉菜单中的显示名
- `page`：所有业务翻译的根节点，之下按模块层级嵌套

### 1.3 维护原则

- 中文和英文文件**必须保持 key 结构完全一致**，不允许一边有 key 而另一边没有
- 新增页面时**中英文同步添加**
- 每次新增后用 `node -e "JSON.parse(require('fs').readFileSync('src/locales/zh-chs.json','utf8'))"` 验证 JSON 合法性

---

## 2. Key 命名规范（三层层级）

### 2.1 核心规则

```
page.{一级模块英文} .{二级模块英文} .{三级模块英文} .{具体key}
     └─ snake_case ─┘└─ snake_case ─┘└─ snake_case ─┘
```

**英文来源**：[后台Webman界面截图对照表](./后台Webman界面截图对照表.md) 中的英文列。

**格式转换**：对照表英文 → 全小写 + 空格替换为下划线 + `&` 替换为下划线。

### 2.2 对照表 → i18n Key 映射表

| 对照表英文名 | snake_case（用于 i18n key） | kebab-case（用于目录名） |
|-------------|---------------------------|------------------------|
| System Administration | `system_administration` | `system-administration` |
| Production Master Data | `production_master_data` | `production-master-data` |
| Equipment Management | `equipment_management` | `equipment-management` |
| Planning & Production | `planning_production` | `planning-production` |
| Quality Management | `quality_management` | `quality-management` |
| Data Platform | `data_platform` | `data-platform` |
| Factory Model | `factory_model` | `factory-model` |
| Process Model | `process_model` | `process-model` |
| Product Management | `product_management` | `product-management` |
| Material Model | `material_model` | `material-model` |
| SPC Configuration | `spc_configuration` | `spc-configuration` |
| Team Model | `team_model` | `team-model` |
| User Management | `user_management` | `user-management` |
| Menu Management | `menu_management` | `menu-management` |
| System Utilities | `system_utilities` | `system-utilities` |
| System Monitoring | `system_monitoring` | `system-monitoring` |
| Batch Management | `batch_management` | `batch-management` |
| Production Monitoring | `production_monitoring` | `production-monitoring` |
| Process Control | `process_control` | `process-control` |
| Inspection Management | `inspection_management` | `inspection-management` |
| Traceability | `traceability` | `traceability` |
| Production Reports | `production_reports` | `production-reports` |
| Correlation Analysis | `correlation_analysis` | `correlation-analysis` |
| Factory Area | `factory_area` | `factory-area` |
| Production Line | `production_line` | `production-line` |

> **完整映射表**见本文档末尾附录 A。

### 2.3 完整示例

以「生产配置 → 工厂模型 → 工厂区域」页面为例：

```json
{
  "page": {
    "production_master_data": {
      "factory_model": {
        "factory_area": {
          "search": "查询",
          "reset": "重置",
          "code": "所区编码",
          "name": "所区名称",
          "add": "新 增",
          "edit": "编 辑",
          "delete": "删 除"
        }
      }
    }
  }
}
```

对应的 `i18nMixin` 前缀：

```js
mixins: [i18nMixin('page.production_master_data.factory_model.factory_area')]
```

---

## 3. 公共 Key 规范（page.common）

### 3.1 什么应该放公共

跨页面、跨模块重复出现的文案，提取到 `page.common` 下：

```json
{
  "page": {
    "common": {
      "help": "帮 助",
      "confirm": "确定",
      "cancel": "取消",
      "save": "保存",
      "delete": "删除",
      "edit": "编辑",
      "add": "新增",
      "search": "查询",
      "reset": "重置",
      "operation": "操作",
      "tip": "提示",
      "confirm_delete": "确定要执行该操作吗?",
      "operation_success": "操作成功",
      "no_data": "暂无数据",
      "loading": "加载中..."
    }
  }
}
```

### 3.2 已有公共 Key 清单

| key | 中文 | 英文 | 用途 |
|-----|------|------|------|
| `page.common.help` | 帮 助 | Help | 表格工具栏右侧帮助按钮 |

> 后续发现跨页面共用 key 时，持续往 `page.common` 中补充。

### 3.3 如何使用

```vue
<page-table :help-text="$t(ckey('help'))" />
```

`ckey('help')` → `'page.common.help'`，由 `i18nMixin` 自动注入。

### 3.4 判断标准：该不该放 common？

| 情况 | 放哪里 | 示例 |
|------|--------|------|
| 多个一级模块都出现 | `page.common` | 帮助、确定、取消 |
| 只在本模块内出现 | 模块自己的 key | 所区编码、产线编码 |
| 不确定 | 先放在模块内，等第二次出现时提取 | — |

---

## 4. 页面中如何使用（i18nMixin）

### 4.1 页面 Script 部分

```js
import { i18nMixin } from '@/composables/useI18n'

export default {
  mixins: [i18nMixin('page.production_master_data.factory_model.factory_area')],
  data () {
    const t = this.$t.bind(this)
    const k = (s) => t(this.key(s))    // 当前页面翻译
    const ck = (s) => t(this.ckey(s))  // 公共翻译

    return {
      formCols: [
        [{ label: k('code'), placeholder: k('enter_code') }]
      ],
      rules: {
        code: [{ required: true, message: k('enter_code'), trigger: 'blur' }]
      }
    }
  },
  created () {
    this.columns = useTableColumns([
      { prop: 'code', label: this.key('code') }
    ])
  }
}
```

### 4.2 页面 Template 部分

```vue
<template>
  <!-- 当前页面翻译 -->
  <el-form-item :label="$t(key('code'))">
    <el-input :placeholder="$t(key('enter_code'))" />
  </el-form-item>
  <el-button>{{ $t(key('search')) }}</el-button>

  <!-- 公共翻译 -->
  <page-table :help-text="$t(ckey('help'))" />
</template>
```

### 4.3 data() 中翻译的时机说明

`data()` 在 `created` 之前执行，此时 `this` 已经可用。因此：

- **column label / formCols / rules.message**：在 `data()` 中或 `created()` 中 `this.key()` 都可以
- **推荐在 `data()` 中用 `k()` 提前翻译**，避免子组件 `$t()` 的 webpack HMR 缓存问题

---

## 5. 常见场景 Key 模板

### 5.1 标准 CRUD 页面（每个页面必有的 key）

```json
{
  "search": "查询",
  "reset": "重置",
  "add": "新 增",
  "edit": "编 辑",
  "delete": "删 除",
  "operation": "操作",
  "add_title": "新增{模块名}",
  "edit_title": "编辑{模块名}",
  "operation_success": "操作成功",
  "confirm_delete": "确定要执行该操作吗?",
  "enter_xxx": "请输入{字段名}",
  "select_xxx": "请选择{字段名}"
}
```

### 5.2 列表页字段 Key

```json
{
  "sort": "序号",
  "code": "{实体}编码",
  "name": "{实体}名称",
  "remark": "备注"
}
```

### 5.3 表单校验 Key

```json
{
  "enter_code": "请输入{实体}编码",
  "enter_name": "请输入{实体}名称",
  "remark_length": "长度在 1 到 100 个字符",
  "validation_fail": "校验失败"
}
```

### 5.4 登录页 Key

```json
{
  "username": "用户名",
  "password": "密码",
  "login": "登录",
  "please_enter_username": "请输入用户名",
  "please_enter_password": "请输入密码",
  "form_validation_failed": "表单校验失败，请检查"
}
```

---

## 6. 旧项目 Key 迁移对照

### 6.1 旧 Key 结构 vs 新 Key 结构

旧项目 key 路径深且命名不统一：

| 旧 key 前缀 | 新 key 前缀 |
|-----------|-----------|
| `page.system_settings.user_management.role` | `page.system_administration.user_management.role` |
| `page.system_settings.user_management.user` | `page.system_administration.user_management.user` |
| `page.system_settings.menu_configuration.menu` | `page.system_administration.menu_management.menu_configuration` |
| `page.system_settings.system_assistant.operate_log` | `page.system_administration.system_utilities.operation_logs` |
| `page.system_settings.system_monitoring.system.login` | `page.system_administration.system_monitoring.login` |
| `page.production_configuration.factory_model.factory_area` | `page.production_master_data.factory_model.factory_area` |
| `page.production_configuration.matetial_model.*` | `page.production_master_data.material_model.*` |
| `page.planning_production.production_batch_management.batch` | `page.planning_production.batch_management.batch_list` |
| `page.data_middleground.basic_traceability.*` | `page.data_platform.traceability.*` |
| `page.warehouse.*` | `page.warehouse.*`（待确定对照表英文名） |

### 6.2 搬迁时的操作步序

1. 确定页面对应的对照表三级模块英文名
2. 按 `page.{一级}.{二级}.{三级}` 组装新 key 前缀
3. 在 `zh-chs.json` 中按三层嵌套创建节点
4. 在 `en.json` 中创建相同结构
5. 将旧 key 的翻译值复制到新 key 下
6. 页面代码中 `i18nMixin` 参数改为新前缀
7. 模板中 `$t('旧key')` 全部改为 `$t(key('新suffix'))`

---

## 7. 翻译格式规范

### 7.1 中文规范

| 场景 | 格式 | 示例 |
|------|------|------|
| 按钮文字 | 字间加空格（两字不加） | `"查询"`、`"新 增"`、`"批量删除"` |
| 占位提示 | `请输入{名称}` | `"请输入所区编码"` |
| 校验消息 | 完整句，不加句号 | `"长度在 1 到 100 个字符"` |
| 提示弹框 | 加问号 | `"确定要执行该操作吗?"` |
| 操作成功消息 | 不加"成功"后缀的冗余 | `"操作成功"`（而非"保存成功"、"编辑成功"各自定义） |

### 7.2 英文规范

| 场景 | 格式 | 示例 |
|------|------|------|
| 按钮文字 | 首字母大写 | `"Search"`、`"Add"`、`"Edit"` |
| 占位提示 | `Please enter {name}` | `"Please enter area code"` |
| 校验消息 | 完整句 | `"Length should be 1 to 100 characters"` |
| 提示弹框 | 问句 | `"Are you sure to delete?"` |
| 操作成功消息 | 过去式或名词 | `"Operation succeeded"` |

### 7.3 占位符

使用 `{name}` 格式，不使用 `%s` / `{0}`：

```json
"please_enter": "请输入{name}"
```

```js
this.$t('please_enter', { name: '所区编码' })
// → "请输入所区编码"
```

---

## 8. 新增页面 Checklist

新增一个 CRUD 页面时，按以下顺序操作：

- [ ] 1. 在 [后台Webman界面截图对照表](./后台Webman界面截图对照表.md) 中找到该页面的三级英文名
- [ ] 2. 确定 i18n key 前缀：`page.{一级snake_case}.{二级snake_case}.{三级snake_case}`
- [ ] 3. 在 `zh-chs.json` 的对应节点下添加本页面全部 key
- [ ] 4. 在 `en.json` 的相同节点下添加对应英文翻译
- [ ] 5. 验证 JSON 合法性：`node -e "JSON.parse(require('fs').readFileSync('src/locales/zh-chs.json','utf8'))"`
- [ ] 6. 页面中使用 `mixins: [i18nMixin('key前缀')]`
- [ ] 7. 模板中用 `$t(key('xxx'))` 替代硬编码文字
- [ ] 8. data() 中用 `k('xxx')` 提前翻译 formCols / rules
- [ ] 9. 公共文案（帮助、确定、取消等）用 `ckey('xxx')` 引用
- [ ] 10. `pnpm lint` 无报错

---

## 附录 A：对照表 → i18n Key 完整映射

### 一级模块

| 对照表英文 | snake_case（i18n） | kebab-case（目录） |
|-----------|-------------------|-------------------|
| System Administration | `system_administration` | `system-administration` |
| Production Master Data | `production_master_data` | `production-master-data` |
| Equipment Management | `equipment_management` | `equipment-management` |
| Planning & Production | `planning_production` | `planning-production` |
| Quality Management | `quality_management` | `quality-management` |
| Data Platform | `data_platform` | `data-platform` |
| Warehouse | `warehouse` | `warehouse` |
| SCADA Management | `scada_management` | `scada-management` |

### 生产配置 → 二级模块

| 二级（对照表） | snake_case | 三级页面数 |
|---------------|-----------|:--:|
| Factory Model | `factory_model` | 2 |
| Process Model | `process_model` | 3 |
| Product Management | `product_management` | 2 |
| Material Model | `material_model` | 4 |
| SPC Configuration | `spc_configuration` | 1 |
| Team Model | `team_model` | 3 |

### 设备模型 → 二级模块

| 二级（对照表） | snake_case |
|---------------|-----------|
| Equipment Category | `equipment_category` |
| Equipment Management | `equipment_management` |
| Inspection Management | `inspection_management` |
| Maintenance Management | `maintenance_management` |
| Repair Management | `repair_management` |
| Consumables Management | `consumables_management` |

### 系统设置 → 二级/三级

| 二级（对照表） | snake_case | 三级 snake_case |
|---------------|-----------|----------------|
| User Management | `user_management` | `role` / `user` |
| Menu Management | `menu_management` | `menu_configuration` |
| System Utilities | `system_utilities` | `operation_logs` / `api_logs` |
| System Monitoring | `system_monitoring` | `monitoring_configuration` |
| Organization | `organization` | `production_team_manage` / `production_shift_management` / `production_shift_calender` |
| OCR | `ocr` | `config` / `log` |

---

## 附录 B：当前已实施页面

| 页面 | i18nMixin 前缀 | 语言包节点 |
|------|---------------|----------|
| 工厂区域 | `page.production_master_data.factory_model.factory_area` | `zh-chs.json` / `en.json` ✅ |