Help:Extension:Translate

Here will be dragons and the translate extension user manual

Target audiences:
 * 1) translators
 * 2) translation admins (basic features and page translation)
 * 3) translation admins (advanced)
 * 4) developers

Draft

Translate extension enhances any MediaWiki wiki with essential features needed to do translation work inside a wiki. It can be used to translate the contents of the wiki, the interface of the wiki and even other software products, as it is used at translatewiki.net. Translate extension comes with an easy to use translation interface and allows to separate the content structure from the content language to be translated, showing only the latter to translators by splitting into manageable sections. Each section is automatically tracked for any changes and translators immediately see what needs updating on the single page or throughout the wiki.

Translate extension is used to translate the user interface of MediaWiki and other software projects at translatewiki.net, where it is used by hundreds of translators every month. At userbase.kde.org it is used to translate almost a thousand content pages. It is easy to start using Translate extension but at the same time it also scales up and provides advanced reporting, reviewing and workflow features.

Features
[Screnshot of the message listing] [Screnshot of the translation dialog]

Interface: The main feature of Translate extension is the simple yet functional translation interface. Besides the essential information like message definition and documentation, you can also request to see translations into other languages. If the definition has changed, you will see a difference listing of the changes. The extension comes with some built-in checks, that can check for common mistakes like unbalanced brackets and unused variables. Depending on the configuration there is also suggestions from translation memory and machine translation services like those of Google, Microsoft and Apertium.

The usability of the translation dialog is heavily enhanced with JavaScript and AJAX, but editing the messages in normal page edit view is also supported. All the same translation aids are provided in that view too. And it's not restricted to these interfaces! You can also export messages for translation in other off-line and on-line tools that accept Gettext po format. There is also Web API that can be used to build custom interfaces.

Message groups and tasks: Many of the features build around two basic concepts: message groups and tasks.

Message groups represent a collection of messages. One content page would be a one message group, where each paragraph of the page would be one message in that group. Or messages used in one Extension form a message group – few of the largest extensions have even multiple groups. You can also make group of groups, like All newsletters or All Translate extension messages. Many of the statistics and the tasks work on message group basis.

The tasks or in other words different listing of messages in a message group facilitate different use cases. Normally the translator gets a list of all untranslated messages in a chosen message group, but there also tasks where you can review messages or just get list of all of them.

[Screenshot of language stats]

Reporting and statistics: The extension has extensive reporting features ranging from view of untranslated messages across all message groups in a given language to list of translators per language with their activity level.

Content translation: If you have ever tried to translate content in MediaWiki without any tools, you know it does not scale. The translated versions get out of date, maybe while being only half-translated. Translations are discouraged when they can't work on small manageable pieces. Translators don't find what to work or what needs updating. The users get confused or outdated information.

This is all solved with Translate extension and its page translation feature. It adds a little bit of overhead to the pages you want to have translated, but this is a once-only task and the benefits far outweigh it. Essentially you need to mark the parts of the page you want to translate. The extension then splits them into paragraphs sized sections and creates a message group for it. After that translators can use all the features described above and after. In addition you can easily add language bar with tag or have links automatically go to user's preferred language version if exists using links of the form Special:MyLanguage/Pagename.

For more information see our how to setup content page for translation tutorial and in-depth documentation of the page translation feature.

Developers: Developers are delighted that the Extension comes with built-in support for many common translation file formats, like Java properties and Gettext po files. It also has extensive set of tool both in wiki and on command line to efficiently import and export translations.

Use cases
You can translate almost anything with Translate extension. Naturally there are specialized tools for translation certain kind of texts like video subtitles that are better done with those tools, but in general Translate preforms very well with any kind of texts that can be split into messages with length of one word up to one large of few small paragraphs. Longer messages become unwielthy to translate and are just harder to work with.

The three primary uses cases that Translate extension supports and has been developed those in mind are content translation, local interface translation and software translation. Each one of those are covered in following sections with links to tutorials when available and links to reference documentation or in-depth topical help where available. Of the three use cases the interface translation has been excersized the least.

Content translation
Most of the wikis have content they want to have in multiple languages. Whether just few or hundreds, it doesn't matter. For sake of translators of time, pages are best marked for translation when they are past the initial rapid expansion state. Each change that is done afterwards can affect tens or hundreds of translators and the time adds up. Especially with volunteer translators you should respect their time and avoid unnecessary work. If you use Translate extension to translate pages, you are already doing pretty good.

The way the Translate extension splits up the page into paragraphs sized sections doesn't leave too much freedom for translators to change the content. This is usually a good thing and is ideal where continuity and consistency of content across languages is desired. It can be worked around, but in principle this way of doing translations is not generally suitable for example Wikipedia articles, which usually are totally independent of each other. Even if they originally start as a translation from different language, they usually start living their own independent life form the original version. With Translate the original page is always the main version, and the content cannot be developed in translated versions.

With these limitations in mind there are still plenty of cases where this feature is a perfect match. Most if not all user documentation falls into this category as well news like content that does not change once written. If you have Translate extension already installed and rights configured, try creating a page and wrapping the whole text inside .. and follow the links or follow our nice how to prepare a page for translation tutorial.

Local interface translation in multilingual wikis
One thing almost every wiki has customized is the sidebar. It is possible to create a message group for the new sidebar messages and also for other local interface customisations.

One interesting expansion is the multilingual pages or templates build with magic word. The translatewiki.net main page and some Wikimedia Commons templates are good examples of this. The is an alternative to the content translation feature and it is more suitable to markup heavy pages just like the translatewiki.net main page. The other nice feature of that the language of the page automatically follows the interface language, so you don't need a language bar, although you might want have an interface language selector instead.

Settings this up is currently a little bit more complicated than content translation and needs software configurations, but it is all covered in the how to make a interface message group tutorial.

Software translation
Translate extensions is good fit also for translating software interface messages. At translatewiki.net Translate extension is used to translated tens of software products from games to web applications. Translate extension supports reading and updating translations from and to common formats used in web development including Java properties, Gettext and Yaml files.

The change tracking that is in core of Translate extension is also available for externally tracked files [explain]. Translation administrators can use either web interface or command line interface to check new message definitions and fuzzy (request update of) all translations when they need updating. This works regardless of the underlying file format or version control system (if any).

With simple command line tools translation administrator can easily import even large set of existing translations and with just one command they can export all translations in correct format in correct place. You can export directly to your VCS repository checkout, where you can easily commit changes and new files.

List of tutorials

 * [Translators] How to translate
 * [Translation administrators] How to prepare page for translation
 * [Translation administrators] Using message group workflow
 * [Advanced translation administrators] How to do interface element message groups
 * [Advanced translation administrators] How to write YAML configuration for file based message groups

Existing documentation
Just FYI, will be removed once everything is in place here. All subpages including pages imported from translatewiki.net:
 * For page translation: Translation/Introduction, m:User:GerardM/Translate [to be deleted soon] (quite a mess)

Todo
See translate-doc for specific tasks.