Help:Extension:Translate/Page translation example

Welcome! After completing this tutorial you'll know how to create and manage translatable pages using Translate extension. We aim to keep this tutorial as short as possible while introducing all the basic concepts and tasks. After completing this tutorial you can use the in-depth documentation about page translation feature.

Step 1: Before starting
This tutorial assumes that Translate extension is already installed and configured. You might already have a page in mind, or you can use the example page provided below to try out the steps in this tutorial in your own wiki.

This is a page describing the imaginary municipality of Fréttinga. Fréttinga is a small municipality in MungoLand, located on the BaMungo island. It hosts a population of about 400 people. It has some agriculture and fishing. Tourists like to visit it in the summer time. == Services == It doesn't have many services. There is a shop and a car ferry visits the island from the mainland once a day.


 * 1. Go to the page Fréttinga in your wiki and click create.
 * 2. Paste the above content and save it.

Step 2: Preparations


Now we have a page with some text. If the page is still seeing lots of changes and big refactorings, it is better to wait until the edits slow down to normal level before adding the page into the translation system, this is to avoid too much work for translators as they need to keep up with all the changes.


 * 3. Edit Fréttinga
 * 4. Wrap the whole content inside ... tags like shown below
 * 5. Save the page

&lt;translate> Fréttinga is a small municipality in MungoLand, located in the BaMungo island. It hosts a population of about 400 people. It has some agriculture and fishing and tourists like to visit it in the summer time. == Services == It doesn't have many services. There is a shop and car ferry visits the island from mainland once a day. &lt;/translate>

Step 3: Enabling translations


After saving the page, you will see a text saying "Mark this page for translation" (or "This page contains changes which are not marked for translation." if you are not a translation admin). Click the link. The page has been automatically split into three translation units. The first unit is the title of the page and two following units are the paragraphs of the page source. These are the basics items of translatable pages: each unit is independent; it can and must be translated as a whole; changes to the page content are tracked into the unit level. Units can be rearranged or deleted. There is also a view of the page translation page template, but let's ignore that for now and return into that in later steps. You can give names to the units, but let's go with the defaults.


 * 6. Click the "Mark this page for translation" link
 * 7. Ensure that the page body is split into two units correctly
 * 8. Click the "Mark this version for translation" button
 * 9. Return to the page

Now you will see a new link at the top, "Translate this page", that lets translators to translate the page. You might have a look at the translation tutorial which uses this page as an example and try out few translations now. Then return here for the next step.

Step 4: Making changes
Tracking changes is a very important feature, so let's do some and see how it works. When you open the page for editing you will see that it has been modified with markers like. These are added by the extension and help it identify which unit is which. This allows you to rearrange and edit those units. When editing the page, the markers should be left alone and their position in relation to the unit they belong to should not be changed. When moving a unit, move the unit marker too. When deleting a unit, delete the marker too. When adding new paragraphs, new markers will be added by the software. Do not try to do this manually, it may confuse the software.

&lt;languages /> &lt;translate> &lt;!--T:1--> Fréttinga is a small municipality in MungoLand, located in the BaMungo island. It hosts a population of about 400 people. It has some agriculture and fishing and tourists like to visit it in the summer time. It has marvelous beaches with a lot of seagulls. == Services == &lt;!--T:2--> It doesn't have many services. There is a shop and car ferry visits the island from mainland once a day. In 2009 January the roof of the church in the island fell down. It was rebuilt collaboratively in the following summer. &lt;/translate>




 * 10. Make some additions as highlighted above
 * 11. Click the "marked for translation" link at the top
 * 12. Observe the changes
 * 13. Click the "Mark for translation" button
 * 14. Return to the original page

If you did translations as suggested in previous step, you can now see those translations linked at the top. You will also see that the translation is not 100% up to date. If you go look at the translated version, you will see the new paragraph, and the changed paragraphs will be highlighted. This is shown in the screenshot. If you go the translation view, you see that the unit is marked to be in need of updating.

The translation template view helps you to see what parts of the page are constant in all language versions (the "translation page template", i.e. the parts outside translate tags) and also shows you if units have been moved around.

There might be a slight delay before all translated versions are updated, because there can be many pages to update.

You now know the basics, but this tutorial will continue with more things that you are likely to encounter.

Step 5: Adding other wiki elements
We have a basic translatable page now, but it is very dull. Let's add an image and some other stuff to make it look more like a normal wiki page and see how those elements interact with translation.

We also removed a paragraph, including the unit marker for it, and replaced it with a list, just to give you a chance to see what happens.


 * 15. Add an image, a category and a list to the page as shown below
 * 16. Save the page
 * 17. Click the link "marked for translation" on the top
 * 18. Verify that the changes look correct
 * 19. Click "Mark this version for translation" button
 * 20. Return to the page

&lt;languages /> &lt;translate> &lt;!--T:1--> Fréttinga is a small municipality in MungoLand, located in the BaMungo island. It hosts a population of about 400 people. It has some agriculture and fishing and tourists like to visit it in the summer time. It has marvelous beaches with a lot of seagulls. == Services == &lt;!--T:2--> It doesn't have many services. There is a shop and a car ferry visits the island from the mainland once a day. Main events: * The roof of the church fell down in 2009 * New church was built in 1877 &lt;/translate>

Here you can see that we left most of the image markup outside of a translation unit and have it in the template instead. This is usually okay, but sometimes you might want to allow translators to change the image, especially if it contains linguistic content (text). In those cases it's usually easiest to include the whole markup in a unit (as we did for the category). When the translation of a unit involves or interacts with markup it's a good idea to write a small tip to the translators about it. You can do this with the following steps.


 * 21. Click "Translate this page" link at the top
 * 22. Select "qqq - Page documentation" language
 * 23. Click the message name which contains the message "A typical view of Fréttinga"
 * 24. Write "Description of an image" and Save

In the example the whole category assignment is a translation unit. This lets translators change it to or whatever naming convention you want to use for categories. If it were outside the translation template, you would have all the pages Foo, Foo/de, Foo/ru, Foo/ta and so on in the same category. Sometimes this is okay, but usually it distracts the users. Make sure your translators know what the convention is.

Similarly, for links there are many ways to do it. We used Special:MyLanguage/Seagull, which automatically goes to translated version of the page depending on the users interface language (if that translation exists). This isn't an ultimate solution, because user will always be redirected to the interface language they're using, not the language they are currently reading. Special:MyLanguage also interferes with Special:WhatLinksHere and makes it not work. The good thing with Special:MyLanguage is that you always get some version of the page, even if the requested translation doesn't exists.

Last words
It is also possible to move translatable pages including all their translations to a new name. Again, since many pages need to be moved, this operation is not instant. You can delete either the whole page including all translations, or just one translated version of a page. You can access these functions from the same place they are on all other pages.

Special:PageTranslation lists all the pages in the system. Besides giving you an overview of all translatable pages, there is also the possibility to discourage pages from translation. This hides the page from most of the lists. It does not prevent further translations.

You have now created a translatable page and tried all of the common actions that can be done to translatable pages. Should you still have thirst of information or want to understand the feature more deeply, please continue reading on the in-depth documentation of page translation feature. It also contains discussion about different way of handling links, categories and templates or pros and cons of using larger and smaller translation units.