Document Translation Workflow

This article is about the workflow that we currently use for document translation. Developers who want to contribute other language translations can follow this workflow. Any suggestions for this workflow are welcome and can be posted in discussions.

Overview

We use Sphinx to build PyWebIO's document, which allows us to write document in code as comment and generate document from code.

We host our document with readthedocs. When there is a new push to github, the document will be re-built and updated.

We use sphinx-intl tool to perform Sphinx translation flow. You can get more information from here.

Environment Setup

python3 -m venv /path/to/new/virtual/environment

# For Linux/macOS:
source <venv>/bin/activate
# For Windows cmd.exe, run: <venv>\Scripts\activate.bat 
# For PowerShell, run: <venv>/bin/Activate.ps1

git clone https://github.com/pywebio/PyWebIO.git
cd PyWebIO

# the `numpy` and `matplotlib` packages are not required in doc translating,
# delete them in requirements.txt if you have trouble in installing them
pip install -r requirements.txt  
pip install sphinx-intl

Translation

Get the code of language that you want to translate to from here.

In the following, we use <lang> to refer to the language code.

cd docs
make gettext  # Extract translatable messages into _build/gettext directory
sphinx-intl update -p _build/gettext -l <lang> -w 79  # Generate po files

Once completed, the generated/updated po files will be placed in locale/<lang>/LC_MESSAGES/ directory.

Note: when you run make gettext, your web browser may open a tab automatically, you can just ignore it and close the tab.

Translating

There are a lot of tools that can edit po files, here we use poedit, it's open source and cross-platform.

After you install poedit, you can use it to open the po files and start to translate.

The document is write in reStructuredText (reST) , which is a plaintext markup language. You can find a brief introduction to reStructuredText (reST) concepts and syntax in here. When you translating, please take care of the reST notaions and keep them in translated text.

There is one thing to note, the source text contains some duplicate items, it seems the issue of gettext, but we haven't found a way to solve it.

The duplicate items is shown as follows:

You can see that in the 3 highlighted items, the second and third item also appear in the first item. In this situation, keep in mind, do not translate the first item, but translate the remaining item.

You can use sphinx-intl stat to see the translation state.

When the origin document is updated, it is necessary to apply differences to translated po files. Just run the above commands (make gettext && sphinx-intl update ...) again to do that.

Preview translated document

For Linux/macOS, run:

make -e SPHINXOPTS="-D language='<lang>'" html

For Windows cmd.exe, run:

> set SPHINXOPTS=-D language=<lang>
> .\make.bat html

For PowerShell, run:

> Set-Item env:SPHINXOPTS "-D language=<lang>"
> .\make.bat html

You will get the translated documentation in the _build/html directory. Then, open the index.html file in that directory with web browser, you will see the translated documentation website.

Submit to Github

Submit the *.po files located in PyWebIO/docs/locales/<lang> in git and make pull request in github.

Publish

This is done by PyWebIO maintainers.

Follow https://docs.readthedocs.io/en/stable/localization.html#project-with-multiple-translations