---
name: ui-localization
description: 新增或修改 CombatSolver 玩家可见 UI 文案、胶囊附加信息、提示与本地化时使用，维护中英双语和显示边界；创意工坊介绍与发包另用 release-gate。
---

# CombatSolver 中英界面维护

## 当前入口

- `src/UI/SolverText.cs` 与内嵌 `src/UI/English.json`：`zhs` / `zht` 使用现有中文，其他语言使用英文。当前没有独立语言开关；切换游戏语言后重启统一刷新既有窗口和路线快照。
- 静态文案用 `SolverText.Get`，插值用 `SolverText.Format`。先翻译完整模板，再插入名称、数字和玩家输入；保留占位符及格式，不对最终拼接文本全局替换中文。
- `SolverOverlaySnapshot.CaptureAction` 同时生成胶囊和悬停说明。显示新信息时检查标题、目标、击杀括号来源、遗物效果、药水类型、选牌及嵌套/空选择，避免只翻译一级标签。
- 卡牌名称以 snapshot 的 `SolverActionTextIdentity` 中稳定 ID/升级为依据，由主线程 `SolverUiModelNames` 解析当前语言；不要重新直接显示 PlanAction.CardTitle 或从已翻译标题推断升级。已有胶囊通过 `SolverLocaleRefresh` 合并语言通知原位刷新，退出树后解除登记；新增显示字段同时考虑新投影和已存活控件。
- 路线行复用须比较全部动作显示值与完整本地化身份，包括嵌套选择和遗物，不能只比较当前标题。整行构建成功后才发布可复用快照，失败半行不能复用。语言变化后Populate重新构造该行，状态页清空上一快照，部署高亮每次Populate重置；不影响Runtime的最新路线采用数据。语言通知每帧合并一次，但不能因最终语言与上次相同而跳过刷新——中途可能新建了控件。合同覆盖同帧往返、保留/替换控件、失败后重试、部署索引与退出树订阅清理。
- `SolverRelicEffectText` 解析内置遗物摘要的紧凑语法。新增内置记录格式时同步中英显示与样本；第三方自定义摘要保留其原文。
- `SolverDisplayNames.Capture` 在主线程获取游戏名称，捕获能力/充能球的规范 ID 与类型名别名和通用来源的语言。worker 只读取冻结名称表；根外生成敌人按主线程冻结的原版站位横向顺序和分支已知阵容生成左起编号，动作目标与击杀说明共用名称入口；已死亡敌人保留编号依据，后台不读场景节点，不把内部战斗 ID 当显示编号；卡牌、怪物、遗物等沿用游戏译名。

## 维护边界

翻译位于 UI 投影或主线程名称捕获，Search 不引用 SolverText / SolverRelicEffectText，不读取实时语言，不逐分支加载资源或做本地化。搜索状态键、结构化事件 ID、协议和原始异常保持原口径。现有部分详细诊断与系统通知仍是原文，新增玩家文案应同时提供英文，不把这项历史限制扩大到新功能。

英文控件使用简短措辞，说明文字适当换行；检查窄面板和数值控件，避免依赖中文字符宽度估算布局。文案和用户输入按既有纯文本/富文本边界处理，不翻译或解释用户插值内容。

## 验证

文案改动选择受影响的最小检查；扩展胶囊来源或格式时使用 `UI-LOCALIZATION` headless 合同，覆盖 eng/zhs/zht、模板占位符、名称冻结、附加标签与 tooltip 一致性。命令及已有证据见 `docs/TEST_MATRIX.md`。只更新本 skill 时检查 frontmatter、路径和职责，不启动游戏。

名称缓存/刷新改动还覆盖同一已保存英文路线和存活控件的中文→英文→中文往返，含升级牌、嵌套选择、JSON 恢复、订阅清理和搜索状态保持。只在每种语言下重建控件不足以验证热切换。

输入未变且已有成功证据时复用。Headless 不证明真实排版或帧率；用户明确交由自己做交互验收时按其要求执行。

- 循环折叠保留完整平坦动作，不复用 ReplayCount 表示周期次数。snapshot 的动作结构身份及全部显示值/语言身份共同决定可折叠性；UI 投影忽略物理手牌序号，目标有 CombatId 时按该 ID 区分而非可变阵容索引，原搜索键与部署动作保持原值；三次以上重复才折叠；路线行保存区间、周期与偏移，真实动作数和部署索引保持原合同。末击/遗物效果/选择不同必须分开，循环次数与整周期动作包在同一轻量外框，次数放在动作右侧；宽面板按内容收紧，窄面板在组内换行，不新增动作间箭头。路线外层布局区分自然宽度和最小宽度，避免长循环阻止面板收窄；悬停说明随语言通知刷新。16 行之外须提示未显示回合数。验证区间中间/末次/后缀高亮、失败构造重试和折叠行复用。