Converting Joomla Templates for Right to Left (RTL) Languages.

There doesn't seem to be much information around the internet on this subject (well at least not in English), so I thought I'd post my notes here. I've been working on a Joomla 1.5 site with a client and they needed an Arabic site put up. I initially tried to do this using Joomfish translation agent, but didn't have much luck, so in the end we decided to put up a separate site. Here's how I did it.

Making RTL sites with Joomla

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

However, if you're stuck in the position of having an existing template to change to RTL, then you're going to have to get down and dirty with your template. In addition be aware that not all the third party add-ons will be compatible with your new text direction.

There are a few elements which must be changed.

– Template metafiles.
– Text direction.
– Text encoding
– The relative position of block elements.
– Image direction.

1) Preparation.

In effect, what you're aiming for is a mirror image of the original template. Take a screenshot of your tempate and do a horizontal flip in an image editor. This will help you visualise what you're aiming for.

Also make a backup of your template files, or copy them to another directory which you'll be working in.

Make sure that 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. This may break existing non-utf-8 content.

2) Meta files

The templateDetails.xml file lives 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 feel free to use this, but the chances are it will be UTF-8, which works across most languages.

Now open the index.php file, and make sure you save it as the same character set: utf-8 in this case. A text editor such as Babel Pad or Notepad++ will help you do this.

3) CSS file.

Elements on the page are positioned using the CSS files of your template. There may be several in more complex templates. Load a page from your website and look at the source code to see which ones are in use on any given page.

The CSS directive direction: rtl; is the single command which will do most for you. It will define the direction, but will not affect the alignment. Set this and unset this on your site, reloading the pages to see the difference.

It is possible to set this in the template's BODY tag. If you do this 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.

Now you can work through the CSS file from top to bottom and

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;

But NOT in style names, image names etc. This means you can't use search and replace. Basically everything between the {} brackets should be replaced.

b. Change the numeric values of margins, borders and padding directives eg.

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

For margins, borders and padding, the syntax can be done in two ways. The following are equivalent.
margin-left: 20;
margin-right: 5;
margin-top: 5;
margin-bottom: 5;
OR
margin: 5 5 5 20;
In this collapsed form, the directives are read top, right, bottom, left: imagine watching the second hand sweep around a clock. There are even more collapsed forms with three, two and one numbers after the directive, but you don't have to worry about these as left and right take the same value. (eg padding: 10px; which puts 10px padding on all sides, and padding: 10px, 20px which puts 10px on top and bottom, and 20px on left and right)

So, these need to be altered wherever left and right values are different, and the values transposed.

Check the site by saving the CSS and reloading the site periodically. Its really useful to do this on a local development machine. I found it best to work through in one sweep, top to bottom, checking every line.

4) Other adjustments in CSS

You may or may not have caught everything in your first pass through the CSS files, depending on the complexity of your template. A useful tool for picking up the stragglers is the Firefox Web Developer extension. It will let you view the CSS being applied to any element by hovering above it (CTRL-Shift-Y). Use this to find misbehaving text and adjust the CSS file.

If you can't find it in there, check the index.php file to make sure its not hardcoded in there.

5) Dealing with Images

a) Some (maybe all!) of your images will already have been shifted around by your transposition of left and right in the CSS. In particular the ones using left or right as a background directive. eg background: url(images/image.png) top right no-repeat;

Consult your normal and mirrored design to see which ones don't look correct.

You now need to fix those, specifically:

– Images which are positioned by number of pixels from the left border.
– Backgrounds, positioned with the background-position directive.

If you have any of these they will need to be converted into % instead, as there is no way of specifying the distance from the right of the page.
eg. 0px from left becomes 100% from the right.
eg. 10px from the left becomes approximately 99% from the right on a 1024×768 screen.
This has to be done by trial and error.

b) Mirroring images.
Some non-symmetrical images can't just be moved. You will need to mirror them in a graphics editor, and then re-save them with the same name. Sometimes you will also need to flip the images horizontally to make them work, sometimes vertically and horizontally. Refer to the mirrored design.

c) A special challenge is presented by overlapping images such as those in menus with rollovers. These you will probably need to flip and also change the CSS code.

6) Sharing the template between RTL and LTR languages.

This is possible and is done as an example in the beez template supplied with Joomla 1.5.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; ?>

What this does, clearly, is load a different css file if rtl is detected, so if your index.php file is the same for both ltr and rtl versions, then you can use this too. This is a key advantage of using CSS as much as possible for design.