Translate extension

Translate this page

The Translate extension allows for easy translation of pages on the multilingual Wikimedia platforms. The extension is installed on all major Wikimedia platforms, except on Wikipedia that has its own translation tool.

By convention, Wikipedia is only serving one single language per platform. It has its own dedicated translation system that works across Wikipedia languages (and is automatically translating internal links and references, and updates the Wikidata sitelink).

The core of the system are <translate> and </translate> tags that mark the start and the end of translation units. Empty lines after a <translate> tag also mark translation units.

Principles

It allows Wikimedia platforms to really become multi-language, completely transparent for the end-user, and easy to be managed by the translators.

It is crucial that the master (source) page is well structured with the necessary translation tags, so that the translation process is straightforward for the translators. This is the responsibility of the authors, and the translation administrator.

Translation sections should be kept short, and should not contain specific wiki syntax. After the content of the source page is complete and stable, it is marked for translation by the translation administrator.

Notes:

This tool is not to be confused with the dedicated Wikipedia article translation tool that is used to translate Wikipedia pages.
The user can choose their GUI language, independent from the content language.

Advantages

Easy to use by translators, a bit more difficult for the base page editors, and for the translation administrators.
Keep page sections aligned amongst languages. When content on the source page is changed, translations can be easily updated, after performing another mark for translation.
Well integrated in the MediaWiki environment, e.g. using the Special:MyLanguage/ link prefix a language code suffix is automatically generated for the readers' language.
For the reader it is completely transparant.
The base language can be any language, but English is the standard (most translators understand English).
Translation to any language can be incremental; untranslated sections show the original text (typically English, but it can be any supported language).
Work can be distributed amongst volunteers. Nobody knows all languages. A volunteer can be appointed for each language.
The history of the translated texts are maintained.
Translated sections can be reused on other pages (so it is advantageous to keep translation sections short and unique).
Translated sections are automatically saved.

General procedure

