Документация InstantCMS

для администраторов и разработчиков

Инструменты пользователя

Инструменты сайта


en:dev:controllers:language

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

Back to Contents

en/dev/controllers/language.txt · Последнее изменение: 12.06.2017 12:35 — murlysja

Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki