OHIF Viewer 多语言模式下 Modes.json 配置问题解析

问题背景

在 OHIF 医学影像查看器的多语言支持功能中，开发者经常遇到 Modes.json 文件修改后不生效的情况。这是一个典型的国际化(i18n)配置问题，主要影响那些需要为不同语言环境定制显示模式的用户。

问题本质

Modes.json 文件用于定义查看器各种模式（如基础查看器、MPR 模式等）的显示名称。当开发者将文件复制到对应语言目录并修改后，系统未能正确加载这些变更，导致界面仍然显示默认语言的文本。

根本原因分析

经过技术验证，该问题通常由以下两个关键因素导致：

1. 文件导出缺失：在目标语言目录的 index.js 文件中未正确导出 Modes.json 的配置内容。这是最常见的配置疏忽。

2. 构建缓存问题：修改配置文件后，未清除构建缓存或未重新启动开发服务器，导致变更未被正确加载。

解决方案

完整配置步骤

1. 文件位置确认：

   • 确保 Modes.json 文件放置在正确的语言目录下，例如：platform/i18n/src/locales/vi/（越南语示例）

2. 导出配置：

   • 打开对应语言目录下的 index.js 文件
   • 添加对 Modes.json 的显式导出：

     import Modes from './Modes.json';
     export default {
       // 其他导出项...
       Modes,
     };
     

3. 构建流程：

   • 执行完整的项目重建
   • 清除可能的构建缓存（如 webpack 缓存）
   • 重新启动开发服务器

4. 验证步骤：

   • 在浏览器中访问查看器
   • 检查模式选择按钮是否显示为配置的语言文本
   • 使用开发者工具检查网络请求，确认正确加载了修改后的语言包

技术原理深入

OHIF Viewer 使用基于 React 的国际化框架，其多语言支持机制包含以下关键环节：

1. 语言包加载：系统会根据当前语言设置动态加载对应目录下的 JSON 配置文件

2. 文本解析：通过统一的翻译函数(如 t())解析配置中的键值对

3. 组件渲染：各UI组件使用解析后的文本来显示界面元素

当 Modes.json 未被正确导出时，系统会回退到默认语言或显示键名而非翻译文本。

最佳实践建议

1. 配置完整性检查：

   • 确保所有需要国际化的配置文件都在 index.js 中导出
   • 使用IDE的导入分析功能验证文件引用关系

2. 开发流程优化：

   • 修改语言配置后执行完整的构建流程
   • 在开发环境中禁用相关缓存以快速验证变更

3. 调试技巧：

   • 使用React开发者工具检查i18n上下文
   • 在浏览器控制台输出语言包对象以验证加载内容

总结

OHIF Viewer 的多语言配置是一个需要细致处理的过程。正确配置 Modes.json 不仅需要文件本身的修改，还需要确保其被正确导出和加载。理解这一机制有助于开发者高效地实现查看器的本地化工作，为不同地区的医疗专业人员提供更好的使用体验。