---
title: teedoc 国际化（i18n）（翻译）
keywords: teedoc, i18n, 国际化, 翻译
desc: teedoc 国际化（i18n）, 包括插件国际化和文档国际化
---

## 国际化（i18n）简介

如果文档只使用一种语言，事情比较简单，但是事实是经常会遇到不同语言的使用：
* 对于 `teedoc`， 必须支持足够多的语言，或者易于扩展翻译。 因为使用者可能使用的语言不尽相同， 可能是英语， 可能是中文， 也可能是其它语言， 哪怕使用者只使用一种语言

* 对于使用者， 在使用时需要指定语言， 以让`teedoc`生成合适的翻译， 最后在没有翻译的时候能自定义文字，或者能参与翻译

所以国际化（`Internationalization`, 缩写 `i18n`）就十分重要， 下面对在`teedoc`中如何使用国际化进行介绍



## 文档指定语言

每份文档都有一个`config`(`config.yaml`或者`config.json`)文件，在其中加入`locale`即地域（地域对应了一种语言）关键字，比如 简体中文

```json
{
    "locale": "zh_CN",
    ...
}
```

地域编号可以参考[这里](https://www.science.co.il/language/Locale-codes.php), 可以在[维基百科](https://en.wikipedia.org/wiki/Language_localisation)查阅到， 或者使用程序来查看，比如

```shell
pip install babel
pybabel --list-locales
```

比如`zh` `zh_CN` `zh_TW` `en` `en_US` `ja` 等等

文档只有正确指定了语言，才能让部分文档的内容语言正确， 比如搜索插件的提示语言，不同语言的文档页面会生成对应语言的搜索提示信息


## 文档内容国际化（翻译）

如果你有一份文档，希望有其它语言的翻译，有几种方法：

* 使用页面翻译插件，用户可以选择翻译到几乎任何语言，比如谷歌翻译插件`teedoc-plugin-google-translate`, 但是缺点是机器翻译可能有些地方会不准确
* 用户自己使用浏览器自带的页面翻译功能，和插件的功能一样
* 新建一份翻译文档， 进行人工翻译校对

如果需要人工翻译，则需要在`site_config`中进行配置`translate`关键字，比如编辑`site_config`(`site_config.yaml`或者`site_config.json`):

```json
    "route": {
        "docs": {
            "/more/": "docs/more"
        }
    },
    "translate": {
        "docs": {
            "/more/": [ {
                    "url": "/more/en/",
                    "src": "docs/more/en"
                }
            ]
        }
    },
```

这样配置就是 `docs/more` 目录下的文档生成的 `html` 文件会在 `out/more/` 目录下（也就是 `url` [/more/](/more/)）；
英文源文件在`docs/more/en` 目录下，生成的网页页面`url`在[/more/en/](/more/en/)下。
这样做的好处就是翻译文档里面可以直接使用相对路径引用主文档的资源文件，比如`../assets/`，不论是本地编辑器预览还是最终生成的网页都能正常预览图片，不用担心路径问题。

另外，你可能想将中英文翻译分开放置，比如`docs/get_started/zh`和`docs/get_started/en`目录，并且共用`docs/get_started/assets`的资源文件，会复杂一点，现已不建议这样使用：
```json
    "route": {
        "docs": {
            "/get_started/zh/": "docs/get_started/zh"
        },
        "pages": {
            "/": "pages/index/zh",
        },
        "assets": {
            "/get_started/assets/": "docs/get_started/assets"
        }
    },
    "translate": {
        "docs": {
            "/get_started/zh/": [ {
                    "url": "/get_started/en/",
                    "src": "docs/get_started/en"
                }
            ]
        },
        "pages": {
            "/": [ {
                    "url": "/en/",
                    "src": "pages/index/en"
                }
            ]
        }
    },
```

这里有份文档`"/get_started/zh/"`, 以及页面`"/"`, 都是中文文档.
现在我们需要为他们三份文档添加英文翻译, 分别在`translate` -> `docs`下添加翻译， 翻译文档需要指定`url`（生成的路径， 需要`/`结尾）和`src`（翻译文档的根目录， 不需要`/`结尾）

可以看到这里手动指定了一个中英文文档共同使用的资源文件`"assets"`， 这样在文档里面都可以用相对路径`../assets`来引用资源文件了并且在本地编辑器也可以预览。

然后
* 将 `config`(`config.yaml`或`config.json`) 和 `sidebar`(`sidebar.yaml`或`sidebar.json`) 复制一份到 翻译文档目录比如这里是`"docs/get_started/en"`，
* 修改`config`的`locale`值为`en`, 在`navbar`添加语言选项, `type` 指定为`language`
* 翻译`sidebar`为英文, 结构需要和源文相同， 只是 `label` 不同， 若不相同在构建时会抱警告消息
* 复制需要翻译的文档并翻译， 需要和源文档目录结构相同，如果用户通过侧边栏访问到了未翻译的文档，会自动显示[no_translate.md](https://github.com/teedoc/teedoc/blob/main/teedoc/templates/no_translate.md)页面，你也可以在翻译目录下新建一个`no_translate.md`文档来覆盖默认的，建议基于默认的修改

```json
    "locale": "en",
    "navbar": {
        "items": [
            {
                "id": "language",
                "label": "语言: ",
                "position": "right",
                "type": "language"
            }
        ]
    }
```


## 插件国际化

插件使用`babel`进行国际化渲染， 使用[gettext](https://www.gnu.org/software/gettext/)定义的格式， 可以使用[gettext](https://www.gnu.org/software/gettext/) 生成， 翻译文件格式为
* `pot`: 翻译模板字符文件
* `po`: 翻译字符文件
* `mo`: 翻译编译后的二进制文件， 用于发布给程序使用

这里以[teedoc-plugin-search](https://github.com/teedoc/teedoc/tree/main/plugins/teedoc-plugin-search/teedoc_plugin_search)为例，需要给搜索提示进行国际化

目录下有`locales`文件夹， 生成过程：
* 在`__init__.py`中使用`gettext`来使用国际化， 在`babel.cfg`中设置了寻找`py`文件
* 执行`./trans_prepare.sh` 生成翻译文件，会自动寻找使用了翻译的字符串
* 手动翻译`locales/语言目录/*.po`
* 执行`./trans_finish.sh`来编译`po`生成`mo`文件
* 运行即可使用`mo`文件
* 记得添加资源文件到`setup.py`的`package_data`中


对于 `HTML template`的渲染， 比如 [teedoc-plugin-theme-default](https://github.com/teedoc/teedoc/tree/main/plugins/teedoc-plugin-theme-default/teedoc_plugin_theme_default)， 会自动从`locales`目录下查找翻译， 在模板中使用`Jinja2`语法使用即可，比如

```jinja2
{% trans %}需要翻译的语句{% endtrans %}
```

生成翻译的方法和上面所讲相同