规范的语言文件

This page is a translated version of the page Specification of language files and the translation is 21% complete.

Other languages:
English • ‎español • ‎français • ‎Nederlands • ‎中文(中国大陆)‎
Split-icon.png
Split Page into Specific Joomla! Versions - J2.5 and 3.x

It has been suggested that this article or section be split into specific version Namespaces. (Discuss). If version split is not obvious, please allow split request to remain for 1 week pending discussions. Proposed since 5 months ago.

Quill icon.png
Content is Incomplete

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 has not been edited in several days, please consider helping complete the content.
This article was last edited by Guozhanfeng (talk| contribs) 5 months ago. (Purge)

本页介绍从1.5到2.5版本语言文件的规范变化。

1.5规范说明在 创建一个语言定义文件.

Joomla 3.2 Joomla 3.2变化概述

从Joomla !3.2开始,自动加载en-GB,后面的xx-XX语言字符串 这是确保总有返回值给程序调用。这样做是防止“不变”的显示如果xx-XX语言ini文件损坏或翻译字符串是失踪。

Joomla 2.5 Joomla 2.5变化概述

  1. 定义好关键
    1. 没有任何空格。所有空白应转化为下划线“_”
    2. 所有关键的扩展前面应包括一个前缀

额外参考信息 thread

所以,在ini文件种规范的格式: 正如前面提到的,我们的格式必须改变。不允许再用空格,而是下划线来连接每个关键词,这样你会得到类似COM_EXAMPLE_MYKEY的形式。 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.

  1. 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 " 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.
  2. 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.

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.


Updating your Joomla 1.5 language files to work on Joomla 2.5

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
  • d. and 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

Advertisement