litellm/docs/i18n/TEST_CASES.md

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）。