3.8 KiB
3.8 KiB
控制台 i18n 接入计划
状态：基础设施已落地，大型业务页迁移继续进行 创建日期：2026-06-29 核心目标：把 Docs 已有的中英文文档能力提升为前端统一 i18n 体系，让未登录认证页、Docs UI、控制台外壳、导航、搜索和核心工作台文案共用同一个语言状态。
背景
Docs 站点已经有 zh / en 文档目录、Gatekeeper 权限和 /api/v1/docs/{lang}/{slug} 内容接口，但语言状态只保存在 docs-lang，不影响控制台。控制台页面、搜索索引、toast、dialog、表格和认证页仍以中文硬编码为主，导致用户切到英文文档后，控制台仍是中文。
本计划把前端语言偏好收敛到 planet-locale，默认 zh-CN，支持 en-US。Docs 继续使用后端现有 zh / en 文档接口，通过前端映射与全局 locale 对齐。
设计决策
- 使用
i18next和react-i18next作为统一 i18n 层，避免长期维护自研插值、hook 和资源加载逻辑。 - 前端统一语言枚举为
zh-CN/en-US；Docs 请求继续转换为zh/en，新闻接口继续使用已有zh-CN/en-US口径。 - 语言偏好首版只保存在浏览器
localStorage，不新增后端用户设置字段。 docs-lang保留为兼容读取和写入项，让已访问过 Docs 的浏览器能平滑迁移。- 静态路由、导航、搜索目标和通用组件使用显式翻译 key；大型业务页在迁移期间通过 legacy UI 翻译桥补足常见硬编码文案。
分期
P1：统一语言基础设施
- 在
frontend/src/i18n/下维护 locale 类型、资源、初始化和useLocale()。 - 在
frontend/src/main.tsx里初始化 i18n，并同步document.documentElement.lang。 - 在认证页和控制台侧边栏偏好面板提供语言切换入口。
P2：高复用界面迁移
- 迁移 Docs UI、AdminLayout、route manifest、admin search、Auth、DataTable、Dialog、Toast 和 MarkdownRenderer。
- 搜索索引按当前语言展示，同时保留中英文关键词以免降低可发现性。
- 用户管理页作为独立业务页示范，迁移表头、按钮、toast、校验提示、角色和 Gatekeeper 标签。
当前已完成统一 planet-locale、Docs 兼容映射、认证页和控制台外壳语言入口、共享组件 key 化，以及 legacy UI 翻译桥。后续工作集中在把大型业务页从过渡桥迁移到显式 key。
P3：大型业务页收敛
- 分批把 Dashboard、DataList、Logs 和 PlainResourcePages 的配置块改为显式翻译 key。
- 过渡期保留 legacy UI 翻译桥，只处理 admin/auth 容器里的精确静态文本和属性。
- 业务数据、日志原文、API 字段名、provider id、命令和 Markdown 正文不走 legacy 翻译桥。
P4：移除过渡桥
- 当
rg -n "[\\p{Han}]" frontend/src/admin frontend/src/pages frontend/src/components只剩业务数据示例、中文文档标题或必须保留的中文品牌词时，删除 legacy UI 翻译桥。 - 增加 key 完整性检查，确保
zh-CN和en-US资源结构一致。
验证
cd frontend && bun run buildscripts/harness/frontend-rules-check.shscripts/harness/docs-consistency-check.shscripts/harness/quick-check.sh- 前端 smoke 需要覆盖登录页、Docs、Admin 侧边栏语言切换、侧边栏和搜索结果在中英文下渲染。
相关文件
frontend/src/i18n/：统一 locale、资源和过渡桥。frontend/src/pages/Docs/Docs.tsx：Docs 语言状态改为读取全局 locale。frontend/src/admin/components/layout/AdminLayout.tsx：控制台侧边栏语言切换、导航和搜索文案。frontend/src/admin/search/indexers.ts：Admin 搜索目标本地化。docs/technical/{zh,en}/frontend-admin-frontend-context.md：当前实现上下文。