RTLize¶ ↑

RTLize allows you to write your stylesheets for left-to-right (LTR) layouts and have them automatically work for right-to-left (RTL) layouts as well. It does this by mirroring all the properties and values to their RTL equivalent.

RTLize doesn’t depend on any other gem and doesn’t tie you down to Rails or any other framework. However, it does work with Rails & Sprockets out of the box, and you’ll need to hook it up manually if you use a different stack, but it should be pretty simple to do so.

Using RTLize from the Command Line¶ ↑

First, you’ll need to install the gem:

gem install rtlize

Afterwards, you can use the ‘rtlize` command to flip your LTR stylesheets to their RTL versions (or vice versa)

rtlize application.css application.rtl.css

For more information on using RTLize from the command line:

rtlize -h

Using RTLize with your Web Framework¶ ↑

To use RTLize in your Rails or Ruby application, you’ll need to add it to your Gemfile (and then run ‘bundle install` of course):

gem 'rtlize'

Next you’ll need to make symbolic links (or copies if you must) of your stylesheets with the ‘.css’ extension replaced with ‘.rtl.css’:

ln -s sheet1.css sheet1.rtl.css
ln -s sheet2.css.sass sheet2.rtl.css.sass
ln -s sheet3.css.erb sheet3.rtl.css.erb
...

Finally, you’ll need to use the ‘dir` property on the `html` or `body` element in order to give your document the correct direction and have your RTLized document be mirrored properly once the RTLized CSS is applied to it:

<html lang="<%= I18n.locale %>" dir="<%= Rtlize.dir %>">

‘[dir=rtl]` is also used by RTLize as the default `rtl_selector` for targeting RTL content with your CSS.

Now when you request the assets ‘sheet1.rtl.css’ and ‘sheet2.rtl.css’ you will receive an RTLized version of the original.

Manually overriding CSS¶ ↑

When writing your CSS, you will often encounter cases where you need to manually override CSS for RTL layouts, to change a background image for example. To do this, you can use the ‘rtl_selector`. RTLize wont transform any CSS rules that use the `rtl_selector`.

For example:

.class-1
  margin: 1px 2px 3px 4px; // This will be transformed to "margin: 1px 4px 3px 2px"

// The following rules will not be transformed because they target RTL content using the rtl_selector

[dir=rtl] .class-2
  margin-right: 2px;

[dir="rtl"] .class-3
  margin-right: 3px;

[dir='rtl'].class-4
  margin-right: 4px;

// This will also not be transformed.
// Be careful not to write RTLizable rulesets that mix selectors that include the `rtl_selector` with others that dont.
[dir=rtl] .class-5, .another-class
  float: left;

Preventing some parts of your CSS from being transformed¶ ↑

You might also find that you need to prevent the layout from being flipped on certain parts of your website. To do this, you’ll need to tell the RTLizer about the CSS files/rules you don’t want switched. You can do this using the no-rtl directive. The way this works is that whenever the RTLizer finds the following comment:

/*!= begin(no-rtl) */

it will stop transforming all the CSS rules that follow until it reaches the comment:

/*!= end(no-rtl) */

after which transforming CSS will be turned back on.

A few issues to keep in mind when using the no-rtl directive is that, depending on your CSS preprocessor if you use one, you might need to add an extra !. You should also avoid adding those comments except at the top-level of your nested declarations for them to work properly. For example, using SASS, the no-rtl directives look like this:

.top-level-class
  .child-class-1
    margin-left: 1px // This rule will be transformed to "margin-right: 1px"

/*!!= begin(no-rtl) */
.top-level-class
  .child-class-2
     float: left // This rule wont be transformed
/*!!= end(no-rtl) */

.another-top-level-class
  span
    padding-right: 5px // This rule will be transformed to "padding-left: 5px"

RTLize in the wild!¶ ↑

Jawaker (an Arabic card game website) uses RTLize to automatically generate CSS files for the right-to-left (Arabic) layout of the website. You can get an idea of how RTLize works by comparing the English interface with the Arabic one. Jawaker utilizes all the main features of RTLize: most the CSS is layout-switched automatically, with some manually-specified switching for images. Also, some parts (the game table, for example) has the same layout in both Arabic and English (to preserve playing order).

TODO¶ ↑

Add examples, including a sample application.
Improve matching & documentation of the no-rtl directive.
Add helper methods in both Ruby & JS that would take a string (or a hash) of CSS declarations and convert them to the equivalent RTLized version. This is in order to extend the RTLization support to inline styles as well as dynamic CSS changes.

Versioning¶ ↑

This gem follows Semantic Versioning

Credits¶ ↑

RTLize was inspired by Dustin Diaz’s R2. In fact, initially RTLize was not much more than a ruby port of R2.

License¶ ↑

RTLize rocks and uses MIT-LICENSE.

maljub01 / RTLize