Help:Extension:Translate/Group configuration example

This tutorial is for developers and advanced translation administrators. This tutorial explains how to create new configuration files for software interface message translation, detailing the practical aspects of it. It is to be used together with the group configuration reference manual and the developers of Translate extension will gladly help you.

Prerequisites

 * Install Mediawiki
 * Install Translate extension and configure it.

This tutorial has been done with Translate extension version r97948 (2011-09-23).

This tutorial describes the process of adding to translation some parts of the MyBB project, as an example. You can follow similar steps to add other projects/files for translation. Some things are specific to translatewiki.net and you should naturally use what is relevant in your case instead of following this blindly.

Step 1: Check out source code
Let's check out MyBB source code using $wgTranslateGroupRoot as our working directory, which is  in our example.

svn co http://svn.mybboard.net/mybb/branches/1.6-stable mybb

sudo -u betawiki svn co http://svn.mybboard.net/mybb/branches/1.6-stable mybb

Now we need to find the i18n files. They are at  subdirectory and you can find the English translations under   subdirectory.

So let's start with, the first localisation file of our project.

Step 2: File Format Support
In our MediaWiki installation directory, under  we can see the classes for file format support, which are used to map message groups to localisation files of each project. You would have to do a bit digging to actually see what kind of formats they support. So we just decide to try and use FlatPhpFFS class first and see how well it works with our PHP file.

So we have a file to map and we've chosen the FFS class for it. Now we need to write a group configuration. That is just a simple YAML file.

So let's look at documentation. The index is at Help:Extension:Translate, where we can find link to Help:Extension:Translate/Group configuration. Let's start with the minimal file given as example for the BASIC section.

We can go ahead and just replace stuff with our own values for now.

The description accepts all wikitext syntax. One nice trick shown in the original example is that you can make it translatable by using. But then you need to define the english text at Mediawiki:message-key page. Note that the namespace ID is added through its constant, see how to use custom namespaces.

We need one more thing, the FFS section, again starting from the example given on the documentation:

Hmm, %CODE% is the language code, like 'en' by default. For now, we don't want to change the directory structure used by MyBB. Instead we can use a feature designed for this purpose: the codemap, which allows us to change language codes of each language to the identifiers used by our project.

So we end up with:

Basically this says that for code 'en', the %CODE% in above will be 'english', which is the directory for the English files. The key targetPattern is usually the same as sourcePattern, but without the %GROUPROOT% prefix.

Good. Now let's save this file somewhere, for example to the same folder where LocalSettings.php is stored, with name. The whole file is:

Then we must tell our extension to read that file. Add the following line to LocalSettings.php:

So let's log in, make sure we have the translate-manage right, and go to [[Special:ManageMessageGroups]].

We will see:

No valid namespace defined, got NS_MYBB. Backtrace: <...>

If we had read the documentation carefully, we would have noticed the need to add the following line to LocalSettings.php to register the new namespace into MediaWiki

We picked 1246, you can pick any free namespace number you need. [Is this the way recommended by Manual:Using custom namespaces, linked above?]

If we now reload the ManageMessageGroups special page, we should see a line which says: "MyBB This message group has not been imported previously."

Let's click on the MyBB link. You should now see the list of messages that were in that file. We are happy with the results, so we can click execute.

After you click on Execute, the file is processed and you will see an output similar to this:

Imported new version of page MyBB:L\x5b'boardstats'\x5d/en. Imported new version of page MyBB:L\x5b'new posts'\x5d/en. Imported new version of page MyBB:L\x5b'no new posts'\x5d/en. ... Cache rebuild. All done!

If the file is very large, we would need to run php Translate/scripts/sync-group.php --group=out-mybb --lang=en first, because the web interface can only import a limited number of messages at once, after which it asks you to click a button to import more.

Step 3: Adding a second file
And moving forward, let's add a second file. There are two ways to do this:

Approach 1: Adding a new YAML file
We simply add a new YAML file and save it with a new name; then we call it from inside LocalSettings.php and follow all the above steps. The file will look something like this:

As obvious in the above example, we have to use a different ID for this new group.

While easy, this approach does not scale to hundreds of different translation units (i.e. files mapped to their message group). At some point you need to update some value, and doing it for all those files is not so fun. Fortunately there is another way, shown below.

Approach 2: TEMPLATE syntax
The idea is that we pull common values into a template. Then each group will take missing values from the template and we do not need to repeat them for every group.

Let's get back to MyBB example. Let's say we want to include index.lang.php, showthread.lang.php and global.lang.php in the translatable messages. Our YAML file needs to be updated like this:

As obvious in the above example, codeMap</tt> is defined only once; addition and removal of files is as easy as adding or removing a section in the above file.

Now if you go to the ManageMessageGroups special page, you will see three items like this:

MyBB global messages: This message group has not been imported previously. MyBB index page: This message group has not been imported previously. MyBB show thread: This message group has not been imported previously.

Step 4: Aggregate group
Adding a parent group and defining the message files as subgroups of this parent group has two benefits:
 * translators don't care so much, they can just open the aggregate group and translate everything;
 * you can get statistics on the aggregate level, i.e. whole project.

In order to define a parent group, you need to add the following section right after the TEMPLATE section and before the definition of individual subgroups:

This gets us pretty close, but there is still one step missing. At this point, if you go to Special:Translate, you will see the MyBB parent group (and it in fact works!) but also the subgroups listed as separate groups. :(

This is the way to fix it: Add the following line to your localsettings.php $wgTranslateGroupStructure['/^out-mybb/'] = array( 'mybb' ); What this essentially does, is that it takes all groups whose id match that pattern, shows the first group and hides everything else below that first group. Ugly but works.

Now, if you go to Special:Translate, you will only see the parent group MyBB listed. Additionally, you will see a link title "Show 3 subgroups"; clicking on that will show you the names of subgroups.

Check out the manual for TAGS and other sections we didn't go through in this document.

Step 5: Cleaning up
YAML files of projects supported by translatewiki.net are committed to the trunk/translatewiki directory in Wikimedia Subversion repository, although that will change when they start using Git for version control.

And in translatewiki.net the LocalSettings.php lines are actually in TranslateSettings.php. Sandboxwiki at translatewiki.net doens't have a TranslateSetting.php file, which is why we added everything in LocalSettings.php