I18n-js is a library for loading a script's messages, stored as JSON, ready for said script to use. Not only does it allow messages to be split out of the main code containing all the logic, it handles language fallbacks as well.


I18n page

To use I18n-js, you will need to set up your messages in the appropriate place and in the correct format. The message loader will expect your messages to be in a page such as MediaWiki:Custom-PAGENAME/i18n.json here on Dev Wiki, where PAGENAME should be the name of your script. the format of your messages should be as follows:

    "en": {
        "name": "value"
    "pl": {
        "name": "value"

Importing the script

Once you're all set up, simply import MediaWiki:I18n-js/code.js into your script. There are a few ways to achieve this, but they generally fall into 1 of 2 categories:

1. Import the script using importArticles or other import function that provides no indication of when the script has finished loading. If you use this method, you can listen for the dev.i18n event using mw.hook:

// register the hook before the import to avoid race conditions
mw.hook('dev.i18n').add(function (i18n) {
    // i18n is a shortcut to
importArticle({ type: 'script', article: 'u:dev:I18n-js/code.js' });

2. Import the script using a function that provides a callback, such as $.getScript. If you're using this method, you use the callback and access within:

// TODO:

Loading your messages

Now the script is loaded you're ready to load your messages. This is achieved using the loadMessages method of which returns and instance of i18n. This will also cache said instance in case you attempt to load the messages again for any reason:

// name is the PAGENAME part of
i18n.loadMessages(name).done(function (i18n) {
    // use your i18n instance here

i18n usage

i18n controls access to your individual messages as well as the language it tries to translate them into. It defines the following 4 methods:

  • useLang(code): Set the default language to code, e.g. 'pt'. By default, the language will be the value of wgUserLanguage.
  • useContentLang(): Set the default language to the value of wgContentLanguage.
  • useUserLang(): Set the default language to the value of wgUserLanguage.
  • msg(message, arg1, arg2, arg3, ...): Create a Message instance representing the message in the closest language to the default language possible with any arguments substituted in. See #message usage for details on how to use this.

message usage

message represents a translated message in the closest language to the default language set in the i18n instance as possible. If a translation could not be found in the requested language, then it will try a fallback language instead, until it falls back to English. If the English translation could not be found, then it will contain the name of the message wrapped in < ... >, e.g. <MESSAGE>.

If your message uses arguments, these should be specified in the form $n where n is a integer greater than 0, e.g, 'Hello, $1, my name is $2'.

There are 3 methods available for outputting the message stored in the Message instance:

  • plain(): This outputs the message as is with no further processing.
  • parse(): This outputs the message with all basic wikitext links converted into HTML. This supports links in the formats:
    • [url text]
    • [[pagename]]
    • [[pagename|text]]
  • escape(): This outputs the message with any HTML characters escaped.

Editing your messages

JSON can be a bit tricky to edit, especially if you're unfamiliar with the syntax. To improve the editing experience, a dedicated editor can be found at Special:Blankpage/i18nedit.

Change log

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.