Translation

Note: This page describes the translation process for Moodle 2.0 onwards. For details of the translation process in versions of Moodle prior to 2.0, see Translation.

Template:Moodle 2.0== Summary of changes since 1.x ==

• Translations are not kept in CVS any more but in a database at http://lang.moodle.org
• A web interface is used to translate strings
• All plugins now define their English strings in the plugin folder, as contrib plugins used to
• Language codes no longer have a _utf8 suffix
• HTML help files have been replaced with strings with a _help suffix
• Placeholders must be wrapped in curly braces
• Double quotes should not be escaped any more in the string definition

Structure of a Moodle 2.x language pack

The standard Moodle distribution comes with English language pack only. All other languages must be added to your installation. The English strings for Moodle core (that is the main subsystems like administration, gradebook, roles etc) can be found in lang/en/ folder of your Moodle installation. For example, grading related strings are defined in lang/en/grades.php. All other Moodle components (like activity modules, blocks, enrolment plugins etc) define their own strings in lang/en/ folder within the plugin directory. For example, Workshop module defines its strings in mod/workshop/lang/en/workshop.php.

Translations are located in your moodledata directory, in folder lang/xx/. Translations of all the components - both core and plugins - are stored there. For example, the Czech translation of the Workshop module is stored in moodledata/lang/cs/workshop.php and grade-related strings in moodledata/lang/cs/grades.php (note the difference against the English strings).

The language files all have a .php extension (eg moodle.php or workshop.php). These files contains short phrases, often called "strings". Strings may contain a placeholder for variable substitution. The placeholder is replaced with a certain value when the string is displayed. Strings are stored in PHP array called $string. The item key in this array is called string identifier or string name. Examples:

$string['addnewcourse'] = 'Add a new course';
$string['hidesection'] = 'Hide section {$a}';
$string['uploadedfileto'] = 'Uploaded {$a->file} to {$a->directory}';

These strings definition can be then used by get_string() function (see lib/moodlelib.php). If a string doesn't exist in a particular language, Moodle tries to find it in the so called parent language. If there is no parent language defined or it does not define the requested string, then the equivalent in English will automatically be used instead.

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 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 our script is run and commits them into Moodle sources.

Using the AMOS translation tool

Just quick notes for now, to be elaborated more - please help to improve this documentation.

Language pack maintainers can create an account at http://lang.moodle.org and email translation@moodle.org (Koen) to get their account activated for working for their language.

AMOS provides support for community contributions into the translation. If you want to participate, just create an account at http://lang.moodle.org. There is no need to contact Koen in this case but you should definitely contact the language maintainer and coordinate your work.

Basic concepts

AMOS consists of several tools available via the main navigation block - Translator, Stage, Stashes and Log.

• Translator - is a tool that allows you to filter strings you want to work on and translate them
• Stage - is a temporary area that holds the strings you have translated during the current session
• Stashes - are snapshots of the stage. Imagine them as ordinary files at your computer where you can save your work. You can share your stash with the language pack maintainers via so called pull request.
• Repository - a database of all Moodle strings and their history running at lang.moodle.org server
• Log - displays the log of all modifications of Moodle strings.

Using Translator

Use the Translator filter to show strings you want to work on. You have many options of filtering. You can work on a single component or all missing strings at once. You can search for strings containing a given text (either in English or the translated string) etc. You can check for strings in older versions, too but those strings are read-only. They get automatically pulled into AMOS from the CVS repository.

Click the Translation field to turn it into editable field and put the translation there. Click outside the field to stage your translation.

Using Stage

The translated strings are put into a temporary area called stage immediately after the cursor leaves the editor field. The stage holds your work before it is either committed into the repository (if you are language pack maintainer) or is stashed and offered to the maintainers for inclusion.

The stage is destroyed when you logout. You have to explicitly commit or stash the stage so it is saved permanently. If you forget to do it, or there is a problem with the connectivity, your browser crashes or whatever, you can find your most recent snapshot of the stage in AUTOSAVE stash.

If you are language pack maintainer, you can commit the stage into the repository so your work is registered and the translated strings become part of the official language package. Language packages in ZIP format are generated every hour (at 45 mins) and are published at http://download.moodle.org/langpack/2.0/. At the same time, they become available for Moodle sites for automatic update.

