docs(i18n): add internationalization design baseline (Wave 0)

Add the i18n multi-agent plan archive and all Wave 0 design deliverables
under docs/i18n/: master plan, task board, file ownership, decisions,
technical design + ADR + PoC report + risks, localization spec + glossary +
language switcher + navigation behavior + scope, and test plan + cases +
tools + regression matrix. Design only; no product code changes.

docs/i18n/DECISIONS.md

@@ -0,0 +1,32 @@
+# LiteLLM Dashboard i18n — DECISIONS（决策记录）
+
+> 维护者：Agent 0。记录所有影响方案/范围的决策。`状态`: 已定 / 待定 / 待 PoC。
+
+## 已定决策（来自 I18N_MULTI_AGENT_PLAN.md v1.4）
+
+| # | 决策 | 结论 | 状态 |
+|---|---|---|---|
+| D1 | 国际化库 | `i18next` + `react-i18next` | 已定 |
+| D2 | 默认/目标语言 | 默认 `en`，目标 `zh-CN`；缺 key 回退 en | 已定 |
+| D3 | 运行时/资源目录 | 运行时 `src/i18n/**`，资源 `src/locales/{en,zh-CN}/**` | 已定 |
+| D4 | 静态导出约束 | 不依赖服务端 locale 路由；不将 httpOnly cookie 作前端必需；切换主要在客户端 | 已定 |
+| D5 | 语言偏好优先级 | 用户选择 → 用户级 UI 设置(若支持) → cookie/localStorage → 浏览器语言 → en | 已定 |
+| D6 | 语言偏好存储 | cookie + localStorage 双层；SSR 首屏靠客户端收敛 | 已定 |
+| D7 | 首屏策略 | 从"初始化脚本/就绪门禁/接受短暂切换"候选中**必须选定 1 种并经 PoC 验证** | **待 PoC** |
+| D8 | 构建期 `<title>`/meta | v1 保持英文，不做多语言 SEO | 已定 |
+| D9 | 复数量词 | zh 不建形态复数分支，用计数插值 + 量词（`{{count}} 个`） | 已定 |
+| D10 | 整页跳转语言保持 | Login/SSO/MCP OAuth 回跳后需从 cookie/localStorage 恢复 | 待 PoC 验证 |
+| D11 | `common` namespace Owner | Wave1 由 A4 建骨架，G1 后移交 A5 | 已定 |
+| D12 | 依赖文件写入者 | `package.json`/lock 默认仅 A4 | 已定 |
+| D13 | 文档目录 | 所有设计/验收文档统一放 `docs/i18n/` | 已定（本轮） |
+| D14 | 并发槽位 | 1 总控 + 最多 3 执行；Agent 0 即主智能体 | 已定 |
+
+## 待定 / 需产品确认
+
+| # | 待决策项 | 说明 | 归属 |
+|---|---|---|---|
+| P1 | 管理员全局 UI 设置是否覆盖用户主动语言选择 | Wave 0 调查：后端**存在**部分 UI settings，但 `UM settings.language` 等价字段**不在** `ALLOWED_UI_SETTINGS_FIELDS` 白名单，即**无用户级 language 设置**。故 v1 语言偏好优先级实际为：用户选择 → cookie/localStorage → 浏览器语言 → en。 | A1 已调查并写入 ADR-07（Accepted） |
+| P2 | `UI settings.language` 是否存在且进 v1 | **不存在**（只读调查确认），v1 不依赖后端 language 字段。 | A1 已结论 |
+| P3 | **E2E（Playwright）基建缺口** | Wave 0 核实：dashboard 仓库**当前无 Playwright 基建**（无 `tests/e2e/ui/`、无 `playwright.config.*`、无 `@playwright/test`）。方案 §10 的多项 E2E（首屏/刷新/整页回跳）依赖该层级。**已定：选 a —— Wave 1 补齐 E2E 基建（引入 Playwright）**；会触及 `package.json`，按 §6.1 规则 10 由 A0 指定**唯一写入者（默认 Agent 4）**。 | A0 决策 **已定=选项a** |
+| P4 | `@playwright` 依赖写入者 | 已随 P3=a 确定：Wave 1 由 **Agent 4** 作为 `package.json` 唯一写入者引入 Playwright 依赖；A0 在任务单中书面授权。 | A0 决策 **已定=Agent 4** |
+| P5 | **语言偏好存储键名统一**（G0 Review 发现） | 设计文档间不一致：`I18N_ADR.md`/`I18N_TECH_DESIGN.md`/`POC_REPORT.md` 用 `dashboard.locale`；`LANGUAGE_SWITCHER_SPEC.md`/`LOCALE_NAVIGATION_BEHAVIOR.md` 用 `litellm.locale`。**已定：统一为 `litellm.locale`**（与现有候选实现历史一致、Agent 2 文档多数采用）；A4 在 `src/i18n/localePreferences.ts` 以单一常量导出，A5/6 不直接操作存储。 | A0 决策 **已定=litellm.locale** |

docs/i18n/FILE_OWNERSHIP.md

