Specification of language files

From Joomla! Documentation

Other languages:
English • ‎español • ‎français • ‎Nederlands • ‎português • ‎中文(中国大陆)‎
Split Page into Specific Joomla! Versions - J2.5 and 3.x

It has been suggested that this article or section be split into specific version Namespaces. (Discuss). If version split is not obvious, please allow split request to remain for 1 week pending discussions. Proposed since 4 years ago.

Quill icon.png
Content is Incomplete

This article or section is incomplete, which means it may be lacking information. You are welcome to assist in its completion by editing it as well. If this article or section has not been edited in several days, please consider helping complete the content.
This article was last edited by Tom Hutchison (talk| contribs) 4 years ago. (Purge)

This page explains the changes of the language file specification from version 1.5 to 2.5. As this is currently under development it is not merged back to the central specification page.

The 1.5 specification is described in Creating a language definition file.

Overview of changes in Joomla 3.2 Joomla 3.2

Starting with Joomla! 3.2, en-GB is automatically load first, then the xx-XX language strings. This is to ensure there is always a fallback to a string value. What this does is prevent the display of a 'constant' if the xx-XX language ini file is broken or a translation string is missing.

Overview of changes in Joomla 2.5 Joomla 2.5

  1. The KEY is now defined to be
    1. without any whitespace. All whitespace shall be converted into a underscore '_'
    2. All KEY's in the frontend shall include a prefix of the extension

Additional information from a new thread

