International Enhancements for Version 1.6

From Joomla! Documentation

Language and International Enhancements for Joomla 1.6, 1.7, 2.5, 3.x

3-Letter Language Prefixes for Installation

In version 1.5, we are limited to language prefixes of 2 letters at installation time. i.e fr-FR and not fra-FR. In all other areas of Joomla!, we can use 3-letter language prefixes. Many languages in the world can't be accomodated with a 2 letters prefix. ISO gives each langage a prefix. For example "ast" for Asturian (Spain), "sla" for Montenegrian (Montenegro) etc. See

Joomla tries to propose a specific language for installing depending on the browser's settings. Let's say a browser is set to use Slovenian as preferred language (sl). If, among the installation languages proposed by Joomla, we have a 3 letters ISO code language which tag starts by "sl" - the prefix- (for example for Montenegrin sla-ME) and IF the sl-SI Slovenian language pack is not present among J! languages, then a Slovenian would be presented with a Montenegrian first install screen.

No browsers as of today include 3-letters ISO languages. The only solution to prevent this is to default all 3 letters code Joomla! languages to English in the first install screen. At that point, you can choose the correct language for installation.


The issue is not present when a user installs a customised distribution of Joomla as the installation language can be defined in the localise.xml file.

Default Latin Transliteration

Transliteration is used in Joomla! to automatically create or modify non-compliant aliases into ASCII strings. These aliases are used for creating SEF URLs. I.e the title of an article or menu item can be "Émergé", the auto alias will transliterate it into "emerge"

In 1.5, this transliteration would not know how to manage for Latin supplement, Extended A letters used in some central European countries and people had to modify manually their aliases when created automatically.

In 1.6 has been added a table to help take care of most Latin languages.

Note: As in 1.5, when non latin glyphs are entered in the Title field, alias field is left empty and Unicode slugs are not implemented (see below), the alias field will automatically be filled with the present date)

Custom Transliteration Support

For people who still want to use ASCII SEF but are not using a Latin language(Cyrillic, Greek,...) or with specific usage (some weird math glyphs, etc.) we have added the ability to override the default Latin transliteration by adding some code in a specific file called xx-XX.localise.php (use correct lang tag) in the core language pack for their language.

We have such a file and a sample table for Latin 1, Latin supplement , extended A, Cyrillic, Greek in the temporary xx-XX site language folder in 1.6 trunk (this language will be taken off when 1.6 reaches RC). It adds a table where all the said glyphs are transliterated to their ASCII counterparts, charge to the Translation Team providing the packs to make sure this transliteration is correct.

For example ω will be transliterated into an "o", etc.

Concerning the xx-XX.override.php see Making a Language Pack for Joomla 1.6.

All usage of this file is explained there in details.

Unicode URLs

Opposed to transliteration, one may now use natively in 1.6 Unicode urls. This parameter is defined in Global Configuration. This way of making aliases does not transliterate, it displays the utf8 glyphs instead of ascii. It uses Percent Encodings to display correctly (wikipedia:Percent-encoding).

Wikipedia demonstrates this in Persian:فارسي is in fact:

Browsers behave differently when copying such urls. Firefox will copy the unicode format while Opera will get the original glyphs. Google has no problem searching or referencing such links.

Language String Overrides

If you wish to change an existing value for a string present in the Joomla! core or for a specific extension, the only solution in version 1.5 was to edit the .ini file concerned and change the value of the string.

When updating the Core, the extension or a translated .ini file, your local changes can be overwritten if there are updates to the edited language file.

The new xx-XX.override.ini file has been created to avoid this issue. Instead of changing the original file, one can add any key already existing somewhere among all .ini files and a specific value to a file named for the language chosen (en-GB.override.ini, for example).

The file has to be administrator/language/overrides/en-GB.override.ini for the backend or language/overrides/en-GB.override.ini for the frontend.

