AMOS: Difference between revisions

Revision as of 02:17, 20 November 2012

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.

File:amos-workflow.png

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.

AMOS tools

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

File:amos-screenshot-stage-contrib.png

Strings staged by a contributor

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 submitted to the maintainers for inclusion or stashed.

The stage is cleared 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. You can also propagate the strings to other branches by selecting the branches you want the string to go to and hit the propagate button. It is a wise thing to do that, to save work and to keep consistency in the wording over the versions.

Updated language packages in ZIP format are published hourly at http://download.moodle.org/langpack/2.4/ - look at the bottom of the page to see the last update. At the same time, they become available for Moodle sites for automatic update.

The stage can also be used to import strings from files and to merge or compare versions of language packs.

Importing a file

File:amos-screenshot-stage-empty.png

Empty stage allows you to import strings from a file

Strings can be translated offline and uploaded back to AMOS using the stage page. 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
strings are defined as elements of global array $string
strings are single quoted constants

Example of a 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, strings found in the file are added into your 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). To manage your stash, click on Stashes in the right menu of AMOS. You just see a list of the stashes. There are "peekaboo" buttons that appear when you mouse hoover over the stashes. The stash can be applied so that the stashed strings are copied back to the stage. What the pop does is apply and drop (delete) the stash. drop is like delete. submit to maintainer opens a form for doing just that.

There is one special stash record for every user called autosave stash. 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 stash 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.

Language packs and Moodle versions

When a new Moodle version is released, it will become the default version on your Amos - Translator page (see tick boxes at the top).

The suggested work flow is to continue your translation work for the new Moodle version and merge your work in the older versions. You can do that using the Amos - Stage page: Set the source version to the version you were working in and set the target version to the version you want the strings to be copied to.

Contributing to a language pack

AMOS allows community members to help with the translation of Moodle strings. AMOS Contributions page tracks all submitted translations and their current status. Before you start working on a translation, please communicate with the language pack maintainer (to be found on https://docs.moodle.org/en/Translation_credits).

Steps for the contributor

File:amos-screenshot-contribution-new.png

Submitting a contribution form

Contact the language pack maintainer about your intention to contribute to the language pack
Use AMOS translator interface to translate missing strings or amend the current translation
Go to the Stage page
Click 'Submit to maintainers' button
At 'Submitting a contribution' page, please provide a message for maintainers describing your work and why you would like to see your contribution included. You can cancel the submission at this moment yet. If you are sure, click 'Submit to maintainers'.
Your stage will submitted into the contributions database. If there were more languages affected by your contribution, the stage will be divided into separate contribution records, one per each language. The language pack maintainers will be notified by email about your new contribution.
Language pack maintainers will be able to apply your work into their stage, review it and eventually commit. You will receive automatically generated email when the status of contribution changes (typically when a maintainer starts a review of your work and then when they accept or reject it).
Use contribution record comments for further communication with the maintainer about the submitted translation.

Steps for the maintainer, making own contributions

Use AMOS translator interface to translate missing strings or amend the current translation
Go to the Stage page
Make a meaningful comment about your work in the 'Commit message' form
Click on 'Commit'

Steps for the maintainer, approving users contributions

File:amos-screenshot-contribution-details.png

Contribution details page

When a user submits new contribution, you will receive automatically generated email from AMOS
Go to the Contributions page to see a list of all new incoming contributions. Click the link in the table to open the contribution details page
Press 'Start review' button. That will assign the contribution to yourself, change the status from 'New' to 'In review', send automatically generated email to the contributor and will copy the submitted strings into your stage. You should check that your stage is empty before you apply the submitted strings, unless you want to merge several contributions into one commit.
Review the submitted strings, eventually edit them. Commit the stage. It is nice to mention the contributor's name in the commit message and attribute the original authorship to them.
Go back to the contribution record and change the status to Accepted or Rejected. Automatically generated email will be sent to the contributor whenever you change the status.
Use contribution record comments for further communication with the contributor about the submitted translation.
Accepted and Rejected contributions are not shown at the contributions page unless you press 'Show resolved contributions' button.

Suggesting improvements to English language strings

Suggested fixes for typos or misspellings and any other suggested improvements to English language strings may be submitted via AMOS by contributing them to the English (fixes) (en_fix) language pack (as described above in 'Contributing to a language pack'). They will then be reviewed and implemented in the English (en) language pack.

Documentation