Езикови променливи - Документация 4
Едно от основните средства за интернационализация и локализация на CS-Cart и неговите добавки са езиковите променливи. Когато се използват езикови променливи, вместо директно поставяне на текст на определен език в изходния текст и в шаблони, се използва специално извикване на функция, на което се предава името на езиковата променлива. Функцията връща текст на един или друг език в зависимост от локала на потребителя. Следва подробно описание на използването на езикови променливи в CS-Cart и при разработването на добавки.
Декларация: PO файлове¶
Когато създавате превод на CS-Cart добавка или езиков пакет, стойностите на езиковите променливи за всеки език се поставят в отделен файл във формат PO (преносим обект). Форматът е един от най-често срещаните, много приложения и услуги, използващи или свързани с локализация, поддържат експортиране и импортиране в PO, например Crowdin, услуга, използвана за превод на CS-Cart.
Езиковите пакети са във var/langs/. Най-отгоре е мета описанието на пакета. Всички полета са задължителни:
- Language-Team - името на езика на английски.
- Език - локал (код-на-език_COUNTRY-CODE)
Следват самите променливи. За удобство променливите са разделени на групи и подгрупи. Такива променливи се записват, както следва:
Списък на групи и подгрупи:
- добавки.[ADDON_NAME].име_на_променлива
- доставки.[SHIPPING_NAME].име_на_променлива
- плащания.[PAYMENT_NAME].variable_name
- подсказки.[ID_NAME]
Променливите, общи за подгрупите, могат да бъдат записани по следния начин:
Името на самата променлива може да има префикс text_ за описание на нещо и error_ за съобщения за грешка:
Следното е типично описание на езикпроменлива за CS-Cart в PO файлове.
Ето как изглежда променливата във файла за английски език:
Същата променлива във файла за френски:
Трябва да се спазва форматът на данните:
- Езиковите променливи винаги са разделени една от друга с 1 празен ред.
- Файлът винаги трябва да завършва с 1 празен ред.
Ключовите думи имат следните значения:
Според описанието на формата на PO, msgctxt обозначава уникалния контекст на преводим низ и се използва за разграничаване на идентични преводими низове на различни места в приложение. За CS-Cart msgctxt съхранява името на езиковата променлива, както се използва в шаблони и изходен код.
Когато се предава на функция за превод, името се посочва без префикс.
В допълнение към преводите на редове, PO файлът на CS-Cart също съхранява преводи на името и описанието на добавката, имената на секциите за конфигурация и опциите за конфигуриране на добавката.
Различните типове данни за превод имат различни префикси. Имената на езиковите променливи трябва да започват с префикса Languages::.
Името на променливата трябва да е уникално сред всички променливи на основния език на CS-Cart и инсталираните добавки, така че когато създавате добавки, за да избегнете конфликти със съществуващи променливи, трябва да поставите името на добавката в началото на името на променливата, в примера по-горе това е email_marketing.
Низът, който трябва да бъде преведен на изходния език. Препоръчително е винаги да използвате английски, тъй като е лесно да се намерят преводачи, които го владеят.
Превод на низа на целевия език. В случай че се създава PO файл на изходен език, msgstr ще бъде същият като msgid.
Заместители¶
Може да се наложи да вмъкнете променливи данни в текста на променливите, например имена на продукти, връзки, количестваелементи и т.н. За това се използват запазени места, създадени с помощта на скоби. Например:
Множество форми¶
В повечето езици, в случай на уточняване на броя на елементите (например броя на поръчаните стоки), формата на фразата се различава за единствено и множествено число. В някои езици, например в българския има няколко форми за множествено число. Когато използвате променливи с различни форми в CS-Cart, в ключовите думи msgid и msgstr, формите трябва да бъдат разделени със знак и трябва да се добави контейнер [n], който ще бъде заменен с число. Пример за променлива с множество форми:
Ако броят на формулярите на целевия език се различава от оригиналния, msgstr изброява всички формуляри на целевия език, msgid не се променя. Същата променлива за български:
Когато е изброена, формата за единствено число е изброена първа, последвана от формата(ите) за множествено число. Редът на формулярите за различните езици е както е описано в документа Правила за множествено число на езика.
Използване¶
В изходния код¶
За показване на променливи в изходния код се използва функцията на ядрото на CS-Cart __ (двойна долна черта):
Единственият задължителен параметър е името на променливата. Стойностите на контейнерите се предават във втория параметър, целевият език е посочен в третия параметър, по подразбиране това е текущият локал на потребителя.
Пример за използване на функцията:
В шаблони Smarty¶
За да вмъкнете променливи в шаблон, конструкцията __ (двойно подчертаване) е напълно аналогична на функцията, описана по-горе. Изразите се поставят във фигурни скоби. Пример:
При компилирането на шаблона CS-Cart замества такива конструкции с извикване на метода __ на обвиващия клас Smarty, който от своя страна извиква горната функцияядки.
Заместители¶
Пример за вмъкване на променлива в шаблон с помощта на контейнер:
Множество форми¶
Когато използвате променливи с множество форми, вместо да използвате контейнера [n], е необходимо да прехвърлите заместеното число като първи елемент във втория параметър на функцията __. Пример:
В зависимост от предадения номер автоматично ще бъде избрана подходящата форма. Например за английски: