Help:Extension:Translate/Group configuration example

Documentation of adding a new project to a Translate installation.

Prerequisites
Install Mediawiki Install Translate extension and configure it

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

This document describes the process of adding parts of MyBB for translation, as an example. You can follow similar steps to add other projects/files for translation.

Step 1: Check out source code
Let's check out MyBB source code into $wgTranslateGroupRoot, the value is /home/betawiki/projects/ for us.

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

NOTE: On Translatewiki, always sudo as betawiki user before adding project files or configuration files. 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 i18n files. They are at /home/betawiki/projects/mybb/inc/languages/ and you can find the English translations under english/ subdirectory.

So lets start with /home/betawiki/projects/mybb/inc/languages/english/index.lang.php

Step 2: File Format Support
Under Translate/ffs we can see the classes for file format support. You have to do a bit digging to actually see what kind of formats they support. We decide to try to use FlatPhpFFS first and see how well it works.

So we have a file and FFS class for it. [22:54:42] Nikerabbit> now we need to write a group configuration [22:54:54] Nikerabbit> that is a simple YAML file

So let's look at documentation. The index is at http://translatewiki.net/wiki/Translating:Documentation, where we can find link to http://translatewiki.net/wiki/Translating:Group_configuration. Once we recover from the shock after seeing that photo, we can see example files. Let's start with the minimal file given as example

BASIC: id: out-freecol label: FreeCol (open source game) description: "" namespace: NS_FREECOL class: FileBasedMessageGroup We can go ahead and just replace stuff with our own values for now.

BASIC: id: out-mybb label: MyBB description: ""MyBB is a web-based discussion forum software" namespace: NS_MYBB  class: FileBasedMessageGroup We need one more thing, the FFS section, again adapted from the example given on that page.

FILES: class: FlatPhpFFS 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 don't want to change the directory structure. We can use a feature designed for this purpose - the codeMap.

So we end up with:

FILES: class: FlatPhpFFS sourcePattern: %GROUPROOT%/mybb/inc/languages/%CODE%/index.lang.php targetPattern: mybb/inc/languages/%CODE%/index.lang.php codeMap: en: english

(Beware, you will need quotes around 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 files.

targetPattern is usually the same as sourcePattern, but without the %GROUPROOT% prefix.

Good. Now lets save this file somewhere, for example to the same folder where LocalSettings.php is stored, with name MyBB.yaml

Then we must tell our extension to read that file. Add the following line to LocalSettings.php: $wgTranslateGroupFiles[] = "MyBB.yaml";

The whole file:

BASIC: id: out-mybb label: MyBB description: ""MyBB is a web-based discussion forum software" namespace: NS_MYBB  class: FileBasedMessageGroup FILES:  class: FlatPhpFFS  sourcePattern: %GROUPROOT%/mybb/inc/languages/%CODE%/index.lang.php  targetPattern: mybb/inc/languages/%CODE%/index.lang.php  codeMap:    en: english

NOTE: Save the file while you're sudo'ed as betawiki user.

So let's log in, make sure we have the translate-manage right, and go to http://sandbox.translatewiki.net/wiki/Special:ManageMessageGroups

We will see:

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

If we would have 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

wfAddNamespace( 1246, 'MyBB' );

We picked 1246, you can pick any free namespace number you need.

If we now reload the ManageMessageGroups special page, we should se 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 would have been very large, we would have run sudo -u betawiki php Translate/scripts/sync-group.php --group=out-mybb --lang=en, because the web interface can only imported limited number of messages at once, after which it asks you to press button to import more.

Niklas: First we could mention about the  shown on Special:Translate 0:09Niklas: it corresponds to the description key, but instead of using we can just write wikitext description directly in it 0:09Niklas: description key in the YAML file, BASIC section to be exact

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 YALM 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 sometihng like this:

BASIC: id: out-mybb-showthread label: MyBB description: ""MyBB is a web-based discussion forum software" namespace: NS_MYBB  class: FileBasedMessageGroup FILES:  class: FlatPhpFFS  sourcePattern: %GROUPROOT%/mybb/inc/languages/%CODE%/showthread.lang.php  targetPattern: mybb/inc/languages/%CODE%/showthread.lang.php  codeMap:    en: english

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



Approac 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:

TEMPLATE: BASIC: description: ""MyBB is a web-based discussion forum software"   namespace: NS_MYBB    class: FileBasedMessageGroup  FILES:    class: FlatPhpFFS    codeMap:      en: english --- 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

As obvious in the above exapmle, 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 ManageMessageGouprs 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 thingy
Adding a parent gorup 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, ie whole product

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:

--- BASIC: id: out-mybb-0-all # The id should short 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 you also see th subgroups listed as separate groups :(

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

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 http://translatewiki.net/wiki/Translating:Group_configuration#TAGS and other sections we didn't go through in this document.

Step 5: Cleaning up
YAML files of projects supported by Translate are usually committed to the Translate extensions' source and are stored in extensions/Translate/groups/ (for now, we are planning to move them to /trunk/translatewiki)

And the LocalSettings.php lines are actually in TranslateSettings.php. (Sandbox doens't have a TranslateSetting.php file, which is why we added everything in LocalSettings.php)