Work In Progress

This book is currently work in progress. Some sections are not yet written. Thank you for your understanding!

Language files

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

  • The keys must always be in UPPERCASE. You cannot have keys in lowercase or MixedCase.

  • The values to the right of the equals sign must be enclosed in double quotes (").

  • If you want to use double quotes inside your values you need to escape them as \".

  • Some language strings are used in JavaScript code using a legacy method. They do not support escaped double quotes. Use single quotes (') instead, even for HTML attributes (yes, HTML allows you to do things like <a href=''>example</a> even though attribute values should use double quotes for compatibility with XHTML). If you want to put quotes around human-readable text you can also use calligraphic quotes: “ ” ‘ ’ and so on.

  • You can comment a line by putting a semicolon (;) as its first character. Do not put semicolons at the end of strings, they might be parsed as part of the value.

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:

  • Backend com_example.sys.ini — System language file. Required. Used to render the backend menu items and menu item types (for both front- and backend menu items).

  • Backend com_example.ini — Backend language file. Required. Used to render the backend interface and the component's Options page.

  • Frontend com_example.ini — Frontend language file. Optional (only if your component has a frontend part).

  • API com_example.ini — API application language file. Optional (only if your component has an API application integration).

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:

  • (Only if Debug Language is disabled). The language file for the site's default language (en-GB, unless a third party extension has changed it).

  • The currently active language's normative INI file (e.g. com_example.ini) or legacy INI file (e.g. en-GB.com_example.ini).

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:

  <!-- … -->
  <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>
  <!-- … -->

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:

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

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:

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

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.


This means that the language overrides cannot be used for language keys not defined in your language files, unlike Joomla 3.

Since this was a widely popular “trick” to allow your users to customise the display of your components you now have to take that explicitly into account. For example, given an item with an alias foobar you might be looking for the language string COM_EXAMPLE_ITEM_OVERRIDE_FOOBAR_TITLE to override the title field of your item for display in different languages. This worked in Joomla 3 but will NOT work in Joomla 4 or later.

You will need to provide an alternative mechanism for your users to provide custom translations. Remember the custom files I described just above? That's the alternative mechanism you can provide. DO NOT ship that file with your component. Just tell users to create it under their language folder and put their custom translations in there. It's far less user friendly than language overrides, unless of course you provide your own user interface for managing the contents of this file.

[4] Joomla started as a fork of another CMS called Mambo back in 2005. Mambo was originally developed by an Australian company. Australian and British English use the same spelling and are mostly the same, so that company chose to make British English the default language for Mambo. When Joomla forked off Mambo it retained the default language despite the fact that the majority of its co-founders were not even native English speakers.

For the longest time Joomla's default language files were a mix of British, American and mangled English (most contributors are NOT native English speakers) but as of Joomla 3.9 a lot of effort has been put in British English being actually British English. There are separate language packages for US American English (for those who prefer ‘colored trash cans’ to ‘coloured rubbish bins’, for example) and other English spellings / dialects.