Локализация экстраполей в Cotonti

Локализация экстраполей в Cotonti: полное пошаговое руководство для начинающих разработчиков

Экстраполя — это мощный инструмент Cotonti, который позволяет добавлять любые дополнительные данные к страницам, категориям структуры, пользователям, заказам и другим разделам сайта без изменения базы данных вручную. Вы создаёте поле один раз в админ-панели, и оно сразу появляется в формах редактирования и на сайте.

Но чтобы сайт выглядел профессионально на любом языке, экстраполя нужно локализовать. Cotonti имеет встроенный умный механизм, который автоматически подставляет переводы заголовков полей и значений списков. В этой статье мы разберём всё от А до Я: как именно работает система, куда писать строки перевода, какие приоритеты у ключей, как переводить заголовки, варианты выбора и выводить всё в шаблонах.

Статья поможет применить знания и сделать свои экстраполя полностью многоязычными.

Как Cotonti определяет заголовок экстраполя

Заголовок поля (то, что выводится тегом {PAGE_MYG_FIELD_TITLE}) формируется функцией cot_extrafield_title(). Она проверяет языковой массив $L (или Cot::$L) в следующем порядке приоритета:

1. Самый высокий приоритет — ключ с префиксом, который вы передаёте вторым параметром: page_имяполя_title (для страниц) structure_имяполя_title (для категорий структуры)
2. Второй приоритет — ключ с указанным location (местом хранения поля): pages_имяполя_title или structure_имяполя_title
3. Третий приоритет — простой ключ: имяполя_title
4. Если ничего не найдено — используется описание поля из базы (field_description).
5. Если и оно пустое — просто техническое имя поля.

Это значит: вы можете переопределить заголовок именно для страниц или именно для структуры, даже если поле используется в нескольких местах.

Как локализовать значения полей (списки выбора)

Функция cot_build_extrafields_data() отвечает за вывод значения поля на сайте. Для полей типа:

• select
• radio
• checklistbox

система автоматически ищет перевод в массиве $L по ключу: имяполя_значение

Пример: если поле color имеет вариант red, то перевод будет в строке $L['color_red'] = 'Красный';

Для checklistbox (множественный выбор) каждый выбранный пункт переводится отдельно и склеивается через разделитель.

Остальные типы полей (input, textarea, datetime, country и т.д.) перевод не требуют — они выводятся как есть или через парсер.

Пошаговая инструкция: создаём и локализуем экстраполе

Шаг 1. Создаём поле в админ-панели Перейдите: Управление сайтом → Прочее → Экстраполя → Добавить.

Пример настроек поля для страниц:

• Таблица: pages
• Имя поля: mycolor (только латинские буквы и подчёркивание)
• Тип: select
• Варианты: red, green, blue
• Описание: Цвет товара (это будет заголовок по умолчанию)
• Сохраняем.

Поле создано. Теперь оно доступно в редактировании страниц как page_mycolor.

Шаг 2. Создаём файл локализации Предположим, вы разрабатываете плагин myproducts. Создайте файл: plugins/myproducts/lang/myproducts.ru.lang.php

Начните его стандартно:

<?php
defined('COT_CODE') or die('Wrong URL.');

Шаг 3. Добавляем перевод заголовка Самый правильный и рекомендуемый способ — использовать префикс page_:

$L['page_mycolor_title'] = 'Цвет товара';

Если вы хотите отдельный заголовок именно для структуры (категорий), добавьте:

$L['structure_mycolor_title'] = 'Цвет категории';

Можно добавить и простой ключ на всякий случай:

$L['mycolor_title'] = 'Цвет';

Шаг 4. Локализуем варианты выбора Для нашего поля mycolor:

$L['mycolor_red'] = 'Красный';
$L['mycolor_green'] = 'Зелёный';
$L['mycolor_blue'] = 'Синий';

Готово! Теперь всё переведено.

Шаг 5. Создаём английскую версию Скопируйте файл и переименуйте в myproducts.en.lang.php. Замените значения:

