63 lines
3.8 KiB
Markdown
63 lines
3.8 KiB
Markdown
# 控制台 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 build`
|
||
- `scripts/harness/frontend-rules-check.sh`
|
||
- `scripts/harness/docs-consistency-check.sh`
|
||
- `scripts/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`：当前实现上下文。
|