Chatto 30 语言国际化架构指南Runtime JSON 客户端 i18n 与多语言包扩展实战【免费下载链接】chattoA fully-featured team and group chat application that you can easily selfhost.项目地址: https://gitcode.com/gh_mirrors/chatt/chattoChatto 是一款功能完整的团队与群组聊天应用支持轻松自托管并内置 30 种语言的客户端界面国际化i18n。它没有选择编译期生成消息函数而是用一套「运行时 JSON 目录」方案翻译就是普通 JSON 文件改一个词 改一行 JSON无需跑任何 i18n 编译器。本文带你读懂这套架构的设计动机、消息包组织结构以及如何零门槛扩展一个新语言。从编译期到运行时为什么换方案Chatto 早期ADR-043使用 Paraglide 做编译期消息系统。但目录膨胀到 29 个语言区、21 个分区后生成的 locale 模块成了构建产物的重要部分生产构建逼近 Node 默认堆上限且每个前端命令都依赖一次 i18n 编译。ADR-065 给出了替代方案目录本来就是版本化的 JSONChatto 不需要本地化路由浏览器自带Intl复数/数字规则——那么直接在运行时读 JSON 即可。核心取舍一句话总结维度编译期方案旧Runtime JSON 方案新加/改翻译需要编译步骤纯 JSON 变更构建生成 locale 模块进打包图无 i18n 编译器键校验静态类型目录形状测试 运行时校验30 语言与地区变体的精细化设计语言区清单定义在 locales.ts共 30 个可选语言区地区变体独立成语言区de-DE/de-AT/de-CH、nl-NL/nl-BE、fr-FR/fr-CA、es-ES/es-419、pt-BR/pt-PT、zh-CN/zh-TW加上en-GB/en-US以及sv-SE、nb-NO、pl-PL、uk-UA、it-IT、lv-LV、et-EE、tr-TR、cs-CZ、ru-RU、ja-JP、ar、he-IL、eo世界语等en-GB是源语言兼最终回退它是唯一完整且被立即导入的目录稀疏地区层en-US、de-AT、de-CH只包含与父语言的差异如美式拼写缺失的键逐键回退到en-GB/de-DERTL 支持ar阿拉伯语和he-IL希伯来语是首批 RTL 语言区布局方向由语言区模型统一控制中文协商还有专门规则浏览器偏好带Hant脚本或 TW/HK/MO 地区选zh-TW否则选zh-CN避免「一个 Chinese 混两种方言」。多语言包的组织结构按「语言 × 分区」拆分成 JSON所有翻译存放在 apps/frontend/messages/目录规则是语言区/分区.json例如apps/frontend/messages/ ├── en-GB/ # 21 个分区源语言 ├── zh-CN/ # 21 个分区 ├── de-DE/ # 21 个分区 ├── de-AT/ # 仅 1 个分区差异覆盖 └── ...21 个分区清单见 catalogSections.jsauth登录注册、room聊天室、chat、composer输入框、settings、admin、search、voice……每个 JSON 顶层只含自己的分区。以简体中文的 room.json 为例{ room: { create: { title: 创建新聊天室, name_placeholder: 输入聊天室名称 }, join: { member_count: { one: {count} 位成员, other: {count} 位成员 } } } }三个命名约定由运行时自动识别校验逻辑在 conventions.ts键以_count或.count结尾 →CLDR 复数消息值必须是复数分类对象且必须有other键以_html或.html结尾 →富文本消息只能走专门的 HTML API其余 → 普通文本消息核心运行时chatto/lingua 如何工作chatto/lingua 是一个框架无关的小包Apache-2.0无运行时依赖源码仅 10 个 TS 文件。它不生成任何代码只做四件事按语言区 分区加载目录加载器由应用提供加载后同步取词t(room.create.title)语言回退链de-AT → de-DE → en-GB目录一致性校验加载翻译时拒绝未知键、值类型变化、占位符与基础目录不一致前端在 catalogs.ts 里用import.meta.glob把整个 messages 目录注册成加载器messages.ts 则暴露给业务代码的取词门面m(room.create.title) // 普通消息 m(room.join.member_count, { count: 12 }) // 复数消息 mHtml(some.key_html, { name: Alice }) // 富文本消息懒加载与回退策略控制包体积的关键这套方案对性能非常友好en-GB的 21 个分区被立即导入保证首次渲染即可同步取词无加载瀑布其他语言区保持动态 JSON import构建器最多合并成每语言区 2 个物理 chunk两级加载边界根布局登录页等公共界面只加载 10 个「公共分区」进入/chat认证界面时才加载其余 11 个分区。用户每个所选语言区最多付出两次请求单语言区增量约17–26 KiBBrotli 压缩且永不进入初始路由包切换语言时setLocale()先加载完所有活动分区再发布新语言区订阅方永远不会看到半翻译界面语言协商谁来决定界面语言语言选择由客户端外壳拥有而不是由连接中的服务器决定Chatto 是多服务器客户端一个浏览器可同时连多台服务器。解析优先级negotiateLocale浏览器本地的 Chatto 语言偏好持久化在chatto:locale浏览器的语言偏好列表兜底en-GB语言区一经选定就作用于整个 SPA切换服务器不会改变界面语言。语言选择器中的语言名本身也用Intl.DisplayNames本地化——切成德语后选项列表显示的是德语语言名永远可读。一个容易被忽略的原则持久化事件保持语言中立。事件溯源存储的是事实谁、何时、做了什么不是渲染好的文案后端 API 返回稳定码与枚举由 UI 边界映射到消息键。这样将来改文案、加语言都不需要重写任何历史数据。如何扩展一个新的语言包实战清单得益于 glob 自动发现新增语言几乎没有接线工作放入 JSON 文件在apps/frontend/messages/新语言区/下按 21 个分区放置翻译文件可参考 en-GB 目录。机器翻译可起草但发布前需要母语者审校登记语言区把语言区加入 locales.ts 的selectableLocales若是差异覆盖型地区变体如新的fr-CA稀疏层再在fallbackLocales中声明父语言完成构建时自动扫描注册运行时自动按「所选语言区 → 父语言 →en-GB」的链条回退质量护栏不靠编译期类型而靠测试纪律完整目录形状测试、占位符校验、缺失键标记见 catalogs.spec.ts。改键名因此要格外小心——它依赖搜索与测试而非编译器报错。安全细节_html 键的隔离设计翻译里允许带标记的文案但lingua.html()返回的是**不可信本地化标记品牌化类型**插值部分会被转义模板本身刻意不消毒必须由应用的受审消毒渲染器在严格的标签/属性/URL 允许名单下清理后插入 DOM而普通m()调用会直接拒绝 HTML 键。这种类型级隔离让翻译可能含 HTML这件事在编译期就无处越界。总结一套值得借鉴的轻量 i18n 架构Chatto 的国际化方案给自托管项目提供了很好的参照零编译器翻译即 JSON加语言 放文件构建链路彻底解耦体积可控基础语言同步可用 其余语言区懒加载 两级加载边界回退精细稀疏地区层逐键回退兼顾美式英语这类小差异场景纪律有兜底运行时目录校验 完整形状测试替代静态键检查数据语言中立事件与 API 不携带渲染文案国际化演进零数据迁移如果你正在给自托管的聊天、协作或 SaaS 产品做国际化这套Runtime JSON 分区懒加载 CLDR 约定的组合值得直接借鉴。【免费下载链接】chattoA fully-featured team and group chat application that you can easily selfhost.项目地址: https://gitcode.com/gh_mirrors/chatt/chatto创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考