Diagnosis for a multilingual Jupyter Book

[whyjz]

Hi everyone! 👋

I have been making my multilingual tutorials, and Jupyter Book is a great tool for that. Here I want to write down some findings to improve its greatness further, especially for its language support. Some of them are bugs that I don't know where to report, and the others are potential enhancements.

Background

The tutorial GMT Tutorials is written in Chinese (Taiwan) and is partially translated into English. The source files are hosted in this repository under docs/ folder. Documents in the source language are located in docs/main, and the .po files containing the translated strings are in docs/locale. I used the method described here to compile the multilanguage Book.

Diagnosis

Both the original and translated versions look mostly neat. Despite that, the following findings are my pain in the neck.

1. Jupyter Book CLI compatibility for overriding language option

This is described in Jupyter Book issue #1791.

2. TOC strings stay in the source language

The TOC captions are parsed into index.pot and can be translated in index.po. I have done the translation here along with other text in the index page, but these translations can't be rendered into the English HTML, and the captions stay in the original language (see the figure below).

3. Numbering between parts restarts in the translated version

The same figure also shows that the numbering between the Chinese (Taiwan) and the English versions mismatch with each other. I use the default numbering rule (i.e., use_multitoc_numbering is false), but somehow this setting does not apply to the translated book.

4. MyST Reference Link does not work in the translated version

Take a look at the broken link in the Section 1.1 title:

Reference link (which is defined as [GMT-link]: https://www.generic-mapping-tools.org/ later in the document) is applied in the source-language HTML but does not work in the translated HTML.

5. MyST footnote syntax does not work in the translated version

There are two footnote links in the figure above. In Chinese (Taiwan) HTML they are correctly rendered as superscripted [1] and [2], but in the English page, they stay their raw appearance in the plain text ([^1] and [^2]) without linking anywhere.

6. Loss of translation since Jupyter Book 0.3.1

As documented in Sphinx Book Theme #538 and Sphinx Book Theme #584, All of the generic words ("search this book," "By," "source repository,"...) always stay in English no matter what the source language is. To provide more examples, you can switch between the Chinese (Taiwan) version and the English version to explore this.

7. "Fig" (as in Fig 1, Fig 2,...) is not translated

This is described in #705.

8. Python code block displays strangely

My _congif.yml defines gettext_additional_targets: ['literal-block'] so all code blocks are parsed into the strings to be translated. In most cases, a code string remains the same unless there are some comments that need to be translated. From this figure, we see all bash blocks work well, but the only Python block (which I just copied the entire code into the .po file) is strangely translated into ::.

I am now experimenting with more python code blocks to see if it is a universal case or limited to that block. To be updated!