User:Nike/iged

Draft!!! Unfinished, please improve

Internationalisation guide for extension developers

Introduction
This is a guide directed for people writing extensions for MediaWiki and may be useful for MediaWiki developers too. Internationalisation (later i18n because the writer is lazy) is an integral part of developing high quality extensions. Using the so called best practises benefits everyone. Translations are happy and efficient when strings are easy to translate and stable. I18n coordinators are happy when the extensions follows common structure and integrating it to the translation system is almost instant. The developers itself gets a good feeling when translation begin to flow to his extensions in great amounts.

Starting up
Nowadays every extensions needs the basic i18n support, because every extensions ought to have translatable description message for Special:Version (Code listing 1).

Code listing 1: example extension first line: GoodExtension.php

Here we can already see first bits of i18n best practises.

BP1: Extension should have a translatable description message, usually prefix-desc.

BP2: All messages should use common prefix derived from the extension name, all in lower case. (few exceptions later)

BP1 is quite self-explanatory, as is BP2. Using a prefix is an important thing for two reasons: it avoids message name collisions, and it allows implementing efficient message autoloader in the future.

So now we have two messages already. We are developing a special page, and that page needs a name of course. By default it is the name of the special page, all in lower case. It is usually also same as the prefix, in case of extension having only single special page.

I18n file
MediaWiki relies a lot on autoloading and lazy initialization. Now let's go ahead and create a i18n file and register it.

Code listing 2: example i18n file: GoodExtension.i18n.php

Code listing 3: registering the i18n file and the special page

So now we have created a i18n file named GoodExension.i18n.php and added a Special page class SpecialGoodExtension for autoloading.

BP3: Message file should be named ExtensionName.i18n.php

BP4: Message file should contain a header, line $messages = array and English definitions as shown in code listing 2.

Simple Special Page
Now that we have basic things set up, let's create a simple special page.


 * Code listing 4: start of simple special page: SpecialGoodExtension.php


 * Code listing 5: new message to GoodExtension.i18n.php

Now we should have a working special page. Include it in MediaWiki by putting following code to LocalSettings.php:

The relevant thing in this section is outputting text. We used an instance of OutputPage, which is a global variable $wgOut. If you just want to add simple wikitext message to output, OutputPage::addWikiMsg. It will handle parsing the message and all the i18n features happen behind the scenes. It is the preferred choice for multi sentence messages.

BP5: Use OutputPage::addWikiMsg</tt> for outputting explanatory messages that use wikitext.

Message variables
It is usually necessary to use variables in messages. MediaWiki allows using up to nine independent variables from $1</tt> to $9</tt> in a message. The most common thing to use a variable for is a number. In most languages numbers inflect in number, for example one car, but 2 cars. In MediaWiki you can (and should!) use one message for these kind of messages.

Let's go ahead and modify our introductory message to use a number as a variable.

Try it out few times and make sure it says 1 visitor but 2 visitors. The important thing is to always use NaN plurals. Even if the number cannot be smaller than two! Don't let English make you think you don't need plural in some special cases. It is safe and thus suggested to use plural handling in all messages having whole numbers, even if in English doesn't use more than one form. In some languages there can be as many as 6 different forms, where for example numbers 2 and 8 can get a different form. For floating point numbers on the other hand, plural handling should not be used.

BP6: Always use plural handling if there is changing whole number.

Number formatting
BP7: Always format numbers that user sees in normal use with Language::formatNum</tt>.

You probably noticed that we used a new global variable in last example: $wgLang</tt>. It represents a language object for the users interface language. There is also another language object $wgContLang</tt>, which represents the wikis content language. You need to use it in some special cases.

Take a minute to look at the some functions provided by Language class. There is many formatting methods from dates to file sizes. Using these functions when applicable ensures you are producing output in correct, i18ned format.

Whenever you output a number that user sees in normal use, you should format it with Language::formatNum</tt>. It can take whole numbers as well as integers. If you change the rand</tt> function above to produce value in thousand, you should see how the numbers are appropriately formatted for your language. It is important to format small numbers also, because some languages don't use arabic numerals (1…9), but a different kind of numbers. You would not like guessing which number is ১০২,২৭২, would you?(you are missing a font if you don't see number-like symbols here).

If you are critical reader, you might have noticed that we are passing a formatted number to NaN undefineds. That is totally fine, because it can normalise the number we just formatted for logic calculations. If you want to look what kind of plural codes there is around, browse the language files in languages/classes</tt>.