|Line 94:||Line 94:|
This article or section is incomplete, which means it may be lacking information. You are welcome to assist in its completion by editing it as well. If this article or section
This page explains the changes of the language file specification from version 1.5 to 1.6,1.7 & 2.5. As this is currently under development it is not merged back to the central specification page.
The 1.5 specification is described in Creating a language definition file.
Additional information from a new thread
So, the implications on ini file format:
Typical comment and string:
; A comment COM_KEY_CONSTANT="My value is "_QQ_"great!"_QQ_". I like it"
Note: If your INI format is invalid, the results are not well defined. Most versions of PHP will load your language file up to the point where an error occurs, but throw no error message whatsoever.
Note: Only ASCII characters are supported in language keys
Using the native php ini parser for language files has many benefits including much faster performance.
Basically, you have two options:
Note from nikosdion: I have written a reliable Joomla! 1.5 to Joomla! 1.6 language converter which abides to these conventions. You can find it at my Snipt page
All language files follow the naming convention language.extension.ini. For example, the Great British English translation file of com_foobar is named en-GB.com_foobar.ini.
Translation files are stored inside the respective system-wide language directory. For example, front-end language files for GB English are stored inside language/en-GB. So, the front-end GB English translation file of com_foobar has a full path of language/en-GB/en-GB.com_foobar.ini. Likewise, its back-end translation has a full path of administrator/language/en-GB/en-GB.com_foobar.ini. You must specify system-wide translation files in your extension's XML manifest file, otherwise they will not be installed. These system-wide language files are loaded first by Joomla!. In order to place your language files in your XML manifest file, you can use the same syntax as with Joomla! 1.5, i.e.:
<languages folder="path/to/language"> <language tag="en-GB">en-GB/en-GB.com_foobar.ini</language> <language tag="en-GB">en-GB/en-GB.com_foobar.sys.ini</language> </languages>
Each extension can also have "local" translation files, inside its own front- or back-end directory. For example, you can have a language ini for GB English in administrator/components/com_foobar/language/en-GB/en-GB.com_foobar.ini. These "local" files do not need to be mentioned in your extension's XML manifest file. In fact, a user can always create a language directory inside your extension's directory, create a sub-directory named after his language and inside it create a language INI file with his desired language overrides.
Joomla! extension's must also specify a sys.ini file which is used a. during the extension's installation, to allow localising the post-installation messages, b. to build the administrator Components menu, c. to localise component parameters and menu parameters and d. in the Extension Manager->Manage. These follow a similar naming convention with the main language files and can be stored in the site's back-end. If they are only stored there, their strings will not be used when installing. For example, com_foobar's GB English sys.ini file is stored in administrator/language/en-GB/en-GB.com_foobar.sys.ini and its variant in administrator/components/com_foobar/language/en-GB/en-GB.com_foobar.sys.ini. IMPORTANT! For the sys.ini to load automatically upon installation it MUST be stored inside the extension's directory. In other words, a system-wide sys.ini file WILL NOT be loaded upon installation. If there is only ONE sys.ini file present in the extension language directory, that one will be loaded for back-end normal usage. IMPORTANT! the ini files stored system wide ALWAYS override the ones stored in the extension language folder, except for the sys.ini at installation time. One can therefore have 2 sys.ini files. Also using different values for the manifest key <description>COM_FOOBAR_XML_DESCRIPTION</description> in the sys.ini file from the extension language folder used at installation and the ini file will provide a different display when editing the extension.
The menu item shown in the Components menu always comes from the translation key COM_FOOBAR for a component named com_foobar (that is, your component's installation directory uppercased). This is substantially different than the way Joomla! 1.5 menu.ini files used to work!
The best way to wrap your head around these conventions is to download a popular Joomla! 1.6 compatible extension from the JED and analyse its contents, in the true Free and Open Source Software spirit.
Joomla! automatically loads the translation files when you are accessing a component. In order to load arbitrary language files in your extensions, you can use the following code:
$language = JFactory::getLanguage(); $language->load('com_yourcomponentname');
Note from elkuku: Or shorter using PHP 5's chaining:
Another cool trick you can do is to load arbitrary front-end and back-end language files of any component and language. For example, you may want to load the English language file and mix it with the user's current language. This means that untranslated strings will appear in English and not as untranslated keys. You can use something like this for the back-end language files:
$language = JFactory::getLanguage(); $language->load('com_yourcomponentname', JPATH_ADMINISTRATOR, 'en-GB', true); $language->load('com_yourcomponentname', JPATH_ADMINISTRATOR, null, true);
And to load the front-end language files, using the same trick:
$language = JFactory::getLanguage(); $language->load('com_yourcomponentname', JPATH_SITE, 'en-GB', true); $language->load('com_yourcomponentname', JPATH_SITE, null, true);