Write your text. Add a single empty line before a header, a paragraph, a list, or any other sections in your document. This makes it easier for the parser to automatically create translation units.
Make sure to use internal links when possible (unique link prefixes are available).
Start your document with <languages/> on the first line to automatically build a language list. and a language menu option.
The header and the footer of the article must not be translated: place <translate> after the header and </translate> before the footer.
Special templates at the top of the page are considered being part of the header, so are not translated
Categories are considered being part of the footer, so are not translated.
Add <translate> and </translate> tags where you (do not) want to translate text.
General cleanup of the Wiki text (make sure you have blank lines before headers, paragraphs, lists, or other sections).
Lists should have one <translate> </translate> pair for each line after the * or the #
Use {{PAGELANGUAGE}} to insert the ISO language code, e.g. in URLs or language specific templates.
Use Special:MyLanguage/ to refer to other Wikimedia language pages.
Categories require a {{#translation:}} suffix.
The translation administrator marks the page for translation:
- Don't do this step until the basic document is completely ready, and stable.
- Make sure that all necessary translation markup tags are included at their proper place.
Translate the page into any wanted language; this task can be distributed to multiple translators.
Maintain the updates.
When the source text changes, the translation administrator has to mark the page again for translation.
Then editors can filter for changed or new sections.
Readers are warned for obsolete sections

Special cases

Translate an existing page

You might try the Special:PagePreparation interface to automate this:

Check the name of the base page (avoid accents or UTF characters, choose an English name).
If necessary rename the pagename (with or without redirect, depending if there are referencing pages?).
The page language should reflect the text language. If necessary change the page language (or update via Page information).
Replace any special language templates by tags supported by the Translate extension (read more below).
Continue with the general procedure above.

Migrate specific language subpages

When language subpages exist:

Rename the subpages to reflect the ISO language code.
Prepare and mark the source page.
Run the Import subpage tool to align every translated page. The previous version of each translation page is used to get the alignment done.

Migrate other translation mechanisms

Specific techniques exist, depending on the used templates. Those templates should be recoded to equivalent language tags.

Migrate {{GetFallback}} or {{int:Lang}} => {{PAGELANGUAGE}}

Migrate {{Langhead}} - Individual translated pages.

Requires renaming to ISO language suffix pages.

Migrate {{Langmajor}} - Insitu translation with LangSwitch.

Requires to separate the languages text. Remove the LangSwich templates.

Migrate {{Langmenu}} - Insitu with title update

Requires to separate the languages text. Remove the LangSwich templates.

Migrate {{Languages}} - language suffixes

Migrate {{LangSwitch}} - coding language text sections

Remove the LangSwich templates.

Restrictions

After marking the base page for translation, only the base text (source page) can be edited.
Translated pages can only be maintained by the tool. They can't be edited in the normal way.
There is a suffix version of the base text without translation units, that can be used to copy the wiki text to other platforms (or a new issue).
You need to be member of the translation administrator group in order to be able to mark a page for translation. A bureaucrat can grant this group membership.
Any user can translate the article to any language once it is marked for translation by the administrator.
There is an internal version control, so anyone can verify if a translation is out-of-date.
Never remove the space after the special translation unit comment.
Text sections and translation unit markers are bound to each other:
- Do not manually insert nor remove the translation unit comments.
- Make sure translation units are separated from each other (e.g. one blank line between the header and the next paragraph, one space after the translation marker = structured comment).
- When copying text from other (translated) pages, only paste the text, not the "foreign" translation unit comments. When necessary copy wiki code from the /en (base) version of the page (translation unit markers being removed).
- When you want to remove all text of a translation unit, also remove the structured comment, to avoid conflicts amongst translation units.
- You can move a text section, together with its marker.
- When you merge two paragraphs, remove the second translation marker.

Specific rules and tips

Translators should only see short textual paragraphs and sentences to translate. Never complicated Wiki code, nor tables, if possible.

For simple documents, i.e. only containing headings and paragraphs, only one single <translate> tag (after the header) and </translate> tag (before the trailer) is sufficient. <translate> and </translate> must always be balanced. You should put <translate> and </translate> on separate lines when possible. Don't add extra blank lines.

Insert one blank line before section headers, or a <translate> or </translate> tag.

Make sure you start every paragraph with a blank line, or a <translate> or </translate> tag (even the first paragraph after a head). Doing so the software can correctly parse heads and paragraphs.

You can mark <syntaxhighlight> and </syntaxhighlight> between </translate> and <translate> tags to prevent translation.

(long) Lists should have one <translate> </translate> pair for each line after the * or the #. Before and after the list you need to add </translate> and <translate>.

URL labels (both internal and external) need to be embedded in <translate> </translate> pairs.

You need to add one extra </translate> and <translate> tags before and after a list or a (group of) URLs.

Use the {{lwp}} template to embed a Wikipedia page.

Categories require a {{#translation:}} suffix, to discriminate them from the base categories. Categories belong to the footer, so come after the final </translate> tag.

{{PAGELANGUAGE}} can be used everywhere... it translates to the "local" ISO language code. This way you can automatically insert language sentisive prefixes or suffixes.

Use the Special:MyLanguage/ prefix to refer to other Wikimedia language pages.

Generic requirements

The extension needs to be installed by the site administrator.
Each page to be translated needs to be marked for translation by the translation administrator. This requires a special groups right. It needs to be marked again after (multiple) amendments are done.
You need volunteers capable of translating from the source language to the target language.
You better choose the source language to be the best known language amongst your community; doing so you will have more translators and translations.
Sometimes you have no choice as to take the version that is already available. Maybe the source language is just the first version of the page, whatever the language is. Wikimedia platforms have a default language. The source page language does not always match this default language. Make sure to verify or change the language code before starting the translation.

Components and functions

Edit rights	Component	Description	Remarks
Translation administrator	Set source page language	Setup or verify the page language. Every site has a default language.	Language can also be updated via "page information"
	Activate a source page for translation	Automatically add <languages/> and <translate> tags	Editing subpages is disabled after marking the page
	Mark a page for translation	Allow translators to translate a (new version of the) source page	Needs to be repeated after each edit of the source page.
	Import a subpage	Initially align translated page sections	Do it once only for each language subpage
	Deactivate a page for translation	Deactivate page translation and remove the translation tags	Enable free subpage editing again
Any user	List translated pages	Show the list of translated pages	Manage the pages
Any user	Translate	Translate any page ready for translation	The actual translated page is amended

Known problems

Too many contributions

The translate tool makes many changes in the Translations namespace. It might be needed to explicitly select the (main) namespace when searching for contributions. Otherwise you might not find your contribution.

Out-of-date translations

The translated pages don't show the same content as the source language page. But the system seems to indicate that the translations are up-to-date, which is not the case.

Solution: The original text has been modified, but the translation administrator did not mark the page for translation. Some languages still need to be updated.

Redundant verbatim translate tags

When you see verbatim <translate> and </translate> tags while saving your updates, the obvious problem is a missing empty line between a header and a paragraph, or a missing space after a translation unit marker. This leads to two "concatenated" and conflicting translation units. Remember every paragraph has to start with an empty line for the translation engine to work properly. Another problem can be redundant or missing <translate> and </translate> tags.

Wrong source language

Any language can be source language. Default is the wiki default language. English is most used, since it is internationally best known. You can only properly translate when the page language corresponds to the actual language of the text. Setting the language is restricted to the translation administrator.

Use Special:PageLanguage or page information to change the source language when it was wrongly (or not) set during the first mark for translation.

Bot automatically adds untranslated English page

Restrict the list of languages that are required.

Marking for translation

After the source page has been changed, you must refresh the page before you get the option to mark the updated page for translation.

False outdated translation warning

When translating and choosing for outdated sections, the last translated section is still shown as untranslated after it has been modified.

Filter again for untranslated sections.

A lot of updates in the page history

The translation tool saves every tranalated paragraph (translation unit) separately. It can become very confusing when viewing the long history of (user) updates.

Filter for specific namespaces.
Only show the last update.

Terms and definitions

Term	Definition	Remarks
Translation extensioin	Tool to semi-automatically translate pages on Wikimedia platforms	There exist two mechanisms, Wikipedia and a generic one (this one).
Translation administrator	Person responsible for translation	Groups right is assigned by a burocrat, after screening of the volunteer.
Translation tags	Special tags recognized by the translation tool	Examples: <languages/> <translate> </translate>
Translation unit	Piece of text to translate.	Should be kept short, and should not include Wiki tag codes or constructs.
Translation unit marker	Structured comment to indicate a translation unit	Unit markers uniquely belong to the section of text. They are automatically generated. Translated texts are stored in the database for later reuse.