So, the implications on ini file format:

  1. As previously mentioned, our keys will have to change. Spaces are not allowed. The general practice will be to use underscores for spacing. Also, the plan is to name space strings, so that you would end up with something like COM_EXAMPLE_MYKEY for your key. According to the php manual, The characters {}|&~![()^" cannot be used in keys. There are also reserved words for keys: null, yes, no, true, false, on, off, none. Note: the COM_EXAMPLE_ prefix is not mandatory as of Joomla! 1.6/1.7, but it is advisable to follow this convention to avoid naming collisions with other extensions.
  2. The syntax for the value has also changed. According to the PHP manual, if a value in the ini file contains any non-alphanumeric characters it needs to be enclosed in double-quotes ("). That will basically mean all of our values will have to be enclosed in quotes, as a space is non alpha numeric. If you want to include a double-quote in your string, you can use an html entity like " or the default "_QQ_". Finally, according to the PHP manual, the {}|&~![()^" characters have a special meaning in the value. Unfortunately, they don't really unpack what that special meaning is - anybody have experience in this area? Reply from infograf768: My guess is that they can't be used if not enclosed in double quotes. Note from nikosdion: I concur with infograf768's comment. Also, all translation strings should be in double quotation marks.
  3. Comment syntax has changed, as we are typically using pound signs (#) and the standard parser requires semi colons (;). Note from nikosdion: you MUST use semicolons, otherwise your language files will not load.

Typical comment and string:

; A comment
COM_KEY_CONSTANT="My value is "_QQ_"great!"_QQ_". I like it"

Note: If your INI format is invalid, the results are not well defined. Most versions of PHP will load your language file up to the point where an error occurs, but throw no error message whatsoever.

Note: Only ASCII characters are supported in language keys.

Updating your Joomla 1.5 language files to work on Joomla 2.5

Using the native php ini parser for language files has many benefits including much faster performance.

Basically, you have two options:

  1. The Eclipse solution (or any other Coding Platform), extremely easy as well:
    1. Search your file for *.ini in your project of choice. Then use the following search/replace values to automatically, replace exisiting quotes, add quotes to string values and update your comments
    2. Double quotes are now not allowed and this can be easily bypassed by searching " and replace with '
    3. Put a closing double quote at end of line if not empty or a comment. Find ^((?!#).+)\R replace with $1"\R
    4. Put an opening quote at start of translated string if not empty or comment. Find ^((?!#).+?\=)(.+)\R replace with $1"$2\R
    5. Now replace the hash comments with the new semi colon. Find ^# and replace with ;
    6. Remove any illegal strings that can prevent files loading. Find ^(null|yes|no|true|false|on|off|none)=(.+)\R and replace with nothing.

Note from nikosdion: I have written a reliable Joomla! 1.5 to Joomla! 1.6 language converter which abides to these conventions. You can find it at my Snipt page

Language file naming conventions and precedence

All language files follow the naming convention language.extension.ini. For example, the Great British English translation file of com_foobar is named en-GB.com_foobar.ini.

Translation files are stored inside the respective system-wide language directory. For example, front-end language files for GB English are stored inside language/en-GB. So, the front-end GB English translation file of com_foobar has a full path of language/en-GB/en-GB.com_foobar.ini. Likewise, its back-end translation has a full path of administrator/language/en-GB/en-GB.com_foobar.ini. You must specify system-wide translation files in your extension's XML manifest file, otherwise they will not be installed. These system-wide language files are loaded first by Joomla!. In order to place your language files in your XML manifest file, you can use the same syntax as with Joomla! 1.5, i.e.:

<languages folder="path/to/language">
   <language tag="en-GB">en-GB/en-GB.com_foobar.ini</language>
   <language tag="en-GB">en-GB/en-GB.com_foobar.sys.ini</language>

Each extension can also have "local" translation files, inside its own front- or back-end directory. For example, you can have a language ini for GB English in administrator/components/com_foobar/language/en-GB/en-GB.com_foobar.ini. These "local" files do not need to be mentioned in your extension's XML manifest file. In fact, a user can always create a language directory inside your extension's directory, create a sub-directory named after his language and inside it create a language INI file with his desired language overrides.

Joomla! extension's must also specify a sys.ini file which is used

  • a. during the extension's installation, to allow localising the post-installation messages,
  • b. to build the administrator Components menu,
  • c. to localise component parameters and menu parameters
  • d. and in the Extension Manager->Manage.

These follow a similar naming convention with the main language files and can be stored in the site's back-end. If they are only stored there, their strings will not be used when installing. For example, com_foobar's GB English sys.ini file is stored in administrator/language/en-GB/en-GB.com_foobar.sys.ini and its variant in administrator/components/com_foobar/language/en-GB/en-GB.com_foobar.sys.ini.

IMPORTANT! For the sys.ini to load automatically upon installation it MUST be stored inside the extension's directory. In other words, a system-wide sys.ini file WILL NOT be loaded upon installation. If there is only ONE sys.ini file present in the extension language directory, that one will be loaded for back-end normal usage.

IMPORTANT! the ini files stored system wide ALWAYS override the ones stored in the extension language folder, except for the sys.ini at installation time. One can therefore have 2 sys.ini files. Also using different values for the manifest key <description>COM_FOOBAR_XML_DESCRIPTION</description> in the sys.ini file from the extension language folder used at installation and the ini file will provide a different display when editing the extension.

The menu item shown in the Components menu always comes from the translation key COM_FOOBAR for a component named com_foobar (that is, your component's installation directory uppercased). This is substantially different than the way Joomla! 1.5 menu.ini files used to work!

The best way to wrap your head around these conventions is to download a popular Joomla! 1.6 compatible extension from the JED and analyse its contents, in the true Free and Open Source Software spirit.

Loading any language file, anywhere

Joomla! automatically loads the translation files when you are accessing a component. In order to load arbitrary language files in your extensions, you can use the following code:

$language = JFactory::getLanguage();

Note from elkuku: Or shorter using PHP 5's chaining:


Another cool trick you can do is to load arbitrary front-end and back-end language files of any component and language. For example, you may want to load the English language file and mix it with the user's current language. This means that untranslated strings will appear in English and not as untranslated keys. You can use something like this for the back-end language files:

$language = JFactory::getLanguage();
$language->load('com_yourcomponentname', JPATH_ADMINISTRATOR, 'en-GB', true);
$language->load('com_yourcomponentname', JPATH_ADMINISTRATOR, null, true);

And to load the front-end language files, using the same trick:

$language = JFactory::getLanguage();
$language->load('com_yourcomponentname', JPATH_SITE, 'en-GB', true);
$language->load('com_yourcomponentname', JPATH_SITE, null, true);

Related discussion threads in the development mailing list