View source for Help:Extension:Translate

<languages/>
{{Extension-Translate}}
[[Image:Translate manual - Translate example - 04. Untranslated.png|thumb|300px|The main special page of the extension, "[[Special:Translate]]", in its most common task, "view all untranslated messages"]]
__NOEDITSECTION__
The [[mw:Extension:Translate|Translate extension]] enhances MediaWiki 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 [[mw:translatewiki|translatewiki.net]].
<translate><!--T:116--> The Translate extension comes with an easy to use translation interface and can separate the content structure from the text content that needs to be translated, showing only the translatable text to translators by splitting the content into manageable units.</translate>
<translate><!--T:117--> Each unit is automatically tracked for changes, and translators immediately see what needs updating on a specific page or throughout the wiki.</translate>

<translate><!--T:2--> The Translate extension is used to translate the user interface of MediaWiki and other software projects at translatewiki.net by hundreds of translators every month.</translate>
<translate><!--T:118--> At <tvar name=userbase>[http://userbase.kde.org userbase.kde.org]</tvar> it is used to translate almost a thousand content pages with user documentation.</translate>
<translate><!--T:119--> It is easy to start using the Translate extension, but at the same time it also scales up and provides advanced reporting, reviewing and workflow features.</translate>

<translate>
== Features == <!--T:3-->
</translate>
[[Image:Translate manual - Translate example - 07. Editor assistant.png|thumb|300px|<translate><!--T:4--> The translation editor: a message with a tip (not visible in image) and suggestions from two assistant languages</translate>]]

<translate><!--T:5--> '''Interface:''' The main feature of the Translate extension is a simple yet functional translation interface.</translate>
<translate><!--T:120--> Besides the essential information like message definition and documentation, you can also view translations in other languages.</translate>
<translate><!--T:121--> If a definition has changed, you will see the changes.</translate>
<translate><!--T:122--> The extension comes with some built-in checks, that can help with common mistakes like unbalanced brackets and unused variables.</translate>
<translate><!--T:123--> Depending on the configuration, there are also suggestions from translation memory and machine translation services like those of Google Translate, Microsoft's Bing Translator and Apertium.</translate>

<translate><!--T:6--> The usability of the translation interface is enhanced with JavaScript and AJAX.</translate>
<translate><!--T:124--> The backend provides WebAPIs that can be used in mobile interfaces or interfaces tailored to specific kind of content.</translate>
<translate><!--T:125--> It is also possible to export messages for translation in other off-line and on-line tools that accept the [[:en:Gettext|Gettext po]] file format.</translate>

<translate>
<!--T:7-->
'''Message groups and tasks:''' Many of the features are built around two basic concepts: message groups and tasks.

<!--T:8-->
A message group represents a collection of messages. One content page would be one message group, where, in the simplest form, each paragraph would be one message in that group. Messages used in each MediaWiki extension form a message group on translatewiki.net – a few of the largest extensions have 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 the message group basis.

<!--T:9-->
The tasks, or in other words different listings of messages in a message group, facilitate different use cases. Normally a 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 messages, translated or not.</translate>

[[Image:Translate manual - Translate example - 01. LanguageStats long.png|thumb|300px|<translate><!--T:10--> This special page reports the translation status of each message group</translate>]]

<translate>
<!--T:11-->
'''Reporting and statistics:''' The extension has extensive [[mw:Help:Extension:Translate/Statistics and reporting|reporting features]] ranging from a view of untranslated messages across all message groups in a given language to lists of translators per language with their activity level.
</translate>

<translate><!--T:12--> '''Content translation:'''</translate>
<translate><!--T:126--> If you have ever tried to translate content in MediaWiki without any tools, you know it does not scale.</translate>
<translate><!--T:127--> The translated versions get out of date and there is no way to track changes to the master page, so there are many half-translated and outdated translations without a clear overview of the overall status.</translate>
<translate><!--T:128--> Translators often feel discouraged when they cannot work with small manageable pieces of text.</translate>
<translate><!--T:129--> Translators don't find what to work on or what needs updating.</translate>
<translate><!--T:130--> The users also get confused by outdated information.</translate>

<translate>
<!--T:13-->
This is all solved with the Translate extension and its page translation feature. It adds a bit of overhead to the pages that need translation, but the benefits far outweigh this. Essentially you only need to mark the parts of the page that need translation. The extension then splits such parts into paragraph sized units and creates a message group for them. After that translators can use all the features described above. In addition you can easily add a language bar with the <tvar name=lang>{{tag|languages|single}}</tvar> tag or have links automatically go to the user's preferred language version (only) when it exists, by using links of the form <tvar name=pagename><nowiki>[[Special:MyLanguage/Pagename]]</nowiki></tvar>.

<!--T:14-->
For more information see the tutorial [[mw:Help:Extension:Translate/Page translation example|How to set up a content page for translation]] and the [[mw:Help:Extension:Translate/Page_translation_administration|in-depth documentation of the page translation feature]].

<!--T:15-->
'''Developers:''' The extension comes with built-in support for many common translation file formats, like Java properties and Gettext po files. It has an extensive set of tools, both in-wiki and on the command line, to efficiently import and export translations.
</translate>

{{anchor|searching}}
<translate>
<!--T:98-->
'''Searching:''' Without a search feature, it is difficult for translators to find specific messages they want to translate. Traversing all the translations or strings of the project is inefficient. Also, translators often want to check how a specific term was translated in a certain language across the project. 

<!--T:99-->
This is solved by the special page <tvar name=search>[[Special:SearchTranslations]]</tvar>. Translators can find the messages containing certain terms in any language and filter by various criteria: this is the default. After searching, they can switch the results to the translations of said messages, for instance to find the existing, missing or outdated translations of a certain term.

== Use cases == <!--T:16-->

<!--T:17-->
You can translate almost anything with the Translate extension. Naturally there are specialized tools for translation of certain kind of content like video subtitles, that are better done with those tools, but in general ''Translate'' performs very well with any kind of text 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.

<!--T:18-->
The three primary use cases that the Translate extension supports are '''content translation''', '''local interface translation''' and '''software translation'''. All of them are covered in the following sections, with links to tutorials and 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 === <!--T:19-->
</translate>
[[Image:Translate manual - Translate example - 10. Outdated clicking.png|thumb|300px|<translate><!--T:20--> The translation is outdated: outdated parts are replaced with new source text and translators can reach the messages to update in a single click</translate>]]

<translate>
<!--T:21-->
Most wikis have content they would like to be available in multiple languages. Whether just a few or hundreds of pages, 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 made afterwards can affect tens or hundreds of old translations, and the time needed to update them adds up. Especially with volunteer translators, you should be aware of this aspect, and respect the time they spend making translations and updates, avoiding unnecessary work. If you use the Translate extension to translate pages, you are already well on your way to using the translator time available in the most effective and efficient way.

<!--T:22-->
The way the Translate extension splits up a 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.

<!--T:23-->
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 as news-like content that does not change once written. If you have the Translate extension already installed and access rights configured, try creating a page and wrapping the whole text inside <tvar name=code>{{#tag:syntaxhighlight|{{^(}}languages />{{^(}}translate>...{{^(}}/translate>|lang=html|inline=1}}</tvar> and follow the links, or follow the tutorial [[mw:Help:Extension:Translate/Page translation example|How to prepare a page for translation]].

<!--T:102-->
Groups of pages can be further aggregated together with the <tvar name=aggregate>[[Special:AggregateGroups]]</tvar> page.

=== Local interface translation in multilingual wikis === <!--T:24-->

<!--T:25-->
One thing almost every wiki has customized is the [[<tvar name=sidebar>Special:MyLanguage/Manual:Interface/Sidebar</tvar>|sidebar]]. It is possible to create a message group for the custom sidebar messages and also for other local interface customisations.

<!--T:26-->
One interesting expansion is the multilingual pages or templates built with the <tvar name=int><nowiki>{{int:}}</nowiki></tvar> magic word. The [[mw:translatewiki:|translatewiki.net]] main page and some Wikimedia Commons templates are good examples of this. The magic word <tvar name=int><nowiki>{{int:}}</nowiki></tvar> is an alternative to the content translation feature and it is more suitable to mark-up heavy pages just like the translatewiki.net main page. Another nice feature is that the language of the page automatically follows the user interface language, so there is no need for a language bar, although you might want to have an interface language selector instead.

<!--T:27-->
Setting this up is currently a bit more complicated than content translation and needs software configuration, but it is all covered in the tutorial [[mw:Help:Extension:Translate/Unstructured_element_translation|How to make an interface message group]].

=== Software translation === <!--T:28-->

<!--T:29-->
The Translate extension is a good fit for translating software interface messages. At translatewiki.net, it is used to translate dozens 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 [[w:.properties|Java properties]], [[w:Gettext|Gettext]] and [[w:YAML|Yaml]] files.

<!--T:30-->
Change tracking is also available for externally tracked files, because internally the extension uses a cached derivative version of the localisation files where the source text and its translations are stored, instead of using them directly in their original format. Translation administrators can either use the web interface or a 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).

<!--T:31-->
With simple command line tools, translation administrators can easily import even a large set of existing translations and with just one command they can export all translations in the correct format and in the correct directory structure. You can export directly to your [[w:Version control system|VCS]] repository checkout, where you can easily commit changes and new files.

== Further reading and tutorials == <!--T:32-->

=== For translators and translation administrators === <!--T:33-->
</translate>
{{anchor|For translators and translation administrators}}
[[File:How to use ExtensionTranslate - Wikimania 2017.pdf|thumb|Slides of a workshop about how to use [[mw:Extension:Translate]] at Wikimania17.]]
* [[mw:Help:Extension:Translate/Translation example|How to translate]] [Tutorial]
* [[mw:Help:Extension:Translate/Translation best practices|Translation best practices]]
* [[mw:Help:Extension:Translate/Statistics and reporting|Statistics and reporting]]
* [[mw:Help:Extension:Translate/Quality assurance|Quality assurance]]
* [[mw:Help:Extension:Translate/Message group states|Message group states]]
* [In progress] [[mw:Help:Extension:Translate/Search|Search]]
* [[mw:Help:Extension:Translate/Off-line translation|Off-line translation]]
* [In progress] [[mw:Help:Extension:Translate/Glossary|Glossary]]

=== For translation administrators ===

* [[mw:Help:Extension:Translate/Page translation example|How to prepare a page for translation]] [Tutorial]
* [[mw:Help:Extension:Translate/Page translation administration|Page translation administration]]
* [[mw:Help:Extension:Translate/Unstructured element translation|Interface message groups (localised sidebar, main page and templates)]] [Tutorial] 
* [In progress] [[mw:Help:Extension:Translate/Group management|Message group management]]
* [[mw:Help:Extension:Translate/Group configuration|YAML configuration format]]
* [[mw:Help:Extension:Translate/Group configuration example|How to write YAML configuration for file based message groups]] [Tutorial]

=== Reference documents for developers ===
* [[mw:Help:Extension:Translate/Installation|Installation]] and [[mw:Help:Extension:Translate/Configuration|Configuration]]; [[mw:MediaWiki Language Extension Bundle]] should be enough in most cases.
* [[mw:Help:Extension:Translate/Translation memories|Translation memories]]
* [[mw:Help:Extension:Translate/Developer guide|Developer guide]]
* [In progress] [[mw:Help:Extension:Translate/Components|Translate explained for developers]]
** [[mw:Help:Extension:Translate/Hooks|Hooks]]
** [In progress] [[mw:Help:Extension:Translate/Message groups|Message groups]]
** [In progress] [[mw:Help:Extension:Translate/File format support|File format support]]
** [[mw:Help:Extension:Translate/Translation_aids|Translation aids]]
** [Unwritten] [[mw:Help:Extension:Translate/API|action API]]
** [[mw:Help:Extension:Translate/Insertables|Insertables]]
** [[mw:Help:Extension:Translate/Command line scripts|Command line scripts]]
** [[mw:Help:Extension:Translate/Process flow in MediaWiki jobs|Process flow in MediaWiki jobs]] - Describes what jobs are involved when a page is marked for translation or a section is translated
** [[mw:Help:Extension:Translate/Translation memory architecture|Translation memory architecture]]

=== Related ===
* [[mw:Extension:TranslationNotifications#Special_pages]]
* [[mw:Localisation/Tutorial]] - General localisation tutorial for developers, for use at hackathons & trainings
* [[mw:Extension:TranslateSvg]] - Adds support for translating SVG files
* [[mw:Universal Language Selector]] - Provides web fonts and input methods
* [[m:Special:MyLanguage/Translatability|m:Translatability]] – things to think about when creating pages or processes on multilingual wikis
* [[m:Tech/Translators/List|m:Tech/Translators/List]] - Add yourself to the list of currently active tech translators

[[Category:Extension:Translate| ]]