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 every MediaWiki wiki where it is used with essential features needed to do translation work. It can be used to translate the content pages, 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 the content into manageable units. Each unit is automatically tracked for any changes, and translators immediately see what needs updating on a specific page or throughout the wiki.

Translate extension is used to translate the user interface of MediaWiki and other software projects at translatewiki.net by hundreds of translators every month. At userbase.kde.org it is used to translate almost a thousand of 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


Interface: The main feature of Translate extension is a simple yet functional translation interface. Besides the essential information like message definition and documentation, you can also view translations into other languages. If a definition has changed, you will see the changes. The extension comes with some built-in checks, that can help with 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 enhanced with JavaScript and AJAX, but editing the messages in a normal page edit window is also supported. All the same translation aids are provided in that view too. And it is 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. In addition, there is a Web API that can be used to build custom interfaces.

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

A message group represents a collection of messages. One content page would be one message group, where each paragraph of it would be one message in that group. Messages used in each MediaWiki Extension form a message group – few of the largest extensions have even multiple groups. You can also make a 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 listings 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 are tasks where you can review messages or just get a list of all of them.

Reporting and statistics: The extension has extensive reporting features ranging from view of untranslated messages across all message groups in a given language to lists 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, while likely being only half-translated. Translators often feel discouraged when they can not work with small manageable pieces of text. Translators don't find what to work or what needs updating. The users also get confused by outdated information.

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

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

Developers: Developers will be pleased that the Extension comes with built-in support for many common translation file formats, like Java properties and Gettext po files. It 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 of certain kind of texts like video subtitles that are better done with those tools, but in general Translate performs very well with any kind of texts that can be split into messages with length ranging from one word up to one large paragraph. Longer messages become unwieldy to translate and are just harder to work with.

The three primary use cases that Translate extension supports are content translation, local interface translation and software translation. All of them 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 utilized the least.

Content translation
Most of wikis have content they want to have in multiple languages. Whether just few or hundreds, it doesn't matter. In order to prevent wasting translator's time, pages should be marked for translation only when they are reasonably stable. 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 paragraph sized units does not 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, for Wikipedia articles, which usually are totally independent of each other. Even if they originally start as a translation from a different language, they usually begin living their own independent life from the original version. With Translate the original page is always the main version, and new 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 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 custom 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 is that the language of the page automatically follows the interface language, so you don't need a language bar, although you might want to have an interface language selector instead.

Settings this up is currently a 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
The translate extension is a good fit for translating software interface messages. At translatewiki.net it is used to translate tens of software products from games to web applications. The 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) 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 a 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.

Further reading and tutorials
For translators and translation administrators:
 * [Proofreading] How to translate [Tutorial]
 * [Unwritten] /Translation best practices/
 * [Proofreading] /Statistics and reporting/
 * [Unwritten] /Quality assurance/
 * [Proofreading] /Message group states/

For translation administrators:
 * [Proofreading] How to prepare page for translation [Tutorial]
 * [Needs updating] /Page translation administration/
 * [In progress] How to do interface element message groups [Tutorial]
 * [Unwritten] Message group management

Reference documents for developers:
 * [Needs checking] /Installation/
 * [Needs checking] /Configuration/
 * [Proofreading] How to write YAML configuration for file based message groups [Tutorial]
 * [Needs updating] YAML configuration format
 * [Needs checking] How to set up translation memory [Tutorial]

Todo

 * Other pages to tidy up: Translation/Introduction, m:User:GerardM/Translate
 * See translate-doc for specific tasks.