Skip to main content
Version: 5.3 (Upcoming)

Language Files

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"
note

It is recommended and good practice to use your MOD_XY, COM_XY or PLG_XY as Prefix for language keys

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:

Language Strings containing HTML Tags with escaped double Quotes
WARNING_TEXT="<span class=\"red\">Warning!</span>"

or with single quotes:

Language Strings containing HTML Tags with single Quotes
WARNING_TEXT="<span class='red'>Warning!</span>"
note

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.

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:

Language File
WARNING_TEXT="Warning!"
PHP Template File (where the language string will be used)
<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.

Language File Error with unescaped double-quotes
MOD_EXAMPLE_WORKING_HEADING="My Heading"
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:

Language File Error with missing double-quote on line 2
MOD_EXAMPLE_WORKING_HEADING="My Heading"
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.

Language File Error using Multi-Line
MOD_EXAMPLE_WORKING_HEADING="My Heading"
MOD_EXAMPLE_UNESCAPED_ERROR_MSG="<div class=\"error\">
<span>This will not work</span>
</div>"
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:

Language File Error with invalid language key on line 2
MOD_EXAMPLE_WORKING_HEADING="My Heading"
MOD_EXAMPLE WHITESPACE_ERROR_MSG="This will not be translated"
MOD_EXAMPLE_WORKING_SUCCESS_MSG="Success!"