Языковые переменные¶
Одним из основных средств интернационализации и локализации CS-Cart и его дополнений являются языковые переменные. При использовании языковых переменных вместо прямой вставки текста на конкретном языке в исходном тексте и в шаблонах применяется вызов специальной функции, которой передается имя языковой переменной. Функция возвращает текст на том или ином языке в зависимости от локали пользователя. Далее подробно рассказывается об использовании языковых переменных в CS-Cart и при разработке дополнений.
Примечание
Также есть отдельная статья о языковых переменных в жизненном цикле модуля.
Декларация: PO-файлы¶
При создании перевода дополнения или языкового пакета CS-Cart значения языковых переменных для каждого языка помещаются в отдельный файл в формате PO (portable object). Формат является одним из самых распространенных, многие приложения и сервисы использующие или связанные с локализацией поддерживают экспорт и импорт в PO, например, Crowdin, сервис который используется для перевода CS-Cart.
PO-файлы можно редактировать как в обычном текстовом редакторе так и в специальных программах. Подробнее о формате PO можно прочитать на сайте проекта <https://www.gnu.org/software/gettext/manual/html_node/PO-Files.html>.
Языковые пакеты лежат в var/langs/. Сверху идет мета-описание пакета. Все поля обязательные:
Language-Team— название языка на английском.Language— локаль (код-языка_КОД-СТРАНЫ)
Дальше идут сами переменные. Для удобства переменные разбиты по группам и подгруппам. Такие переменные записываются следующим образом:
group.subgroup.variable_name
Список групп и подгрупп:
- addons.[ADDON_NAME].variable_name
- shippings.[SHIPPING_NAME].variable_name
- payments.[PAYMENT_NAME].variable_name
- tooltips.[ID_NAME]
Переменные, общие для подгрупп, могут записываться таким образом:
payments.merchant_id
Само имя переменной может содержать префиксы text_ для описаний чего-либо и error_ для сообщений об ошибках:
addons.seo.text_addon_description
shippings.ups.error_rates_not_found
payments.2checkout.payer_id
Ниже представлено типичное описание языковой переменной для CS-Cart в PO-файлах.
Так выглядит переменная в файле для английского языка:
msgctxt "Languages::email_marketing.subscription_confirmed"
msgid "Thank you for subscribing to our newsletter"
msgstr "Thank you for subscribing to our newsletter"
Та же переменная в файле для французского языка:
msgctxt "Languages::email_marketing.subscription_confirmed"
msgid "Thank you for subscribing to our newsletter"
msgstr "Merci de votre inscription à notre newsletter"
Необходимо соблюдать формат данных:
- Языковые переменные всегда отделяются друг от друга 1 пустой строкой.
- Файл всегда должен заканчиваться 1 пустой строкой.
Ключевые слова имеют следующие значение:
msgctxt¶
Согласно описанию формата PO, msgctxt обозначает уникальный контекст переводимой строки и служит для того, чтобы отличать одинаковые переводимые строки в разных местах приложения. Для CS-Cart в msgctxt хранится имя языковой переменной в том виде как оно используется в шаблонах и исходном коде.
Важно
При передаче в функцию перевода имя указывается без префикса.
В PO-файле CS-Cart кроме переводов строк также хранятся переводы названия и описания дополнения, названий конфигурационных секций, опций настройки дополнения.
Различные типы переводимых данных имеют разные префиксы. Имена языковых переменных должны начинаться с префикса Languages::.
Имя переменной должно быть уникальным среди всех языковых переменных ядра CS-Cart и установленных дополнений, поэтому при создании дополнений чтобы избежать конфликтов с существующими переменными следует помещать имя дополнения в начале имени переменной, в примере выше это email_marketing.
msgid¶
Переводимая строка на исходном языке. Рекомендуется всегда использовать английский язык, так как легко найти переводчиков, знающих его.
msgstr¶
Перевод строки на целевой язык. В случае, если создается PO-файл для исходного языка, msgstr будет совпадать с msgid.
Плейсхолдеры¶
В текст переменных может потребоваться вставить изменяемые данные, например, названия продуктов, ссылки, количество элементов и др. Для этого применяются плейсхолдеры, создаваемые с помощью скобок. Например:
msgctxt "Languages::admin_text_letter_footer"
msgid "E-shop of [company_name]."
msgstr "Электронный магазин [company_name]"
Подсказка
Об использовании плейсхолдеров в исходном коде и шаблонах читайте ниже.
Множественные формы¶
В большинстве языков в случае указания количества элементов (например, количества заказанных товаров) форма фразы различается для единственного и множественного числа. В некоторых языках, например, в русском форм множественного числа несколько. При использовании переменных с различными формами в CS-Cart в ключевых словах msgid и msgstr формы необходимо отделять знаком |, а также добавлять плейсхолдер [n] который будет заменен на число. Пример переменной с несколькими формами:
.. code-block:: po
msgctxt “Languages::n_days” msgid “[n] day|[n] days” msgstr “[n] day|[n] days”
В случае если в целевом языке количество форм отличается от исходного в msgstr перечисляются все формы в целевом языке, msgid при этом не меняется. Та же переменная для русского языка:
msgctxt "Languages::n_days"
msgid "[n] day|[n] days"
msgstr "[n] день|[n] дня|[n] дней"
При перечислении первой указывается форма единственного числа, затем форма(ы) множественного. Порядок следования форм для различных языков соответствует описанному в документе Language Plural Rules.
Использование¶
В исходном коде¶
Для вывода переменных в исходном коде применяется функция ядра CS-Сart __ (двойное подчеркивание):
function __($var, $params = array(), $lang_code = CART_LANGUAGE);
Единственным обязательным параметром является имя переменной. Во втором параметре передаются значения плейсхолдеров, в третьем указывается целевой язык, по умолчанию - это текущая локаль пользователя.
Пример использования функции:
$confirmed_text = __('email_marketing.subscription_confirmed');
fn_set_notification('I',$confirmed_text), $msg);
В шаблонах Smarty¶
Для вставки переменных в шаблон используется полностью аналогичная описанной выше функции конструкция __ (двойное подчеркивание). Выражения помещаются в фигурные скобки. Пример:
{__("hello")}
При компиляции шаблона CS-Сart заменяет такие конструкции на вызов метода __ класса обертки Smarty, который в свою очередь вызывает вышеописанную функцию ядра.
Плейсхолдеры¶
Пример вставки переменной в шаблон с использованием плейсхолдера:
<p>
{__("admin_text_letter_footer", ["[company_name]" => $settings.Company.company_name])}
</p>
Множественные формы¶
При использовании переменных со множественными формами вместо использования плейсхолдера [n] необходимо во втором параметре функции __ в качестве первого элемента передать подставляемое число. Пример:
$return[$service_code]['delivery_time'] = __("n_days", array($shipment->GuaranteedDaysToDelivery));
В зависимости от переданного числа будет автоматически выбрана подходящая форма. Например, для английского языка:
- 0 days
- 1 day
- 3 days
