DocServe/teedoc.gitee.io-main/docs/get_started/en/usage/i18n.md

---

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

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

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