I18n-js/ru

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

Использование[]

Страница I18n[]

Чтобы использовать I18n-js, вы должны расположить свои сообщения в правильном месте и в правильном формате. Загрузчик сообщений будет искать ваши сообщения здесь, на Fandom Developers Wiki, на странице MediaWiki:Custom-<PAGENAME>/i18n.json, где <PAGENAME> — название вашего скрипта. Формат сообщений должен быть следующим:

{
    "en": {
        "name": "value"
    },
    "pl": {
        "name": "wartość"
    }
}

Однако редактирование JSON может быть сложным даже для профессионалов. Идеальный способ создать страницу /i18n.json — отправиться на Special:BlankPage/I18nEdit/<PAGENAME>/en и воспользоваться соответствующим редактором.

Импорт скрипта[]

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

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

// зарегистрируйте хук перед импортом, чтобы избежать "гонки скриптов"
mw.hook('dev.i18n').add(function (i18n) {
    // сокращение для window.dev.i18n
});

importArticle({ type: 'script', article: 'u:dev:MediaWiki:I18n-js/code.js' });

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

$.getScript('https://dev.fandom.com/load.php?mode=articles&articles=MediaWiki:I18n-js/code.js&only=scripts')
    .done(function() {
        // используйте window.dev.i18n здесь
    });

Загрузка сообщений[]

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

// name представляет PAGENAME в ссылке https://dev.wikia.com/wiki/Custom-PAGENAME/i18n.json
i18n.loadMessages(name).done(function (i18n) {
    // используйте ваш экземпляр i18n здесь
});

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

Также метод loadMessages в качестве второго аргумента принимает необязательный объект options, который может содержать следующие параметры:

cacheAll: представляет массив имен сообщений, чьи переводы на все языки должны быть кешированы (подробнее см. §Кеширование сообщений);
cacheVersion: минимальная требуемая скриптом версия кешированных сообщений (подробнее см. §Кеширование сообщений);
language: определяет язык, который будет приниматься скриптом за язык пользователя вне зависимости от значения переменной wgUserLanguage. Указанный язык станет языком по умолчанию, что повлияет на работу функций useUserLang() и inUserLang(). Если значение ключа отсутствует, будет использовано значение wgUserLanguage;
noCache: никогда не кешировать сообщения i18n (не рекомендуется для обычного использования).

Кеширование сообщений[]

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

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

По умолчанию кеш хранит перевод только для языка пользователя (wgUserLanguage) и содержимого вики (wgContentLanguage), чтобы занимать как можно меньше места. Если вашему скрипту необходимо использовать сообщения на других языках, вы можете воспользоваться параметром cacheAll, заполняя его массивом названий нужных сообщений. Также можно указать true, чтобы записать в кеш переводы на все языки, но пользоваться этим на постоянной основе не рекомендуется.

Использование i18n[]

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

useContentLang(): делает стандартным тот язык, чей код содержит переменная wgContentLanguage;
useUserLang(): делает стандартным тот язык, чей код содержит переменная wgUserLanguage (если в параметре options функции loadMessages() не указано иное);
inContentLang(): для следующего сообщения использует язык, указанный в переменной wgContentLanguage;
inUserLang(): для следующего сообщения использует язык, указанный в переменной wgUserLanguage;
inLang(code): для следующего сообщения использует язык с кодом code. Работает только при указании параметра cacheAll (подробнее см. §Кеширование сообщений);
msg(message, arg1, arg2, arg3, ...): создает экземпляр Message, представляющий собой сообщение на языке, самом близком к стандартному, с использованием дополнительных параметров (подробнее см. §Использование сообщений).

Использование сообщений[]

Message представляет переведенное сообщение на тот язык, который ближе всего к установленному в i18n. Если перевод не может быть найден, используется резервный язык. Если перевода нет и на этом языке, используется английский. А если и английского нет, скрипт возвращает название сообщения, обернутое в треугольные скобки, — <i18njs-Script-message>, где Script — название скрипта, а message — имя сообщения.

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

