Лексиконы и мультиязычность

По умолчанию значения полей хранятся прямо в конфиге секции (TV mpc_config). Если включить лексиконы, переводимые значения выносятся в lexicon-файлы MODX, а в конфиге остаётся только ключ. Это даёт две вещи сразу:

• мультиязычность — один и тот же ключ резолвится в значение нужного языка по текущему контексту;
• централизованный перевод — все тексты страницы лежат в одном файле, их удобно отдавать на перевод и подменять, не трогая контент в админке.

Подсказка

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

Включение

Режим включается системной настройкой mpc_use_lexicons (по умолчанию 0 — выключено). После включения нужно перенарезать шаблоны (mgr_tpl.php), чтобы значения переехали из конфига в лексиконы, а в плейсхолдеры добавился модификатор | lexicon.

Какой контент переводится

Не всё подряд лексиконизируется — только типы контента, перечисленные в настройке mpc_translated_content (по умолчанию text,contact). Тип определяется по тегу/назначению поля при нарезке:

Тип	Что это	В дефолтном наборе
text	текстовые поля, а также alt и title картинок и ссылок	да
contact	под-поля контактов (см. ниже)	да
image	src / srcset изображений	нет
poster	постер видео	нет
video	src видео	нет
audio	src аудио	нет

Чтобы переводить, например, и пути к картинкам (разные изображения под разные языки), добавьте image в mpc_translated_content: text,contact,image.

Внимание

Решение «лексиконизировать ли поле» — единое для нарезки, рендера и редактора. Поэтому менять mpc_translated_content нужно с последующей перенарезкой: иначе каттер поставит | lexicon там, где грабер не завёл ключ (или наоборот), и на сайте получите пустую строку.

Исключения

Даже если тип поля переводимый, конкретное имя можно исключить. Список исключений лежит в файле, путь к которому задаёт mpc_exclude_lexicons_filename (по умолчанию components/migxpageconfigurator/services/exclude_lexicons.inc.php).

В дефолтном файле — только generic-исключения, общие для любого проекта: служебные поля MIGX/секций (MIGX_id, section_name, is_static, limit…) и нативное поле ресурса pagetitle (его MODX читает напрямую в <title>, меню, хлебных крошках — там ключ вместо значения недопустим).

Осторожно

Проектные исключения держите в отдельном файле и указывайте путь к нему в mpc_exclude_lexicons_filename. Дефолтный файл при апгрейде пакета перезапишется, и ваши правила потеряются.

Поддерживаются точные имена и паттерны:

$excludeLexiconFields = [
  'promo_subtitle',          // точное имя поля
  '*_alt',                   // glob: все alt-поля
  'cards_[2n+1]_title',      // числовой токен: нечётные строки списка
  '/^hero_\d+_caption$/',    // regex-литерал
];

Проверка идёт по трём формам ключа: имя поля, полный путь parentFieldName_fieldName и итоговый lex-ключ с префиксом секции.

Три уровня лексиконов

Файлы лежат в mpc_lexicon_path (по умолчанию components/migxpageconfigurator/lexicon/), в подпапке по культуре: {культура}/{идентификатор}.inc.php. Идентификатор (имя файла) берётся из поля ресурса, заданного настройкой mpc_lexicon_filename_field (по умолчанию alias, фоллбэк — id).

Уровней — три, по возрастанию приоритета:

1. global (page-types) — общий файл для всех страниц. Сюда попадают статические секции. Идентификатор — ресурс «Типы страниц» (mpc_static_block_page_id).
2. type (тип страницы) — наследуется всеми страницами одного типа. Это ресурс-донор: parent = «Типы страниц» и тот же template, что у страницы.
3. resource (ресурс) — лексикон самой страницы, файл по её идентификатору.

При рендере файлы грузятся именно в этом порядке, поэтому ресурсный уровень перебивает type, а type — global. Это нужно держать в голове: значение на странице — это «самый специфичный» из найденных ключей.

Внимание

Если секцию перевели из обычной в статическую, её ключи переезжают на уровень page-types, но старые ресурсные ключи нужно вычистить — иначе они перебьют page-types. Компонент делает это сам при сохранении ресурса; подробнее — в разделе Статические секции.

Языки и синхронизация

Язык по умолчанию задаётся настройкой mpc_default_language (по умолчанию ru), список всех языков — mpc_available_languages (CSV, по умолчанию пусто = один язык).

При нарезке пишется файл языка по умолчанию, а остальные языки синхронизируются по набору ключей:

• существующий перевод сохраняется;
• новый ключ получает значение языка по умолчанию как плейсхолдер (страница не ломается до того, как переведут);
• ключи удалённых полей выбрасываются.

То есть набор ключей всегда одинаков во всех языках, отличаются только значения.

Контакты

У контактов переводимость настраивается отдельно — настройкой mpc_contact_lexicon_fields (по умолчанию только caption). Если нужно переводить ещё значение, форматированное значение и атрибуты — поставьте caption,value,fvalue,attributes. Подробнее про сами контакты — в разделе Работа с контактами.

Почему ##'ключ' | lexicon}, а не {$field | lexicon}

Это деталь реализации, но она объясняет вид плейсхолдеров в нарезанных чанках. Lexicon-файл ресурса подгружается позже первого (eager) прохода parseChunk. Если бы плейсхолдер резолвился на этом проходе ({-префикс), переопределённый модификатор lexicon ещё не нашёл бы ключ и вернул пусто.

Поэтому каттер эмитит отложенный тег с префиксом ##:

##'hero_title' | lexicon}

На финальном проходе рендера (когда лексикон ресурса уже загружен) ## меняется на {, и модификатор отрабатывает корректно. Вручную городить {$_modx->lexicon(...)} в шаблоне не нужно — это делает нарезка.

Связанные настройки

Полный список — в разделе Справочник системных настроек. Ключевые для лексиконов:

Настройка	По умолчанию	Назначение
mpc_use_lexicons	0	включить режим лексиконов
mpc_translated_content	text,contact	какие типы контента переводимы
mpc_exclude_lexicons_filename	…/services/exclude_lexicons.inc.php	файл со списком исключений
mpc_lexicon_filename_field	alias	поле ресурса для имени lexicon-файла
mpc_lexicon_path	…/lexicon/	папка с lexicon-файлами
mpc_lexicons_namespace	migxpageconfigurator	namespace лексиконов MODX
mpc_default_language	ru	язык по умолчанию
mpc_available_languages	(пусто)	список языков (CSV)
mpc_contact_lexicon_fields	caption	переводимые под-поля контактов