8a4511dc36
1. 新增国际化规范文档 `i18n-rules.md`，详细说明项目国际化的规范、key 命名、使用方式等 2. 新增登录页面搬迁文档 `login-page-migration.md`，记录登录页搬迁的步骤、依赖和验证清单 3. 修复生产主数据路由文件中多余的尾随字符
446 lines
14 KiB
Markdown
446 lines
14 KiB
Markdown
# 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` ✅ |
|