Developer Area/Language Packs/Translating Basics

Note: This is a work in progress and is not complete yet

So you want to translate Mahara into another language, or even just change some strings to be different from an existing translation of Mahara. This guide will give you step by step instructions on how to translate Mahara, from setup all the way to becoming an official translation maintainer for Mahara!

Tweaking strings or making a new language - make a new language pack!

Regardless of whether you just want to change 'Resume' to 'CV', or implement Mahara in a local dialect that only you and your neighbour speak, you should always make a new language pack for Mahara with your changes, instead of changing the English language files. The reason for this is that when you need to upgrade Mahara, you will find it much more difficult to do the upgrade if you have made changes to core files like the English translation files. If those files have changed, you will have to make your changes all over again - and you will have to do that every time an upgrade changes a core language file.

This doesn't mean that you will have to copy all of the English language files just to make one small change however - Mahara allows you to say that one language has another language as its parent, meaning that the other language is searched if the string could not be found in your language. This means your hypothetical language where 'Resume' is changed to 'CV' may only have 10 strings in it - which also makes it easy for you to tell exactly what you changed.

Instructions on setting a parent language will be available below.

Note: There are occasions when you might want to change language strings without making a new language, as you won't want your users to be able to choose between two language packs. There is a feature request filed for this feature.

GUI Translation Interface

David Mudrak has written a GUI translation interface for Mahara that you can access through the administration section of your Mahara installation. With some set up, you will be able to create your language pack using a simple point-and-click interface.

If that option doesn't appeal to you, read on for instructions about making a new language pack manually.

Creating a new language pack

Before you begin, you need to decide whether your language pack is similar enough to another language pack that it can be based off that pack. For example, if you are just tweaking some strings in the English language pack, then your language pack can be based off of it, whereas if you are implementing Mahara in Klingon, there will be no suitable language pack to base your translation on.

You should decide on a name for your language - e.g. "Martian" or "Klingon" - and also a language code. This is a short code that identifies your language. English uses "en" as a language code, Martian might use "mx". If your language is based off another language, then your language code might start with that language code and then have your "dialect" after it in upper case - e.g. "en_NZ" for the New Zealand dialect of English.

Once you know this information, you can begin to create the language pack.

Set up

Let's assume that you want to create a new language pack for the hypothetical Martian language. Your new language will be called "Martian" and have a language code of "mx".

Language packs are simply a directory containing other directories and files. The structure is roughly as follows:

artefact/
 artefact/blog/
 ...
 artefact/blog/lang/
 artefact/blog/lang/xx.utf8/artefact.blog.php
 auth/
 auth/ldap/
 ...
 auth/ldap/lang/xx.utf8/auth.ldap.php
 blocktype/
 ...
 grouptype/
 ...
 interaction/
 ...
 js/
 ...
 lang/
 lang/xx.utf8/
 lang/xx.utf8/account.php
 lang/xx.utf8/activity.php
 ...
 lang/xx.utf8/langconfig.php
 notification/
 ...
 search/
 ...

You can read some more notes about language pack structure, and browse around a complete language pack to find out more.

For Mahara to use the language pack you create, you have to either create it in a place that Mahara knows to look for language packs, or tell Mahara where to look for it.

Mahara automatically detects language packs installed in the langpacks/ directory of dataroot, as long as the directory they are in matches *.utf8, so if you want you can make your language pack in there - but note that the files will have to be readable by the web server user, like all other files in dataroot. In our example, all you have to do is create an mx.utf8 directory in the langpacks/ directory.

Alternatively, you may decide you want to have the language pack somewhere else (perhaps it is a hassle for you to write files in dataroot). In that case, Mahara provides a configuration variable called langpacksearchpaths to help you. If you want your language pack to be in /home/me/languagepacks/mx.utf8, put this in your config file:

$cfg->langpacksearchpaths = array('/home/me/languagepacks/mx.utf8');

As you can see, langpacksearchpaths is an array, you can specify more than one path if you have more than one language pack you want to use.

Then you should create a new directory in your dataroot to hold your new language pack. If your dataroot directory is /home/me/maharadata, then you should create the directory /home/me/maharadata/lang/mx.utf8. So you will need to create the 'lang' directory in dataroot, and then the 'mx.utf8' directory inside that. The mx comes from your language code, the .utf8 is something that all language packs should have.

The next step is to install a langconfig.php into your language pack. The easiest way to do this is to copy the langconfig.php from the English language pack and change some values in it. The English langconfig.php lives at lang/en.utf8/langconfig.php in the Mahara codebase.

You will need to change ither one or two values in there:

• $string['thislanguage'] - you should change this to the name of your language, e.g. 'Martian'
• $string['parentlanguage'] - If your language pack is going to be based off another language pack, then you should specify its language code here - e.g. "en.utf8".

Documentation TODO:

* Changing language in system settings

* Making the directories and files for the translation

* Doing the actual translation work

* Help files: A forum thread has instructions on easily copying the english files to start on the help files for your language.

* Translating language names: A forum thread has instructions on quickly getting country names for languages from the Moodle language pack.