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.com_example.ini (British English), de-DE.com_example.ini (German, Germany) and de-AT.com_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.com_example.ini, de-DE/de-DE.com_example.ini and de-AT/de-AT.com_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 com_example.ini. The language of the file is inferred from the folder name it's in. For example, the filepath en-GB/com_example.ini obviously refers to British English.

Component language files

A component has multiple different language files. The base name of all files is the name of the Joomla component extension, e.g. com_example:

The language files are placed in the respective application's language subdirectory. For example, the backend language files for British English are placed in administrator/language/en-GB. Moreover, Joomla will fall back to the language subdirectory under your component. For example, the backend language files for British English are also sought for in administrator/components/com_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 component's language files automatically.

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 current application's language folder i.e. administrator/language for the backend, language for the frontend and api/language for the API application.

If neither the current language's, nor the default language's files have been found Joomla will fall back to your component's language directory. That is to say, your component'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 components are required to provide a complete language file for the default language which for Joomla is British English^[4] (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 COM_EXAMPLE_ITEMS_SELECT_CATEGORY_DEFAULT_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 per target application.

For the backend language files, you need to list them under the <administration> tag:

<administration>
  <!-- … -->
  <languages folder="languages/admin">
    <language tag="en-GB">en-GB/com_example.ini</language>
    <language tag="en-GB">en-GB/com_example.sys.ini</language>
    <language tag="de-DE">de-DE/com_example.ini</language>
    <language tag="de-DE">de-DE/com_example.sys.ini</language>
  </languages>
  <!-- … -->
</administration>

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

For the frontend language files, if you have any, you need to list them directly under the <extension> tag:

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

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

For the API application language files, if you have any, you need to list them under the <api> tag:

<api>
  <!-- … -->
  <languages folder="languages/api">
    <language tag="en-GB">en-GB/com_example.ini</language>
    <language tag="de-DE">de-DE/com_example.ini</language>
  </languages>
  <!-- … -->
</api>

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

Languages and CLI

CLI commands do not load any language files automatically. You can either supply your language strings in the console plugin which registers the commands or, more commonly, include them in your backend language file and have the plugin load that language file when registering the commands.

Custom language files

Beyond the regular .ini / .sys.ini files you can have any other language file you want. For example, you could have a com_example.alt.ini file which is only loaded when a specific option is enabled in your component. You can do that in your component's Dispatcher. For example:

$this->app->getLanguage()->load($this->option . '.alt', JPATH_BASE)
  || $this->app->getLanguage()->load($this->option . '.alt', JPATH_COMPONENT)

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.