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

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

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

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


dev:controllers:language

Языковой файл компонента

В InstantCMS все текстовые сообщения, выводимые пользователю в процессе работы компонента, хранятся в отдельном языковом файле. Такой подход позволяет переводить интерфейсы на другие языки, не требуя при этом вмешательства в код и шаблоны.

Расположение файла

Языковой файл вашего компонента должен иметь путь:

/system/languages/{язык}/controllers/{компонент}/{компонент}.php

где {язык} – код языка в соответствии с ISO 639-1, {компонент} – системное имя компонента.

Вместе с компонентом может поставляться несколько таких файлов, по одному для каждого поддерживаемого языка. В минимальном наборе должен поддерживаться русский (ru) язык.

Пример расположения русского языкового файла компонента «Комментарии»:

/system/languages/ru/controllers/comments/comments.php

Подключение файла

Языковой файл подключается автоматически при вызове любого действия компонента. Его содержимое сразу доступно в контроллерах, экшенах, хуках, модели и шаблонах компонента. Дополнительных действий не требуется.

Контроллер также может подключить языковой файл другого компонента:

cmsCore::loadControllerLanguage('название компонента');

либо любой файл из папки текущего языка, например:

// подключаем файл /languages/текущий-язык-сайта/widgets/menu.php:
cmsCore::loadLanguage('widgets/menu');

Кроме того, система автоматически подключает все языковые файлы находящиеся в корне папки с текущим языком сайта. То есть, например, если создать файл /languages/ru/example.php, то этот файл будет подключен автоматически и его содержимое будет доступно в любом месте. Этой возможностью стоит пользоваться в исключительных случаях, когда нет другой возможности подключить нужный языковой файл.

Содержимое файла

Внутри файла объявляются константы, содержащие текстовые сообщения.

Имя каждой константы образуется по схеме:

LANG_{КОМПОНЕНТ}_{СООБЩЕНИЕ}

Пример – фрагмент русского языкового файла компонента «Комментарии»:

define('LANG_COMMENTS_NONE', 'Нет комментариев. Ваш будет первым!');
define('LANG_COMMENTS_REFRESH', 'Обновить комментарии');
define('LANG_COMMENT_ADD', 'Написать комментарий');
define('LANG_COMMENT_ERROR', 'Ошибка создания комментария');
define('LANG_COMMENT_SUCCESS', 'Комментарий добавлен');
define('LANG_COMMENT_DELETED', 'Комментарий удален');
define('LANG_COMMENT_DELETE_CONFIRM', 'Удалить комментарий пользователя %s?');

Подстановка текста

Некоторые текстовые сообщения могут требовать подстановки данных «на лету». В примере выше была показана такая константа:

define('LANG_COMMENT_DELETE_CONFIRM', 'Удалить комментарий пользователя %s?');

Этот текст выводится при попытке удаления комментария и содержит имя автора удаляемого комментария. Подстановка осуществляется с помощью функции printf() в шаблоне:

<?php printf(LANG_COMMENT_DELETE_CONFIRM, $comment['user_nickname']); ?>

Подробнее см. в документации по функции printf().

Склонение числительных

Иногда текст сообщения должен содержать количество чего-либо, например – «10 комментариев». Числительное при этом должно правильно склоняться.

В таких случаях создаются три константы, содержащие разные формы числительного:

define('LANG_COMMENT1', 'комментарий'); // один...
define('LANG_COMMENT2', 'комментария'); // два...
define('LANG_COMMENT10', 'комментариев'); // много...

При выводе в шаблоне используется функция html_spellcount($number, $one, $two, $many). Первым параметром передается число, которое нужно вывести, остальные три – формы склонения числительного:

echo html_spellcount(21, LANG_COMMENT1, LANG_COMMENT2, LANG_COMMENT10);
//выведет: 21 комментарий

Также можно использовать более компактную запись, когда все три формы числительного содержатся в одной константе, разделяемые вертикальной чертой:

define('LANG_COMMENTS_SPELLCOUNT', 'комментарий|комментария|комментариев'); 

Вывод происходит аналогично, но передается только одна константа:

echo html_spellcount(21, LANG_COMMENTS_SPELLCOUNT);

Вы можете совмещать описанный выше прием подстановки и склонение числительных. Например, чтобы получить строку «Вы написали 5 статей» достаточно двух констант:

define('LANG_ARTICLES_SPELLCOUNT', 'статья|статьи|статей'); 
define('LANG_ARTICLES_YOU_WROTE', 'Вы написали %s'); 

Вывод:

printf(LANG_ARTICLES_YOU_WROTE, html_spellcount(5, LANG_ARTICLES_SPELLCOUNT));

Вернуться к оглавлению

dev/controllers/language.txt · Последние изменения: 03.03.2016 22:26 — fuze