Localising Joomla! Documentation

I am pleased to announce the launch of our localisation project for Joomla! documentation. Using an extension designed specifically for translation of pages, our documentation can now be translated. In fact, the translation will be close to the original content of a current documentation page. Once translated, a page will be tracked and when needed, it can be updated easily if the content changes.

For a long time, our international community has desired Joomla! documentation in their native language. One of the major hurdles was deciding how and what tools to use for translating our documentation. This not only included how to translate, but how to track documentation changes while keeping the translated pages up-to-date with the original source pages. You can see an example of a translated page in our sandbox.

Besides tracking the original content of the page, if the original content ever changes, the translation can be updated easily. What is radically different from traditional translations, it will be unnecessary to translate the entire page again. Translators will only have to re-translate the section of a page with changes.

Organised Workflow

As the Documentation Working Group launches this project, please keep in mind we must be organised and use an appropriate workflow. Joomla already translates strings for the language packs available for our CMS's core with a specific workflow. Our translation of documentation will take a similar approach. Our workflow will be mainly set by the extension we are using for translations. Below is a brief summary of our documentation translation workflow.

Our current documentation is en-GB. The English version of a page will be the source language. Simply, there must be an English version of a page for translation.
A page must be marked (tagged) for translation. The page will automatically be sectioned into smaller translation units called 'message groups' when the page is saved. The message groups are used to track changes but more importantly, they break a page into smaller sections for translation.
A marked page must then be approved for translation by a Translation Administrator. The role of a Translation Administrator will be to determine if a page should be translated and verify if the page’s message groups are manageable.
Once a page is marked and approved, it can be freely translated into any language. A translator will not have to translate the entire page all at once and may work at their own speed translating a few message groups at a time. The fallback language is always the source language.
Any user with translator permission can help translate pages and any translator will be able to review other translator’s translations. For some languages, the translator and translation reviewer may be one and the same.
Translations are available for viewing immediately upon a successful translation save completion.
If the source content of a page is changed, a Translation Administrator marks the changes so the translators know there have been changes. Step 5 will start again with the exception that only the changes to affected message groups need to be translated again. For example, if a page has been sectioned into 15 message groups and the changes only affect 1 message group, then only 1 message group will need to be re-translated.

For a more indepth look, please read about the Life of a Translatable Page on https://www.mediawiki.org.

Tools for Translators

There are tools built into the extension to assist volunteer translators. One of the most useful ones is machine translation to assist in preparing some text for manual translation. Most translators know machine translations are inaccurate because they lack the finite knowledge of a language, but they can be useful in helping build a text block quickly which can be manually improved by an actual human translator. Translators can choose to use this feature or completely ignore it.

Translators may sign up to be notified about new pages which need translation. These notifications can be by email, a user talk page post or both. Settings include instant notifications to a weekly or monthly digest. Translation Administrators will be able to send out these notices for page translations or re-translations to a page.

Another built-in tool allows for exporting a file of translation units or ‘message groups’ in need of translation. The exported file can be for a single page or multiple pages. Translators can then use a local translation tool such as Poedit. Once translations are complete locally, you can then import the file, review the individual changes and commit the changes. Even a partially translated file of message groups can be imported. Only changes to the message groups being imported will be processed.

There are reports to track translated page statistics, such as percentages of completion, and notifications of a page’s base language change. Actually there is a dual purpose for these percentages. A documentation reader will know a page’s percentage of translation when they view it. The viewer will also know if changes to the source language have occurred and the translation they are reading is not in sync with the source content.

A Call for Volunteers

Even though we are in the early stages of the documentation translation project, there are already volunteers interested in Spanish and Dutch translations. I hope everyone is excited and can’t wait to sign up as a translator for your language. The international community has really desired localisation of documentation, but it will take willing volunteers and the dedication of interested community members to make this project a success.

Here are some key pages to help translators understand translation of our documentation.

This is a large project and there will be decisions to make as it progresses. One thing I would like to discuss further, will there be a need to use a channel specifically for translator help and feedback. If so, what should we use? The Documentation Mail List? The #joomla irc channel? I also recently discovered a #joomla-docs irc channel, should we use this instead? Those with an interest should be able to come and go as needed.

Please provide feedback and comments on https://forum.joomla.org/viewtopic.php?f=704&t=836702.