AMOS

AMOS stands for Automated Manipulation Of Strings. AMOS is a central repository of Moodle strings and their history. It tracks the addition of English strings into Moodle code, gathers translations, handles common translation tasks and generates language packages to be deployed on Moodle servers.

The name was chosen in honour of John Amos Comenius, the author of Janua linguarum reserata (Gate to Languages Unlocked). Sorry Tori ;-)

AMOS is installed at http://lang.moodle.org. If you want to use it, please create an account there. Language pack maintainers should then send an email to translation@moodle.org (Koen) to get write access 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 us in this case but you should definitely contact the language maintainer and coordinate your work.

Basic concepts

File:amos-screenshot-navigation.png

AMOS tools in the navigation block

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

• User - AMOS is used by languages pack maintainers and by the community members who want to contribute
• Translator - is a tool that allows you to filter strings you want to work on and translate them
• Stage - is a temporary working area that holds the strings you have translated during the current session. Maintainers can permanently commit the stage into the strings repository. Contributors can submit the stage for maintainers.
• Stashes - are snapshots of the stage. Imagine them as ordinary files at your computer where you can save your work. You can submit your stash to the language pack maintainers.
• Contributions - is a database tracking all submitted contributions and their current status. Records in this database are like issues in Moodle tracker with the translated strings attached.
• 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.

Translation workflow

The following data flow diagram illustrates how AMOS tools are used during the translation process.

The key AMOS component is the staging area or shortly the stage. It holds translated strings temporarily during your current login session. If you log out, the stage is cleared (though there is a backup - see below). There are several ways how translations can be staged, that is how translated strings can be put into the stage:

• by using AMOS translator
• by importing strings from an uploaded file
• by applying a previously created stash
• by applying a submitted contribution

Language pack maintainers have write access into the AMOS strings repository. Therefore they can commit their stage permanently. Once the stage is committed, staged strings are stored in the AMOS repository. Every hour at xx:45, AMOS generates ZIP packages from the most recent snapshot of the repository. These ZIP packages are published at http://download.moodle.org/langpack/2.0/ for download. Moodle sites can install and update language packages automatically from the Site administration > Language > Language packs page.

Community members do not have write access into the repository so they can't commit their stage. Instead, they can submit it to the maintainers. By submitting a stage, a new contribution record is created and language pack maintainers are notified by automatic email message. Maintainers can review the submitted contribution and, if they accept it, commit it on behalf of the contributor.

The stage can be also saved so you can interrupt your work and continue next time you come back to the site. The stage is saved into so called stashing area. Stashing area consists of stashes. A new stash is nothing but a snapshot copy of your current stage. AMOS automatically keeps one stash for you as a backup copy of your most recent stage. A stash can be submitted to the maintainers, too.

Using the translator tool

File:amos-screenshot-translator.png

AMOS Translator tool

The translator tool page has two main parts. At the top, there is a filter form (1). You use that filter to get the strings you want to translate. When the filter settings are saved (2), a table with the filtered strings is displayed below.

Every row in the table represents a single string. The table has four columns. The first column (3) describes the version (or branch) where the string is used, its identifier and its component. You can see a text like

2.0 [completiondate,coursereport_completion]

That reads: this string is used in Moodle 2.0, its identifier is 'completiondate' and it belongs to 'courserepor_completion' component.

The second column (4) contains the English original of the string. Below the text, you can see Google icon. Click that icon to get automatic translation of the string into the language being translated. The next column contains a code of the language that this string is being translated to (for example "cs" for Czech).

Finally the last column contains the translation itself. If it is empty, the string is not translated yet, otherwise it displays the current translation. Click in the cell to turn it into the input editor. Insert the translation and click outside the cell to stage the translation. Note there is no submit button, the text is sent to the stage automatically in the background. You can see that the colour of the cell turned blue. Blue colour signalizes that the translation is currently staged.

You have many options of how to use the strings filter. 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 of 1.x translations.

The 'permalink' below the filter's submit button can be used to keep the current filter settings. For example, you can bookmark a setting use regularly or you can copy the link URL and send it to somebody so they can set their filter just by visiting that URL.

When you finish translating, do not forget to visit the stage page. You probably want either commit it (if you are a lang pack maintainer) or submit it to maintainers so they can review your work and include it into the language pack.

Using the 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 a 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 the Log tool

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

See also

• Translation 2.0
• Development:Languages/AMOS for the AMOS code documentation