---
title: teedoc internationalization (i18n) (translation)
keywords: teedoc, i18n, internationalization, translation
desc: teedoc internationalization (i18n), including plug-in internationalization and document internationalization
---

## Introduction to Internationalization (i18n)

If the document only uses one language, things are relatively simple, but the fact is that you often encounter the use of different languages:
* For `teedoc`, it must support enough languages ​​or be easy to extend the translation. Because users may use different languages, it may be English, Chinese, or other languages, even if the user only uses one language

* For users, you need to specify the language when you use it, so that `teedoc` can generate a suitable translation, and finally can customize the text when there is no translation, or participate in the translation

So internationalization (abbreviation `i18n`) is very important, the following is an introduction to how to use internationalization in `teedoc`



## Document specified language

Each document has a `config` (`config.yaml` or `config.json`) file, in which is added `locale`, which is a region (region corresponds to a language) keyword, such as Simplified Chinese

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

You can refer to [here](https://www.science.co.il/language/Locale-codes.php) for the area code, and it can be found in [Wikipedia](https://en.wikipedia.org/wiki/Language_localisation) Check it out, or use a program to check it, such as

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

For example, `zh` `zh_CN` `zh_TW` `en` `en_US` `ja` etc.

Only when the language of the document is correctly specified, can the content language of some documents be correct, such as the prompt language of the search plug-in. The document pages in different languages ​​will generate the search prompt information in the corresponding language.


## Document content internationalization (translation)

If you have a document and wish to have a translation in another language, there are several ways:

* Using page translation plugins, users can choose to translate to almost any language, such as Google translation plugin `teedoc-plugin-google-translate`, but the disadvantage is that machine translation may be inaccurate in some places
* The user himself uses the browser's built-in page translation function, which is the same as the plug-in function
* Create a new translation document for manual translation and proofreading

If you need manual translation, you need to configure the `translate` keyword in `site_config`, such as editing `site_config` (`site_config.yaml` or `site_config.json`):

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

This configuration means that the `html` files of the documents under the `docs/more` directory will be generated in the `out/more/` directory (that is, the `url` [/more/](/more/));
The English source file is in the `docs/more/en` directory, and the generated web page `url` is in [/more/en/](/more/en/).
The advantage of this is that the translated documents can use relative paths to reference the resource files of the main documents, such as `../assets/`, whether it is a local editor preview or the final generated web page can be previewed normally. Don't worry about the path problem.

On the other hand, you may want to put the Chinese and English translations separately, such as the `docs/get_started/zh` and `docs/get_started/en` directories, and share the resource files of `docs/get_started/assets`. It will be a little more complicated, and it is no longer recommended to use it in this way:

```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"
                }
            ]
        }
    },
```

The Doc `"/get_started/zh/"` and the page `"/"` are both Chinese documents.
Now we need to add English translations for them. Add translations under `translate` -> `docs`, and specify `url` (the generated path, which needs to end with `/`) and `src` (the root directory of the translation document, which does not need to end with `/`)

As you can see, we manually specify a resource file `"assets"` that is shared by Chinese and English documents, so that we can use relative paths `../assets` in the documents to reference the resource files, and preview them in the local editor.

Then
* Copy `config` (`config.yaml` or `config.json`) and `sidebar` (`sidebar.yaml` or `sidebar.json`) to the translation document directory. For example, here is `"docs/get_started /en"`,
* Modify the `locale` value of `config` to `en`, add language option in `navbar`, and specify `type` as `language`
* To translate `sidebar` into English, the structure needs to be the same as the source text, but the `label` is different. If it is not the same, a warning message will be displayed when building
* Copy and translate the document that needs to be translated. It needs to have the same directory structure as the source document. If the user accesses an untranslated document through the sidebar, it will automatically display [no_translate.md](https://github.com/teedoc/teedoc/blob/main/teedoc/templates/no_translate.md) page, you can also create a new `no_translate.md` document in the translation directory to overwrite the default, it is recommended to modify based on the default

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


## Plug-in internationalization

The plug-in uses `babel` for international rendering, using the format defined by [gettext](https://www.gnu.org/software/gettext/), you can use [gettext](https://www.gnu.org/ software/gettext/) generated, the translation file format is
* `pot`: Translation template character file
* `po`: Translation character file
* `mo`: translated and compiled binary files for distribution to programs

Here is [teedoc-plugin-search](https://github.com/teedoc/teedoc/tree/main/plugins/teedoc-plugin-search/teedoc_plugin_search) as an example, the search prompt needs to be internationalized

There is the `locales` folder under the directory, the generation process:
* Use `gettext` in `__init__.py` to use internationalization, and set the search for `py` file in `babel.cfg`
* Execute `./trans_prepare.sh` to generate a translation file, and it will automatically find the translated string
* Manually translate `locales/language directory/*.po`
* Execute `./trans_finish.sh` to compile `po` to generate `mo` file
* Run and use the `mo` file
* Remember to add resource files to `package_data` of `setup.py`


For rendering of `HTML template`, such as [teedoc-plugin-theme-default](https://github.com/teedoc/teedoc/tree/main/plugins/teedoc-plugin-theme-default/teedoc_plugin_theme_default), it will automatically Find the translation from the `locales` directory and use the `Jinja2` syntax in the template, such as

```jinja2
{% trans %}Sentences to be translated {% endtrans %}
```

The method of generating translation is the same as described above