Локализация Расширений

Подробное изложение правил используемых при локализации Расширений.

#1. Общие правила

Файлы локализации каждого из Расширений располагаются в собственной папке Расширения, в подпапке lang, т.е. (для плагинов) полный путь от корня сайта будет таким: plugins/plug_name/lang/plugin_name.*.lang.php, где * обозначает 2-х буквенный код языка. 

Основные правила оформления файлов локализации расширений не отличается от правил для основных файлов.

#2. Основные строки

К основным строкам относятся все строки, которые вы предполагаете использовать в своем Расширении. Т.к. в системе используется единый реестр-массив строк локализации, то к вопросу именования строк надо подойти ответственно, чтобы случайно не переписать системную строку или строку используемую в другим Расширением. Для этого в Cotonti принято имена языковых строк начинать с уникального префикса, например по первым трем буквам из названия плагина. Вот пример одной из строк для плагина comments:

$L['com_closed'] = 'Для этого элемента нельзя добавлять комментарии';

Имя строки com_closed это ничто иное, как ключ массива, через который можно получить значение строки.

#3. Варианты числительных

Если вы изучали документацию или код движка, то вероятно в курсе существования функции 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]

#4. Системные строки

Системные строки используются для описания Расширения и отображаются в панеле управления сайтом (в списке Расширений и на странице описания).

$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'];

#5. Описание переменных конфигурации

Посредством языкового файла можно также локализовать описания переменных Конфигурации, которые вы можете видеть на странице настроек Расширения (Управление сайтом → расширения → 'имя расширения' → Конфигурация).

Чтобы сделать привязку описания к конкретной переменной надо знать ее имя, которое можно увидеть в файле настроек Расширения (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 заменяется именем переменной.

#6.  Локализация экстра-полей

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.

#7. Локализация списков

В некоторых (преимущественно старых) Расширениях вы можете встретить массивы используемые для локализации списков выбора или указания форм слова для отображения рядом с числительными:

$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'] = 'гость, гостя, гостей');

Т.е. списки становятся строкой со значениями разделенными запятой, а массивы вида ключ-значение тем же списком через запятую, где в качестве значение указывается пара 'Ключ:Значение' разделенные знаком :.

Для автоматической конвертиции файлов старого формата в новый можно воспользоваться специальной программой.

#8. Пример файла локализации

Ниже приведен сокращенный пример языкового файла для плагина 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'] = 'Редактирование комментария';

#9. Использование языковых данных

#9.1. Использование в файлах ресурсов

Ресурс это своего рода строка микрошаблон, часть данных которого будет заменена подстановкой актуальных данных.

Определение ресурса (как правило в файле 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);

#9.2. Использование в программном коде

В программном коде обращение к строке языковых данных идет через массив $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');

#9.3. Использование в шаблонах

В шаблонах доступ к языковым данным осуществляется как и доступ из шаблона к значению переменной 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).



Комментарии отсутствуют
Добавление комментариев доступно только зарегистрированным пользователям