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. 语言包文件规范
2. Key 命名规范（三层层级）
3. 公共 Key 规范（page.common）
4. 页面中如何使用（i18nMixin）
5. 常见场景 Key 模板
6. 旧项目 Key 迁移对照
7. 翻译格式规范
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（不允许尾逗号，不允许注释）
• 顶层结构：

{
  "_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界面截图对照表 中的英文列。

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

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 完整示例

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

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

对应的 i18nMixin 前缀：

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

---

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

3.1 什么应该放公共

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

{
  "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 如何使用

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

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

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

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

---

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

4.1 页面 Script 部分

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 部分

<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）

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

5.2 列表页字段 Key

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

5.3 表单校验 Key

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

5.4 登录页 Key

{
  "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}：

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

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

---

8. 新增页面 Checklist

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

• 1. 在 后台Webman界面截图对照表 中找到该页面的三级英文名
• 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 ✅