# 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 才允许提交）。