Note: You are currently viewing documentation for Moodle 1.9. Up-to-date documentation for the latest stable version is available here: Translation.

Translation

From MoodleDocs
Revision as of 22:20, 25 June 2007 by Mark Nielsen (talk | contribs) (Spelling error)

Moodle has been designed for internationalisation. Each 'string' or 'page' of text that is displayed as part of the interface is drawn from a set of language files.

Structure of a Moodle language pack

Moodle1.6


  • All Moodle language packs may be found in the lang folder, with each language in a unique folder named the same as the language short name e.g. es, nl. From Moodle 1.6 upwards, the lang folder may be found in moodledata, with pack names indicating they are UTF-8 language packs e.g. es_utf8, nl_utf8. The default English language pack, en_utf8, remains in moodle/lang, along with a tiny non-UTF-8 version (en) for use in the 1.5 to 1.6 upgrade, prior to the database migration process.
  • All the main files are in the lang/xx_utf8 folder, with .php extensions (eg moodle.php, resource.php etc). These files contains short phrases, often called "strings". Each string supports variable substitution, to support variable ordering in different languages.
e.g. $strdueby = get_string("assignmentdueby", "assignment", userdate($date));
If a string doesn't exist in a particular language, then the equivalent in English will automatically be used instead.
There is also a help folder containing HTML pages for pop-up context-sensitive help.
  • Installation language packs may be found in the install/lang folder. These language packs contain only the strings needed for the installation process. The files are generated automatically every night by the download.moodle.org server and must not be changed manually. For translators this is a unusual experience, since changes you add to the strings used in the installation script will not be visible until 24 hours later in a new download of your 1.6 installation.

Creating a new language pack

If your language is not yet supported by Moodle, you may want to start a new translation. If you are starting a new language, please contact Koen roggemans our Translation Coordinator (translation@moodle.org). You may also like to post in the Using Moodle Languages Forum.

All you need to do is create a new folder in the lang directory using the 2-letter code for your language. You can find these standard codes in lib/languages.php. If you are making a local variation of another language, use the code of that language with an underscore and a meaningful two letter extension (e.g. pt for Portuguese and pt_br for Brasilian variation of the Portuguese language pack). If you are making a Unicode version add _utf8 at the end (eg sr_utf8). Language packs created with a new Moodle 1.6 or with a Moodle 1.6 in Unicode mode are always in Unicode and should get the _utf8 suffix.

Next, copy the langconfig.php from another language into your new directory. The one from the "en_utf8" folder is usually best.

You are now ready to start inserting new strings by editing your language... see below for details on this.

Note that your new language pack may not show up immediately on the dropdown list if under your site configuration you have langcache set to "Yes."

Moodle1.6


Since Moodle 1.6, only UTF-8 is used as characterset. This setting is located in a string named "thischarset" in langconfig.php and should not be changed. All other settings for your language pack, as the notation of dates, the locale string, the direction etc. are in this file and can be changed there. Just be careful! ;-)

Editing an existing language pack

Making small customisations

If you just want to change a few things in the interface to suit your own site better, don't start editing one of the standard language packs. If you do then your changes will be overwritten next time you upgrade to a new Moodle.

Instead, use the instructions above for making a brand new language pack, add a string 'parentlanguage' (in langconfig.php) with the code of the language that is most similar to yours. That language will be checked by Moodle for anything missing from yours. Here's an example of such a line:

$string['parentlanguage'] = 'en_utf8';

