...translating Joomla! power and simplicity in any language...

Preface

This translation guide constitutes an introduction to the language system in Joomla! 1.5 and its purpose is to assist language pack developers in getting started.

Core Language packs

In Joomla! 1.5 the complete core localisation for a particular language consists of:

1. A language pack for the front-end site. This consists of a xml metadata file, a xml installation file, individual language files for front-end framework, core components, core modules, core plug-ins and a suitable set of PDF font files for the language. This pack can be packaged for installation by the Joomla! extension manager.
2. A language pack for the administrator interface (back-end site). This consists of a xml metadata file, a xml installation file, individual language files for back-end framework, core components, core modules and core plug-ins.
3. A language set for the Joomla! installation application. This consists of a single language file and a xml metadata file. This set cannot be packaged or installed and is provided as part of the installable Joomla! package.

Language File Formats

Prior to Joomla! Version 1.5, site translation was handled by a single php file for each language using php constants. In version 1.5 the file format has changed to the ini file format which is much simpler. For example:

ALIAS=translated text string

Note that the ALIAS must be in all uppercase.

In English, the alias and the text are typically the same for short words. For longer words and phrase, the alias may be a shortened key to reference the full phrase. For example:

YES=Yes
NO=No
ERRORNONAME=Please enter a name
TIPCOPYFROM=Select an existing language to copy to create the new files

All of the ini files should be encoded and saved as having UTF-8  encoding. The BOM is not required and should not be used. (BOM stand for Bit Order Marker and is a small header to indicate that the said file is using UTF-8 encoding. This can cause errors in a PHP web application and is not used or required. Some editors offer to add BOM)

Language naming convention

Starting with Joomla! 1.5 language packs have a standardised naming convention using a combination of [language-code]-[COUNTRY-CODE] format such as en-GB, en-US or fr-FR.The ‘language-code’ is based on the ISO-639-1 standard for 2 letter language codes (always in lowercase), ISO-639-2 if none exists in ISO-639-1. The ‘COUNTRY-CODE’ is based on the ISO=3166 standard for 2 letter country codes (always in uppercase).

Language file organisation

In prior versions the files for all languages were stored in the /languages folder. Starting with Joomla! 1.5 each language pack or set is placed in an individual sub-folder under the /languages folder. Each language folder uses the language naming convention for its name. i.e. /languages/en-GB.Language files are also divided into their components or modules. If you look a language folder you will see many files, like:

en-GB.ini

en-GB.com_content.ini

en-GB.com_contacts.ini

The languages files are divided up to improve performance and address scalability by allowing for custom components, plug-ins and modules to be able install their own language files. The files are also grouped in the one specific language directory to ease the maintenance of the files (Joomla just has to look in one place for them).

Creating a new language pack

The method to create a new language file is to copy the original English files, to change their file name prefix to the new language code and then edit all the texts after the equal signs. You MUST keep the ALIAS the same in your new files.

To create an entire pack the following checklist should be followed:

• Create a new sub-folder under /languages or under /administrator/languages depending which pack is being prepared.
• Copy all en-GB files from the sister folder to the new folder.
• Change all file prefixes with the en-GB language name to the new language name (i.e. heb-IL).
• Translate all texts to the right of the equals sign in all ini files. Save files with UTF-8 NO BOM encoding .
• Edit the xml metadata file to reflect the required information for the language. (See following section).
• Edit the installation xml file to reflect the language identity and the correct file names (change prefixes).
• In the case of the front-end language pack the PDF font name needs to be set in the metadata xml file and the file names of the font set (3 files) need to be inserted to the appropriate tags in the installation xml file.
• Prepare the zipped language pack. The zip should include all ini files, the two xml files and in the case of the front-end pack, also the 3 PDF font files.

The metadata xml file

<?xml version="1.0" encoding="utf-8"?>
<name>English(GB)</name>
<version>1.5.0</version>
<creationDate>2005-10-30</creationDate>
<author>Joomla! Project</author>
<authorEmail> This e-mail address is being protected from spam bots, you need JavaScript enabled to view it </authorEmail>
<authorUrl>www.joomla.org</authorUrl>
<copyright>(C) 2005 - 2006 Open Source Matters. All rights reserved.</copyright>
<license>http://www.gnu.org/copyleft/gpl.html GNU/GPL</license>
<description></description>
<metadata>
<name>English (GB)</name>
    <tag>en-GB</tag>
    <rtl>0</rtl>       
    <locale>eng_GB, en_GB, en, english, english-uk </locale>        <pdfFontName>vera</pdfFontName></metadata>

Description of the metadata values:

• name – This is the descriptive (normal) name for the language
• tag – This language tag following the RFC 3066
• rtl – Set to 1 for a language that displays Right-to-Left, otherwise set to 0
• locale – list of locale codes that are Operating System specific and passed by PHP to the OS. The first code recognised by the OS will be the one that is used. (Codes can and should include a .utf-8 suffix i.e. ‘heb_IL.utf-8’; list utf8 locale codes first)
• pdfFontName – the name of the PDF font set to use (lowercase only)

The Joomla! Translation API

There are two API's for translation static text in Joomla!
In PHP, Joomla! provides you with a static class named JText. This class has a number of methods but by far the one you will use most is the _ (underscore) method which is a mimic of the gettext shortcut that is built into php. It is used like this:

$title = JText::_( 'Users' );
<?php echo JText::_( 'DescControlOutputElemenets' ); ?>

In the first example, the API will look for an alias in the language file called USERS. If it finds a match it will return the text associated with that alias. If it doesn't find a match, it will simply return the text passed to it. In the second example we are using an alias for a long phrase. Note that the text passed to the method is not case sensitive.

In HTML files (used by patTemplate) there is a translation tag that you wrap your text in, for example:

<h2><jtmpl:translate>FTP Configuration</jtmpl:translate>:</h2>

<jtmpl:translate key="tipFtpConfSteps">
    <p>Due to filesystem permission restrictions and PHP Safe Mode restrictions.
    For all users to utilize the Joomla! installers an FTP layer exists to handle
    filesystem manipulation.
    <br />
    <br />
    Enter an FTP username and password with access to the Joomla! root directory,
    this will be the FTP account that handles all filesystem operations when Joomla!
    requires FTP access to complete a task.
</jtmpl:translate>

The two examples above perform exactly the same as the php examples. Note that using the patTemplate tags, we do see the relationship between the alias and the text for long phrases.
Language Manager

Debugging Localised Text Elements

The language API gives you some ability to debug screens and language files. Enable debugging via the Debug Tab on the Global Configuration screen.

When you turn debugging on, the translation API displays some codes around text. Following are the possible codes and their meanings:

•Modules• - Text items with bullets either side. This means that the text has been passed through the translation function and that a match has been found.

??Modules?? -  Text items with question marks on either side. This means that the text has been passed to the translation API but there is no entry in the language file.
 
Modules – Text items with nothing on either side (debug enabled). This means that this text has not been passed to the translation API and will not be translated.

Language Selection

There are two levels of language selection from among the installed languages:
1. Default language setting for the site and default language setting for the administrator section (different language can be set)
2. User preferred language for site and user preferred language for the administrator section

Guests (non logged in users) will view the site interface in the default language. If a user logs in and has defined a preferred language the site (or the back-end) will display in the user’s preferred language. If a user has not defined preferred languages the site or back-end will display in the default language when the user logs in.

For example, the default setting for you web site may be English. Mary is a registered user from France. Through the ‘My Details’ form, she is able to select French (providing it is installed). John is an Administrator from Germany. He can change his personal details so that he sees both the web site interface and the Administrator in German.