teedoc internationalization (i18n) (translation)

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

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

You can refer to here for the area code, and it can be found in Wikipedia Check it out, or use a program to check it, such as

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):

    "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/);
The English source file is in the docs/more/en directory, and the generated web page url is in /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:

    "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 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

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

Layout template internationalization

Use custom layout, if you want to internationalize, you can use {{gettext}} for internationalization, for example:

{{gettext("Hello world")}}

{{_("Hello world")}}

Execute teedoc build or teedoc serve will automatically generate translation files in the layout/locales directory, and manually edit the po file in layout/locales/.

It will automatically generate two files layout/i18n_babel.cfg and layout/i18n_locales.cfg. The former is to set the scanned file, and the latter is to set the language to be translated. Modify it according to the situation.

Except for using the gettext method of Jinja2 template for translation, you can also use the method of web front-end for translation, please refer to relevant information by yourself.

Plug-in internationalization

The plug-in uses babel for international rendering, using the format defined by 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 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, it will automatically Find the translation from the locales directory and use the Jinja2 syntax in the template, such as

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

The method of generating translation is the same as described above

Customize layout

Customize 404 page