界面语言:资源发现、配置与重启
UI/ColorVision.UI/Languages/ 管理 ColorVision 产品的界面文化选择。正常设置入口走确认、保存配置、启动新进程并关闭当前应用;它不是给全部已打开窗口广播翻译的实时切换服务。应用的语言资源与仓库知识语言策略相互独立:保留英文 AGENTS.md 或取消文档语言镜像,都不决定产品支持哪些界面文化。
资源、可选列表与系统语言
本模块提供以下资源:
| 界面文化 | 资源文件 |
|---|---|
简体中文 zh-Hans | 中性资源 Resources.resx |
英文 en | Resources.en.resx |
繁体中文 zh-Hant | Resources.zh-Hant.resx |
资源文件不是可选语言的固定白名单。下拉框还受实际输出目录中的卫星资源、当前线程文化和系统文化影响;某语言能被选择,不代表所有模块都有对应翻译。
两种目录扫描的用途不同:
| 入口 | 当前行为 |
|---|---|
GetLanguages(defaultProcessDllName) | 从当前线程 CurrentUICulture 开始,在执行 LanguageManager 的程序集目录下逐个子目录查指定资源 DLL(仅该子目录顶层),再确保加入 zh-Hans 和 InstalledUICulture;同时清空重建静态显示名字典 keyValuePairs |
GetDefaultLanguages(defaultProcessDllName) | 在同一根目录的每个子目录内递归查找资源 DLL,收集子目录名并确保加入 zh-Hans;用于配置 getter 的可用性判断,不主动加入当前/系统文化 |
未传 DLL 名时,两者使用 AppDomain.CurrentDomain.FriendlyName + ".resources.dll",不是枚举每个插件的所有本地化资源,也不检查每个字符串是否有翻译。目录名未在此处统一验证成有效 CultureInfo;目录枚举异常没有局部隔离。扫描结果只是当前环境的候选证据,不是完整翻译清单。
LanguageManager.Current.Languages 在 manager 实例初始化时取得列表,不因资源文件或系统设置变化自动刷新。Copilot 的 GetAvailableLanguages() 会另行调用 GetLanguages 并替换该列表,但也不负责刷新所有已创建的语言编辑器。
显示为“自动检测”(英文 Auto detect、繁体 自動偵測)的项实际使用 CultureInfo.InstalledUICulture.Name 这个文化字符串,不是一个独立的 UseSystem 持久化标记或持续监听系统变化的订阅。某文化因当前线程/系统项出现在下拉框中,不代表主程序及每个插件都有该文化的卫星资源。
语言显示名称先查询当前界面文化中的精确文化名资源,再沿候选文化的父级查询。例如 en-US 使用 en 的译名,zh-CN 使用 zh-Hans,zh-TW 使用 zh-Hant;找不到译名时使用该文化的 NativeName,无效文化名保留原字符串。语言编辑器将系统项显示为“自动检测”,英文、繁体与简体分别显示为 English、繁體中文、简体中文,其它文化沿用上述回退;不修改保存的文化代码、语言发现范围或重启流程。
配置值与启动应用
LanguageConfig.UICulture 的 setter 仅保存私有字段;不更改线程文化、不广播变化、不写文件也不重启。getter 每次按 GetDefaultLanguages 判断该字段是否在当前资源候选中,匹配不到就返回 InstalledUICulture.Name,不回写或清除原字段。
因此,旧配置里写了 ja,但当前资源扫描没有 ja 时,读取会得到系统文化;若系统文化本来就是 ja,返回值仍可能是 ja。残留卫星 DLL 也可能使扫描继续接受旧文化。不能将回退说成必定切换到简体中文,或声称旧配置已被迁移改写。
ColorVision/App.xaml.cs 在配置、日志和主题初始化之后,将读取到的 UICulture 设到启动线程的 CurrentUICulture;替换旧实例后重载配置的分支会再次应用。这个赋值没有设置 CurrentCulture 或 DefaultThreadCurrentUICulture,也不是逐个设置各模块的 Properties.Resources.Culture。日期、数值格式及其它线程/显式资源文化应分别查实际调用点。
设置选择与重启副作用
LanguagePropertiesEditor 在常规页为 UICulture 建立 TwoWay、PropertyChanged 更新的 ComboBox 绑定。下拉框提供语言搜索、浅色悬停与选中勾选;搜索只改变选项可见性,不删减可选列表或改写当前配置,关闭浮层清除搜索。SelectionChanged 再调用 LanguageManager.Current.LanguageChange(str),不是在普通设置关窗时才决定是否切换。
| 阶段 | 实际结果与限制 |
|---|---|
| 与当前线程文化字符串相同 | LanguageChange 返回 false,不弹提示或重启;false 不唯一代表用户取消 |
| 选择不同语言但取消确认 | LanguageChange 返回 false;编辑器将目标属性与下拉选中值恢复为上次接受的配置值,不回滚其它设置,也不能撤销之前已保存的修改 |
| 确认 | 先创建 CultureInfo 并改当前线程文化,再写 LanguageConfig,调用 ConfigService.SaveConfigs();保存的是配置服务管理的配置集合,不仅语言字段 |
| 保存返回之后 | Process.Start(Application.ResourceAssembly.Location.Replace(".dll", ".exe"), "-r"),然后 Application.Current.Shutdown(),最后返回 true |
这个入口会写配置、启动进程和关闭当前应用,不能作为只读验证或无害预览。它没有等待新进程启动完成、校验新窗口语言或恢复旧进程的握手。任何步骤抛异常时,LanguageChange 本身没有捕获或回滚已经发生的线程/内存/文件变化;true 也不证明新进程已就绪。文件保存的准确失败语义归配置持久化。
LanguageChange 本身不要求 lang 先存在于下拉框,只直接构造 CultureInfo;直接调用者不能把它当成资源完整性校验。也不要用直接赋值 UICulture 绕过确认后再宣称已完成语言切换。
为什么旧窗口不会统一更新
当前没有 LanguageChanged 广播或统一窗口重建协议。不同显示路径在各自取值时读取资源:
SettingWindow.xaml等 XAML 使用x:Static Properties.Resources.*;其现有文本不是绑定到 LanguageConfig 的实时翻译表达式。SearchSettingsWindow在构造时调用 ApplyLocalization,直接给标题和控件 Content 赋字符串;此处没有订阅语言配置变更。PropertyEditorHelper.CreateLabel在生成标签时写入 Text/ToolTip;字符串缓存按 ResourceManager、文化名和 key 分开,新文化下再次查询与已有 TextBlock 自动更新是两件事。- 强类型
Resources.Designer.cs的 Culture 是该资源类独立的静态覆盖值;LanguageManager 不统一清空这些覆盖,也不重写硬编码字符串。
因此,新增翻译应跟随拥有该文字的模块资源和实际消费入口,保留资源键/代码符号;不能只改 LanguageConfig 就承诺已打开窗口、插件内容和所有后台格式同步切换。
添加或完善界面语言
- 在拥有该文字的模块中维护
Properties/Resources.<culture>.resx,沿用中性资源的键与格式占位符;语言显示名称由ColorVision.UI资源中的文化名键提供。只补显示名称不会生成其它模块的翻译。 主程序、共享 UI 库及相关插件/客户项目的DisplayText从本程序集资源管理器按CurrentUICulture查询;XAML 使用同程序集的DisplayTextExtension,动态文本用Get或保留格式参数的Format。Engine 沿用EngineLocalization/EngineLangExtension和已注册的Lang查询顺序。显示键可使用原中文文字,翻译不能替换配置、数据库、算法和协议标识;客户输入的名称及样品数据也保留原值。以{0}开头的 XAML 键须用{}{0}转义。避免仅大小写不同的资源键,资源生成会将它们视为重复;亮度 Y 与色度 y 等不同含义须使用独立语义键。科学诊断中明确采用不变文化的数字格式继续使用该文化,与界面文本翻译分开。 - 核对主程序与目标模块构建后的卫星资源及部署目录。默认语言发现查主程序名对应的资源 DLL,仅有某个插件的翻译文件不保证它进入可选列表。
- 在隔离配置中启动新的应用实例,再检查目标窗口、属性标签和格式化文本;确认“跟随系统”、资源缺项及显式资源 Culture 的回退结果。语言切换会保存配置并关闭当前应用,先处理未保存工作。
Flow 节点标题、属性名称/说明和分类通过 ST.Library.UI.Lang 查询 ST、FlowEngineLib 及 Engine 已注册的资源。节点迁入 Engine 后,枚举下拉先用对象资源,再回退到枚举类型所属程序集的资源;既有枚举仍可使用 FlowEngineLib 译文。模板/量程和校正组增益提示由 Engine 资源提供。
Engine 的默认、英文和繁体资源按同一键集合维护;中文动态键在默认资源中显式保存原文,便于资源编辑器核对缺项,运行时仍保留原有的 Lang 回退。资源清理必须同时核对强类型调用、EngineLang、格式化文字、属性/枚举元数据与拼接键;例如 ServiceType_* 和 Camera_HikBayerQuality* 仍有动态消费者,不能仅凭完整键名搜索不到就删除。强类型访问属性只随实际使用和删除情况维护,动态查找不要求新增访问属性。
翻译只改变显示文本,不改枚举值、序列化字段、协议名称或资源键。历史翻译可从 Git 查询后按当前键集合核对;不要直接用旧资源覆盖当前文件。
共享设备控制管理、流程执行状态、模板浏览器与批量图像处理使用各自所属模块的简体、英文和繁体资源。设备分组的显示名称与持久化 Name 分开:默认分组显示本地化名称,用户命名原样保留,派生 DisplayName 不写入配置。流程状态保留调用方传入的流程名、节点名和原始错误代码;批量算法显示名称使用目录提供的资源提示,算法 ID、目录名称和输出后缀保持原有含义。
Copilot 入口与验证缺口
CopilotAgentCapabilityServices.SetLanguageAsync 解析当前可用语言,在 UI dispatcher 上调用同一 LanguageChange,仍需用户确认和重启;已是目标文化时返回无需修改,未确认时返回未完成。工具审批、取消与恢复说明归工具契约,不能因为通过 AI 调用而略过应用自身确认或把工具返回当作重启验收。
动态中文键可以直接用原键作为中性显示值,核对资源时同时检查英文独有键。验收在获授权、无未保存工作且使用隔离配置的环境下检查资源部署、取消、保存失败及新进程界面。
