Компонент multiLingual реализует функциональность мультиязычных сайтов без дополнительных контекстов, в отличие от компонента Babel.



«Из коробки» подходит для большинства небольших сайтов вроде «сайта-визитки» или несложного каталога.

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

Настройка компонента

Для работы компонента должны быть включены ЧПУ (friendly URLs)

Внимание, настройка Строгий режим дружественных URL (friendly_urls_strict) должна быть выключена (установлена в состояние «Нет»)

Компонент требует установки pdoTools версии не ниже 2.8.2

Перед тем, как начать работу с компонентом, необходимо установить настройку ml_default_site_url.
В нее необходимо записать URL сайта по-умолчанию. Например

https://mysite.ru/

Работа с мультиконтекстными сайтами

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

Например, у вас на одном modx работают два сайта:

http://mysite.com

и

https://mynewsite.ru.

В контексте первого сайта вы указываете в настройке ml_default_site_url значение

http://mysite.com/

В контексте второго —

https://mynewsite.ru/

Обратите внимание на слеш на конце.

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

Про выборку ресурсов и pdoTools

При работе со сниппетами пакета pdoTools для выборки ресурсов, такими как pdoResources и pdoMenu,
данные сниппеты ничего не знают о компоненте multiLingual, поэтому по-умолчанию, независимо от языковой версии,
они будут получать из БД поля ресурсов со значениями на языке по-умолчанию.

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

pdoFetch.class = mlFetch
pdofetch_class_path = {core_path}components/multilingual/model/multilingual/

При выборке ресурсов другими способами, подстановка переводов ложится на плечи разработчика.

Более подробное описание механизма см. ниже.

Настройка веб-сервера nginx

Для того, чтобы веб-сервер nginx корректно обрабатывал URL адреса и корректно отдавал статичные ресурсы,
в раздел server вашего сайта добавьте следующие строки:

• для любых адресов типа http://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

Если вы используете веб-сервер apache, необходимо внести изменения в файл .htaccess в корневой директории сайта.
Суть настроек аналогична настройкам nginx. Синтаксис инструкций см. в документации к веб-серверу apache2.

Пример:

...

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

# The Friendly URLs part
...

Принцип работы с компонентом

После установки вам необходимо сначала добавить дополнительные языковые версии сайта, после чего, перейдя в любой ресурс, на вкладку
«Переводы» добавить там переводы для соответствующих полей.

Интерфейс редактирования языковых версий

Синтаксис шаблона URL (site_url) при создании нового языка допускает несколько вариантов:

1. Указание только правой части url
   Например для английской версии мы можем указать
   /eng/
   В этом случае все адреса ресурсов в английской версии будут иметь вид mydomian.com/eng/resource/full/url.html
   
2. Указание точного соответствия url
   Например
   mydomain.com/
   При таком варианте вы жестко привязаны к адресу сайта. В этом случае разные языковые версии сайта могут находиться на разных доменах.
   Например русская на mydomainrussia.ru/, а английская на mydomainusa.com/
   
3. С помощью плейсхолдеров `[[+schema]]` и `[[+base_domain]]`
   Например
   [[+schema]]eng.[[+base_domain]]/
   [[+schema]]english.[[+base_domain]]/
   Данный вариант более удобен, если языковые версии строятся на поддоменах. Например mybasedomain.ru/ и eng.mybasedomain.ru/
   

Интерфейс для добавления переводов к полям ресурса (вкладка «Переводы»)

После установки компонента у каждого ресурса появляется дополнительная вкладка «Переводы».

На данной вкладке вы можете увидеть все поля, которые уже переведены на другие языки, а также добавить переводы
для непереведенных полей.

При нажатии на кнопку «Добавить перевод» или при клике правой кнопкой мыши по одному из
существующих переводов и выбора пункта «Обновить перевод» появится всплывающее окно, в котором
можно выбрать поле, для которого создается перевод, язык (из тех, которые ранее были добавлены в интерфейсе
управления языковыми версиями), а также указать, собственно, сам перевод.

Сниппеты

mlLanguagesLinks

Данный сниппет выводит элемент для переключения языков на фронтенде

—

Параметры:

&wrapperTpl — шаблон обертки
&tpl — основной шаблон
&mod — стилевой модификатор для проброса в каждую ссылку
&activeClass — активный класс
&scheme — схема формирования URL (аналогично параметру $scheme метода $modx->makeUrl)
&showActive — показывать ли ссылку текущего языка

—

Доступные плейсхолдеры внутри чанка wrapperTpl:

&output — содержимое

—

Доступные плейсхолдеры внутри чанка tpl:

&culture_key — ключ языка на ссылке
&link — ссылка
&site_url — базовый URL сайта
&classes — набор классов ссылки
&mod — стилевой модификатор, указанный в параметре mod

Принцип перевода сущностей, отличных от modResource и перевода выборок

Работа любых сниппетов, выводящих список каких-либо ресурсов (не обязательно modResource, но также и файлов галереи,
комментариев и т.д.), заключается в том, что сниппет, получает на вход набор параметров, формирует
запрос к базе данных, получает данные, проводит с ними какую-либо обработку и затем отдает дальше.

В сниппетах pdoTools предусмотрен механизм, позволяющий заменой системной настройки переопределить класс,
осуществляющий выборку каких-либо ресурсов.

pdoFetch.class = mlFetch
pdofetch_class_path = {core_path}components/multilingual/model/multilingual/

Для того, чтобы иметь возможность получать выборки с переводами ресурсов, отличных от класса modResource (и наследуемых от него),
вам необходимо написать свой класс, наследуемый от класса mlFetch, переопределив методы getArray и prepareRows, добавив
в них логику подготовки выборки перед отдачей дальше по аналогии с тем, как это сделано в классе mlFetch.

После этого, получая выборки при помощи сниппета pdoResources или при помощи другого, самописного сниппета, использующего
класс из настройки `pdoFetch.class` для этих целей, вы сможете получать выборки с переводами на текущий язык.