企业官网建设流程全解析

• 教育
• 音视频
• 后端
• 前端

本篇指南面向希望为 BigBlueButton 贡献翻译的社区成员与开发者，完整讲解基于 Transifex 的翻译协作流程、字符串从翻译平台同步回 GitHub 发布包的机制，并深入 HTML5 客户端的 i18n 加载、回退与语言切换源码实现。读完本文，你将掌握如何注册并选择翻译项目、申请新语言、判断翻译何时生效，以及客户端语言文件的结构与fallbackLocale/overrideLocale等关键配置的底层原理。

一、BigBlueButton 的本地化生态概览

BigBlueButton 是一个面向虚拟课堂等场景的完整网络会议系统（见项目主页），其界面字符串的本地化（Localization / i18n）由社区共同维护。得益于社区贡献者的努力，BigBlueButton 已被翻译为超过五十种语言。

翻译字符串并非散落在各处，而是集中在 HTML5 客户端（bigbluebutton-html5）的public/locales/目录下，每个语言对应一个 JSON 文件。当前仓库中已包含大量语言文件，例如：

• af.json、ar.json、az.json、bn.json、ca.json
• bg_BG.json、el_GR.json、es_ES.json、es_419.json、es_MX.json（区分地区变体）
• de.json、en.json、fr.json、ja.json、ko_KR.json、zh-CN.json等

语言文件的命名遵循 BCP-47 风格的语言或语言_地区约定（如de、bg_BG、es_419），这些文件会随 BigBlueButton 的安装包一同发布，供浏览器端的会议客户端动态加载。

二、如何参与翻译：Transifex 三步流程

如果你发现某个语言的翻译缺失或存在错译，可以按照以下步骤在 Transifex 平台贡献翻译：

第 1 步：创建 Transifex 账号

前往 Transifex 官方网站（transifex.com）注册一个账号。Transifex 是 BigBlueButton 官方使用的翻译协作平台，社区成员在此完成字符串的翻译与校对。

第 2 步：选择项目

登录后进入 BigBlueButton 在 Transifex 上的项目主页（app.transifex.com/bigbluebutton，需要登录）。页面会列出：

• 可翻译的语言列表：按语言分组展示；
• 可翻译的组件（Components）：BigBlueButton 的不同模块分别作为独立组件提供翻译，你可以按需选择。

第 3 步：点击你要翻译的语言

点击目标语言名称即可进入该语言的翻译工作台。如果在列表中找不到你使用的语言，可以通过 Transifex 菜单请求添加该语言，平台管理员审核后便会创建对应的翻译任务。

提示：参与翻译时优先关注尚未达到 100% 完成度的语言，或修正你已经熟悉的语言中的错译短语——这两类贡献对项目价值最大。

三、翻译字符串如何进入 BigBlueButton 发布包

翻译并不是在 Transifex 上完成后立即生效的。BigBlueButton 使用了Transifex 与 GitHub 之间的自动集成：翻译在 Transifex 上完成，集成服务将已完成的字符串同步回 GitHub 上的源码仓库，使它们有机会被打入下一个 BigBlueButton 发布版本。

这一集成机制由仓库根目录的 transifex.yml 描述，核心配置如下：

git: filters: - filter_type: file source_file: bigbluebutton-html5/public/locales/en.json file_format: KEYVALUEJSON source_language: en translation_files_expression: bigbluebutton-html5/public/locales/<lang>.json

各字段的含义：

关键同步规则如下（这也是官方文档明确说明的行为）：

• 只有当某个语言的翻译完成度达到 100%时，Transifex 集成才会向 GitHub 发起自动 Pull Request；
• 当某个已达 100% 完成度的语言中的字符串发生更新时，也会触发自动 PR。

仓库历史中即存在这类由 Transifex 自动创建的 PR（例如编号为 17799 的自动化拉取请求）。因此，如果你最近修改了字符串，但在最新版 BigBlueButton 中看不到效果，通常有两种原因：

1. 该语言的完成度尚未达到 100%，未满足同步条件；
2. 自你修改以来，对应的代码分支上还没有发布新的 BigBlueButton 版本。

四、仓库中的语言文件与格式

4.1 语言文件结构

所有语言文件位于bigbluebutton-html5/public/locales/目录，格式为键值对 JSON。例如en.json中每一条目均为「消息键（id）→ 翻译文本」的形式：

{ "app.meeting.join": "Join", "app.meeting.leave": "Leave" }

前端组件通过intl.formatMessage({ id: 'app.meeting.join' })引用这些键，运行时会替换为当前语言对应的文本。因此新增界面文案时，必须先在en.json中登记新键，它才会出现在 Transifex 的可翻译列表中。

4.2 语言元数据与特殊处理

并非所有语言都能自动获得完整的元数据。仓库中的 fallbackLocales.json 为部分语言补充了英文名与本地名（nativeName），例如：

{ "dv": { "englishName": "Dhivehi", "nativeName": "ދިވެހި" }, "ka": { "englishName": "Georgian", "nativeName": "ქართული" }, "lo-LA": { "englishName": "Lao", "nativeName": "ລາວ" }, "oc": { "englishName": "Occitan", "nativeName": "Occitan" } }

这些元数据用于在语言选择界面中以本地语言显示语言名称，从而为母语用户提供更好的可发现性。

