Youjoomla Support Forums (
-   Joomla Tutorials (
-   -   Converting Joomla! Templates for Right to Left (RTL) Languages (

jaycburton 12-31-2009 09:12 PM

Converting Joomla! Templates for Right to Left (RTL) Languages
There seems to be some confusion surrounding this subject, so I decided to do some research and post my results in the forums in an attempt to eliminate (or at least remove much of) the confusion.

Making RTL sites with Joomla!

If you want to use your site's template(s) in Hebrew and Arabic, they must be designed for right-to-left writing. Some of the templates included in Joomla! 1.5 are "ambi-languagestrous", meaning they’ll detect if the text direction is RTL and deploy a special CSS file which overrides the usual (LTR) settings.

If you find yourself needing to convert an existing template to RTL, it will be necessary to get into the guts of the template. Also, please be aware that not all the third party add-ons will be compatible with your new text direction. In such a case, you can either see if the author will modify the existing add-on, or you may have to implement such changes yourself (or hire some to do it).

Here are the elements which must be changed:

- Template metafiles
- Text direction
- Text encoding
- Relative position of block elements
- Image direction

Step 1: Preparation

Quite simply, your goal is to create a mirror image of the original template. If possible, take a screenshot of the template before making any modifications, then do a horizontal flip using an image editor. This is a great visual aid to help you achieve your goal.

Before modifying anything, it is strongly recommended that you make a backup of your template files. The worst case scenario is you will have your original, unmodified files. However, this is better than having modified files that don't work, and being unable to revert to the unmodified original files.

IMPORTANT: Ensure your database tables are capable of handling the character encoding you’re using (probably UTF-8). If not, you’ll need to change them before you start. Note that this may break existing non-UTF-8 content.

Step 2: Meta Files

The templateDetails.xml file is in the template directory. Update the details (author, description etc) to reflect the new template details. You’ll also need to change the encoding to Unicode UTF-8. If you know you’re using another encoding, then adjust the details accordingly. If you are uncertain, use UTF-8, which works with most languages.

Open the index.php file, and make sure you save it as the same character set: utf-8 in this case. Use a text editor that will not change anything other than what you edited, such as Babel Pad or Notepad++.

Step 3: CSS Files

Elements on the Website's pages are positioned using the CSS files of your template. The more complex the template, the greater number of CSS files there will likely be. You can view your Website, then view the source code to see which CSS files are in use on any given page.

The CSS property 'direction: rtl' is the single command which will accomplish most of the work for you. It defines the direction, but does not affect the alignment. Change and reset this on your site, 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 scrollbar will appear on the opposite side of the window. You may also set it in a “container” DIV tag which holds the entire content, which means that the scroll bar will remain on the right, but the text will be altered.

Now you can work through the CSS files, starting at the top and working to the bottom. Along the way, you'll need to:

a. Replace all mentions of “left” with “right”, and vice versa. This applies to positioning directives such as:

- text-align: right;
- float: left;
- background: url(images/image.png) top right no-repeat;

DO NOT make these changes in style names, image names, etc. For this reason, avoid using search and replace. Generally speaking, everything between the {} brackets should be replaced.

b. Change the numeric values of margins, borders and padding styles:

- border: 10 15 20 25;
- padding-left: 0px;

For margins, borders and padding, the styles can be listed in two ways. The following are equivalent:

margin-left: 20;
margin-right: 5;
margin-top: 5;
margin-bottom: 5;


margin: 5 5 5 20;

In this shorthand form, the values are read top, right, bottom and left. It may help to think of an analog clock, and how the hands pass the 12:00, 3:00, 6:00 and 9:00 positions. There are other shorthand variations/combinations with three, two or even one number(s) after the property, but you don’t have to worry about these as left and right take the same value. For example, "padding: 10px;" which adds a 10px padding to all sides, and "padding: 10px 20px which puts 10px on the top and bottom, and 20px on the left and right.

These need to be altered wherever left and right values are different, and the values transposed. If you are uncertain how to use CSS shorthand, I would recommend using the longer form until the CSS files produce the desired results, then modify them individually, checking after each change to ensure nothing unexpected happens.

It may help to periodically check your progress by saving the CSS and reloading the Website. You may find it more convenient to perform these changes on a local development machine. At a minimum, I would recommend that the work not be done on a 'live' site which might be viewed by the public. You will probably be less frustrated if you are able to completely rewrite all the files in a single session.

Step 4: Check Your Work and Make Any Other Necessary CSS Adjustments

It is not uncommon to miss a few things during your first pass through the CSS files, depending on the complexity of your template. A useful tool for spotting such errors is a Web browser add-on which allows you to view your live Web pages and see the CSS being applied to any given element. Utilizing this tool, you can inspect is to find anomalies and adjust the CSS file accordingly.

If you are having difficulty locating something in a CSS file, don't overlook the index.php file. The properties you are looking to change could be hard-coded in there.

Step 5: Dealing with Images

a. Some (or all) of your images might have already been shifted around by the "left" and "right" changes you already made in the CSS files, especially those that use left or right as a background style [e.g. background: url(images/image.png) top right no-repeat;]. View your normal and mirrored designs to see which ones don’t look correct.

Specifically, the following are most likely in need of modification:

- Images which are positioned by the number of pixels from the left border
- Backgrounds that are positioned with the background-position property

If you have any of the following, they may need to be converted into percentage or pixel values instead, as it is somewhat more difficult to specify the distance from the right side of the page. For example, 0px from the left becomes 100% from the right, and 10px from the left becomes approximately 99% from the right on a 1024768 screen. You may be able to use other CSS properties as well to accomplish the desired position, including mixing more than one type, if necessary. It may require a little experimenting to get it just right (pardon the pun!).

b. Mirroring Images

Some non-symmetrical images can’t just be moved. You will need to mirror (also called horizontal flip or something similar) them in a graphics editor, and then re-save them with the same name (creating backups of the original files before modifying them is a good habit to practice). Alternately, you might need to flip the images vertically to make them look right on the site, sometimes they might need to be manipulated vertically and horizontally. Again, experiment until you achieve the desired results.

c. An extra challenge can appear when overlapping images, such as those in menus with rollover images, are present. You may find it necessary to modify the image as well as the CSS code.

Step 6: Sharing the Template Between RTL and LTR Languages

This is not only possible, but is easily accomplished by studying the example provided in the default beez template supplied with Joomla! 1.5.x. The relevant code is this:

<?php if($this->direction == ‘rtl‘) : ?>
<link rel=”stylesheet” href=”/blueprint_beez/<?php echo $this->baseurl ?>/templates/<?php echo $this->template ?>/css/template_rtl.css” type=”text/css” />
<?php endif; ?>

It should be obvious that this code will switch to the correct template file whenever RTL is detected. If your index.php file is the same for both LTR and RTL versions, then you can use this as well. This is a primary advantage of using CSS as much as possible for site design.

ahmedfouad 02-17-2010 03:47 PM

thank you sir for this useful information
i want to tack your permeation to publish this article in forum if it's ok please inform me
and please look at this link
Joomla! &bull; View topic - Joomla buzz, CMS and open source talk
thank you

jaycburton 02-17-2010 04:03 PM

Hi - I have posted about this in the Joomla! forums.

All times are GMT -4. The time now is 05:14 PM.

Powered by vBulletin®
Copyright ©2000 - 2017, Jelsoft Enterprises Ltd.