How to start a new translation?

[mohamed-ali]

I would like to start translating d2l-ai book to Arabic. I see that you have a repository per language, could you create one for Arabic? If not what's the procedure? Thanks.

[astonzhang]

Thanks! At the moment you may create your own repo d2l-ar, and start translating the Preliminaries chapter of the Release 0.7 (https://github.com/d2l-ai/d2l-en/releases/tag/v0.7.0). If we make changes in this chapter in the future release, you may git diff and incorporate translation of such changes. When translating, just leave math/code/labels/filenames as they are. Once you have a few chapters translated, I'll take a look and we can go from there :)

[mohamed-ali]

@astonzhang Thanks for the details. Arabic (like hebrew, persian and others) are right-to-left languages. So I would like to test the framework that generates the books to see the changes required to support such languages. Could you point to a minimal example generated with the same framework that I could play with to create a todo list of the changes required for RTL? Thanks

[astonzhang]

Sure, you may follow the instructions of http://book.d2l.ai/ to play with any example you like.

[mli]

you can change the _build/rst/conf.py manually to add support for Arabic, see http://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-internationalization

the pdf is built with xelatex, it should support Arabic as well

[mohamed-ali]

@mli thanks for suggesting using language="ar" but it doesn't have an impact on the page layout.

I spent sometime investigating various options to support RTL, I found that the best way is to create a rtl.css file and include it in the book's config.ini file.

[html]
...
# A list of CSS files to be included
include_css = static/rtl.css
...

The only blocker against using this technique is that, currently, mxtheme layout loads the custom css files before the main template's css. Here's the part responsible for that: https://github.com/mli/mx-theme/blob/master/mxtheme/layout.html#L14-L19

{% set css_files = css_files + [
    '_static/material-design-lite-1.3.0/material.' + theme_primary_color|e + '-' + theme_accent_color|e + '.min.css',
    '_static/sphinx_materialdesign_theme.css',
    '_static/fontawesome/all.css',
    '_static/fonts.css',
] %}

This means that any change to the template's layout in the custom file will be overwritten by loading the template's css after the custom css file.

This can be easily fixed by switching the order of concatenation, in mxtheme's layout.html page, to:

{% set css_files = [
  '_static/material-design-lite-1.3.0/material.' + theme_primary_color|e + '-' + theme_accent_color|e + '.min.css',
  '_static/sphinx_materialdesign_theme.css',
  '_static/fontawesome/all.css',
  '_static/fonts.css',
] + css_files %}

But before doing a PR to change the order, I would like to make sure that you don't have objections against reordering the css file loads as suggested.

@mli @astonzhang Is there something that requires the current css file load order?

Thanks.

[mohamed-ali]

@mli I added a PR to change the css files load order: https://github.com/mli/mx-theme/pull/4

[ChaiBapchya]

@mohamed-ali any update on this? Looks like it's not merged yet.

[mohamed-ali]

@ChaiBapchya I started some translations locally which required few changes. I can push PRs with the changes and translations, but as you can the PR in my last comment is still open.

[ChaiBapchya]

Yes. I'm guessing we need to first get the change to css file load order merged & then your subsequent PR for translation. Right? But to get css file load order verified, it would be great if you could verify existing functionality doesn't break + Arabic translations work too. Just because I don't know CSS thoroughly.