Creating a language definition file

Joomla! 

3.x

series

General Information

Joomla! language definition files are written in the very basic INI file format. They must be saved using the UTF-8 encoding. Blank lines and lines beginning with ; are ignored and the latter may be used to add comments to the file. Each line consists of a key-value pair 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"

Different versions of Joomla have used slightly different ways to read language files (namely a custom parser and the native PHP INI parser, the latter of which was buggy in PHP 5.2 and older), leading to different rules for what exactly is allowed in keys and values. Language files that abide by the following rules should work under many versions of Joomla, but at least under Joomla and newer.

The KEY should only use ASCII characters. It should only contain capital letters, digits, underscores and hyphens, and it should start with a capital letter. (Dots (.) are formally allowed, but do not appear to be completely supported.) It is a convention to replace any whitespace in the string to be translated with underscores. If more than one entry has the same key, the last one to be encountered is the one that will be used. When you use the key in a JText::_ call, the case 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 value should always be surrounded by double-quote characters ("), as in the example. The value itself cannot include double-quote characters ("), although single-quote characters (') are valid. Use "_QQ_", including the double quotes, to place a double-quote character in your value. For example, to attach the value <span class="red">Warning!</span> to the key WARNING_TEXT, use following line:

WARNING_TEXT="<span class="_QQ_"red"_QQ_">Warning!</span>"

Note that these rules are stricter than required by the PHP INI parser. For example, the PHP INI parser allows you to omit the double quotes around the value as long as it does not contain certain characters. Using the rules above should make it much easier to avoid mistakes like forgetting double quotes when they are required.

Information about the changes in the language file format between the Joomla 1.5, 2.5 and 3.x series can be found on the page Specification of language files.

---