Лексиконы в MODX: руководство по созданию и применению

Что такое лексиконы в MODX?

Лексиконы в MODX представляют собой набор языковых строк (ключ — значение), которые используются для вывода текста на сайте или в административной панели. Это своего рода словарь, где ключи — это уникальные идентификаторы, а значения — соответствующие им переводы или текстовые фразы. Лексиконы особенно полезны для:

• Локализации сайтов на разные языки.
• Управления текстами в шаблонах, чанках и сниппетах.
• Настройки интерфейса административной панели.
• Создания гибких решений для динамического контента.

Пример: в прошлом уроке мы разбирались как при помощи babel создать мультиязычный сайт, и я показывал это все на 2х языках:

[[*context_key:is=`web`:then=`Контактная информация`]]
[[*context_key:is=`en`:then=`Contact Information`]]

или это же 1й строчкой, при помощи модификаторов: [[++cultureKey:is=`ru`:then=`Контактная информация`:else=`Contact Information`]].

А теперь представим, что языка у нас не 2, а к примеру 5 или 10, тогда модификаторы уже не катят, да и делать 10 выводов типа: [[*context_key:is=`web`:then=`Контактная информация`]], для каждого контекста, тоже как-то не серьезно. И вот как раз тут на помощи приходят лексиконы: мы можем создать ключ к примеру welcome_message, и написать для него переводы хоть на 100 языках, таких как «Welcome to the site!» (английский) или «Bienvenido al sitio!» (испанский). Далее вывести его 1 раз в шаблоне, сниппете, или еще где-нибудь и все будет автоматом выводится на нужно языке.

Лексиконы в MODX делятся на два типа:

1. Системные лексиконы — встроенные строки, используемые в ядре MODX для интерфейса админки.
2. Пользовательские лексиконы — создаются разработчиками для собственных компонентов, шаблонов или дополнений.

Преимущества использования лексиконов

• Гибкость: легко изменять текст без правки кода.
• Многоязычность: поддержка нескольких языков в одном проекте.
• Удобство: централизованное управление текстовыми данными.
• Повторное использование: один ключ можно применять в разных частях сайта.
• SEO-дружелюбность: возможность оптимизировать тексты под разные языки и регионы.

Создание лексиконов в MODX

Создание лексиконов в MODX — это процесс добавления языковых строк в систему. Лексиконы можно создавать как через файлы, так и через интерфейс админки. Рассмотрим оба подхода.

Создание лексиконов через файлы

Файловый подход чаще используется разработчиками, так как он удобен для версионирования и работы в команде. Лексиконы хранятся в PHP-файлах в виде массивов.

Шаг 1: Определите пространство имен

Пространство имен (namespace) — это уникальный идентификатор вашего компонента. Например, если вы создаете дополнение «MyComponent», пространство имен будет mycomponent.

Шаг 2: Создайте структуру папок и файлов лексикона

Лексиконы обычно хранятся в папке core/components/название_компонента/lexicon/. Например:

core/components/mylexicon/lexicon/
├── en/
│   └── default.inc.php
├── ru/
│   └── default.inc.php

Каждая папка соответствует языку (en — английский, ru — русский).

В файле default.inc.php определите массив $_lang с парами ключ-значение. Пример для русского языка (ru/default.inc.php):

<?php
$_lang['welcome_message'] = 'Добро пожаловать на сайт!';
$_lang['contact_us'] = 'Свяжитесь с нами';
$_lang['error_404'] = 'Страница не найдена';

Для английского языка (en/default.inc.php):

<?php
$_lang['welcome_message'] = 'Welcome to the site!';
$_lang['contact_us'] = 'Contact us';
$_lang['error_404'] = 'Page not found';

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

Вот пример заполнения default.inc.php:

Шаг 3: Регистрация пространства имен

Чтобы MODX распознал ваши лексиконы, зарегистрируйте пространство имен в админке:

1. Перейдите в Система (шестеренка) → Пространства имен.
2. Нажмите Создать новый и в сплывающем окне укажите:
   • Имя: mycomponent.
   • Путь: {core_path}components/mylexicon/.
3. Сохраните.

Создание лексиконов через админку

Если вы предпочитаете работать через интерфейс, MODX позволяет добавлять лексиконы в разделе Система (шестеренка) → Управление словарями.

Шаг 1: Перейдите в управление лексиконами

В админке откройте Система → Управление словарями.

Шаг 2: Выберите пространство имен и тему

• Пространство имен: выберите существующее или создайте новое (например, mylexicon).
• Тема: обычно используется default, но вы можете создать свою (например, frontend для текстов сайта).

Шаг 3: Добавьте записи

1. Нажмите Добавить новую запись.
2. Укажите:
   • Ключ: например, welcome_message.
   • Значение: текст, например, «Добро пожаловать на сайт!».
   • Язык: выберите нужный (ru, en и т.д.).
3. Сохраните.

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

Подключение лексиконов в MODX

После создания лексиконов их нужно подключить к шаблонам, чанкам, сниппетам или плагинам. MODX предоставляет несколько способов для этого.

Использование лексиконов в шаблонах и чанках

Для вывода строки из лексикона в шаблоне или чанке используется тег [[%ключ]]. Пример:

[[%lexicon_key]]

// Fenom
{$_modx->lexicon('lexicon_key')}

//или
{'lexicon_key' | lexicon}

Если вы хотите указать конкретное пространство имен или тему, используйте модификатор lexicon:

<h1>[[%welcome_message? &namespace=`mylexicon` &topic=`default`]]</h1>

Подключение лексиконов в сниппетах

В сниппетах лексиконы подключаются через метод $modx->lexicon(). Пример:

<?php
$welcome = $modx->lexicon('welcome_message', array(), 'mylexicon', 'default');
return $welcome;

Параметры:

• Первый: ключ лексикона (welcome_message).
• Второй: массив плейсхолдеров (если нужно заменить части текста).
• Третий: пространство имен (mycomponent).
• Четвертый: тема (default).

Подключение лексиконов в плагинах

В плагинах лексиконы подключаются аналогично, через $modx->lexicon(). Например:

<?php
$modx->log(modX::LOG_LEVEL_ERROR, $modx->lexicon('error_404'));

Указание языка

Чтобы лексиконы автоматически подстраивались под язык пользователя, настройте системную настройку cultureKey. Например:

• cultureKey = ru — для русского языка.
• cultureKey = en — для английского.

Вы также можете динамически менять язык в коде:

$modx->setOption('cultureKey', 'en');

Дополнительная информация

Вызов лексического значения в ExtJS: _('lexicon_key').

Вызов темы через xPDO:

$modx->lexicon->load('namespase:default');

// с указанием конкретного языка
$modx->lexicon->load('ru:namespase:default');

Для перевода пользовательских настроек системы используется запись лексикона, которая названа в честь ключа настройки с префиксом «setting_»: setting_ + Key

Описание должно следовать тому же формату и включать суффикс «desc»: setting_ + Key + _desc.

Частые ошибки и их решения

1. Лексикон не отображается:
   • Проверьте правильность пространства имен и темы.
   • Убедитесь, что файл лексикона находится в нужной папке.
   • Очистите кэш MODX.
2. Неправильный язык:
   • Проверьте настройку cultureKey.
   • Убедитесь, что файл лексикона существует для нужного языка.
3. Конфликты ключей:
   • Используйте уникальные префиксы для ключей, например, mycomponent_welcome.
4. Проблемы с кодировкой:
   • Убедитесь, что файлы лексиконов сохранены в UTF-8 без BOM.

Заключение

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

Лексиконы — это шаг к профессиональной разработке, который экономит время и повышает качество ваших проектов.