Help:Extension:Translate/Page translation administration

Page translation feature allows controlled translation of wiki pages into other languages. That means that the content of each translation will be equal to the source page. This is opposed to for example the different language version of articles in different Wikipedias, which usually are independent of each other. Without any help translating more than few pages into few languages becomes a time-waster at the best, unmaintainable mess at the worst. The core points of this feature is to split the work into smaller parts and handle changes to the source article. It is assumed that languages are only translated from one language (usually English) to all others, although translators can take advantage of other language translations due to other features in Translate extension. Next there is short description of the system works. After that there is links for more in-depth documentation.

The translatable parts of source page must be marked with &lt;translate>-tags. There can be any number of such parts in one page as needed. The system will complain and prevent saving if it is unable to make sense of the result, for example if there is missing close tag.

Once those parts are tagged and page is saved, the system will detect that the page is prepared for translation. It will suggest marking the page for translation for users which have the user right to do so. The system will split everything in inside &lt;translate>-tags into sections. Each section is separated from each other with one or more empty lines. For this reason each section roughly correspond to a paragraph, and I may use term paragraph interchangeably with translatable section. Once the user has accepted the suggested sections, the page is ready for translation. Users who have the user right to translate pages are now suggested to do so when viewing the source page or any of its translations.

In the mean time the source page can be changed freely, while translators keep translating the version that was marked for translation. Only after user with right to mark pages for translation has reviewed the changes and accepted the new version, will existing translation marked as outdated if needed, and new version of the translatable sections will be shown to translators.

This is the end of general description. Depending which is your role, you can continue reading sections for System administrators, Translators or anyone who edits translatable pages. Those sections may not explain everything that is explained elsewhere in the documentation for similar roles.

System administrators
It is assumed Translate extension is already installed and basic configuration is done.

To enable page translation feature, complete the following steps:
 * 1) Add   to your
 * 2) Rerun the installer or run   the create the new tables needed for this feature.

After that you should assign right pagetranslation to suitable user group. Users in that group can mark pages for translation. You should also have translator group with right translate. For example:

If you have not already done so, it is recommended to install the following extensions:
 * mw:Extension:CleanChanges – hides extra translation edits from recent changes and provides more filters
 * mw:Extension:CLDR – provides localized language names in many languages

Content management
This documentation is for those for whose responsibility is to mark translatable parts of wiki pages and mark them for translation. Parts of it are useful for almost anyone, who are likely to see the markup in the page source. There may be dedicated translation managers or it may fall on content writer's shoulders. Either way, this manual is for you and you should take the time to read it. First I will explain the syntax, then the actual marking pages for translation together with suggestion for best practices.

Markup
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. This should not cause problems in usual cases, but may if you are trying something fancy. For this reason they cannot be used in templates. There can be multiple such pairs of tags in one page.

The text inside translate tags are split into translatable sections (roughly paragraphs). There must be at least one empty line between each section. It has simple whitespace handling: Whitespace is preserved, except if a starting or ending tag is the only thing on a line. In that case the trailing newline character for starting tags is eaten, and similarly the preceding newline character for closing tag too. This only means that they don't cause extra new lines in the rendered version of the page. If possible, try to put the tags on their own lines, with no empty lines between the content and the tags. Sometimes this is not possible, for example if you want to translate some content surrounded by the markup, but not the markup itself. This is fine too, for example:

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 every time it changes. You still need to mark new version of the source page for translation, though.

Avoiding too much mark-up in the text makes them easier for translators to translate. Page translation feature places some restrictions to the text. There should not be any mark-up that will span over two or more sections. In other words each paragraph should be standalone and be complete 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.

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.

Marking process
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 section division. You can give each section a short name. By default it uses a running number from number 1 upwards. The names are permanent, so think up a good future compatible name if you choose one. Each section will have a corresponding translation pages where the name is of form Translation:Source page namespace:Source page name/section name/language code. These have to be unique and valid titles, so two paragraphs cannot have the same name. Remember that spaces and underscores and even dots are considered the same character in the equality comparison. The main reason to give names is to keep Special:RecentChanges more readable, if section page translations are not hidden with CleanChanges extension.

All translatable sections are joined together by a translation page template. The template is the full page, where the translatable sections are replaced with placeholders.

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 right can translate the sections using all the translation aids that are available. The translation pages are updated immediately reflecting the new translations.

Handling changes
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 sections 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>

The tags are always on the line before the section, or if it starts with a header, after the first header on the same line. The reason for different placement with headers is to keep section editing working as expected.

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. The best practices are:


 * If section is moved, the section marker tag should be moved with it.
 * If section is deleted, delete the section marker tag too.
 * If new section is added, do not add mark to it. The software will generate one for it when the page is marked for translation.
 * If the section content changes so much that old translations would no longer make any sense, delete the section marker tag.
 * When merging multiple sections, keep only one section marker tag.
 * When splitting a section into multiple sections, keep the section marker tag only on the first one of the, or not at all.

When marking a new version for translation wikitext difference are shown for each section. New and deleted sections 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 template. If there is many translation for the page, the updates are handled with the MediaWiki job queue and are not immediate.

Before marking new version of page for translation, ensure that the best practices above are followed, especially that translators get a new section if the content has changed. Also make sure that there are no unnecessary changes to prevent wasting translators time. If the source page is getting many changes, it may be worthwhile to wait it to stabilize, and only after that push the work for translators.

The software does not check if previously used section id is first made unused and taken into use again. These messages will show the difference like a changed messages to translators. Unused section translations and translations pages are not cleaned up automatically, but that should not cause a trouble.

Translators

 * @link to translation aids (TBD)

Apart from the usual issues in translation, you should pay attention to links. There are three kinds of links: links within the page, links to other pages and links to external sites.


 * Internal links
 * Internal links are of type  and refer to a header somewhere else on the same.   should be exactly the same as the translation for the header ( , which may be in a different translatable section. Note that whitespace between the headers tags and the actual header are removed. There is a feature request to make it easier to have the link and the header translation match.


 * Links to other pages
 * Links to other pages are of type . For now we suggest to link to the source version (usually English) of the page, even if the target page can be translated too. There is a feature request to automatically go the translated version if available, and show some other language if not.


 * Links to external sites
 * Links to external sites are of form . Consult your own project's guidelines whether you should use translated version of the resource if available or not.

Note that you should always translate the link text, and usually you should add one if there isn't already. Please consult your own project's guidelines for more detailed rules if any.

Aside from links there may be other markup like templates. Again, consult your own project's guidelines how to handle those.