Интернационализация

Общее представление¶

Интернационализация, или i18n, - это процесс экстраполяции текстовых строк в документе на отдельные языки, так что документ может просматриваться на множестве разных языков без необходимости дублирования страницы для каждого другого языка. С технической точки зрения, интернационализация относится к процессу подготовки кода для его перевода; в MODX этот процесс часто сводится к изоляции переводимых строк в отдельные заполнители (плейсхолдеры).

i18n Аббревиатура i18n происходит от слова «internationalization» («интернационализация»). Это означает «i плюс 18 букв, затем n».

MODX Revolution поддерживает i18n на уровне ядра через то, что называется «Лексиконами». Лексикон - это просто коллекция следующих данных:

• Языки (формат IANA)
• Темы
• Записи

Тема лексикона - это коллекция статей лексикона. Запись лексикона - это одна языковая строка с ключом и значением. Revolution разделяет записи на разделы, чтобы ускорить загрузку языковых файлов, сократить время загрузки языкового кэша JS и облегчить обслуживание.

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

Локали¶

Некоторые фреймворки для перевода (такие как gettext) полагаются на определенный языковой стандарт и контекст, чтобы помочь различать значения. Например, «футбол» («football») имеет различное значение в зависимости от локали (Великобритания или США). MODX, скорее всего, не будет поддерживать локали в ядре, но вы можете настроить локали как вам нужно, исходя из организации вашего сайта и подхода i18n. Наиболее логичным, вероятно, будет использовать плагин, связанный с событием OnInitCulture.

Вы можете установить локаль в системных настройках MODX (или в контекстных настройках, если вы используете, например, Babel). Но убедитесь, что языковой стандарт системы MODX использует кодировку utf8 (т.е. de_DE.utf8), в противном случае серверная часть MODX покажет некоторые ошибки.

Записи лексиконов¶

Запись лексикона (или modLexiconEntry в модели MODX) - это просто один перевод строки на другой язык. Здесь есть несколько важных полей, которые мы отметим:

• name - это имя или «ключ» записи. При использовании лексиконов вы будете ссылаться на этот ключ.
• value - перевод ключа.
• topic - тема, к которой принадлежит эта запись.
• language - ключ языка в формате IANA, на который эта запись переведена.

Загрузка и использование лексиконов¶

Лексиконы должны быть сначала загружены, если они будут использоваться во внешнем интерфейсе. Тем не менее, это тривиальный процесс.

Лексиконы через тег (в содержании, чанках, шаблонах и т.д.)¶

Чтобы использовать запись лексикона в теге, используйте следующий синтаксис:

[[%key? &topic=`topicname` &namespace=`namespace_name` &language=`en`]]

Свойства language, topic и namespace являются необязательными; если тег был ранее запущен на странице с тем же значением свойства 'topic', эта тема уже будет загружена. Если тема не указана, она будет принимать значение по умолчанию. Если 'namespace' не указано, оно будет принимать 'core' или пространство имен MODX Revolution Core.

Желательно не использовать свойство 'language' для каждого тега, если вы меняете языки; это лучше всего сделать через cистемную или контекстную настройку для всего сайта или контекста. Лучший вариант - это разные контексты для каждого языка. Но опять же, MODX оставляет вам выбор.

Если в строке лексикона есть плейсхолдеры, например «Это [[+userinput]]!», Вы просто указываете ключ («userinput») в качестве свойства тега и передаете в значение то, что вы хотите заменить. Пример:

[[!%key? &topic=`topicname` &namespace=`namespace_name` &language=`en` &userinput=`amazing`]]

Обратите внимание на на восклицательный знак, т.е. префикс для тега это гарантирует, что тег не будет кэширован, поскольку наша строка может измениться до того, как страница будет закеширована.

Лексиконы в PHP¶

Использование лексиконов в коде довольно просто; прежде всего, вы должны убедиться, что класс modLexicon загружен, создав его экземпляр как сервис:

