Help:Extension:Translate/Page translation administration

The 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 a few pages into a few languages becomes a time-waster at best, an unmaintainable mess at worst. The core points of this feature are to split the work into smaller parts and to 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 the Translate extension. Next, there is a short description of how the system works. After that, there are links for more in-depth documentation.

The translatable parts of the 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 a missing close tag.

Once those parts are tagged and the 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 inside &lt;translate>-tags into sections. Each section is separated from the others with one or more empty lines. For this reason, each section roughly corresponds to a paragraph, and I may use the 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 a user with the right to mark pages for translation has reviewed the changes and accepted the new version, will existing translations be marked as outdated if needed, and a new version of the translatable sections will be shown to translators. The page translation log will have entries for who marked which version of pages for translation, or who took pages out of translation.

This is the end of the general description. Depending on which is your role, you can continue reading the 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 that the Translate extension is already installed and its basic configuration is done.

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

After that you should assign the right pagetranslation to a suitable user group. Users in that group can mark pages for translation. You should also have the 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 whose responsibility it is to mark translatable parts of wiki pages and mark the pages 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 the responsibility may fall on the 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, and then the actual marking of pages for translation together with suggestions 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 that you want to translate, you must mark the translatable parts by enclosing them within &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 usually, 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 is 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 for the preceding newline character for the closing tag. 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 waiting for translators to update their translations every time it changes. You still need to mark the new version of the source page for translation, though.

Avoiding too much mark-up in the text makes it easier for translators to translate. The page translation feature places some restrictions on 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 of the page, the severity depending on whether the resulting html is fixed by tidy or not.

It is also possible to use the tag to add a list of all translations of the page, with their completion and up-to-date percentages. Currently this is recommended, because there is no other indication that translations exist. A feature will be designed to try to automatically show the user the preferred translations, 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 the 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 corresponding translation pages where the name is in the 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 the CleanChanges extension.

For sections whose content has changed, there is a check-box that allows you to skip the normal process that invalidates translations. It is useful for spelling fixes, where the normal process would just waste translators' time in marking translations up-to-date without any actual changes.

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 the 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 a page is marked for translation, the software will add some marks to it. See the example below. These marks 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 for 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 a section is moved, the section marker tag should be moved with it.
 * If a section is deleted, delete the section marker tag too.
 * If a new section is added, do not add a 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 new section, or not at all.

When marking a new version for translation, wikitext differences 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 are many translations for the page, the updates are handled with the MediaWiki job queue and are not immediate.

Before marking the new version of the 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 for it to stabilize, and only after that push the work for translators.

The software does not check if a previously used section id is first made unused and taken into use again. These messages will show the difference like a changed message to translators. Unused section translations and translations pages are not cleaned up automatically, but that should not cause 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 page.   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 is 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 to the translated version if available, and show some other language if not.


 * Links to external sites
 * Links to external sites are of the form . Consult your own project's guidelines as to whether you should use a 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 one 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 for how to handle those.