Creating a language definition file

From Joomla! Documentation

This page contains changes which are not marked for translation.
Other languages:
Deutsch • ‎English • ‎Nederlands • ‎español • ‎français • ‎português • ‎русский

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 a semicolon (;) 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:


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 on Joomla Joomla 3.x 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 \, 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=\"red\">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 such as forgetting double quotes when they are required.

Note also that from Joomla 4.4.1 and 5.0.1 each value can only be one line of text. Hard linebreaks invalidate the whole language definition file.