Для работы с экземпляром Message существуют три метода:

plain(): возвращает сообщение без дальнейшей обработки.
escape(): возвращает сообщение с использованием escape-символов для любых HTML-сущностей.
parse(): возвращает сообщение с любым викитекстом и некоторыми локализованными волшебными словами, конвертированными в HTML. Еще метод поддерживает строчные теги , , ,  и , а также атрибуты title, style и class. Обратите внимание: неподдерживаемые теги будут удалены вместе с их содержимым, запрещенные атрибуты и функция url('...') внутри атрибута style также будут удалены. Поддерживается следующий викитекст:

- [url text]
- [[pagename]]
- [[pagename|text]]
- {{PLURAL:count|singular|plural}} (подробнее)
- {{GENDER:gender|masculine|feminine|neutral}} (подробнее)
  - Заметьте, что никнеймы не работают. Аргумент gender обязательно должен быть либо male, либо female, либо чем-то еще для нейтрального варианта.

Каждый экземпляр Message содержит одно свойство:

exists: exists: равняется true, если для сообщения существует перевод, false в противном случае.

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

// начнем с языка пользователя (пусть это будет английский)
i18n.msg('hello-world').plain(); // Hello World!

// вывод одного сообщения на французском
i18n.inContentLang().msg('hello-world').plain(); // Bonjour le monde !

// и снова английский
i18n.msg('hello-world').plain(); // Hello World!

Изменение сообщений[]

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

Переопределение сообщений[]

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

// используется в JS-файле участника или вики

// инициализация глобальных объектов, используемых без исправлений
window.dev = window.dev || {};
window.dev.i18n = window.dev.i18n || {};
window.dev.i18n.overrides = window.dev.i18n.overrides || {};
window.dev.i18n.overrides['EXAMPLE'] = window.dev.i18n.overrides['EXAMPLE'] || {};

// изменение требуемых сообщений
window.dev.i18n.overrides['EXAMPLE']['some-message'] = 'My customised message';
window.dev.i18n.overrides['EXAMPLE']['another-message'] = 'Another customised message';

EXAMPLE — название, подсказывающее загрузчику, какие сообщения искать. Например, если использовать I18nEdit, то загрузчик получит сообщения со страницы u:dev:MediaWiki:Custom-I18nEdit/i18n.json. Таким образом, для изменения сообщений скрипта I18nEdit можно воспользоваться этим кодом:

window.dev = window.dev || {};
window.dev.i18n = window.dev.i18n || {};
window.dev.i18n.overrides = window.dev.i18n.overrides || {};
window.dev.i18n.overrides['I18nEdit'] = window.dev.i18n.overrides['I18nEdit'] || {};

window.dev.i18n.overrides['I18nEdit']['title'] = 'My new title';

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

Зависимые скрипты[]

Список скриптов, использующих эту библиотеку

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

(устарел; для просмотра полного списка изменений обращайтесь к истории страницы)

Date	Description
07 December 2018	Added support for the `GENDER` magic word when parsing messages.
19 September 2018	Added message caching functionality.
28 August 2018	Removed support for inline comments in JSON pages.
16 August 2018	Fixed an XSS issue when parsing messages. Added an `exists` property to `Message` instances. Added support for the `PLURAL` magic word when parsing messages. Added support for the `qqx` language code to show keys of used messages.
21 June 2018	Added support for temporary language changes on a per message basis.
01 June 2018	Added support for some inline tags and attributes when using `Message.parse()`.
29 May 2018	Added message override support.
21 February 2017	Prevent the script loading multiples times and causing the cache to be lost.
16 February 2017	Switched to factory method instead of constructors. Fixed argument handling to start at $1 instead of $0. Fixed link parsing for absolute URLs.
15 February 2017	Improved fallback behaviour to mirror that of MediaWiki. Added argument handling. Added basic parsing functionality.
13 February 2017	Initial release.

См. также[]

Руководство по i18n.
I18n Lua module