Beekeeper Studio 十语言文档：用母语上手数据库客户端-开发者社区

Beekeeper Studio 十语言文档：用母语上手数据库客户端

【免费下载链接】beekeeper-studioModern and easy to use SQL client for MySQL, Postgres, SQLite, SQL Server, and more. Linux, MacOS, and Windows.项目地址: https://gitcode.com/GitHub_Trending/be/beekeeper-studio

刚装好 Beekeeper Studio，打开文档却全是英文，workspace、connection file 这类词要查半天。这个开源 SQL 客户端已把官方文档和 README 翻译成西语、日语、葡语、法语等 10 种语言。下面用 4 步把文档切到你的母语，并拆开看项目是怎么做到这一点的。

4步切换文档语言

安装客户端：下载并安装与操作系统匹配的 Beekeeper Studio 安装包，界面默认是英文。
打开官方文档站：文档站右上角有语言切换器，里面列出了全部 10 种目标语言。
选择语言：以西班牙语 es 为例，选中后页面 URL 会带上 /es/ 这样的后缀。
验证效果：没有翻译的页面自动回退成英文，不会出现死链或 404。

Beekeeper Studio 主界面：界面保持英文，与英文文档中的术语完全一致。

它如何工作：文档的 i18n 机制

那它是怎么做到的？项目没有手写任何语言包，文档站用 MkDocs 加 i18n 插件构建，全部语言配置集中在仓库根目录的 mkdocs.yml 里。构建时插件先读取 languages 列表，接着为每种语言生成一套独立页面并给 URL 加后缀，最后重建切换器和搜索索引，因此切换语言后站内搜索也跟着换语言。

核心配置只有几行：

- i18n: docs_structure: suffix fallback_to_default: true languages: - locale: es build: true

三个关键点：

suffix 后缀。每种语言版本对应同一批页面，用 URL 后缀区分；仓库里的翻译文件也是同名加后缀，例如 docs/installation/linux.es.md。
fallback_to_default。未翻译的页面自动回退英文，所以翻译没做完时切换也不会断链。
reconfigure_search。搜索索引按语言重建，西语版里搜关键词返回西语结果。

3个真实场景

日语开发者首次连 MySQL。一位福冈的同事刚上手：先读仓库根目录的 README-ja.md 里的安装步骤，装好对应平台包，再在应用里新建一条指向本地 MySQL 的连接。遇到建表问题，对照文档里的界面截图操作；报错是英文的，直接拿去搜就能找到答案。

官方文档的上手指南，西班牙语版在相同位置加 es 后缀即可找到。

西语 DBA 做备份恢复。团队成员配置数据库备份时，直接打开 docs/user_guide/backup-restore.es.md 的译文，按步骤设置备份目录。界面按钮是英文的，术语与文档一一对应，不用来回翻译确认。

社区翻译贡献者。想给文档加一门新语言，步骤是固定的：复制任意一个 .es.md 文件当模板，写出同页面的新语言版本，再到 mkdocs.yml 的 i18n 列表里注册新语言。

建表对话框保持英文，多语言文档里能找到对应操作说明。

进阶配置：给文档添加一门新语言

下面是 mkdocs.yml 里 i18n 插件的完整摘录，可直接复制后改：

- i18n: docs_structure: suffix fallback_to_default: true reconfigure_material: true reconfigure_search: true languages: - locale: en default: true name: English - locale: es name: Espanol build: true

docs_structure: suffix：语言版本共用同一套页面结构，靠后缀区分；仓库里的翻译文件用 .es.md 这类后缀命名。
fallback_to_default: true：未翻译页面回退英文，默认语言体验不受影响。
reconfigure_material / reconfigure_search: true：切换语言后重建主题导航和搜索索引。
build: true：标记该语言参与构建并输出到站点；新增语言时记得加上这一项。

想评估翻译进度，直接看文件树就行：目前西语是整个 docs 目录都有译文文件的语言，其余语言在缺失处回退英文。

常见问题与避坑

切换语言后部分页面仍是英文：原因是该页翻译未完成，fallback_to_default 生效中。解法：读英文版，或到 docs 目录看对应 .xx.md 文件是否存在，判断进度。
找不到语言列表的配置在哪：配置不在独立文件里，就在仓库根目录的 mkdocs.yml。解法：在 i18n 的 languages 下追加一个新 locale 条目。
Settings 里找不到界面语言选项：应用界面目前只有英文，设置面板没有语言项。解法：保持界面英文，靠多语言文档对照操作。
有没有欧洲葡萄牙语版本：配置里的 10 种语言只有 pt-BR（巴西）。解法：需要 pt-PT 的话，按上文步骤新增 locale 和翻译文件。