Making templates translateable

Joomla is a truly international application and supports the translation of all strings contained within it. Templates are no exception on this. They are a bit neglected, but a little extra time spent here will ensure that the strings used in your templates are translatable will pay back - and will give you an edge over your competitors.

The language translation system has been designed to be as simple and error-proof as possible. For example, even if a language file is missing, or a particular string has not been translated, Joomla will transparently fall back to showing the untranslated string. There are also some useful tools built into Joomla itself to assist translators in creating a new translation.

Location of template language definition files

Language definition files for front-end templates are stored in

[path-to-Joomla]/language/[ln-LN]

where [ln-LN] is the language code. Language codes are defined in RFC3066. The file must be named

[ln-LN].tpl_[template-name].ini

where [template-name] is the name of the template (in lowercase). For example, the British English language file for the Beez template is

[path-to-Joomla]/language/en-GB/en-GB.tpl_beez.ini

You should also create a separate language file for translating the Administrator back-end of your template. This will be stored in

[path-to-Joomla]/administrator/language/[ln-LN]

but the file naming convention is the same.

For administrator templates, as distinct from front-end templates, the second of these files is the only one required. For example, the British English language file for the Khepri administrator template is located in

[path-to-Joomla]/administrator/language/en-GB/en-GB.tpl_khepri.ini

Creating a language definition file

Important note: Joomla language INI files must be saved as UTF-8 without the Byte Order Mark (BOM).

The format of language definition files is very basic. Blanks lines and lines beginning with “#” are ignored and the latter may be used to add comments to the file. Each line consists of a pair of strings separated by an equals sign like this

KEY=Value

where “KEY” is a string to be translated and “Value” is the translated string. For example

ADDITIONAL INFORMATION=Additional Information

The “KEY” must be in all capitals or the string will not be found. The case of the source string does not matter as strings are folded to upper case before searching takes place. So “additional information”, “Additional Information” or even “AdDiTiOnAl InFoRmAtIoN” will be matched.

The “KEY” can include spaces and other punctuation characters but there should not be any spaces either side of the equals sign as spaces are significant. If more than one entry has the same left-hand side, the last one to be encountered is the one that will be used.

The "VALUE" cannot include double-quote characters ("). To get a double-quote character you must use the HTML special character sequence """ instead. Single-quote characters (') are valid.

More information about the changes for Joomla 1.6/1.7 can be found on the page Specification of language files

Amending the templateDetails.xml file

To ensure that your template is fully internationalized you must make sure that certain XML elements are translated and that the language definition files are listed in the templateDetails.xml file.

Translating templateDetails.xml

A couple of the elements in the templateDetails.xml file are used in the Template Manager and are themselves translatable. These should always be translated.

name Name of the template. For example, Beez
description Description of the template.

These fields are also shown to the user during template installation.

Adding language definition files to templateDetails.xml

All language files must be declared in the templateDetails.xml file. This is done by adding two <language> elements for each language to be included with the template; one for the front-end strings; the other for the administrator back-end strings. For example, the two British English language files and the two German language files for the Beez template are declared as follows

<?xml version=”1.0” encoding=”utf-8” ?>
<install version=”1.5” type=”template”>

 
     .........
 
    <languages>
        <language tag=”en-GB”>en-GB.tpl_beez.ini</language>
        <language tag=”de-DE”>de-DE.tpl_beez.ini</language>

    </languages>
 
     .........
 
    <administration>
        <languages folder=”admin”>
            <language tag=”en-GB”>en-GB.tpl_beez.ini</language>

            <language tag=”de-DE”>de-DE.tpl_beez.ini</language>
        </languages>
    </administration>
 
</install>

Note that in the administration <languages> tag the folder attribute is used. This is because the language files for the front-end and back-end have the same file names and so cannot exist in the same directory within the template package file. In this example, the administration language files have been placed in a sub-directory called admin to separate them from the front-end language files.

Embedding translatable strings in the template

In the template itself translations are handled using the JText static class. It is referred to as “static” because it does not require instantiation as an object before its methods may be used.

Simple text strings

Most text strings can be translated using the “_” (underscore) method. For example, suppose your template contains the English text “Welcome” which needs to be made translatable.

<?php
    echo 'Welcome';
?>

Then you would replace the static string like this

<?php
    echo JText::_( 'Welcome' );
?>

This would cause the translation system to search the appropriate language file for “WELCOME” on the left-hand side of an equals sign. The search is case-insensitive. If this language definition string is encountered

WELCOME=Welcome!

then the effect will be to output the string “Welcome!” to the browser. If the user switches to the German language then the German language definition file will be searched for “WELCOME” and this time might encounter the string

WELCOME=Willkommen

and so “Willkommen” will be sent to the browser. Importantly, if the user switches to German but there is no German language file present, or the appropriate string does not appear in the German language file, then Joomla will fall back to sending the untranslated string “Welcome” to the browser, also preserving its original case.


It is so pleasant to work with experts. Learn more to find out more regarding best vape pens.