Подробное изложение правил используемых при локализации Расширений.
Файлы локализации каждого из Расширений располагаются в собственной папке Расширения, в подпапке lang, т.е. (для плагинов) полный путь от корня сайта будет таким: plugins/plug_name/lang/plugin_name.*.lang.php, где * обозначает 2-х буквенный код языка.
Основные правила оформления файлов локализации расширений не отличается от правил для основных файлов.
К основным строкам относятся все строки, которые вы предполагаете использовать в своем Расширении. Т.к. в системе используется единый реестр-массив строк локализации, то к вопросу именования строк надо подойти ответственно, чтобы случайно не переписать системную строку или строку используемую в другим Расширением. Для этого в Cotonti принято имена языковых строк начинать с уникального префикса, например по первым трем буквам из названия плагина. Вот пример одной из строк для плагина comments:
$L['com_closed'] = 'Для этого элемента нельзя добавлять комментарии';
Имя строки com_closed это ничто иное, как ключ массива, через который можно получить значение строки.
Если вы изучали документацию или код движка, то вероятно в курсе существования функции cot_declension, которая служит для отображения правильных окончаний у слов во множественной форме. Например: "1 страница" / "2 страницы" / "5 страниц". Одним из параметров этой функции передается строка с формами слова или ссылка на такую строку в массиве языковых данных. Прямое указание форм:
$text = 'Вы написали '.cot_declension(12, 'страница, страницы, страниц'); // в переменной $text будет строка "Вы написали 12 страниц"
или используя данные из языкового массива:
$Ls['pages'] = 'страница, страницы, страниц'; // обычно определена в языковом файле $text = 'Вы написали '.cot_declension(12, 'pages'); // в переменной $text будет строка "Вы написали 12 страниц"
Если вы заметили, то для описания форм используется не стандартный реестр строк $L, а дополнительный $Ls — это сделано специально, чтобы уменьшить путаницу при использовании языковых данных.
[У функции cot_declension есть и другие параметры. Подробнее смотри в API]
Системные строки используются для описания Расширения и отображаются в панеле управления сайтом (в списке Расширений и на странице описания).
$L['info_name'] = ''; // название Расширения $L['info_desc'] = ''; // описание Расширения $L['info_notes'] = ''; // примечание
Эти переменные применимы как к плагинам, так и модулям. Примечание info_notes отображается на странице управления расширением (Управление сайтом → Расширения → 'выбранное_расширение').
Еще одна специальная строка используется только для некоторых плагинов:
$L[$extname . '_title'] // вместо $extname следует подставить название вашего плагина
Используется только на странице плагина вызываемого по хуку standalone и использующего стандартный (системный) шаблон.
Если вы для Расширения проектируете интерфейс управления для Админ панели (вызываемый по хуку tools), то вам могут пригодится еще 2 переменные: $adminhelp и $adminsubtitle. Первая определяет текст подсказки, который будет выведен в нижнем блоке на странице администрирования Расширения (Управление сайтом → Расширения → 'имя расширения' → Администрирование). Вторая — подзаголовок, который будет использован при формировании заголовка HTML станицы (пример: "BBCodes - Администрирование" ). Эти переменные не заполняются автоматически при загрузке языкового файла и их надо принудительно инициализировать в той части кода, которая вызывается по хуку tools:
$adminhelp = $L['userimages_help']; $adminsubtitle = $L['userimages_title'];
Посредством языкового файла можно также локализовать описания переменных Конфигурации, которые вы можете видеть на странице настроек Расширения (Управление сайтом → расширения → 'имя расширения' → Конфигурация).
Чтобы сделать привязку описания к конкретной переменной надо знать ее имя, которое можно увидеть в файле настроек Расширения (pluginname.setup.php) в специальной секции [BEGIN_COT_EXT_CONFIG] (подробнее о структуре блока написано на странице «Настройка переменных конфигурации»).
Рассмотрим переменную, определенную следующим образом:
sort=01:select:ID,Title,Date:ID:Default sorting column for search results
…и ее локализацию:
// локализация описания пункта конфигурации $L['cfg_sort'] = 'Сортировка по умолчанию в результатах поиска'; // локализация пунктов списка $L['cfg_sort_params'] = 'ID: По ID, Title: По заголовку, Date: По дате'; // локализация подсказки к полю ввода данных $L['cfg_sort_hint'] = 'сортировка происходит по возрастанию';
Описание и подсказка могут быть прописаны для переменной любого типа. Локализация пунктов списка актуальна только для переменной типа select. Имена строк в массиве $L формируются в соответствие с шаблонами:
$L['cfg_'.$varname] // описание $L['cfg_'.$varname.'_params'] // локализация пунктов списка $L['cfg_'.$varname.'_hint'] // локализация подсказки к полю ввода данных
… где $varname заменяется именем переменной.
Cotonti предусматривает возможность для разработчика создать дополнительные поля данных для некоторых таблиц (Панель администрирования → Прочее → Экстраполя). В интерфейсе добавления поля мы можем задать описание поля по умолчанию. Оно будет выводится по тегу {XXX_EXTRAFIELDNAME_TITLE}, где XXX — имя раздела (таблицы), аEXTRAFIELDNAME имя экстра-поля. Несмотря на то, что на текущий момент (Siena 0.9.19) нет единого встроенного механизма локализации описания экстра-поля, тем не менее во многих случаях будет использована следующая переменная:
$L['page_{extrafieldname}_title'] = 'Описание поля';
где {extrafieldname} это имя экстра-поля заданное при его настройке, а pageэто префикс по имени таблицы данных, в котором мспользуется экстраполе.
Для локализации значений списка в экстраполях типа `select`, `radio`, `checklistbox` — используйте следующую схему именования языковых переменных:
$L['{extrafieldname}_{ListItemName}'] = 'Название элкмента списка';
здесь {extrafieldname} — это имя экстра-поля, а {ListItemName} это значение (имя) элемента, указанное в списке при настройке экстраполя. Пример:
$L['country_none'] = "Не указана";
$L['country_belarus'] = "Беларусь";
$L['country_russia'] = "Россия";
$L['country_ukraine'] = "Украина";
Для экстраполя page_country, соответственно в списке: none, belarus, russia, ukraine.
В некоторых (преимущественно старых) Расширениях вы можете встретить массивы используемые для локализации списков выбора или указания форм слова для отображения рядом с числительными:
$L['cfg_array1_params'] = array('Foo', 'Bar');
$L['cfg_array2_params'] = array('foo' => 'Foo', 'bar' => 'Bar');
$Ls['Guests'] = array('гость', 'гостя', 'гостей');
Внимание! Использовать массивы в файлах локализации крайне не рекомендуется. Это устаревшая форма записи. В текущих версиях, для совместимости с инструментами сервиса коллективного перевода Transifex (подробнее об этом), используется только строковая запись. Давайте посмотрим, как должны быть записаны языковые данные из примера выше в строковом виде:
$L['cfg_array1_params'] = 'Foo, Bar'; $L['cfg_array2_params'] = 'foo:Foo, bar:Bar'; $Ls['Guests'] = 'гость, гостя, гостей');
Т.е. списки становятся строкой со значениями разделенными запятой, а массивы вида ключ-значение тем же списком через запятую, где в качестве значение указывается пара 'Ключ:Значение' разделенные знаком :.
Для автоматической конвертиции файлов старого формата в новый можно воспользоваться специальной программой.
Ниже приведен сокращенный пример языкового файла для плагина comments, где в отдельных (условных) блоках приведены различные типы языковых данных:
<?php
/**
* Russian Language File for Comments Plugin
*
* @package Comments
* @copyright (c) Cotonti Team
* @license https://github.com/Cotonti/Cotonti/blob/master/License.txt
*/
defined('COT_CODE') or die('Wrong URL.');
/**
* Plugin Config
*/
$L['cfg_order'] = 'Порядок сортировки';
$L['cfg_order_hint'] = 'Хронологический или самые последние вверху';
$L['cfg_order_params'] = 'Хронологический, самые последние вверху';
$L['info_desc'] = 'Комментарии с API и интеграцией со страницами, списками, опросами, RSS и другими расширениями';
/**
* Plugin Body
*/
$L['comments_comment'] = 'Комментарий';
$L['comments_comments'] = 'Комментарии';
/**
* cot_declension arrays
*/
$Ls['Comments'] = "комментарий,комментария,комментариев";
/**
* Comedit
*/
$L['comments_title'] = 'Редактирование комментария';
Ресурс это своего рода строка микрошаблон, часть данных которого будет заменена подстановкой актуальных данных.
Определение ресурса (как правило в файле ext_name.resources.php):
$R['comments_code_pages_info'] = $L['Total'].': {$totalitems}, '.$L['comm_on_page'].': {$onpage}';
Использование строки-ресурса:
// ф-я `cot_rc` формирует конечную строку подстановкой данных из массива
$stat_data = array(
'totalitems'=> $totalitems,
'onpage' => $page_title
);
$stat_msg = cot_rc('comments_code_pages_info', $stat_data);
В программном коде обращение к строке языковых данных идет через массив $L, $Ls или иной, определенный в языковом файле Расширения:
$email_title = $L['plu_comlive']; cot_error($L['com_commenttooshort'], 'comtext');
Аналогично значение может быть присвоено какому-либо тегу шаблона:
$t->assign(array(
'COMMENTS_POSTER_TITLE' => $L['Poster']
));
Кроме того, языковые данные могут быть получены и использованы не явно при вызове некоторых функций:
// функция `cot_rc` использует данные из $L['com_msg']
$message = cot_rc('com_msg', array('number'=> $com_count));
// функция `cot_declension` использует данные из $Ls['Comments']
$text = $L['com_posted_comments'].' '.cot_declension($com_count, 'Comments');
В шаблонах доступ к языковым данным осуществляется как и доступ из шаблона к значению переменной PHP:
{PHP.L.lang_string_id}
где lang_string_id это ключ массива $L, в котором содержаться основные языковые данные. Пример вывода правильных окончаний с числительным прямо из шаблона:
<!-- BEGIN: SOME_BLOCK -->
Вы оставили {PHP.num_of_comments|cot_declension($this, 'Comments')}
<!-- END: SOME_BLOCK -->
Приведенный пример предполагает, что в переменной $num_of_comments содержится число комментариев пользователя, и определена языковая константа 'Comments':
$Ls['Comments'] = "комментарий,комментария,комментариев";
Тогда конечная строка будет в виде «Вы оставили 5 комментариев» (как пример, для случая $num_of_comments == 5).