Help:Extension:Translate/Page translation administration

Documentation
Page translation feature allows controlled translation of wiki pages into other languages. In other words the content of each translation should be about equal to the source page. The source page is split into sections or paragraphs, each of which are translated individually. Also changes are tracked in the paragraph level. These paragraphs are translated using Special:Translate, which provides the common features known from message translation: display of translations in other languages, message documentation. A new feature currently unique to the page translation is a difference display of changed messages.

A translation page is constructed automatically form translated paragraphs, using the source page as model. Each translation page is assigned a completion percentage, which is calculated from the translated paragraphs, and decreased if those translations are out of date. Outdated translations are also highlighted.

Installation
This extension should be compatible with 1.14, 1.15 and 1.16 branches of MediaWiki. Fetch Translate extension form MediaWiki.org (choose trunk version) or check it out directly from Wikimedia's Subversion repository.

When the files are in place, add the following lines to LocalSettings.php. Replace sysop and user with the groups you want. translate right allows translating of pages, which are marked for translation by users having the pagetranslation right.

Then you need to run php maintenance/update.php or rerun the web installer to create new tables needed for this feature. Page translation feature should now be installed and enabled.

It is recommended to install few other extensions too, like CleanChanges and CLDR. See the Other features section for more information.

Creating translatable pages
It doesn't matter whether you create new pages or mark existing pages for translation. Marking a page for translation is a two step process. Once you have a page with content you want to translate, you must mark the translatable parts by enclosing them with &lt;translate>...&lt;/translate> tags. Beware, these tags work differently from other tags, because they do not go trough the parser. Currently they do not honour  or other such tags. For the same reason they cannot and should not be used in templates. There can be multiple such pairs of tags in one page.

The text inside translate tags are split into paragraphs. There must be at two new lines between each paragraph. Leading and trailing space are preserved, but not included in the text that is shown to translators. Putting the &lt;translate> tags on their own lines is recommended, and it does not create empty lines in the output when removed.

It is possible to use variables similar to templates. The syntax for this is &lt;tvar|name>contents. For translators these will show up only as $name, and will automatically be replaced by the value in translation pages. This can be used for often changing non-linguistic content without the need for wait for translators to update their translations.

Avoiding too much mark-up in the text makes them easier for translators to translate. Using page translation feature places some restrictions to the text. There should not be any mark-up that will span over two or more paragraphs. In other words each paragraph should be complete should work in isolation. This is currently not enforced in the software, but violating it will cause invalid rendering on the page, the severity depending on whether the resulting html is fixed by tidy or not.

Once the page is ready and the translatable content is marked it is time to put it up for translation. After the page is saved, users with pagetranslation right will see a link at the top of page. It is also possible to go to Special:PageTranslation and select the page from the list.

There you will see the paragraph division. You can give each paragraph a short name. By default the use running number from number 1 onwards. The names are permanent, so think up a good future compatible name. Each paragraph will have a corresponding page where it is translate in form Translation:Source page namespace:Source page name/section name/language code. These have to be valid titles and unique so two paragraphs cannot have the same name. The sections names also define the order of the messages, albeit this is subject to change. The main reason to give names is to keep Special:RecentChanges more readable.

When everything looks ok, use the form to mark the page for translation. Then it will appear on Special:Translate and the page itself will have a direct link to translate it. Users with translate</tt> can translate the paragraphs. The translation pages are usually updated immediately reflecting the new translations.

Stuff changes
The translation pages are protected from normal edits. Changes to the source page are not immediately "live", but a new version of the page must be marked for translation as outlined in the previous section. When page is marked for translation, the software will add some marks to it. See the example below. These marks are correspond to the named paragraphs and they are used to keep track of each section.

&lt;translate>

Birds
&lt;!--T:1--> Birds are animals which....

&lt;!--T:2--> Birds can fly and... &lt;/translate>

It is not recommended to add these marks manually or tamper with them. The software doesn't currently enforce their validity and sanity very rigorously. If paragraph is moved, the tag should be moved with it. If paragraph is deleted, delete the tag too. New paragraphs will be detected automatically. The tags are always on the line before the paragraph, or if it starts with a header, after the first header.

When marking a new version for translation wikitext difference are shown for them. New and deleted paragraphs are also listed. The person who marks can then do the final review, before creating new work for translators :). Then all the translation pages are updated to match the new model.

Currently it is not possible to unmark pages. Also, the software does not check if previously used id is first unused and taken into use again. These messages will show the difference like a changed messages to translators. Unused paragraph translation and translation pages are not cleaned up automatically, although a script or special page will be implemented for doing cleanup.

Other features
It is also possible to use tag to add list of all translation of the page with their completion and up-to-date percentages. Currently this is recommended, because there is no other indication that translations exists. A feature will be designed to try to automatically show user the preferred translation, eliminating the need to list potentially hundreds of languages.

Special:RecentChanges has a new filter that allows filtering translation away, or showing only them. This helps to keep the changes list more readable, eliminating multiple entries for each translation. Additionally it is recommended to install CleanChanges extension for filtering per user or per language. CLDR extension is recommended for localised language names for each language.