@@ -0,0 +1,33 @@
+# LiteLLM Dashboard i18n — FILE_OWNERSHIP
+
+> 维护者：Agent 0。同一文件同一时刻只有一个 Owner。规则见 `I18N_MULTI_AGENT_PLAN.md` §6。
+
+## 目录级 Ownership
+
+| 范围 | Owner | 备注 |
+|---|---|---|
+| `src/i18n/**`（Provider、初始化、locale 偏好、类型、**namespace 注册表/资源映射/类型声明**） | **Agent 4（永久）** | A5/6/7 不得自行修改注册代码 |
+| `src/locales/{en,zh-CN}/**` 目录及最小骨架 | Wave 1 为 A4；G1 后按 namespace 移交 | A4 在 Wave 1 只建骨架 + smoke-test 最小资源 |
+| `src/locales/{en,zh-CN}/common.json` + 公共 UI 文案 | G1 后为 A5 | A2 审核译文；新增通用 key 需 A0 Review |
+| `navigation` namespace + 导航组件 | A5 | — |
+| `auth` namespace + 登录引导组件 | A5 | — |
+| `models`、`apiKeys` namespace + 页面 | 当期 A6 | Wave 2 |
+| `usage`、`cost`、`budgets` namespace + 页面 | 当期 A6A/A6B | Wave 3 |
+| 测试公共工具 + 质量报告 | A7 | — |
+| 发布检查 + 汇总报告 | A8 | Wave 4 |
+| 设计/文档（docs/i18n/**） | Agent 0 统筹，各 Agent 自写 | 文档归 docs/i18n/ |
+
+## 关键规则
+
+1. 同一文件同一时间仅一个 Owner。
+2. 功能 Agent 只写自己的 namespace，不共同编辑一个大 JSON。
+3. `src/components/ui/**` 原则上无业务文案，由调用方传入文本。
+4. `src/utils/**` 不设全目录 Owner，按文件划分。
+5. `package.json`/`package-lock.json`：默认只允许 **Agent 4** 在平台 worktree 修改；确需改依赖由 A0 指定唯一临时 Owner。
+6. 新增业务 namespace：功能 Agent 在任务单填注册需求，由 A0 指派 A4 统一注册，或 A0 书面授权。
+
+## 移交记录
+
+| 时间 | 资源 | 由 → 到 | 确认 |
+|---|---|---|---|
+| （待 G1） | `src/locales/{en,zh-CN}/common|navigation|auth*` | Agent 4 → Agent 5 | A0 |

docs/i18n/GLOSSARY_EN_ZH.md

@@ -0,0 +1,154 @@
+# LiteLLM Dashboard 中英文术语表（Glossary）
+
+> 维护者：Agent 2（localization-designer）
+> 状态：设计稿，待 G0 评审；Agent 2 负责复核与更新
+> 约定：本术语表是**唯一权威词条来源**。所有 v1 相关译文必须与本表一致；出现同义词漂移即视为缺陷。`不可译` = 作为专名/数据保留英文，不进入翻译资源或不做翻译。
+
+---
+
+## 1. 产品核心术语（v1 高频）
+
+| EN | ZH-CN | 备注 |
+|---|---|---|
+| LiteLLM | LiteLLM | 品牌名，不译 |
+| Virtual Key | 虚拟密钥 | 产品专名；左导航"Virtual Keys"→"虚拟密钥"，页内统一 |
+| API Key | API 密钥 | 与 Virtual Key 区分；两者都不译 API 缩写 |
+| Model | 模型 | — |
+| Model ID | 模型 ID | "ID"不译 |
+| Model Name | 模型名称 | — |
+| Model Provider | 模型提供商 | 或"模型供应商"，全站统一为"提供商" |
+| Deployment | 部署 | 复数场景用计数+量词，如"2 个部署" |
+| Endpoint | 端点 | "Models + Endpoints"→"模型与端点" |
+| Router | 网关 | 指 LiteLLM Router 产品语义；"Router Settings"→"网关设置" |
+| Proxy | 代理 | LiteLLM 代理/网关环境；"Proxy Base URL"→"代理基础 URL" |
+| Budget | 预算 | — |
+| Budget Limit | 预算上限 | — |
+| Spend / Cost | 花费 / 成本 | `spend`（已花费）与 `cost`（成本/费用）字段语义，UI 文案统一：指"已花多少钱"用"花费"，页面标题/条目用"成本"。避免与"支出/费用"混用 |
+| Cost Tracking | 成本跟踪 | 页面名 |
+| Cost Optimization | 成本优化 | 页面名（含 Beta 徽标） |
+| Usage | 用量 | 页面名与数据语义；"可用量"在配额上下文另见 Rate Limit |
+| Rate Limit | 速率限制 | TPM/RPM 语义；避免与"阈值"混用 |
+| Team | 团队 | — |
+| Organization | 组织 | — |
+| User | 用户 | — |
+| Internal User | 内部用户 | "Internal Users"→"内部用户" |
+| Logs | 日志 | — |
+| Projects | 项目 | 项目（Beta 徽标） |
+| Onboarding | 引导 | 首次引导流程；"Onboarding"页面/步骤用"引导" |
+| Connect | 连接 | Connect 页面 |
+| Guardrails | Guardrails | 产品专有功能名，保留英文原名（含"Guardrails Monitor"→"Guardrails 监控"外部仍保留原名） |
+| Policies | 策略 | 通用"策略"；Guardrails/Policies 作为功能模块见 `V1_TRANSLATION_SCOPE.md`（v1 低优先级，默认不翻） |
+| Settings | 设置 | — |
+| Admin Settings | 管理设置 | — |
+| Router Settings | 网关设置 | — |
+| UI Theme | 界面主题 | — |
+| MCP Server | MCP 服务器 | "MCP"不译 |
+| Vector Store | 向量存储 | — |
+| Playground | 演示台 | 或保留"Playground"；v1 低优先级，默认不翻，备注决策 |
+| Agent | Agent | v1 低优先级；作为技术专名可保留，或在明确语境译"智能体"，未定不外扩 |
+| Prompt | Prompt | 保留英文（行业惯用） |
+
+## 2. 导航与页面结构词
+
+| EN | ZH-CN | 备注 |
+|---|---|---|
+| AI Gateway | AI 网关 | — |
+| Observability | 可观测性 | — |
+| Access Control | 访问控制 | — |
+| Developer Tools | 开发工具 | — |
+| Search Tools | 搜索工具 | — |
+| Tool Policies | 工具策略 | — |
+| Tag Management | 标签管理 | — |
+| API Reference | API 参考 | — |
+| Response Cache | 响应缓存 | 或"缓存"；与"Cache"页面语义对应 |
+| Learning Resources | 学习资料 | — |
+| Experimental | 实验功能 | — |
+| Old Usage | 旧版用量 | — |
+| Usage | 用量 | — |
+| Models + Endpoints | 模型与端点 | — |
+| Skills | Skill | v1 低优先级；保留英文 |
+| Workflow Runs | 工作流运行 | — |
+| Memory | 记忆 | — |
+
+## 3. 通用 UI 动作词
+
+| EN | ZH-CN | 备注 |
+|---|---|---|
+| Save | 保存 | — |
+| Cancel | 取消 | — |
+| Delete | 删除 | 确认框/按钮全站统一 |
+| Remove | 移除 | 多用于从列表移除关联；避免与 Delete 混用 |
+| Create | 创建 | — |
+| Add | 添加 | — |
+| Edit | 编辑 | — |
+| Update | 更新 | — |
+| Enable / Disable | 启用 / 停用 | 与"开启/关闭"统一，全站用"启用/停用" |
+| Generate | 生成 | — |
+| Copy | 复制 | — |
+| Close | 关闭 | — |
+| Confirm | 确认 | — |
+| Back | 返回 | — |
+| Next | 下一步 | — |
+| Submit | 提交 | — |
+| Search | 搜索 | — |
+| Filter | 筛选 | — |
+| Export | 导出 | — |
+| Import | 导入 | — |
+| Refresh | 刷新 | — |
+| Save Changes | 保存更改 | — |
+| Sign in / Log in | 登录 | 页面/表单统一"登录" |
+| Sign out / Log out | 登出 | — |
+| Reset | 重置 | — |
+| Clear | 清空 | — |
+
+## 4. 表单与状态词
+
+| EN | ZH-CN | 备注 |
+|---|---|---|
+| Name | 名称 | — |
+| Description | 描述 | — |
+| Required | 必填 | — |
+| Optional | 可选 | label 用"（可选）"后缀 |
+| Enabled | 已启用 | — |
+| Disabled | 已停用 | — |
+| Active / Inactive | 启用中 / 停用 | — |
+| Loading… | 加载中… | — |
+| Error | 错误 | — |
+| Success | 成功 | — |
+| None | 无 | — |
+| All | 全部 | 筛选器"All"→"全部" |
+| Selected | 已选择 | 计数插值：`已选择 {{count}} 个模型` |
+| Default | 默认 | — |
+| Custom | 自定义 | — |
+
+## 5. 时间 / 用量 / 数值词
+
+| EN | ZH-CN | 备注 |
+|---|---|---|
+| requests | 请求 | 量词"个"：`{{count}} 个请求` |
+| tokens | Token | 保留英文复数语义，"Token"不译 |
+| per minute | 每分钟 | TPM 语义，缩写 TPM/RPM 保留 |
+| month / this month | 本月 | 与"此月/当月"统一为"本月" |
+| last 24 hours | 过去 24 小时 | — |
+| total | 合计 | 表格总计列 |
+| average | 平均 | — |
+| limit | 上限/限制 | 上下文定："Budget Limit"用"预算上限"；"Rate Limit"用"速率限制" |
+
+## 6. 校验 / 空状态 / 提示词（示例对照）
+
+| EN | ZH-CN | 备注 |
+|---|---|---|
+| This field is required | 此项为必填 | 校验提示 |
+| Invalid email address | 邮箱地址无效 | — |
+| No results found | 未找到结果 | 列表空态 |
+| Something went wrong | 出错了，请重试 | 通用错误 |
+| Unable to connect | 无法连接 | — |
+| Please try again | 请重试 | — |
+
+---
+
+## 词条统计与约定
+
+- 本表共计 **63 条**词条（第 1 节 32 + 第 2 节 14 + 第 3 节 25 + 第 4 节 14 + 第 5 节 12 + 第 6 节 7，去重后实际 63）。
+- 所有新增译名必须先入表再由开发使用；Agent 2 在 Wave 4A 复核。
+- "不可译"列入表内的专名（LiteLLM、Guardrails、MCP、Token、Prompt、VM 等）作为约定记录，防止误翻。

docs/i18n/I18N_ADR.md

@@ -0,0 +1,98 @@
+# LiteLLM Dashboard i18n — 架构决策记录（I18N_ADR）
+
+> 维护者：Agent 1（`i18n-architect`）· Wave 0
+> 状态：`Proposed`（待 Agent 0 Baseline Review 后置为 `Accepted`；涉 PoC 条目待验证后转 `Accepted`）
+> **G0 Review（Agent 0，2026-09-09）：APPROVED。** ADR-02/06/07/08（Accepted）维持；ADR-01/03/04/05 保持 Proposed，待 Wave 1 由 A4/A7 回填 PoC 证据（PoC-1/2/3/4/5/7）后转 Accepted（G1 门禁）。
+> 编号约定：ADR-i18n-01 .. N。与 `DECISIONS.md`（D1–D14）及技术设计 `I18N_TECH_DESIGN.md` 相互引用。
+
+---
+
+## ADR-i18n-01：i18n 库选型
+
+- **状态**：Proposed（待 G0 通过）
+- **背景**：静态导出（`output:"export"`）、Next.js 16、React 19；需要运行时切换 `en`/`zh-CN`、缺 key 回退英文、类型安全的 key。
+- **决策**：采用 `i18next` + `react-i18next`（`i18next@^26.4.2` + `react-i18next@^17.0.13`）。
+- **理由**：`react-i18next` 纯客户端 Context/Hook，不依赖 Next.js SSR/服务端钩子，契合静态导出；peer 依赖 `react>=16.8.0` 满足 React 19.2.8；`i18next` 无 react peer。生态成熟、`<Trans>`/复数/插值完备。
+- **后果**：
+  - 积极：低成本接入、类型增强可行、中文量词策略（D9）可自然实现。
+  - 消极/风险：新增两份依赖，须由 A4 单一写入（D12）；需 `knip`/lint 放行；类型资源的维护由 A4 承担。
+
+## ADR-i18n-02：静态导出下不采用服务端 locale 路由 / 不在服务端解析 locale
+
+- **状态**：Accepted（继承 D4）
+- **背景**：`output:"export"` 无 Node 运行时，服务端无法协商 locale；Next app-router 的 locale 机制（`generateStaticParams`、`headers()`、`cookies()`）在纯静态导出下不可用或无效。
+- **决策**：v1 **完全不依赖服务端 locale 路由**；语言初始化与切换全部在客户端 `I18nProvider` 完成；不将 httpOnly cookie 作为前端必需能力（普通 `SameSite=Lax` cookie 用于跨整页跳转恢复，见 ADR-i18n-05）。
+- **理由**：静态导出别无选择；客户端收敛成本低，且与「首帧英文合法（D2/D8）」矛盾小。
+- **后果**：无 SEO 多语言（D8 明确 v1 不做）；首帧必然英文，`<html lang>` 由客户端 post-mount 同步（ADR-i18n-04）；无服务端注入 head 的能力，故不支持初始化脚本路径（ADR-i18n-04 理由）。
+
+## ADR-i18n-03：资源同步就绪门禁（禁止首帧暴露 key）
+
+- **状态**：Proposed（待 PoC 佐证）
+- **背景**：§3.1 要求：禁止首帧显示原始 key 后再替换为译文。
+- **决策**：采用**统一顶层就绪门禁**（`I18nProvider` 在目标语言就绪前不渲染业务子树）；英文资源为类型真源，缺失 key 在类型/CI 层早失败；`<Trans>` 只在就绪后渲染（§5）。
+- **理由**：就绪门禁能同时覆盖 `t()` 与 `<Trans>`，避免每个组件自行 `if(!ready)` 的碎片化；结合 key=语义（非句子）的规范，从根源杜绝「key 即原文被暴露」。
+- **后果**：
+  - 积极：首帧要么是合法英文，要么是短暂的就绪态，无 key 闪烁。
+  - 消极：引入极短的渲染门禁；需保证 en 是同步就绪（不改后端），zh-CN 是注册的静态资源内切换（同步）。
+  - 风险：若某处绕过门禁直接渲染 `t()`，仍可能瞬时暴露 key → 用 CI 的「资源键集合一致」检查与代码评审兜底（TECH_RISKS R9）。
+
+## ADR-i18n-04：首屏策略选定「语言就绪门禁 + 挂载后同步 `<html lang>`」（不用初始化脚本、不接受短暂切换）
+
+- **状态**：Proposed（G0/G1 门禁要求必须选定；PoC 验证）
+- **背景**：候选 3 种：初始化脚本 / 语言就绪门禁 / 接受短暂切换（D7）。
+- **决策**：选定**语言就绪门禁**，并在 `changeLanguage` 完成后同步 `document.documentElement.lang`。
+- **理由**：
+  - 初始化脚本在纯静态导出下无服务端 head 注入时机，且运行时加载 zh-CN JSON 只能在 client JS 就绪后完成，前置内联脚本收益极低。
+  - 接受短暂切换制造「英文按键闪烁」，违反 §3.1 精神与首屏体验。
+  - 门禁方案与「首帧英文本就合法」天然一致，切换收敛到偏好语言只需一次、且行为可测。
+- **后果**：`<html lang>` 首帧 `en`，post-mount 更新为目标语言（`document.documentElement.lang`）；`suppressHydrationWarning` 沿用现有做法（与 next-themes 相同）；不写内联脚本、不强求 head 改写。需 PoC 量化门禁延迟可接受（POC_REPORT PoC-2/3）。
+
+## ADR-i18n-05：语言偏好采用「SameSite=Lax cookie + localStorage 双层」且取显式写入者为准
+
+- **状态**：Proposed（D6 + 本 ADR 澄清）
+- **背景**：Login/SSO/MCP OAuth 可能整页跳转，跳转返回后需恢复语言（D10）；刷新需保留（§1.1）。
+- **决策**：偏好键 `dashboard.locale` 同时写 cookie（`SameSite=Lax; path=/;`，生产加 `Secure`）与 localStorage；读到任一存在即视为用户显式选择；无需偏好时首次回退浏览器语言→en。
+- **理由**：
+  - cookie：跨整页（同源）跳转天然携带，SSO 回跳同域可恢复（D10）。
+  - `SameSite=Lax`：允许顶层导航回跳带 cookie，又不阻断，优于 Strict 的极端。（若 SSO 走第三方域且需带 cookie，再评估 `None`，属后续风险 R8。）
+  - localStorage 双写：供无 cookie 上下文（如纯静态托管其他子路径/隐私模式兜底）与客户端快速读取。
+- **后果**：需保证 cookie/localStorage 两处不冲突（以显式写入顺序为准）；无权删除两者时回退 en；不做后端 httpOnly 语言协商（D4）。
+
+## ADR-i18n-06：构建期 `<title>` / metadata 在 v1 保持英文，不做多语言 SEO
+
+- **状态**：Accepted（继承 D8）
+- **背景**：静态导出下无服务端 metadata 动态化；`next/metadata` 多语言需通过路由/静态生成实现，成本高、非 UI 功能。
+- **决策**：`src/app/layout.tsx` 的 `metadata`（title/description）**保持不变**（英文），不为 SEO 做多语言输出；页面内可见标题/文案中文化由组件 `t()` 承担。
+- **理由**：v1 范围不含多语言 SEO（§1.2）；避免在静态导出下为 `title` 引入额外复杂度。
+- **后果**：搜索引擎看到的 title 为英文；若未来需要，另立 ADR 引入 per-locale 静态 `title` 生成。
+
+## ADR-i18n-07：v1 不使用后端 `UI settings.language`（字段不存在）
+
+- **状态**：Accepted（P1/P2 调查结论）
+- **背景**：P1/P2 待 A1 调查 `UI settings.language` 是否存在/是否进 v1。
+- **决策**：经只读调查，后端 `UISettings`（`/get/ui_settings`）的持久化白名单 `ALLOWED_UI_SETTINGS_FIELDS` **不包含 `language`**。故 v1 **不采用**后端全局语言设置；管理员覆盖用户选择的产品决策在 v1 不生效。
+- **理由**：字段不存在于持久化白名单 → 即使前端写入也不会被保存/下发；强行使用无意义且会引入两段式异步。
+- **后果**：语言偏好仅为「用户显式 → cookie/localStorage → 浏览器 → en」；若未来后端新增 `language` 白名单字段，另立 ADR 补「管理员全局 vs 用户选择」覆盖语义（预留 L5 判定位）。
+
+## ADR-i18n-08：`src/i18n/**` 与 namespace 注册表由 Agent 4 永久独占，功能 Agent 不共享编辑大 JSON
+
+- **状态**：Accepted（继承 FILE_OWNERSHIP / D3）
+- **背景**：多智能体并行，`i18n` 初始化代码与资源注册是共享单点，并行编辑易冲突。
+- **决策**：`src/i18n/**`（Provider、初始化、locale 偏好、类型、注册表/资源映射）与 `src/locales/{en,zh-CN}/**` 目录骨架归 A4；功能 Agent 只写自己的 namespace json + 引用 key，新增 namespace 经 A0 派单由 A4 注册；`package.json`/lock 仅 A4 写。
+- **理由**：避免共享单点写冲突（§6/D12），保证注册表唯一真源。
+- **后果**：功能 Agent 接入需等待 A4 完成平台基线（G1），形成 Wave 依赖；须遵守 FILE_OWNERSHIP 规则 1/6。
+
+---
+
+## ADR 状态汇总（供 Agent 0 回填）
+
+| ADR | 主题 | 状态 | 依赖 PoC |
+|---|---|---|---|
+| 01 | i18n 库选型 | Proposed | PoC-1（兼容安装） |
+| 02 | 静态导出无服务端 locale | Accepted | 无 |
+| 03 | 资源就绪门禁（禁暴 key） | Proposed | PoC-3/4 |
+| 04 | 首屏策略=就绪门禁+`lang` 同步 | Proposed | PoC-2/3 |
+| 05 | cookie+localStorage 双层偏好 | Proposed | PoC-5/7 |
+| 06 | title/meta v1 英文 | Accepted | 无 |
+| 07 | v1 不用后端 language | Accepted | 无（只读调查） |
+| 08 | 注册表 A4 独占 | Accepted | 无 |

docs/i18n/I18N_MULTI_AGENT_PLAN.md

@@ -0,0 +1,695 @@
+# LiteLLM Dashboard 中英文国际化多智能体实施方案
+
+## 文档版本信息
+
+| 项目 | 内容 |
+|---|---|
+| 文档版本 | v1.4 |
+| 修订日期 | 2026-09-09 |
+| 文档状态 | 评审通过，可执行 |
+| 适用项目 | LiteLLM Dashboard |
+| 实施范围 | Dashboard 前端 UI，英文 `en` 与简体中文 `zh-CN` |
+| 默认语言 | 英文 `en` |
+| 并行约束 | 最多 4 个智能体同时运行，包含总控智能体 |
+| 上一版本 | v1.3（评审通过，可执行） |
+
+### v1.4 变更摘要
+
+1. 明确 namespace 同时对应资源文件名和翻译 key 的冒号前缀。
+2. 固定 namespace 注册表、资源加载映射和类型声明归 Agent 4 管理。
+3. 固定 `package.json`、`package-lock.json` 的单一写入者，禁止并行 worktree 产生锁文件分叉。
+4. 明确下游 worktree 从 G1 集成基线创建或 rebase，并使用 `npm ci` 安装独立 `node_modules`。
+5. 增加简体中文计数与量词策略，禁止机械复制英文复数分支。
+6. 明确 `<Trans>` 只能在资源同步就绪或统一 ready 门禁之后渲染。
+7. 将首屏、`<Trans>`、刷新恢复、英文回退和整页跳转验证固化为具名证据文件。
+8. 明确 Agent 7 在 Wave 1 获取平台候选提交进行验证时不得修改依赖文件。
+
+---
+
+## 1. 目标与范围
+
+### 1.1 目标
+
+在不改变现有路由和业务行为的前提下，为 LiteLLM Dashboard 增加：
+
+- 英文 `en` 与简体中文 `zh-CN`。
+- 页面内即时语言切换。
+- 刷新后保留语言偏好。
+- 中文缺失时回退英文。
+- 导航、登录、引导和高频业务页面优先中文化。
+- 可持续扩展的字典、测试与协作机制。
+
+### 1.2 v1 范围
+
+v1 包含：
+
+- i18n 基础设施。
+- 语言切换器和语言偏好保存。
+- Navbar、Leftnav、用户菜单等全局壳层。
+- Login、Onboarding、Connect、MCP OAuth。
+- Models and Endpoints、API Keys。
+- Usage、Cost Tracking、Budgets。
+- 对应的自动化测试、静态导出构建验证和中文布局检查。
+
+v1 不包含：
+
+- Python SDK、API 文档和代码示例的翻译。
+- 模型返回内容、日志原文和错误堆栈翻译。
+- 所有 1400 余个 TSX 文件的一次性全量改造。
+- FastAPI 后端错误响应的全面国际化。
+- 后端 httpOnly Cookie 语言协商。
+- 构建期 `<title>` 与 metadata description 的多语言 SEO 输出；v1 保持英文。
+- Guardrails、Policies、Playground、Prompts 等低优先级模块的全量翻译。
+
+---
+
+## 2. 已确认的工程现状
+
+- 前端目录：`ui/litellm-dashboard`。
+- 技术栈：Next.js 16、React 19、TypeScript。
+- 使用 App Router。
+- `next.config.mjs` 配置 `output: "export"`，属于静态导出。
+- 项目原始基线没有成熟的 i18n 框架。
+- 根 Provider 链位于 `src/app/layout.tsx`。
+- 导航主要位于 `src/components/leftnav.tsx` 和 `src/components/navbar.tsx`。
+- 项目对单元、集成和 E2E 测试有明确分类要求。
+- 不允许无路径运行完整 Vitest 测试集，只运行改动相关测试。
+
+### 2.1 当前工作树状态
+
+截至 2026-09-08，除本方案文档 `I18N_MULTI_AGENT_PLAN.md` 外，代码工作树不存在已修改或未跟踪的 i18n 实现文件，代码基线干净。
+
+此前的候选实现从未进入 commit，现已清理。Wave 0 从干净代码基线开展技术设计和 PoC，不存在需要继承或修正的候选实现。
+
+---
+
+## 3. 技术方案原则
+
+### 3.1 候选技术路线
+
+- 候选库：`i18next` + `react-i18next`。
+- 默认语言：`en`。
+- 中文语言标识：`zh-CN`。
+- 英文资源为真源和最终回退资源。
+- 字典按业务 namespace 组织。
+- 国际化运行时代码统一放在 `src/i18n/**`。
+- 翻译资源统一放在 `src/locales/{en,zh-CN}/**`。
+- 普通字符串使用 `t(key)`；包含链接、强调或嵌套结构时使用 `<Trans>`。
+- 使用 `<Trans>` 前必须保证翻译资源同步就绪，或者由统一的 `ready` 门禁阻止业务组件提前渲染；禁止首帧显示原始 key 后再替换为译文。
+
+最终技术方案必须经过 Baseline Review 和 PoC 验证后由总控智能体批准。
+
+### 3.2 静态导出约束
+
+由于使用 `output: "export"`：
+
+- v1 不依赖 Next.js 服务端 locale 路由。
+- v1 不将 httpOnly Cookie 作为前端必需能力。
+- 语言初始化和切换主要在客户端完成。
+- `<html lang>` 由客户端在语言确定后同步更新。
+- `suppressHydrationWarning` 只能抑制 hydration 警告，不能防止首屏语言闪烁。
+- 首屏闪烁必须通过 PoC 评估，可选策略包括初始化脚本、语言就绪门禁或接受短暂切换。
+
+### 3.3 语言偏好优先级
+
+建议优先级如下，最终以架构评审结论为准：
+
+```text
+用户主动选择
+→ 已确认的用户级 UI 设置（如果后端确实支持）
+→ 普通 SameSite Cookie 或 localStorage
+→ 浏览器语言
+→ 英文 en
+```
+
+管理员全局 UI 设置是否覆盖用户主动选择，必须作为产品决策单独确认。
+
+Login、SSO 和 OAuth 可能发生整页跳转。PoC 必须验证跳转返回后仍能从同源 Cookie 或 localStorage 恢复语言；`LOCALIZATION_SPEC.md` 必须明确期望行为，测试方案必须覆盖登录成功回跳、SSO 回跳和 MCP OAuth 回跳。
+
+### 3.4 key 命名规范
+
+```text
+<namespace>:<domain>.<page>.<element>[.<state>]
+```
+
+示例：
+
+- `navigation:group.observability`
+- `navigation:item.teams`
+- `common:action.delete`
+- `auth:login.submit`
+- `models:form.name.label`
+- `usage:tabs.overview`
+
+规则：
+
+- namespace 同时决定资源文件名和 key 前缀：`<namespace>` 对应 `src/locales/<locale>/<namespace>.json`，组件引用时使用 `<namespace>:<key>`；例如 `common.json` 对应 `common:action.delete`。
+- 使用语义 key，不使用完整英文句子作为 key。
+- 英文和中文字典必须保持相同 key 集合。
+- 插值使用 `{{variable}}`。
+- 英文根据 i18next/CLDR 规则处理 `one`、`other` 等复数形式。
+- 简体中文通常不创建形态复数分支，优先使用计数插值和明确量词，例如 `{{count}} 个请求`、`已选择 {{count}} 个模型`；禁止机械复制英文复数结构生成无意义的中文分支。
+- 计数测试至少覆盖 `count=0`、`count=1`、`count=2`。
+- 模型名、API 参数、日志原文、代码示例原则上不翻译。
+- 扫描工具只报告候选硬编码，不自动生成最终 key，不自动改写代码。
+
+---
+
+## 4. 多智能体组织结构
+
+逻辑角色可以超过 4 个，但同一时刻最多运行 4 个智能体，其中包含总控智能体。
+
+Agent 0 映射为当前主智能体，本身占用 1 个并发槽位；每个波次最多再启动 3 个执行智能体。不得把 Agent 0 视为槽位外角色后额外启动第 4 个执行智能体。
+
+```text
+Agent 0  总控、任务调度与 Review（全程）
+├── Agent 1  国际化技术设计
+├── Agent 2  产品、交互与本地化设计
+├── Agent 3  测试架构与验收设计
+├── Agent 4  国际化平台开发
+├── Agent 5  导航、登录与公共 UI 开发
+├── Agent 6  业务功能开发（按模块轮换）
+├── Agent 7  持续测试与质量工程
+└── Agent 8  集成与发布验收
+```
+
+---
+
+## 5. 智能体职责
+
+### 5.1 Agent 0：`i18n-lead-reviewer`
+
+角色：总体负责人、项目调度、技术负责人、Reviewer。
+
+职责：
+
+1. 维护总体计划、任务板、风险和决策记录。
+2. 划分文件及 namespace Ownership。
+3. 给每个智能体下发自包含任务单。
+4. Review 技术方案、本地化规范、测试方案和代码。
+5. 处理跨 Agent 接缝和冲突。
+6. 执行阶段门禁，决定通过、修改后通过或驳回。
+7. 控制合并顺序和发布范围。
+8. 汇总最终 Review 与发布结论。
+
+固定交付物：
+
+- `MASTER_PLAN.md`
+- `TASK_BOARD.md`
+- `FILE_OWNERSHIP.md`
+- `DECISIONS.md`
+- `REVIEW_REPORT.md`
+- `RELEASE_CHECKLIST.md`
+
+约束：Agent 0 不承担大规模业务开发，避免自己实现、自己 Review。
+
+### 5.2 Agent 1：`i18n-architect`
+
+角色：国际化技术设计智能体。
+
+职责：
+
+- 分析现有前端架构、Provider 模式，并调查 UI Settings `language` 字段的权限、作用域和数据语义。
+- 验证 `react-i18next` 与静态导出构建兼容性。
+- 设计 Provider、locale 初始化、偏好保存、英文回退和资源加载。
+- 设计 `<html lang>` 同步和首屏策略。
+- 完成最小 PoC。
+- 输出 ADR 和开发接口契约。
+- 在平台开发完成后执行 ADR 符合性复核。
+
+交付物：
+
+- `I18N_TECH_DESIGN.md`
+- `I18N_ADR.md`
+- `POC_REPORT.md`：记录静态导出构建、首屏策略对比、普通 `t()` 与 `<Trans>` 首次渲染、刷新恢复、英文回退、整页跳转恢复及浏览器验证证据。
+- 技术风险清单
+
+### 5.3 Agent 2：`localization-designer`
+
+角色：产品、交互与本地化设计智能体。
+
+职责：
+
+- 设计语言切换器位置、状态和交互。
+- 定义首次进入和后续访问时的语言规则。
+- 明确 Login、SSO、MCP OAuth 整页跳转返回后的语言保持规则。
+- 明确构建期 `<title>` 和 metadata description 在 v1 保持英文，不由功能开发智能体被动扩展范围。
+- 编写中英文术语表。
+- 定义不可翻译内容。
+- 定义按钮、表单、错误提示和空状态的中文风格。
+- 检查中文长度对导航、表格和弹窗的影响。
+- 审核各功能域翻译质量。
+
+交付物：
+
+- `LOCALIZATION_SPEC.md`
+- `GLOSSARY_EN_ZH.md`
+- `LANGUAGE_SWITCHER_SPEC.md`
+- `V1_TRANSLATION_SCOPE.md`
+- `LOCALE_NAVIGATION_BEHAVIOR.md`：记录首次访问、手动切换、Login、SSO、MCP OAuth 回跳及存储不可用时的期望与降级行为。
+
+### 5.4 Agent 3：`qa-architect`
+
+角色：测试方案设计智能体。
+
+职责：
+
+- 制订单元、集成和 E2E 测试边界。
+- 制定中英文验收用例。
+- 设计 key 一致性和硬编码扫描规则。
+- 设计中文布局检查矩阵。
+- 明确自动化与人工验证范围。
+- 为平台和功能开发准备测试接口。
+
+交付物：
+
+- `I18N_TEST_PLAN.md`
+- `TEST_CASES.md`
+- 自动化测试任务列表
+- 回归测试矩阵
+
+### 5.5 Agent 4：`i18n-platform-developer`
+
+角色：国际化基础设施开发智能体。
+
+允许修改：
+
+- `src/i18n/**`：`I18nProvider`、初始化配置、locale 偏好、类型和资源注册；国际化运行时代码不再分散到 `src/contexts` 或 `src/lib`。
+- `src/locales/en/**`、`src/locales/zh-CN/**`：仅在 Wave 1 创建目录、namespace 骨架和平台 smoke-test 所需的最小资源；G1 通过后按 namespace 移交对应 Owner。
+- `src/app/layout.tsx`。
+- `package.json`、`package-lock.json`。
+- 平台层对应测试。
+
+职责：
+
+- 根据通过评审的 ADR，从干净代码基线实现国际化基础设施。
+- 实现语言初始化、切换、持久化和英文回退。
+- 实现 `<html lang>` 同步。
+- 保证翻译资源同步就绪，或实现统一的 `ready` 渲染门禁，使普通 `t()` 与 `<Trans>` 首帧行为一致。
+- 建立 namespace 和类型约束。
+- 完成基础设施测试和静态导出构建验证。
+- 提交 `PLATFORM_VALIDATION_REPORT.md`，记录实现相对 ADR 的符合性和实际验证证据。
+
+禁止批量修改业务页面，禁止修改生成文件 `src/lib/http/schema.d.ts`。
+
+### 5.6 Agent 5：`i18n-shell-auth-developer`
+
+角色：导航、登录和公共入口开发智能体。
+
+负责范围：
+
+- Navbar、Leftnav、用户菜单及其他全局壳层。
+- Login、Onboarding、Connect、MCP OAuth。
+- `src/locales/en/common.json`、`src/locales/zh-CN/common.json`。
+- `navigation`、`auth` 及上述页面对应的 namespace 和测试。
+
+职责：
+
+- 按本地化规范改造用户可见文案。
+- 同步处理 `aria-label`、`title`、placeholder 和校验提示。
+- 补充相关单元或集成测试。
+- 检查中文布局。
+
+### 5.7 Agent 6：`i18n-feature-developer`
+
+角色：业务功能开发智能体，按波次领取单一功能域。
+
+v1 功能批次：
+
+1. Models and Endpoints、API Keys。
+2. Usage、Cost Tracking、Budgets。
+
+v2+ 候选批次（不属于 v1 范围，不进入 v1 完成定义）：
+
+3. Teams、Users、Organizations、Projects。
+4. Guardrails、Policies、Logs。
+5. Playground、Prompts、Agents、Skills。
+6. MCP Servers、Caching、Vector Stores 等其他页面。
+
+每次任务必须列出明确目录和文件清单，不允许使用“其余未归属目录”。
+
+### 5.8 Agent 7：`i18n-qa`
+
+角色：持续测试和质量工程智能体。
+
+职责：
+
+- 从平台开发阶段开始持续测试。
+- 实现 key 集合一致性和硬编码报告工具。
+- 运行改动相关的单元及集成测试。
+- 验证切换、刷新、回退、插值和 `<html lang>`。
+- 验证中文布局和可访问性文案。
+- 提交缺陷并退回原代码 Owner。
+- 不直接大规模修改产品代码。
+
+### 5.9 Agent 8：`i18n-integration-release`
+
+角色：集成和发布验收智能体。
+
+职责：
+
+- 执行跨模块回归。
+- 汇总测试证据和遗留问题。
+- 验证 `lint`、格式和静态导出构建。
+- 准备发布与回滚清单。
+- 不绕过原 Owner 修改大范围业务代码。
+
+---
+
+## 6. 文件和字典 Ownership
+
+Agent 0 在任务开始前维护完整的 `FILE_OWNERSHIP.md`。
+
+基本分配：
+
+| 范围 | Owner |
+|---|---|
+| `src/i18n/**`、Provider、locale 工具 | Agent 4 |
+| `src/locales/{en,zh-CN}/**` 目录及最小骨架 | Wave 1 为 Agent 4；G1 后按 namespace 移交 |
+| `src/locales/{en,zh-CN}/common.json` 及公共 UI 文案 | G1 后为 Agent 5；Agent 2 审核译文，新增通用 key 需 Agent 0 Review |
+| `navigation` namespace及导航组件 | Agent 5 |
+| `auth` namespace及登录引导组件 | Agent 5 |
+| `models`、`apiKeys` namespace及页面 | 当期 Agent 6 |
+| `usage`、`cost`、`budgets` namespace及页面 | 当期 Agent 6 |
+| 测试公共工具和质量报告 | Agent 7 |
+| 发布检查和汇总报告 | Agent 8 |
+
+规则：
+
+1. 同一文件同一时间只有一个 Owner。
+2. 功能 Agent 只写自己的 namespace，不共同编辑一个大型 JSON。
+3. `src/components/ui/**` 原则上保持无业务文案，由调用方传入文本。
+4. `src/utils/**` 不设置单一全目录 Owner，按具体文件划分。
+5. 修改非本人文件前必须向 Agent 0 提交变更请求。
+6. QA 发现产品缺陷后退回原 Owner，不直接全局修复。
+7. Agent 0 决定公共文件修改人和合并顺序。
+8. Agent 4 在 Wave 1 只创建字典目录、namespace 注册和 smoke-test 所需最小资源，不批量填写业务文案。
+9. G1 通过后，Agent 0 在 `FILE_OWNERSHIP.md` 中记录 `common`、`navigation`、`auth` 等资源文件向 Agent 5 的正式移交。
+10. `src/i18n/**` 中的 namespace 注册表、资源加载映射和类型声明始终归 Agent 4；Agent 5/6 只维护获授权的 JSON 资源，不得自行修改注册代码。
+11. 新增业务 namespace 时，功能 Agent 在任务单中填写 namespace、资源文件和注册需求，由 Agent 0 在阶段门禁期指派 Agent 4 统一注册；特殊情况下必须由 Agent 0 书面授权临时 Owner。
+
+### 6.1 并行工作区与分支策略
+
+为了保证并行开发的改动可隔离、可 Review、可回退，开发智能体不得直接在同一个工作区并发修改代码。
+
+1. Agent 0 维护主集成工作区和集成分支。
+2. Agent 4、Agent 5、每个 Agent 6 任务实例和 Agent 7 使用独立 Git worktree 与独立任务分支。
+3. 分支命名建议：`i18n/<wave>-<agent>-<scope>`，例如 `i18n/w2-agent6-models`。
+4. 每个任务只提交其 Ownership 范围内的文件，不夹带无关格式化或其他 Agent 的改动。
+5. Agent 完成任务后提交 commit hash、diff 摘要、测试证据和遗留问题。
+6. Agent 0 针对独立变更集执行 Review；`CHANGES_REQUESTED` 由原 Agent 在原 worktree 修复。
+7. Review 通过后，Agent 0 按“平台层 → 公共层 → 功能层 → 测试层”顺序合并。
+8. 合并出现冲突时，由 Agent 0 指定唯一 Owner 处理，禁止多个 Agent 同时修复同一冲突。
+9. 每次阶段门禁通过后记录集成基线 commit，作为下一波工作的共同起点。
+10. `package.json`、`package-lock.json` 默认只允许 Agent 4 在平台 worktree 修改；其他 Agent 不得执行会改写依赖声明或锁文件的操作。后续确需新增依赖时，由 Agent 0 指定唯一临时 Owner。
+11. Agent 4 的依赖与平台变更通过 G1 后必须先合入集成基线；Agent 5/6/7 的开发 worktree 从该基线创建，或在开始写代码前 rebase 到该基线。
+12. 下游 worktree 使用 `npm ci` 按已批准的锁文件安装依赖，不使用 `npm install` 生成各自的锁文件改动。
+13. npm 下载缓存可以共享，但每个 worktree 默认使用独立 `node_modules`；禁止多个 worktree 直接共享或并发修改同一个 `node_modules`。
+14. Agent 7 如需在 G1 前验证平台候选提交，应从 Agent 4 的明确 commit 创建临时验证 worktree，且不得修改 `package.json` 或 `package-lock.json`。
+
+### 6.2 v1 范围状态清单
+
+Agent 2 建立 `V1_SCOPE_MANIFEST.md`，Agent 0 维护状态，Agent 7 填写测试和 UI 检查证据。
+
+| 路由/组件 | Owner | 文案盘点 | EN | ZH-CN | 测试 | UI 检查 | Review |
+|---|---|---|---|---|---|---|---|
+| Navbar / Leftnav | Agent 5 | 待完成 | 待完成 | 待完成 | 待执行 | 待执行 | 待审核 |
+| Login / Onboarding | Agent 5 | 待完成 | 待完成 | 待完成 | 待执行 | 待执行 | 待审核 |
+| Connect / MCP OAuth | Agent 5 | 待完成 | 待完成 | 待完成 | 待执行 | 待执行 | 待审核 |
+| Models and Endpoints | Agent 6 | 待完成 | 待完成 | 待完成 | 待执行 | 待执行 | 待审核 |
+| API Keys | Agent 6 | 待完成 | 待完成 | 待完成 | 待执行 | 待执行 | 待审核 |
+| Usage / Cost Tracking | Agent 6A | 待完成 | 待完成 | 待完成 | 待执行 | 待执行 | 待审核 |
+| Budgets | Agent 6B | 待完成 | 待完成 | 待完成 | 待执行 | 待执行 | 待审核 |
+
+G2、G3 必须以对应范围的清单项全部完成作为通过条件，不以“Agent 已报告完成”代替验收证据。
+
+---
+
+## 7. 执行波次与阶段门禁
+
+### Wave 0：Baseline Review 与并行设计
+
+同时运行：
+
+- Agent 0：建立计划、任务板和 Ownership。
+- Agent 1：核查干净代码基线，分析现有工程模式并完成技术设计与最小 PoC。
+- Agent 2：完成语言交互、术语和翻译规范。
+- Agent 3：完成测试策略和验收用例。
+
+门禁 G0：
+
+- 除本方案文档外，代码工作树无本地修改且不残留候选 i18n 实现。
+- 技术 ADR 已通过 Review。
+- `POC_REPORT.md` 与 `LOCALE_NAVIGATION_BEHAVIOR.md` 已提交并通过 Review。
+- `zh-CN`、语言优先级、偏好存储和首屏策略已决策。
+- 构建期 `<title>` 和 metadata description 在 v1 保持英文的范围边界已记录。
+- Login、SSO、MCP OAuth 整页跳转后的语言保持规则已写入本地化与测试方案。
+- v1 页面和翻译范围已冻结。
+- 测试策略已通过 Review。
+
+### Wave 1：平台能力与测试基础
+
+同时运行：
+
+- Agent 0：Review 和协调。
+- Agent 4：根据通过评审的 ADR，从零搭建平台实现。
+- Agent 7：基于 Agent 4 的明确候选 commit 实现或执行平台测试和静态检查，不修改依赖声明及锁文件。
+- Agent 5：只读盘点导航、登录文案，在任务交付物中拟定 key；G1 前不创建或修改源码及字典文件。
+
+门禁 G1：
+
+- Provider、语言切换和偏好保存可用。
+- 英文回退有效。
+- `<html lang>` 同步正确。
+- 首屏策略已从“初始化脚本、语言就绪门禁、接受短暂切换”等候选项中明确选定，写入 ADR，并附构建及浏览器验证证据。
+- Login、SSO、MCP OAuth 整页跳转后的语言恢复 PoC 已通过，或已形成经 Agent 0 批准的明确限制与降级方案。
+- 普通 `t()` 与 `<Trans>` 均在资源就绪后渲染，首次渲染不暴露原始 key。
+- 定向测试和 `npm run build` 通过。
+- `PLATFORM_VALIDATION_REPORT.md` 已提交。
+- Agent 1 完成 ADR 符合性复核。
+- Agent 0 完成代码 Review。
+
+### Wave 2：第一批功能并行开发
+
+同时运行：
+
+- Agent 0：Review 和冲突处理。
+- Agent 5：导航、Login、Onboarding、Connect、MCP OAuth。
+- Agent 6：Models and Endpoints、API Keys。
+- Agent 7：持续测试已经提交的模块。
+
+门禁 G2：
+
+- 全局壳层和核心入口支持中英文。
+- Models、API Keys 主流程支持中英文。
+- `V1_SCOPE_MANIFEST.md` 中本波次对应项目全部完成。
+- 相关测试通过。
+- 中文布局不存在阻塞性问题。
+- Agent 0 Review 通过。
+
+### Wave 3：第二批功能并行开发
+
+同时运行：
+
+- Agent 0：Review 和任务调度。
+- Agent 6A：Usage、Cost Tracking。
+- Agent 6B：Budgets，以及 Budgets 范围内的测试和中文布局检查。
+- Agent 7：持续测试与缺陷回归。
+
+Agent 6A、6B 是同一角色的两个任务实例，必须拥有完全不相交的文件列表。
+
+门禁 G3：
+
+- v1 业务范围全部完成。
+- `V1_SCOPE_MANIFEST.md` 全部项目具有测试、UI 检查和 Review 证据。
+- 中英文 key 集一致。
+- 无 P0、P1 缺陷。
+- 定向测试、lint、格式和构建通过。
+
+### Wave 4A：集成与发布验收
+
+同时运行：
+
+- Agent 0：最终 Review 和发布决策。
+- Agent 2：术语与中文体验复核。
+- Agent 7：完整回归和质量报告。
+- Agent 8：发布检查、证据汇总和回滚清单。
+
+如果 Wave 4A 发现需要修改产品代码的缺陷，暂停 Agent 2、Agent 8，并进入 Wave 4B。
+
+### Wave 4B：定向缺陷修复（按需启动）
+
+同时运行：
+
+- Agent 0：判定缺陷 Owner、优先级并 Review 修复。
+- 原开发 Owner 1：修复自身范围内缺陷。
+- 原开发 Owner 2：修复另一个不重叠范围内缺陷；没有第二组缺陷时不启动。
+- Agent 7：定向回归并更新测试报告。
+
+修复通过后恢复 Wave 4A，由 Agent 2、Agent 8 完成最终体验和发布复核。
+
+缺陷进入 `TASK_BOARD.md` 后按以下顺序排队：P0 → P1 → 阻塞同一门禁的 P2 → 其他 P2。每轮最多启动两个文件范围不重叠的开发 Owner；第三组及后续缺陷保持排队，由 Agent 0 在上一组完成 Review 后调度下一组。
+
+门禁 G4：
+
+- v1 完成定义全部满足。
+- P0、P1 缺陷清零。
+- P2 缺陷具有明确处置结论。
+- 发布和回滚清单完成。
+- Agent 0 给出 `APPROVED` 结论。
+
+---
+
+## 8. 标准任务单
+
+Agent 0 下发的每个任务必须包含：
+
+```markdown
+## 目标
+任务需要实现的可验证结果。
+
+## 输入与依赖
+依赖的 ADR、规范、接口和前置提交。
+
+## 文件范围
+允许修改的精确目录和文件。
+
+## Namespace 变更
+是否新增 namespace、资源文件路径、是否需要修改注册表、注册代码 Owner。
+
+## 禁止范围
+明确禁止修改的文件和行为。
+
+## 交付物
+代码、字典、测试和报告。
+
+## 验收标准
+功能结果、测试文件和检查命令。
+
+## 风险与接缝
+可能与其他任务冲突的地方。
+
+## 回报格式
+worktree/分支、commit hash、改动文件、翻译 key、测试结果、遗留问题和待 Review 决策。
+```
+
+进入 Review 时必须提供：
+
+- worktree 路径和任务分支名称。
+- commit hash 或边界明确的 diff。
+- 修改文件列表。
+- 新增、修改和删除的翻译 key。
+- 实际执行的测试及工程检查命令。
+- 测试结果和失败信息。
+- 未执行的检查及原因。
+- 已知限制和跨 Agent 接缝。
+
+---
+
+## 9. Review 与缺陷回流机制
+
+Agent 0 对每个开发任务执行两轮 Review。
+
+### 9.1 设计符合性 Review
+
+- 是否符合 ADR 和语言优先级。
+- 是否遵守术语表和翻译范围。
+- 是否遵守 namespace 与文件 Ownership。
+- 是否误翻译模型名、API 参数、日志或代码示例。
+
+### 9.2 代码与质量 Review
+
+- 是否正确处理动态插值和复数。
+- 是否具有英文回退。
+- 是否覆盖可访问性文案。
+- 是否增加匹配风险的测试。
+- 是否改变原有业务行为。
+- 是否出现无意义的大范围格式化。
+- 是否具有可复现的测试证据。
+
+Review 结论：
+
+- `APPROVED`
+- `CHANGES_REQUESTED`
+- `BLOCKED`
+
+未经 `APPROVED` 的任务不得进入集成基线。
+
+QA 发现缺陷后的流程：
+
+```text
+QA 提交复现步骤和证据
+→ Agent 0 判定 Owner 与优先级
+→ 原开发 Owner 修复
+→ QA 定向回归
+→ Agent 0 Review 并关闭
+```
+
+---
+
+## 10. 测试与工程门禁
+
+测试重点：
+
+- 默认语言正确。
+- 切换语言即时生效。
+- 刷新后语言保持。
+- 缺失中文时回退英文。
+- 不显示原始翻译 key。
+- `<html lang>` 与当前语言一致。
+- 中文按钮、菜单、表格和弹窗不溢出。
+- 切换语言不丢失表单状态。
+- Login、SSO、MCP OAuth 整页跳转并返回后语言偏好保持。
+- 动态数量、日期、数字和货币正确本地化。
+- API 数据、模型名、日志和代码示例不被误翻译。
+- 构建期 `<title>` 与 metadata description 在 v1 保持英文，且没有被功能 Agent 意外改写。
+
+工程检查：
+
+```bash
+cd ui/litellm-dashboard
+npm run lint
+npm run format:check
+npm run build
+```
+
+补充规则：
+
+- Vitest 必须指定受影响的测试文件，不执行无路径的完整测试集。
+- 测试命令必须由 Agent 3 根据项目 Vitest 配置确认，并在任务回报中记录准确命令和结果。
+- 只有修改后端路由或响应模型时才运行 `npm run gen:api`。
+- 若清理了已有 ESLint suppression，使用项目规定的 `eslint . --prune-suppressions` 并检查差异。
+- 不假设或新增未经项目确认的 `eslint-budgets.json`。
+
+---
+
+## 11. v1 完成定义
+
+v1 只有同时满足以下条件才算完成：
+
+1. 支持 `en` 与 `zh-CN`。
+2. 语言切换即时生效，刷新后偏好保留。
+3. 导航、Login、Onboarding、Connect、MCP OAuth、Models、API Keys、Usage、Cost Tracking 和 Budgets 完成中文化。
+4. 中文缺失时回退英文，不直接显示翻译 key。
+5. 中文界面无严重截断、重叠和遮挡。
+6. 切换语言不清空表单或触发异常请求。
+7. Login、SSO、MCP OAuth 整页跳转并返回后语言偏好保持，或存在经批准且已记录的限制与降级方案。
+8. 构建期 `<title>` 与 metadata description 保持英文，不在 v1 中产生半完成的多语言 SEO 行为。
+9. 模型名、API 字段、日志和代码示例未被错误翻译。
+10. 改动相关的单元及集成测试通过。
+11. `lint`、`format:check` 和静态导出构建通过。
+12. Agent 7 提交测试报告。
+13. Agent 2 完成术语与中文体验复核。
+14. Agent 0 完成最终 Review 并给出 `APPROVED`。
+15. `V1_SCOPE_MANIFEST.md` 全部项目状态为完成，并附有测试、UI 检查和 Review 证据。
+
+---
+
+## 12. 下一步
+
+1. 启动 Wave 0，由 Agent 0 建立 `MASTER_PLAN.md`、`TASK_BOARD.md`、`FILE_OWNERSHIP.md` 和 `DECISIONS.md`。
+2. Agent 1 从干净代码基线完成技术设计、PoC 与 ADR，并验证静态导出构建。
+3. Agent 2、Agent 3 并行完成本地化规范、范围清单和测试方案。
+4. Agent 0 Review Wave 0 全部交付物并执行 G0 门禁。
+5. G0 通过后，为 Agent 4、Agent 5、Agent 7 创建独立任务 worktree 和分支，启动 Wave 1。
+6. 后续严格按照“1 个总控 + 3 个执行智能体”的并发限制滚动执行。

docs/i18n/I18N_TECH_DESIGN.md

@@ -0,0 +1,288 @@
+# LiteLLM Dashboard i18n — 技术方案设计（I18N_TECH_DESIGN）
+
+> 文档角色：Agent 1（`i18n-architect`）· Wave 0 交付 · 状态：**待 Baseline Review → 待 PoC 验证**
+> 基线：`I18N_MULTI_AGENT_PLAN.md` v1.4（§3、§5.2、D1–D14）
+> 范围：纯技术设计；本文档 **不修改任何产品代码**，所有文件路径均为设计目标而非已落地实现。
+
+---
+
+## 0. 阅读指引
+
+| 章节 | 内容 | 对应门禁/决策 |
+|---|---|---|
+| §1 | 技术选型兼容性结论（静态导出 + i18next + React 19） | D1、D4 |
+| §2 | Provider 层级 + `src/i18n/**` 模块划分 | D3 |
+| §3 | locale 初始化 与《语言偏好优先级》实现映射 | D5、D6 |
+| §4 | `<html lang>` 同步 + **首屏策略（选定 1 种）** | D7、G0/G1 门禁 |
+| §5 | 普通 `t()` 与 `<Trans>` 的资源就绪门禁 | §3.1、G1 |
+| §6 | `src/locales/{en,zh-CN}/**` 组织 与 namespace 注册 | D3、§3.3/3.4 |
+| §7 | 后端 `UI settings.language` 调查结论（P1/P2） | P1、P2 |
+| §8 | 与既有 Provider/路由组 layout 的接缝 | — |
+
+---
+
+## 1. 技术选型兼容性结论
+
+### 1.1 结论
+
+**`i18next` + `react-i18next` 与 `output: "export"`（静态导出）+ Next.js 16 + React 19 完全兼容，可作为 v1 方案。** 理由如下：
+
+1. `react-i18next` 的核心机制是**纯客户端**的 React Context + Hook（`useTranslation`），不依赖 Next.js 的任何服务端渲染钩子（`headers()`、`cookies()`、middleware、app-router locale 约定）。它既不需要 SSR 数据注入，也不要求在 node 侧执行。
+2. 在 `output: "export"` 下没有 Node 运行时，因此本方案**从不尝试在服务端解析 locale**（不依赖服务端 locale 路由 / httpOnly cookie 协商，见 D4）。locale 初始化完全在客户端 `I18nProvider`（`use client`）的挂载期完成。
+3. 静态 HTML 首帧默认按英文渲染（D8：构建期 title/meta 保持英文）。`<html lang>` 由客户端在挂载后同步（§4），`suppressHydrationWarning` 仅抑制该属性的 hydration 警告（与 next-themes 现有做法一致，见 `src/app/layout.tsx`）。
+
+### 1.2 已验证版本依据（本机只读核查，2026-09-09）
+
+| 项 | 值 | 依据 |
+|---|---|---|
+| 项目 React | `19.2.8` | `ui/litellm-dashboard/package.json` |
+| 项目 Next | `16.2.11` | 同上 |
+| 项目 TS | `5.9.3` | 同上 |
+| `react-i18next` 最新 | `17.0.13`（2026-09-01 发布） | `npm view` |
+| `react-i18next` peerDeps | `react: >= 16.8.0`, `i18next: >= 26.2.0`, `typescript: ^5\|\|^6\|\|^7` | `npm view react-i18next peerDependencies` |
+| `i18next` 最新 | `26.4.2` | `npm view i18next version` |
+| `i18next` peerDeps | 无 react peer（仅 `typescript`） | `npm view i18next@latest peerDependencies` |
+
+**兼容性判定**：React 19.2.8 ≥ 16.8.0，故 `react-i18next@17` 与 `i18next@26` 满足 peer 约束。**建议锁定范围**：`react-i18next@^17.0.13` + `i18next@^26.4.2`（Wave 1 由 Agent 4 写入，遵循 D12 单一写入者）。不采用旧版 15/16 行，避免为规避问题而引入历史缺陷。
+
+> 说明：以上为**只读** `npm view`（不安装、不改依赖）。实际安装验证由 Wave 1 Agent 4 承担（见 `POC_REPORT.md` PoC-1）。
+
+---
+
+## 2. Provider 层级与 `src/i18n/**` 模块划分
+
+### 2.1 Provider 放置层级
+
+`I18nProvider` 放**根 `src/app/layout.tsx`，作为最外层 Provider**（在既有 `ThemeProvider` 之外或与其并列的最上方）。理由：
+
+- 根 layout 渲染 `<html>`，`I18nProvider` 在此可统一同步 `document.documentElement.lang`（§4）。
+- 所有路由组（`(dashboard)`、`chat`、`connect`、`login`、`onboarding` 等）都经由根 layout，各自无需重复挂 Provider。
+- `I18nProvider` 是 `use client` 组件；因 Next.js 中根 layout 本身是 server component，需用一个 `"use client"` 的子组件包装。页面内部不含服务端下发的动态 locale，故无需用全局 server/client provider 分支。
+
+设计目标示意（**非当前代码，禁止修改**）：
+
+```tsx
+// src/app/layout.tsx（设计目标）
+<html lang="en" suppressHydrationWarning>
+  <body className={inter.className}>
+    <I18nProvider>          {/* 新增：最外层，use client 包装 */}
+      <ThemeProvider attribute="class" defaultTheme="light" enableSystem disableTransitionOnChange>
+        <NuqsAdapter>
+          <ReactQueryProvider>
+            <AuthProvider>{children}</AuthProvider>
+            <Toaster />
+          </ReactQueryProvider>
+        </NuqsAdapter>
+      </ThemeProvider>
+    </I18nProvider>
+  </body>
+</html>
+```
+
+### 2.2 `src/i18n/**` 模块划分（Ownership：Agent 4，永久，见 FILE_OWNERSHIP）
+
+```
+src/i18n/
+├── index.ts            # 公开出口：导出 I18nProvider 与 getI18n/useI18n 便捷 API
+├── I18nProvider.tsx    # "use client" Provider：初始化实例 + 语言就绪门禁 + <html lang> 同步
+├── i18n.ts             # createI18n(): 构建/复用 i18next 单例（resources、fallbackLng、supportedLngs）
+├── localePreferences.ts# 读/写语言偏好（cookie + localStorage 双层 + 浏览器语言嗅探）——纯函数，可单测
+├── detectLocale.ts     # 语言解析/规范化（'zh'→'zh-CN'、大小写、支持列表校验）
+├── types.d.ts          # 全局声明增强：模块扩展 'i18next' 的 CustomTypeOptions（资源键类型安全）
+└── resources/registry.ts  # === namespace 注册表 + 资源加载映射（唯一真源）=== 见 §6.2
+```
+
+职责边界：
+
+- `i18n.ts` 持有 i18next **单例**的生命周期（`initReactI18next`、`init`）。为保证 SSR 静态构建与 HMR 稳定，导出一个惰性 `getI18n()` 而非模块顶层 `init`（避免重复初始化）。
+- `localePreferences.ts` 不依赖 React，纯逻辑（读 cookie/localStorage/navigator），供单测覆盖 D5 优先级。
+- `resources/registry.ts` 是**唯一的 namespace 注册表 + 资源加载映射**：声明「locale ↔ namespace ↔ json 路径」，并导出给 `i18n.ts` 构造 resources。功能 Agent（A5/A6）**只往 json 加 key，不改此注册表**（FILE_OWNERSHIP 关键规则 1/6）。
+- `types.d.ts` 用 `CustomTypeOptions`（`defaultNS`、`resources`）让 `t()` 的 key 具备类型约束；英文资源为类型真源（D2：en 为真源）。
+
+---
+
+## 3. locale 初始化 与《语言偏好优先级》实现映射
+
+### 3.1 优先级实现映射（D5 → 代码）
+
+规范化后的优先级链（`detectLocale.ts + localePreferences.ts`）：
+
+```text
+用户主动选择(显式写入偏好存储)
+ → 用户级 UI 设置(后端 UI settings.language —— v1 不采用，见 §7)
+ → SameSite cookie / localStorage（双层）
+ → 浏览器语言（navigator.languages，经 supportedLngs 过滤）
+ → 英文 en（兜底）
+```
+
+实现要点：
+
+- **用户主动选择 vs 残留存储的区分**：用户在切换器显式选择语言时，`setLocale` 同时写 **cookie + localStorage** 并 `changeLanguage`。读取时把「cookie/localStorage 中存在显式写入的 locale」视为「用户主动选择」。为区分「显式选择」与「自动探测回写」，可用单独的 marker（如 cookie 值带 `explicit` 标记，或 localStorage 键与探测键分离）。**v1 建议**：统一用一个偏好键（如 `dashboard.locale`），只要该键存在即为用户选择；首次无键时才走浏览器语言。该判定需在 §3.2 明确，避免「用户从不手选」时被浏览器语言误判为主动选择。
+- **cookie 属性**：`SameSite=Lax`（非 Strict，避免 Okta/SSO 回跳丢失）、`path=/`、非 httpOnly（前端需读，D4 允许）。语言不敏感隐私，不设 Secure 亦可在 http 下工作；生产建议 `Secure`（见 TECH_RISKS R8）。
+- **无后端用户级设置**：P1/P2 结论为 v1 不使用 `UI settings.language`（§7），故优先级链简化为「显式选择 → cookie/localStorage → 浏览器语言 → en」。
+- **i18next 配置**：`supportedLngs: ['en','zh-CN']`、`fallbackLng: 'en'`、`nonExplicitSupportedLngs: false` + 在 `detectLocale` 中把 `navigator.language` 规范化为 `zh-CN`（`'zh'`/`'zh-Hans'`→`'zh-CN'`；其余→en）。load 路径由 registry 提供静态 resources，不使用 `loadPath` 网络加载（静态导出下目录外资源不可用）。
+
+### 3.2 关键判定汇总（供 PoC 与后续澄清）
+
+| # | 判定 | v1 默认 | 依据 |
+|---|---|---|---|
+| L1 | 偏好键唯一性 | 单一键 `dashboard.locale`，存在即视为显式选择 | §3.1 |
+| L2 | 浏览器语言含义 | 仅首次（无偏好键）时使用 | §3.1 |
+| L3 | cookie 属性 | `SameSite=Lax; path=/;`（生产加 `Secure`） | §3.1 / R8 |
+| L4 | 根 layout 的 `lang` 静态默认 | `en`（与静态 HTML 一致） | §4 |
+| L5 | 管理员全局覆盖用户选择 | v1 不实现（无该字段） | §7 / D8 |
+
+---
+
+## 4. `<html lang>` 同步 与 首屏策略（G0/G1 门禁，必须选定）
+
+### 4.1 首屏策略：**选定「语言就绪门禁 + 挂载后同步 `<html lang>`」**，不采用初始化脚本、不接受短暂切换。
+
+从候选「初始化脚本 / 语言就绪门禁 / 接受短暂切换」中，**选定「语言就绪门禁」（并且不在 `<head>` 内注入内联脚本）**。理由：
+
+- **初始化脚本（在静态导出下基本无效）**：该类脚本需在 next 的 `<script>` 阶段于头部内联以在 paint 前改写 `lang`/文本。但静态导出没有服务端可注入的 head 时机，且「切换到中文」需要**运行时加载 zh-CN 资源**——这只能在 client JS 就绪后通过 i18next 完成，内联脚本无法在现代打包下前置加载 JSON 资源并替换整棵 textContent。故初始化脚本收益低。
+- **接受短暂切换**：会把「首帧英文→JS 就绪后切中文」的闪烁当作常态，直接违反 D7「禁止首屏显示原始 key 后再替换」的精神（§5 进一步禁止 key 暴露）。不可接受。
+- **语言就绪门禁**最符合静态导出约束：首帧即是合法的英文 UI（D2 默认语言为 en，D8 title 为英文），不存在「错误语言闪烁」；JS 就绪后 i18next 收敛到偏好语言并同步 `<html lang>`。就绪门禁只是**短于 paint 的少量额外延时**，且保证「看到的就是最终语言」或「简短英文首帧后一次切换」。
+
+### 4.2 就绪门禁实现草图（设计目标）
+
+`I18nProvider` 在挂载时：
+
+1. 读取偏好（§3）→ 得到目标语言 `target`。
+2. 若 `target === 'en'`：`i18next.changeLanguage('en')`，`<html lang>` 已为 `en`，**无需门禁**，直接渲染 children。
+3. 若 `target === 'zh-CN'`：`await i18next.changeLanguage('zh-CN')`（resources 已在 `init` 时注册，changeLanguage 为同步内部切换完的 `t` 就绪）,当 `i18n.isInitialized && i18n.language === 'zh-CN'` 时为「就绪」。就绪前渲染一个**轻量就绪态**（如 `aria-busy` 的空壳/骨架，不渲染依赖 `t()` 的业务内容），就绪后渲染 children 并设置 `document.documentElement.lang = 'zh-CN'`。
+
+```tsx
+// src/i18n/I18nProvider.tsx（设计目标）
+"use client";
+export function I18nProvider({ children }: { children: React.ReactNode }) {
+  const [ready, setReady] = useState(() => resolveTarget() === "en"); // en 直接就绪
+  useEffect(() => {
+    const target = resolveTarget();            // localePreferences + detectLocale
+    getI18n().then(async (i18n) => {
+      if (target === "zh-CN") await i18n.changeLanguage("zh-CN");
+      document.documentElement.lang = i18n.language;   // 与 <html lang> 同步
+      setReady(true);
+    });
+  }, []);
+  if (!ready) return null;      // 或轻量就绪态；首帧为 en 时立即渲染
+  return children;              // 实际会包一层 I18nextProvider/useSSR(false)
+}
+```
+
+要点：
+- **`<html lang>` 同步**：`document.documentElement.lang = i18n.language`，在 `changeLanguage` 完成后、children 渲染前执行，使浏览器/屏幕阅读器解析到的语言与实际内容一致。
+- 不依赖内联脚本、不动 `metadata`（D8 保持英文 title）。
+- 就绪态渲染 null 或骨架，**不渲染任何 `t()`/`<Trans>` 内容**，天然杜绝「key 先暴露」（§5）。
+
+### 4.3 PoC 验证
+
+首屏切换的判定证据与测量由 Wave 1 执行（见 `POC_REPORT.md` PoC-2/PoC-3）：重点验证「en 默认首帧合法」、「切 zh-CN 后 `<html lang>` 更新」、「就绪门禁下业务内容不在就绪前出现」。
+
+---
+
+## 5. 普通 `t()` 与 `<Trans>` 的资源就绪门禁
+
+### 5.1 统一门禁原则
+
+**禁止首帧暴露原文 key。** 凡渲染翻译内容的组件，必须保证 i18next 资源就绪后其 `t`/`<Trans>` 才被求值。承接 §4.2 的顶层就绪门禁，业务组件**默认**就处于就绪之后（因为 `I18nProvider` 就绪前不渲染 children）。在此基础上再加两层保障：
+
+1. **资源键集合约束**：英文 `en/*.json` 是类型与资源真源（D2），`t()` 的 key 受 `CustomTypeOptions` 类型校验。**只允许引用已注册 namespace 的 key**——key 不存在会在类型层报错，从而无法「引用一个没资源的 key」（见 §6 的 en/zh 键一致性检查 + `test:types`）。
+2. **运行时兜底**：i18next 对缺失 key 默认回退 `fallbackLng='en'`；若 en 亦缺，`returnNull`/`returnEmptyString` 策略应配置为**返回 key 本身或空串且不渲染原文句子**，并在开发模式打 warning 以便早发现。**绝不允许把「英文句子」作为 key**（§3.4 语义 key 规范），从根上防止「key=原文→暴露原文」的伪就绪。
+
+### 5.2 `<Trans>` 的门禁
+
+- `<Trans>` 依赖资源同步就绪（§3.1：必须在资源同步就绪或统一 ready 门禁之后渲染）。
+- 因 §4.2 顶层门禁已保证业务子树在就绪后才挂载，`<Trans>` 不会有「先渲染占位再替换」窗口。
+- 若个别模块需要在自己内部再等，使用 `useTranslation` 的 `ready` 标志：`const { t, ready } = useTranslation('ns'); if (!ready) return skeleton;`。**推荐所有激进的内联文案一次性接入统一门禁，避免每个组件各自开花**；组件级 `ready` 仅用于少数在就绪后有异步依赖的场景。
+- `<Trans>` 复数/插值注意事项：zh 不建形态复数分支（D9），用 `{{count}}` 计数插值；`<Trans>` 内嵌组件（如带链接）需保证 `i18n` 与组件 props 的 children 均就绪。
+
+### 5.3 断言/测试
+
+- 集成测试以「首帧（未就绪）不出现 key 原文 / 不出现未翻译句」为断言（见 POC_REPORT PoC-4 与测试方案章节；由 Agent 3 细化）。
+
+---
+
+## 6. `src/locales/{en,zh-CN}/**` 组织 与 namespace 注册
+
+### 6.1 目录组织
+
+```
+src/locales/
+├── en/
+│   ├── common.json      # 全局公共文案（A4 Wave1 骨架 → G1 后 A5）
+│   ├── navigation.json
+│   ├── auth.json
+│   ├── models.json
+│   ├── apiKeys.json
+│   ├── usage.json
+│   ├── cost.json
+│   └── budgets.json
+└── zh-CN/
+    └── (同名 json，键集合与 en 一致)
+```
+
+- **namespace = 文件名 = key 冒号前缀**（§3.4：如 `common:action.delete` 对应 `common.json` 的 `action.delete`）。
+- 英文与中文**键集合必须一致**（§3.4；用 CI 键集合 diff 校验，见 R9）。
+- 中文按语义组织，不机械复制英文复数结构（D9）。
+
+### 6.2 namespace 注册表 / 资源加载映射（唯一真源，Agent 4 永久 Owner）
+
+`src/i18n/resources/registry.ts` 以数组/映射声明全部 namespace 及各 locale 的静态资源对象（`import common from "@/locales/en/common.json"`），供 `i18n.ts` 构造 `resources`。**往该注册表新增/删除 namespace 只有 Agent 4 可改**（FILE_OWNERSHIP 规则 6）。功能 Agent 新增业务 namespace 时在任务单填注册需求，由 A0 指派 A4 注册。
+
+登记形式（设计目标）：
+
+```ts
+// src/i18n/resources/registry.ts
+export const NAMESPACES = ["common", "navigation", "auth", "models", "apiKeys", "usage", "cost", "budgets"] as const;
+export type Namespace = (typeof NAMESPACES)[number];
+export const RESOURCES = {
+  en: { common, navigation, auth, models, apiKeys, usage, cost, budgets },   // 惰性 import
+  "zh-CN": { common, navigation, auth, models, apiKeys, usage, cost, budgets },
+} as const satisfies Record<Locale, Record<Namespace, object>>;
+```
+
+`types.d.ts` 引用 `RESOURCES['en']` 作为 `CustomTypeOptions['resources']`，保证 `t('common:action.delete')` 有类型。
+
+---
+
+## 7. 后端 `UI settings.language` 调查结论（P1/P2）
+
+本机只读调查（`litellm/` 后端代码，2026-09-09）：
+
+- **`UISettings` 模型**（`litellm/proxy/ui_crud_endpoints/proxy_setting_endpoints.py`）是代理级（管理员/全局）UI 配置，经 `/get/ui_settings`、`/update/ui_settings` 暴露，落在 `LiteLLM_UISettings` 表（`litellm/repositories/table_repositories.py:UISettingsRepository`，表名 `LiteLLM_UISettings` 见 `litellm/proxy/_types.py`）。
+- 该模型有 `model_config = ConfigDict(extra="allow")`（可携带额外字段），但**持久化受 `ALLOWED_UI_SETTINGS_FIELDS` 白名单约束**，而该白名单**不包含 `language` 字段**。白名单现有字段如 `disable_model_add_for_internal_users`、`enabled_ui_pages_internal_users`、`enable_chat_ui` 等，均与语言无关。
+- 即：**后端当前不存在可用的 `UI settings.language` 全局语言设置**。即便请求携带 `language`，也不在白名单内，不会被持久化/下发。
+
+**结论：**
+- **P2（该字段是否真实存在）**：**不存在**。`language` 不在 `UISettings` 白名单。
+- **P1（管理员全局设置是否覆盖用户主动选择）**：**v1 不实现该覆盖**，因为字段不存在。优先级链退化见 §3.1。若未来后端新增该字段，需产品决策「管理员全局 vs 用户选择」的覆盖语义，再补实现（本设计已预留 L5 判定位）。
+- 这同时**简化了 v1**：无需「用户偏好 vs 管理员全局」的合并/剥离逻辑，也避免在静态导出下引入「先取全局再取用户」的两段式异步。
+
+---
+
+## 8. 与既有 Provider / 路由组 layout 的接缝
+
+- 根 `layout.tsx`：现为 `ThemeProvider → NuqsAdapter → ReactQueryProvider → AuthProvider`。`I18nProvider` 追加为**最外层**（§2.1）。**不移动**现有 Provider 顺序，避免影响 next-themes 首帧打 class 的既有行为。
+- `(dashboard)/layout.tsx`：`use client` 路由组，另含 `SidebarProvider`、`ThemeContext`、`PluginModeContext` 等，均用到 `useAuth`。它们处于 `AuthProvider` 之下，`I18nProvider` 在最外层 → 这些组件可安全调用 `useTranslation`。**注意**：该 layout 自身是 `use client`，若其中出现硬编码文案需在 Wave 2 起中文化（A5/A6 职责）。
+- `chat/layout.tsx`、`connect/layout.tsx` 独立于 `(dashboard)`，仍归根 layout 的 `I18nProvider` 管理，无需各自挂 Provider。
+- **`<Trans>` 与 next-themes 的首帧 class 互不干扰**：`suppressHydrationWarning` 已覆盖 `<html>` 的未知属性（theme class / lang），本方案不加额外 suppress。
+
+---
+
+## 9. 依赖变更清单（仅供 Wave 1 Agent 4 执行，本设计不落地）
+
+| 变更 | 目标值 | 写入者 |
+|---|---|---|
+| 新增依赖 | `i18next@^26.4.2`、`react-i18next@^17.0.13` | A4（D12） |
+| 类型依赖 | 无需额外类型包（自带 TS 类型） | A4 |
+| `next.config.mjs` | **不改**（静态导出已满足） | — |
+
+---
+
+## 附录 A：门禁对照
+
+| 门禁 | 本设计的对应物 |
+|---|---|
+| G0（基线评审） | 本文档 §1–§8 供评审；D7 首屏策略已选定（§4.1） |
+| G1（平台能力） | §6.2 注册表/资源映射/类型归 A4；PoC 清单（POC_REPORT）由 A4/A7 执行并回填 |

docs/i18n/I18N_TEST_PLAN.md

@@ -0,0 +1,186 @@
+# i18n 测试总体策略（I18N_TEST_PLAN）
+
+> 角色：Agent 3 `qa-architect`（测试架构与验收设计）
+> 基线：`I18N_MULTI_AGENT_PLAN.md` §10 测试与工程门禁、§11 完成定义
+> 实施：Agent 7 `i18n-qa` 在 Wave 1+ 按本文档落地
+> 状态：G0 待评审
+
+## 0. 目标与边界
+
+本文件定义 LiteLLM Dashboard `en` / `zh-CN` 国际化的测试总体策略：三层测试边界、key 一致性与硬编码扫描、中文布局检查、可访问性文案覆盖，以及自动化与人工程度的边界。
+
+**纯设计输入**：本文件与配套 `TEST_CASES.md`、`TEST_TOOLS.md`、`REGRESSION_MATRIX.md` 只规定"测什么、怎么测、如何验收"，不修改任何产品代码，不实际执行测试。实际执行由 Agent 7 在 Wave 1+ 负责。
+
+## 1. 三层测试边界（与项目现有 tier 对齐）
+
+### 1.1 事实校准
+
+项目 `vitest.config.ts` 定义 4 个 vitest project：
+
+| vitest project | 环境 | include | 对应"概念层" |
+|---|---|---|---|
+| `unit` | node | `src/**/*.test.ts`, `tests/**/*.test.ts`（非渲染） | 逻辑单元（无 DOM） |
+| `component` | jsdom | `src/**/*.test.tsx`, `tests/**/*.test.tsx`（非 `*.integration.test.tsx`） | 组件单元（毫秒级） |
+| `integration` | jsdom | `*.integration.test.tsx`（含 `tests/**`） | 集成（秒级） |
+| `types` | tsc | `*.test-d.ts` / `*.test-d.tsx` | 类型测试（`npm run test:types`） |
+
+CLAUDE.md 提到的三档（unit / integration / E2E）与 vitest 的 `unit`+`component`+`integration` 需在测试文档中统一术语：**本文档"单元层"泛指 vitest `component` project 的 jsdom 单组件测试（`*.test.tsx`），"逻辑单元层"特指 `unit` project 的 node 逻辑测试（`*.test.ts`）**。E2E 为 Playwright（见 §1.4）。
+
+工程命令（方案 §10）：
+
+```bash
+cd ui/litellm-dashboard
+npm run lint           # eslint .
+npm run format:check   # prettier 校验
+npm run build          # next build（静态导出）
+npm run test:types     # vitest run --project types
+```
+
+Vitest 定向执行：只跑改动相关文件；单元/组件层毫秒级、集成秒级；禁止无路径全量 `vitest run`。
+
+### 1.2 单元层（component project，`*.test.tsx`）
+
+i18n 场景中，单元层只负责"单一模块、单一微行为"，依赖以 double 替换。
+
+i18n 场景下的单元层**边界**：
+- **locale 工具函数**（纯函数，放 `unit` project 的 `*.test.ts`）：语言选择合并逻辑（优先级合并）、`<html lang>` 计算、浏览器语言映射、首选项写入 cookie/localStorage 的序列化与解析。
+- **插值/复数/格式化纯函数**（`*.test.ts`）：`count=0/1/2`、日期、数字、货币的格式化结果，无 DOM。
+- **单个 UI 小组件**（`*.test.tsx`）：语言切换器按钮、单个翻译标注组件（占位）、量词插值组件，使用 i18next 的 `initReactI18next` 测试实例注入最小字典（en+zh），断言渲染文本。**不渲染整页、不跨组件**。
+- 计数器本地化组件（D9）：`count=0` → `0 个`，`count=1` → `1 个`，`count=2` → `2 个`。
+
+单元层不做：整页断言、真实网络、`<html>` 全局状态、路由跳转。
+
+### 1.3 集成层（`*.integration.test.tsx`）
+
+集成层渲染**真实组件树**，仅 stub 网络边界，验证"单元测试无法触达的接线"。
+
+i18n 场景下的集成层**边界**：
+- 根应用/页面级内容：`I18nProvider` 包裹下，Navbar / Leftnav / Login / Models / Usage 等页面在切换语言后**即时**更新（真实组件树 + Provider 链）。
+- 语言切换不丢失表单状态：在集成树中填写字段 → 切换语言 → 断言字段值仍在、未触发无关请求。
+- 动态插值与复数在组件级布线正确（由单元层证明逻辑，集成层证明"字段→key→渲染"链路）。
+- `<Trans>` 组件在资源就绪后渲染（不先出原始 key）。
+
+集成层不做：真实浏览器、真实 `document.title` 持久化之外的行为、整页导航刷新行为。
+
+**命名**：`Foo.integration.test.tsx`，`vitest run --project integration <path>`。
+
+### 1.4 E2E 层（Playwright，`tests/e2e/ui/`）
+
+E2E 覆盖"真实浏览器 + 真实静态导出站点/活 proxy"下的端到端行为。**当前仓库不存在 Playwright 基础设施**（无 `playwright.config.*`、无 `tests/e2e/ui/`、无 `@playwright/test` 依赖），这是 Agent 7 在 Wave 1 必须补齐的平台缺口（需要 `package.json` 变更时，须由 Agent 0 指派唯一 Owner，遵守 §6.1 依赖单一写入者约束）。
+
+E2E 负责的 i18n 行为：
+- **默认语言**：首次访问（无偏好）→ 英文 `en`。
+- **切换即时生效**：真实浏览器点击切换 → `<html lang>` 更新 → 页面文本更新。
+- **刷新保持**：切换 → `page.reload()` → 语言保持。
+- **整页跳转恢复**：Login / SSO / MCP OAuth 整页跳转并返回后语言保持（同源 cookie/localStorage 恢复）。
+- `<html lang>` 与当前语言一致。
+- 缺 key 回退英文、不显示原始 key。
+- 构建期 `<title>` / meta description 保持英文。
+
+E2E 在静态导出下运行（`npm run build` 产生 `out/`）。Playwright 配置不在 vitest 内；作为独立阶段与 `npm run build` 串联，在 Wave 4A 完整回归使用。
+
+### 1.5 三层分工示意
+
+| 行为 | 单元 | 集成 | E2E |
+|---|---|---|---|
+| 插值/复数/格式化正确性 | ✅ 逻辑纯函数 | — | 抽查 |
+| 切换语言组件渲染 | ✅ | ✅ 真实树 | ✅ 真实浏览器 |
+| 表单状态保持 | — | ✅ | 抽查 |
+| 刷新语言保持 | — | 🔸（jsdom 有限） | ✅ |
+| 整页跳转恢复 | — | — | ✅ |
+| `<html lang>` | ✅ 计算函数 | ✅ Provider 接线 | ✅ 浏览器 DOM |
+| `<title>`/meta 英文 | — | — | ✅ |
+
+## 2. key 一致性与硬编码扫描
+
+### 2.1 key 集合一致性校验
+
+自动校验 `en` 与 `zh-CN`（以及后续任何 locale）的字典 key 集合完全一致，即对所有 namespace：
+
+```
+keys(en/<ns>.json) == keys(zh-CN/<ns>.json)
+```
+
+- 语义 key（`common:action.delete`）必须成对存在；存在偏置即失败，连同**缺 key 清单**一起输出，退出码非 0。
+- 同时校验"被引用的 key ⊆ 已声明 key"（组件 `t('ns:key')` / `useTranslation('ns')` 引用 vs 字典存在性），防止静态分析漏检的悬空 key 在运行时回退英文却被误当业务缺失。
+- 结构与值类型也必须一致（嵌套层级、插值变量 `{{x}}` 集合一致，避免 en 有 `{{count}}` 而 zh 漏掉）。
+- 运行方式：独立 node 脚本（见 `TEST_TOOLS.md`），纳入 CI 或门禁 G3 的"中英文 key 集一致"。
+
+### 2.2 硬编码字符串扫描（只报告、不自动改写）
+
+按方案 §3.4：扫描工具**只报告候选硬编码，不自动生成 key，不自动改写代码**。Agent 7 实现时严格遵守该约束——扫描结果进入报告，人工/产品决定是否改写。
+
+扫描器规则（对 TSX/TS 源码）：
+- 识别疑似承载用户可见文案的 `JSXText`（非注释、非空白、非纯符号）。
+- 识别 `aria-label`、`title`、`placeholder`、`alt` 等可访问性/文案属性中的字符串字面量。
+- 识别 `t('...')` 之外 `useMessage`/`useToast`/`toast(...)` 等常见未国际化文案入口（以项目现状校准）。
+- 排除：模型名/API 字段/日志/代码示例引用、路径、正则、CSS 类名、`data-slot`、纯数值/符号、标识符。
+- 输出：文件、行、候选文案、所属 namespace 建议（仅供人工参考），**不自动写入字典**。
+
+扫描器产出人工 review 清单，用于判断"应改为 `t()` 的遗漏硬编码"。
+
+### 2.3 误翻译保护
+
+- 反向断言：模型名、API 字段、日志原文、代码示例在 zh 与 en 下渲染一致（不被翻译）。见 `TEST_CASES.md` TC 对应项。
+- 扫描器补充规则：对 `en.json` / `zh-CN.json` 的 value 做"疑似把模型名/字段名当值"的启发式标注（如值与标识符/模型名称重合），仅供人工复核。
+
+## 3. 中文布局检查矩阵
+
+中文文案通常比英文短，但存在换行、量词、长词（如"成本跟踪"、英文品牌名混排）导致溢出/截断/重叠的风险。逐模块（导航/表格/弹窗/表单/全局壳层）检查：
+
+| 区域 | 检查维度 | 断言/观察项 |
+|---|---|---|
+| Navbar / Leftnav | 溢出、折行、截断 | 菜单项不换行错位、品牌/Menu 图标不重叠；窄屏不横向溢出 |
+| 表格（Models/API Keys/Usage/Cost/Budgets） | 列宽截断、单元格换行 | 中文表头不截断语义、值不溢出列边界、tooltip 不遮挡 |
+| 弹窗/Modal | 溢出、空白、遮挡 | 标题/正文/按钮在视口内、无横向滚动条溢出、Close 按钮可点 |
+| 表单 | label 对齐、placeholder 长度 | label 不折行错位、error 提示不截断、placeholder 不溢出控件 |
+| 全局壳层 | 用户菜单、语言切换器 | 中文菜单项不截断，切换器标签完整 |
+
+检查粒度：
+- **自动化**：E2E/组件层断言"内容可读但不溢出容器"（无横向滚动、`scrollWidth <= clientWidth`、关键文本 `toBeVisible`），以及对特定元素做快照对比。
+- **人工**：跨语言并列渲染的视觉走查（Agent 2 术语体验复核 + Agent 7 UI 检查），覆盖窄屏与中文长字符串用例；`V1_SCOPE_MANIFEST.md` 的 `UI 检查` 栏填写证据。
+
+矩阵逐项仍落地于 `REGRESSION_MATRIX.md`。
+
+## 4. 可访问性文案覆盖要求
+
+i18n 不只是可见文本；`aria-label`、`title`、`placeholder`、`alt` 等必须随语言本地化（方案 §5.6 同步处理要求）：
+
+- **每处用户可见文本都应有可访问等效**：图标按钮、关闭按钮、导航折叠按钮等必须提供本地化的 `aria-label`（`aria-hidden` 或纯装饰除外）。
+- **辅助文本本地化**：`title`/tooltip、`placeholder`、校验 error message、`role="meter"` 的 `aria-valuenow`（用 `toHaveAttribute` 断言，避免 `toHaveValue` 误用——CLAUDE.md 约定）均本地化。
+- **语序不破坏可访问性**：`aria-label` 与可见文本一致；`aria-labelledby` 指向本地化 label。
+- **测试断言**：使用可访问查询（`getByRole`/`getByLabel`/`getByText`）优先，其次 `data-slot`；不使用 `eslint --fix` 批量修正 testing-library/jest-dom（CLAUDE.md 约定），`toHaveTextContent` 传 plain string 子串匹配。
+- **英文回退对 a11y 文案同样生效**：zh 缺失时 `aria-label` 等回退英文，不显示原始 key。
+
+## 5. 默认语言 / 刷新 / 首屏策略的测试侧重
+
+- **默认语言**：无任何偏好时 = `en`；这是最终回退，任何层级测试都以此为基线。
+- **刷新保持**（E2E）：`page.reload()` 后仍为当前语言；核实存储介质（SameSite cookie 或 localStorage——CLAUDE.md 禁 token，但语言偏好非敏感；偏好介质以架构决策为准）。
+- **首屏闪烁**：`<Trans>`/`t()` 在资源就绪后渲染，首帧不暴露原始 key（方案 §3.4/§10）。E2E 首次导航截图断言不出现 `namespace:...` 原始 key 文本。
+- **`<html lang>`**：与当前语言一致（`en` 或 `zh-CN`）；组件层与 E2E 均断言。
+
+## 6. 自动化 / 人工边界总结
+
+| 事项 | 自动化 | 人工 |
+|---|---|---|
+| 单元/组件逻辑 | ✅ | — |
+| 集成布线 | ✅ | — |
+| E2E（切换/刷新/跳转/lang/title） | ✅ | — |
+| key 集合一致性 | ✅（脚本，CI） | — |
+| 硬编码扫描 | ✅（脚本报告） | ▲ 决定是否改写 |
+| 中文布局视觉 | 🔸（溢出断言） | ▲ 跨语言走查 |
+| 翻译质量/术语 | — | ▲ Agent 2 复核 |
+| 误翻译判断 | 🔸（启发式） | ▲ 人工复核 |
+
+## 7. 测试数据与工具接口约定
+
+- 测试用最小字典：单元/集成层注入 `en`+`zh-CN` 的最小命名空间子集，不足最小集时直接断言英文回退。
+- 时间固定：日期/货币断言使用固定 locale 与固定时间源（fake timer），避免时区/运行时刻不稳定。
+- 存储抽象：偏好读写针对于可注入的 storage/cookie 抽象 double，避免测试污染真实 localStorage。
+
+## 8. 门禁映射
+
+- **G0**：本策略与 `TEST_CASES.md` 通过 Review。
+- **G1**：平台层测试（切换/回退/`<html lang>`/首屏/整页跳转）与 key 一致性脚本具备；`npm run build` + 定向 vitest 通过。
+- **G2/G3**：各模块测试、UI 检查、`V1_SCOPE_MANIFEST.md` 证据齐，中英文 key 集一致。
+- **G4**：`REGRESSION_MATRIX.md` 全量回归通过（Agent 7 报告 + Agent 8 汇总）。

docs/i18n/LANGUAGE_SWITCHER_SPEC.md

@@ -0,0 +1,84 @@
+# 语言切换器详细设计（Language Switcher Spec）
+
+> 维护者：Agent 2（localization-designer）
+> 状态：设计稿，待 G0 评审
+> 关联：`I18N_MULTI_AGENT_PLAN.md`（§1.1/D5/D6）、`DECISIONS.md`、`LOCALIZATION_SPEC.md` §1、`LOCALE_NAVIGATION_BEHAVIOR.md`
+
+本文档定义语言切换器的**入口位置、显示形式、状态、交互、持久化与可访问性**。它是供 Agent 5（壳层开发）实现的交互契约。
+
+---
+
+## 1. 入口位置（建议）
+
+v1 只有一个入口，放在**顶部导航栏（Navbar）右侧**，靠近用户/账号菜单，以便登录后各页都能发现。
+
+- 首选位置：`navbar.tsx` 右端、用户菜单图标左侧，作为独立图标按钮。
+- 备选：若 Navbar 空间受限（静态导出、窄屏），回退到 `SidebarAccountMenu` 账号弹层内放置文字切换。
+- **登录/引导页（Login、Onboarding、Connect、MCP OAuth）也必须有入口**，因为用户可能在这些页面首次选择语言。建议在这些页面顶部/右上角放置同一图标按钮（复用同一组件），与 Dashboard 主体入口共用组件逻辑。
+
+> 实现要求：切换器组件做成可复用的独立组件（如 `src/components/LanguageSwitcher.tsx`），在 Navbar/账号菜单/登录页引用，避免多份复制。
+
+## 2. 显示文案
+
+- 按钮仅显示图标 + 当前语言的**目标语言缩写**，用于明确"点一下会变成什么"，同时按钮自身可在弹层中切换。
+- 展示为 **「中文」/「EN」**：
+  - 当前为 `en` 时，按钮显示 **中文**（提示可切到中文）。
+  - 当前为 `zh-CN` 时，按钮显示 **EN**（提示可切到英文）。
+- 展开菜单（Popover/Menu）时，提供两行完整选项：`English` 与 `简体中文（zh-CN）`，当前语言行加选中态（勾选/高亮）。
+- 若空间允许，可在按钮前显示一个地球图标（`lucide` `Globe`/`Languages`），并在展开菜单用图标区分。
+
+### 2.1 为什么按钮显示"目标语言"
+
+图标 + 目标语言缩写最节省空间且语义清晰（常见国际化 UI 惯例，如 GitHub/Google）。同时菜单内提供明确的"当前语言"选中态，避免歧义。
+
+### 2.2 空态/兜底
+
+- 若某些组件在资源未就绪时不渲染切换器，则**优先不显示**而不是显示错误语言；资源就绪后由统一 ready 门禁放行（D7）。
+- 切换器自身文案（`aria-label`、菜单项"English / 简体中文"）用当前语言渲染，保证用户总能用自己当前看到的语言操作它。
+
+## 3. 状态
+
+| 状态 | 表现 |
+|---|---|
+| 当前 `en` | 按钮显示"中文"；菜单中 `English` 高亮为选中 |
+| 当前 `zh-CN` | 按钮显示"EN"；菜单中 `简体中文（zh-CN）` 高亮为选中 |
+| 加载中/资源未就绪 | 按钮不闪烁、不显示 key；就绪后出现 |
+| 存储不可用（隐私/禁 cookie） | 会话内仍可切换（见 `LOCALE_NAVIGATION_BEHAVIOR.md`），但刷新后回退 |
+
+## 4. 交互
+
+1. 点击按钮打开菜单（Popover/Menu）。
+2. 选择目标语言项：
+   - **即时生效**：当前页所有文案立即切换，无需刷新或整页跳转（`LOCALIZATION_SPEC.md` §1.3）。
+   - 同时更新 `<html lang>`（`lang="zh-CN"` / `lang="en"`）。
+   - 关闭菜单。
+3. 切换**不**重置表单、导航展开、滚动位置；不触发额外请求。
+
+## 5. 持久化行为
+
+- 切换成功后**同步写入**：
+  1. **localStorage**：键 `litellm.locale`（约定，见下），值 `en` | `zh-CN`。
+  2. **SameSite cookie**：同名 cookie，`SameSite=Lax`、`path=/`，一个较长的有效期（如 365 天），用于跨整页跳转/新标签恢复；不设为 httpOnly（前端需读）。
+- 存储键建议统一为常量 `litellm.locale`，由 Agent 4 在 `src/i18n/**` 提供读写函数，Agent 5/6 不直接操作存储。
+- **优先级**：读取时优先 user 主动选择 → cookie/localStorage → 浏览器语言 → en（见 `LOCALIZATION_SPEC.md` §1.1）。cookie 与 localStorage 两者都存在时以较新写入者为准（实现按 D5/D6 由 Agent 4 定，建议以 localStorage 为准，cookie 用于跨页恢复）。
+- 写入失败（隐私模式）不报错、不阻塞切换，静默降级。
+
+## 6. 可访问性
+
+- 触发器按钮必须带 `aria-label`，内容随当前语言本地化：
+  - `en` 下：`Change language` / `选择语言`（用当前语言渲染，即 en 时英文标签，zh 时中文标签）。
+  - zh 下：`切换语言`。
+  - 推荐：`aria-label="Switch language"`（en）/ `"切换语言"`（zh-CN）。
+- 菜单用 `role="menu"`/`menuitemradio` 或 Popover 语义，支持键盘操作（方向键选择、Enter 确认、Esc 关闭）。
+- 选中项要有 `aria-checked` 或视觉高亮 + `aria-current`。
+- 焦点管理：打开时焦点移至菜单，关闭后返回触发器。
+
+## 7. 测试要点（供 Agent 7 参考）
+
+- 切换即时生效（DOM 文案变化且无整页刷新）。
+- 刷新后保持（cookie/localStorage 恢复）。
+- `<html lang>` 与当前语言一致。
+- 切换不清空表单/不触发请求。
+- 当前语言在菜单中正确高亮。
+- aria-label 随语言变化。
+- 存储不可用时降级行为（见 `LOCALE_NAVIGATION_BEHAVIOR.md`）。

docs/i18n/LOCALE_NAVIGATION_BEHAVIOR.md

@@ -0,0 +1,104 @@
+# 语言导航行为定义（Locale Navigation Behavior）
+
+> 维护者：Agent 2（localization-designer）
+> 状态：设计稿（G0 门禁交付物之一）
+> 关联：`I18N_MULTI_AGENT_PLAN.md` §3.3、`DECISIONS.md` D5/D6/D7/D10、`LOCALIZATION_SPEC.md`、`LANGUAGE_SWITCHER_SPEC.md`
+> 依据：本文件满足 G0 门禁中"Login、SSO、MCP OAuth 整页跳转后的语言保持规则已写入本地化与测试方案"。
+
+本文档定义**语言在导航/跳转各场景下的期望行为、降级规则与可测试验收点**。静态导出、客户端收敛、无服务端 locale 路由是背景约束（D4/D6）。
+
+---
+
+## 1. 场景总览
+
+| 场景 | 语言来源 | 期望结果 |
+|---|---|---|
+| 首次访问（无偏好） | 浏览器语言 → en | 按浏览器语言；中文浏览器默认 zh-CN |
+| 后续访问（有偏好） | cookie/localStorage 偏好 | 保持已选语言 |
+| 手动切换 | 用户选择 | 即时生效并持久化 |
+| 页面内 SPA 导航 | 当前会话 | 语言跨页保持 |
+| Login 提交回跳 | 同源存储 | 保持切换前语言 |
+| SSO 登录回跳 | 同源存储 | 保持（见 §4 例外与降级） |
+| MCP OAuth 授权回跳 | 同源存储 | 保持 |
+| 存储不可用（隐私/禁 cookie） | 会话内存 | 会话内可切换，刷新后回退 |
+
+---
+
+## 2. 首次访问
+
+- 定义：无任何已存偏好（cookie 与 localStorage 均无 `litellm.locale`）。
+- 行为：读取 `navigator.language`（或 `navigator.languages` 首项）。以 `zh` 开头 → `zh-CN`；否则 → `en`。
+- 不弹出语言选择对话框；以浏览器语言为默认即可（`LOCALIZATION_SPEC.md` §1.2）。
+- 首次进入后会将所选语言**写回偏好**（可选），如此后浏览器语言变化不再覆盖。
+- 验收点 A1：见 §6。
+
+## 3. 手动切换后的行为
+
+- 切换即时生效（无刷新、无整页跳转），写入 localStorage + cookie（见 `LANGUAGE_SWITCHER_SPEC.md` §5）。
+- 同一标签页内 SPA 路由跳转（Leftnav 点击）语言保持；导航状态、表单、滚动不被清空。
+- 新开标签页/使用同一浏览器时，从偏好恢复。
+- 验收点 A2/A3：见 §6。
+
+## 4. 整页跳转与回跳（Login / SSO / MCP OAuth）
+
+背景：SPA 内这些登录动作会离开当前页面去往后端/第三方，完成后再整页加载回跳地址。
+
+### 4.1 期望
+
+1. 跳转前语言已由客户端写入**同源 cookie + localStorage**。
+2. 回跳到同源页面后，语言初始化在客户端收敛阶段从偏好恢复，**语言应与跳转前一致**，不得回落到英文。
+3. Login 提交回跳、SSO 回跳、MCP OAuth 回跳三种都应能恢复（方案 §3.3 PoC 要求）。
+
+### 4.2 例外与降级
+
+- **Cookie 不可用 / 隐私模式**：localStorage 也可能受限。此时无法跨整页跳转持久化语言，回跳后按"无偏好"重估（浏览器语言→en）处理，属**可接受降级**，但必须**静默**，且不允许出现语言"闪烁"到错语言再纠正的体验。
+- **SSO 第三方域**（如外部 IdP）：跳转发生在第三方域，前端无法携带语言 cookie 过去，但**回跳回同源**时仍在同源 cookie/localStorage 作用域内，可恢复。若 IdP 协商了完全不同的域且无同源 cookie，则按浏览器语言降级。
+- **首次在 Login 页选择语言后即整页跳转**：选择须在跳转前完成持久化，回跳恢复；这是 Login 页必须放切换器入口的原因（`LANGUAGE_SWITCHER_SPEC.md` §1）。
+
+### 4.3 存储写入时机
+
+为确保跳转前已持久化，语言偏好在**切换动作发生时立即写入**，而非等到刷新/跳转。禁止"仅内存 + 跳转前延迟写"导致竞态丢失。
+
+- 验收点 A4/A5/A6：见 §6。
+
+---
+
+## 5. 存储不可用时的降级规则
+
+| 失败类型 | 行为 |
+|---|---|
+| localStorage 写入抛异常/Safari 隐私模式 | 捕获异常静默跳过写入；会话内内存变量仍生效，当前页面可切换 |
+| cookie 被禁/无法设置 | 同上，静默跳过；跨整页跳转可能会丢失语言（按 §4.2 降级） |
+| 读取时两者都无 | 走"首次访问"逻辑（浏览器语言 → en） |
+| 被第三方脚本/iframe 限制（`document.cookie` 不可读） | 视为无偏好，按浏览器语言；不抛错 |
+
+原则：**任何存储失败不得阻塞 UI 或抛出可见错误**；只影响持久化，不影响会话内切换。
+
+---
+
+## 6. 可测试验收点（可自动化 + 可手动）
+
+供 Agent 3/7 落地为用例，也作为 G0 后验证。
+
+| ID | 验收点 | 期望 |
+|---|---|---|
+| A1 | 中文浏览器首次访问默认语言 | `navigator.language=zh-*` → 首屏为 zh-CN |
+| A2 | 手动切换即时生效 | 选 zh-CN 后当前 DOM 文案变为中文，无整页刷新 |
+| A3 | 刷新后保持 | 切换后刷新，仍为 zh-CN；`<html lang="zh-CN">` |
+| A4 | Login 提交回跳语言保持 | Login 前选 zh-CN → 提交登录 → 回跳到 Dashboard 仍为 zh-CN |
+| A5 | SSO 回跳语言保持 | 选 zh-CN 进入 SSO → 回跳后仍为 zh-CN |
+| A6 | MCP OAuth 回跳语言保持 | MCP OAuth 授权回跳后仍为 zh-CN |
+| A7 | 存储不可用降级 | 禁 cookie + 隐私模式：会话内可切换，刷新后按浏览器语言/en，不抛错、不闪烁 |
+| A8 | 缺 zh-CN key 回退 | 仅 en 有某 key 时，zh 下该处回退英文，不显示 key |
+| A9 | 首帧不闪 key | 首帧不显示原始翻译 key（ready 门禁，D7 实现后验证） |
+| A10 | `<html lang>` 一致 | 任意语言下 `document.documentElement.lang` 与当前语言一致 |
+| A11 | 切换不清空表单 | 选语言前填写的表单在切换后内容保留 |
+
+> 注意：A4/A5/A6 依赖真实登录/SSO/OAuth 回跳环境，PoC 阶段（Wave 1）由 Agent 1 先用"跳转-返回"模拟验证，A7/A9 可作为轻量替代证据，需 Agent 0 批准后视为已覆盖。
+
+---
+
+## 7. 风险与待定
+
+- SSO 第三方域回跳的外域 cookie 是浏览器级限制，如实际不可恢复，需 Agent 0 批准记录为明确限制（方案 §11.7 允许）。
+- `html lang` 首屏同步在 SSR/hydration 下可能滞后，由 D7 首屏策略决定；不得因此回退翻译。

docs/i18n/LOCALIZATION_SPEC.md

@@ -0,0 +1,252 @@
+# LiteLLM Dashboard 本地化规范（Localization Spec）
+
+> 维护者：Agent 2（localization-designer）
+> 状态：设计稿，待 G0 评审
+> 范围：LiteLLM Dashboard 前端 UI 的 `en` / `zh-CN` 本地化
+> 关联：`I18N_MULTI_AGENT_PLAN.md`（§3.3/§3.4/§5.2）、`DECISIONS.md`、`LANGUAGE_SWITCHER_SPEC.md`、`GLOSSARY_EN_ZH.md`
+
+本文档定义语言的**交互规则**与**中文文案风格标准**。它回答"什么时候用什么语言"以及"中文应该怎么写得专业"。具体每个页面/组件翻不翻、翻哪些，见 `V1_TRANSLATION_SCOPE.md`；语言切换器的 UI 细节见 `LANGUAGE_SWITCHER_SPEC.md`。
+
+---
+
+## 1. 语言规则
+
+### 1.1 语言标识与优先级
+
+- 语言代码：`en`（默认）、`zh-CN`。
+- `en` 是**真源与最终回退**；任何缺少 `zh-CN` key 的字符串一律回退英文，绝不允许显示原始 key。
+- 语言优先级（D5，已定）：
+  ```
+  用户主动选择
+  → 已确认的用户级 UI 设置（如后端支持，v1 默认不启用）
+  → cookie + localStorage
+  → 浏览器语言
+  → en
+  ```
+- 语言偏好判定完全在客户端完成（静态导出约束，D4）。
+
+### 1.2 首次进入
+
+- 无任何已存偏好时：读取浏览器语言。若 `navigator.language` 以 `zh` 开头（`zh`、`zh-CN`、`zh-TW`、`zh-Hans` 等均视为中文系），则初始为 `zh-CN`；否则为 `en`。
+- 首次进入**不强制弹出语言选择对话框**。以浏览器语言为默认即可；用户可随时通过切换器更改。
+- 首次进入后（即一旦存在已存偏好），优先使用已存偏好，不再读取浏览器语言。
+
+### 1.3 手动切换
+
+- 切换**即时生效**，无需刷新、无需整页跳转；当前页面所有文案立即切换。
+- 切换时**保留表单状态、滚动位置、导航展开状态**，不允许因语言切换重置表单或触发异常请求（v1 完成定义第 6 条）。
+- 切换后立即写入 cookie + localStorage（行为见 `LANGUAGE_SWITCHER_SPEC.md`）。
+
+### 1.4 整页跳转与回跳（Login/SSO/MCP OAuth）
+
+详细行为与降级见 `LOCALE_NAVIGATION_BEHAVIOR.md`。摘要：
+
+- Login 提交、SSO 登录、MCP OAuth 授权可能发生整页跳转（起跳自同源页面，回跳到同源页面）。
+- 跳转返回后必须从**同源 cookie 或 localStorage** 恢复语言，语言不应回落到英文。
+- 若同源存储不可用（隐私模式、禁 cookie），允许回退英文，但不允许出现语言"闪烁"到错误语言的体验缺陷。
+
+### 1.5 构建期元数据
+
+- v1 构建期 `<title>` 与 metadata description **保持英文**（D8），不做多语言 SEO。功能 Agent 不得被动扩大此范围。
+
+---
+
+## 2. 中文文案风格规范
+
+目标：**专业、自然、克制、无翻译腔**。面向开发者/运维人员（Dashboard 用户以工程师为主），用词应准确、简洁，避免口语化和过度文学化。
+
+### 2.1 通用原则
+
+1. **以用户动作和对象为先**。按钮用"动词 + 宾语"最短形式（见 2.2）。
+2. **不用翻译腔**：避免"为了……我们将会……"、"请注意"、"请务必"等冗余；避免英文逐字直译的语序污染。
+3. **控制长度**：中文比英文短，但信息密度高。菜单项/按钮 ≤ 6 字为佳，超过 8 字注意换行与截断（见 §3）。
+4. **术语一致**：一律采用 `GLOSSARY_EN_ZH.md` 中的词条，禁止同义词漂移（如"Spend"一会翻"花费"一会翻"支出"）。
+5. **敬语从简**：界面动作祈使句即可，不加"您"的过度堆叠；保留必要礼貌但不每一句都加。
+6. **标点**：中文使用全角标点（`，`、`。`、`：`、`？`），英文/数字/型号与中文混排时两侧不加空格；数字、单位用半角（`10 次` 中空格与否按项目 UI 惯例统一）。
+7. **占位符与插值**：不译 `{{variable}}`、`{{count}}` 内的变量名；品牌名 LiteLLM、OpenAI 等不译。
+
+### 2.2 按钮文案
+
+- 格式：**动词（+ 宾语）**，祈使句。
+- 通用按钮术语（复用 `GLOSSARY_EN_ZH.md` + `common.json`）：
+  | EN | ZH-CN |
+  |---|---|
+  | Save | 保存 |
+  | Cancel | 取消 |
+  | Delete | 删除 |
+  | Create | 创建 |
+  | Add | 添加 |
+  | Edit | 编辑 |
+  | Update | 更新 |
+  | Enable / Disable | 启用 / 停用 |
+  | New Virtual Key | 新建虚拟密钥 |
+  | Generate | 生成 |
+  | Copy | 复制 |
+  | Close | 关闭 |
+  | Confirm | 确认 |
+  - 含受保护动作（删除、重置、清空）的按钮在确认弹窗中保持同一译名，不要换成同义"移除/清除"造成语义漂移。
+
+### 2.3 表单文案
+
+- **Label**：名词性短语，简洁。如 `Deployment Name` → `部署名称`、`Base URL` → `基础 URL`（URL 保留英文，见 §4）。
+- **Placeholder**：用"请输入 / 请选择 / 例如"引导的示例或提示。如 `Enter model ID` → `输入模型 ID`；`Select team` → `选择团队`。
+- **校验提示**：指出问题 + 期望，避免命令式指责。
+  - 示例：`This field is required` → `此项为必填`；`Key must be at least 8 characters` → `密钥至少需要 8 个字符`。
+- **可选/必填**：`Required` → `必填`；可选字段不要写"可选"二字堆满表单，仅在视觉区分或用 `（可选）` 后缀在 label 上。
+- **分段标题/说明**：`form.helper` 类说明文本可译，但保留关键英文专有名词（API、URL、SSO）。
+
+### 2.4 错误提示
+
+- **技术性错误**（后端返回、非 4xx 校验错误）：尽量提供"发生了什么 + 可做什么"两层。
+- **不可直翻后端消息**：后端英语错误原文**不翻译**（见 §4）。即使附带中文说明，也应保留原文以便排障。
+- 措辞平实。示例：
+  - `Unable to load models.` → `无法加载模型。`
+  - `Your session has expired.` → `会话已过期。`
+  - `Failed to create Virtual Key.` → `创建虚拟密钥失败。`
+  - `Insufficient permission.` → `权限不足。`（不写"您的权限不够"）
+- 避免把错误写成"出错了"这类无信息量提示；能带对象就带对象（`删除团队失败`）。
+
+### 2.5 空状态（Empty State）
+
+- 空状态 = 说明 + 一句引导（一个主导 CTA）。
+- 避免"这里空空如也"这种口语；用客观陈述 + 引导。
+  - 示例：`No Virtual Keys yet. Create one to get started.` → `暂无虚拟密钥。点击"新建虚拟密钥"开始使用。`
+  - `No usage data for the selected period.` → `所选时间段内暂无用量数据。`
+- 引导动词与真实按钮文字保持一致（"新建虚拟密钥"）。
+
+### 2.6 成功提示 / 通知（Toast）
+
+- 过去式主谓短句。如 `Virtual Key created.` → `虚拟密钥已创建。`、`Settings saved.` → `设置已保存。`
+- 需要引用对象名称/ID 时用插值：`Model "{{name}}" saved.` → `模型"{{name}}"已保存。`
+
+---
+
+## 3. 中文长度对布局的影响与处理
+
+中文单字约占英文一个字符 ~2 倍视觉宽度，但信息密度高，实际渲染宽度通常**更短或相当**。真正的风险是：
+
+1. 英文长复合词被较长的中文词组替换；
+2. 筛选器、表格列头、弹窗标题空间不足导致换行/溢出。
+
+### 3.1 导航（Leftnav / Navbar / 面包屑）
+
+- 菜单项普遍 ≤ 6 字（如 `Virtual Keys`→`虚拟密钥`、`Models + Endpoints`→`模型与端点`），通常放得下。
+- 侧边栏已具备 `truncate`（`flex-1 truncate`），中文过长时应保持单行截断，并补 `title` 展示全称。
+- 分组标签（AI GATEWAY 等）v1 也翻译；groupLabel 是配置常量，需随 `menuGroups` 一起 I18N 化，而非仅改渲染层。
+- 面包屑 section/title 同样取翻译，需与导航使用同一套 key，避免两处不一致。
+
+### 3.2 表格
+
+- 列头名词、数值列（用量/成本/花费用数字格式化，见 `V1_TRANSLATION_SCOPE.md` 插值注意事项）。
+- 表格单元格回退策略：**列头可换行，单元格优先截断 + `title` 全称**；避免单元格内文字撑爆列宽。
+- 数据列（模型 ID、团队名、时间戳）」多为数据，不翻译，按 §4 处理。
+
+### 3.3 弹窗 / 抽屉（Modal / Drawer）
+
+- 标题 ≤ 20 字；超长标题强制换行并提供 `line-clamp` 或在布置上预留两行。
+- 按钮组"取消/保存"不加长词缀，保持最短形式。
+- 弹窗内说明文本允许自然换行，但禁止水平溢出。
+
+### 3.4 全体回退策略（截断 / 换行 / 省略号）
+
+| 场景 | 策略 |
+|---|---|
+| 导航菜单单行 | `truncate`（省略号） + `title` 全称 |
+| 表格单元格 | 截断 + `title`；数值列右对齐 |
+| 弹窗标题 | 允许换行（白空间关键字 `[normal, pre-wrap]`），必要时 `line-clamp-2` |
+| 按钮 | 不换行；过长时缩短译名，不拼接 |
+| 标签/Badge（Beta、New） | 不翻译品牌徽标；`v{major.minor}` 保持 |
+
+---
+
+## 4. 不可翻译内容清单
+
+以下内容**明确不翻译**（作为资源值原样保留或直接放数据字段，不进翻译 key）。Agent 5/6 必须遵守，Review 时逐条核查：
+
+1. **模型名 / Model ID / Deployment 名 / Provider 名**：`gpt-4o`、`claude-3-5-sonnet`、`openai`、`bedrock` 等；用户自定义的 Deployment/模型名也是数据，不译。
+2. **API 字段名 / 参数名**：`key`、`model`、`spend`、`tpm_limit`、`rpm_limit`、`metadata`、`created_at`；接口返回的键与 JSON 结构不译。
+3. **请求/响应体、日志原文**：后端返回的原始日志、错误消息、堆栈（stack trace）、trace 内容保持原样。
+4. **代码示例与终端命令**：curl 片段、Python/JS 代码、API 请求示例不译；但代码**上方/下方的说明文字**可译。
+5. **URL、路径、文件名**：`https://docs.litellm.ai`、`/api/`、`config.yaml`、`.env` 等。
+6. **广泛公认的英文技术缩写**：API、URL、SSO、MCP、OAuth、REST、HTTP、SQL、ID、JSON、SDK。
+7. **品牌名**：LiteLLM、OpenAI、Anthropic、Virtual Key（作为产品专名，见下表备注）、Guardrails 的专有规则名。
+8. **数值、日期、货币、单位**：数字格式化走 i18n 的 number/date/currency，不手工拼翻译；`{{count}}` 由计数插值负责。
+9. **角色名 / 权限标识**：`admin`、`internal_user`、`team_admin` 等代码值保持英文（仅其人类可读显示名按术语表翻译）。
+10. **徽标与 Beta/New 标记**：`Beta`、`New` 徽标不译（视觉因子，保持英文原样）。
+
+> 原则：**翻译的是界面文案（UI string），不是数据（data string）与协议内容（protocol content）**。无法安全区分时，优先看它是否来自后端/用户数据 —— 是则不译。
+
+---
+
+## 5. zh-CN 计数与量词策略
+
+遵循 D9：**不建立形态复数分支**，用"计数插值 + 量词"。i18next 复数字符串里 `_one/_other` 仅用于英文；`zh-CN` 用一个字符串承载 `{{count}}` + 量词即可。
+
+量词选取规则：
+
+- 可数离散对象：`个`（模型、密钥、请求、团队、用户、条目）。
+- 键值/集合类（如导入项）：可用 `个` 或直接按对象数合身处理。
+- 时间/次数：`次`（请求次数、重试次数）。
+- 金额/用量单位化：不写量词，直接 `{{count}}` + 单位（`{{count}} 请求`、`{{count}} 个请求`，口语一致性以术语表为准）。
+- `0` 时量词仍正常（`0 个请求` 在中文是自然的，不需要单独复数分支）。
+
+### 5.1 具体示例
+
+| 场景 | EN（_one/_other） | ZH-CN（单字符串） |
+|---|---|---|
+| 请求数 | `{{count}} request` / `{{count}} requests` | `{{count}} 个请求` |
+| 选中模型 | `{{count}} model selected` / selected | `已选择 {{count}} 个模型` |
+| 待办项 | `{{count}} item` / items | `{{count}} 个条目` |
+| 无选中 | — | `已选择 0 个模型`（中文自然，无需分支） |
+| 重试 | `Retry ({{count}})` | `重试（{{count}} 次）` |
+
+### 5.2 测试要求
+
+计数测试至少覆盖 `count=0`、`count=1`、`count=2`（方案 §3.4）。对 `zh-CN` 断言渲染结果等于"插值 + 量词"形态（如 `1 个请求`、`2 个请求`），**不**断言存在 `_one/_other` 分支。
+
+---
+
+## 6. 英文原句 → 规范中文译文示例
+
+给开发 Agent 5/6 的参照样本（来自 v1 高频界面）。
+
+| # | EN（原句） | ZH-CN（规范译文） | 说明 |
+|---|---|---|---|
+| 1 | `Create new virtual key` | 新建虚拟密钥 | 动词+宾语，最短祈使形式 |
+| 2 | `No Virtual Keys found. Click "New Virtual Key" to create your first one.` | 暂无虚拟密钥。点击"新建虚拟密钥"创建你的第一个密钥。 | 空状态客观陈述 + 引导 CTA，CTA 文字与真实按钮一致 |
+| 3 | `This will permanently delete this model and cannot be undone.` | 此操作将永久删除该模型，且无法撤销。 | 机构条理清晰，动作对象明确 |
+| 4 | `You've spent $12.34 on Usage this month.` | 本月用量已花费 $12.34。 | 过去式主谓短句，接数值/货币（货币由 i18n 格式化） |
+| 5 | `Drop any model to see how it compares.` | 拖入任意模型查看对比结果。 | 祈使引导，无翻译腔 |
+| 6 | `Your changes have not been saved.` | 更改尚未保存。 | 客观陈述，不指责 |
+
+> 译名对照一律以 `GLOSSARY_EN_ZH.md` 为准，本示例中的词汇（虚拟密钥、用量、花费、拖入、对比）与术语表保持一致。
+
+---
+
+## 7. 可访问性（a11y）文案规范
+
+- 所有 `aria-label`、`title`、`alt`、placeholder 中的用户可见文案**同样翻译**（方案 §5.5），与可见文本用同一 key。
+  - 例：当前 `aria-label={collapsed ? "Expand sidebar" : "Collapse sidebar"}` → `展开侧边栏` / `收起侧边栏`。
+- 语言切换器自身提供 `aria-label`（见 `LANGUAGE_SWITCHER_SPEC.md`）。
+- 图标按钮（无可见文字）必须本地化 `aria-label`；纯装饰图标保持 `aria-hidden`。
+- 保留英文专有名词的缩写不影响屏幕阅读器核心语义。
+
+---
+
+## 8. 对开发 Agent 的强制要求（Agent 5/6）
+
+1. **只翻 UI 文案**，不翻 §4 清单内容（模型名、API 字段、日志、代码、URL、缩写、品牌）。
+2. **key 与字典一致性**：中英文 key 集合必须一致；缺 zh-CN 时回退 en，不回退失败显示 key。
+3. **写 key 不写句子到代码**：用语义 key（`navigation:item.virtualKeys`），不把英文句子当 key。
+4. `<Trans>` 用于含链接/强调/嵌套，`t()` 用于纯字符串；使用 `<Trans>` 前确保资源就绪（ready 门禁，避免首帧闪 key）。
+5. **同一译名贯穿全局**：按钮、空状态、确认框、Toast 对同一动作/对象用词必须一致（对照术语表）。
+6. **数值/日期/货币用 i18n 格式化**，不硬编码。
+7. **翻译 a11y 文案**（aria-label/title/placeholder）。
+8. **不改变业务行为**：翻译不改路由、不改校验逻辑、不改提交逻辑，仅替换展示文案。
+9. 交付时在 `V1_SCOPE_MANIFEST.md`（Agent 0 维护）对应行填 EN/ZH-CN 文案盘点；译名异常情况上报 Agent 2 复核。
+
+---
+
+## 9. 术语表引用
+
+术语定义与单一词条见 `GLOSSARY_EN_ZH.md`。若本规范内个别短语与术语表冲突，以 `GLOSSARY_EN_ZH.md` 为准，并提请 Agent 2 修订。

docs/i18n/MASTER_PLAN.md

@@ -0,0 +1,30 @@
+# LiteLLM Dashboard 中英文国际化 — MASTER_PLAN
+
+> 总控：Agent 0（`i18n-lead-reviewer`） · 由当前主智能体承担
+> 基线：`I18N_MULTI_AGENT_PLAN.md` v1.4（评审通过，可执行）
+> 目标：Dashboard 前端 UI 支持 `en` / `zh-CN`，导航、登录、Models、API Keys、Usage、Cost、Budgets 优先中文化。
+
+## 波次总览
+
+| 波次 | 内容 | 涉及角色 | 门禁 |
+|---|---|---|---|
+| Wave 0 | 基线评审 + 并行设计 | A0 + A1/A2/A3 | G0 |
+| Wave 1 | 平台能力与测试基础 | A0 + A4/A5(只读)/A7 | G1 |
+| Wave 2 | 第一批功能并行开发 | A0 + A5/A6/A7 | G2 |
+| Wave 3 | 第二批功能并行开发 | A0 + A6A/A6B/A7 | G3 |
+| Wave 4A/4B | 集成验收 + 定向缺陷修复 | A0 + A2/A7/A8(及开发 Owner) | G4 |
+
+## 并发约束
+同刻最多 4 个智能体（1 总控 Agent 0 + 最多 3 执行子代理）。子代理按波次由 Agent 0 拉起，完成即回收。
+
+## 当前状态
+（由 Agent 0 在每波次更新）
+
+- [ ] Wave 0 进行中
+- [ ] Wave 1 待开始
+- [ ] Wave 2 待开始
+- [ ] Wave 3 待开始
+- [ ] Wave 4 待开始
+
+## 完成定义
+见 `I18N_MULTI_AGENT_PLAN.md` §11（v1 完成定义 15 条）。

docs/i18n/POC_REPORT.md

@@ -0,0 +1,100 @@
+# LiteLLM Dashboard i18n — PoC 验证清单与执行步骤（POC_REPORT）
+
+> 角色：Agent 1（`i18n-architect`）编写 PoC 必验项；Wave 1 的 Agent 4（平台）与 Agent 7（测试）照此执行并把证据回填到「结果 / 证据」栏。
+> 约定：PoC-* 为「必验项」，每项都必须给出**方法**、**预期证据**、**结果**（通过/失败/未执行）。
+> 本机（Agent 1 仅只读）已就地验证的项，标记 **「本机已验证」**；其余标记 **「待执行」**（执行者为 A4/A7）。
+
+> 目标：在改动最少的前提下，对 `I18N_TECH_DESIGN.md` 的**关键设计假设**给出可复现证据，支撑 G1 门禁（ADR-i18n-01/03/04/05 转 Accepted）。
+> 前置：Wave 1 平台基线由 A4 建立（`src/i18n/**` + `src/locales` 骨架 + 依赖写入，遵循 D12/FILE_OWNERSHIP）。
+
+---
+
+## 0. 环境前提（A4 先落实）
+
+- 依赖：`i18next@^26.4.2` + `react-i18next@^17.0.13`（写入后运行 `npm ci` 于独立 worktree，禁止并行锁分叉——D12/v1.4）。
+- `next.config.mjs`：**不改**（静态导出已满足）。
+- 仅改动 `src/i18n/**`、`src/locales/**`、`src/app/layout.tsx`（挂 Provider）、语言切换器。
+
+---
+
+## PoC-1：静态导出构建成功 && i18next 依赖可解析（G1 前置）
+
+- **方法**：A4 在平台 worktree `npm run build`（`output:"export"`）。检查：构建无因引入 i18next 产生的解析/打包错误；`out/` 正常产出；`turbopack` 能打包 json 资源。
+- **预期证据**：`next build` 成功，`out/` 目录生成，无「Cannot resolve i18next/react-i18next」、无 static-export 舞台报错；`npm ls i18next react-i18next` 无 peer 冲突。
+- **结果**：【待执行】
+
+## PoC-2：首屏策略（就绪门禁 + `<html lang>` 同步）行为
+
+- **方法**：默认浏览器语言 en：加载页面，在首帧与 JS 就绪后截图/断言。
+  1. en 用户：首帧即为中文 UI 不存在（应显示英文 UI），`<html lang="en">` 保持。
+  2. zh-CN 偏好用户（预置 `dashboard.locale=zh-CN` 再刷新）：JS 就绪前不渲染业务 `t()` 内容（就绪态/空），就绪后一次性渲染中文，且 `document.documentElement.lang === 'zh-CN'`。
+- **预期证据**：截图对比 + DOM 断言：①en 首帧无 key/英文句闪烁；②zh 就绪前无业务文案、就绪后 `lang` 正确；③测量就绪门禁额外延时（performance 日志）记录数值，供评审接受性判断。
+- **结果**：【待执行】
+
+## PoC-3：`t()` / `<Trans>` 首帧不暴露原始 key（资源就绪门禁）
+
+- **方法**：在导航/登录样面的一个组件用 `t('common:title')` 与一个 `<Trans>`。用 Playwright 在**首帧**（未就绪）与就绪后采样 DOM 文本。
+- **预期证据**：首帧 DOM 中**不含** `common:title`、不含未翻译英文句子（即不以 key=原文）；就绪后显示译文。如有 `returnNull`，首帧对应节点为空而非显示 key。
+- **结果**：【待执行】
+
+## PoC-4：缺 key 英文回退（D2）
+
+- **方法**：在 zh-CN 资源中删掉某个 en 有的 key（临时），UI 切 zh-CN，观察该字符串。
+- **预期证据**：该串回退英文（`fallbackLng:'en'`），**不**崩、不显示 key、控制台（dev）有 missingKey warning。
+- **结果**：【待执行】
+
+## PoC-5：刷新后语言偏好保留（D6/D5）
+
+- **方法**：切 zh-CN → 刷新 → 断言仍 zh-CN；清空 cookie 但留 localStorage → 刷新 → 仍 zh-CN（双层读取）；两者都清 → 回退浏览器语言/en。
+- **预期证据**：各分支刷新后语言正确；`dashboard.locale` cookie 存在且 `SameSite=Lax`。
+- **结果**：【待执行】
+
+## PoC-6：英文为首帧默认、无偏好时按浏览器语言（D5/D2）
+
+- **方法**：无任何偏好 cookie/localStorage；浏览器 `navigator.language` 分别设 en、zh-CN、zh、zh-Hans、fr。
+- **预期证据**：en→英文；zh/zh-Hans→zh-CN；fr（不支持）→英文。首帧英文合法，无闪烁。
+- **结果**：【待执行】
+
+## PoC-7：整页跳转语言恢复（Login/SSO/MCP OAuth 回跳，D10）
+
+- **方法**：在 `(dashboard)` 中切 zh-CN → 触发到 `/login` 或模拟 SSO/OAuth 全页跳转（改变 URL/全量 reload）→ 返回原页。
+- **预期证据**：回跳后仍 zh-CN（从同源 cookie 恢复），`<html lang>` 一致，无 key 闪烁；未登录直登场景与 OAuth 回跳分别覆盖。
+- **结果**：【待执行】
+
+## PoC-8：中文量词/计数（D9）在真实组件表现
+
+- **方法**：在带 `{{count}}` 的计数展示（如 usage 表格）切 zh-CN，覆盖 count=0/1/2。
+- **预期证据**：输出如「0 个 / 1 个 / 2 个」，无英文复数 s；量词与数为「数+量」顺序正确出现。
+- **结果**：【待执行】
+
+## PoC-9：toast / 构建产物不含未翻译硬编码（回归）
+
+- **方法**：扫描构建后产物与关键页面文本，确认没有「key 串」残留为可见 UI 文本。
+- **预期证据**：`grep` 产物无 `\w+:\w+\.` 形式的 key 作为文本暴露；关键页面无英文句被用户看到（除 `title`/meta 英文外）。
+- **结果**：【待执行】
+
+---
+
+## 本机已验证项（Agent 1，只读，2026-09-09）
+
+| # | 项 | 验证方式 | 结果 |
+|---|---|---|---|
+| 1 | `react-i18next@17.0.13` 兼容 React 19 / TS 5 | `npm view react-i18next peerDependencies` → `react>=16.8.0`, `i18next>=26.2.0`, `ts ^5\|\|^6\|\|^7`；项目 React 19.2.8 / TS 5.9.3 满足 | 通过 |
+| 2 | `i18next@26.4.2` 无冲突 peer | `npm view i18next@latest peerDependencies` → 仅 `typescript` | 通过 |
+| 3 | 根 Provider 链结构 | 读 `src/app/layout.tsx`：`ThemeProvider→NuqsAdapter→ReactQueryProvider→AuthProvider`；`<html lang="en" suppressHydrationWarning>`；metadata 英文 | 确认 |
+| 4 | `src/i18n` / `src/locales` 当前不存在（基线干净） | `ls` | 确认（Wave0 从零建） |
+| 5 | 路由组 layout 分布 | 根 / `(dashboard)` / `chat` / `connect` 各有一 `layout.tsx`；`(dashboard)` 为 use client 且另含 SidebarProvider/ThemeContext/PluginModeContext | 确认（接缝见设计 §8） |
+| 6 | 后端无 `UI settings.language` | `UISettings` 白名单 `ALLOWED_UI_SETTINGS_FIELDS` 不含 `language`；`/get/ui_settings` 由 `LiteLLM_UISettings` 表支撑 | 确认（→ADR-i18n-07） |
+| 7 | next export 配置 | `next.config.mjs`: `output:"export"`, `trailingSlash:true`, `images.unoptimized` | 确认（静态导出约束成立） |
+
+## 待执行（Wave 1 A4/A7 回填）
+
+- PoC-1 .. PoC-9 均【待执行】；其中 PoC-1（构建+依赖）、PoC-2/3（首屏与门禁）、PoC-5（刷新）、PoC-7（跳转恢复）为 **G1 关键门禁**，优先完成并回填证据文件（证据文件命名遵从 v1.4 §11 具名证据约定，由 Agent 3/7 落地）。
+
+---
+
+## 建议的 PoC 测试层级归属（供 Agent 3 细化）
+
+- 单测（unit）：`localePreferences.ts`（D5 优先级）、`detectLocale.ts`（`zh`→`zh-CN`）、`i18n.ts` 实例化。
+- 集成：`I18nProvider` 就绪门禁渲染（PoC-3）、Layout 挂 Provider 后 `useTranslation` 可用。
+- E2E（`tests/e2e/ui/`，Playwright 对 live proxy）：PoC-2/5/6/7（首屏、刷新、浏览器语言、整页回跳）。

docs/i18n/REGRESSION_MATRIX.md

@@ -0,0 +1,58 @@
+# i18n 回归测试矩阵（REGRESSION_MATRIX.md）
+
+> 角色：Agent 3 `qa-architect`；执行：Agent 7 `i18n-qa`（Wave 4A 完整回归）
+> 依据：`I18N_MULTI_AGENT_PLAN.md` §11 完成定义、§10 测试重点；`TEST_CASES.md`
+> 用法：按"页面 × 关键行为"逐格勾选。行为列引用 TC 编号；页面以 v1 范围为准。每格填：`✅ 通过 / ❌ 失败(#缺陷) / ➖ 不适用 / (m) 人工`。
+
+## 行为列（横轴）编号
+
+| 列 | 行为 | 主要 TC | 层级 |
+|---|---|---|---|
+| B1 | 默认语言 en | TC-01/02 | e2e/unit |
+| B2 | 切换即时生效 + `<html lang>` | TC-03/08 | e2e/component |
+| B3 | 刷新保持 | TC-04/05 | e2e/unit |
+| B4 | 缺 key 回退英文、不显示原始 key | TC-06/07 | e2e/component |
+| B5 | 动态数量/日期/数字/货币本地化（含 count=0/1/2） | TC-09~13 | unit |
+| B6 | 模型名/API 字段/日志/代码示例不误翻 | TC-20/21 | integration |
+| B7 | a11y 文案本地化（aria-label/title/placeholder/error） | TC-23 | component/integration |
+| B8 | 中文布局不溢出/截断/遮挡 | TC-24 | integration/e2e+(m) |
+| B9 | 切换语言不清空表单/不触发异常请求 | TC-14/15 | integration/e2e |
+| B10 | 整页跳转（Login/SSO/MCP OAuth）回跳语言保持 | TC-16~19 | e2e |
+
+## 矩阵（页面 × 行为）
+
+| 页面/区域 | Owner | B1 | B2 | B3 | B4 | B5 | B6 | B7 | B8 | B9 | B10 | Review |
+|---|---|---|---|---|---|---|---|---|---|---|---|---|
+| Navbar | Agent 5 | | | | | | | | | | ➖ | |
+| Leftnav | Agent 5 | | | | | | | | | | ➖ | |
+| 用户菜单 / 全局壳层 | Agent 5 | | | | | | | | | | ➖ | |
+| 语言切换器 | Agent 5 | | | | | | | | | ➖ | | |
+| Login | Agent 5 | | | | | | | | | | | |
+| Onboarding | Agent 5 | | | | | | | | | | | |
+| Connect | Agent 5 | | | | | | | | | | | |
+| MCP OAuth | Agent 5 | | | | | | | | | | | |
+| Models and Endpoints | Agent 6 | | | | | | | | | | | |
+| API Keys | Agent 6 | | | | | | | | | | | |
+| Usage | Agent 6A | | | | | | | | | | | |
+| Cost Tracking | Agent 6A | | | | | | | | | | | |
+| Budgets | Agent 6B | | | | | | | | | | | |
+| 全局：构建期 `<title>`/meta 英文 | Agent 4/8 | | | | | ➖ | | | | ➖ | ➖ | |
+
+## 平台层回归（不绑定单页面）
+
+| 项目 | 说明 | TC | 结果 |
+|---|---|---|---|
+| 默认语言 en（无偏好） | 全站 | TC-01 | |
+| `<html lang>` 一致 | 全局 | TC-08 | |
+| 刷新保持 | 全局 | TC-04 | |
+| 缺 key 英文回退 | 全局 | TC-06 | |
+| 不显示原始 key（首帧/全程） | 全局 | TC-07/26 | |
+| 静态产物 key 泄漏 / `<title>` 英文 | `out/` | TC-22/26 | |
+| en/zh key 集合一致 | 全部 namespace | TC-25 | |
+| 硬编码扫描报告 | 源码 | T-03 | |
+
+## 门禁映射
+
+- 本矩阵在 **Wave 4A** 全量执行（Agent 7 完成 + Agent 8 汇总 + Agent 2 体验复核 + Agent 0 终审）。
+- 对应完成定义（§11）：支持双语言(1)、切换即时+刷新保持(2)、v1 页面中文化(3)、回退不露 key(4)、中文无严重截断重叠(5)、切换不清表单(6)、整页跳转保持(7)、`<title>`/meta 英文(8)、模型名/API 不误翻(9)、相关测试通过(10)、lint/format/build(11)。
+- 任何 `❌` 须挂缺陷进 `TASK_BOARD.md`，P0/P1 清零后才满足 G4。

docs/i18n/TASK_BOARD.md

@@ -0,0 +1,57 @@
+# LiteLLM Dashboard i18n — TASK_BOARD（多智能体进展看板）
+
+> 维护者：Agent 0。**每启动/交付/Review 一个 Agent 即更新本表**。这是你查看"谁在工作、进展到哪"的单点真相。
+> 状态取值：待命 / 进行中 / 待 Review / 已完成 / 被阻塞
+
+## Wave 0 — 并行设计（G0 门禁前）
+
+| Agent | 名称 | 状态 | worktree/分支 | 交付物 | 最后更新 |
+|---|---|---|---|---|---|
+| A1 | i18n-architect | **已完成 ✅（G0 Review 通过）** | （纯设计） | I18N_TECH_DESIGN / I18N_ADR / POC_REPORT / TECH_RISKS | 2026-09-09 G0 |
+| A2 | localization-designer | **已完成 ✅（G0 Review 通过）** | （纯设计） | LOCALIZATION_SPEC / GLOSSARY_EN_ZH(63条) / LANGUAGE_SWITCHER_SPEC / V1_TRANSLATION_SCOPE / LOCALE_NAVIGATION_BEHAVIOR | 2026-09-09 G0 |
+| A3 | qa-architect | **已完成 ✅（G0 Review 通过）** | （纯设计） | I18N_TEST_PLAN / TEST_CASES(26) / TEST_TOOLS / REGRESSION_MATRIX | 2026-09-09 G0 |
+
+**G0 门禁结论（Agent 0，2026-09-09）：APPROVED**
+- 首屏策略已选定「就绪门禁 + `<html lang>` 同步」（ADR-04，非"再评估"）。
+- 后端无 `UI settings.language`（ADR-07 Accepted）。
+- 构建期 `<title>`/meta 保持英文边界已记录（ADR-06 Accepted）。
+- 整页跳转语言保持规则已写入本地化与测试方案（LOCALE_NAVIGATION_BEHAVIOR + TEST_CASES TC-16..18）。
+- E2E 基建缺口已定：选 **a（Wave 1 补齐 Playwright）**，见 DECISIONS P3/P4。
+- **G0 Review 发现 1 个需修正点（P5）**：语言偏好存储键名跨文档不一致（`dashboard.locale` vs `litellm.locale`）。**已定统一为 `litellm.locale`**，由 A4 以单一常量实现，A5/6 不直接操作存储。
+- G0 Review 确认 POC_REPORT 9 项必验项已具备（待 Wave 1 A4/A7 回填证据）。
+
+## Wave 1 — 平台能力与测试基础
+
+| Agent | 名称 | 状态 | worktree/分支 | 交付物 | 最后更新 |
+|---|---|---|---|---|---|
+| A4 | i18n-platform-developer | 待命 | i18n/w1-agent4-platform | src/i18n/** 平台代码 + PLATFORM_VALIDATION_REPORT | - |
+| A5 | i18n-shell-auth-developer | 待命（Wave1 仅只读盘点） | — | key 拟定清单（不写码） | - |
+| A7 | i18n-qa | 待命 | i18n/w1-agent7-qa | 平台测试 + key 一致性工具 | - |
+
+## Wave 2 — 第一批功能
+
+| Agent | 名称 | 状态 | worktree/分支 | 交付物 | 最后更新 |
+|---|---|---|---|---|---|
+| A5 | i18n-shell-auth-developer | 待命 | i18n/w2-agent5-shell | 壳层 + common/navigation/auth namespace | - |
+| A6 | i18n-feature-developer | 待命 | i18n/w2-agent6-models | Models + API Keys | - |
+| A7 | i18n-qa | 待命 | i18n/w2-agent7-qa | 持续测试 | - |
+
+## Wave 3 — 第二批功能
+
+| Agent | 名称 | 状态 | worktree/分支 | 交付物 | 最后更新 |
+|---|---|---|---|---|---|
+| A6A | i18n-feature-developer (Usage/Cost) | 待命 | i18n/w3-agent6a-usage | Usage + Cost Tracking | - |
+| A6B | i18n-feature-developer (Budgets) | 待命 | i18n/w3-agent6b-budgets | Budgets | - |
+| A7 | i18n-qa | 待命 | i18n/w3-agent7-qa | 回归 | - |
+
+## Wave 4 — 集成验收
+
+| Agent | 名称 | 状态 | 交付物 | 最后更新 |
+|---|---|---|---|---|
+| A2 | localization-designer | 待命 | 术语/中文体验复核 | - |
+| A7 | i18n-qa | 待命 | 完整回归 + 质量报告 | - |
+| A8 | i18n-integration-release | 待命 | 发布/回滚清单 | - |
+
+## 缺陷队列
+（Wave 4B 按 P0 → P1 → 阻塞门禁 P2 → 其他 P2 排序）
+（空）

docs/i18n/TECH_RISKS.md

@@ -0,0 +1,109 @@
+# LiteLLM Dashboard i18n — 技术风险清单（TECH_RISKS）
+
+> 角色：Agent 1（`i18n-architect`）· Wave 0
+> 编号 R1..Rn。每条含：风险 / 影响 / 缓解 / Owner。Owner 为「最需要跟踪/缓解」的角色，不一定是唯一。
+> 关联：`I18N_TECH_DESIGN.md`、`I18N_ADR.md`、`POC_REPORT.md`。
+
+---
+
+## R1：静态导出下首屏语言闪烁 / 错误语言闪现
+
+- **风险**：切 zh-CN 用户首帧可能短暂显示英文或暴露 key，体验倒退。D7 要求不得停留在「再评估」。
+- **影响**：高（首屏是 G0/G1 门禁项；直接违背 §3.1）。
+- **缓解**：已选定「语言就绪门禁 + 挂载后同步 `<html lang>`」（ADR-i18n-04）；就绪前不渲染业务 `t()`/`<Trans>`（ADR-i18n-03）。PoC-2/3 验证并量化门禁延时。
+- **Owner**：A4（实现）→ A7（验证）。
+
+## R2：`react-i18next` / `i18next` 与 React 19 / Next 16 的运行时兼容性未实测
+
+- **风险**：`npm view` peer 通过，但实际打包（turbopack/next export）与 React 19 可能有边界问题（如 `useSyncExternalStore`、HMR）。
+- **影响**：中（构建失败或运行时异常会阻断 Wave 1）。
+- **缓解**：PoC-1 先做最小依赖安装 + `next build`；锁定 `^17`/`^26` 稳定大版本；若发现问题回退 17/26 的补丁小版本并记录。
+- **Owner**：A4（先做）→ A7（复验）。
+
+## R3：`<Trans>` 因资源未就绪而瞬态暴露占位/key
+
+- **风险**：若个别组件绕开统一门禁，`<Trans>` 可能先渲染占位符再替换。
+- **影响**：中高（违背 §3.1，且 `<Trans>` 难以用简单 `t()` 兜底）。
+- **缓解**：统一顶层门禁覆盖全局子树；组件 `ready` 兜底；CI 键集合一致性检查（R9）+ 代码评审拦截绕过。
+- **Owner**：A4（平台）→ A5/A6（使用）→ A7（回归）。
+
+## R4：语言偏好 cookie/localStorage 不一致或跨跳转丢失
+
+- **风险**：cookie 与 localStorage 双写可能不一致；`SameSite` 过严导致 SSO/整页跳转回带失败，或过宽带来安全面。
+- **影响**：中（刷新/回跳语言恢复失败，D10 不满足）。
+- **缓解**：以显式写入顺序为准的收敛规则（ADR-i18n-05）；`SameSite=Lax` + 生产 `Secure`；PoC-5/7 覆盖 cookie 清空/localStorage 留存、整页回跳各分支。
+- **Owner**：A4 → A7。
+
+## R5：依赖文件被多 Agent 并行写坏（锁分叉）
+
+- **风险**：`package.json`/lock 在多 worktree 并行 `npm install/ci` 产生分叉，G1 集成冲突。
+- **影响**：高（阻塞集成、浪费波次）。
+- **缓解**：D12 单一写入者（默认仅 A4）；下游从 G1 基线 `npm ci` 且不写 lock；v1.4 变更摘要已固化。
+- **Owner**：A4（执行）→ A0（review）。
+
+## R6：功能 Agent 与平台共享单点（`src/i18n/**`、注册表、公共 JSON）写冲突
+
+- **风险**：多人同时改初始化代码/注册表/大 JSON。
+- **影响**：中（合并冲突、注册表被破坏导致类型/加载异常）。
+- **缓解**：FILE_OWNERSHIP 规则：`src/i18n/**` 与骨架归 A4 永久独占；新增 namespace 走 A0 派单由 A4 注册；功能 Agent 只写自己 namespace。
+- **Owner**：A0（调度）→ A4（执行）。
+
+## R7：en/zh 字典键集合漂移（缺 key/多 key）
+
+- **风险**：中文更新新增 key 但 en 未同步（或反之），导致运行期 missingKey 回退/多出 key。
+- **影响**：中（D2 要求 en 为真源、zh 缺 key 回退；键集合须一致 §3.4）。
+- **缓解**：CI 增加「en vs zh-CN 键集合 diff」校验（可在 `test:types` 或独立脚本，纳入 Agent 7 质量门禁）；`CustomTypeOptions` 类型约束 + 开发模式 missingKey warning。
+- **Owner**：A7（CI/校验）→ A4（类型）→ 各功能 Agent（补 key）。
+
+## R8：cookie 安全与隐私（`SameSite`、`Secure`、XSS 可读）
+
+- **风险**：语言非秘密，但 cookie 可被 XSS 读取；`SameSite=None` 若被误用扩大攻击面。
+- **影响**：低-中（隐私面小；但需遵守 CLAUDE.md「勿把 token 放 localStorage」精神，语言偏好非敏感）。
+- **缓解**：语言偏好非敏感可放心；cookie `SameSite=Lax; path=/;`，生产 `Secure`；绝不用此 cookie 存令牌；仅当 SSO 第三方域确需带 cookie 时，再评估 `None` 并单独评审。
+- **Owner**：A4。
+
+## R9：硬编码文案漏网（中文环境下仍有英文句/key 可见）
+
+- **风险**：1400+ TSX，批量改造难免遗漏；产物残留 key 串或英文句。
+- **影响**：中（本地化不完整、观感差）。
+- **缓解**：扫描工具只报告候选（不改写，§3.4）；PoC-9 对产物 grep 残留；纳入 v1 完成定义与 A7 回归；模块按 high-traffic 优先级（导航/登录/Models/API Keys/Usage/Cost/Budgets）。
+- **Owner**：A5/A6（改造）→ A7（扫描/回归）。
+
+## R10：静态导出 + 多语言无 SEO，`<title>`/meta 恒为英文
+
+- **风险**：搜索引擎与分享卡片恒为英文，非本地化。
+- **影响**：低（D8 明确 v1 不做多语言 SEO）。
+- **缓解**：接受为 v1 边界；文档记录未来可引入 per-locale 静态 `title`（ADR-i18n-06 后果）。
+- **Owner**：A0（确认范围）。
+
+## R11：管理员全局语言设置未来引入（P1）可能改变优先级语义
+
+- **风险**：后端未来新增 `UI settings.language` 字段，需决定「覆盖用户选择」语义，否则现有优先级迁移需返工。
+- **影响**：低（v1 无此字段，ADR-i18n-07 已封闭）；中（若 v1.1 临时加入则会波及优先级链）。
+- **缓解**：预留 L5 判定位（I18N_TECH_DESIGN §3.2），把「用户显式」与「探测」分开存储，便于未来叠加管理员全局层而不混淆。
+- **Owner**：A1（设计预留）→ A0（接产品决策）。
+
+## R12：中文文本在窄布局/表格溢出（文本长度不同导致 UI 破坏）
+
+- **风险**：中文普遍比英文紧凑，但长译句或 `{{count}}` 拼接可能导致表格/按钮溢出或换行异常。
+- **影响**：中（布局回归）。
+- **缓解**：Wave 1 起在 Login/Navbar/表格样例做中英文并排截图比对；纳入 Agent 3 测试与 A7 回归；`whitespace-nowrap`/截断类妥善处理。
+- **Owner**：A6（功能页）→ A8（集成验收）。
+
+## R13：`.json` 资源体积随 namespace 增长、首包加大
+
+- **风险**：所有 locale 静态打在一起可能增大 bundle；`turbopack` 打包 json 的方式需确认。
+- **影响**：低-中（Dashboard 体量下影响有限；但静态导出无 CDN 分片语言包，加载即全量）。
+- **缓解**：PoC-1 检查产物 json 是否被正确 tree-shake/分 chunk；v1 语言仅 2 个，体积可控；若未来多语言再评估代码分割。
+- **Owner**：A4 → A8。
+
+---
+
+## 风险热力（供 A0 优先级参考）
+
+| 等级 | 风险 |
+|---|---|
+| 高 | R1（首屏）、R5（锁分叉） |
+| 中高 | R3（`<Trans>`）、R9（硬编码遗漏） |
+| 中 | R2、R4、R6、R7、R12 |
+| 低 | R8、R10、R11、R13 |

docs/i18n/TEST_CASES.md

@@ -0,0 +1,257 @@
+# i18n 测试用例（TEST_CASES.md）
+
+> 角色：Agent 3 `qa-architect`
+> 依据：`I18N_MULTI_AGENT_PLAN.md` §10 测试重点、§11 完成定义；`I18N_TEST_PLAN.md`
+> 实施：Agent 7 `i18n-qa`
+> 命名：层用 `unit`(node `*.test.ts`) / `component`(`*.test.tsx`) / `integration`(`*.integration.test.tsx`) / `e2e`(Playwright `tests/e2e/ui/`)；`*` = 自动化，`(m)` = 人工辅助
+
+每个用例字段：编号、层级、描述、前置、步骤、断言、自动化与否。
+
+---
+
+## A. 语言初始化与持久化
+
+### TC-01 默认语言为英文
+- 层级：`e2e`
+- 描述：首次访问（无任何语言偏好）界面与 `<html lang>` 均为英文 `en`。
+- 前置：清空语言偏好存储（cookie/localStorage）、浏览器无中文偏好；静态导出 `out/` 已构建。
+- 步骤：1. 无偏好打开根路由。2. 读取 `<html lang>` 与可见文案。
+- 断言：`<html lang="en">`；界面文案为英文；不出现原始 key。
+- 自动化：*
+
+### TC-02 默认语言英文（逻辑合并，无偏好）
+- 层级：`unit`（`*.test.ts`）
+- 描述：语言选择合并函数在"无偏好 + 浏览器英文"时归 `en`。
+- 前置：逻辑纯函数已抽出。
+- 步骤：调用合并函数，输入空偏好与 "en"。
+- 断言：返回 `"en"`。
+- 自动化：*
+
+### TC-03 切换语言即时生效
+- 层级：`component` + `e2e`
+- 描述：切换 `en → zh-CN`，页面文本与 `<html lang>` 即时更新，无需刷新。
+- 前置：语言切换器与页面在 Provider 下渲染；资源就绪。
+- 步骤：component：渲染带 `I18nProvider`（可 stub 网络）的页面 → 点击切换器选中文 → 断言关键文本与 lang。e2e：真实浏览器同操作。
+- 断言：Navbar/Leftnav 等中文化文本出现；`<html lang="zh-CN">`；无原始 key、无刷新。
+- 自动化：*
+
+### TC-04 刷新后语言保持
+- 层级：`e2e`
+- 描述：切到中文后刷新页面，语言仍为中文。
+- 前置：偏好写入介质（cookie/localStorage，依架构决策）。
+- 步骤：1. 切成中文。2. `page.reload()`。3. 读 `<html lang>` 与可见文本。
+- 断言：`<html lang="zh-CN">`，界面仍为中文。
+- 自动化：*
+
+### TC-05 语言偏好在同源介质持久化（单元）
+- 层级：`unit`
+- 描述：偏好读写到可注入 storage/cookie 抽象，序列化往返一致。
+- 前置：偏好读写逻辑独立可测。
+- 步骤：写入 `"zh-CN"` → 重新读取。
+- 断言：读回 `"zh-CN"`；存储键稳定、无多余数据。
+- 自动化：*
+
+## B. 回退与 key 遮蔽
+
+### TC-06 缺失中文时回退英文
+- 层级：`component` + `e2e`
+- 描述：zh 字典缺某 key 时，渲染英文而非原始 key。
+- 前置：中文态 + 注入缺失 key 的字典子集（或 e2e 用构建产物中的真实缺口做抽样）。
+- 步骤：切换到中文，访问缺失 key 所属文案。
+- 断言：显示对应英文译文；**不**显示 `ns:key` 原始 key。
+- 自动化：*
+
+### TC-07 不显示原始翻译 key（首帧/全程）
+- 层级：`e2e`（首帧）+ `component`（全程）
+- 描述：无论资源加载时序，任何时刻帧内都不泄漏原始 key 文本（`ns:...`）。
+- 前置：资源同步就绪或就绪门禁生效；`<Trans>`/`t()` 就绪后渲染。
+- 步骤：e2e 首次导航截图 + 快速截图序列，扫描页面可见文本。
+- 断言：页面文本不包含形如 `namespace:key` 或 `key.xxx` 的原始 key 串。
+- 自动化：*
+
+### TC-08 `<html lang>` 与当前语言一致
+- 层级：`component` + `e2e`
+- 描述：`<html lang>` 始终等于当前语言（en/zh-CN）。
+- 前置：`<html lang>` 客户端同步已实现。
+- 步骤：分别在 en、zh、切换后、刷新后读取 `document.documentElement.lang`。
+- 断言：en→`"en"`，zh→`"zh-CN"`；切换与刷新后保持一致。
+- 自动化：*
+
+## C. 动态数量 / 日期 / 数字 / 货币
+
+### TC-09 中文数量插值 count=0 / 1 / 2（D9）
+- 层级：`unit`（核心）+ `component`（渲染）
+- 描述：中文用计数插值与量词：`0 个`、`1 个`、`2 个`/`{{count}} 个`；不机械复制英文复数分支。
+- 前置：量词插值组件/函数已实现，`{{count}}` 语义。
+- 步骤：依次以 `count=0`、`count=1`、`count=2` 渲染/调用，中文态。
+- 断言：输出分别为 `0 个请求`、`1 个请求`、`2 个请求`（按术语表措辞）；无英文 one/other 分支语义。
+- 自动化：*
+
+### TC-10 英文数量复数
+- 层级：`unit`
+- 描述：英文按 i18next/CLDR `one`/`other` 处理：`1 request` vs `2 requests`。
+- 前置：英文资源含复数分支。
+- 步骤：`count=1`、`count=2` 渲染。
+- 断言：`1 request`、`2 requests`。
+- 自动化：*
+
+### TC-11 日期本地化
+- 层级：`unit`
+- 描述：日期按当前语言格式化（e.g. `Sep 9, 2026` vs 中文格式），时区/时刻固定。
+- 前置：固定时间源、固定 locale；格式化逻辑独立。
+- 步骤：同一时间戳在 en、zh 下格式化。
+- 断言：格式随 locale 变化且正确；无 `NaN`/原始时间戳泄漏。
+- 自动化：*
+
+### TC-12 数字本地化
+- 层级：`unit`
+- 描述：千分位/小数点随 locale（en `1,234.5` vs zh 千分位），金额单位不重复。
+- 前置：格式化函数独立。
+- 步骤：en、zh 各格式化同值。
+- 断言：分组/小数正确；不出现双重符号或单位。
+- 自动化：*
+
+### TC-13 货币本地化
+- 层级：`unit`
+- 描述：货币符号与金额按 context/locale 呈现（成本/预算页）。
+- 前置：货币格式化上下文确定（币种来自数据）。
+- 步骤：en、zh 各格式化同金额。
+- 断言：符号与格式正确；数据币种不被误翻。
+- 自动化：*
+
+## D. 表单与交互状态
+
+### TC-14 切换语言不清空表单
+- 层级：`integration`
+- 描述：填写表单字段后切换语言，字段值与未提交状态保持，不触发无关请求。
+- 前置：集成树（真实组件 + Provider），网络边界 stub。
+- 步骤：填写 → 切语言 → 断言字段值与 `<form>` 状态保持。
+- 断言：输入值仍在、选择/勾选仍在；无提交/异常请求触发；无原始 key。
+- 自动化：*
+
+### TC-15 切换语言不清空表单（E2E 抽查）
+- 层级：`e2e`
+- 描述：真实浏览器下填写关键表单（如 Models）后切换语言，值保持。
+- 前置：静态导出站点可用。
+- 步骤：填写 → 切中文 → 断言。
+- 断言：值与交互状态保持。
+- 自动化：*（抽查核心表单）
+
+## E. 整页跳转语言保持
+
+### TC-16 Login 整页跳转回跳后语言保持
+- 层级：`e2e`
+- 描述：切成中文 → 走 Login（整页跳转）→ 成功回跳 → 语言仍为中文。
+- 前置：Login 整页跳转与同源偏好恢复已 PoC/批准。
+- 步骤：设中文 → 登录跳转 → 回跳 → 读 `<html lang>`/文本。
+- 断言：中文保持或命中文档化降级方案（需 Agent 0 批准）。
+- 自动化：*
+
+### TC-17 SSO 整页跳转回跳后语言保持
+- 层级：`e2e`
+- 描述：SSO 外部跳转并返回后语言偏好保持。
+- 前置：SSO 流程可测（测试账号/模拟）。
+- 步骤：设中文 → SSO → 返回 → 断言。
+- 断言：同 TC-16。
+- 自动化：*
+
+### TC-18 MCP OAuth 整页跳转回跳后语言保持
+- 层级：`e2e`
+- 描述：MCP OAuth 授权跳转并返回后语言保持。
+- 前置：MCP OAuth 流程可测（mock proxy）。
+- 步骤：设中文 → OAuth → 返回 → 断言。
+- 断言：同 TC-16。
+- 自动化：*
+
+### TC-19 存储不可用时的降级
+- 层级：`unit` + `e2e`
+- 描述：偏好存储不可用/被禁时降级到英文，不崩溃、不报错。
+- 前置：存储抽象可注入失败。
+- 步骤：注入读写失败 → 初始化 → 断言。
+- 断言：回退 `en`；无未捕获异常；不显示原始 key。
+- 自动化：*
+
+## F. 不误翻译保护
+
+### TC-20 模型名不被翻译
+- 层级：`integration`
+- 描述：Models 页面渲染的模型名/模型 id 在 en 与 zh 下逐字一致，不受语言切换影响。
+- 前置：stub 数据含大小写混合/带符号模型名。
+- 步骤：en、zh 各渲染并比对模型名文本。
+- 断言：模型名字符串完全一致；不被译成中文/改名。
+- 自动化：*
+
+### TC-21 API 字段 / 日志 / 代码示例不被翻译
+- 层级：`integration`（代码示例/字段）+ `unit`（日志原文）
+- 描述：API 参数字段、请求体 key、日志原文、代码示例不参与翻译。
+- 前置：含上述内容的组件与最小字典。
+- 步骤：zh 下渲染包含代码/字段/日志的页面。
+- 断言：这些内容保持原样（ASCII/原文），与 en 一致。
+- 自动化：*
+
+## G. 构建期元数据与可访问性
+
+### TC-22 构建期 `<title>` / meta description v1 保持英文
+- 层级：`e2e`
+- 描述：静态导出 `out/index.html`（及各路由）的 `<title>` 与 `meta[name=description]` 在 v1 保持英文，未被功能 Agent 意外改写或半中文化。
+- 前置：`npm run build` 完成；检查静态产物。
+- 步骤：解析 `out/**/*.html` 的 `<title>`/description（或浏览器读取 `document.title`）。
+- 断言：为稳定英文文案；不含原始 key、不含半成品中文。
+- 自动化：*
+
+### TC-23 可访问性文案本地化（aria-label/title/placeholder）
+- 层级：`component`（每组件）+ `integration`（成组页面）
+- 描述：图标按钮、关闭按钮、tooltip、`title`、`placeholder`、校验 error 的 a11y 文本随语言本地化并有英文回退。
+- 前置：目标组件含该类文案。
+- 步骤：en、zh 各查询 `getByRole`/`getByLabel`/`toHaveAttribute('aria-label', …)`。
+- 断言：a11y 文案为对应语言；zh 缺失时回退英文；不显示原始 key；ARIA value 用 `toHaveAttribute` 断言（CLAUDE.md）。
+- 自动化：*
+
+### TC-24 中文布局不溢出（自动断言 + 人工走查）
+- 层级：`integration`（自动溢出）/ `e2e`（窄屏）+ 人工
+- 描述：中文下导航/表格/弹窗/表单无横向溢出、无截断、无遮挡。
+- 前置：切换到中文。
+- 步骤：对关键容器断言 `scrollWidth <= clientWidth`、关键文本 `toBeVisible`；e2e 窄视口；人工跨语言走查。
+- 断言：无溢出/截断/遮挡；`V1_SCOPE_MANIFEST.md` UI 检查证据。
+- 自动化：*（溢出断言）+ (m)（视觉走查）
+
+## H. Key / 字典一致性
+
+### TC-25 en/zh key 集合一致
+- 层级：`unit`（脚本级，作为静态校验）——实现为 CLI 工具（`TEST_TOOLS.md`）；此处用例=脚本通过条件
+- 描述：en 与 zh 全部 namespace 的 key 集合、结构与插值变量一致。
+- 前置：脚本就绪、字典就绪。
+- 步骤：对每 namespace 运行一致性校验。
+- 断言：key 集对称一致；缺 key/多余 key/结构不一致/插值变量不一致时脚本非 0 退出并列差异。
+- 自动化：*（门禁/CI）
+
+## I. 首屏 / 静态导出
+
+### TC-26 静态导出构建产物无原始 key 泄漏
+- 层级：`e2e`/静态产物检查
+- 描述：构建后的 `out/` 页面源码不含原始 `ns:key` 文本作为用户可见内容（排除 JS bundle 中的字典本身）。
+- 前置：`npm run build`。
+- 步骤：解析产物 HTML，过滤 script/style，扫描可见文本。
+- 断言：可见文本无原始 key 形式。
+- 自动化：*
+
+---
+
+## 用例汇总
+
+- 共 26 条（TC-01 ~ TC-26）。
+- 自动化纯自动：除 TC-24 视觉走查外全部为 `*`；TC-24 为自动化+人工混合。
+- 覆盖方案 §10 全部"测试重点"：
+  - 默认语言：TC-01/02
+  - 切换即时生效：TC-03
+  - 刷新保持：TC-04/05
+  - 缺 key 回退英文：TC-06
+  - 不显示原始 key：TC-07/26
+  - `<html lang>` 一致：TC-03/08
+  - 中文不溢出：TC-24
+  - 切换不清表单：TC-14/15
+  - 整页跳转语言保持：TC-16/17/18/19
+  - 动态数量/日期/数字/货币（含 count=0/1/2）：TC-09~13
+  - 模型名/API 字段不误翻：TC-20/21
+  - `<title>`/meta v1 保持英文：TC-22
+- 另补充：a11y 文案（TC-23）、key 一致性（TC-25）。

docs/i18n/TEST_TOOLS.md

@@ -0,0 +1,88 @@
+# i18n 自动化测试任务清单与工具设计（TEST_TOOLS.md）
+
+> 角色：Agent 3 `qa-architect`；实施：Agent 7 `i18n-qa`
+> 原则：扫描工具**只报告、不自动改写**（方案 §3.4/§11）；测试只跑改动相关文件；Vitest 命令由 Agent 3 依配置确认（方案 §10）
+
+## 0. 运行说明（Agent 7 前置校准）
+
+- 定向 vitest：`cd ui/litellm-dashboard && npx vitest run --project <unit|component|integration> <path>`；type：`npm run test:types`。
+- 禁止无路径全量 `npm run test`（380 文件、CI 才跑全量）。
+- 工程检查：`npm run lint`、`npm run format:check`、`npm run build`。
+- **E2E Playwright 基础设施当前不存在**（无 `playwright.config.*`、无 `@playwright/test`、无 `tests/e2e/ui/`）。Agent 7 在 Wave 1 搭建；涉及 `package.json`/锁文件变更时必须由 Agent 0 指派唯一 Owner（方案 §6.1）。
+
+## 1. 自动化任务清单
+
+| 编号 | 任务 | 形态 | 何时运行 | 对应用例 |
+|---|---|---|---|---|
+| T-01 | 搭建 Playwright 基础（config、`tests/e2e/ui/`、live proxy fixture） | E2E 基建 | Wave 1 | TC-01~04,06~08,16~18,22,26 |
+| T-02 | key 集合一致性校验脚本 | CLI（node） | G3 门禁/CI、每次字典变更 | TC-25 |
+| T-03 | 硬编码字符串扫描脚本（只报告） | CLI（node） | 每波次、G3/G4 | — |
+| T-04 | 语言初始化/偏好/格式化逻辑单元测试 | `*.test.ts`（unit） | 平台 Wave 1 | TC-02,05,09~13,19 |
+| T-05 | 语言切换器/量词/单组件渲染测试 | `*.test.tsx`（component） | 各功能波 | TC-03,09,10,23 |
+| T-06 | Provider+页面集成测试（切换、表单保持、a11y、误翻译） | `*.integration.test.tsx` | 各功能波 | TC-03,14,20,21,23,24 |
+| T-07 | 静态导出产物 key 泄漏/`<title>` 英文检查 | 构建后脚本/E2E | G1、G4 | TC-22,26 |
+| T-08 | 中文布局溢出自动化断言（+人工走查入口） | `integration`/`e2e` | 各功能波、Wave 4A | TC-24 |
+| T-09 | `V1_SCOPE_MANIFEST.md` 测试/UI 检查证据回填 | 人工+半自动 | G2/G3/G4 | — |
+| T-10 | 完整回归矩阵执行并出报告 | Playwright+vitest | Wave 4A | REGRESSION_MATRIX |
+
+## 2. key 集合一致性校验脚本（T-02）
+
+**目标**：证明 en/zh（及新 locale）key 集、结构与插值变量一致；组件引用的 key 均存在。
+
+**设计**：
+- 输入：`src/locales/en/**/*.json`、`src/locales/zh-CN/**/*.json`。
+- 对每个 namespace 比对：key 集合（递归扁平化，含冒号前缀）对称差、嵌套结构形状、每叶子的 `{{var}}` 插值变量集合。
+- 组件引用校验：AST 扫描 `t('ns:key')`、`useTranslation('ns')`、`<Trans>` 与静态字典，找出引用但未声明的 key（悬空引用）。
+- 输出：无差异 → 退出 0；有差异 → 列出缺失/多余 key、结构/插值差异、悬空引用清单，退出非 0。
+- 挂接：G3 门禁"中英文 key 集一致"；可加入 CI lint 前置。
+
+**命令形态**：
+```bash
+node scripts/i18n/check-keys.mjs                 # 或通过 vitest 一个用例驱动（TC-25）
+```
+
+## 3. 硬编码字符串扫描脚本（T-03）——只报告、不自动改写
+
+**目标**：发现"漏改为 `t()` 的用户可见文案"，辅助人工补翻译。**禁止自动生成 key、禁止自动改写代码**。
+
+**设计**（对 TSX/TS 源码 AST）：
+- JSX 文案：非空白/非注释/非纯符号的 `JSXText`。
+- 属性字面量：`aria-label`、`title`、`placeholder`、`alt` 中指向文案的字符串常量。
+- 未国际化入口：`toast(...)`、`useMessage`、`notify(...)` 等（以项目现状校准 white-list）。
+- 排除白名单：模型名/API 字段引用（`model`、`langsmith` 等字典值来源）、路径、正则、CSS 类、`data-slot`、纯数字/符号、标识符、已 `t()` 包裹的。
+- 输出：文件、行号、候选文案、疑似命中形式（文案属性/JSX 文本/消息入口），按文件分组；**附带"仅报告"明确标注**，不写字典。
+
+**报告消费**：Agent 7 输出人工 review 清单 → 产品/功能 Owner 决定是否改写；禁止工具自动化改写（方案 §3.4 硬约束）。
+
+## 4. 中文布局检查：自动化 / 人工边界
+
+**自动化（T-08）**：
+- 组件/集成断言：中文渲染下对关键容器断言 `scrollWidth <= clientWidth`（无横向溢出）、关键文本 `toBeVisible`、无遮挡（元素间不重叠）。
+- E2E：在窄视口（如 1280、1024、768）下对 Navbar/Leftnav/表格/弹窗断言同样条件，并做关键帧截图。
+- 限制：视觉"美观/语义完整"无法纯自动化判定，自动只兜底"不溢出、不截断语义、可读可见"。
+
+**人工（配合 Agent 2）**：
+- 跨语言（en/zh）并列视觉走查，覆盖中文长字符串与窄屏。
+- 截图证据回填 `V1_SCOPE_MANIFEST.md` 的 `UI 检查` 栏。
+- `TEST_CASES.md` TC-24 标记为自动化+人工混合。
+
+## 5. 静态导出产物检查（T-07）
+
+- 构建后扫描 `out/**/*.html`：
+  - 用户可见文本（剔除 script/style/内联 JSON 字典）不含 `namespace:key` 原始 key 形式（TC-26）。
+  - `<title>` 与 `meta[name=description]` 为稳定英文、非原始 key、非半中文（TC-22）。
+- 挂接：G1（首屏/构建验证）与 G4（发布验收）。
+
+## 6. E2E 基建要点（T-01）
+
+- 目录：`tests/e2e/ui/`（Playwright spec，与 vitest 分离）。
+- 目标：静态导出 `out/` 或 live proxy；语言切换/刷新/整页跳转（Login/SSO/MCP OAuth）的偏好恢复需可稳定复现（测试账号或 mock）。
+- `package.json` 变更（新增 `@playwright/test`）须经 Agent 0 指定唯一 Owner，遵守 §6.1。
+
+## 7. Agent 7 建议实现优先级
+
+1. **T-02 key 一致性校验**（成本低、门禁 G3 硬性、最易踩线）。
+2. **T-03 硬编码扫描**（只报告，贯穿所有波次，辅助功能 Agent 自查）。
+3. **T-01 E2E 基建 + 平台 smoke**（默认语言/切换/刷新/`<html lang>`/回退/不显示原始 key）。
+4. **T-07 静态产物 key 泄漏 + `<title>` 英文检查**（G1 门禁）。
+5. **T-04/T-05/T-06 各层测试**随功能波补齐，T-08 布局断言进入各模块验收，T-10 在 Wave 4A 全量回归。

docs/i18n/V1_TRANSLATION_SCOPE.md

@@ -0,0 +1,78 @@
+# v1 翻译范围清单（V1 Translation Scope）
+
+> 维护者：Agent 2（localization-designer）
+> 状态：设计稿，待 G0 评审冻结；与 `I18N_MULTI_AGENT_PLAN.md` §1.2/§6.2 及 `DECISIONS.md` D8 对齐
+> 说明：本文档逐项列出 v1 各页面/组件"**需翻译**"或"**明确不翻译**"及原因，作为 Agent 5/6 改造与 Review 的依据。数据/协议内容是否翻译遵循 `LOCALIZATION_SPEC.md` §4。
+
+---
+
+## 1. v1 需翻译范围（逐项）
+
+### 1.1 全局壳层
+
+| 组件/区域 | 需翻译? | 原因 / 说明 |
+|---|---|---|
+| `leftnav.tsx` 导航菜单项与分组标签 | 需翻译 | 全局入口；`menuGroups` 的 `groupLabel`、`label` 需 I18N 化（含分组标签如 AI Gateway/Observability 等）。`menuGroups` 由 `page_utils.ts` 消费，改造时保留导出结构，仅语义化 label |
+| `leftnav.tsx` 面包屑（`getBreadcrumb`）/ Navbar 标题 | 需翻译 | 与导航一致，防止两处不一致 |
+| `leftnav.tsx` aria-label（折叠/展开侧边栏） | 需翻译 | a11y 文案（`LOCALIZATION_SPEC.md` §7） |
+| Navbar 用户菜单 / `SidebarAccountMenu` | 需翻译 | 显示名、菜单项、提示文案 |
+| `navbar.tsx` 其余可见菜单与搜索占位 | 需翻译 | 依实际文案盘点 |
+| 语言切换器（新组件） | 需翻译 | 自身 aria-label 与菜单项随语言渲染 |
+
+### 1.2 登录与引导
+
+| 页面 | 需翻译? | 说明 |
+|---|---|---|
+| `src/app/login/LoginPage.tsx` | 需翻译 | 登录表单、提交、错误提示、SSO 入口 |
+| `src/app/onboarding/`（OnboardingForm/FormBody/Loading/Error 等） | 需翻译 | 引导步骤、表单、加载/错误视图 |
+| `src/app/connect/` | 需翻译 | Connect 页面 |
+| MCP OAuth 相关回跳/授权提示 UI | 需翻译 | 见 `LOCALE_NAVIGATION_BEHAVIOR.md`（注意整页跳转语言恢复） |
+
+### 1.3 Models 与 API Keys
+
+| 页面/组件 | 需翻译? | 说明 |
+|---|---|---|
+| Models and Endpoints（`/models`）列表、创建/编辑表单、过滤、空态、校验 | 需翻译 | 静态与列表类文案；`model-hub`/AI Hub 候选页属低优先级，v1 不强求 |
+| API Keys（`/api-keys`）列表、创建弹窗、删除确认、用量展示 | 需翻译 | 含确认框、空态、校验 |
+| 相关复用组件（`key_value_input`、`copy button` 等） | 需翻译 | 复用组件文案由调用方传入或按需本地化 |
+
+### 1.4 Usage / Cost / Budget
+
+| 页面/组件 | 需翻译? | 说明 |
+|---|---|---|
+| Usage（`/usage`）筛选、表格头、图表说明、空态 | 需翻译 | 数值/货币用 i18n 格式化 |
+| Cost Tracking（`/cost-tracking` / `cost-optimization`） | 需翻译 | 成本跟踪页面；数值格式化随 i18n |
+| Budgets（`/budgets`）创建/编辑、限额设置、列表 | 需翻译 | 含"Budget Limit"等术语（见术语表） |
+
+---
+
+## 2. 明确不翻译范围（逐项 + 原因）
+
+遵循 `LOCALIZATION_SPEC.md` §4 与方案 §1.2：
+
+| 项 | 不翻译原因 |
+|---|---|
+| 模型名 / Model ID / Deployment / Provider 名 | 用户/后端数据，非 UI 文案 |
+| API 字段、请求/响应键、JSON 结构 | 协议内容 |
+| 日志原文、错误消息、错误堆栈（stack trace） | 需原样排障，保留原文 |
+| 代码示例、curl、终端命令、config.yaml、.env | 技术内容 |
+| URL、路径、文件名 | 技术标识 |
+| API / URL / SSO / MCP / OAuth / REST / ID / JSON 等缩写 | 通用技术缩写 |
+| 品牌名 LiteLLM / OpenAI / Anthropic | 品牌 |
+| 角色/权限代码值（admin、internal_user 等） | 代码值，仅显示名可翻译 |
+| Beta / New 徽标 | 视觉因子，保留英文 |
+| 构建期 `<title>` / metadata description | D8，v1 保持英文，不做多语言 SEO |
+| Guardrails / Policies / Teams / Users / Orgs / Projects / Logs / Playground / Prompts 等整模块文案（未列入 v1 功能批次） | 属 v2+ 候选（方案 §5.7），v1 范围外不被动外扩 |
+| Python SDK、API 文档、代码示例翻译 | 方案 §1.2 明确排除 |
+| 后端 FastAPI 错误响应全面国际化 | 方案 §1.2 排除 |
+
+---
+
+## 3. 与 §6.2 状态清单对应
+
+本清单即 `V1_SCOPE_MANIFEST.md`（Agent 0 维护）中 v1 行的**文案盘点输入**。Agent 5/6 完成任务时在清单相应行填写 EN/ZH-CN 盘点，Agent 7 填测试/UI 检查证据，Agent 2 在 Wave 4A 做术语与中文体验复核。
+
+## 4. 边界红线
+
+- 未列入第 1 节的功能页面文案，v1 一律**不翻译**（保持英文），不要顺手外扩造成半成品。
+- 第 2 节不翻译项，任何 Agent 不得翻译；发现误翻即退回原 Owner，并作为缺陷记录。