Jupyter-book: Multilingual books

[ueberchild]

How to create a jupyter-book with language selection?

[choldgraf]

Right now, your best bet would be to maintain two versions of your content in the "content" folder (eg, "en" and "fr"). Perhaps in the future we can explore some kind of automatic translation tool?

Update:

Now that Jupyter Book is using Sphinx under the hood, my guess is that we could follow Sphinx's guidelines for internationalization to see how this might be accomplished. E.g. https://www.sphinx-doc.org/en/master/usage/advanced/intl.html

It seems that readthedocs supports this as well, so perhaps we could look to them for inspiration as well? https://docs.readthedocs.io/en/stable/localization.html

[mathieuboudreau]

+1 this would be a really cool feature to have.

[choldgraf]

If anybody has expertise in this, input and ideas would be really helpful! I don't know much about i18n so this will need folks in the community to help out!

[mathieuboudreau]

It'd be useful in other cases, i.e. Canada has two official languages, so some documents/books would be great to be displayed in both.

[choldgraf]

I'd like to leave this one open, at least until we can fit the issue into a wish list somewhere...I think it's important to improve the story around i18n...just not sure what is the right path forward on it

[joergbrech]

+1 I would like this as well! Bilingual higher education is becoming more and more popular in Europe, especially in engineering and computer science where English is the lingua franca.

[turukawa]

I'd like to help on this issue. I've just completed a distance-learning data wrangling course for students in Cote d'Ivoire. The material is in Jupyter Notebooks in both French and English and I'd like to build that into a Jupyter Book.

I've no experience at this, so will be working through your documentation, but I definitely need a way to integrate the two languages without it requiring me to maintain separate repos.

If you have any pointers as to where I can start, I'll see what I can come up with. My idea of a simple approach would be some sort of mapping between the root language (EN) to alternatives (FR) in the YML, a folder structure for alternative language files in the build, and a language drop-down in the book itself to switch?

Alternatively, and potentially much more complex, is some system of tags to identify text for translation and then maintaining a separate translation file. Although that gets hopelessly tangled fast (in the Notebooks, there are code snippets with comments in French / English, and variable names in French/English, as well as markup blocks which include HTML).

As I said, though, I haven't the faintest idea where to start, or what would be considered best practice, so happy to play a supporting role....

[choldgraf]

Thanks for reaching out! Now that Jupyter Book is using Sphinx under the hood, my guess is that we could follow Sphinx's guidelines for internationalization to see how this might be accomplished. E.g. https://www.sphinx-doc.org/en/master/usage/advanced/intl.html

It seems that readthedocs supports this as well, so perhaps we could look to them for inspiration as well? https://docs.readthedocs.io/en/stable/localization.html

I wonder if @ericholscher could recommend anybody in the Sphinx/RTD community that could provide guidance on multi-language books?

[pfelber]

Just wondering if there had been progress on this side. I would like to write a book in French (no need for language selection). I could configure sphinx to use French for its messages (e.g., search results in the generated HTML pages). But I don't see a way to change the language used in the menus or the headers/footers (e.g., "Powered by") generated by Jupyter Book. Are the templates used to produce the book editable? Can we customize/override them? Thanks!

[choldgraf]

Right now I believe it's manually set by Jupyter Book, but we could make this configurable. Here is where it is manually set:

https://github.com/executablebooks/jupyter-book/blob/master/jupyter_book/sphinx.py#L33

I think we'd need to just add a configuration variable in _config.yml for search_bar_text, set the default to Search this Book..., and then use that instead of manually setting it.

This wouldn't solve the broader challenge of multi-language books but would be a first step.

[pfelber]

Thanks for the advice, indeed I can change some of the text like "Search this Book..." by overriding the configuration. I almost have a complete translated version but I could not track down where the title "Contents" in the top right navigation bar comes from. Do you know if it is hardcoded somewhere, and if so where? Thanks.

[choldgraf]

yep - it is in the sphinx-book-theme here: https://github.com/executablebooks/sphinx-book-theme/blob/master/sphinx_book_theme/topbar.html#L30

[chrisjsewell]

FYI just about all buttons, tooltips, etc are now translated in sphinx-book-theme: https://github.com/executablebooks/sphinx-book-theme/commit/d2a8b44271bc20baa49d5ea1a94aea18a25b2e3d