entity/docs/i18n.md

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