SQLBot/docs/agents/i18n.md

# 国际化 Agent 说明

## 普通文案

- 前端界面文案使用 vue-i18n，JSON 位于 `frontend/src/i18n/`。
- 后端返回给用户的错误和提示使用 `backend/locales/`。
- 两处都必须同步五种语言：
  - `en`
  - `zh-CN`
  - `zh-TW`
  - `ko-KR`
  - `th-TH`
- 以 `zh-CN` 的键结构为基准校验其他语言。
- 不要把新用户可见文案硬编码在 Vue 组件、后端 handler、异常消息或 prompt 展示层中。
- 后端 Swagger summary/description 使用 `PLACEHOLDER_PREFIX` 模式时，确认对应翻译键存在。

可以用脚本比较键路径，但不要为了普通文案变更引入新依赖。

## 新增语言

新增语言不是只添加 JSON 文件。以提交 `21961e2d`（Thai / `th-TH`）为完整示例，逐项检查：

### 前端

- 添加 `frontend/src/i18n/<locale>.json`，并与 `zh-CN.json` 保持键结构一致。
- 在 `frontend/src/i18n/index.ts`：
  - import 语言 JSON；
  - 注册 messages；
  - import 并注册 Element Plus / `element-plus-secondary` locale。
- 更新语言选择入口：
  - `frontend/src/components/Language-selector/index.vue`
  - `frontend/src/components/layout/Person.vue`
- 更新浏览器语言识别：
  - `frontend/src/utils/utils.ts`
- 更新旧版下划线别名：
  - `frontend/src/stores/user.ts`
  - 例如 `th_TH` → `th-TH`。
- 在所有既有前端 locale 中新增该语言名称键，例如 `common.thai`。

### 后端

- 添加 `backend/locales/<locale>.json`。
- 更新用户语言白名单：
  - `backend/apps/system/api/user.py`
  - `backend/apps/mcp/mcp.py`
- 更新 schema 正则和显式校验：
  - `backend/apps/system/schemas/system_schema.py`
- 同步 MCP 参数描述中的语言枚举：
  - `backend/apps/chat/models/chat_model.py`

### 模型输出

- 更新 `backend/apps/chat/task/llm.py` 中 `get_lang_name` 的语言映射。
- 检查 `backend/templates/template.yaml`：
  - 所有需要跟随用户语言的输出都通过 `{lang}` 约束；
  - 猜测问题、分析和图表相关 JSON 值不会固定在中文；
  - 不需要的重复语言指令没有重新引入。

### 文档

- 更新所有明确声明支持语言列表的文档；不要让文档继续停留在旧语言集合。
- 检查 `README.md` 和 `docs/README.en.md`：
  - 如果新增语言提供公开文档，则添加对应 localized README；
  - 更新每个 README 顶部的语言切换 badge/link；
  - 不要提交机器翻译后未检查的正式文档。
- 如果 README 的功能列表或部署说明提到界面语言，同步新增语言名称。
- 涉及 agent 指引时，更新：
  - `docs/agents/i18n.md` 的语言列表和新增语言 checklist；
  - `docs/agents/frontend.md` 的 locale 文件列表。
- xpack 功能使用该语言输出用户可见错误或商业界面时，检查独立 xpack 仓库的说明和领域词汇是否需要同步。

## 验证

```bash
cd frontend
npm run build
```

再运行与 supplier、文档或语言配置相关的守卫测试（`backend/tests/`）；如没有对应守卫，至少用脚本验证五个 JSON 的递归键路径一致。