Описание

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

Возможности

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

Интеграция

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

Зависимости

• pdoTools

Видео-обзор

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

• Настройка “Использовать дружественные URL” (friendly_urls) должна быть включена (установлена в состояние “Да”)
• Настройка “Строгий режим дружественных URL” (friendly_urls_strict) должна быть выключена (установлена в состояние “Нет”)
• Настройка “Схема URL” (link_tag_scheme) должна быть либо abs, либо full
• Для того чтобы URL всех страниц был без слеша на конце, необходимо указать пустое значение в настройке “Суффикс контейнера” (container_suffix)
• Включение системной настройки “Автоопределение языка посетителя” (polylang_detect_visitor_language) позволяет при первом посещении сайта перебросить посетителя на языковую версию сайта, определенную на основании языка его системы.
• Системная настройка “Ключ языка посетителя по-умолчанию” (polylang_visitor_default_language) позволяет указать языковую версию сайта, на которую следует перебросить посетителя при первом визите, если для языка его системы нет языковой версии сайта.

Настройка веб-сервера 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 ссылки на разные языки разных доменов

Теги fastField

Теги fastField, т/е конструкции типа

[[#15.pagetitle]]
    {27 | resource : 'pagetitle'}

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

phpThumbOn

Для корректной работы следует использовать модификатор Polylang2BaseUrl.

Пример

[[+image:Polylang2BaseUrl:phpthumbon=`w=610&h=305&q=80&zc=1`]]

Сниппеты

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

PolylangCanonical — Сниппет выводит canonical ссылки.

Параметры:
tpl — Fenom чанк оформления работы сниппета.
languageGroup — Список ID языковых групп, через запятую. По умолчанию берется из системной настройки polylang_default_language_group или polylang_default_domain_settings

PolylangMsOptions — Обертка над сниппетом msOptions.

PolylangField — Обертка над сниппетом pdoField с возможностью вывести значения поля на нужном языке.

Параметры:
lang — Код языка.

Пример использования:

[[PolylangField?
    &id=`[[*id]]`
    &field=`longtitle`
    &lang=`en`
]]

Системные события

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_”

Перевод

Из “коробки” перевод можно осуществить с помощью API google translate или yandex translate. Для этого в системной настройке 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).

Для использования 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}