企业官网建设流程全解析

DataHub 多语言支持（i18n）完整指南：界面语言切换、配置开关与新增翻译实践

【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub

DataHub 的 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 下的语言目录）：

标记为Beta的语言仍在持续打磨中，界面中可能存在少量未翻译的字符串，此时会回退到英文显示。

除文档列出的语言外，当前仓库的翻译目录中还包含芬兰语（fi）、日语（ja）和俄语（ru）三个语言目录（见 locales 目录），且前端常量表中也注册了对应的语言配置（见 constants.ts），从源码结构看它们同样属于受支持的语言候选。每个语言目录下都维护着 68 个 JSON 翻译文件，覆盖界面中的各个功能命名空间。

语言与组件库的联动在 constants.ts 中定义：每种语言通过LocaleConfig结构绑定三样东西——lang（i18next 语言代码）、antd（Ant Design 组件库的语言包）和dayjs（日期时间库的区域设置）。例如简体中文配置为：

export const ZH_CN_LOCALE_CONFIG: LocaleConfig = { lang: 'zh-CN', antd: zhCN, dayjs: 'zh-cn', label: '简体中文', };

这意味着切换语言不仅会替换业务文案，还会同步切换 UI 组件库的默认文案与日期格式，体验是一致的。

启用与关闭多语言支持

多语言支持默认开启。关闭它的方式是设置 GMS 环境变量I18N_ENABLED=false并重启服务。

从源码可以确认该开关的完整链路：

1. 后端默认值定义在 FeatureFlags.java：private boolean i18nEnabled = true;
2. 环境变量绑定在 application.yaml：i18nEnabled: ${I18N_ENABLED:true}——即未显式设置时默认true，设置I18N_ENABLED=false时生效为false。
3. 前端通过 GraphQL 配置读取该功能开关：useIsI18nEnabled()调用useFeatureFlag('i18nEnabled')（见 useIsI18nEnabled.ts），进而决定是否允许非英文语言生效。

因此，典型的关闭操作是：

# 在 GMS 容器/进程的环境中设置 export I18N_ENABLED=false # 然后重启 GMS 服务

关闭后，前端仍保留语言选择入口，但任何非英文语言都不会生效（见下文“语言选择优先级”），整个界面固定显示英文。

语言自动探测与选择优先级

首次访问：从浏览器语言自动匹配

用户首次访问 DataHub 时，前端会根据浏览器的语言偏好自动选择界面语言。该逻辑位于 useEffectiveLanguage.ts，其决策顺序是：

1. 若 i18n 功能被关闭（i18nEnabled=false），一律使用默认语言（英文）；
2. 若用户在Settings → Preferences中显式选择过语言，且该语言受支持，则用户选择优先；
3. 否则调用detectBrowserLanguage()，根据浏览器语言（navigator.languages，按偏好从高到低排列）匹配一个受支持的语言；
4. 没有任何匹配时回退到默认语言英文。

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），它依次完成：

1. i18next.loadLanguages(localeConfig.lang)——按需动态加载该语言的翻译资源；
2. updateUserLocaleSettings(language)——通过 GraphQL mutationupdateCorpUserLocaleSettings把语言偏好写回用户档案（见 useUpdateUserLocaleSettings.ts），并刷新当前用户信息，实现跨会话、跨设备持久化；
3. i18next.changeLanguage(localeConfig.lang)——切换 i18next 的当前语言；
4. 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 中完成注册：

1. 定义该语言的LocaleConfig，包含lang、antd（Ant Design 语言包）、dayjs（dayjs 区域名）与label（语言下拉框中显示的自称）；
2. 将新配置加入LOCALE_MAP；
3. 将新配置加入LANGUAGE_OPTIONS数组，使其出现在Settings → Preferences的语言下拉框中。

同时需要确认SupportedLanguage类型（types.ts）包含新语言代码。utils.ts中detectBrowserLanguage()的注释也提到，伴随语言（companion locale）如zh-TW可以通过“先注册、类型后置”的方式接入，说明仓库对该机制预留了扩展空间。

建议的贡献流程

1. 阅读 CONTRIBUTING.md（仓库根目录下的贡献指南）了解提交流程与代码规范；
2. 以en目录为基准，为缺失的语言目录补齐全部命名空间 JSON 文件，或修正现有语言目录中不准确的词条；
3. 运行前端的 i18n 一致性校验脚本（仓库提供了 check-i18n-parity.mjs 与 check-translations.mjs，用于检查各语言与英文基准之间的键对齐情况），确保没有遗漏键；
4. 本地验证翻译效果（开发模式下可即时预览），再提交 Pull Request；
5. 如需与其他贡献者协调新语言或翻译进度，可在 DataHub 社区 Slack 的相应频道沟通。

常见问题

Q：切换语言后，某些字符串仍是英文，是 bug 吗？不一定。Beta 语言允许存在未翻译词条，i18next 的fallbackLng: 'en'会让缺失词条回退到英文。若你发现正式语言（如中文）存在缺失，可以在 docs 或前端仓库中补充翻译并提交贡献。

Q：I18N_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