Help:Extension:Translate/Group configuration example

Translate this page

Documentation for Extension:Translate

Translators (main help page )

Translation administrators

Sysadmins and developers

Translate this template

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 the Translate extension will gladly help you with any questions you have after working through this tutorial.

Prerequisites

Install MediaWiki
Install the Translate extension and
Configure it.

This tutorial has been created based on Translate extension revision r97948 (2011-09-23).

This tutorial describes the process of enabling translation for some parts of the MyBB project. 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 the steps of this tutorial blindly.

Step 1: Check out source code

Let's check out the MyBB source code using $wgTranslateGroupRoot as working directory, which is /home/betawiki/projects/ in this example.

cd /home/betawiki/projects svn co http://svn.mybboard.net/mybb/branches/1.6-stable mybb

Depending on your configuration, you may need to run this as root or another user before adding project files or configuration files. On translatewiki.net, the user is "betawiki", so the above command is actually executed as:

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

Now we need to find the files containing the messages. They are in the mybb/inc/languages/ subdirectory, and you can find the English source messages under the english/ subdirectory.

So let's start with mybb/inc/languages/english/index.lang.php, the first localisation file of our project.

Step 2: Format

In our MediaWiki installation directory, in src/FileFormatSupport/FileFormatFactory.php we can see the classes for file format support, which are used to map message groups to localisation files of each project. You have to do a bit digging to actually see what kind of formats are supported. So we just decide to try and use FlatPhp format first and see how well it works with our PHP file.

So we have a file to map and we have chosen the format class for it. Now we need to write a group configuration. That is a YAML file.

In the index you can find a link to Group configuration . Let's start with the minimal file given as example for the BASIC section.

BASIC:
  id: out-freecol
  label: FreeCol (open source game)
  description: "{{int:bw-desc-freecol}}"
  namespace: NS_FREECOL
  class: FileBasedMessageGroup

We can go ahead and just replace the example text with our own values.

BASIC:
  id: out-mybb
  label: MyBB
  description: "[[Translating:MyBB|MyBB]] is a web-based discussion forum software"
  namespace: NS_MYBB
  class: FileBasedMessageGroup

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

We need one more thing: the FILES section. Again starting from the example provided in the documentation:

FILES:
  format: FlatPhp
  sourcePattern: %GROUPROOT%/inc/languages/messages_%CODE%.properties
  targetPattern: commonist/messages_%CODE%.properties

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

So we end up with:

FILES:
  format: FlatPhp
  sourcePattern: %GROUPROOT%/mybb/inc/languages/%CODE%/index.lang.php
  targetPattern: mybb/inc/languages/%CODE%/index.lang.php
  codeMap:
    en: english
    "no": norwegian

Beware, you will need quotes around language code no, because some YAML parsers interpret it as boolean.

Basically this says that for code en, the %CODE% in above will be english, which is the directory for the English message 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 MyBB.yaml. The whole file is:

BASIC:
  id: out-mybb
  label: MyBB
  description: "[[Translating:MyBB|MyBB]] is a web-based discussion forum software"
  namespace: NS_MYBB
  class: FileBasedMessageGroup

FILES:
  format: FlatPhp
  sourcePattern: %GROUPROOT%/mybb/inc/languages/%CODE%/index.lang.php
  targetPattern: mybb/inc/languages/%CODE%/index.lang.php
  codeMap:
    en: english
    "no": norwegian

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

$wgTranslateGroupFiles[] = "MyBB.yaml";

After doing this, follow the instructions at Help:Extension:Translate/Group management to run the processMessageChanges.php script.

So let's log in, make sure the user has the "translate-manage" right configured properly, and go to [[Special:ManageMessageGroups]].

You may see this:

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

In this case, reading the documentation carefully, you could have identified the need to add the following line to LocalSettings.php to register the new namespace with MediaWiki:

wfAddNamespace( 1246, 'MyBB' );

