Add RTL support

[ffoodd]

Fixes #30918, fixes #24807, fixes #27783, fixes #31845

Preview — Examples — cheatsheet — RTL cheatsheet

Todo

Beta 2

• Move cheatsheet from examples to main docs
• Allow main docs to be passed a direction in the front matter and have that automatically toggle LTR to RTL CSS inclusion
• The above items should resolve most of this, but... De-dupe the RTL CSS once moved
• Convert page content to Markdown
• And Add RTL support #30980 (comment)

Cheatsheet

• use buttons in cheatsheet side navigation, as it's been done in our main docs recently
• Fix the sticky components title covering the page content
• Fix floating labels example (remove row)
• Make the header a little less huge
• check and update translations in examples and cheatsheet

Docs

• check again I didn't break @mdo's changes to the docs
• ensure there's no missing occurrences of our old-fashioned classes (will take care of that when we'll be about to merge)
• Fix alignment utilities breakage https://deploy-preview-30980--twbs-bootstrap.netlify.app/docs/5.0/utilities/position/
• Search docs for left and right in case we missed something

Done

• add RTLCSS and dedicated scripts

Test cases

• convert some example templates to dir="rtl"—those on which direction makes a difference:
  • Album
  • Checkout
  • Dashboard
  • Blog
  • Carousel
• add lang="ar" (and hreflang="ar" in examples list)
• translate them to Arabic. (need help)
  • I used both Google Translate and an Arabic Lorem Ipsum generator—however I don't expect those to be either accurate or even good. I'll try to find proof-reader for this.
