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

Translation: Difference between revisions

From MoodleDocs
(link edits)
 
Line 1: Line 1:
<p class="note">'''Note:''' In Moodle 2.0 onwards, the process and tools used for translation are significantly different. See [[Translation]] for details.</p>
<p class="note">'''Note:''' In Moodle 2.0 onwards, the process and tools used for translation are significantly different. See [[:en:Translation|Translation 2.0]] for details.</p>




Line 21: Line 21:
==Creating a new language pack==
==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 [[User:koen roggemans|Koen Roggemans]] our Translation Coordinator (''translation@moodle.org''). You may also like to post in the Using Moodle [http://moodle.org/mod/forum/view.php?id=43 Languages Forum].
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 [http://moodle.org/mod/forum/view.php?id=43 Languages Forum].


By default, an administrator can only edit a local language pack, not the master language pack. If you are not involved in translation work, you should only edit your local language pack to ensure that your changes are not overwritten by every update/upgrade of Moodle or the Moodle language packs. The documentation on how to edit languages as administrator, not translator are on the [[Language editing]] page.
By default, an administrator can only edit a local language pack, not the master language pack. If you are not involved in translation work, you should only edit your local language pack to ensure that your changes are not overwritten by every update/upgrade of Moodle or the Moodle language packs. The documentation on how to edit languages as administrator, not translator are on the [[Language editing]] page.
Line 75: Line 75:
For a new language pack, you simply archive your whole new language directory as a zip file and email it to ''translation@moodle.org''.  
For a new language pack, you simply archive your whole new language directory as a zip file and email it to ''translation@moodle.org''.  


For improvements to an existing language pack, please contact the language pack maintainer and ask how you can help. See [[Translation credits]] page for contact details of language pack maintainers. If you don't get a reply from the language pack maintainer or there are no contact details, please contact ''translation@moodle.org''.  
For improvements to an existing language pack, please contact the language pack maintainer and ask how you can help. See [[:en:Translation credits|Translation credits]] page for contact details of language pack maintainers. If you don't get a reply from the language pack maintainer or there are no contact details, please contact ''translation@moodle.org''.  


To obtain CVS access on a Moodle language pack, please send your work to ''translation@moodle.org'' for a technical review. Then apply for CVS access using the form on http://moodle.org/cvs.
To obtain CVS access on a Moodle language pack, please send your work to ''translation@moodle.org'' for a technical review. Then apply for CVS access using the form on http://moodle.org/cvs.
Line 141: Line 141:


*Using Moodle [http://moodle.org/mod/forum/view.php?id=43 Languages Forum] - news and discussion about issues that affect translations
*Using Moodle [http://moodle.org/mod/forum/view.php?id=43 Languages Forum] - news and discussion about issues that affect translations
*[[Translation credits]]
*[[:en:Translation credits|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 [http://lists.moodle.org CVS (commits) mailing list]. This helps to keep your translation as close to the English text as possible.
*To keep in touch with changes in the project on a day-to-day basis it is recommended that you subscribe to the [http://lists.moodle.org CVS (commits) mailing list]. This helps to keep your translation as close to the English text as possible.
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=75088 Automatic update of language package while updating in 1.9] forum discussion
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=75088 Automatic update of language package while updating in 1.9] forum discussion

Latest revision as of 01:40, 1 August 2011

Note: In Moodle 2.0 onwards, the process and tools used for translation are significantly different. See Translation 2.0 for details.


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

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. You can find the lang folder 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, is in moodle/lang.

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 and onwards 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.

By default, an administrator can only edit a local language pack, not the master language pack. If you are not involved in translation work, you should only edit your local language pack to ensure that your changes are not overwritten by every update/upgrade of Moodle or the Moodle language packs. The documentation on how to edit languages as administrator, not translator are on the Language editing page.

In Moodle 1.9 onwards, if you are a translator, you need to give yourself the right to maintain the master language pack. To do so, log in as an administrator, go to Site administration > Users > Define roles, then edit the Administrator role and set the capability "Edit master language packages" to allow.

Now you are capable of editing master language packs, you need to 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). Add _utf8 at the end (eg sr_utf8). Only UTF-8 language packs are possible.

Next, copy the langconfig.php from the "moodle/lang/en_utf8" folder to that newly created folder. Modify langconfig.php in a way that the settings match your language. 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! ;-) Ask for help if necessary.

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."

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

  1. Log on to your Moodle server as an administrator.
  2. Go to Site Administration >> Language >> Language editing, which is the build in Moodle language editor page.
  3. On this page you can choose for "Local string customisation" or "Language pack maintaining". Only choose "Language pack maintaining" if you are maintainer of a language pack. You need to change the setting in the administrator role as described above to get this screen.
  4. Choose your language from the menu, then choose "Edit words or phrases".
  5. 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 writable - you may have to change file permissions in your moodledata/lang folder.
  6. The forms consist of two columns, the first is that string in English and the name of each string, the second is the translation in the current language.
  7. Edit missing strings in each files (highlighted in colour), remembering to hit the "Save changes" button at the end of each form.
  8. You'll notice expressions in bold like $a->something. These are variables, used by moodle and should NEVER be translated or changed! Note that there is nowhere in the expression a space allowed. Expressions like {no} could look the the English word "no" but when surrounded by the { } denote a variable, in this case a number and should not be changed/translated.
  9. 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.
  10. A quick way to see all the missing strings is by using the link to "Check untranslated words or phrases". 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 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.

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. Note that a translation doesn't need to be complete before submitting - any improvement or start of a new translation is welcome.

For a new language pack, you simply archive your whole new language directory as a zip file and email it to translation@moodle.org.

For improvements to an existing language pack, please contact the language pack maintainer and ask how you can help. See Translation credits page for contact details of language pack maintainers. If you don't get a reply from the language pack maintainer or there are no contact details, please contact translation@moodle.org.

To obtain CVS access on a Moodle language pack, please send your work to translation@moodle.org for a technical review. Then apply for CVS access using the form on http://moodle.org/cvs.

Check list you can use before committing:

  • No empty files?
  • No untranslated files or strings (English) used in the submitted files?
  • Help files not edited with a word processor?
  • README file contains language, name and email address of the translator?
  • Folder name is the right language code (check moodle\lib\languages.php)?
  • Does the language pack run error free on a test site?
  • Are the strings and files XHTML compliant?
  • Does langconfig.php exists and is it correct?
  • No Byte Order Marks in your files (is always OK if you used the build in Moodle language editor)
  • Nowhere $a->something translated? No spaces in those expressions?

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. Use the latest stable version or at least a beta. It is not a good idea to use the head branche before the release of a beta, since the content of strings and help files can change and these changes are not noticable in the translation interface.

  • Always check out the latest stable Moodle code: do not use HEAD to do translation work before beta release.
  • 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@cvs.moodle.org:/cvsroot/moodle co lang

or to checkout just a single language pack (Czech in the following example)

  cd moodledata    (for example)
  cvs -z3 -d:ext:me@cvs.moodle.org:/cvsroot/moodle co lang/cs_utf8
  • Do not forget to set the correct file system permission so the process of your web server can modify checked-out files.

To do a checkout with Tortoise on Windows,

  right click on your dataroot folder, choose "CVS Checkout", 
  CVSROOT field:  :ext:me@cvs.moodle.org:/cvsroot/moodle
  Module: lang
  • Edit languages from within the Moodle GUI.
  • Check your files into CVS, by going 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.

CVS checkout is replaced during Moodle upgrade

During Moodle upgrade, the current language pack is automatically updated from download.moodle.org. For translators working with CVS, this replaces their CVS checkouts by the "static" non-CVS pack from moodle.org. To disable this, one just needs add

$CFG->skiplangupgrade = true;

to their config.php and keep their language pack up-to-date manually. This is intended for lang pack maintainers with CVS access only! Keep in mind that your language pack must be up-to-date before you run upgrade. See http://tracker.moodle.org/browse/MDL-17094 for more info.

Translation of contributed code

The language files of contributed modules and plugins (including blocks, filters, authentication plugins, assignment types, data fields, data presets, enrolment plugins, course formats, question types, course reports, quiz reports and resource types) reside in the lang folder within the module or plugin folder e.g. moodle/mod/modulename/lang/ln_utf8. When you wish to translate such a module, you can find the English language file in the lang/en_utf8 folder of the module or plugin. Translate this file, using a UTF-8 aware text editor, and save it in an appropriate new language folder /lang/XX_utf8/filname.php in the module or plugin folder. Please don't forget to send the translated file to the maintainer of the component, whose address may be found in the readme file in the module or plugin folder. This will ensure that your work doesn't get lost in an upgrade and is available for use by other Moodlers.

These translations should never go in your main Moodle language pack.

See also