LenMus translation instructions

This guide is supposed to be a first start for translators. There are probably errors. Please tell me if you find any. Thank you.

I'd like to translate LenMus into my own language

What should I do?

If you are interested in translating LenMus to your own language, I'd be happy to include your translation. But I would expect that you continue doing it for the coming LenMus versions, at least for some time. It would be frustrating for users to find LenMus in their native language in one release and not to find it updated in next version. And for you, once a translation exists, translating a new version of the program generally requires just a couple of hours to translate the new strings added or changed, as the other information rarely changes.

There is a list with the status of current translations, so you can check if your language is already included and/or it needs to be updated.

There is also a mailing list intended for LenMus translators in SourceForge.net: Translators mailing list. Please consider joining to the list if you are interested in translating LenMus. When the next release is approaching, I notify to the lenmus-translators mail list, to give you a chance to update the translation with any new/changed strings. Also, all relevant instructions for translators are posted to this list.

The steps to do are the following:

  1. Join the Translators mailing list, and post a message informing about the new translation you are going to do.
  2. Download and install the recommended translation tool poEdit or other tool that can handle and manipulate PO files (see Needed tools).
  3. Download the language pack, containing the files to translate.
  4. Do the translation.
  5. Test your translation.
  6. Send me your translation

Thank you in advance for your help!

How much work is it to translate LenMus?

LenMus executable translations are based on PO files. PO files are text files which have original English strings and translated strings listed together.

To fully translate LenMus you will have to translate several files:

  • Two (lenmus_xx.po and wxmidi_xx.po) are for the LenMus program strings (visible strings, dialogues, message boxes, etc.) and the installer.
  • Next one is for the General Exercises book (GeneralExercises_xx.po).
  • Three more, are for the other books (one per book: L1_MusicReading, L2_MusicReading and TheoryHarmony)
  • Finally, one HTML document: the Study Guide (study-guide.htm).

To include a translation into LenMus, at least the first three files must be translated (lenmus_xx.po, wxmidi_xx.po, GeneralExercises_xx.po).

Getting credit for your work

In the LenMus project your translation work will be acknowledged in the following ways:

  • On the relevant LenMus web site pages (credits and translation credits pages).
  • In the Help >About box of the LenMus program.
  • In all relevant documentation, in the credits section.

Needed tools

Translating documentation is not very difficult in itself. It is relatively simple to do a translation when you have to translate everything. The difficult part comes when you have to maintain your work. Detecting which parts did change and need to be updated is tiring, error-prone and highly unpleasant.

Think about a typical review scenario for a translator:

  1. Compare the previous English file with the new one.
  2. Identify the changes.
  3. Identify where theses changes must be introduced in the translated document.
  4. Finally, do the real translation work.

Steps 1 to 3 are tedious and unpleasant. But the good news are that the computer can do it for you!. There are tools that helps to re-use the previous translations and to spot needed changes.

LenMus software is written with the wxWidgets application framework and follows wxWidgets approach to internationalization. This approach closely follows the GNU gettext package, based on using plain files 'message catalogues' ( PO files) containing the strings to translate.

PO files are plain text, so you can even translate them using a normal text editor, although I strongly un-recommend this option. The task is more comfortable and less error prone if you use a specific tool. There is a wide range of tools out there that can handle and manipulate PO files. I recommend that you use poEdit on Windows and Linux, or KBabel on Linux.

Apart of the PO files there is a need to translate one document: the "Study Guide" (file study-guide.htm). It is an HTML document, that is, it is a text file with tags. The work to do is that of translating a text document but taking very care of not removing/altering any mark-up.

You can do the translation by using any text editor, such as Wordpad. Please DO NOT USE a text processor, such as Microsoft Word, as it changes the document format in many bad ways. Better than using a text editor is to use a specialized program for HTML documents translation. One good free tool is OmegaT. It is a tool suitable for HTML and other formats. As 'translation memory' (that is, the mechanism used to store the translations and re-use them when a review is needed) it uses the TMX standard (TMX widely used by the industry and nearly all translation professional software is able to deal with this format). OmegaT seems to be an excellent choice for web translations and HTML pages.

Procedure: Steps to do the translation

1. Join the Translators mailing list and inform me

Join the translators mailing list, and post a message informing about the new translation you are going to do. To subscribe to the list use this link.

I will acknowledge your message and post you any available additional information, if it exists. By knowing that you are going to do a new translation I will have also time to review the files to translate, if needed, to ensure that you start with the good ones!

2. Download the language pack

In LenMus, both the program strings and the books content are translated by using PO files. There is a PO file for each book and two additional PO files for program strings. You will find all the necessary files in the language pack containing all the PO files to translate. Please do the following:

  1. Download the language pack from Sourceforge downloads (this link). For a new translation download pack "pack_n.n_xx.zip"
  2. Unzip the downloaded archive.