五、客户端如何加载与回退本地化字符串

翻译文件最终要服务于浏览器中的会议客户端。下面结合源码剖析bigbluebutton-html5的 i18n 加载链路，帮助你理解「翻译何时生效、找不到语言时如何回退」。

5.1 加载流程（intlLoader.tsx）

客户端启动时由 intlLoader.tsx 负责语言加载，核心流程为：

1. 拉取语言索引：先请求locales/index得到可用语言列表（仅使用其中的name字段）；
2. 解析目标语言：fetchLocaleOptions依据浏览器语言（navigator.language）与配置计算应加载的语言集；
3. 并行拉取语言文件：对「默认回退语言、地区默认语言、规范化语言」做去重后并行fetch各locales/<lang>.json?v=<构建版本号>；
4. 合并注入：将拉取到的多个语言文件用Object.assign合并为一个 messages 对象，注入IntlProvider，同时写入当前 locale 状态。

值得注意的是，语言文件的请求 URL 带有v=${html5ClientBuild}版本号参数，可有效规避浏览器缓存导致的旧翻译不生效问题。

5.2 回退配置：fallbackLocale 与 overrideLocale

语言解析逻辑读取的是public.app.defaultSettings.application下的两项配置（见 settings.yml）：

# fallbackLocale: 若客户端当前语言缺少某字符串的翻译， # 则使用该语言对应的译文。建议设置为 100% 完成翻译的语言， # 以获得最佳用户体验 fallbackLocale: en # overrideLocale (默认 null): 若设置（例如 'de'）， # 将强制所有客户端显示德语译文。用户仍可在设置中单独选择 # 自己偏好的语言，但首次加载页面时 overrideLocale 优先于 # 浏览器语言 overrideLocale: null

• fallbackLocale: en：当用户语言（如某个小语种）缺少某条字符串时，自动回退到英文译文，避免出现空白文案；
• overrideLocale：适合部署方强制指定界面语言（如培训系统统一使用某语言），首次加载时优先于浏览器设置。

此外 settings.yml 还提供了：

fallbackOnEmptyLocaleString: true

该配置控制当某字符串的译文为空字符串时是否启用回退机制：为true时回退到其他语言，为false时直接返回空字符串。

5.3 加载健壮性设计

从源码结构可以推断，intlLoader.tsx对网络异常做了较完善的容错处理：

• 退避重试：采用RETRY_DELAYS = [1000, 2000, 5000]（毫秒）的退避序列，并叠加均匀抖动（jitter），避免大量客户端在共享网络故障后同步重试造成「惊群」；
• 总预算上限：MAX_RETRY_DURATION = 60000毫秒，整个加载过程（含索引与各语言文件）共享同一重试预算，防止无限重试；
• 失败降级：404 或 JSON 解析失败被视为「合法回退」而非瞬时故障，直接走语言回退路径；只有网络中断、5xx、429 才触发重试；预算耗尽时显示错误页（ErrorScreen）而非白屏或无限加载。

5.4 用户侧语言切换

会议客户端设置面板中提供语言切换功能：

• settings/service.js 中的getAvailableLocales()请求./locales/目录列表，并过滤掉index.json与.gz压缩文件，得到可选语言；
• locales-dropdown/component.jsx 渲染语言下拉框，其filterLocaleVariations依据public.app.showAllAvailableLocales决定显示全部语言，还是仅显示当前语言族及其地区变体；
• 用户切换语言后，通过useCurrentLocale状态触发intlLoader重新拉取对应语言文件并热更新界面。

六、常见问题排查

Q：我在 Transifex 翻译完了，为什么线上还是英文？A：按第三节的同步规则，只有语言完成度达到 100%（或 100% 语言中的字符串更新）才会触发自动 PR；同时还需等待该分支发布新版本。未满足任一条件，改动都不会出现在安装包中。

Q：某个小语种缺了很多译文，客户端会崩溃或显示空白吗？A：不会。客户端依据fallbackLocale: en回退到英文译文；若fallbackOnEmptyLocaleString: true，空字符串也会走回退逻辑，保证界面始终有可读文案（详见 settings.yml 与 intlLoader.tsx）。

Q：我想让所有用户默认使用某一种语言怎么办？A：将 settings.yml 中的overrideLocale设置为目标语言代码（如de），首次加载时即强制使用该语言，用户仍可在设置中自行调整。

Q：新增了界面文案，如何让它进入翻译流程？A：在源语言文件bigbluebutton-html5/public/locales/en.json中添加新键，并在组件中通过intl.formatMessage({ id: ... })引用；新键会随下一次 Transifex 集成同步进入平台，供各语言译者翻译。

小结

BigBlueButton 的本地化是一条「社区翻译 → Transifex 协作 → 自动同步 GitHub → 随包发布 → 客户端动态加载」的完整链路。对翻译贡献者而言，理解 100% 完成度门槛与发布节奏是判断改动何时生效的关键；对部署运维与前端开发者而言，掌握public/locales目录结构、fallbackLocale/overrideLocale/fallbackOnEmptyLocaleString配置以及 intlLoader.tsx 的加载与回退逻辑，即可从容应对多语言场景下的部署与排障。

• 教育
• 音视频
• 后端
• 前端