返回文档导航

BeeX 多语言文案闭环

当前实现 · 2026-07-17 · App 内校对、管理服务授权、AI Ops Worker 同步 Git、H5 构建发布

唯一结论

Git 是生产文案的唯一真相源，数据库是翻译操作入口和同步队列的来源，不是 App 的长期动态文案源。

翻译在测试 App 保存文案后，数据立即写入测试管理服务，并自动创建 Git 同步任务。AI Ops Worker 把修改合并回 H5 仓库；下一次 H5 构建从 Git 生成静态 JSON 和离线包。普通用户不在运行时动态拉取翻译后台。

三个角色，各自只做一件事

开发在 H5 代码中新增调用位置和默认文案；运行扫描、校验、导出；合并前消除硬编码。

翻译使用被授权的 BeeX 测试账号，在 App 调试入口进入文案校对模式；点击当前文案、修改、保存。不能创建或修改 Key。

AI Ops Worker拉取最新仓库、按 Key 合并数据库修改、运行检查与导出、提交并推送 Git；失败时保留日志并通知处理。

数据放在哪里

位置	用途	是否生产真相源
`beex-app-h5/i18n/beex-translations.csv`	人工可审阅、可版本管理的完整文案表。	是
`beex-app-h5/public/i18n/beex-translations.json`	由 CSV 导出，进入 H5 构建产物与离线包。	派生产物
`i18n_copy_entries`	记录 App 内保存的文案、编辑人、页面路径、时间和待同步内容。	否
H5 离线包	App 实际运行时加载的版本化文案。	发布快照

飞书不是最终存储；生产 App 也不直接访问飞书或文案数据库。这样即使网络差、管理服务异常，已发布页面仍能正常显示。

完整时序

sequenceDiagram
  participant D as 开发
  participant G as H5 Git 仓库
  participant T as 翻译人员测试 App
  participant A as beex-admin-service
  participant DB as i18n_copy_entries
  participant W as ai-ops-worker
  participant P as H5 发布流水线

  D->>G: 新增 Key、默认文案和 t(key) 调用
  D->>G: i18n:scan / i18n:check / i18n:export
  T->>A: permission(联盟码/授权码)
  A-->>T: canEdit + localeScope
  T->>A: quick-update(copyKey, locale, text, pagePath)
  A->>DB: 保存文案和操作记录
  A->>W: 创建 I18N_SYNC_TO_GIT 任务
  A-->>T: 保存成功 + sync job id
  W->>G: pull 最新 main
  W->>A: 读取待同步文案
  W->>G: 按 Key 合并 CSV、校验、导出 JSON
  W->>G: commit + push
  P->>G: checkout 指定 commit
  P->>P: 构建 H5 和离线包
  P-->>T: 新包经测试/灰度/发布后生效

翻译人员实际操作

管理员在管理后台用翻译人员的联盟码配置 App 内校对权限和可编辑语言。
翻译人员登录测试 App，从调试入口进入“文案校对”。页面保持正常视觉，只给可编辑文案增加轻量标记。
点击某条文案，只显示当前文案和输入框；Key、页面路径等技术信息不让翻译编辑。
点击保存后立即写入 i18n_copy_entries，并返回 Git 同步任务 ID；不经过运营审核，也没有草稿状态。
AI Ops Worker 同步成功后，Git 中出现对应提交。完成一轮校对后统一发布一个 H5 版本。

接口边界

接口	调用方	说明
`GET https://admin-api-id-test.beexofficial.com/api/v1/i18n/editor/permission`	测试 App	按 BeeX 用户、联盟码和授权码判断是否可编辑。文案校对只使用测试管理服务。
`POST /api/v1/i18n/editor/quick-update`	测试 App	保存单条语言文案并自动创建 `I18N_SYNC_TO_GIT` 任务。
`GET /api/v1/admin/i18n/sync-jobs/{jobId}`	管理后台	查询同步状态和失败原因。
`POST /api/v1/admin/i18n/sync-git`	管理后台	必要时人工重试或批量同步，不替代自动任务。

Key 与冲突规则

Key 全局唯一并按页面语义冗余，例如 home.pasteProduct.placeholder；不同位置即使当前中文相同，也使用不同 Key，避免改一处误伤另一处。
翻译只能改文本，不能增删或重命名 Key。新增、重命名、删除 Key 都由开发提交 Git。
AI/工具可提出 Key 建议，但必须先检查 CSV 与代码使用情况；禁止用自动数字后缀掩盖语义冲突。
Worker 每次写入前先拉取最新 main。若同一 Key 在基线之后被开发和翻译同时修改，任务必须失败并提示冲突，不能静默覆盖。
删除 Key 前先扫描全部代码引用；无引用后从代码、CSV 和导出 JSON 同一提交删除。数据库历史操作记录保留用于审计。

语言兜底

语言优先级由国家数据中心决定，而不是固定回退中文。印尼数据中心默认 id，马来数据中心默认马来语；用户显式选择的受支持语言优先。当前 ID 环境顺序：

用户选择 → 系统语言(受支持时) → id

发布与验收

Worker 同步任务成功，Git commit 可追溯到编辑人、Key 和时间。
npm run i18n:check、npm run i18n:export 和 H5 构建全部通过。
H5 包先在 id-test 发布并由翻译复验，再把同一 commit 的产物转入生产灰度。
生产发布后抽查三种语言；发生错误时回滚 H5 包，不直接在线上数据库热改文案。