For example, if you add the following key=value to the en-GB.override.ini file:

JSAVE="Save now!", it will replace the JSAVE="Save" throughout your site.

This file will not be uninstalled or overwritten when updating. Since the override file loads last, all keys present in your Joomla can be overriden.

Language Folder For Extensions

In version 1.6, language files can be added to a language folder under the extension folder. For example, mod_mymodule/language/en-gb/en-gb.mod_mymodule.ini.

Extension developers can choose this solution instead of adding the language files inside the core folders. This does not prevent adding translation of these files in the main core folder. Users have still to beware when uninstalling a language, since this will delete all ini files in the core language folders, included extension-related ones.

The new .sys.ini

The .sys.ini language files are used for extension description translations on the install and update screens. These files are used so that descriptions of all extensions in the system can be loaded at once. This avoids the overhead of loading and parsing full language files for every installed extension. If you only need the description or name of an extension, it is preferable to load the .sys.ini file instead of the .ini file.

The new sys.ini file replaces the .menu.ini in 1.5 and provides translation in some Managers.

As the 3pd can now include specific script at install time, the sys.ini is also used in case these scripts contain language keys.

The xml description in the sys.ini file is used at install time to display a message to specify the result of the install. This will work ONLY when the extension contains its own language folder. Example: language/xx-XX/xx-XX.nameofextension.sys.ini file

Look at the plugins/content/example/example.xml for details.

  • !! All extensions should have a xx-XX.nameofextension.sys.ini file

Langswitcher / Languagefilter

This is a simple multilingual solution provided by one module and one plugin. See the tutorial Language_Switcher_Tutorial_for_Joomla_1.6.

Pluralization Support for Translation Files

1.6 uses a new function JText::plural() for usual ones.

Code example:

$this->setMessage(JText::plural('COM_USERS_N_USERS_ACTIVATED', count($ids)));

will use the following ini strings:

COM_USERS_N_USERS_ACTIVATED="%s Users successfully activated"
COM_USERS_N_USERS_ACTIVATED_1="User successfully activated"

To which could be added for languages where the equivalent to the word "Users" is different for 0 and for multiple:

COM_USERS_N_USERS_ACTIVATED_0="0 (or No) users activated"


Concerning extremely customised languages where the value not only changes for zero, 1 and >1 but also for 5 for example (Russian) and depending of context, this is done in the same file xx-XX.localise.php stated above for transliteration.

See Making a Language Pack for Joomla 1.6

Support for Non-Gregorian Calendars

In the display of the date in front and back-end calendar fields, we need to be able to override the Javascript files used to render the dates. In version 1.6, we can now do that by installing custom Javascript in the media folder. That means that in version 1.6 Persian or other distributions no longer need to be hacked to get local calendar display and that these sites can be truly multi-language and permit switching and get the right calendar for the language concerned. This is done in the same file xx-XX.localise.php stated above for transliteration.

This needs to be done this way because MySQL accepts only Gregorian dates, thus the need to calculate when saving and when loading for these languages.

See Making a Language Pack for Joomla 1.6

Calendar icon: new parameter

This new meta parameter is set in the language xml file in each language pack.


means that Sunday is considered as the first day in the week.

For French or Italian it would be Monday


See Making a Language Pack for Joomla 1.6

New Search related parameters

The xx-XX.override.php is also used to define new parameters concerning search.

It replaces the xx-XX.ignore.php in 1.5 and includes new functionalities:

  • Define the words to not search for (as the ignore.php)
  • Define a lower limit and upper limit of characters to search for, in order to accommodate 2 bytes languages as Chinese.
  • Define the number of characters displayed in the results.

See Making a Language Pack for Joomla 1.6

Templates Need Only One Language File

Front-end templates using custom strings in the front-end need to have a separate language file for front-end in 1.5.

In 1.6 we need only one file which is loaded in both the front and back ends. This ini file will now load custom template override strings as well.