Dionysopoulos.me

The Joomla language files have not really changed much since Joomla 1.0. Joomla is using the INI format with a few twists:

No more language tags in filenames

There is a pretty big change for language file naming in Joomla 4 and beyond: you must not use the language prefix.

In Joomla 1.5 to 3.10 inclusive language files were named like en-GB.plg_system_example.ini (British English), de-DE.plg_system_example.ini (German, Germany) and de-AT.plg_system_example.ini (German, Austria).

However, that naming was highly redundant as starting with Joomla 1.6 in 2010 the language files had to be placed in a folder whose name was the language tag itself! Inside a language folder you'd have the relative filepaths en-GB/en-GB.plg_system_example.ini, de-DE/de-DE.plg_system_example.ini and de-AT/de-AT.plg_system_example.ini. Having the same language tag appear twice in a pathname didn't make sense. Therefore in Joomla 4 and beyond we no longer use the language tag prefix!

The files are now simply named similar to plg_system_example.ini. The language of the file is inferred from the folder name it's in. For example, the filepath en-GB/plg_system_example.ini obviously refers to British English.

Plugin language files

A plugin has multiple different language files. The base name of all files is the name of the Joomla component extension, e.g. plg_system_example(the two latter parts separated by underscores is the plugin type a.k.a. folder and the plugin name, in all lowercase):

Plugin language files are placed in the administrator application's language subdirectory — even for plugins which ONLY run in the frontend of the site! For example, the language files for British English are placed in administrator/language/en-GB. Moreover, Joomla will fall back to the language subdirectory under your plugin. For example, the language files for British English are also sought for in plugins/system/example/language/en-GB. If files exist in both locations then only the one in the application's directory will be loaded.

Language file autoloading

Unlike previous versions of Joomla, you do NOT have to load your language files manually. Joomla loads your plugin's language files automatically.

All you need to do is set the protected property autoloadLanguage to true in your constructor:

public function __construct(&$subject, $config = array())
{
    $this->autoloadLanguage = true;

    parent::__construct($subject, $config);
}

If you prefer to load the language files of your plugin only when they are absolutely needed you just need to call:

$this->loadLanguage();

Since Joomla 3.3 (based on my recollection, +/- 1 minor version…) Joomla will load language files in this order:

Joomla will first look in the administrator application's language folder i.e. administrator/language . This applied even if you are in the frontend of the site, the API application or the CLI application.

If neither the current language's, nor the default language's files have been found Joomla will fall back to your plugin's language directory. That is to say, your plugin's language directory is a last resort and not guaranteed to be used!

You may wonder: why does Joomla load both the default language (British English in most cases) and my current language (e.g. Canadian French) files? The reason is simple. All plugins are required to provide a complete language file for the default language which for Joomla is British English (en-GB). Translation to other languages are optional and often incomplete. Sometime around 2012 we decided that it makes far more sense to show an English, human-readable string to non-English speakers they can look up in the dictionary or their favorite translation tool than an incomprehensible language key like PLG_SYSTEM_EXAMPLE_CONFIG_EARLY_PREP_ARRAY_LABEL. Of course this makes it harder for translators. That's why the Debug Language feature was simultaneously introduced. When enabled, the default language is not enabled and untranslated strings are marked clearly in the output.

Defining language files in your XML manifest

Your XML manifest needs one set of <languages> tags under the <extension> root:

<extension>
<!-- … -->
<languages folder="language">
    <language tag="en-GB">en-GB/plg_system_example.ini</language>
    <language tag="en-GB">en-GB/plg_system_example.sys.ini</language>
    <language tag="de-DE">de-DE/plg_system_example.ini</language>
    <language tag="de-DE">de-DE/plg_system_example.sys.ini</language>
</languages>
<!-- … -->
</extension>

This copies the files from the language/ folder in your package to Joomla's admin language folder, e.g. the language/en-GB/plg_system_example.ini file in your package to administrator/language/en-GB/plg_system_example.ini file on your site.

Language overrides

Language overrides are loaded before any of your language files, at the initialisation of the CMSApplication object, namely when the Language object is constructed. They are stored in the file language/overrides/LANGUAGE_TAG.override.ini under the application's root (site root for the frontend, administrator for the backend, api for the API application) where LANGUAGE_TAG is the current language's tag, e.g. en-GB for British English.

The way it works is that your language file is loaded and then the overridden strings are replaced into the language file if and only if they are already defined in the language file.