RTL Rendering for Guides

[jathayde]

Motivation / Background

This PR provides improved RTL language support, specifically focused on Arabic (MSA), Farsi, and Hebrew languages, including custom fonts for those languages, a javascript to detect auto-translation and shift the dir attribute, and other cleanup based on volunteer feedback.

Checklist

Before submitting the PR make sure the following are checked:

• [X] This Pull Request is related to one change. Unrelated changes should be opened in separate PRs.
• [X] Commit message has a detailed description of what changed and why. If this PR fixes a related issue include it in the commit message. Ex: [Fix #issue-number]
• [X] Tests are added or updated if you fix a bug or add a feature.
• [X] CHANGELOG files are updated for the changed libraries if there is a behavior change or additional feature. Minor bug fixes and documentation changes should not be included.

[mr3abd]

this comment not related to RTL

but that related by (Translation) I think should translate words like (Rails) to be like write as you speak not as (Google translation --> (train rails) ) Then I hope to be translated by ريلز, not قضبان

Thanks

[AhmedNadar]

This is related to translation.

Rails

In Arabic; the word "Rail" refer to different meanings. such as: for clothes, railway system, for safety, for curtains and for support. https://en.bab.la/dictionary/english-arabic/rails Most translation for "Rails" refer to Railway system or قضبان, where the document header refer to.

There's no direct translation to "Ruby on Rails" among the Arabic speaking Rails developers. The proper usage is writing how the English word sounds, Rails = ريلز Similar to Ruby = روبي

I noticed, the doc is not consistent on referring to the word "Rails". Sometimes Rails and others ريلز .

Edge

In Arabic, the word "Edge" here means "cliff edge" https://en.bab.la/dictionary/english-arabic/edge In Rails docs we use the word Edge as "Cutting Edge", and no direct word in Arabic. But we can use مُتَقَدِّم (motaqaddim). Which has different meaning such as: "advanced, state-of-the-art, cutting-edge, leading-edge, pioneering, innovative."

There a few places where translation could confuse Arabic readers.

[zackbraksa]

[This comment is not related to RTL]

@AhmedNadar @mr3abd from I can find in the Rails docs:

Note that translations are not submitted to the Rails repository; your work lives in your fork, as described above. This is because, in practice, documentation maintenance via patches is only sustainable in English.

So the Rails repo itself doesn't have Arabic translation bundled in, there might be a semi-official fork somewhere on GitHub, but I'm not aware of it. And so the best place to start for us as Arabic devs is either kick-off an Arabic fork of rails/guides/source (if there is not one already) or contribute to an existing one.

[zackbraksa]

@jathayde Visually at least, I don't see any issues with the Arabic RTL version. 👍

[carlosantoniodasilva]

Thanks @mr3abd @AhmedNadar @zackbraksa, indeed we do not intend to make translations available in the guides ourselves, but we're trying to make at least Google Translation do a nicer job, swapping the direction accordingly. If it's going to translate certain words like "Rails" that it maybe should not, there's not much we can do unless it's possible to flag such words in certain ways to tell Translate / automated tools to not translate them -- but even then that'd add a lot of burden to maintaining the guides as they currently are.

That said, we hope that the changes here will make it easier to at least auto-translate the guides via Google or some other tool, and to manually generate them with the appropriate direction set (which was already supported previously), for those who want to work on a fork translating the guides.

[jathayde]

As far as translation goes, this is all handled by Google Translate in the browser. We are looking at options to exclude or force certain words, but it may not be doable without API translation (which would be future functionality). Focus for this is UI support for RTL languages and ensuring there's no weird rendering bugs or any best practices we may have missed in RTL support.

[AhmedNadar]

Regarding RTL layout and for Arabic it is good. No issues. I will do my best to contribute to translation guide. Google translation is not good. It is ok.

[mr3abd]

@AhmedNadar I'll work too in Arabic content We can work together on it

[jathayde]

@carlosantoniodasilva anything else we need to address here?

[carlosantoniodasilva]

@jathayde my apologies, I got side tracked with some personal & work stuff, but I'll take a look and get back to you soon.

[idangoldman]

Hi @jathayde and @carlosantoniodasilva

@MohammadYounes made RTLCSS (Website), a wonderful library automating the process of supporting RTL Web UIs by generating a RTL css file base on a LTR css file.

The generated style-rtl.css file can be added easiely as parf of the observer in guides/assets/javascripts/guides.js like so:

var googleTranslateLanguageSwitch = new MutationObserver(function (mutations, _observer) {
  each(mutations, function (mutation) {
    if (mutation.type === "attributes" && mutation.attributeName == "class") {
      const isRTLbyGoogleTranslate = mutation.target.classList.contains("translated-rtl");

      mutation.target.dir = isRTLbyGoogleTranslate
        ? "rtl"
        : "ltr";

      if (isRTLbyGoogleTranslate && !document.getElementById("rtl-style")) {
          const rtlStyle = document.createElement("link");
          rtlStyle.id = "rtl-style";
          rtlStyle.rel = "stylesheet";
          rtlStyle.href = "style-rtl.css";

          document.head.appendChild(rtlStyle);
      } else {
        document.getElementById("rtl-style")?.remove();
      }
    }
  });
});

googleTranslateLanguageSwitch.observe(document.querySelector("html"), {
  attributeFilter: ["class"],
});

I'm sure the above example can be rewritten in a more readable way 🫣

Also, RTLCSS comes with various options of configuration, including taking care of edge cases, custom rules, and generation flows of RTL css files.

After successful implementation for style.css, the RTL support can be expanded twards print.css and epub.css.

[jathayde]

Thanks Idan! I’m totally open to trying this. I’m traveling this week and will try to review it. I really appreciate the source references!

[idangoldman]

Enjoy your travels John! Feel free to ping me with follow-ups.

[jathayde]

Some missed issues with interstitial padding due to body vs html dir call fixed in 196635c3

[jathayde]

@carlosantoniodasilva I think I've resolved everything - if you want to check and mark resolved as you see fit, we can see if there's anything else floating and get this finished up.

[jathayde]

@carlosantoniodasilva Fixed the RTL side bar stuff in 7abc64ba