If you have any problem with the download, then please post a message to the translators list and I will send the file to you.

When unzipping the language pack you will find the following content:

  • Two PO files for program strings:
    • lenmus_xx.po
    • wxmidi_xx.po
  • Four additional PO files for the books:
    • GeneralExercises_xx.po
    • L1_MusicReading_xx.po
    • L2_MusicReading_xx.po
    • TheoryHarmony_xx.po
  • One HTML document: the "Study Guide" (study-guide.htm)

3. Rename the files

The name of program PO files must include the ISO 639-1 code for the language. So first thing to do is to change its name by replacing '_xx' by the ISO code of the new language (use lower case, please). For example, assuming your are translating lenmus to Spanish (ISO language code 'es') you should replace '_xx' by '_es', thus 'lenmus_xx.po' will be renamed as 'lenmus_es.po'. A list of ISO 639-1 language codes can be found here .

In certain languages there are variations from one country to another. In these cases, you can add two more characters (upper case) to specify the country. For example, language code '_es_ES' refers to the Spanish language spoken in Spain, and '_es_AR' refers to the Spanish language spoken in Argentina. This two letter country code is the ISO 3166 country code. It must be upper case.

But let's be practical. It is better to have as few translations as possible that cover as many languages as possible. Please keep in mind that maintaining a translation involves a lot of work. I would not be very happy at having to maintain a (de_CH) Swiss German, (de_AT) Austrian German and (de_DE) German German translation, unless there are truly committed translators to keep these translations alive. But if it's really necessary because the local variations are really important, sure go ahead.

4. Do translation: tips & tricks

Now translate each .po file and provide a translation for each string using poEdit. If you are not sure with one or the other translation, mark it as fuzzy. You can enter a comment in poEdit to give some information about your thoughts to other translators. If you are not sure about the meaning of the original sentence post a message to the translators list and you will get more information.

To include a translation into the next LenMus release, at least the following files must be translated:

  • lenmus_xx.po
  • wxmidi_xx.po
  • GeneralExercises_xx.po
  • study-guide.htm

The first one (lenmus_xx.po) is the longest and the two last ones are very short. I recommend you not to start translating files:

  • L1_MusicReading_xx.po
  • L2_MusicReading_xx.po
  • TheoryHarmony_xx.po

until the previous ones are ready.

File wxmidi_xx.po contains, mainly, the names of the 128 standard MIDI musical instruments. Probably you will be able to find somewhere, in Internet, this list in your language. This would save you some time in translation.

In strings to be translated you will find characters that have special meaning. Watch out for the following:

  • In some strings you will find 'substitution marks' such as '%s', '%d' or '\n'. These represent places to include some data. They must be preserved in the translated string. Otherwise a compilation error will occur. As a special case, you will have to translate the following strings: 'c%d', 'd%d', 'e%d', ... 'a%d'. Please note that these strings represent the names of the notes followed by the substitution mark '%d'. So, for example, its translation in Spanish should be 'Do%d', 'Re%d', 'Mi%d', etc.
  • Special characters such as quotes must be "escaped" (i.e. preceded with a backslash), if you want to use them as part of the text.
  • The "&" character normally used to mark an "accelerator key", i.e. a letter which in combination with Ctrl (on PC keyboards) will execute the command; i.e. Ctrl + O for "Open file". You have to make sure that the same letter is not marked twice within one menu. The & can be placed before any letter, such us in 'Open s&pecial file'. In your translation, you should put the & before a suitable mnemonic letter for the menu function represented by the string, so that the chosen letter does not repeats in the same menu or submenu.
  • Try to keep your translated string approximately the same size than the original. These is specially important in short strings used as labels for menus, buttons, etc. Otherwise, the translation might be too wide for the allocated space and the translated text will be cut off. If you find cases were the geometry of the offending buttons, menus, boxes, etc. is too short for the translation, please keep your translation and tell us by posting a message to the translators list, to create a new bug report.

For any problem you might have, please post a message to the translators list. Please, do not just leave the problem unmentioned. Thank you.

5. Send me your translation

When you are finished, send me your translated files. I will review your translation; if there are problems, I will contact you to get them resolved. When everything is working your translation will be committed to the source code repository. From that moment on, your language will be available in the development repository for testing. And it will become part of the next official release. I will also put your name on the list of contributors.

When the next release is approaching, I notify to the lenmus-translators mail list, to give you a chance to update the translation with any new/changed strings.

How to get help

If you need further assistance, feel free to ask for help on the LenMus translators mailing list.

 

Thank you in advance for your help and for helping others to use LenMus.

Last updated: 2012/11/03