Fandom Developers Wiki
Advertisement

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) {
    // 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. Ще метод підтримує малі теги <i>, <b>, <em>, <strong> і <span>, а також атрибути title, style і class. Зверніть увагу: непідтримувані теги будуть вилучені разом з їх вмістом, заборонені атрибути і функція url('...') всередині атрибуту style також будуть вилучені. Підтримується такий вікі-текст:
    • [url text]
    • [[pagename]]
    • [[pagename|text]]
    • {{PLURAL:count|singular|plural}} (детально)
    • {{GENDER:gender|masculine|feminine|neutral}} (детально)
      • Зауважте, що нікнейми не працюють. Аргумент gender обов'язково повинен бути або male, або female, або щимось ще для нейтрального варіанту.

Кожен екземпляр Message містить одну властивість:

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 може здатися хитрим жартом, особливо якщо ви не розумієте синтаксис. Щоб полегшити завдання, скористайтеся редактором на сторінці Special:Blankpage/i18nedit.

Перевизначення повідомлень[]

Іноді кінцевий користувач може захотіти змінити набір повідомлень відповідно до своїх уподобань тільки для себе або навіть для цілого вікі-проєкта. Це можна зробити так:

// використовується у 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.
  • Глобальний Lua-модуль I18n.
Advertisement