008. Using languages files

In this chapter we will ...

Even if your target audience for your Joomla! component only speaks English, it is important to use a language file for all the text that is displayed in the front end or the back end of your component. Because, this makes it easy for a user to create a language override and change the displayed text of your component without having to edit any of the source code.

Now we are working on Joomla! being able to display your component automatically in different languages - multilingual.

Newly created or Modified files

Newly created files

administrator/components/com_foos/language/en-GB/en-GB.com_foos.ini

administrator/components/com_foos/language/en-GB/en-GB.com_foos.sys.ini

components/com_foos/language/en-GB/en-GB.com_foos.ini

Modified files

changelog.xml

foo_update.xml

administrator/components/com_foos/foos.xml

components/com_foos/Model/FooModel.php

components/com_foos/tmpl/foo/default.php

All changes at a glance

https://github.com/astridx/boilerplate/compare/t7...t8

More detailed explanations

The front end and the back end have their own language files. Unlike in the front end where there is only one file, there are two files in the back end. Shortened explained the sys.ini language file is used for translating your installation XML file, as well as your menu items. The ini file is used for the rest of the back end of your component. More detailed explanations can be found at the end of this text.

File Structure

Newly created

Now create the https://github.com/astridx/boilerplate/blob/t8/src/administrator/components/com_foos/language/en-GB/en-GB.com_foos.ini file and add the following lines:

The left-hand side of the equals sign in the language string is always in uppercase. Usually it starts with the extension name, in our case with COM_FOOS. After that you include a short description of what this language string is for. Make sure, that you do not use any space, only uppercase characters and underscores are allowed. The right-hand side of the language string is enclosed within speech marks, and is the actual text displayed on the site. When your extension is translated into another language, the translator only needs to change this right-hand side of the language string in their new language file.

Modified files

Example in Joomla 4

Side Note

What if you need to use double quotes in your language string?

Because the text is shown within speech marks, if you need to use double quotes you can insert __QQ__.

Where should the language files be stored?

The core components store their back end language files in the /administrator/language/en-GB/ folder and their front end language files in the /language/en-GB/ folder. This is the first place, Joomla! searched for the language files. Because of this it was common for extension developers to put their language files in here, too. However, sometimes it is easier to put them within your component folder. In our cast this is the folder /administrator/components/com_foos/language/en-GB for the back end and /components/com_foos/language/en-GB for the front end. The is the place where Joomla! searches for the language file if it does not find any in /administrator/language/en-GB/ or /language/en-GB/.

What does Joomla need for multilingualism?

Note that the primary language of Joomla is British English. Other languages need separate translation files. So, Joomla speaks English. If you want to support multilingualism, you have to at least provide English language files.

In case you are not familiar with Joomla extensions,

• the source admin language folder contains two file: en-GB.com_foos.ini and en-GB.com_foos.sys.ini, which contains the translated values of fixed strings,
• the source site language folder contains one file: en-GB.com_foos.ini, which contains the translated values of fixed strings,

used to allow translation from English into other languages.

The folder structure is simple:

- language                 - the folder containing the language translation files
-- en-GB                   - the folder containing English translations
--- en-GB.com_foos.ini     - the file of translated keys

And the files are contain the translations in a special format:

For each line, the first part is a key and the second part is its value, the English translation should contain one line for every string that is displayed in a view. For example, the text in the description for creating a menu item should be a key in the source code and translated. In the English file this could be

COM_FOOS_FOO_VIEW_DEFAULT_TITLE="Single Foo"

So you write the text COM_FOOS_FOO_VIEW_DEFAULT_TITLE in the source code an show the text Single Foo in the front end of an English Joomla installation. For a German translation you have to create the file com_foos/language/de-DE/de-DE.com_foos.ini with the line

COM_FOOS_FOO_VIEW_DEFAULT_TITLE="Ein Foo"

So, you probably already suspect it. Ein Foo means in German Single Foo and if Joomla is to display the German language and the German language file is available, then unlike in English Single Foo the German version Ein Foo is displayed.

What is the difference between *.ini and *.sys.ini?

The sys.ini file has 3 roles:

• It provides the translation strings for the installation/updating process as well as the de-installation process.
• From 1.6+ it replaces the old extension.menu.ini for component menu items.
• It is used by various Joomla! managers to display the translated name of your extension.

The .ini file is used to translate the remaining strings and the description when viewing your extension in the Joomla! back end.

Where does Joomla look for language files?

Debugging

Test your component

Now you can zip all files and install them via Joomla Extension Manager. After that you can see a link to your component in the left side menu. Clicking on this link will open the basic back end view.

Concluding Remark

Now we have . Up to now we have no . We are going to work on this in the next chapter.

Overview of all files