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": {
            "/get_started/zh/": "docs/get_started/zh",
            "/develop/zh/": "docs/develop/zh",
        },
        "pages": {
            "/": "pages/index/zh",
        },
        "assets": {
            "/static/": "static",
            "/get_started/assets/": "docs/get_started/assets"
        },
        "/blog/": "blog"
    },
    "translate": {
        "docs": {
            "/get_started/zh/": [{
                    "url": "/get_started/en/",
                    "src": "docs/get_started/en"
                }
            ],
            "/develop/zh/": [{
                    "url": "/develop/en/",
                    "src": "docs/develop/en"
                }
            ]
        },
        "pages": {
            "/": [{
                    "url": "/en/",
                    "src": "pages/index/en"
                }
            ]
        }
    },

There are two documents "/get_started/zh/" and "/develop/zh/", and the page "/", both of which are Chinese documents. Now we need to add English translations for their three documents, respectively add translations under translate -> docs, the translated documents need to specify url (generated path, end with /) and src (translation The root directory of the document, the end of / is not required)

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

Plug-in internationalization

The plug-in uses babel for international rendering, using the format defined by gettext, you can use 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