Specification of language files

出典: Joomla! ドキュメンテーション

Languages:

English  • 日本語

This page explains the changes of the language file specification from version 1.5 to 1.6/1.7. As this is currently under development it is not merged back to the central specification page.

1.7 is not introducing any changes in these 1.6 specifications.

The 1.5 specification is described in Creating a language definition file.

== Overview of changes in Joomla 1.6 ==

1. The KEY is now defined to be
   1. without any whitespace. All whitespace shall be converted into a underscore '_'
   2. All KEY's in the frontend shall include a prefix of the extension

Additional information from a new thread

So, the implications on ini file format:

1. As previously mentioned, our keys will have to change. Spaces are not allowed. The general practice will be to use underscores for spacing. Also, the plan is to name space strings, so that you would end up with something like COM_EXAMPLE_MYKEY for your key. According to the php manual, The characters {}|&~![()^" cannot be used in keys. There are also reserved words for keys: null, yes, no, true, false, on, off, none. Note: the COM_EXAMPLE_ prefix is not mandatory as of Joomla! 1.6/1.7, but it is advisable to follow this convention to avoid naming collisions with other extensions.
2. The syntax for the value has also changed. According to the PHP manual, if a value in the ini file contains any non-alphanumeric characters it needs to be enclosed in double-quotes ("). That will basically mean all of our values will have to be enclosed in quotes, as a space is non alpha numeric. If you want to include a double-quote in your string, you can use an html entity like & quot; or the default "_QQ_". Finally, according to the PHP manual, the {}|&~![()^" characters have a special meaning in the value. Unfortunately, they don't really unpack what that special meaning is - anybody have experience in this area? Reply from infograf768: My guess is that they can't be used if not enclosed in double quotes. Note from nikosdion: I concur with infograf768's comment. Also, all translation strings should be in double quotation marks.
3. Comment syntax has changed, as we are typically using pound signs (#) and the standard parser requires semi colons (;). Note from nikosdion: you MUST use semicolons, otherwise your language files will not load

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.

Updating your Joomla 1.5 language files to work on Joomla 1.6

Using the native php ini parser for language files has many benefits including much faster performance.

Basically, you have two options:

1. The Eclipse solution (or any other Coding Platform), extremely easy as well:
   1. Search your file for *.ini in your project of choice. Then use the following search/replace values to automatically, replace exisiting quotes, add quotes to string values and update your comments
   2. Double quotes are now not allowed and this can be easily bypassed by searching " and replace with '
   3. Put a closing double quote at end of line if not empty or a comment. Find ^((?!#).+)\R replace with $1"\R
   4. Put an opening quote at start of translated string if not empty or comment. Find ^((?!#).+?\=)(.+)\R replace with $1"$2\R
   5. Now replace the hash comments with the new semi colon. Find ^# and replace with ;
   6. Remove any illegal strings that can prevent files loading. Find ^(null|yes|no|true|false|on|off|none)=(.+)\R and replace with nothing.

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

Language file naming conventions and precedence

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.

Loading any language file, anywhere

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:

JFactory::getLanguage()->load('com_yourcomponentname');

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);

Related discussion threads in the development mailing list

• Another language question concerning 1.6 Optionen
• Here is a proposal from the com_localise team - Comments?
• Hardcoded punctuation creates issues in language files Optionen
• Language String Namespaces