This page captures the considerations and best
...
practices for supporting right-to-left languages.
Flipping the Sass
...
Table of Contents
| Table of Contents |
|---|
Sass
EdX mostly uses Bi-App-Sass to help flip our UI for languages that read right to left. The primary
...
CSS properties that are involved in flipping are float, margin, padding, text-align, positioning, and borders. When you are using these properties in the edX platform, you should check whether it will need to be flipped for right-to-left languages. If so, use the bi-app mixins instead of the regular property: value syntax
...
.
...
Testing Your Feature
To test, spin up your local dev environment and visit the webpage of your feature. In a different browser, or an incognito window, visit the feature again (log in as a different user, if logins are needed). In the second view, append the following string to the end of the url: ?preview-lang=rtl (if you are working on master; if you are behind master, use ?preview-lang=ar).
This will switch your session's language to a dummy RTL language, or Arabic if you are not up to date with master. If you must test in Arabic and it is a released language on your dev environment, instead just switch your user's profile language to Arabic. Navigate your feature in the English webpage and the RTL webpage simultaneously. You should see that all elements in the RTL version mirror the English version.
Note that certain page elements may not look right because they are controlled by the browser. For the best testing, switch your browser's language to Arabic or another RTL language (Hebrew, Persian, or Urdu) as well.
Reach out to us on the edx-code mailing list if you have any questions about testing.
Other Considerations
Note that for Bootstrap pages, edX instead uses rtlcss which automatically converts an LTR-based CSS file by flipping any directional rules. This is preferable to Bi-App-Sass because almost all rules will "just work" as expected for RTL languages, so there is no need to use special mixins. If there are issues with the automatic translation, comment-based declarations can direct rtlcss as to how to specify the RTL rule. See RTLCSS: Control Directives for more details.
Semantics
An HTML document is a stand alone piece of content that should have a language and character set attribute set early in the DOM. In addition, adding an attribute defining the language direction should be part of the DOM, either on the document as a whole, or on the specific pieces of content that read right to left or left to right. Changing the display language should change any of those attributes that apply. And, as always, structure your HTML in a logical order (main content first, supplementary content following) and with proper semantic structure (sections, headers, etc) to make it readable and adjustable for various contexts. (Turn off css to check that the document flow is logical.)
Dev actions: Structure your HTML semantically; set language and character attributes early in the DOM
Visual Layout
In addition to indicating that the raw document content should be read right to left, the visual layout of the page should change to accommodate a change of language and language direction: content written in RTL languages should appear right aligned (and vice versa). For full page changes, main content should appear to the right, sidebars of supplementary content should shift from right to left, "previous" arrows should point right (and "next" to the left). Form field content should fill from right to left as well.
Dev actions: Visually check that layout flips
HTML
The W3C recommends adding the language direction attribute (dir="rtl") on the root (html) element to define the language direction of the document. Because some browsers incorrectly switch the location of the scroll bar to the left as well, current best-practice is to add the dir="rtl" to the <head> tag and to a <div> wrapping the whole page to flip the entire document (which is an alternate recommendation by W3C) to ensure that the scrollbar isn't flipped.
Note: Flexbox-based layouts will automatically flip based upon the specified language direction on the page. See https://css-tricks.com/snippets/css/a-guide-to-flexbox/ for details.
Dev actions: Add dir="rtl" to head element and highest content-wrapping div element; add dir="ltr" to any URL or file location text elements
SASS/CSS
There are a variety of ways to use css to change the direction of text, but some are better than others, and following some best-practices can help alleviate trouble later. Most importantly, using "display: inline-block;" correctly when laying out pages can allow the document or element direction property on the document or specific html elements (dir="rtl") to reverse the layout as well as the content. Also, setting equal margin/padding on both sides of elements when possible is better than having to explicitly flip. (thanks to Integralist for the gist of this!)
...
Testing Your Feature
To test your changes, see the instructions here: Internationalization Coding Guidelines: Coverage Testing