Делаем сайт мультиязычным
Разделы: Документация / Расширяем Cotonti / Локализация
В данном разделе описаны настройки плгина `i18n` (идет в базовой поставке), для обеспечения следующих возможностей:
Итак, давайте разберемся что нам для этого потребуется:
en|English nl|Nederlands de|Deutsch
<!-- Меню выбора перевода -->
<!-- BEGIN: I18N_LANG -->
{PHP.L.Language}:
<ul>
<!-- BEGIN: I18N_LANG_ROW -->
<li><a href="{I18N_LANG_ROW_URL}">{I18N_LANG_ROW_TITLE}</a></li>
<!-- END: I18N_LANG_ROW -->
</ul>
<!-- END: I18N_LANG -->
<!-- Кнопки управления -->
{PAGE_I18N_TRANSLATE} {PAGE_I18N_DELETE}
<!-- BEGIN: I18N_LANG -->
<ul>
<!-- BEGIN: I18N_LANG_ROW -->
<li>
<a href="{I18N_LANG_ROW_URL}" title="{I18N_LANG_ROW_TITLE}"><img src="images/flags/{I18N_LANG_ROW_FLAG}.png" alt="{I18N_LANG_ROW_CODE}" /></a>
</li>
<!-- END: I18N_LANG_ROW -->
</ul>
<!-- END: I18N_LANG -->
Вот и все.
Добавление:
8. Если на вашем сайте используется плагин `urlreditor`, то стоит проверить наличие следующей строки в файле `.htaccess`:
# Language selector RewriteRule ^(ru|ua|en|de|nl)/(.*) $2?l=$1 [QSA,NC,NE,DPI]
Если вы его устанавливали по инструкции, то строка скорее всего в вашем файле имеется, т.к. она есть в шаблоне `sef-urls.htaccess`.
Если вы добавляете язык отличный от указанных в списке (ru|ua|en|de|nl), то просто добавьте его туда через разделитель `|`.
Плагин i18n не имеет настройки для задания отдельных заголовка и описания сайта (meta description, title) для каждого из языков. Но это можно исправить в 2 счета:
$cfg['maintitle']='maintitle-en'; $cfg['subtitle']='subtitle-en';
Для единообразия отображения заголовков переведенных страниц в категории system добавляем в языковые файлы темы следующую строку:
if (strtolower($_GET['c']) == 'system') $cfg['page']['title_page'] = '{TITLE}';
Локализация Расширений
Разделы: Документация / Расширяем Cotonti / Локализация
Файлы локализации каждого из Расширений располагаются в собственной папке Расширения, в подпапке 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).
Контроль изменения в файлах локализации
Разделы: Документация / Расширяем Cotonti / Локализация
Надежнее всего обновлять Cotonti целиком с выходом новой стабильной версии. Тем не менее может возникнуть ситуация когда вам надо обновить только часть проекта в «ручном режиме». В таком случае может стать вопрос какие именно файлы необходимо обновить, т.к. отверсии к версии может меняться не только функционал но и сопутствующие файлы, такие как файлы локализации.
Все изменения по файлам от версии к версии можно отследить используя репозиторий Cotonti на GitHub. (Кроме того, если вы владеете навыком работы с Git, то можете даже предложить свои правки в файлы локализации, которые будут размещены в официальном репозитории).
GitHub позволяет легко отследить изменения между релизами. Ссылка на сиавнение релизов есть на каждой странице с описанием релиза. Для примера посмотрим на произошедшие изменения с версии 0.9.17 до версии 0.9.18. Мы увидем здесь «список правок» (`Commits`), а также можем просмотреть все измененные файлы, переключившись на вкладку «Измененные файлы» (Files changed).
Во времена, когда Cotonti разрабатывался с помощью инструмента под названием Trac, была возможность увидеть изменения в текстовом формате, называемом «общие изменения» (`unified diff`). Несмотря на то, что Git и GitHub позволяют сделат аналогичное, не всегда удобно просматривать большой список изменений в браузере. К тому же если вам надо просто отследить изменения в языковых файлах, подойдет упрощенный вариант файла «общих изменений». Для этого потредуется:
Cotonti. Скачайте и распакуйте в этот каталог архивы сравниваемых версий, например, последний и предпоследний релиз. Думаю, нет необходимости упомянать, что каждая версия должна находится в собственном подкаталоге.Теперь вы имеете обобщанный файл изменений и можете отследить правки в конкретных файлах. Для этого используйте поиск в текстовом редакторе для быстрого перехода к месту с правками языковых файлов. Например, ищите стрку "en.lang" для изменений в английских языковых файлах. Знак "-" в найденном блоке текста будет означать, что строка была изменена или удалена, а знак "+" обозначает добавленные данные. Для более подробного ознакомления с форматом diff файлов загляните в инструкцию diff утилиты.
Кроме этого для отображения и навигации по файлу изменений вы можете использовать любую графическую утилиту, например WinMerge.
Если у вас большая часть времени уходит на поддержку и локализацию осноных файлов поставляемых с Cotonti Siena на свой или дополнительный язык — возможно вам стоит присмотреться к сервису Transifex, который мы уже не первый год используем для управления переводом основных языковых файлов проекта.
С помощью веб-интерфейса, который предостовляет Transifex вы можете наблюдать за изменением файлов при выходе новой версии, а так же с легкостью принять участие в локализации или исправлении ошибок перевода. Все что вам потребуется — это бесплатно зарегистрироваться на сайте, выбрать подходящий язык и запросить разрешение на перевод.
Поддержка файлов локализации с помощью Transifex
Разделы: Документация / Расширяем Cotonti / Локализация
Начиная с версии Cotonti 0.9.13 языковые файлы движка совместимы со стандартами сервиса переводов Transifex, ознакомится с проектом и присоединиться к международной команде переводчиков можно здесь:
https://www.transifex.com/projects/p/cotonti/
Для начала работы с сервисом переводов, желательно изучить документацию — Transifex Help Pages (на английском языке). В этой статье будут освещены только особенности касающиеся работы с файлами Cotonti.
После регистрации на сервисе Transifex в качестве пользователя вам будет необходимо запросить доступ в группу перевода одного из языков, или сделать запрос на создание новой группы, если перевода на ваш язык еще нет. После назначения вас в одну из групп перевода вы сможете использовать онлайн интерфейс для перевода файлов.
Кроме онлайн перевода есть возможность скачать набор файлов к себе на диск. О наборе инструментов для «офлайн» перевода далее и пойдет речь.
Все файлы могут быть отредактированы онлайн, тем не менее т.к. Cotonti содержит множество отдельных языковых файлов, для перевода, возможно, будет удобнее скопировать их к себе на диск и использовать свой любимый редактор. Для этого Transifex предоставляет специальную программу работающую с командной строкой — Client tool (далее утилита `tx`).
Внимание! Т.к. часть утилит для автоматизации перевода поставляется в виде скриптов на языке Python, то вам, возможно, потребуется установленный в системе интерпретатор Python (для unix систем он обычно установлен по умолчанию). Скачать его можно здесь: http://python.org/download/. Если вы работаете под ОС Windows, то вам будет полезным настроить команды быстрого вызова — см. инструкцию (на англ. языке).
После этого вы можете установить программу 'tx' (см. английскую инструкцию).
Для облегчения работы по переводу мы подготовили набор утилит для манипуляций с языковыми файлами, скачать которые можно здесь: https://github.com/trustmaster/cotlang. Это набор скриптов на Python, запускаемых из командной строки.
Сервис Transifex работает по аналогии с репозиториями git, поэтому первое что необходимо сделать это получить рабочую копию.
Примечание: все последующие команды подразумевают использование командной строки.
Создайте для работы новый каталог (для примера назовем его 'cot-lang') и перейдите в него, введя в командной строке:
cd cot-lang
Теперь надо инициализировать в этом каталоге репозиторий Transifex командой:
tx init
После этого надо импортировать файл конфигурации. Выполняем:
tx set --auto-remote https://www.transifex.com/projects/p/cotonti/
Для правильного сопоставления файлов локализации Transifex и языковых файлов Cotonti, откройте файл '.tx/config', созданный предыдущей командой и замените его содержимое актуальными настройками для Cotonti из файла:
https://raw.github.com/trustmaster/cotlang/master/tx.config
Замечание для продвинутых пользователей: подобный файл конфигурации может быть создан скриптом 'cotlangtx.py', указав путь к каталогу с исходными файлами Cotonti:
python cotlangtx.py ~/htdocs/cotonti
Теперь пора скопировать языковые файлы в рабочий каталог:
tx pull -a
Отлично. Теперь у вас есть структура каталогов в расположенными в них языковыми файлами.
Если файлы вашей локализации были установлены с версией младше 0.9.13, вам необходимо провести их обновление для соответствия форматам используемым в Transifex. Для этого в наборе утилит cotlang есть скрипт под именем 'cotlangfix.py'. Он автоматизирует 95% работы по изменению файлов. Запускается он следующим образом:
python cotlangfix.py путь/к/исходным/файлам
Он выводит информацию о процессе конвертации на экран. Он так же сообщит о том какие строки должны быть исправлены самостоятельно. Ниже несколько примеров.
Transifex не поддерживает записи разбитые на несколько строк. Поэтому их надо объединить в одну строку. Если перенос строк необходим внутри записи, используйте двойные кавычки и символ \n внутри строки. Не забудьте при замене одинарных кавычек на двойные экранировать символы '$', чтобы они выглядели так '\$'.
Пример, строку:
$L['multiline_example'] = 'это пример %1$s многострочной записи';
Придется заменить на:
$L['multiline_example'] = "это пример\n%1\$s многострочной\nзаписи";
В некоторых случаях в языковых файлах можно встретить записи содержащие переводы вариантов настроек в таком виде:
$L['cfg_array_params'] = array( 'Foo', 'Bar' );
или в таком виде:
$L['cfg_array2_params'] = array( 'foo' => 'Foo', 'bar' => 'Bar' );
Их тоже надо преобразовать в простые строки. Массивы «склеиваются» с помощью знака ',', а ассоциативные массивы собираются в таком виде: 'key1: value1, key2: value2'. Таким образом строки представленные выше преобразуются в следующий вид
$L['cfg_array_params'] = 'Foo, Bar';
и
$L['cfg_array2_params'] = 'foo: Foo, bar: Bar';
Перед загрузкой файлов с переводом на новый язык, убедитесь, что запись для этого языка создана и отображается в проекте Cotonti на сайте Transifex. Если этого языка еще нет в проекте, то войдите на сервис под своей учетной записью (регистрация здесь) и запросите добавление нового языка в проект Cotonti. Мы получим ваш запрос и оперативно создадим запись для новой локализации.
В наборе утилит cotlang есть скрипт под названием 'cotlangcp.py'. Он позволяет упростить операции по копированию набора языковых файлов из одной папки в другую, сохраняя при этом структуру каталогов. Используйте его следующим образом:
python cotlangcp.py путь/к/исходным/файлам путь/к/целевому/каталогу
Кроме этого можно копировать файлы только для определенного языка, например 'nl' (для обозначения используется 2-х буквенный код принятый в Cotonti):
python cotlangcp.py путь/к/исходным/файлам путь/к/целевому/каталогу -l nl
Например, если вы используете текущую 'nl' локализацию, файлы которой находятся в каталоге '~/htdocs/cotonti' и вы хотите скопировать её в каталог репозитория '~/cot-lang', используйте cotlangcp.py следующим образом:
python cotlangcp.py ~/htdocs/cotonti ~/cot-lang -l nl
Теперь, когда у вас есть новые файлы для языка вы можете отправить их на сервер Transifex:
tx push -t -l nl
Замените код 'nl' на код вашего языка.
После этого языковые записи попадут на сервер и будут доступны на страницах проекта https://www.transifex.com/projects/p/cotonti/.
Языковые файлы периодически обновляются. Какие-то строки могут быть добавлены, какие-то удалены. Если вы используете веб-интерфейс Transifex для перевода проблем возникнуть не должно — все изменения видны, просто найти записи без перевода. Более того при редактировании онлайн доступны такие инструменты как Translation Memory и автоматический перевод при помощи сервиса Google.
Тем не менее, вам может потребоваться получить актуальную версию локальной копии языковых файлов для редактирования в привычном редакторе. Сделать это не сложно, с помощью командной строки и все тех же утилит.
Перед внесением любых изменений в файлы лучше всегда обновить локальные копии свежими версиями с сервера:
tx pull
Для получения всех файлов, включая новые используйте команду:
tx pull -a
Теперь вы можете редактировать файлы прямо в текущих каталогах. Или можете скопировать ваш вариант локализации из другой папки, например так:
python cotlangcp.py ~/htdocs/cotonti ~/cot-lang -l nl
Эта команда скопирует языковые файлы голландской локали ('nl')из каталога ~/htdocs/cotonti в каталог ~/cot-lang. Здесь предполагается что каталог ~/cot-lang это каталог вашего Transifex репозитория, а ~/htdocs/cotonti путь где вы храните последние версии файлов с голландской локализацией.
И наоборот, вы всегда можете скопировать последние версии файлов из репозитория Transifex в каталог с файлами вашего сайта на Cotonti:
python cotlangcp.py ~/cot-lang ~/htdocs/cotonti -l nl
Когда процесс редактирования файлов в локальной копии закончен надо отправить изменения на сервер Transifex:
tx push -t -l nl
Замените код 'nl' на соответствующий вашему языку.
Это правило многим должно быть знакомо по работе с Git, однако Tx это не Git, и надо быть более осторожным. Рекомендуем выполнять команда в следующем порядке:
tx pull -a # получаем последнюю версию с сайта cotlangcp.py # редактируем или заменяем часть файлов tx push -t # выгружаем изменения обратно на сервер
Разделы: Documentation (Genoa and older) / Russian / Администрирование
…\system\lang\ru\main.lang.phpНаходим слово «править» (строка 87), копируем всю строку
$L['Edit'] = 'Править';И вставляем ее в файл
…\skins\{имя_скина}\{имя_скина}.ru.lang.php
После вставки заменяем значение переменной $L[‘Edit’] на «редактирование». Сохраняем.$sed_countries[‘us’]=’США’;Сохраняем.
[BEGIN_SED_EXTPLUGIN_CONFIG] category=01:string::news:Category code of the parent category maxpages=02:select:0,1,2,3,4,5,6,7,8,9,10,15,20,25,30,50,100:10:Recent pages displayed [END_SED_EXTPLUGIN_CONFIG]Видим, что есть 2 параметра с именами «category» и «maxpages» (имена параметров указаны до символа «=»).
$L['cfg_category']= array('Код родительской категории');
$L['cfg_maxpages']= array('Отображать страниц', 'количество отображаемых элементов');