尧图网页设计 
OHIF Viewer 多语言支持语言切换、检测机制与本地化扩展实战【免费下载链接】ViewersOHIF zero-footprint DICOM viewer and oncology specific Lesion Tracker, plus shared extension packages项目地址: https://gitcode.com/GitHub_Trending/vi/ViewersOHIF ViewerOHIF 零部署 DICOM 查看器内置基于ohif/i18n包底层为 i18next的国际化能力允许通过偏好设置弹窗或 URL 查询参数切换界面语言。本文以官方用户指南 Language 文档为主线结合 platform/i18n 包的源码实现讲解语言切换的完整链路、语言检测与持久化机制、当前已支持的语言与命名空间以及如何在自己的项目或扩展中动态扩展、新增翻译。一、国际化能力概览与翻译覆盖现状官方指南明确指出OHIF 支持国际化能力可以设置 Viewer 的通用语言同时需要说明的是目前并非所有组件、所有语言都有完整翻译。不过按照开发者指南的流程用户可以很轻松地补充“键值对”形式的翻译条目。实现层面翻译能力集中在独立的工作区包 platform/i18n 中该包封装了一个共享的 i18n 实例i18nextViewer 启动时即初始化所有扩展共享同一个实例包内src/locales/目录存放各语言的.json翻译文件每个.json文件自动成为一个命名空间namespaceOHIF Viewer 已在应用外层设置了主I18nextProvider连接共享 i18n 实例扩展内部无需再创建新的 Provider直接使用t函数即可。二、切换 Viewer 语言的两种方式2.1 通过偏好设置Preferences弹窗切换在 Viewer 界面打开偏好设置弹窗其中包含语言下拉列表。该下拉列表的数据来源可以从源码得到印证userPreferencesCustomization.tsx 中直接从 i18n 实例解构出availableLanguages、defaultLanguage与currentLanguage将当前语言作为下拉框初始值languageValue: currentLanguage.value并遍历availableLanguages渲染全部可选语言项。选择新语言后组件会调用 i18next 的语言切换逻辑界面文本随之重新渲染。2.2 通过 URL 查询参数lng切换OHIF Viewer 接受 URL 查询参数lng来指定语言例如https://viewer.example.org/viewer/1.2.840.xxx?lnges-MX这一能力的实现位于 platform/i18n/src/config.js其中语言检测配置detectionOptions指定了lookupQuerystring: lng即检测器会优先从 URL 的lng参数读取用户语言。2.3 Test Language一键验证翻译是否生效仓库内置了一个测试语言test-LNG其翻译文件位于 locales/test-LNG 对应的目录中。启用后所有被翻译的元素都会被加上Test {}前缀例如Study list会变成Test Study list。开发者可以用它快速验证某个界面文本是否已经接入翻译体系?lngtest-LNG三、语言检测顺序与偏好持久化机制config.js 中的detectionOptions定义了 i18next-browser-languageDetector 的完整检测策略这是理解“语言从哪来、存在哪”的关键const detectionOptions { // 检测顺序先 URL 查询参数再 cookie再 localStorage…… order: [querystring, cookie, localStorage, navigator, htmlTag, path, subdomain], // 各来源对应的键名/参数名 lookupQuerystring: lng, lookupCookie: i18next, lookupLocalStorage: i18nextLng, // 用户语言偏好缓存到 localStorage 与 cookie 两处 caches: [localStorage, cookie], excludeCacheFor: [cimode], // CI 模式下不持久化 };从源码结构可以看出以下行为优先级明确URL 的lng参数优先级最高其次是 cookie、localStorage最后才是浏览器navigator语言、HTMLlang属性、路径与子域名。因此?lngxx可以覆盖已保存的偏好。偏好自动持久化caches: [localStorage, cookie]表示检测到的语言会自动写入 cookiei18next与 localStorage 键i18nextLng用户下次打开无需重新选择这些名称可通过自定义 detector 配置修改。支持自定义检测配置index.js 暴露了initI18n(detection, useLocize, apiKeyAvailable)方法第一个参数即可传入新的检测配置适配部署在子域名区分语言的场景。四、当前支持的语言与命名空间4.1 已内置的语言platform/i18n/src/locales/index.js 汇总导出了各语言包当前内置的语言为语言代码语言en-US默认回退语言英语美国ar阿拉伯语de德语es西班牙语fr法语ja-JP日语nl荷兰语pt-BR葡萄牙语巴西ru俄语tr-TR土耳其语土耳其vi越南语zh中文test-LNG测试语言默认语言在 index.js 中定义为DEFAULT_LANGUAGE en-US并作为fallbackLng任何语言缺失的词条都会回退到英文。utils.js 中的languagesMap还登记了更多语言标签如en-GB、pt-PT、zh-CN、zh-TW等供语言下拉框显示规范化的语言名称下拉框展示语言时若languagesMap中找不到标签则直接回显语言代码本身。4.2 命名空间Namespace的组织方式翻译按语义/用途切分为多个命名空间典型的有Buttons所有按钮文本Common可复用的通用术语如t($t(common:image))CineDialogCine Player 对话框内的提示文本Header顶部栏相关文本MeasurementTable测量表格ohif/uiUserPreferencesModal偏好设置弹窗ohif/uiPatientInfo、SidePanel、ToolTip、Modals等。跨命名空间引用使用 i18next 的解析语法例如在某个命名空间内引用 Common 命名空间$t(Common:Reset)五、在代码中使用翻译5.1 React 组件内useTranslationimport React from react; import { useTranslation } from react-i18next; function MyComponent() { const { t } useTranslation(); return p{t(my translated text)}/p; }ohif/i18n初始化时配置了react: { useSuspense: true, bindI18n: languageChanged editorSaved }见 index.js语言变化时会自动触发组件重新渲染无需手动监听。5.2 非 React 环境T 函数在工具函数、服务类等非组件代码中可以使用导出的Timport { T } from ohif/i18n; console.log(T(my translated text)); console.log(T($t(Common:Play) my translated text));T在初始化完成后挂接到 i18n 实例上i18n.T t见 index.js。5.3 完全脱离 OHIF Viewer 使用如果要在 Viewer 之外复用翻译需要自行挂载 Providerimport i18n from ohif/i18n; import { I18nextProvider } from react-i18next; I18nextProvider i18n{i18n} App / /I18nextProvider;六、扩展翻译新增条目、地区变体与整门新语言6.1 动态扩展现有语言addResourceBundle / addLocales同一语言在不同国家、不同医院可能有术语差异。i18next 支持动态加载资源ohif/i18n暴露了addLocales(newLocales)批量方法实现见 index.js内部对每个“语言→命名空间”组合调用i18n.addResourceBundle(key, namespace, locale, true, true)import { addLocales } from ohif/i18n; import locales from ./locales/index.js; addLocales(locales);也可以逐条追加import { i18n } from ohif/i18n; i18n.addResourceBundle(pt-BR, Buttons, { Angle: Ângulo, });6.2 地区子语言文件夹en-US / en-GB 式扩展若只需为某个地区修改个别词条可在已有语言目录下新建双字符地区子目录例如|-- src |-- locales |-- index.js |-- en |-- Buttons.json |-- index.js |-- UK | |-- Buttons.js | |-- index.js |-- US |-- Buttons.js |-- index.jsen-US、en-UK会通过 i18next 的 fallback 机制与基础语言en的词条合并只需覆盖需要差异化的键即可。子目录的index.js需按如下结构导出{ en: { NameSpace: { keyWord1: keyWord1Translation, keyWord2: keyWord2Translation, }, }, en-UK: { NameSpace: { keyWord1: keyWord1DifferentTranslation, }, }, };6.3 新增整门语言两种方式向ohif/i18n提交贡献将翻译贡献给社区合并后该语言即被内置所有 OHIF 项目可直接使用仅在本项目/扩展中生效复制/locales中现有语言的.json命名空间文件与index.js导出结构保持相同的键与命名空间翻译成目标语言后通过addLocales注入例如法语示例const newLanguage { fr: { Commons: { Reset: Réinitialiser, Previous: Précédent, }, Buttons: { Rectangle: Rectangle, Circle: Cercle, }, }, }; addLocales(newLanguage);6.4 翻译工作流与调试拉取托管翻译locales目录下各语言的index.js文件由脚本 pullTranslations.sh 动态生成该包集成 Locize 作为翻译管理平台。生产环境若需从 Locize CDN 加载翻译可通过环境变量启用见 index.js 中读取USE_LOCIZE、LOCIZE_PROJECTID、LOCIZE_API_KEY默认情况下未设置USE_LOCIZE使用本地locales文件无需外部依赖。调试模式环境变量REACT_APP_I18N_DEBUG控制调试日志仅在非 production 且显式开启时生效见 config.js开启后控制台会输出ohif/i18n:前缀的初始化、语言检测与资源加载信息REACT_APP_I18N_DEBUGtrue yarn run dev七、小结OHIF Viewer 的语言能力由ohif/i18n包统一提供用户可通过偏好设置弹窗或?lngURL 参数切换语言语言偏好按querystring → cookie → localStorage → navigator的顺序自动检测并持久化开发者可以借助命名空间组织词条通过addLocales、addResourceBundle或地区子目录扩展语言配合test-LNG与REACT_APP_I18N_DEBUG快速验证翻译效果。由于并非所有组件在所有语言下都有完整翻译遇到缺失词条时会回退到默认英文en-US按上述扩展方式即可在本地补齐差量翻译。更多实现细节可参考开发者指南 Internationalization。【免费下载链接】ViewersOHIF zero-footprint DICOM viewer and oncology specific Lesion Tracker, plus shared extension packages项目地址: https://gitcode.com/GitHub_Trending/vi/Viewers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OHIF Viewer 多语言支持：语言切换、检测机制与本地化扩展实战
OHIF Viewer 多语言支持语言切换、检测机制与本地化扩展实战【免费下载链接】ViewersOHIF zero-footprint DICOM viewer and oncology specific Lesion Tracker, plus shared extension packages项目地址: https://gitcode.com/GitHub_Trending/vi/ViewersOHIF ViewerOHIF 零部署 DICOM 查看器内置基于ohif/i18n包底层为 i18next的国际化能力允许通过偏好设置弹窗或 URL 查询参数切换界面语言。本文以官方用户指南 Language 文档为主线结合 platform/i18n 包的源码实现讲解语言切换的完整链路、语言检测与持久化机制、当前已支持的语言与命名空间以及如何在自己的项目或扩展中动态扩展、新增翻译。一、国际化能力概览与翻译覆盖现状官方指南明确指出OHIF 支持国际化能力可以设置 Viewer 的通用语言同时需要说明的是目前并非所有组件、所有语言都有完整翻译。不过按照开发者指南的流程用户可以很轻松地补充“键值对”形式的翻译条目。实现层面翻译能力集中在独立的工作区包 platform/i18n 中该包封装了一个共享的 i18n 实例i18nextViewer 启动时即初始化所有扩展共享同一个实例包内src/locales/目录存放各语言的.json翻译文件每个.json文件自动成为一个命名空间namespaceOHIF Viewer 已在应用外层设置了主I18nextProvider连接共享 i18n 实例扩展内部无需再创建新的 Provider直接使用t函数即可。二、切换 Viewer 语言的两种方式2.1 通过偏好设置Preferences弹窗切换在 Viewer 界面打开偏好设置弹窗其中包含语言下拉列表。该下拉列表的数据来源可以从源码得到印证userPreferencesCustomization.tsx 中直接从 i18n 实例解构出availableLanguages、defaultLanguage与currentLanguage将当前语言作为下拉框初始值languageValue: currentLanguage.value并遍历availableLanguages渲染全部可选语言项。选择新语言后组件会调用 i18next 的语言切换逻辑界面文本随之重新渲染。2.2 通过 URL 查询参数lng切换OHIF Viewer 接受 URL 查询参数lng来指定语言例如https://viewer.example.org/viewer/1.2.840.xxx?lnges-MX这一能力的实现位于 platform/i18n/src/config.js其中语言检测配置detectionOptions指定了lookupQuerystring: lng即检测器会优先从 URL 的lng参数读取用户语言。2.3 Test Language一键验证翻译是否生效仓库内置了一个测试语言test-LNG其翻译文件位于 locales/test-LNG 对应的目录中。启用后所有被翻译的元素都会被加上Test {}前缀例如Study list会变成Test Study list。开发者可以用它快速验证某个界面文本是否已经接入翻译体系?lngtest-LNG三、语言检测顺序与偏好持久化机制config.js 中的detectionOptions定义了 i18next-browser-languageDetector 的完整检测策略这是理解“语言从哪来、存在哪”的关键const detectionOptions { // 检测顺序先 URL 查询参数再 cookie再 localStorage…… order: [querystring, cookie, localStorage, navigator, htmlTag, path, subdomain], // 各来源对应的键名/参数名 lookupQuerystring: lng, lookupCookie: i18next, lookupLocalStorage: i18nextLng, // 用户语言偏好缓存到 localStorage 与 cookie 两处 caches: [localStorage, cookie], excludeCacheFor: [cimode], // CI 模式下不持久化 };从源码结构可以看出以下行为优先级明确URL 的lng参数优先级最高其次是 cookie、localStorage最后才是浏览器navigator语言、HTMLlang属性、路径与子域名。因此?lngxx可以覆盖已保存的偏好。偏好自动持久化caches: [localStorage, cookie]表示检测到的语言会自动写入 cookiei18next与 localStorage 键i18nextLng用户下次打开无需重新选择这些名称可通过自定义 detector 配置修改。支持自定义检测配置index.js 暴露了initI18n(detection, useLocize, apiKeyAvailable)方法第一个参数即可传入新的检测配置适配部署在子域名区分语言的场景。四、当前支持的语言与命名空间4.1 已内置的语言platform/i18n/src/locales/index.js 汇总导出了各语言包当前内置的语言为语言代码语言en-US默认回退语言英语美国ar阿拉伯语de德语es西班牙语fr法语ja-JP日语nl荷兰语pt-BR葡萄牙语巴西ru俄语tr-TR土耳其语土耳其vi越南语zh中文test-LNG测试语言默认语言在 index.js 中定义为DEFAULT_LANGUAGE en-US并作为fallbackLng任何语言缺失的词条都会回退到英文。utils.js 中的languagesMap还登记了更多语言标签如en-GB、pt-PT、zh-CN、zh-TW等供语言下拉框显示规范化的语言名称下拉框展示语言时若languagesMap中找不到标签则直接回显语言代码本身。4.2 命名空间Namespace的组织方式翻译按语义/用途切分为多个命名空间典型的有Buttons所有按钮文本Common可复用的通用术语如t($t(common:image))CineDialogCine Player 对话框内的提示文本Header顶部栏相关文本MeasurementTable测量表格ohif/uiUserPreferencesModal偏好设置弹窗ohif/uiPatientInfo、SidePanel、ToolTip、Modals等。跨命名空间引用使用 i18next 的解析语法例如在某个命名空间内引用 Common 命名空间$t(Common:Reset)五、在代码中使用翻译5.1 React 组件内useTranslationimport React from react; import { useTranslation } from react-i18next; function MyComponent() { const { t } useTranslation(); return p{t(my translated text)}/p; }ohif/i18n初始化时配置了react: { useSuspense: true, bindI18n: languageChanged editorSaved }见 index.js语言变化时会自动触发组件重新渲染无需手动监听。5.2 非 React 环境T 函数在工具函数、服务类等非组件代码中可以使用导出的Timport { T } from ohif/i18n; console.log(T(my translated text)); console.log(T($t(Common:Play) my translated text));T在初始化完成后挂接到 i18n 实例上i18n.T t见 index.js。5.3 完全脱离 OHIF Viewer 使用如果要在 Viewer 之外复用翻译需要自行挂载 Providerimport i18n from ohif/i18n; import { I18nextProvider } from react-i18next; I18nextProvider i18n{i18n} App / /I18nextProvider;六、扩展翻译新增条目、地区变体与整门新语言6.1 动态扩展现有语言addResourceBundle / addLocales同一语言在不同国家、不同医院可能有术语差异。i18next 支持动态加载资源ohif/i18n暴露了addLocales(newLocales)批量方法实现见 index.js内部对每个“语言→命名空间”组合调用i18n.addResourceBundle(key, namespace, locale, true, true)import { addLocales } from ohif/i18n; import locales from ./locales/index.js; addLocales(locales);也可以逐条追加import { i18n } from ohif/i18n; i18n.addResourceBundle(pt-BR, Buttons, { Angle: Ângulo, });6.2 地区子语言文件夹en-US / en-GB 式扩展若只需为某个地区修改个别词条可在已有语言目录下新建双字符地区子目录例如|-- src |-- locales |-- index.js |-- en |-- Buttons.json |-- index.js |-- UK | |-- Buttons.js | |-- index.js |-- US |-- Buttons.js |-- index.jsen-US、en-UK会通过 i18next 的 fallback 机制与基础语言en的词条合并只需覆盖需要差异化的键即可。子目录的index.js需按如下结构导出{ en: { NameSpace: { keyWord1: keyWord1Translation, keyWord2: keyWord2Translation, }, }, en-UK: { NameSpace: { keyWord1: keyWord1DifferentTranslation, }, }, };6.3 新增整门语言两种方式向ohif/i18n提交贡献将翻译贡献给社区合并后该语言即被内置所有 OHIF 项目可直接使用仅在本项目/扩展中生效复制/locales中现有语言的.json命名空间文件与index.js导出结构保持相同的键与命名空间翻译成目标语言后通过addLocales注入例如法语示例const newLanguage { fr: { Commons: { Reset: Réinitialiser, Previous: Précédent, }, Buttons: { Rectangle: Rectangle, Circle: Cercle, }, }, }; addLocales(newLanguage);6.4 翻译工作流与调试拉取托管翻译locales目录下各语言的index.js文件由脚本 pullTranslations.sh 动态生成该包集成 Locize 作为翻译管理平台。生产环境若需从 Locize CDN 加载翻译可通过环境变量启用见 index.js 中读取USE_LOCIZE、LOCIZE_PROJECTID、LOCIZE_API_KEY默认情况下未设置USE_LOCIZE使用本地locales文件无需外部依赖。调试模式环境变量REACT_APP_I18N_DEBUG控制调试日志仅在非 production 且显式开启时生效见 config.js开启后控制台会输出ohif/i18n:前缀的初始化、语言检测与资源加载信息REACT_APP_I18N_DEBUGtrue yarn run dev七、小结OHIF Viewer 的语言能力由ohif/i18n包统一提供用户可通过偏好设置弹窗或?lngURL 参数切换语言语言偏好按querystring → cookie → localStorage → navigator的顺序自动检测并持久化开发者可以借助命名空间组织词条通过addLocales、addResourceBundle或地区子目录扩展语言配合test-LNG与REACT_APP_I18N_DEBUG快速验证翻译效果。由于并非所有组件在所有语言下都有完整翻译遇到缺失词条时会回退到默认英文en-US按上述扩展方式即可在本地补齐差量翻译。更多实现细节可参考开发者指南 Internationalization。【免费下载链接】ViewersOHIF zero-footprint DICOM viewer and oncology specific Lesion Tracker, plus shared extension packages项目地址: https://gitcode.com/GitHub_Trending/vi/Viewers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考