In this example 1246 is used, but you can pick any free namespace number you need. For the Translate extension, we recommend you to use the even namespace numbers 1200-1298.

If you now reload the ManageMessageGroups special page, you should see a line which says:

MyBB This message group has not been imported previously.

Click on the MyBB link. After that, you will see the list of messages that are in that file. If you are happy with the results, click "Execute".

After you click "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, you 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 because of the PHP timeout limit; if you encounter this limit, you can click a button at the bottom of the page to import the remaining messages.

Step 3: Adding another file

Now let's add a second file for MyBB for translation. There are two ways to do this:

Approach 1: Adding a new YAML file

Simply add a new YAML file and save it with a new name. Then call it from inside LocalSettings.php and follow all the above steps. The file will look something like this:

BASIC:
  id: out-mybb-showthread
  label: MyBB
  description: "[[Translating:MyBB|MyBB]] is a web-based discussion forum software"
  namespace: NS_MYBB
  class: FileBasedMessageGroup

FILES:
  format: FlatPhp
  sourcePattern: %GROUPROOT%/mybb/inc/languages/%CODE%/showthread.lang.php
  targetPattern: mybb/inc/languages/%CODE%/showthread.lang.php
  codeMap:
    en: english
    "no": norwegian

As obvious in the above example, you 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 no 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 there is no need to repeat them for every group.

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

TEMPLATE:
  BASIC:
    description: "[[Translating:MyBB|MyBB]] is a web-based discussion forum software"
    namespace: NS_MYBB
    class: FileBasedMessageGroup

  FILES:
    format: FlatPhp
    codeMap:
      en: english
      "no": norwegian
---
BASIC:
  id: out-mybb-index
  label: MyBB - index page

FILES:
  sourcePattern: %GROUPROOT%/mybb/inc/languages/%CODE%/index.lang.php
  targetPattern: mybb/inc/languages/%CODE%/index.lang.php
---
BASIC:
  id: out-mybb-showthread
  label: MyBB - show thread

FILES:
  sourcePattern: %GROUPROOT%/mybb/inc/languages/%CODE%/showthread.lang.php
  targetPattern: mybb/inc/languages/%CODE%/showthread.lang.php
---
BASIC:
  id: out-mybb-global
  label: MyBB - global messages

FILES:
  sourcePattern: %GROUPROOT%/mybb/inc/languages/%CODE%/global.lang.php
  targetPattern: mybb/inc/languages/%CODE%/global.lang.php

Notice that each group must be separated with a line containing three dashes --- without initial and trailing spaces! Otherwise the YAML file will not be parsed correctly.

As obvious in the above example, codeMap 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.

If there are a lot of files to be included in your project, it may be a good idea to write a script that generated your YAML file for you. An example can be found in svn:trunk/translatewiki/StatusNet/genStatusNet-plugins.php.

Step 4: Aggregate group

Adding an aggregate group and defining the message files as its subgroups has two benefits:

Less work for translators to select different message groups, in particular for maintenance work. Translators can simply open the aggregate group and translate or update everything that needs updating or translation for all the groups.
Statistics can be reported on the aggregate group level, i.e. whole project.

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

---
BASIC:
  id: out-mybb-0-all # The id should sort before all the subgroups it has
  label: MyBB
  meta: yes
  class: AggregateMessageGroup # Not taken from template

GROUPS:
  - out-mybb-* # We could specify them one by one, but wildcard is easier

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' );

This takes all groups whose id match the given pattern, shows the first group, and hides everything else below that first group. A bit ugly, but it works. This construction only supports two layers, even though aggregate groups can be part of aggregate groups.

If you go to [[Special:Translate]] now, you will only see the parent group MyBB listed. Additionally, you will see a link "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 translatewiki repository on Git .

In translatewiki.net, the LocalSettings.php lines are actually in TranslateSettings.php. Sandboxwiki at translatewiki.net does not have a TranslateSettings.php file, which is why we added everything in LocalSettings.php.