$L['page_mycolor_title'] = 'Product color';
$L['mycolor_red'] = 'Red';
$L['mycolor_green'] = 'Green';
$L['mycolor_blue'] = 'Blue';

При смене языка сайта все экстраполя автоматически переключатся.

Вывод экстраполей в шаблонах (самый частый случай)

В любом шаблоне страниц (page.tpl, page.add.tpl, page.edit.tpl и т.д.) используйте стандартные теги:

<!-- Заголовок поля -->
{PAGE_MYCOLOR_TITLE}
<!-- Значение поля -->
{PAGE_MYCOLOR}

Для структуры (в шаблонах категорий):

{CAT_MYCOLOR_TITLE}: {CAT_MYCOLOR}

Cotonti автоматически вызывает cot_extrafield_title() с правильным префиксом (page_ или structure_) и cot_build_extrafields_data(), поэтому переводы подхватываются без единой строки кода в шаблоне.

Если нужно вывести только сырое значение (без перевода):

{PAGE_MYCOLOR_VALUE}

Примеры локализации разных типов полей

1. Поле типа radio Варианты в админке: yes,no В lang-файле:

$L['page_delivery_title'] = 'Доставка';
$L['delivery_yes'] = 'С доставкой';
$L['delivery_no'] = 'Самовывоз';

2. Поле типа checklistbox (множественный выбор) Варианты: wifi,parking,pool В lang-файле:

$L['page_amenities_title'] = 'Удобства';
$L['amenities_wifi'] = 'Wi-Fi';
$L['amenities_parking'] = 'Парковка';
$L['amenities_pool'] = 'Бассейн';

На сайте выбранные пункты выведутся через запятую с переводами.

3. Поле типа select с параметрами Если в настройках поля указан параметр separator= | , то в lang-файле ничего дополнительно делать не нужно — перевод вариантов работает так же.

4. Поле типа country Перевод не нужен — Cotonti использует встроенный список стран из языкового файла системы.

Как использовать локализацию в своём плагине или модуле

Если вы пишете собственный модуль и выводите экстраполя вручную, используйте те же функции:

$exfld_title = cot_extrafield_title($exfld, 'page_'); // для страниц
$value = cot_build_extrafields_data('page', $exfld, $page_data['page_mycolor']);

Пример из реального кода (как это делает сам Cotonti в модуле pages):

$tag = mb_strtoupper($exfld['field_name']);
$exfld_title = cot_extrafield_title($exfld, 'page_');
$temp_array[$tag . '_TITLE'] = $exfld_title;
$temp_array[$tag] = cot_build_extrafields_data('page', $exfld, $value);

Вы можете точно так же делать в своих плагинах — передавайте 'page_' или 'structure_' как префикс, и всё будет работать с вашими переводами.

Полезные советы и частые ошибки

• Всегда используйте префикс page_ или structure_ — это самый надёжный способ.
• Если поле используется только в одном месте, можно обойтись простым ключом имяполя_title.
• Для Transifex и коллективных переводов пишите только строковые ключи — никаких массивов.
• После изменения lang-файла очистите кэш (Управление сайтом → Очистка кэша).
• Если заголовок не переводится — проверьте порядок приоритетов: сначала ищется page_mycolor_title.
• Описание поля в админке (field_description) используется только как запасной вариант.
• Для полей типа datetime, filesize, currency перевод значения не требуется.

Заключение

Теперь вы полностью владеете механизмом локализации экстраполей в Cotonti. Вы знаете:

• как работает приоритет ключей в cot_extrafield_title(),
• как переводить варианты списков через cot_build_extrafields_data(),
• куда и какие строки писать в файлах .lang.php,
• как выводить переведённые поля в шаблонах без единой строчки PHP,
• как использовать те же функции в своих расширениях.

Один раз настроив переводы с правильными префиксами page_ и structure_, вы получаете полностью многоязычный интерфейс для всех дополнительных полей. Ваш сайт будет выглядеть профессионально на русском, английском, немецком и любом другом языке без лишних усилий.