Polylang

Описание

Компонент Polylang позволяет создавать мультиязычные и мультидоменные сайты без дополнительных контекстов.

Возможности

• Локализация полей документов Modx
• Локализация Tv
• Локализация полей miniShop2 (добавленных через msFieldsManager)
• Локализация опций miniShop2
• Изменения типа ввода данных для полей
• Изменения порядка вывода полей в админке
• Изменение порядка вывода языков на сайте
• Автоматический перевод поля или группы полей локализации через google translate, yandex translate или PROMT
• Задание полей, для которых следует использовать автоматический перевод
• Автоматическое создание локализаций для документа с автоматическим переводом полей
• Индексация полей локализаций в mSearch2
• Авто определение языковой версии сайта при первом его посещении
• URL с слэшем на конце и без

Интеграция

• msFieldsManager
• plAlert
• plCustomMenu
• miniShop2
• mSearch2
• pdoTools
• msMultiCurrency
• MIGX
• msImportExport — В планах

Зависимости

• pdoTools

Видео-обзор

Основная настройка компонента

• Настройка “Использовать дружественные 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
    ...

Настройка мультидоменности

Чтобы создать мультидоменность необходимо выполнить следующие шаги:

1. Для основного домена добавить алиас в виде дополнительного домена
2. На странице настройки Polylang в вкладке “Языковые версии” добавить нужные языки. При создании языковых версий следует руководствоваться следующим правилами:
   
   • если для всех доменов контент страниц и локализаций не отличается, то достаточно указать нужные языки с указанием в поле “шаблон URL” плейсхолдеров [[+schema]][[+base_domain]]
     
     
   
   
   • если же контент или лексиконы для каждого домена отличаются, то необходимо в поле “шаблон URL” явно указывать для каждого домена его имя и язык
     
     
3. Если контент или лексиконы для каждого домена отличаются, то в системной настройке компонента (ключ polylang_default_domain_settings) для каждого домена нужно задать параметры по умолчанию.
   Пример
   

   {"site.com":{"default_language":"en","language_group":"1"},"site.de":{"default_language":"de_de","language_group":"2"}}

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






Установка для языка “языковой группы” позволяет вывести сниппетам PolylangLinks, PolylangCanonical, PolylangSitemap ссылки на разные языки разных доменов

Автоматическая переадресации на языковую версию сайта в зависимости от страны посетителя

Для автоматической переадресации на языковую версию сайта в зависимости от страны посетителя необходимо включить опцию “Автоопределение языка по коду страны посетителя” (polylang_geo_detect_language) и настроить связку код страны — код языка локализации в опции “Язык для страны“ (polylang_geo_language_country).

Гео данные посетителя будут определятся с помощью класса указанного в опции “Класс Geo Locator“ (polylang_geo_locator_handler_class).

Автоматическая переадресации на домен в зависимости от гео локации посетителя

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

1. в системной опции “Настройки домена по умолчанию” (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"}}

2. в системной опции “Название гео параметра” (polylang_geo_detect_domain_param) указать гео параметр на основании которого следует определять домен. Доступны следующие значения:
   
   • country_code — код страны
   • region — название региона
   • city — название города
3. в системной опции “Класс Geo Locator” (polylang_geo_locator_handler_class) указать название класса который будет использоваться для получения геолокационных данных по IP. Доступны следующие значения:
   
   • PolylangGeoLocatorIPInfo — бесплатный (до 50k запросов в месяц) сервис ipinfo.io
   • PolylangGeoLocator — бесплатный (не всегда коректно определеят геоданные) сервис geoplugin.com
   
   При необходимости можно создать свой класс в core/components/polylang/handlers/geo, который должен быть наследником PolylangGeoLocatorHandler
   
4. В системной опции “Автоопределение домена по геоданным” (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();

Создание SEO-тегов для шаблонов сайта

Включение в системных настройках опции «Включить SEO шаблоны» (polylang_seo_pattern_enabled) позволит использовать SEO-теги предварительно созданные для каждого языка с привязкой к шаблону сайта.

На странице настройки компонента во вкладке «SEO» сначала необходимо добавить поле с произвольным именем на латинице, которое в дальнейшем будет использоваться как плейсхолдер.

После добавления полей, во вкладке «Шаблоны» добавляем шаблон для созданных полей с привязкой к языку.

Пример значения для шаблона:

Цена [[+price]] на товар "[[+pagetitle]]" в магазине [[++site_name]]

После чего можно в шаблоне сайта выводить плейсхолдеры [[+pl_имя_поля]] или {$pl_имя_поля}.

<!doctype html>
    <html lang="en">
    <head>
        <meta charset="UTF-8">
        <title>[[+pl_title]]</title>
        <meta name="description" content="[[+pl_description]]">
    </head>
    </html>

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'}

не поддерживаются, место них стоит использовать сниппет pdoField

phpThumbOn

Для корректной работы следует использовать модификатор 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 — переключение языка:

1. $tools — экземпляр класса PolylangTools
2. $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; DeepL или PROMT. Для этого в системной настройке Polylang “Класс переводчика” (polylang_class_translator) нужно указать одно из значений:

• PolylangTranslatorGoogl
• PolylangTranslatorYandex
• PolylangTranslatorYandexCloud
• PolylangTranslatorDeepl
• 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).

Для использования PolylangTranslatorDeepl необходимо получит ключ доступа https://www.deepl.com/pro-api?cta=header-pro-api к API и указать его в системной настройке “API ключ для DeepL переводчика” (polylang_translate_deepl_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

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

1. включить в системных настройках опцию «Устанавливать валюту по умолчанию»
2. указать в языке валюту
   
   

Код плагина для переключения валюты при смене языка

<?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}

В примере перевод названий опций содержится в словаре miniShop2

mFilter2

Для правильной работы с mFilter2 существует специальный класс обработчик. Для его активации нужно указать в системной настройке mSearch2 “Класс-обработчик фильтров” (mse2_filters_handler_class) значение mse2PolylangFilter

Локализация пользовательского текста

Для локализации разнообразного текста на фронтенде можно создать нужные переводы в словаре компонента в теме “site”.

Локализации способов оплаты и доставки miniShop2

Необходимо создать лексикон в словаре компонента в теме “site” название которого привязать к id варианты оплаты или доставки.
Например название лексикона для оплаты с id 1 будет таким polylang_site_payment_1, то выводить его в чанке следует так

{('polylang_site_payment_' ~ $payment.id) | lexicon}