RTL Developer Guide

Owned by Andy Armstrong (Deactivated)
Last updated: Jul 23, 2021 by David Joy (Deactivated)

This page captures the considerations and best practices for supporting right-to-left languages.

Table of Contents

Sass

edX's legacy UIs (primarily Django templates and pre-micro-frontend interfaces) mostly use 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.

Note that for micro-frontends and bootstrap pages, edX instead uses rtlcss which automatically converts an LTR-based CSS file by flipping any directional rules. In micro-frontends, this happens as part of the webpack build via PostCSS plugins (See https://github.com/edx/frontend-build for more details on the MFE webpack build) 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

Testing Your Feature

To test your changes, see the instructions here: Internationalization Coding Guidelines: Coverage Testing