Hoppscotch 多语言支持上手：5分钟切好中文界面，3个场景讲透原理与贡献-迪斯科星球

Hoppscotch 多语言支持上手：5分钟切好中文界面，3个场景讲透原理与贡献

【免费下载链接】hoppscotchOpen-Source API Development Ecosystem • https://hoppscotch.io • Offline, On-Prem & Cloud • Web, Desktop & CLI • Open-Source Alternative to Postman, Insomnia项目地址: https://gitcode.com/GitHub_Trending/ho/hoppscotch

队友盯着英文界面试探地问"这个按钮是干嘛的"，你却只能用英文回答？这篇讲 Hoppscotch 的国际化（i18n）能力：先把界面切到中文，再搞懂语言是怎么被选中的，最后学会给项目贡献翻译。

你将带走什么

学会如何切换界面语言，并让选择被浏览器自动记住
看懂首次启动时的语言判定顺序与英文兜底逻辑
用请求头和变量模拟不同语言环境下的 API 响应
掌握"改一个词"与"加一种语言"两条贡献路径

🚀 快速上手：从打开页面到看到中文界面

浏览器打开 Hoppscotch 网页版（hoppscotch.io）
进入设置页，点击"选择语言"按钮
搜索框输入"中文"，列表立刻过滤
点击"简体中文"，界面实时切换
关掉页面再打开，偏好仍在

整个过程没有注册、没有配置文件，选择只写进浏览器本地。源码里这个动作由changeAppLanguage完成：语言文件按需加载，选完即持久化，下次启动直接命中，所以你只需要手动选一次。

🌐 场景一：应用如何决定给你看哪种语言

有人第一次打开就是中文，有人却停在英文，差别在哪？判定逻辑写在packages/hoppscotch-common/src/modules/i18n.ts里，顺序很直白。

首次启动的判定顺序

先读本地配置里的locale字段；没有就取navigator.language（你浏览器的语言）做前缀匹配——zh-CN命中cn，en-US命中en；再不行就回落到英文。

切换后为什么不用重选

你手动选择后，语言代码会被写进浏览器本地配置，下次启动直接命中第一条规则。旧版带/{lang}/前缀的 URL 也会在路由层被识别并转成同一次写入，访问分享链接不会打乱你的语言偏好。

🧪 场景二：借多语言界面，测试 API 的国际化响应

界面语言是给你看的，API 的语言是给最终用户看的。当测试同学反馈"中文响应少了一个字段"，你可以先在本地复现它。

用请求头模拟语言环境

多数服务从Accept-Language读语言。在请求的 Headers 面板加一行：键Accept-Language，值zh-CN，发送后核对返回字段的完整性与措辞。

用环境变量管理多组语言值

频繁在多种语言间切换时，新建一个环境，定义变量accept_language，再把请求头的值写成{{accept_language}}。之后换语言只需一键切换环境，不必再手动改头。

🔎 场景三：英文兜底与从右到左的语言

缺词时为什么自动变英文

i18n 实例的fallbackLocale被固定为en：某个键在语言文件里缺失时，界面显示英文原文，而不是空白或占位符。所以中文界面里冒出一句英文时，第一步是去locales/cn.json搜对应模块的键，而不是怀疑版本坏了。

阿拉伯语这类 RTL 语言

阿拉伯语、希伯来语从右往左书写。languages.json中ar的条目带了"dir": "rtl"，布局会随之整体翻转。这正是"翻译"和"真正本地化"的差距所在，也是新建语言包时容易漏掉的一行。

🛠️ 进阶玩法：自定义与二次扩展

语言文件都在packages/hoppscotch-common/locales/下，共 34 个 JSON，结构一致：顶级键是功能模块，叶子值是文案。改语言文件不用碰任何源码，JSON 本身就是"代码"。

改一个词

打开locales/cn.json，定位到模块键，改掉值，保存。从源码构建的场景需要重新构建才能看到效果；线上版本则建议提交修复，让所有人一起受益。

加一种语言

完整流程见仓库根目录的TRANSLATIONS.md，核心三步：

git clone https://gitcode.com/GitHub_Trending/ho/hoppscotch cp packages/hoppscotch-common/locales/en.json packages/hoppscotch-common/locales/ky.json

复制en.json并翻译，键结构保持不动
在languages.json追加一条：{ "code": "ky", "file": "ky.json", "iso": "ky-KG", "name": "Кыргызча" }
提交 PR，未完成也可以先提交并说明进度，方便他人接力

排错速查表

现象	原因	解法
切换后个别词仍是英文	该键在语言文件中缺失，自动回落英文	到对应 JSON 补上翻译
新语言不出现在列表	`languages.json`与 locales 文件缺一不可，代码需一致	两处都补齐后重新构建
改了 cn.json 看不到变化	源码构建未重新打包，或线上版本缓存	重新构建，或用无痕窗口验证
切换语言后界面异常	JSON 逗号、引号错误导致整个文件解析失败	用 JSON 校验工具检查，或 git 恢复
阿拉伯语界面文字方向错乱	语言条目缺少`"dir": "rtl"`	在`languages.json`补上 rtl 标记

写到最后

Hoppscotch 的多语言不只是换一套文案：34 个语言文件、本地记忆、英文兜底、RTL 支持，每一处都对着某位工程师的母语。

发现翻译错误或功能问题，去项目 Issues 提一条
翻译细节想先讨论，Discord 社区里很热闹
如果你恰好会第二种语言，locales目录里总有些键在等你补全

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析