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 仓库的说明和领域词汇是否需要同步。

验证

cd frontend
npm run build

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