Contribute to Documentation Internationalization¶

Note

Existing Documentation

Prepare the Environment¶

Assuming you have forked the repository and cloned it locally.

Use cd JAnim to enter the project folder, then install the required environment:

pip install -e .[gui,doc]

Additionally, make sure GNU gettext is installed.

Workflow¶

The workflow for documentation internationalization consists of the following steps:

Update translation files: extract the latest translatable text and generate/update .po files
Translate: edit .po files to perform translation (use format-po to normalize formatting when needed)
Local verification: build the docs locally to preview translation results

Update Translation Files¶

In most cases, translation files (with the extension .po) have already been generated in the project. If you only want to edit existing translation files, you can skip this section and go directly to Translate the Documentation to start translating.

To create translations for a new language or update existing translation files, use the following command:

python scripts update-po docs <language>

Here <language> is the language code you want to translate to (for example, en for English, ja for Japanese, etc.).

Note

zh_CN is the source language of the documentation, so translation files do not need to be created for it.

After completion, you can find all .po files in the corresponding doc/source/locales/<language>/LC_MESSAGES/ directory.

Check Translation Progress¶

Before starting translation or during the process, you can check translation progress:

python scripts check-po docs <language>

This command scans all .po files and lists files that still contain untranslated or fuzzy entries. This helps you understand what translation work remains to be done.

Some tools, such as Poedit’s Catalog Manager, can also list translation progress for .po files in a folder.

Translate the Documentation¶

Translation files (with the .po extension) are now stored in doc/source/locales/<language>/LC_MESSAGES/.

You can use Poedit to edit .po files, or edit them directly with any text editor.

Note

If you are able to review the results, using an LLM Agent for translation is also fine (but remember to proofread).

Example prompt:

Please complete the translation work for the `<language>` documentation.
Please strictly follow the guidelines and workflow described in `doc/source/development/contribute-to-doc-i18n.rst`.

If you manually edited many .po files, it is recommended to run this once before submitting:

python scripts format-po docs <language>

This command standardizes line wrapping and formatting in .po files, reducing unrelated diffs caused by formatting differences.

After translating, submit your changes and create a Pull Request to merge into the main branch.

Build the Documentation Locally¶

To preview your translation results locally, you can build the documentation:

python scripts build-docs <language>

Here <language> is the language code to build (for example, en for English).

This command generates web files under doc/build/html_i18n/<language>/. Open index.html there in your browser to view the documentation.

Or add the -o option to the previous command to automatically open the browser for preview after the build finishes:

python scripts build-docs <language> -o

Note

When building documentation, .mo files are automatically compiled from .po files, so you do not need to generate them manually in advance.

Complete Example¶

Suppose you want to provide an English translation for the documentation. The complete workflow is as follows:

Update translation files:
```
python scripts update-po docs en
```
Edit .po files under doc/source/locales/en/LC_MESSAGES/ for translation
Check translation progress (optional):
```
python scripts check-po docs en
```
Build and open the local documentation preview:
```
python scripts build-docs en -o
```
(Optional) Normalize .po file formatting before submitting:
```
python scripts format-po docs en
```
Submit your changes and open a Pull Request