• Kitchen sink of sorts: all our components in one page, with its RTL counterpart.
  • Maybe use some kind of Hugo shortcode to ease this?
  • The Cheatsheet is available, next to the Migration page: https://deploy-preview-30980--twbs-bootstrap.netlify.app/docs/5.0/examples/cheatsheet/
  • its RTL counterpart exists (https://deploy-preview-30980--twbs-bootstrap.netlify.app/docs/5.0/examples/cheatsheet-rtl/), however it's not translated and it seems odd to try: I'll ask about it in a comment.
  • missing JavaScript for components,
  • and the directional dropdowns, popovers and tooltips to add.
• Update → Cheatsheet examples, to ease counterpart and translations:
  • https://deploy-preview-30980--twbs-bootstrap.netlify.app/docs/5.0/examples/cheatsheet/
  • https://deploy-preview-30980--twbs-bootstrap.netlify.app/docs/5.0/examples/cheatsheet-rtl/
• translate RTL cheatsheet to Arabic
• bulletproof testing, with the help of RTL Styling 101—focusing mainly on Things that might not work and RTL design considerations for common components
  • See the "Spotted bugs" comment above
• check with everything enabled (shadows, gradients, etc.)

Spotted bugs

• carousel arrows
• Card link isn't aligned properly. The margin-right: 1rem; should be margin-left: 1rem; (see comment below).
• disable word-break on RTL?
  • "Line break" section in RTL Styling 101 — I opened an issue to mention other word-breaking properties
  • see comment below
  • This required to introduce a new rtl boolean property in our Utility API, to add an RTLCSS remove directive around the utility.
• email and phone fields: it looks content-related to me, but we may have to provide a way to handle this.
  • "Form inputs" section in RTL Styling 101 — I opened an issue to mention other input types that may be concerned
  • see comment below
• Dropdowns, tooltips and popovers: their left/right variants aren't flipped for now, and ignored from RTLCSS (see comment below).

  • the default dropdown should follow the reading direction (Left/LTR and Right/RTL)

  • RTLCSS's Bootstrap fork (4.2.1) did something interesting
• rename variants for dropdowns, tooltips and popovers, in both SCSS and JS (eg. constants). I guess most data attributes would keep right and left since it's Popper based, but the Bootstrap layout could still use start and end to stay consistent.
• Breadcrumb separator now has a second variable $breadcrumb-divider-flipped to allow different separator for each direction.

Documentation

• Docs page (perhaps under Getting Started or Customize) to document how we build our RTL dist files. This should include how to build with these files (which is likely a small modification from the Customize docs) and edge cases
  • Breadcrumb separator: our current is a /: it's not changed to backslash (should it?)
    • moreover, this separator can be overridden to use an icon (typically, an arrow) which wouldn't be flipped: should we flip the separator, no matter what it is?
    • https://rtlstyling.com/posts/rtl-styling#breadcrumbs
    • see comment below
  • switching font-family for RTL (Boosted switches from Helvetica Neue to Helvetica Neue Arabic, for example)
  • drop letter-spacing if any ( https://www.rtlstyling.com/posts/rtl-styling/#1.-letter-spacing) → Irrelevant, we'll simply add RTL Styling 101 in additional resources.
  • how-tos with RTLCSS
• update RTL examples' screenshot
• mention rtl: {boolean} in Utility API doc
• mention RTL files in "Introduction", "downloads" & "Getting started" pages, at least

Chore things

• add files to SRI hashes and docs' _config.yml
• RTL: refactor using logical names #31210 — consider renaming things, ala Logical properties—to prevent .float-left { float: right; }. It would also help to switch to logical properties one day (when dropping Legacy Edge, v6 or tomorrow with Revisit our browserslist config #30986 ?)
• add RTL files to Bundlewatch
• double check the css-rtl task: something feels weird when it comes to start the docs, since it builds the dist then post-processes it for RTL.
• Missing a way to correctly handle modal's padding in two ways. I fixed a case but I guess there's more…
  • and it will obviously require new test, I guess?
• proof-read JS changes: I added a utility to check if document is using dir="rtl" and calling it where appropriate to toggle right / left.
• double-check package.json changes:
  • I duplicated css-minify to prevent a hundreds cols long script, but it's basically the same, split on two parts (standards + RTL)
  • I added a watcher for dist/css/ to reload when RTL files are compiled again (since they're not compiled from our sources but from our dist files)
• fix sourcemaps for RTL dist files
  • FWIW, sourcemaps are fine: there's a single path ending URL encoded, but it's not part of our sources: %3Cinput%20css%202%3E
  • I think it relates to the /*rtl:raw*/ directive, used for [type="email"] for example;
  • Other /* rtl:* */ directives are correctly mapped to their sources.
  • Opened an issue upstream to have some better understanding.
• (optional) run examples CSS through RTLCSS (dashboard, carousel, blog) to use a single source for both LTR & RTL
  • @XhmikosR I managed to make it work as intended, however I'm stuck with setting the full output path since glob patterns don't seem to work here (so we have /5.0/) in --dir and --base).
• check new examples' screenshot (old logo?)
• make a new dist PR separately before we land this one (Dist #32216)

Questions

• About the new Cheatsheet example: should we add introduction text before each component or section? → Probably not, since it's mostly a detailed view not meant to replace docs.
• I used RTLCSS block-level syntax for directives, but RTLCSS' fork used property-level syntax. Block-level is lighter to output and faster to parse, but make it less obvious of what is important to ignore for RTL. Should I move to property-level syntax? → Switched to property-level syntax, as argued in comments.

References

• RTLCSS documentation
• RTLCSS's Bootstrap fork
• Boosted scripts (css-compile-rtl and docs-rtl mostly)
• RTL Styling 101

Related

RTL concerns

#28797 #28238 #24807 #27123 #27122 #26879 #26818 #19545 #26299 #25422 #24662 #23703 #24332 #23117 #22708 #22137 #21619 #21180 #20293 #19555 #20075 #19787 #19703 #19668 #19643 #19545 #19379 #18184 #17595 #16455 #16419 #15717 #15700 #15509 #15479 #15433 #14717 #14510 #13564

Kitchen sink of sorts

#18645 #27783 #21209 #17423

[ffoodd]

@twbs/team Content strategy concerns here, before going further: how/where should we show and test RTL?

As a simple basis, I just duplicated our firt example, "Album" using a new examples-rtl.html layout and a condition to use bootstrap.rtl.min.css if the layout is used.

So, two questions:

1. should I keep going with those duplicated examples?
2. what about testing our components? How do we ensure future changes does not harm RTL version?
   1. do we provide some kind of sandbox or kitchen sink with every components in RTL?
   2. do we try to display RTL version alongside our current docs (with, say, something like an iframe with srcdoc—which could be handled via a shortcode)
   3. maybe need an entire new section for our docs?

"Duplicated" examples looks fine IMHO, since they also allow to translate content (which would be very valuable). But when it comes to component, I have no strong opinion ATM.

FYI, Boosted used a very ugly script to automatically duplicate examples and a sort of Kitchen Sink named "Boostwatch"—also available in RTL. None of those seems fine to me.

[mdo]

Regarding content strategy, I think we need at 2-3 pieces:

• Docs page (perhaps under Getting Started or Customize) to document how we build our RTL dist files. This should include how to build with these files (which is likely a small modification from the Customize docs).

• I don't think we need to do all our examples, but up to three sounds reasonable if we think it makes sense. One at the minimum.

• For testing components, I think this is where we need to create a kitchen sink of sorts—all our components and their most common (or least common lol) variations in one page. This then could be duplicated and shown with RTL enabled.

  This kitchen sink page has for sure been requested and is something I know the community would appreciate. Putting the right love into it could be something folks could rally around for customizing Bootstrap for their own needs, and extending it as needed.

  I think this page could live as an example, or as a top level page like Migration (docs/5.0/cheatsheet/).

[ffoodd]

I tried to automate the Cheasheet page by parsing our components' markdown files, finding examples via a regex (ala scss-docs shortcode) and displaying them. It somehow works, but seems like a dead end to me since our examples are done in multiple ways (including datas, loops, etc.), and some of them require either a few JavaScript or custom styles to work well, which I doubt being able to get easily.

So I'll go for a dedicated example, hand-managed for now: if anyone has any idea to improve this, feel free to mention or PR against this branch :)

Edit: For now, I manually wrap up component examples, trying to be both exhaustive and concise. I'm still missing Content, Forms and Cards.

[mdo]

This is so encouraging to see! <3

[ffoodd]

Note to myself:

• there's probably a way to use frontmatter for RTL layouts, instead of duplicate layout

[ahmadalfy]

Hello, I've extensive experience working with RTL and I've been using logical properties and values in production for almost four years with fallbacks. I wrote a couple of guides for RTL one of them is published on CSS Tricks and I would love to help. Any suggestions where can I start looking?

[ffoodd]

Hi @ahmadalfy, very glad to have some help!

At the moment, you may help by checking the five example templates I converted to RTL:

• Album
• Checkout
• Dashboard
• Blog
• Carousel

For now, I only ran out CSS through RTLCSS, and translated roughly their content to arabic (with tools).

So I guess there can be things to improve on a CSS side (already noticed the carousel arrows) and the arabic content can probably be improved.

There's not much more for now, I'm working on a full test page using every components: I think your experience will be extremely valuable when it's here, to find common issues and help fixing them.

Also, we'll need to document working with RTL, so feel free to share any ressource you wrote or any suggestion that may help people using Bootstrap to work with RTL: there're tons of things missing on this PR current roadmap, I guess.

Speaking about fallback for logical properties, does this mean physical properties? Or do you have another stratégie?

[ahmadalfy]

Hi @ffoodd

Will definitely check and share feedback if I have any. I can help with the documentation part for sure. Regarding the resources I wrote this article recently (Building Multi-Directional Layouts) about logical properties and values and how PostCSS plugins can help you use them now. I wrote another piece 6 years ago that still stands firm as well (Let's talk about RTL).

There is another excellent guide written by Ahmad Shadeed RTLStyling.com. It covers a lot more topics and can be considered a complete resource for anyone who wants to work with RTL languages.

Regarding your question about logical properties and values; yes, the fallback is done using physical properties. It's automatically translated using this PostCSS plugin.

Please feel free to ping me anytime you need anything.

[Tawfeekamr]

Hello there... I'm Tawfeeq Amro working with biggest Arabic website in World (www.mawdoo3.com), and I hope I can help you in Arabic proofreading, Arabic translation, technicality and more.

[kamel3d]

Hi,
I am a graphic designer (working for TV ) and web developer in my part-time, I could help you with Arabic translations and terminology since I was working on some projects online to improve the presence of the Arabic language on the web

[badrshs]

@ffoodd one of the problem that I found in your example in this url
https://deploy-preview-30980--twbs-bootstrap.netlify.app/docs/5.0/examples/carousel-rtl/

the arrows should point to outside not inside .. like this < ---- >

[Tawfeekamr]

@ffoodd one of the problem that I found in your example in this url
https://deploy-preview-30980--twbs-bootstrap.netlify.app/docs/5.0/examples/carousel-rtl/

the arrows should point to outside not inside .. like this < ---- >

This problem can be fixed by reflecting arrows transform: scale(-1);

or changing arrows positions (Better browser support):

.rtl .carousel-control-prev { left:0; }

.rtl .carousel-control-next { right:0; }

[badrshs]

or changing arrows positions (Better browser support):
thanks @Tawfeekamr

yep the second solution is better I think

[ahmadalfy]

or changing arrows positions (Better browser support):
thanks @Tawfeekamr

yep the second solution is better I think

That's actually a worse solution. This way you are moving the back button to the far left; which in Arabic should be on the right. What should be done is either using transform like @Tawfeekamr offered or to switch the pseudo content value of bootstrap font in Arabic.

fixed

[MartijnCuppens]

Looks fine to me. Well done!

[FaridAghili]

@ffoodd
In this url, please take a look at this:

I guess we should flip this chevrons like this:

Which can be done with transform: rotate(180deg):

Also the transform-origin can be increased to .6em to have more space between chevron and text.

[XhmikosR]

@FaridAghili please make a new issue, this PR is long enough as is.