Importing file

Strings can be translated offline and uploaded back to AMOS. The only supported format at the moment is common PHP format used by Moodle where strings are defined in associative array called $string. For obvious security reasons, AMOS can not actually execute PHP files uploaded by users. Instead, it parses the uploaded file in a similar way as PHP parser, looking for patterns that are considered as valid string definition. That means that not every valid PHP code is valid string definition. AMOS parser requires following conditions are met:

• the filename is valid component name used by Moodle, for example moodle.php, enrol_manual.php or workshop.php
• the file is valid PHP code without syntax errors - that means is passes the PHP lint check
• the strings are defined as elements of global array $string
• the strings are single quoted constants

Example of valid file to import into AMOS (filename countries.php, Czech translation)

<?php

$string['AE'] = 'Spojené Arabské emiráty';
$string['AF'] = 'Afghánistán';
$string['CH'] = 'Švýcarsko';
$string['HU'] = 'Maďarsko';

?>

During the import, the strings found in the file are added into you stage as if they were translated via web. You can commit them into repository if you have such privilege.

Using Stashes

At any moment, you can save a snapshot of the current stage. We call such snapshot a stash. Stashed strings are kept forever until you drop them manually (please do not abuse this and keep your stashes reasonable big). The stash can be applied so that the stashed strings are copied back to the stage.

Your stash can be also offered to the official language pack maintainers for inclusion into the repository. Once you have a bulk of translation finished in your stage, just stash it and create pull request. This will mark the stash as available for the maintainers and they will be able to apply it into their stage, review your work and eventually commit it. Please note that the maintainers are not sent any notification on new pull requests (this is intentional to prevent spamming). Just use either Moodle messaging subsystem or direct email to inform the maintainer about the pull request. We believe that all contributors should be in contact with the official maintainer anyway and AMOS should not try to replace this kind of communication.

Your pull request is available to the maintainers of all languages that your stash modifies. Once you receive a confirmation from the maintainers that your work has been accepted, you should drop the offered stash.

There is one special stash record for every user called AUTOSAVE. This stash keeps the most recent state of the stage. You may find it useful if you loose the current stage for any reason - your browser crashes, your internet connectivity dies or you accidentally unstage all strings. If that happens, just apply the AUTOSAVE stash to get your work back. The AUTOSAVE stash is updated every time you stage a string. So if your stage is empty and your AUTOSAVE is full of strings and you go into the Translator first without applying the stash, the AUTOSAVE will be replaced with the new translated string. We recommend to experiment a bit with this feature first.

Using Log

The Log page allows even anonymous users to search in the history of commits tracked by AMOS. At the top of the page there is a filter that allows you to look for a particular information or report. It is important to realize how the filter actually works. Searching and filtering happens in two steps (this was necessary for performance reasons):

• Firstly, commit records are searched based on the criteria specified in the Commit filter form. If there are more commits found matching the filter settings, only 100 most recent commits are processed.
• Then, within the commits found, either all string modification records are returned, or you can filter these records, too. Settings in String filter form section are used in that case.

By default, the filter looks for all commits since the last time you logged in and than displays only strings at the currently translated branch modified by those commits.

Contributing to a language pack

AMOS allows community members to help with the translation of Moodle strings. At the moment, the feature is a bit experimental and the user interface and the process itself is planned to be simplified in the future (please provide you feedback and ideas to make it better!). Good communication with the language pack maintainer (to be found on https://docs.moodle.org/en/Translation_credits) is required (use email or Moodle messaging). The following steps describe the cycle of the contribution:

Steps for the contributor:

1. Contact the language pack maintainer about your intention to contribute to the language pack
2. Use AMOS translator interface to translate missing strings of amend the current translation
3. Go to the Stage page
4. Save the current content of the stage into a new stash. You should already know that stash is a snapshot of the current stage.
5. Go to Stashes page
6. Press the button "Pull request" next to the stash you want to submit to the maintainers
7. Send the maintainer a message and wait for the reply

Steps for the maintainer:

1. Go to Stashes page, you will see Incoming pull requests there
2. Apply the contributed stash. The strings will be copied into your stage.
3. Go to the Stage page
4. Review, eventually edit and/or commit
5. Let the contributor know that they should drop the shared stash