Translating the ActiveMath Server Software

This page under construction explains how to start the translation of the ActiveMath server with a new language. It should also be useful to correct or adapt the translations’ terms.

See also other pages about translation.

About

This page is an adaptation and enrichment of the README file in ActiveMath distribution under webapps/ActiveMath/i18n/I18n-Readme.txt.

This page does not cover the translation of content for which other documentation is expected in short.

Ingredients of the ActiveMath translation

The ActiveMath learning environment has the following source of textual messages which need to be adapted to each language:

• each file inside webapps/ActiveMath may be variants internationalized which means that it exists in copies in different languages. In principle, this is only the help files.
• the file may also be considered fully multilingual (e.g. the LeActiveMath logo), in which case, no translation is expected.
• the file may also use phrases of the resource bundle but, itself, be multinational
• finally, core content also comes along each ActiveMath and is used by most other content collection. These are mostly symbols and notations and should be translated as well.

Translators’ work

First, an enrichment of the configuration will be needed in order to introduce the language, even if missing all translations.

Translators should then edit the phrases file and compile.

Translators are, then, expected to go through all the directories of webapps/ActiveMath to check if each file is fully-multilingual (or uses phrases, in the case of .vm files, as can be seen with the usage of the #phrase macro), or if it has variants (such as next_de.gif which is a variant of next.gif).

Finally, translators should edit each of the .omdoc files in omdoc1/cd/ to add the translations.

Encoding warning

It has been a convention that all text files in ActiveMath are encoded using the utf-8 character set, please avoid imperatively to use editors that do not support this encoding (such as many installations of emacs or notepad).

Introducing a new language

• Find the ISO language code for your language (see the list)
• Add an entry for your language code to conf/ActiveMath.properties. This is done by adding a new property

        messages.defaultLanguage.i=XX'

where i is a number not already used by the other languages, and XX is your language code (eg. `messages.defaultLanguage.4=cn`). ### The Phrase file - For your language XX, create a file ‘i18n/phrases_XX.properties’, which must be in UTF-8. Start with an existing phrase file and use it as a template. The phrase file starts with a comment that contains more information on how to encode phrases. - Each phrase file starts with a list of language names. Add your language to *each* of the phrase files. The name of your language must be written in the language itself (“Deutsch”, not “German”). Here is the current list:

    language.de=Deutsch
    language.en=English
    language.fr=Français
    language.es=Español
    language.it=Italiano
    language.nl=Nederlands
    language.ru=Русский
    language.zh=中文

Variants Translation

The following files, at least, need to be translated by adding a variant:

• The help files are found in help/. Here, the text is directly found in the Velocity files (no phrases). To translate, copy the English version of each file to ‘file_XX.vm’ and translate that. Chances are that the English help is the most up to date, so use it as a reference.
• several other files have already variants and you should introduce yours as well
• crawling through the skins directory is probably not useful unless specifically requested.

Testing

• After changing a phrase file, you need to invoke ant i18n from the ActiveMath bin directory. The build script will convert each file i18n/*.properties into an ASCII-encoded file in i18n/ascii with the same name, which can be loaded by Java. (For details, see the JDK doc for the native2ascii tool.)

Unfortunately, you currently have to restart ActiveMath for the changes to take effect.

• For testing, you can switch the user’s language in the menu “My profile / My user data”).
• To test a single page in several languages, a trick is to append the parameter ‘&lang=xx’ to the URL.
• Changes to Velocity files are visible immediately, just reload the page in your browser.
• When you have tested, check in your changes. Don’t forget to add the new files to CVS first. If you are missing CVS commit rights, please get in touch with ActiveMath developers.

Adding new text to the GUI

When adding a new key to the GUI (because you are programming a new thingie) or changing the semantic of a message, please make sure to impact all properties files. You fill with correct values for the files you can. For the others, you fill them commented out and the word MISSING as follows:

# MISSING: register.beHappy = Let's be happy!

This way, localizers (which can be really external persons) can browse seasonally through the properties file of their language and find all the “MISSING”! Also, they see the english text and have a clue about what the phrase is.

How to remove a language

It sounds dumb to do so but it’s meaningful if you are writing skins which, typically, will only be available in context where only one or two languages make sense and is writable.

You need, for this, to overwrite the properties declaring the language making it empty. As follow, to remove french in the current ActiveMath, add the following in ActiveMath-indvidiual.properties:

  messages.defaultLanguage.3      =

(in other configuration files, which ActiveMath-individual.properties overwrites, the value is messages.defaultLanguage.3 = fr)

Translating core content

TODO: describe the task here, which involves the same OMDoc translation task for the .omdoc files in omdoc1/cd.

Adding a language to the search tool

The search tool needs special care for new languages and may fail to work with an added language. This is because several procedures are made to enhance the retrieval quality and they depend on each language.

Note that the search tool only searches the current language (different opinions welcome) unless otherwise indicated. For now, if you are lucky, you will find your content. In any case, an investigation is required to find the two following ingredients:

• a stemmer or analyzer for the Lucene retrieval library for the new language is needed. A stemmer is little procedure which converts words to their stem, allowing chevaux and cheval to be found at the same time. The snowball project of Martin Porter is probably the best tool to approach this.
• a phonetic tokenizer is also needed: this tokenizer converts words to phonetic tokens in such a way that two words that have the same phonetics become the same token. Classical algorithm include Soundex and Metaphone, we are using the latter for English, German, and Spanish for now.

One you have found approaches to this, which might to say english stemming and phonetic tokenization is ok for now, you should please contact the developers so that we can enable this for the new language… it will require development on our part though this may be really small.