68 lines
3.5 KiB
Markdown
68 lines
3.5 KiB
Markdown
# entity 模块 i18n 提取说明（W-03 实体管理）
|
||
|
||
本文件是 entity 模块**新文案 i18n 提取清单与引用约定**，覆盖两个新增页面
|
||
（`wwwroot/index.ui`、`wwwroot/import_page.ui`）及后端错误码/按钮等全部新文案。
|
||
|
||
## 1. i18n 文件清单
|
||
|
||
| 文件 | 语言 | 内容 |
|
||
|------|------|------|
|
||
| `wwwroot/i18n/zh-CN.json` | 简体中文 | 全部 UI 文案 + 错误码文案 + 字典文案 |
|
||
| `wwwroot/i18n/en-US.json` | 英文 | 与 zh-CN 键一一对应 |
|
||
|
||
i18n 文件与页面同置于 `wwwroot/` 下，宿主应用加载时按当前语言读取对应 json，
|
||
键缺失时回退到 `zh-CN.json`，仍缺失则显示键名本身（不阻塞页面）。
|
||
|
||
## 2. 键命名规则（扁平点分，前缀 entity.）
|
||
|
||
| 前缀 | 用途 | 示例 |
|
||
|------|------|------|
|
||
| `entity.page.*` | 页面标题/副标题 | `entity.page.index.title` |
|
||
| `entity.btn.*` | 按钮文案 | `entity.btn.add` |
|
||
| `entity.col.*` | 表格列头 | `entity.col.name` |
|
||
| `entity.filter.*` | 筛选区标签/占位 | `entity.filter.world_id` |
|
||
| `entity.form.*` | 新增/编辑表单标签 | `entity.form.code` |
|
||
| `entity.import.*` | 导入页专用文案 | `entity.import.col.total` |
|
||
| `entity.msg.*` | 操作提示/消息 | `entity.msg.confirm_delete` |
|
||
| `entity.dict.*` | 字典下拉（entity_type / entity_status / import_status） | `entity.dict.entity_type.npc` |
|
||
| `entity.err.*` | 后端错误码→文案映射 | `entity.err.DUPLICATE_CODE` |
|
||
| `entity.field.*` | 错误码文案中的字段标签占位 | `entity.field.name` |
|
||
|
||
## 3. 页面引用方式
|
||
|
||
- `index.ui`（实体列表页）：标题/按钮/列头/筛选/表单/提示全部使用
|
||
`entity.page.index.title`、`entity.btn.add`、`entity.col.name` 等键，经宿主
|
||
i18n 函数取文案，禁止硬编码中文。
|
||
- `import_page.ui`（实体导入页）：使用 `entity.page.import.*`、`entity.import.*`、
|
||
`entity.btn.*` 键。
|
||
- 字典下拉（世界/场景/实体类型/状态/导入状态）取值经 `get_search_*.dspy` 返回
|
||
`[{value,text}]`，其中 `text` 优先取 i18n 文案（`entity.dict.*`），服务端字典
|
||
值作为兜底。
|
||
|
||
## 4. 错误码 → 文案映射约定
|
||
|
||
接口统一返回错误结构 `{code, message, field, detail}`。前端展示优先级：
|
||
1. 取 `entity.err.{code}` 对应 i18n 文案（支持 `{label}`/`{max}` 占位符替换，
|
||
占位值来自 `field` 对应的 `entity.field.*` 与 `detail`）；
|
||
2. 无映射时回退接口返回的 `message`。
|
||
|
||
已提取的错误码（10 个）：
|
||
|
||
| code | 中文文案 | 英文文案 |
|
||
|------|----------|----------|
|
||
| PARAM_REQUIRED | 缺少必要参数 | Missing required parameter |
|
||
| FIELD_REQUIRED | {label}不能为空 | {label} is required |
|
||
| FIELD_TOO_LONG | {label}长度不能超过{max} | {label} length cannot exceed {max} |
|
||
| WORLD_NOT_FOUND | 所属世界不存在 | World not found |
|
||
| SCENE_NOT_FOUND | 所属场景不存在 | Scene not found |
|
||
| DUPLICATE_CODE | 实体编码已存在 | Entity code already exists |
|
||
| PARSE_ERROR | 文件解析失败 | File parse error |
|
||
| INVALID_JSON | 属性JSON格式错误 | Invalid attributes JSON |
|
||
| DB_ERROR | 数据库操作失败 | Database operation failed |
|
||
| NOT_FOUND | 记录不存在 | Record not found |
|
||
|
||
## 5. 新增文案流程（维护约定）
|
||
|
||
新增任何页面文案/错误码/按钮时：先在 `zh-CN.json` 与 `en-US.json` 同步增加同键
|
||
条目，再在页面中引用该键。两文件键集合必须保持一致（提交前用脚本比对
|
||
`jq -S 'keys'` 两文件差异，差异为 0 才允许提交）。 |