Translation Files

Introduction

Translation files hold the defines used in the manifest file i.e. the ".xml" associated with installling a module or a plugin, and return the text which it is wished to present on screen.

In essence translating is very easy. One simply replaces "some text" with a DEFINE, and the replacement of the DEFINE with "sometext" is held in one of two .ini files which have have two purposes and are named [NAME being just a name] as follows:

NAME.sys.ini - which is always read when Joomla starts up.
NAME.ini - which is read when the module or plugin is configured.

Structure of the ini files

The best way is by showing an example or two.

Starting with the XML file which is where the defines are created, for example, this is the code for a spacer field:

Thus the convention for naming the defines seems to be: TYPE_NAME_TEXTID. The name for a content plugin is PLG_CONTENT_plugin-name, and this is used in both naming the two translation files, and the defines within them.

The system ini file will therefore be named: TYPE_NAME.sys.ini, and the configuration file TYPE_NAME.ini

So the TDOCGMAP ini file is named: plg_content_tdocgmap.ini

It is good practice to put some definition information in the file as well, thus an example for the ini file starts with:

;; TDOC Gmap
;; Ver 4.2.1 of 12th March 2022
;; Language file for Options: plg_content_tdocgmap.ini

And the example define used above is shown as:

PLG_CONTENT_TDOCGMAP_DEFAULTS="Default Settings"

It is conventional to use UPPERCASE for all the defines, although in fact lower case does seem to work.

Personally I use NOTEPAD that come with Windows 7 Pro, and have saved the file in the UTF-8 format which works ok. In fact it seems as if the ANSI option works as well... better to safe than sorry and use UTF-8 for the files and UPPERCASE for the defines.

Content of ini files

First the sys.ini file:

There are two defines required: The extension [Plugin or Module] Name and Description as follows:

PLG_CONTENT_TDOCGMAP="TDOC Google Maps"
PLG_CONTENT_TDOCGMAP_XML_DESCRIPTION="Plugin to display KML files in Google Maps"

The matching items in the Manifest file are:

<name>PLG_CONTENT_TDOCGMAP</name>
<description>PLG_CONTENT_TDOCGMAP_XML_DESCRIPTION</description>

Second the .ini file:

This contains all the other defines, such as:

PLG_CONTENT_TDOCGMAP_DEFAULTS="Default Settings"

Each of which is matched by an entry in the Manifest file, e.g.

Styling and Content options

These have been learned by examining the sigplus ini files - just install and have a look at the basic settings. My thanks to Levente Hunyadi whose image gallery I rely on.

The html code that works includes:

Making the text bold by using the tag typically as follows:
PLG_CONTENT_TDOCGMAP_DEFAULTS="Default Settings"
Inserting a new line using the tag.
Making text italic by using the tag
Keeping text together by using  
Add an external link by using the <a> tag and a URL typically as follows:
PLG_CONTENT_TDOCMAP_URL="<a href='http://tdocplus.co.uk/' target='_blank'>Home Page</a>"
Add an instruction for exampl;e by using the <kbd> tag which presents white text on a black background, e.g.
PLG_CONTENT_TDOCMAP_CALL="<kbd>tdocgmap kml='http://tdocplus.co.uk/lp_routes/lp_snuff_white_west.kml'</kbd>"
Note: the { }'s wrapping the path to the kml file are missing - otherwise one would see a map !
And lastly, the use of the <code> tag to illustrate an entry, for example:
BASE_FOLDER_DESCRIPTION="Set the base folder as<code>images</code>"

Some Notes

Important: For modules the contents of the sys.ini file must also be included in the .ini file.

Location of ini files: There are two other places where language files can be held, but for modules and plugins it is now conventional to hold them in the associated directory which is typically as follows:

Modules - e.g. for the module named: mod_tdocfbk:

..\modules\mod_tdocfbk\language\en-GB

Plugins - e.g. for the content plugin named: plg_content_tdocgmap

..\plugins\content\tdocgmap\language\en-GB

Beware: When modules are updated, the name and descriptions first used appear to be always used, except when a module title is updated using the edit in the Site Modules.

Other Locations - seem now to be deprecated ?? The principle one for modules and plugins which is now apparently redundant is:

..\language\en-GB

The same rule is applied to administrator components such as Akeeba Backup, so it seems that the following becomes redundant:

..\administrator\language\en-GB

Some screen shots

Acknowledgements etc

On the Joomla Forum, pe7er, and ceford who set me straight. Thanks guys.

Joomla Documents: https://docs.joomla.org/Manifest_files