mdBook 用 translate.js 实现国际化自动多语言翻译

mdBook 的多语言翻译和国际化一直是一个问题。

不想为国际化而重写文章。因此，我集成 translate.js 。

我曾分别维护两个不同语言 mdBook 来解决国际化问题。直到我发现了 translate.js 这个项目。它支持几乎一键翻译页面，而且可以手动修正页面的翻译不准确处。

我的 mdBook 版本：

❯ mdbook -V
mdbook v0.4.29

创建 Javascript 脚本

创建 assets/translate_lib.js 文件。

写入以下代码：

assets/translate_lib.js

function initTranslate() {
    try{
        try{
            translate.service.use('client.edge');
            translate.listener.start();
            translate.language.setLocal('chinese_simplified');
            translate.setAutoDiscriminateLocalLanguage();
            translate.language.setUrlParamControl();
            translate.ignore.class.push('notTranslate');
        }
        catch(e){console.log(e);}
        translate.setUseVersion2();
        translate.nomenclature.append('chinese_simplified','english',`
            核污染水=Nuc-polluted Water
            哈姆语言之书=Hamud Book
            刘甜=PJ568
        `);
        translate.execute();
    }
    catch(e){console.log('翻译系统出错：' + e);}
}

window.addEventListener('load', initTranslate);

将 chinese_simplified 修改为您的文档的语言。但，如果您的文档包含多语言，可将 translate.language.setLocal('chinese_simplified'); 替换为 translate.language.getLocal(); 。它会识别页面内最多的语言作为文档语言。更多设置和功能等可在 translate 文档查看。

修改页面元素

编辑 theme/index.hbs 。

什么？您没有找到 theme/index.hbs ？ 您可以在一个新文件夹内执行 mdbook init --theme 您就可以将新文件夹的 theme/index.hbs 复制到您现有项目的 theme/index.hbs 位置进行编辑。

在其中添加新增部分。

theme/index.hbs

<div class="left-buttons">
    <button id="sidebar-toggle" class="icon-button" type="button" title="目录表 - Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
        <i class="fa fa-bars"></i>
    </button>
    <button id="theme-toggle" class="icon-button" type="button" title="更改主题 - Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
        <i class="fa fa-paint-brush"></i>
    </button>
    <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
        <li role="none"><button role="menuitem" class="theme" id="light">亮 - Light</button></li>
        <li role="none"><button role="menuitem" class="theme" id="rust">锈 - Rust</button></li>
        <li role="none"><button role="menuitem" class="theme" id="coal">碳 - Coal</button></li>
        <li role="none"><button role="menuitem" class="theme" id="navy">海魂 - Navy</button></li>
        <li role="none"><button role="menuitem" class="theme" id="ayu">阿黑 - Ayu</button></li>
    </ul>
    <script src="//res.zvo.cn/translate/translate.js"></script>
+   <button id="translate" class="icon-button" type="button" title="更改语言 - Change language" aria-label="Change language" aria-haspopup="true" aria-expanded="false">
+       <i class="fa fa-language"></i>
+   </button>
    {{#if search_enabled}}
    <button id="search-toggle" class="icon-button" type="button" title="搜索 - Search [S]" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
        <i class="fa fa-search"></i>
    </button>
    {{/if}}
</div>

这样能在页面左上按钮处新增一个翻译按钮。

创建 CSS 样式

问题在于 translate.js 生成的是 <select> 元素。难以做到按下按钮打开 <select> 元素。

我可以将 <select> 元素设定成透明，用 z-index 使它覆盖在 “翻译” 按钮上层，这样点击按钮位置实际上点到的是 <select> 元素。（哈，我聪明）

我还应当将文字颜色和背景颜色做成能和 mdBook 的主题系统匹配。

assets/translate.css

.translateSelectLanguage{z-index:10;width:100%;height:100%;opacity:0;cursor:pointer;position:absolute;left:0;color:var(--fg);background-color:var(--bg)}

添加 Javascript 和 CSS 到 book.toml

book.toml

  [output.html]
+ additional-css = ["assets/translate.css"]
+ additional-js = ["assets/translate_lib.js"]

多个：

book.toml

[output.html]
additional-css = [
    "assets/loading.css",
    "assets/title_fix.css",
+   "assets/translate.css"
]
additional-js = [
    "assets/loading.js",
+   "assets/translate_lib.js",
    "assets/giscus.js"
]

解决与 giscus 兼容问题

为了添加评论系统，我集成了 giscus 。 我设置 giscus 根据页面标题识别是否应该使用同一评论区。因此如果您没有使用 giscus 或您没有相同设置，您可跳过此步。

您可以查看《mdBook 添加 giscus 评论系统支持》来在 mdBook 中集成 giscus 。

theme/index.hbs

- <title>{{ title }}</title>
+ <title class="notTranslate">{{ title }}</title>

本地检查修改

mdbook build
mdbook serve

浏览器打开 http://[::1]:3000 检查是否有问题。有时候因为一些限制，要部署到服务器评论区和翻译才能正确加载。

尾声

如果您有什么问题欢迎在底下评论区与各位讨论。