$modx->getService('lexicon','modLexicon');

Затем мы хотим загрузить тему с помощью метода load().

Загрузка тем лексикона с помощью modLexicon::load()¶

Синтаксис метода modLexicon::load довольно прост:

$modx->lexicon->load('topicname');

Функция load() поддерживает загрузку пространства имен. Итак, допустим, что у вас была тема лексикона с именем «default» в пространстве имен «school». Вы бы загрузили его так:

$modx->lexicon->load('school:default');

Это загрузит тему «по умолчанию» в пространство имен «school». Если пространство имен не указано, по умолчанию используется значение «core», которое является пространством имен по умолчанию для серверной части MODX Revolution.

Функция load() также принимает бесконечное количество параметров; каждый параметр загружает отдельную тему. Пример:

$modx->lexicon->load('chunk','user','school:playground');

Этот код загрузит 3 темы: «chunk», «user» и тему «playground» из пространства имен «school».

Кроме того, параметр load поддерживает загрузку для конкретного языка, если вы хотите переопределить загружаемый язык по умолчанию (по умолчанию используется текущее значение $this->modx->cultureKey, которое устанавливается по-разному в зависимости от загруженного контекста, и может быть установлен через настройки), вы можете загрузить его так:

$modx->lexicon->load('es:school:playground');

Это приведет к загрузке испанской версии темы «playground» для пространства имен «school». Здорово, да?

Отображение переведенного контента с помощью modX::lexicon()¶

Теперь мы можем использовать метод lexicon() объекта MODX, чтобы получить нашу запись с ключом 'school.basketball':

$modx->lexicon('school.basketball');

Если в строке лексикона есть плейсхолдеры, например «Это [[+userinput]]!», вы можете передать массив в качестве второго аргумента, в котором есть пары key=>value содержимого плейсхолдера, например, так:

$modx->lexicon('school.basketball',array('sport' => 'basketball'));

Лексиконы в JavaScript (внутри MODX)¶

В CMP вы можете использовать следующее для использования лексиконов

 _('lexicon.key')

Обратите внимание, что это предполагает, что вы загрузили лексикон в свой коннектор - нет (по крайней мере, насколько мне известно в настоящее время ~Mark H.) способа динамически загружать другие темы лексикона через JavaScript.

Если в строке лексикона есть плейсхолдеры, например «Это [[+userinput]]!», Вы можете передать значения плейсхолдера в виде объекта JavaScript, например:

 _('lexicon.key',{ userinput: 'amazing' })

Лексиконы для настроек¶

Допустим, вы создаете системные настройки для стороннего компонента. Синтаксис для автоматической загрузки их в сетку настроек Revolution прост. Допустим, у нас есть пространство имен для нашего компонента под названием «gallery» и параметр под названием «gallery.display_thumbs»

Рекомендуемый формат Рекомендуемый формат для разработчиков сторонних компонентов - использовать префикс, который идентифицирует родительский компонент: $*lang['name-of-component*.key-name'] = 'Ваш перевод здесь.';

Это помогает предотвратить конфликты имен; имейте в виду, что массив $_lang может содержать тысячи записей, поэтому вы должны убедиться, что каждая запись уникальна.

Чтобы добавить название и описание лексикона, мы просто добавили бы следующие 2 строки в нашу тему лексикона по умолчанию для нашего пространства имен «gallery»:

$_lang['setting_gallery.display_thumbs'] = 'Отображать миниатюры';
$_lang['setting_gallery.display_thumbs_desc'] = 'При значении true будут отображаться эскизы для галереи.';

И вот мы закончили!

Заключение¶

Лексиконы предоставляют пользователям MODX Revolution множество путей и возможностей для работы i18n. Лексиконы состоят из нескольких записей для каждого языка и сгруппированы по темам. Они могут быть вызваны методами PHP или тегами MODX.

Смотрите также¶

• modX.lexicon