In the previous article in the series: Joomla 4 Templating Part 1: The Manifest, we looked at setting up the manifest file: templateDetails.xml for the simple template.

In this article, we'll be looking at how to set up the language folder for the template.

How to Setup Language

Firstly, inside the parent language folder you will put in another folder for each language you want to use. So for English, you'd have a folder: en-GB. For German, you'd have a folder: de-DE, and so on.

Each of these folders will contain the same 2 files. For the simple template they would be named:

  1. tpl_simple.ini - language strings for the template itself
  2. tpl_simple.sys.ini - language strings for overriding components

Both files will initially contain language strings for the name of the template (in our case: simple) and the template description. So if were using both the English and German language files:

en-GB (folder)

Contains: tpl_simple.ini and tpl_simple.sys.ini. They will be the same before we start adding more language strings.

de-DE folder

Contains: tpl_simple.ini and tpl_simple.sys.ini. They will be the same before we start adding more language strings.


Each language string must be on it's own line (depending on your device size, the graphic above may show line breaks which is misleading).

What Language Strings go Where?

To begin, both tpl_simple.ini and tpl_simple.sys.ini will have the same 2 lines. As you add more language strings, you'll need to decide which of these two files they belong in.

You can use language strings throughout your template, both for rendering on the frontend or the backend. You could, for instance, use a language string for a button text, a template instruction or even your site's phone number! A good rule of thumb is to put language strings you intend to render (backend/frontend) into the tpl_simple.ini file. (And if you're using multiple languages, that means into the tpl_simple.ini under each language folder.)

index.php (template)
∕∕Access Text functions
use Joomla\CMS\Language\Text;
<button><?php echo Text::_('TPL_SIMPLE_CLICK'); ?></button>

tpl_simple.sys.ini is used for an entirely different purpose than tpl_simple.ini. It's used to create custom layouts from Joomla core components that will be available as layout choices from the menu. The language strings in this file are used to replace tags in the core layout so that they are renamed and recognised as belonging to your theme. The system also knows where to look for your override which would be in your template's html folder. An example would be creating a customised version of the default Category Blog layout.

Put language strings that you want rendered to text into tpl_simple.ini, NOT tpl_simple.sys.ini

In the first article in this series, we added a user parameter into the templateDetails.xml file which referenced this language string to the simpletemplate:
TPL_SIMPLE_GOOGLEFONTS="Please enter the url for your chosen google fonts"

Since that string will be rendered into text we need to put it into the tpl_simple.ini file.

TPL_SIMPLE_GOOGLEFONTS="Please enter the url for your chosen google fonts"

Folder Structure

For the purposes of an installable template, we would create a folder: language and set up the structure as follows if we were using both English and German:

language (folder)
  -en-GB (folder)
  -de-DE (folder)

The placeholders in language/en-GB/tpl_simple.ini and language/de-DE/tpl_simple.ini will be identical in both files, just the translation would be different. And the same is true for tpl_simple.sys.ini in both language packs.

The language folder itself would be placed into the tpl_simple folder as described in the first article in this series.

Also, as mentioned in that article, our install method will result in the language folder being placed into the /templates/simple folder, rather than into the Joomla's own /language/ folder. I prefer it that way because the language strings will be updated if we re-install the template with amended strings.

You need to have at least one language for the template to work

What's Next?

In the next article in this series about Joomla 4 templating, we will take a look at the Web Asset Manager.