A good name for a local English variant could be "en_utf8_local", and the parent language would be defined as "en_utf8" or "en_us_utf8". (For Moodle 1.5 and earlier, omit the "_utf8" from the names, since older versions of Moodle don't use UTF8.)

Note that you also have to create a string 'thislanguage' in moodle.php for your "en_utf8_local" language pack:

$string['thislanguage'] = 'English at OCU';

In Moodle 1.5.x and earlier you would have to then make sure everyone chooses your new language pack. They can change it in their profiles or you can issue an SQL command to change everyone, and prevent them changing it by restricting the available languages on Administration >> Configuration >> Variables.

Moodle1.6


Starting in Moodle 1.6, the very best method is just to create a new language directory called "xxxx_local" where xxxx is the name of the language pack you want to modify (eg es_utf8_local or ja_utf8_local). This new local language pack will automatically be checked before the main one. The local pack only needs to contain the local changes (you don't need a complete copy of the language you are modifying). It will not appear in the language menus for selection and your users do not need to change their settings.

The 'parentlanguage' method described above for 1.5 still works, just in case you want to create more than one variant of one language. In this case, you still have to add the 'thislanguage' string, except in 1.6 you add it to the langconfig.php and not to moodle.php.

Translating the Moodle interface language files (the "string" files)

  1. Log on to your Moodle server as an administrator.
  2. Go to Administration >> Configuration >> Language, which is the language administration page.
  3. On this page you can choose your language from the menu, then choose "Compare and Edit Language".
  4. You should see forms you can edit for each file. If you do not, then you may have to make sure that the files are writeable - you may have to change file permissions in your web folder.
  5. The forms consist of three columns, the first is the name of each string, the second is that string in English, and the last is translation in the current language.
  6. Edit missing strings in each files (highlighted in colour), remembering to hit the "Save changes" button at the end of each form.
  7. It's OK to leave strings empty - Moodle will simply use the parent language for that string instead. You can define the parent language in langconfig.php, otherwise English is always used by default.
  8. A quick way to see all the missing strings is by using the button to "Check for missing strings". Leave the untranslated strings completely empty or this handy tool won't work.

Translating the help files

There is a built-in editor in Moodle to translate the help files. It uses the en_utf8 language pack as a reference language. You are strongly advised to use this editor: it cleans out some possible problems, it warns you for old translations and it marks (with stars in the drop down list) which files are out of date and takes care of Unicode. If you want another language than English as a reference (which is not a good idea), you copy a help file from the reference language pack and paste it on the same location in your own language pack. Then use a plain text editor with Unicode support to translate the file, making sure not to modify any code in the file (there usually is no code, just HTML-tags). (DON'T USE A WORDPROCESSOR to write the help-files because these programs add too much rubbish to the files). Don't leave untranslated help files or empty files in your language pack.

Take care to write the helpfiles XHTML-compliant. This means in short:

  • All tags should be closed:
    <p>lalala</p>
  • All elements should be nested:
    <p> lalala <em>lalala</em> </p>
  • All elements and attributes must be lower case
  • All atributes should be written in full and with quotes :
    <p align="right"> lalala </p>
  • Empty elements must end with />:
    <br /> <hr />
    . You should add an extra space before the "/" symbol.
  • An <img should have an alt="" (it can be empty) en must be closed like other empty elements with a space and /> like
    <img alt="" src="picture.gif" />
  • <?= and <? should be
    <?php
  • There should not be ANY font tags at all.
    <p><em> <h1> <h2>
    etc should be enough for the language files ...

None of the files in the help folder need a doc type, html, body, head opening and closing tags - these files are included with help.php. The script will take care of welforming the pages. This means also there is not much room for HTML creativity! Please stick to the English example. Moodle1.6


The files in the docs folder must be completely XHTML compliant, including doc type, header etc. From Moodle 1.6 they will be moved to this wiki.

Clicking on "Check for missing strings" in the language administration screen will also show you what files you are missing. If you have missing files then Moodle will use the parent language instead, so don't leave copies of untranslated help files in your language pack or this handy tool won't work.

Submitting your language pack to the Moodle project

Sharing your translation with Moodle will ensure that you help other people who speak your language. Your interface language will be available in future versions of Moodle.

Simply archive your whole new language directory as a zip file and email it to translation@moodle.org.

We will get back to you with further details.

Checklist you can use before committing:

  • No empty files?
  • No untranslated files or strings?
  • Help files not edited with a wordprocessor?
  • README file contains language, name and emailadress of the translator?
  • Foldername is the right language code (check moodle\lib\languages.php)?
  • Does the language pack run errorfree on a testsite?
  • Are the strings and files XHTML compliant?
  • Does langconfig.php exists and is it correct?

Maintenance of a standard language pack

If you are committed to maintaining a language in Moodle, it's best to use Moodle CVS so that you have an up-to-date version of Moodle, and can easily "check in" your changes directly into the Moodle project. Moodle1.6


You should always use HEAD to do translation. Instead of modifying the lang pack within your main code tree as it was until Moodle 1.6, you will now be modifying the one within your dataroot/lang directory.

  • Always check out the very latest Moodle code
  • Upgrade your site. Of course you use a NON-PRODUCTION server for this.
  • Go to your dataroot directory and check out the new lang directory from CVS there like this on Unix/Linux
  cd moodledata    (for example)
  cvs -z3 -d:ext:me@moodle.cvs.sourceforge.net:/cvsroot/moodle co lang

or like this with Tortoise on Windows,

  right click on your dataroot folder, choose "CVS Checkout", 
  CVSROOT field:  :ext:sfusername@moodle.cvs.sourceforge.net:/cvsroot/moodle
  Module: lang
  • Continue editing languages from within the Moodle GUI as you did before Moodle 1.6.

To check them into CVS, just go into the dataroot/lang directory and commit your changes.

If you really want to continue updating the language packs for 1.5.x or earlier, then you should zip the folder of your langpack and mail it to translation@moodle.org. CVS write access on moodle/lang/xx will be moved to lang/xx_utf8.

Please contact translation@moodle.org if you need help setting this up.

See also

  • Using Moodle Languages Forum - news and discussion about issues that affect translations
  • Translation credits
  • To keep in touch with changes in the project on a day-to-day basis it is recommended that you subscribe to the CVS mailing list. This helps to keep your translation as close to the English text as possible.