Message usage:
← Older revision
Revision as of 22:52, February 15, 2017
(One intermediate revision by one user not shown)
Line 12:
Line 12:
== Usage ==
== Usage ==
+
=== 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 <code>MediaWiki:Custom-PAGENAME/i18n.json</code> here on Dev Wiki, where PAGENAME should be the name of your script. the format of your messages should be as follows:
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 <code>MediaWiki:Custom-PAGENAME/i18n.json</code> here on Dev Wiki, where PAGENAME should be the name of your script. the format of your messages should be as follows:
Line 25:
Line 26:
</syntaxhighlight>
</syntaxhighlight>
−
Once
you're all set up, simply import [[MediaWiki:I18n/code.js]] into your script. Then pass
the
name of your
script
to <code>window.dev.i18n.loadMessages</code> which will return a promise:
+
===
Importing
the script
===
+
Once you're all set up, simply import [[MediaWiki:I18n/code.js]] into your script. There are a few ways to achieve this, but they generally fall into 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 <code>dev.i18n</code> event using <code>mw.hook</code>:
<syntaxhighlight lang="javascript">
<syntaxhighlight lang="javascript">
−
window.dev.i18n.loadMessages
('
PAGENAME
')
+
importArticle
(
{ type:
'
script', article: 'u:dev:I18n/code.js
'
}
)
−
.
done
(function (
messages
) {
+
mw.hook('dev.i18n')
.
add
(function (
i18n
) {
−
// use your
messages
here!
+
//
i18n
is
a
shortcut
to
window.dev.i18n
−
console.log(messages
)
;
+
}
)
−
});
</syntaxhighlight>
</syntaxhighlight>
−
Once
you
have
your
messages
,
you
can
get
the
best
available
translation
for
the
user
of
your
script
using
<code>window.dev.i18n
.msg
</code>:
+
2.
Import
the
script
using a function that provides a callback
,
such
as
<code>$.getScript</code>.
If
you're
using
this
method,
you
use
the
callback
and
access
<code>window.dev.i18n</code>
within
:
+
<syntaxhighlight lang="javascript">
+
// TODO:
+
</syntaxhighlight>
+
=== Loading your messages ===
+
Now the script is loaded you're ready to load your messages. This is achieved using the <code>loadMessages</code> method of <code>window.dev.i18n</code> which returns and instance of <code>I18n</code>. This will also cache said instance in case you attempt to load the messages again for any reason:
<syntaxhighlight lang="javascript">
<syntaxhighlight lang="javascript">
−
window.
dev.i18n.
msg('MESSAGE');
+
// name is the PAGENAME part of http://
dev.
wikia.com/wiki/Custom-PAGENAME/
i18n.
json
+
i18n.loadMessages(name).done(function (i18n) {
+
// use your I18n instance here
+
});
</syntaxhighlight>
</syntaxhighlight>
−
If
no
translation
of your message can be found, which will usually be a spelling error, the output will be <code><MESSAGE></code>
+
===
I18n
usage
===
+
<code>I18n</code> controls access to your individual messages as well as the language it tries to translate them into. It defines the following 4 methods:
+
* <code>useLang(code)</code>: Set the default language to <code>code</code>, e.g. <code>'pt'</code>. By default, the language will be the value of <code>wgUserLanguage</code>
+
* <code>useContentLanguage()</code>: Set the default language to the value of <code>wgContentLanguage</code>.
+
* <code>useUserLanguage()</code>: Set the default language to the value of <code>wgUserLanguage</code>.
+
* <code>msg(message, arg1, arg2, arg3, ...)</code>: Create a <code>Message</code> 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 ===
+
<code>Message</code> represents a translated message in the closest language to the default language set in the <code>I18n</code> 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 <code>< ... ></code>, e.g. <code><MESSAGE></code>.
+
+
If your message uses arguments, these should be specified in the form <code>$n</code> where n is a integer greater than 0, e.g, <code>'Hello, $1, my name is $2'</code>
+
+
There are 3 methods available for outputting the message stored in the <code>Message</code> instance:
+
* <code>plain()</code>: This outputs the message as is with no further processing.
+
* <code>parse()</code>: This outputs the message with all basic wikitext links converted into HTML. This supports links in the formats:
+
** <code><nowiki>[url text]</nowiki></code>
+
** <code><nowiki>[[pagename]]</nowiki></code>
+
** <code><nowiki>[[pagename|text]]</nowiki></code>
+
* <code>escape()</code>: This outputs the message with any HTML characters escaped.
== Releases ==
== Releases ==