Содержание
Component Language File
In InstantCMS, all text messages that are displayed to a user in the course of the component’s work are stored in a separate language file. Such approach allows to translate interfaces to other languages without interference in the code and templates.
File Location
Your component’s language file should be located in:
/system/languages/{language}/controllers/{component}/{component}.php
where {language} is the language code according to ISO 639-1, {component} – component’s system name.
A component can have several such files, one for each supported language. A minimum set must have at least the Russian (ru) language.
An example of the «Comments» component’s Russian language file location:
/system/languages/ru/controllers/comments/comments.php
Linking a File
The language file is linked automatically when requesting any component action. Its contents becomes immediately available in controllers, actions, hooks, models and component templates. No additional actions required.
A controller can also link another component’s language file:
cmsCore::loadControllerLanguage('component name');
or any file from the current language folder, for example:
// we link the /languages/current-site-language/widgets/menu.php file: cmsCore::loadLanguage('widgets/menu');
Moreover, the system automatically links all language files located in the root of the current language folder of the website. In other words, for example, if you create the /languages/ru/example.php file, the file will be automatically linked and its contents will be available anywhere. Use this feature in exceptional cases when there is no other option to link a relevant language file.
File Contents
Constants containing text messages are declared inside the file.
Each constant’s title is generated according to the scheme:
LANG_{COMPONENT}_{MESSAGE}
An example – an extract from the English language file of the «Comments» component:
define('LANG_COMMENTS_NONE', 'No comments yet. Be the first to post a comment!'); define('LANG_COMMENTS_REFRESH', 'Refresh comments'); define('LANG_COMMENT_ADD', 'Add a comment'); define('LANG_COMMENT_ERROR', 'Failed to add a comment'); define('LANG_COMMENT_SUCCESS', 'Comment added'); define('LANG_COMMENT_DELETED', 'Comment deleted'); define('LANG_COMMENT_DELETE_CONFIRM', 'Delete %s’s comment?');
Text Substitution
Some text messsages may require an «on the fly» data substitution. The following constant is shown in the example above:
define('LANG_COMMENT_DELETE_CONFIRM', 'Delete %s’s comment?');
This text is displayed at an attempt to delete a comment and contains an author’s name whose comment is going to be deleted. Substitution is performed with the help of the printf() function in the template:
<?php printf(LANG_COMMENT_DELETE_CONFIRM, $comment['user_nickname']); ?>
For details, see the Documentation on the printf() function.
Declension of Numerals
Sometimes a message text should contain an amount of something, for example – «10 comments». The numeral should be properly declined though.
In such cases, three constants containing different forms are created:
define('LANG_COMMENT1', 'comment'); // one... define('LANG_COMMENT2', 'comments'); // two... define('LANG_COMMENT10', 'comments'); // many...
The html_spellcount($number, $one, $two, $many) function is used to output them in the template. The number to be displayed is passed by the first parameter, the other three are the numeral’s declension forms:
echo html_spellcount(21, LANG_COMMENT1, LANG_COMMENT2, LANG_COMMENT10); //it will output: 21 comments
You can also use a more compact entry when one constant contains all three forms of a numeral separated by a vertical bar:
define('LANG_COMMENTS_SPELLCOUNT', 'comment|comments|comments');
It is output by analogy, however, only one constant is passed:
echo html_spellcount(21, LANG_COMMENTS_SPELLCOUNT);
You can combine the described above method to substitute and decline numerals. For example, two constants are enough to get the «You wrote 5 articles» string.
define('LANG_ARTICLES_SPELLCOUNT', 'article|articles|articles'); define('LANG_ARTICLES_YOU_WROTE', 'You wrote %s');
Result:
printf(LANG_ARTICLES_YOU_WROTE, html_spellcount(5, LANG_ARTICLES_SPELLCOUNT));