Add RTL Support to Joomla Templates

joomla rtlThe web can be difficult for speakers of right-to-left (RTL) languages such as Arabic, Persian, Urdu and Hebrew.

With RTL languages, writing starts from the right of the page and continues to the left. This means your template needs to be "mirrored" to support these languages.

However, many template designers aren't experienced with RTL issues and don't provide that option.

In this tutorial, we're going to show you how to adapt an existing Joomla template so it can be used as an RTL template as well as LTR.

Because we hope to reach as many designers as possible, we're going to use English on our RTL template. You don't have to know a RTL language in order to create an RTL-ready template.



Step 1. Prepare a local test copy of your website

The most secure and easy way to go about this is to not do this work on a live site, but to prepare a local test copy of your website.

  1. Install XAMPP, WAMP, MAMP or similar to set up a local server. Create an empty database in that local installation.
  2. Using Akeeba Backup, create a full backup of your website.
  3. Using an FTP client (like FileZilla or similar), copy the site backup and save it locally.
  4. Copy Akeeba kickstart.php to your local test site root.
  5. Copy the backup you created from your live website (.jpa file) to your local test site root.
  6. Point your browser to https://localhost/kickstart.php
  7. Follow the on-screen instructions to recreate a local copy of your live website.

Step 2. Copy your main template files to RTL template files

Find your main template and sub template files. Create copies of them and rename them to reflect their use.

For example:

  • "template.css" - copy to "template-rtl.css"
  • "ie9.css" - copy to "ie9-rtl.css"
  • "print.css" - copy to "print-rtl.css"
  • etc.

Step 3. Make sure you have a proper text editor installed

If you are on Windows, NEVER use Notepad or WordPad or Word to edit your text files. These save your files in a format which does not sit well with Joomla. Joomla language files for example need to be absolutely saved without a Byte Order Mark, or they will simply not work (and you go crazy finding out what is wrong).

So do yourself a favor and make sure you have a good UTF-8 capable coding editor installed, like PSPad or Notepad++, which will save your files in the proper format and without the BOM (Byte-Order-Mark). These editors come with many handy formatting functions, have code highlighting for many programming languages and can even do file side-by-side comparisons (diffs).

Step 4. What to keep and adapt in each RTL file

The RTL template files will be loaded INSTEAD OF the regular LTR template when an RTL language is active, so you need to have an entire duplicate of the normal template file with the needed changes for RTL. The Joomla core includes RTL-capability for the Bootstrap parts natively, so you don't need to specify those changes.

It is a good idea to mark changes for RTL with a comment in the CSS, like this:

/* RTL */

That way you can easily spot later on what was changed.

So what will you be looking for to keep and adapt in your RTL template files?

Remember, the site will have to look like it's seen in a mirror, so right becomes left and left becomes right.

  • Text direction
  • Floats
  • Padding
  • Margins
  • Shadows
  • Image alignments
  • Absolute and relative positioning

The best way to go about this is to do it manually. Avoid using search and replace, as it may change a lot more than you want. This process will be outlined a bit more in Step 8.

Step 6. Fake English as an RTL language in order to test

As mentioned, if you don't speak any RTL languages, installing RTL language packs is not an option for testing your RTL adaptations to the CSS. There is however an easy solution to make English (or any other LTR language) behave as if it was RTL.

In your local installation, find the file [joomlaroot]/language/en-GB/en-GB.xml

At the bottom of this file you find:

English (United Kingdom)en-GB0en_GB.utf8, en_GB.UTF-8, en_GB, eng_GB, en, english, english-uk, uk, gbr, britain, england, great britain, uk, united kingdom, united-kingdom0 





and save.

If you look at the site front end now, you will have an English language website behaving as if it was RTL for easy testing.

Once you are completely done, you set the switch back to 0 (zero) and save.

Step 5. Add RTL template recognition to your index.php

This is accomplished by studying the example provided in the Beez3 core template:

 if ($this->direction == 'rtl') { $doc->addStyleSheet($this->baseurl . '/templates/' . $this->template . '/css/template-rtl.css'); } 

This piece of code will switch to the correct template file whenever RTL is detected.

Step 7. Add text-direction to your template-rtl.css

The CSS property 'direction: rtl' is the command which will accomplish most of the work for you. It defines the direction, but does not affect the alignment. Add this to the template-rl.css and view then reload the pages to view the differences.

It is possible to set this property in the template’s BODY tag. If you do this however, then the scroll bar will appear on the opposite side of the window. You may also set it in a “container” DIV tag, then the scroll bar will remain on the right, but the text will be mirrored.

Just add:

direction: rtl;

in the body tag.

Step 8. Make your adaptations to template-rtl.css

Now it's time to actually make the needed changes outlined in Step 4.

  • Text direction. Done in Step 7.
  • Specific text alignment. "text-align: right;" becomes left and vice versa.
  • Floats. "float: right;" becomes "float: left;" and vice versa.
  • Padding. Padding-right becomes padding-left and vice versa. Short notation like "padding: 5px 10px 7px 12px" is top-right-bottom-left. Short notation like "padding: 5px 10px" is top-right, bottom same as top, left same as right.
  • Margins. Margin-right becomes margin-left and vice versa. Short notation like "margin: 5px 10px 7px 12px" is top-right-bottom-left. Short notation like "margin: 5px 10px" is top-right, bottom same as top, left same as right.
  • Shadows. Any CSS3 shadows need to be inverted. Notation is X-Y-Blur-Spread-Color (where X is horizontal and Y is vertical). Just give the X a negative value to invert the shadow. For example: box-shadow: -5px 5px 22px rgba(0, 0, 0, 0.15); /* W3C */
  • Image alignment. Floats need to be inverted. Absolute positioning needs to be inverted. Some images, like logos, will need to be flipped using an image editor and then specified as name-rtl.jpg or name-rtl.png in the template-rtl.css. Things like "background: url(images/image.png) top right no-repeat;" become "background: url(images/image.png) top left no-repeat;" etc.
  • Absolute and relative positioning. Left becomes right and vice versa.

Note: during the whole process, leave your template-rtl.css open in the editor and your site frontend open in a good browser. That way you can constantly check the effects of your changes in the browser by just pressing F5 or Ctrl+F5 to refresh the page.

Repeat the process for sub templates like print, browser specific css etc.

Step 9. Test in all major browsers

Test how your RTL site looks in all major browsers, and make any browser specific adaptations where needed.

Once done, don't forget to set the switch from Step 6 back to 0.

Step 10. Zip your template

Just zip you template once you're through, and you will now have a template that's RTL-capable.