Мовні змінні - Документація 4
Одним із основних засобів інтернаціоналізації та локалізації CS-Cart та його доповнень є мовні змінні. При використанні мовних змінних замість прямої вставки тексту конкретною мовою у вихідному тексті та шаблонах застосовується виклик спеціальної функції, якою передається ім'я мовної змінної. Функція повертає текст тією чи іншою мовою, залежно від локалі користувача. Далі докладно розповідається про використання мовних змінних у CS-Cart та розробки додатків.
Декларація: PO-файли¶
При створенні перекладу доповнення або мовного пакета CS-Cart значення мовних змінних кожної мови поміщаються в окремий файл у форматі PO (portable object). Формат є одним з найпоширеніших, багато додатків та сервісів, що використовують або пов'язані з локалізацією, підтримують експорт та імпорт у PO, наприклад, Crowdin, сервіс який використовується для перекладу CS-Cart.
Мовні пакети лежать у var/langs/. Зверху йде мета-опис пакету. Усі поля обов'язкові:
- Language-Team - назва мови англійською.
- Language - локаль (код-мови_КОД-КРАЇНИ)
Далі йдуть самі змінні. Для зручності змінні розбиті за групами та підгрупами. Такі змінні записуються так:
Список груп та підгруп:
- addons.[ADDON_NAME].variable_name
- shippings.[SHIPPING_NAME].variable_name
- payments.[PAYMENT_NAME].variable_name
- tooltips.[ID_NAME]
Змінні, загальні для підгруп, можуть записуватись таким чином:
Саме ім'я змінної може містити префікси text_ для описів чогось і error_ для повідомлень про помилки:
Нижче наведено типовий опис мовноїзмінної для CS-Cart у PO-файлах.
Так виглядає змінна у файлі для англійської мови:
Та ж змінна у файлі для французької мови:
Необхідно дотримуватися формату даних:
- Мовні змінні завжди відокремлюються один від одного 1 порожнім рядком.
- Файл завжди повинен закінчуватися одним порожнім рядком.
Ключові слова мають такі значення:
Згідно з описом формату PO, msgctxt позначає унікальний контекст рядка, що перекладається і служить для того, щоб відрізняти однакові рядки, що перекладаються в різних місцях програми. Для CS-Cart у msgctxt зберігається ім'я мовної змінної у тому вигляді як воно використовується у шаблонах та вихідному коді.
Під час передачі у функцію перекладу ім'я вказується без префікса.
У PO-файлі CS-Cart крім перекладів рядків також зберігаються переклади назви та опису доповнення, назв конфігураційних секцій, опцій налаштування доповнення.
Різні типи даних, що перекладаються, мають різні префікси. Імена мовних змінних повинні починатися з префіксу Languages: .
Ім'я змінної має бути унікальним серед усіх мовних змінних ядра CS-Cart та встановлених доповнень, тому при створенні доповнень, щоб уникнути конфліктів з існуючими змінними, слід поміщати ім'я доповнення на початку імені змінної, у прикладі вище це email_marketing .
Рядок, що перекладається вихідною мовою. Рекомендується завжди використовувати англійську мову, тому що легко знайти перекладачів, які її знають.
Переклад рядка на цільову мову. Якщо створюється PO-файл для вихідної мови, msgstr збігатиметься з msgid .
Плейсхолдери¶
У текст змінних може знадобитися вставити змінені дані, наприклад, назви продуктів, посилання, кількістьелементів та ін. Для цього застосовуються плейсхолдери, що створюються за допомогою дужок. Наприклад:
Множинні форми¶
У більшості мов у разі вказівки кількості елементів (наприклад, кількості замовлених товарів) форма фрази відрізняється для однини та множини. У деяких мовах, наприклад, в українській формі множини кілька. При використанні змінних з різними формами CS-Cart у ключових словах msgid і msgstr форми необхідно відокремлювати знаком , а також додавати плейсхолдер [n] який буде замінений на число. Приклад змінної з кількома формами:
Якщо в цільовій мові кількість форм відрізняється від вихідного в msgstr, перераховуються всі форми в цільовій мові, msgid при цьому не змінюється. Та сама змінна для української мови:
При перерахуванні першої вказується форма однини, потім форма(и) множини. Порядок проходження форм для різних мов відповідає описаному в документі Language Plural Rules.
Використання¶
У вихідному коді
Для виведення змінних у вихідному коді використовується функція ядра CS-Сart __ (подвійне підкреслення):
Єдиним обов'язковим параметром є назва змінної. У другому параметрі передаються значення плейсхолдерів, у третьому вказується цільова мова, за замовчуванням це поточна локаль користувача.
Приклад використання функції:
У шаблонах Smarty¶
Для вставки змінних у шаблон використовується повністю аналогічна описаній вище функції конструкція (подвійне підкреслення). Вирази поміщаються у фігурні дужки. Приклад:
При компіляції шаблону CS-Сart замінює такі конструкції на виклик методу __ класу обгортки Smarty, який у свою чергу викликає цю функцію.ядра.
Плейсхолдери¶
Приклад вставки змінної шаблон з використанням плейсхолдера:
Множинні форми¶
При використанні змінних з множинними формами замість використання плейсхолдера [n] необхідно в другому параметрі функції __ як перший елемент передати число, що підставляється. Приклад:
Залежно від переданого числа буде автоматично вибрано відповідну форму. Наприклад, для англійської мови: