I18n-js/ru

I18n-js — библиотека для загрузки сообщений скрипта, хранящихся в формате JSON и готовых к использованию в данном скрипте. Помимо отделения сообщений от кода с полным сохранением их логики библиотека поддерживает резервные языки и базовый анализ сообщений.

Страница I18n
Чтобы использовать I18n-js, вы должны расположить свои сообщения в правильном месте и в правильном формате. Загрузчик сообщений будет искать ваши сообщения здесь, на Dev Wiki, на странице, где   — название вашего скрипта. Формат сообщений должен быть следующим:

Однако редактирование JSON может быть сложным даже для профессионалов. Идеальный способ создать страницу  — отправиться на   и воспользоваться соответствующим редактором.

Импорт скрипта
Когда вы все настроите, просто импортируйте MediaWiki:I18n-js/code.js в свой скрипт. Для этого есть несколько способов, но обычно они сводятся к этим двум:

1. Импортируйте скрипт с помощью importArticles или других подобных функций, у которых нет индикации завершения загрузки скрипта. Если вы следуете по этому пути, вы можете перехватить событие  с помощью  :

2. Импортируйте скрипт с помощью функций, предоставляющих функцию обратного вызова, например. Если вы используете этот способ, просто установите функцию обратного вызова для доступа к :

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

Также метод  в качесте второго аргумента принимает необязательный объект , который может содержать следующие параметры:
 * : минимальная требуемая скриптом версия кешированных сообщений. Смотрите §Кеширование сообщений для подробностей.
 * : никогда не кешировать сообщения i18n (не рекомендуется для обычного использования).

Кеширование сообщений
Загруженные сообщения будут сохранены в браузерном хранилище на срок до двух дней с момента загрузки для улучшения отклика страницы при будущих обращениях к ней (и скрипту не надо будет каждый раз дожидаться окончания загрузки сообщений). Однако это означает, что ваш скрипт может использовать сообщения двухдневной давности. Кешированные сообщения также имеют номер версии, который по умолчанию равен  (нулю).

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

Использование i18n
получает доступ к вашим сообщениям и языку, на который он будет пытаться их перевести. Определено семь следующих методов:
 * : устанавливает стандартным языком язык с кодом, например  . По умолчанию используется значение переменной.
 * : делает стандартным тот язык, чей код содержит переменная.
 * : делает стандартным тот язык, чей код содержит переменная.
 * : использует язык с кодом  только для следующего сообщения.
 * : использует язык, указанный в переменной, только для следующего сообщения.
 * : использует язык, указанный в переменной, только для следующего сообщения.
 * : создает экземпляр, представляющий собой сообщение на языке, самом близком к стандартному, с использованием дополнительных параметров. Подробнее смотрите раздел §Использование сообщений.

Использование сообщений
представляет переведенное сообщение на тот язык, который ближе всего к установленному в. Если перевод не может быть найден, используется резервный язык. Если перевода нет и на этом языке, используется английский. А если и английского нет, скрипт возвращает название сообщения, обернутое в треугольные скобки, —.

Если ваше сообщение использует аргументы, они могут быть вызваны с помощью конструкции, где   — целое число больше нуля. Пример:.

Для работы с экземпляром  существуют три метода:
 * : возвращает сообщение без дальнейшей обработки.
 * : возвращает сообщение с использованием escape-символов для любых HTML-символов.
 * : возвращает сообщение с любым викитекстом и некоторыми локализованными волшебными словами, конвертированными в HTML. Еще метод поддерживает строчные теги,  ,  ,   и  , а также атрибуты  ,   и  . Обратите внимание: неподдерживаемые теги будут удалены вместе с их содержимым, запрещенные атрибуты и функция   внутри атрибута   также будут удалены. Поддерживается следующий викитекст:
 * (more info)
 * (more info)
 * Заметьте, что никнеймы не работают. Аргумент "gender" обязательно должен быть либо "male", либо "female", либо чем-то кроме для нейтрального варианта.
 * (more info)
 * (more info)
 * Заметьте, что никнеймы не работают. Аргумент "gender" обязательно должен быть либо "male", либо "female", либо чем-то кроме для нейтрального варианта.

Каждый экземпляр  содержит одно свойство:
 * : равняется, если для сообщения существует перевод,   в противном случае.

Если используются методы,   или  , можно устроить вызов функций по цепочке:

Изменение сообщений
Во время редактирования JSON может показаться хитрой штукой, особенно если вы не понимаете синтаксис. Чтобы облегчить задачу, воспользуйтесь редактором на странице Special:Blankpage/i18nedit.

Переписывание сообщений
Иногда конечный пользователь может захотеть изменить набор сообщений в соответствии со своими предпочтениями только для себя или даже для целого проекта. Это можно сделать так:

— название, подсказывающее загрузчику, какие сообщения искать. Например, если использовать, то загрузчик получит сообщения со страницы. Таким образом, для изменения сообщений скрипта  можно воспользоваться этим кодом:

Чтобы найти имя сообщения, воспользуйтесь трюком с языком QQX. Сообщения, использующие I18n-js, будут выглядеть как, где   — название скрипта, а   — название сообщения. Например, сообщение, использующееся в скрипте I18nEdit, будет показано как.

Список изменений

 * 7 декабря 2018
 * Добавлена поддержка волшебного слова  для анализатора сообщений.


 * 19 сентября 2018
 * Добавлен функционал кешированных сообщений.


 * 28 августа 2018
 * Удалена поддержка комментариев на страницах JSON.


 * 16 августа 2018
 * Исправлена ошибка XSS во время анализа сообщений.
 * Добавлено свойство  для экземпляра.
 * Добавлена поддержка волшебного слова  для анализатора сообщений.
 * Добавлена поддержка языкового кода  для просмотра названий используемых сообщений.


 * 21 июня 2018
 * Добавлена поддержка временного изменения языка для одного сообщения.


 * 1 июня 2018
 * Добавлена поддержка некоторых внутристрочных тегов и атрибутов при использовании.


 * 29 мая 2018
 * Добавлена возможность переписи сообщений.


 * 21 февраля 2017
 * Предотвращена многоразовая загрузка скрипта, вызывающая потерю кеша.


 * 16 февраля 2017
 * Вместо конструкторов теперь используется фабричный метод.
 * Исправлена нумерация аргументов: теперь они начинаются с.
 * Исправлен анализ ссылок с абсолютными URL.


 * 15 февраля 2017
 * Улучшено поведение скрипта при задействовании резервных языков.
 * Добавлена возможность использовать аргументы.
 * Добавлена базовая функциональность анализатора.


 * 13 февраля 2017
 * Начальная версия.

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

 * Руководство по i18n.
 * Глобальный Lua-модуль I18n.