Языковые переменные

Одним из основных средств интернационализации и локализации 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