Joomla! Programmers Documentation

This section describes the use of language files for extensions. 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:

KEY="value"

where KEY is a string to be translated and value is the translated string. For example:

COM_EXAMPLE_ADDITIONAL_INFO_LABEL="Additional Information"

Conventions & Specifications for Language Keys (Constants)¶

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 language string (KEY) with underscores. Another specification is to avoid spaces around the equal operator (=) between the KEY and the value.

Language Keys should always be unique. To ensure this, something like the following structure should be used for language keys:

1. Extension Type => COM (Components) / MOD (Modules) / PLG (Plugins)
2. Extension Name / Shortcode => EXAMPLE (Example Extension Name)
3. Element Identification (Field, Button, Header, ...)
4. Type of Element (Label / Description / ...)

So if we have a Key for our Field Label & Field Description which selects the Font-Color in our Example Component we should define the Language Keys like this:

COM_EXAMPLE_FONT_COLOR_FIELD_LABEL="Font-Color"
COM_EXAMPLE_FONT_COLOR_FIELD_DESCRIPTION="Select the Font-Color for xy"

And for a Button Label in a My News Module the Language Key could be named like this:

MOD_MYNEWS_LEARN_MORE_BTN_LABEL="Learn more"

Conventions & Specifications for Language Values¶

The Value should always be surrounded by double-quote characters ("), as in the example. Every double-quote character in the value string has to be escaped by using a Backslash (\). For example, to attach the value <span class="red">Warning!</span> to the key WARNING_TEXT, it can be written like this:

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

or with single quotes:

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

HTML in Language Values¶

It is not recommended to use HTML in the translations. HTML Syntax should be placed outside the language strings in the appropriate place:

WARNING_TEXT="Warning!"

<span class="red"><?php echo Text::_("WARNING_TEXT"); ?></span>

Case Sensitivity when using with Text::¶

When you use the key in a Text:: 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. Nevertheless, it is a convention and also considered good practice to write the key in capital letters within the PHP or JavaScript code.

Language Tags¶

If language files are written for an extension, these must be stored in a corresponding subfolder (with a language tag) in the extension. Joomla! then moves the files to the correct directories while the extension gets installed / updated.

The folder structure is languages / [languageTag]/ *.ini where the the language tags such as "en-GB", "de-CH", and "de-AT" are based on the ISO 639-1 and ISO 3166-1 codes. These represent a combination of a language and a regional or national variant. In Joomla! these language tags are used as subfolders in the languages folders.

These tags consist of two parts:

• The first part is the language code from the ISO 639-1 standard, which denotes the language. Examples:
  • en for English
  • de for German
  • fr for French
  • it for Italian
  • ...
• The second part is the country code from the ISO 3166-1 Alpha 2 standard, defining the country or region to distinguish specific dialects or regional settings. Examples:
  • GB for the United Kingdom
  • US for the United States
  • CH for Switzerland
  • FR for France
  • AT for Austria
  • ...

Errors in Language Files¶

If there is an error in a language file, the file is not parsed correctly and individual translations are missing. It is then helpful to examine the corresponding language file with a code editor with syntax highlighting that can process the INI file.

Unescaped Double-Quotes in the Value String¶

The most common error in language files for Joomla! occurs when a value is not encapsulated by double quotes or when there are unescaped double quotes within the value.

MOD_EXAMPLE_WORKING_HEADING="My Heading"
// highlight-next-line
MOD_EXAMPLE_UNESCAPED_ERROR_MSG="<span class=\"error">Oh no an Error</span>"
MOD_EXAMPLE_NOT_WORKING_SUCCESS_MSG="Success!"

Missing Double-Quotes at the end of a Value String¶

Another common mistake is "forgetting" a double quote at the end of a translation string, as here in line 2:

MOD_EXAMPLE_WORKING_HEADING="My Heading"
// highlight-next-line
MOD_EXAMPLE_UNESCAPED_ERROR_MSG="<span class=\"error\">Oh no an Error</span>
MOD_EXAMPLE_NOT_WORKING_SUCCESS_MSG="Success!"

Multi-Line Values¶

As mentioned above Multiline values are not valid - a correct key="value" pair is only valid if it is single-line.

MOD_EXAMPLE_WORKING_HEADING="My Heading"
// highlight-start
MOD_EXAMPLE_UNESCAPED_ERROR_MSG="<div class=\"error\">
<span>This will not work</span>
</div>"
// highlight-end
MOD_EXAMPLE_NOT_WORKING_SUCCESS_MSG="Success!"

Invalid Language Keys¶

If the language key (constant) does not correspond to the specifications, the key cannot be used:

MOD_EXAMPLE_WORKING_HEADING="My Heading"
// highlight-next-line
MOD_EXAMPLE WHITESPACE_ERROR_MSG="This will not be translated"
MOD_EXAMPLE_WORKING_SUCCESS_MSG="Success!"