DataHub 多语言支持i18n完整指南界面语言切换、配置开关与新增翻译实践【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahubDataHub 的 Web 前端支持以多种语言呈现界面每个用户可以在个人设置中选择自己最熟悉的语言同一实例上不同用户可各用各的语言互不干扰。本文以 DataHub 官方多语言支持文档为主线结合当前仓库的前端源码i18n 基础设施、语言探测与切换逻辑与后端功能开关配置完整讲解可用语言列表、启用/关闭机制、浏览器语言自动识别规则、用户级语言持久化以及如何为开源项目贡献一门新语言或改进现有翻译。功能概述多语言支持在 DataHub 中的定位DataHub 的多语言支持Internationalization简称 i18n作用于其 React 前端datahub-web-react。它的设计目标是同一套 DataHub 实例服务多个团队、多个地区用户时每个人都能按自己习惯的语言使用界面首次访问时根据浏览器语言自动匹配无需任何手动配置用户可在个人设置中手动覆盖自动匹配结果且该选择会持久化到用户档案跨会话、跨设备生效管理员可通过一个环境变量在全局范围内关闭该功能。从前端源码结构看这一能力由一套完整的 i18n 模块支撑主要位于 datahub-web-react/src/i18n翻译资源与 i18next 初始化和 datahub-web-react/src/app/i18n语言探测、切换、持久化与选择器组件。可用语言一览截至当前仓库DataHub 界面支持以下语言对应 datahub-web-react/src/i18n/locales 下的语言目录语言本地名称语言代码状态英语Englishen默认德语Deutschde正式西班牙语EspañolesBeta巴西葡萄牙语Português (Brasil)pt-BRBeta法语FrançaisfrBeta意大利语ItalianoitBeta书面挪威语Norsk bokmålnbBeta瑞典语SvenskasvBeta匈牙利语MagyarhuBeta简体中文简体中文zh-CN正式标记为Beta的语言仍在持续打磨中界面中可能存在少量未翻译的字符串此时会回退到英文显示。除文档列出的语言外当前仓库的翻译目录中还包含芬兰语fi、日语ja和俄语ru三个语言目录见 locales 目录且前端常量表中也注册了对应的语言配置见 constants.ts从源码结构看它们同样属于受支持的语言候选。每个语言目录下都维护着 68 个 JSON 翻译文件覆盖界面中的各个功能命名空间。语言与组件库的联动在 constants.ts 中定义每种语言通过LocaleConfig结构绑定三样东西——langi18next 语言代码、antdAnt Design 组件库的语言包和dayjs日期时间库的区域设置。例如简体中文配置为export const ZH_CN_LOCALE_CONFIG: LocaleConfig { lang: zh-CN, antd: zhCN, dayjs: zh-cn, label: 简体中文, };这意味着切换语言不仅会替换业务文案还会同步切换 UI 组件库的默认文案与日期格式体验是一致的。启用与关闭多语言支持多语言支持默认开启。关闭它的方式是设置 GMS 环境变量I18N_ENABLEDfalse并重启服务。从源码可以确认该开关的完整链路后端默认值定义在 FeatureFlags.javaprivate boolean i18nEnabled true;环境变量绑定在 application.yamli18nEnabled: ${I18N_ENABLED:true}——即未显式设置时默认true设置I18N_ENABLEDfalse时生效为false。前端通过 GraphQL 配置读取该功能开关useIsI18nEnabled()调用useFeatureFlag(i18nEnabled)见 useIsI18nEnabled.ts进而决定是否允许非英文语言生效。因此典型的关闭操作是# 在 GMS 容器/进程的环境中设置 export I18N_ENABLEDfalse # 然后重启 GMS 服务关闭后前端仍保留语言选择入口但任何非英文语言都不会生效见下文“语言选择优先级”整个界面固定显示英文。语言自动探测与选择优先级首次访问从浏览器语言自动匹配用户首次访问 DataHub 时前端会根据浏览器的语言偏好自动选择界面语言。该逻辑位于 useEffectiveLanguage.ts其决策顺序是若 i18n 功能被关闭i18nEnabledfalse一律使用默认语言英文若用户在Settings → Preferences中显式选择过语言且该语言受支持则用户选择优先否则调用detectBrowserLanguage()根据浏览器语言navigator.languages按偏好从高到低排列匹配一个受支持的语言没有任何匹配时回退到默认语言英文。detectBrowserLanguage()的实现见 utils.ts体现了细致的匹配规则先做精确的、大小写不敏感的匹配如de→de再尝试把区域变体折叠到基础语言如de-DE→de、fr-CA→fr葡萄牙语只有pt-BR一个变体因此pt-PT也会被映射到pt-BR对中文做了专门处理zh-Hans、zh-CN、zh-SG以及裸的zh都会映射到zh-CN而繁体中文标记zh-Hant、zh-TW、zh-HK、zh-MO不会被折叠到简体中文而是尝试匹配zh-TW当该语言被注册时按navigator.languages的顺序依次尝试返回第一个能匹配上的语言。该探测逻辑由单元测试覆盖见 utils.test.ts。用户手动覆盖Settings → Preferences用户在个人设置Settings → Preferences中可以随时切换语言。前端提供LanguageSelect下拉组件见 LanguageSelect.tsx其选项来源于LANGUAGE_OPTIONS由LOCALE_MAP中全部LocaleConfig生成见 constants.ts。选择语言后触发useChangeLocale()见 useChangeLocale.ts它依次完成i18next.loadLanguages(localeConfig.lang)——按需动态加载该语言的翻译资源updateUserLocaleSettings(language)——通过 GraphQL mutationupdateCorpUserLocaleSettings把语言偏好写回用户档案见 useUpdateUserLocaleSettings.ts并刷新当前用户信息实现跨会话、跨设备持久化i18next.changeLanguage(localeConfig.lang)——切换 i18next 的当前语言setDayjsLocale(localeConfig.dayjs)——同步切换 dayjs 日期库的区域设置保证日期/时间的显示格式与所选语言一致。翻译资源的组织方式翻译文件统一放在datahub-web-react/src/i18n/locales/language/目录下每个语言目录包含 68 个 JSON 文件按命名空间namespace划分例如common.labels.json、common.actions.json——通用标签与操作按钮文案entity.profile.tabs.json、entity.profile.schema.json——实体详情页的页签与 Schema 相关文案search.json——搜索功能文案settings.preferences.json——个人设置页文案ingestion.json、ingestion.sourceBuilder.json——数据接入相关文案governance.glossary.json、governance.domain.json——治理相关的术语表与域文案。完整命名空间清单定义在 namespaces.ts覆盖了 UI 中的绝大多数界面区域包括新版首页home.v2、home.v3、新版搜索searchV2相关命名空间、实体详情entity.profile.*等。i18next 的初始化在 i18n.ts 中完成生产环境通过resourcesToBackend按需动态import对应语言的 JSON 资源import(\./locales/${lng}/${ns}.json)不会在首屏一次性加载全部语言包开发环境使用i18next-http-backend从/assets/locales/{{lng}}/{{ns}}.json加载并启用i18next-hmr热更新插件方便翻译开发时实时预览fallbackLng: en保证任意语言缺少某个词条时回退到英文这就是 Beta 语言“可能有未翻译字符串”时的兜底行为。语言切换与浏览器环境的联动细节从useLanguageSync及其测试useLanguageSync.test.ts可以看出前端会监听 locale 配置变化并同步 i18next 与 dayjs相关测试断言了切换en、de等语言时i18next.changeLanguage会被正确调用。测试示例见 useChangeLocale.test.ts其中验证了切换到不支持的语言时会回退到DEFAULT_LANGUAGE英文。整个语言选择流程由I18nProvider包裹在应用上下文中见 I18nProvider.tsx因此任何页面都能通过useEffectiveLanguage()感知当前生效语言。如果你在浏览器地址栏修改 locale 或通过代码调用 i18next API 切换语言界面文案也会即时刷新。贡献一门新语言或改进现有翻译DataHub 是开源项目欢迎社区贡献新语言以及改进已有翻译。如果你需要的语言不在上表或发现某处翻译可以更地道可以添加或更新翻译并提交 Pull Request。翻译文件位置与格式翻译文件位于datahub-web-react/src/i18n/locales/language/每个文件对应一个命名空间。以新增语言为例需要为全部命名空间提供language/namespace.json文件。JSON 结构为键值对形式例如common.labels.json中形如{ label.key: 翻译后的文案 }翻译时应以英文文件datahub-web-react/src/i18n/locales/en为基准保持键名完全一致仅替换值为目标语言。注册新语言仅有翻译文件还不够需要在 constants.ts 中完成注册定义该语言的LocaleConfig包含lang、antdAnt Design 语言包、dayjsdayjs 区域名与label语言下拉框中显示的自称将新配置加入LOCALE_MAP将新配置加入LANGUAGE_OPTIONS数组使其出现在Settings → Preferences的语言下拉框中。同时需要确认SupportedLanguage类型types.ts包含新语言代码。utils.ts中detectBrowserLanguage()的注释也提到伴随语言companion locale如zh-TW可以通过“先注册、类型后置”的方式接入说明仓库对该机制预留了扩展空间。建议的贡献流程阅读 CONTRIBUTING.md仓库根目录下的贡献指南了解提交流程与代码规范以en目录为基准为缺失的语言目录补齐全部命名空间 JSON 文件或修正现有语言目录中不准确的词条运行前端的 i18n 一致性校验脚本仓库提供了 check-i18n-parity.mjs 与 check-translations.mjs用于检查各语言与英文基准之间的键对齐情况确保没有遗漏键本地验证翻译效果开发模式下可即时预览再提交 Pull Request如需与其他贡献者协调新语言或翻译进度可在 DataHub 社区 Slack 的相应频道沟通。常见问题Q切换语言后某些字符串仍是英文是 bug 吗不一定。Beta 语言允许存在未翻译词条i18next 的fallbackLng: en会让缺失词条回退到英文。若你发现正式语言如中文存在缺失可以在 docs 或前端仓库中补充翻译并提交贡献。QI18N_ENABLED关闭后用户还能在设置里选语言吗设置入口仍然可见但由于useEffectiveLanguage()在 i18n 关闭时直接返回默认语言英文见 useEffectiveLanguage.ts任何非英文选择都不会实际生效。Q语言偏好保存在哪里保存在 DataHub 的用户档案中通过 GraphQL mutationupdateCorpUserLocaleSettings写入并持久化见 useUpdateUserLocaleSettings.ts。因此同一用户换浏览器、换设备后只要登录同一账号语言偏好仍然保留。Q浏览器语言匹配支持哪些变体detectBrowserLanguage()支持精确匹配与区域变体折叠如de-DE→de、fr-CA→fr、pt-PT→pt-BR并对中文做了繁体/简体区分处理详见 utils.ts。延伸阅读前端翻译资源与 i18next 初始化datahub-web-react/src/i18n/i18n.ts、datahub-web-react/src/i18n/namespaces.ts语言常量与 LocaleConfig 注册datahub-web-react/src/app/i18n/constants.ts语言探测与切换逻辑datahub-web-react/src/app/i18n/utils.ts、datahub-web-react/src/app/i18n/hooks/useEffectiveLanguage.ts后端功能开关metadata-service/configuration/src/main/java/com/linkedin/datahub/graphql/featureflags/FeatureFlags.java、metadata-service/configuration/src/main/resources/application.yaml翻译一致性校验脚本check-i18n-parity.mjs、check-translations.mjs贡献指南docs/CONTRIBUTING.md【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考