- Проверено Modstore
- Бесплатные будущие обновления
- Работа на тестовом и публичном домене
- 12 месяцев тех. поддержки
Описание
Компонент Polylang позволяет создавать мультиязычные и мультидоменные сайты без дополнительных контекстов.
Возможности
- Локализация полей документов Modx
- Локализация Tv
- Локализация полей miniShop2 (добавленных через msFieldsManager)
- Локализация опций miniShop2
- Изменения типа ввода данных для полей
- Изменения порядка вывода полей в админке
- Изменение порядка вывода языков на сайте
- Автоматический перевод поля или группы полей локализации через google translate, yandex translate или PROMT
- Задание полей, для которых следует использовать автоматический перевод
- Автоматическое создание локализаций для документа с автоматическим переводом полей
- Индексация полей локализаций в mSearch2
- Авто определение языковой версии сайта при первом его посещении
- URL с слэшем на конце и без
Интеграция
- msFieldsManager
- plAlert
- plCustomMenu
- miniShop2
- mSearch2
- pdoTools
- msMultiCurrency
- MIGX
- msImportExport — В планах
Зависимости
Видео-обзор
Основная настройка компонента
- Настройка “Использовать дружественные URL” (friendly_urls) должна быть включена (установлена в состояние “Да”)
- Настройка “Строгий режим дружественных URL” (friendly_urls_strict) должна быть выключена (установлена в состояние “Нет”)
- Обязательно создать страницу для 404 ошибки и указать ее ID в системной настройке “Страница ошибки 404 «Документ не найден»“ (error_page)
- Настройка “Схема URL” (link_tag_scheme) должна быть либо abs, либо full
- Для того чтобы URL всех страниц был без слеша на конце, необходимо указать пустое значение в настройке “Суффикс контейнера” (container_suffix)
- Включение системной настройки “Автоопределение языка посетителя” (polylang_detect_visitor_language) позволяет при первом посещении сайта перебросить посетителя на языковую версию сайта, определенную на основании языка его системы.
- Системная настройка “Ключ языка посетителя по-умолчанию” (polylang_visitor_default_language) позволяет указать языковую версию сайта, на которую следует перебросить посетителя при первом визите, если для языка его системы нет языковой версии сайта.
ВАЖНО! Все статические файлы (фото, стили, шрифты, скрипты и т.д) должны находится в директории assets.
Настройка веб-сервера nginx
Для того, чтобы веб-сервер nginx корректно обрабатывал URL адреса и корректно отдавал статичные ресурсы, в раздел server вашего сайта добавьте следующие строки:
для любых адресов типа mysite.ru/XX/ (где XX — например en, ua, es и т.д.)
#language rewrite
location ~ "^/([a-z]{2})/" {
rewrite "^/([a-z]{2})/(.*)" /$2 last;
}
если вы хотите жестко прописать доступные языковые версии (например только en, ua и es):#language rewrite
location ~ "^/(en|ua|es)/" {
rewrite "^/(en|ua|es)/(.*)" /$2 last;
}
для любых адресов вида http://(ЯЗЫК).mysite.ru/server_name mysite.ru *.mysite.ru;
если вы хотите жестко прописать доступные языковые версии (например только en, ua и es):server_name mysite.ru en.mysite.ru ua.mysite.ru es.mysite.ru;
Настройка веб-сервера apache
В файл .htaccess (в корневой директории сайта) перед # The Friendly URLs part необходимо внести следующие строки:# Language rewrite
RewriteCond %{REQUEST_URI} ^/(en|ua|es)/assets/.*
RewriteRule ^(en|ua|es)/assets/(.*)$ assets/$2 [L,QSA]
RewriteCond %{REQUEST_URI} ^/(en|ua|es)/(.*)
RewriteRule ^(en|ua|es)/(.*)$ $2 [L,QSA]
# В некоторых случаях RewriteRule ^(en|ua|es)/(.*)$ $2 [L,QSA] нужно заменить на RewriteRule ^(en|ua|es)/(.*)$ $2 [QSA]
# The Friendly URLs part
...
Настройка мультидоменности
Чтобы создать мультидоменность необходимо выполнить следующие шаги:- Для основного домена добавить алиас в виде дополнительного домена
- На странице настройки Polylang в вкладке “Языковые версии” добавить нужные языки. При создании языковых версий следует руководствоваться следующим правилами:
- если для всех доменов контент страниц и локализаций не отличается, то достаточно указать нужные языки с указанием в поле “шаблон URL” плейсхолдеров [[+schema]][[+base_domain]]
- если же контент или лексиконы для каждого домена отличаются, то необходимо в поле “шаблон URL” явно указывать для каждого домена его имя и язык
- если для всех доменов контент страниц и локализаций не отличается, то достаточно указать нужные языки с указанием в поле “шаблон URL” плейсхолдеров [[+schema]][[+base_domain]]
- Если контент или лексиконы для каждого домена отличаются, то в системной настройке компонента (ключ polylang_default_domain_settings) для каждого домена нужно задать параметры по умолчанию.
Пример
{"site.com":{"default_language":"en","language_group":"1"},"site.de":{"default_language":"de_de","language_group":"2"}}
Если несколько доменов имеют общий язык, то можно один из них указать в качестве родительского, что в дальнейшем позволит при создании или редактировании локализаций “родительского языка” автоматически создавать или копировать контент в зависимые языки.




