Polylang

Мультиязычность и мультидоменность без контекстов
Автор дополнения
Prihod
Пакетов
33
Закачек
10 101
Обычно отвечает в течение суток
Автор дополнения
Пакетов
33
Закачек
10 101
Обычно отвечает в течение суток
Версия 1.3.12-pl
Дата выпуска 12.12.2023
Загрузки 518
Просмотры 9 822
Внимание, этот компонент требует версию PHP 7.4 или выше! Если ваш сайт использует PHP ниже требуемого, установка этого дополнения может его сломать.
Внимание, этот компонент требует версию MODX не ниже 2.8 !

Описание

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


Возможности

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

Интеграция

Зависимости

Видео-обзор


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

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

[1.3.12-pl] - 2023-12-01

Исправлено

Кэширование работы сниппета PolylangSitemap Дата lastmod в sitemap.xml для локализаций

Добавлено

[1.3.11-pl] - 2023-11-27

Добавлено

  • Системная опция "Игнорировать 404 ошибку только для ресурсов"

[1.3.10-pl] - 2023-09-19

Исправлено

  • Кэширование данных mFilter
  • Кэширование 404 ошибки у локализаций

[1.3.9-pl] - 2023-06-23

Добавлено

  • Сортировка списка "Языковые группы"
  • Системная опция "Класс определения поискового робота"

Улучшено

  • Определение поискового бота

[1.3.8-pl] - 2023-03-10

Исправлено

  • SQL ошибка "rank" is a reserved word, can't be used as a field

[1.3.7-pl] - 2023-01-05

Изменено

  • Сниппет PolylangCanonical вывод ссылок в месте его вызова
  • Вывод Last-Modified заголовка для модификаций теперь происходит через дополнение LastModified

Исправлено

  • Редирект с UTM метками

[1.3.6-pl] - 2022-12-23

Исправлено

  • Редирект с UTM метками

[1.3.5-pl] - 2022-12-23

Добавлено

  • Поддержка переводчика DeepL
  • Опция включающая авто определения языка текста
  • Опция явно задающая язык переводимого текста
  • Сохранение UTM меток при переключении языка
  • На вкладке настройки языка поля: "локаль"; "иконка"
  • На вкладке настройки группы языков поле "иконка"
  • Last-Modified заголовок для модификаций

[1.3.4-pl] - 2022-11-18

Исправлено

  • Сниппет PolylangSitemap

[1.3.3-pl] - 2022-09-07

Исправлено

  • Загрузка всего списка шаблонов modx для SEO шаблонов
  • Загрузка всех языков при клонировании SEO шаблона
  • Отсутствие текста при групповом удалении лексиконов

[1.3.2-pl] - 2022-08-22

Добавлено

  • SEO Шаблоны
  • Опции: "polylang_seo_pattern_enabled" и "polylang_seo_placeholder_prefix"

[1.3.1-pl] - 2022-07-23

Добавлено

  • Автоопределение языка сайта по коду страны посетителя
  • Опции: "polylang_geo_detect_language" и "polylang_geo_language_country"

Последние обсуждения в сообществе MODX.pro