Is there a way to build and maintain multi language site in jupyter book using only one repo?

[SDSTony]

I would like to host multi language versions (Korean, English) of my jupyter book website.

Currently, the only way that I can think of is to create a repository for each versions of website. (ex. Jupyter-Book-Kor, Jupyter-Book-Eng)

However, this would be inconvenient in maintenance wise since I have to keep track of two different repos where the only difference is the language of the content files and table of contents.

I wonder if there is a way to build and maintain multi language versions of jupyter book website in one repo.

Thanks.

[chrisjsewell]

I'm not sure if it is possible in one repo, and I've tried with jupyter-book.
But with a general sphinx site, I believe the recommended way is detailed here: https://www.sphinx-doc.org/en/master/usage/advanced/intl.html, using transifex

Here is an example from a project I am involved with, to translate to chinese: https://github.com/unkcpz/aiida-l10n-zh_CN

[SDSTony]

Thanks for you help! I'll refer to the attached site along with Custom Sphinx Configuration guide of Jupyter Book to see if there is a way to pull this off.

For the time being, I've decided to go with creating multiple repos.

By the way, thanks for open sourcing Jupyter Book. I absolutely love it.

[chrisjsewell]

thanks! certainly report back if you see any opportunities to improve multi-language support 😄

[choldgraf]

indeed please do let us know how this goes, it would be really great to document any patterns that are useful for others to follow

[Daltz333]

I'm not sure of the integration between sphinx and executablebooks. But https://github.com/wpilibsuite/frc-docs-translations is a 2-repo system that could probably be combined into one (just a separate github actions workflow). It's documented a fair bit and I'd be happy to answer any questions

[anjackson]

I've just been attempting to set up a multilingual JupyterBook site, and got so far before hitting a problem that I can't seem to resolve. So, I'm going to document what I did here, in case someone else can take it further.

The project indicated above using things like sphinx-build -b gettext docs/source locale to start the translation process, but that doesn't work as-is because we're using the JupyterBook jb build . wrapper (note that I'm assuming the source is in the current working directory). Eventually, I managed to work out that the correct incantation is:

jb build --builder custom --custom-builder gettext --path-output _gettext .

Note that I'm using a different output path, because if you don't you get this error:

This environment is incompatible with the selected builder, please choose another doctree directory.

To get this to work at all, I needed these settings:

sphinx:
  config:
    locale_dirs: ['locale/']
    gettext_compact: false
    nb_render_priority:
      gettext: {}

However, the attempt to build the translation files still fails, with this error:

  File "/Users/andy/Documents/workspace/ukwa-documentation/venv/lib/python3.9/site-packages/sphinx/util/osutil.py", line 55, in canon_path
    return nativepath.replace(path.sep, SEP)
AttributeError: 'NoneType' object has no attribute 'replace'

Which seems to be similar to this old Sphinx issue related to image blocks. I can hack Sphinx sidestep this error, but as that was not part of the final fix for that issue, I'm not sure how to proceed.

[gsuarezr]

Could you please link to your jupyter book? I want to do the same and want to take a look at the end result

[anjackson]

Sorry @mcditoos I don't have a complete example to share yet. I've just done enough to determine that it should work, but it'll be a while before I have time to do more.

[hammerdirt-analyst]

Hi,

I am totally interested in this and willing to put the time in. We are delivering to the client two seperate books one in English and one in German. However we would prefer one. Actually we need three or four languages. In Switzerland we have three official languages.

The book is here: https://hammerdirt-analyst.github.io/IQAASL-End-0f-Sampling-2021/titlepage.html

The repo is being refactored right now so no judgments please. We have spent mulitple years in the field building this as we go (the release of Jupyter books really helped us out). I would need some time to get up to speed with the Sphinx-Jupyter interface but would really like to help out on this.

[hammerdirt-analyst]

We did a multilanguage report in English and German in one repo. Our use case is a little special. There is a note book in each language. We run jupyter book build ./ using different congfig and toc files (one for each language)

https://hammerdirt-analyst.github.io/IQAASL-End-0f-Sampling-2021/titlepage.html

[whyjz]

Hi @anjackson and @choldgraf and others,
Just wanted to write down my observations and potential cause about the AttributeError: 'NoneType' object has no attribute 'replace' for future reference. This happens when _toc.yml uses at least one - caption (together with parts) to structure the content. I suppose it also happens when there are other user-defined strings in the TOC but have not tested them through.

With gettext_location set to True, jb build --builder custom --custom-builder gettext --path-output _gettext . runs fine until it hits the root page (say index.md). All the TOC caption strings are parsed and stored in the translation template index.pot, but it is not possible for gettext to find where these strings are in index.md because they are actually from _toc.yml. To avoid this error, gettext_location must be set to False to skip the problematic step.

[whyjz]

@SDSTony Yes, this is what I have been doing for this tutorial website and the corresponding repository.

Here are specific steps. I assume the book content is in the docs folder.

1. Make gettext files (translation templates for a new language to fresh start)

   jupyter book build --builder custom --custom-builder gettext docs
   

2. Specify a target language, make .po files, and start translating. See sphinx-intl for more details. My [locale_folder] is set to docs/locale. This should agree with the locale_dirs settings defined in _config.yml.

   sphinx-intl update -p docs/_build/gettext -d [locale_folder] -l [target_language]
   

3. Generate HTML files in the source language.

   jupyter book build docs
   

4. Generate HTML files in the target language. Note that Jupyter Book's CLI does not allow overriding settings defined in _config.yml (i.e., the -D option in sphinx-build), so we have to generate config.py and use sphinx-build to do the step.

   jupyter book config sphinx docs
   sphinx-build -b html -D language=[target_language] docs [path_for_htmls]
   

5. Your native-language HTMLs are now in docs/_build/html/ and the translated HTMLs are available in [path_for_htmls].

Here are my relevant _config.yml settings for your reference:

sphinx:
  config:
    language: zh_TW              # defining the source language 
    html_search_language: ja     # ja is better at parsing zh_TW strings for search box
    # i18n related
    nb_render_priority:
      gettext: {}                # see the discussion above
    locale_dirs: ['locale/']     # my _config.yml is in docs/, so this points to docs/locale
    gettext_compact: false
    gettext_additional_targets: ['literal-block']
    gettext_location: false      # see the discussion above

[fccoelho]

This should be added to the documentation.

[hammerdirt-analyst]

Okay, I am waiting on some translations. When I get them I will try to implement (there is three languages and 20 +chapters/workbooks). Maybe I can help with the documentation after the experiene?