Help:Extension:Translate/Unstructured element translation

This page explains how to make translating of customised wiki interfaces messages a bit more manageable with Translate extension. It applies to any part of the wiki which you want to automatically provide in the user's interface language. The most typical example is the sidebar, because you can have only one, but the same method can be used for the main page if you want to have all translations of it under the same title, or even templates.

This method is applicable also to wiki content where full page translation just doesn't fit, like pages heavy in markup or templates, whose markup you don't want to expose to translators. This all revolves around interface messages, or the magic word, that allows you to include interface messages anywhere where you can write wikitext. This magic word allows to automatically substitute the interface message, whether standard, customised or new, in the user interface language.

You can use it to bring to the wiki's content the power of the automatic localisation of the wiki's interface, but doesn't solve the problem for anonymous users, who cannot change the interface language by default. See the note about language selector extension below.

Compared to page translation, this method some drawbacks:
 * 1) MediaWiki developers usually discourage the usage of  because it fragments the cache. Instead of storing one cached rendered version of a page, when  is used it needs to be cached potentially in hundreds of different languages.
 * 2) Currently it is harder to setup, requiring access to wiki configuration.
 * 3) Currently there is no automatic tracking of outdated translations and completion statistics might be off when new messages are added or deleted.
 * 4) Currently only wiki administrators can add messages to the message groups and translate them. This means that the system is suitable only for pages which don't change often, or administrators will have a lot of work.

The good thing is that it works most of the time and you can still get the job done. We have made two tutorials for you to give examples of the common use cases. Before that there is section which details how to set up a message group, something which is always needed when using this method.

Setup
Server administrator is required to complete this step. The following snippet needs to be added to the wiki configuration:

The message group id, wiki-sidebar, must be unique, so don't reuse the same id for multiple groups. The second parameter to WikiMessageGroup constructor, sidebar-messages refers to Mediawiki:sidebar-messages page. Label is shown in dropdowns and other places where you can select message group. Description is shown in [[Special:Translate]]. Those are the values you can and should change to suitable values when adding a new message group.

Localised sidebar tutorial
We assume that the setup step has already been done. Then you should follow carefully the sidebar customisation guide. Let's assume that we have defined a stupid sidebar like this:
 * sidebar-commonpages
 * FAQ|sidebar-faq

And MediaWiki:sidebar-commonpages contains Common pages, and MediaWiki:sidebar-faq contains Frequently asked questions.

Then all we need to do is to go to MediaWiki:sidebar-messages (or whatever was defined in the previous step) and write there: sidebar-commonpages sidebar-faq

That is, the names of the messages, without the "MediaWiki:" namespaces prefix, separated by whitespace.

Then we can go to Special:Translate/wiki-sidebar (or whatever was defined in the previous step; see Special:Translate for list of defined groups). And we should be able to translate the messages into other languages. Since all the messages are in MediaWiki-namespace, only wiki administrator can edit the list of messages and actually translate them.

Localised main page tutorial
Another use case is page with lots of markup or templates. See the main page of [//translatewiki.net translatewiki.net] for example. The good thing with this method is that the language automatically appears in the user's interface language. The bad thing is that to change language, one must go to the preferences and change the interface language.

The idea is the same as in the previous tutorial:
 * 1) Setup a new message group
 * 2) Take a wiki page
 * 3) Replace each translatable part with  and move the content to MediaWiki:mainpage-messagename
 * 4) Go to MediaWiki:mainpage-messages (or whatever was defined in the setup) and add the message names there separated by whitespace
 * 5) You are done, go to Special:Translate and translate the front page.

Here is an example. Let's say the Main Page contains:  is a community for chefs and bakers that love chocolate. We currently have full of chocolate.

Then you change it to: 

And create MediaWiki:mainpage-slogan with the content: is a community for chefs and bakers that love chocolate.

And create MediaWiki:mainpage-pagecount with the content: We currently have full of chocolate.

And create MediaWiki:mainpage-messages with the content: mainpage-slogan mainpage-pagecount

And you are done! You can add and remove new messages anytime you want.

Language selector
Not only the user can't choose what localised version of the page to read unless changing their preferences, but anonymous users can't set their user interface language and always use the wiki's default language. A page translated with this system will be in the default content language, if you don't provide anonymous users a way to select their language.

Luckily, there is a solution. With the Extension:LanguageSelector it is possible to guess the user's preferred language and also to let the user manually select another language and store the choice in a cookie, with no need of tricks such as the uselang parameter, which is suitable mostly only for debugging.