Установка для языка “языковой группы” позволяет вывести сниппетам PolylangLinks, PolylangCanonical, PolylangSitemap ссылки на разные языки разных доменов
Автоматическая переадресации на домен в зависимости от гео локации посетителя
Если сайт является мультидоменным и необходимо перенаправлять посетителя в зависимости от его геолокации полученной на основании IP (код страны, регион, город) на определенный домен, то необходимо выполнить следующие действия.
- в системной опции “Настройки домена по умолчанию” (polylang_default_domain_settings) для нужного домена добавить парамет “geo_domains” который должен содержать список значений геолокация- домен.
Пример для кода страны:{"site.ru":{"default_language":"ru","force_language":"","language_group":"1","geo_domains":{"UA":"site.ua","US":"site.com"}},"site.ua":{"default_language":"uk","force_language":"","language_group":"2"},"site.com":{"default_language":"en","force_language":"","language_group":"1,2,3"}}
- в системной опции “Название гео параметра” (polylang_geo_detect_domain_param) указать гео параметр на основании которого следует определять домен. Доступны следующие значения:
- country_code — код страны
- region — название региона
- city — название города
- в системной опции “Класс Geo Locator” (polylang_geo_locator_handler_class) указать название класса который будет использоваться для получения геолокационных данных по IP. Доступны следующие значения:
- PolylangGeoLocatorIPInfo — бесплатный (до 50k запросов в месяц) сервис ipinfo.io
- PolylangGeoLocator — бесплатный (не всегда коректно определеят геоданные) сервис geoplugin.com
При необходимости можно создать свой класс в core/components/polylang/handlers/geo, который должен быть наследником PolylangGeoLocatorHandler
- В системной опции “Автоопределение домена по геоданным” (polylang_geo_detect_domain) выбрать “Да”
На определения домена можно также повлиять через системное событие OnDetectPolylangGeoRedirectDomain
Параметры события
- tools — ссылка на объект PolylangTools
- geoLocator — ссылка на объект PolylangGeoLocator
- geoParam — название геолокационного параметра (country_code;region или city)
- geoDomains — массив значений из geo_domains для текущего домена из polylang_default_domain_settings
- geoValue — геолокационное значения посетителя
- domain — определенное название домена на который следует перенаправить посетителя
Пример плагина для события OnDetectPolylangGeoRedirectDomain
<?php
/**
* @var modX $modx
* @var PolylangTools $tools
* @var PolylangGeoLocator $geoLocator
* @var array $geoDomains
* @var string $geoParam
* @var string $geoValue
* @var string $domain
*/
switch ($modx->event->name) {
case 'OnDetectPolylangGeoRedirectDomain':
if (
empty($domain) &&
$geoParam == 'country_code' &&
$geoValue == 'RU'
) {
$modx->event->returnedValues['domain'] = 'site.shop';
}
break;
}
Пример получения геоданных в консоли modx
<?php
/**
* @var modX $modx
* @var Polylang $polylang
* @var PolylangTools $tools
* @var PolylangGeoLocator $geoLocator
*/
$polylang = $modx->getService('polylang','Polylang');
$tools = $polylang->getTools();
$geoLocator = $polylang->getGeoLocator();
$ip = $tools->getClientIp();
$geoLocator->setIp($ip);
echo $geoLocator->getCountryCode();
//echo $geoLocator->getRegion();
//echo $geoLocator->getCity();
404 ошибка для документов без локализации
По умолчанию если у документа для какого либо языка нет локализации возвращается документ с оригинальным текстом, чтобы место этого выдавать 404 ошибку в системных настройках компонента включить опцию “Использовать 404 ошибку” (polylang_use_error_404). Если нужно чтобы 404 ошибка выдавалась для определенных ресурсов то в опции “Использовать 404 ошибку только для ресурсов” (polylang_use_error_404_resources) укажите через запятую список ID таких ресурсов.
На определения 404 ошибки можно также повлиять через системное событие OnHasPolylangError404
Параметры события
- tools — ссылка на объект PolylangTools
- resources — массив ID ресурсов из опции polylang_use_error_404_resources
- has — наличие 404 ошибки (true|false)
Пример плагина для события OnHasPolylangError404
<?php
/**
* @var modX $modx
* @var PolylangTools $tools
* @var array $resources
* @var bool $has
*/
switch ($modx->event->name) {
case 'OnHasPolylangError404':
$myIDs = array(1,2,4);
$id = $modx->resource ? $modx->resource->get('id') : 0;
if (
$id &&
empty($has) &&
in_array($id,$myIDs)
) {
$modx->event->returnedValues['has'] = true;
}
break;
}
Исключение из результатов сниппетов ресурсов без локализации
Если необходимо исключить из результатов работы сниппетов ресурсы которые не содержат для текущего языка локализаций, то добавьте в вызов сниппета прамметр onlyWithLocalization с значением 1.
Важно! Данная опция будет работать только в сниппетах которые в своей работе используют pdoFetch.
Пример
[[pdoResources?
&tpl=``
&parents=`0`
&onlyWithLocalization=`1`
]]
Теги fastField
Теги fastField, т/е конструкции типа[[#15.pagetitle]]
{27 | resource : 'pagetitle'}
не поддерживаются, место них стоит использовать сниппет pdoFieldphpThumbOn
Для корректной работы следует использовать модификатор Polylang2BaseUrl.Пример
[[+image:Polylang2BaseUrl:phpthumbon=`w=610&h=305&q=80&zc=1`]]
Код языка в шаблоне/чанке
Доступ к коду текущего языка в шаблоне/чанке можно получить через плейсхолдеры: [[++cultureKey]] и [[++lang]].В [[++cultureKey]] содержится исходное значения кода языка из локализации, а в [[++lang]] левая часть кода языка (если код языка из 2х частей). Например если код языка en_UK или en-UK то в [[++cultureKey]] будет en-UK , а в [[++lang]] en.
<html lang="[[++cultureKey]]">
<img src="/assets/flags/flag_[[++lang]].png">
Сниппеты
PolylangLinks — Сниппет выводит список языков на фронтенде.
Параметры:
tpl — Fenom чанк оформления работы сниппета. По умолчанию: tpl.PolylangLinks
mode — Вид вывода. Доступные значения:dropdown;list. По умолчанию: dropdown
scheme — Схема формирования URL.(аналогично параметру $scheme метода $modx->makeUrl) По умолчанию: значение и системной настройки link_tag_scheme.
showActive — Показывать ли ссылку текущего языка. По умолчанию: 0.
activeClass — Класс для текущего языка.
languageGroup — Список ID языковых групп, через запятую. По умолчанию берется из системной настройки polylang_default_language_group или polylang_default_domain_settings
onlyWithLocalization — Выводить только если есть локализация. По умолчанию 0.
trigger — Название класса у ссылки переключения языка. По умолчанию: polylang-toggle
js — если вы хотите использовать собственные скрипты — укажите путь к ним здесь, или очистите параметр и загрузите их вручную через шаблон сайта.
css — если вы хотите использовать собственные стили — укажите путь к ним здесь, или очистите параметр и загрузите их вручную через шаблон сайта.
PolylangMakeUrl — Сниппет создает URL для ресурса с учетом выбранной языковой версии сайта.
Параметры:
id — ID ресурса. По умолчанию: текущий
scheme — Схема формирования URL.(аналогично параметру $scheme метода $modx->makeUrl) По умолчанию: значение и системной настройки link_tag_scheme.
PolylangSitemap — Сниппет генерации карты сайта, все параметры идентичны параметрам pdoSitemap.
Параметры:
languageGroup — Список ID языковых групп, через запятую. По умолчанию берется из системной настройки polylang_default_language_group или polylang_default_domain_settings
onlyWithLocalization — Выводить только существующие локализации. По умолчанию 0.
PolylangCanonical — Сниппет выводит canonical ссылки.
Параметры:
tpl — Fenom чанк оформления работы сниппета.
onlyWithLocalization — Выводить только для существующих локализаций. По умолчанию 0.
languageGroup — Список ID языковых групп, через запятую. По умолчанию берется из системной настройки polylang_default_language_group или polylang_default_domain_settings
PolylangMsOptions — Обертка над сниппетом msOptions.
PolylangField — Обертка над сниппетом pdoField с возможностью вывести значения поля на нужном языке.
Параметры:
lang — Код языка.
Пример использования:
[[PolylangField?
&id=`[[*id]]`
&field=`longtitle`
&lang=`en`
]]
PolylangMigxGetImageList — Обертка над Migx сниппетом getImageList.
Системные события
OnTogglePolylangLanguage — переключение языка:
- $tools — экземпляр класса PolylangTools
- $language — выбранный язык, экземпляр класса PolylangLanguage
TV и опции miniShop2
Важно! Не используйте в названиях переменных дефис.Для того, что бы необходимые TV или опции miniShop2 появились в окне локализации, необходимо на странице настройки TV отметить чекбокс “TV доступно в локализациях”, а на странице настройки опции miniShop2 отметить чекбокс “Опция доступна в локализациях”
Индексация в mSearch2
Для того, что бы поля локализаций индексировались в mSearch2, необходимо в системных настройках Polylang включить опцию “Индексировать поля в mSearch2” (polylang_mse2_index), после чего все поля указанные в системной настройки mSearch2 “Индексация полей” (mse2_index_fields), для которых есть перевод в Polylang, будут так же индексироваться. Для добавления в индекс опции товара, необходимо к ее названию добавить префикс “option_”, а для TV поля добавить префикс “tv_”.
Перевод
Из “коробки” перевод можно осуществить с помощью API google translate, yandex translate, Yandex Cloud translate или PROMT. Для этого в системной настройке Polylang “Класс переводчика” (polylang_class_translator) нужно указать одно из двух значений: PolylangTranslatorGoogl; PolylangTranslatorYandex или PolylangTranslatorPromt .
Для использования PolylangTranslatorGoogl необходимо получит ключ доступа https://cloud.google.com/translate/ к API и указать его в системной настройке “API ключ для Google переводчика” (polylang_translate_google_key).
Для использования PolylangTranslatorYandex необходимо получит ключ доступа https://translate.yandex.ru/developers/keys к API и указать его в системной настройке “API ключ для Яндекс переводчика” (polylang_translate_yandex_key).
Для использования PolylangTranslatorYandexCloud необходимо получит ключ доступа https://translate.yandex.ru/developers/keys к API и указать его в системной настройке “API ключ для Яндекс Cloud переводчика” (polylang_translate_yandex_cloud_key).
Для использования PolylangTranslatorPromt необходимо ключ доступа к API и указать его в системной настройке “Настройки API для PROMT переводчика” (polylang_translate_promt_config).
Примечание. Включение в системных настройках опция «Пост обработка перевода» (ключ polylang_post_processing_translation) позволяет удалить пробелы в тегах modx которые там могут появиться после перевода.
Автоматический перевода группы ресурсов из консоли.
Чтобы сделать массовый перевод какой то группы можно воспользоваться скриптом
core/components/polylang/script/translate.php
который следует вызвать из командной строки (консоли) сервера. По умолчанию переводятся все стандартные ресурсы Modx c задержкой обращения к API переводчика в 1 сек. Что бы добавить к переводу категории или товары miniShop2 раскомментируйте соответствующую строку в коде:$classKeys = array(
'modDocument', // обычные ресурсы Modx
// 'msCategory', // категории miniShop2
// 'msProduct', // товар miniShop2
);
pdoTools
Если при установки Polylang вы не отметили чекбокс “Переопределить класс pdoFetch” и вам нужно, что бы сниппеты пакета pdoTools (pdoResources, pdoMenu) работали с перевеленными полями, то необходимо изменить значение системной настройки:
pdoFetch.class на PolylangFetch и pdofetch_class_path на {core_path}components/polylang/model/polylang/
msMultiCurrency
При первом визите на сайт можно задать какая валюта должна быть выбрана по умолчанию, для этого необходимо:
Код плагина для переключения валюты при смене языка
<?php
/**
* @var modX $modx
* @var PolylangLanguage $language
*/
switch ($modx->event->name) {
case 'OnTogglePolylangLanguage':
if ($language->getCurrencyId()) {
/** @var MsMC $msmc */
$msmc = $modx->getService('msmulticurrency', 'MsMC');
$msmc->setUserCurrency($language->getCurrencyId());
}
break;
}
Важно! Ссылка переключения языка должна иметь класс polylang-toggle или тот который указан в параметре trigger сниппета PolylangLinks.
miniShop2
В сниппете msGetOrder название товара на языке при котором был создан заказ можно получить следующим образом:
{$order.properties.polylang.pagetitle[$product.id]}
Для того, что бы сниппет msProductOptions выводил название опций на выбранном языке необходимо заменить в его чанке строку
{$option.caption}
на{('ms2_product_' ~ $option.key) | lexicon}
В примере перевод названий опций содержится в словаре miniShop2mFilter2
Для правильной работы с mFilter2 существует специальный класс обработчик. Для его активации нужно указать в системной настройке mSearch2 “Класс-обработчик фильтров” (mse2_filters_handler_class) значение mse2PolylangFilter
Локализация пользовательского текста
Для локализации разнообразного текста на фронтенде можно создать нужные переводы в словаре компонента в теме “site”.

Локализации способов оплаты и доставки miniShop2
Необходимо создать лексикон в словаре компонента в теме “site” название которого привязать к id варианты оплаты или доставки.Например название лексикона для оплаты с id 1 будет таким polylang_site_payment_1, то выводить его в чанке следует так
{('polylang_site_payment_' ~ $payment.id) | lexicon}
Polylang 1.3.0
- Изменено: Минимальная версия php не ниже 7.3
- Добавлено: Поддержка переводчика Yandex Cloud
Polylang 1.2.19
- Исправлено: Индексация полей mSearch2
Polylang 1.2.18
- Исправлено: Удалите Tv послей после сохранения объекта «PolylangContent»
Polylang 1.2.17
- Исправлено: URL-адрес для TV полей с типом ввода "Изображение"
Polylang 1.2.16
-Добавлено: методы getTVValue и setTVValue для класса PolylangContent
Polylang 1.2.15
- Добавлено: Поддержка tv типа "Авто-метка"
- Добавлено: Поддержка параметра tvFilters для сниппетов pdoTools
Polylang 1.2.13
- Добавлено: Параметр onlyWithLocalization для сниппетов: PolylangLinks;PolylangCanonical;PolylangSitemap
Polylang 1.2.12
- Исправлено: URL-адрес для TV полей с типом ввода "Изображение"
Polylang 1.2.11
- Исправлено: Перевод TV полей с типом ввода "текстовый редактор"
Polylang 1.2.10
- Исправлено: Перевод Migx полей
Polylang 1.2.9
- Исправлено: Дублирование лексиконов при их копировании и переводе
Polylang 1.2.8
- Добавлено: Автоматическая переадресации на домен в зависимости от гео локации посетителя
- Добавлено: Генерация 404 ошибки для ресурсов бел локализации для выбранного языка
- Добавлено: Параметр "onlyWithLocalization" для сниппетов использующих pdoTools
- Добавлено: Опции "polylang_use_error_404" и "polylang_use_error_404_resources"
- Добавлено: События "OnDetectPolylangGeoRedirectDomain" и "OnHasPolylangError404"
- Исправлено: Перевод лексиконов
Polylang 1.2.7
- Добавлено: Сниппет "PolylangMigxGetImageList"
Polylang 1.2.6
- Исправлено: Uncaught Error: Call to undefined function GuzzleHttp\Psr7\stream_for()
Polylang 1.2.5
- Добавлено: Сниппет "PolylangField"
- Исправлено: Перевод сразу всех полей
- Исправлено: JS ошибка "tinyMCE.getInstanceById is not a function"
Polylang 1.2.4
- Исправлено: Поля TV с типом "фото" и "файл"
- Изменено: Включено декодирование JSON данных полей.
Polylang 1.2.3
- Добавлено: Импорт/экспорт лексиконов -Исправлено: Работа с контекстами -Исправлено: Определения языков для Ajax запросов -Исправлено: Ключ кеша ресурса
Polylang 1.2.2
-Исправлено: Установка языка по умолчанию
Polylang 1.2.1
-Исправлено: Определение хоста
Polylang 1.2.0
- Добавлено: Поддержка мультидоменности
- Добавлено: Опция "polylang_default_domain_settings"
- Добавлено: Событие "OnSetPolylangDefaultSettings"
- Добавлено: Политика доступа
- Добавлено: Клонирование контента как отдельного поля так и всей локализации
- Добавлено: Страница управления лексиконом
- Добавлено: Перевод лексиконов
- Добавлено: Клонирование лексиковнов
- Исправлено: Сниппет "PolylangSitemap"
Polylang 1.1.2
- Изменено: Чанк tpl.PolylangLinks (добавлен класс polylang-toggle)
- Обновлено: Сниппет PolylangLinks (добавлен параметр «trigger»).
Polylang 1.1.1
- Добавлено: Событие OnTogglePolylangLanguage
Polylang 1.1.0
- Добавлено: Поддержка переводчика PROMT
- Добавлено: Поддержка компонента msMultiCurrency
- Добавлено: Сниппет "PolylangSitemap"
- Добавлено: Опции polylang_set_currency_for_language; polylang_post_processing_translation; polylang_disallow_translation_completed_field
Polylang 1.0.11
- Добавлено: Опция "polylang_post_processing_translation" (удаление лишних пробелов из тегов Modx после перевода)
Polylang 1.0.10
Добавлено: PHP скрипт для запуска автоматического перевода группы ресурсов из консоли.
Polylang 1.0.9
- Добавлено: Сниппет PolylangCanonical.
- Исправлено: Создание полного URL
- Исправлено: Автозаполнение полей
Polylang 1.0.8
- Исправлено: Сохранение данных в редакторах: CKEditor;TinyMCE
Polylang 1.0.7
- Исправлено: Сохранение данных полей: размеры и теги
Polylang 1.0.6
- Добавлено: Системная опция polylang_reload_lexicon
- Исправлено: Получение языка по умолчанию
Polylang 1.0.5
- Добавлено: Работа google translate с обозначением украинского языка "ua"
Polylang 1.0.4
- Исправлено: Вкладка «Опции товара»
Polylang 1.0.3
- Добавлено: Локализация возможных значений Tv полей
Polylang 1.0.2
- Добавлено: Сниппеты "PolylangMsOptions" and "Polylang2BaseUrl"
Polylang 1.0.1
- Исправлено: Отображение TV richtext поля
Последние обсуждения в сообществе MODX.pro