Локализация экстраполей в Cotonti
Полное практическое руководство для разработчиков: от механики движка до вывода в шаблонах
Введение
Экстраполя (Extra Fields) — один из ключевых механизмов расширения данных в Cotonti. Они позволяют добавлять собственные поля к страницам, пользователям, категориям и другим сущностям без изменения ядра.
Однако большинство начинающих разработчиков сталкиваются с одной и той же проблемой:
поле создано — но не переводится,
заголовок не локализуется,
значения select отображаются кодами,
шаблон выводит не то, что ожидалось.
Причина проста: локализация экстраполей в Cotonti работает не через отдельную систему, а через существующий языковой механизм $L, но с особой логикой поиска строк.
В этой статье подробно разобрано:
- как движок определяет название экстраполя;
- как происходит локализация значений;
- какие ключи языка используются;
- как правильно назвать строки;
- как данные проходят путь от БД до шаблона;
- где именно происходит перевод;
- как избежать типичных ошибок.
Материал построен максимально последовательно — от внутренней логики функций движка до практического использования.
1. Что такое экстраполе в Cotonti
Экстраполе — это динамически добавляемое поле данных, которое:
- регистрируется в системе;
- создаётся в базе данных;
- автоматически подключается к шаблонам;
- может иметь собственную локализацию.
Примеры:
- дополнительное поле страницы: рейтинг;
- страна пользователя;
- тип материала;
- уровень сложности статьи.
2. Как движок хранит экстраполя
Все зарегистрированные поля находятся в:
Например:
Каждое поле — это массив:
Важно понять:
field_description — НЕ окончательный заголовок.
Он используется только как fallback.
Настоящий заголовок определяется через локализацию.
3. Главная функция локализации — cot_extrafield_title()
Рассмотрим ключевую функцию.
Она решает:
👉 какой текст станет названием поля.
3.1 Алгоритм поиска перевода
Функция проверяет строки строго по порядку:
Шаг 1 — префикс (наиболее приоритетный)
Пример:
Если строка существует — используется она.
Шаг 2 — location поля
Например:
Шаг 3 — глобальное имя
Шаг 4 — описание из БД
Шаг 5 — имя поля
Если всё пусто:
Итог
Движок ищет перевод сверху вниз, пока не найдёт первый существующий вариант.
Это критически важно для правильной локализации.
4. Правильное создание локализации заголовка
Допустим, создано поле:
для страниц.
Правильная языковая строка:
Почему именно так?
Потому что модуль вызывает:
Главное правило
Префикс передаётся кодом модуля.
Вы не придумываете его — вы повторяете то, что использует система.
5. Где происходит вызов локализации (реальный код модуля)
Разберём предоставленный пример.
Для каждого поля:
Затем:
Что это означает
Если поле:
в шаблон попадёт:
6. Путь данных: от БД до шаблона
Полный жизненный цикл:
7. Локализация значений поля — cot_build_extrafields_data()
Теперь главное — перевод значений.
Функция:
Она:
- форматирует данные;
- парсит текст;
- переводит select/radio значения.
7.1 Select и Radio — скрытая локализация
Ключевой код:
То есть перевод ищется как:
Пример
Поле:
варианты:
Локализация:
Теперь вместо easy пользователь увидит:
7.2 Checklistbox
Каждое значение переводится отдельно:
Если выбрано:
результат:
при наличии:
8. Почему иногда перевод не работает
Частые причины:
❌ Неверный ключ
Нужно:
❌ Неправильный регистр
Cotonti чувствителен к регистру.
❌ Языковой файл не загружен
Файл должен находиться:
9. Типы полей и их поведение
| Тип | Локализация |
| input | нет |
| textarea | нет |
| select | через $L[field_value] |
| radio | через $L[field_value] |
| checklistbox | перевод каждого значения |
| datetime | форматируется датой |
| checkbox | 0/1 |
10. HTML-конструкция и тема
Функция:
подгружает:
Это означает:
👉 тема тоже может влиять на локализацию элементов формы.
11. Добавление экстраполя программно
Создание:
После создания добавляем перевод:
12. Экстраполя категорий (structure)
Код:
Значит локализация:
В шаблоне:
13. Все шаблонные теги экстраполя
Для поля rating:
| Тег | Значение |
{RATING_TITLE} | название |
{RATING} | обработанное значение |
{RATING_VALUE} | сырое значение |
Для категории:
14. Полный практический пример
Шаг 1. Создать поле
Шаг 2. Языковой файл
Шаг 3. Значения в админке
Шаг 4. Вывод в шаблоне
Результат
15. Универсальная схема локализации экстраполей
Запомните одну формулу:
16. Рекомендованная структура языкового файла
17. Лучшие практики
Всегда:
- использовать prefix (
page_, structure_); - локализовать значения select;
- держать переводы рядом с модулем;
- использовать английские ключи значений.
Никогда:
- не переводить значения прямо в БД;
- не писать текст в шаблоне вручную;
- не менять field_name после запуска проекта.
Заключение
Локализация экстраполей в Cotonti — это не отдельная система, а надстройка над языковым массивом $L, интегрированная в жизненный цикл данных.
Ключевая идея:
экстраполе само не знает своего перевода — его определяет соглашение имен.
Когда вы понимаете три функции:
cot_extrafield_title()cot_build_extrafields_data()- шаблонную передачу
$temp_array
вся система становится предсказуемой.
Правильно локализованные экстраполя дают:
- многоязычные сайты без дублирования полей;
- чистые шаблоны;
- переносимые модули;
- совместимость с любыми темами.
Освоив этот механизм, разработчик начинает использовать Cotonti именно так, как он был архитектурно задуман — как расширяемую и строго структурированную CMS.
