LenMus translation instructions

This guide is supposed to be a first start for translators. There are probably errors. Please tell me if you find errors. 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 available 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 nine files:

  • Two are for the LenMus program strings (visible strings, dialogues, message boxes, etc.) and the installer.
  • Next two are for the introduction page and the General Exercises eBook.
  • Three more, are for the other eBooks (one per eBook: L1_MusicReading, L2_MusicReading and TheoryHarmony)
  • Finally, two documents: the Score editor quick guide and the release news document.

To include a translation into LenMus, at least the first four files must be translated (the LenMus program strings, the introduction page and the General Exercises eBook). The time required to translate these four files should be less than 20 hours.

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 we 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. We recommend that you use poEdit on Windows and Linux, or KBabel on Linux.

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 eBooks content are translated by using PO files. There is a PO file for each eBook 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. Wait until I acknowledge your message in the translators list.

  2. Download the language pack from this link.
  3. Unzip the downloaded file.

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 package you will find the following content:

  • Two PO files for program strings:
    • lenmus_xx.po
    • wxmidi_xx.po
  • Five additional PO files for the eBooks:
    • intro_xx.po
    • GeneralExercises_xx.po
    • L1_MusicReading_xx.po
    • L2_MusicReading_xx.po
    • TheoryHarmony_xx.po

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
  • intro_xx.po

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 four 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. How to test your translation

When you have finished your translation, always re-read your file at least once to correct all meaning-, spelling-, grammar-, typo-, etc- mistakes.

Then, you should verify your translation using the LenMus program. To this, you need two things:

  • The MO files created by poEdit when saving the PO files. There are two kinds of message catalogues: the PO files, witch are source catalogues (text files) and the MO files, which are binary catalogues which have the extension .mo and are created from the PO files. The MO file is created automatically by poEdit when you save a PO file. Only the binary files (.mo) are needed during program execution, so you only need the message catalogues to run the lenmus program.
  • The MO file for wxWidgets library. Download the PO file for your language from here. Rename the wxwidgets PO files as 'wxwidgets_xx.po' (replace 'xx' by your language code, and country code if needed). Open it with poEdit and generate to MO file.
a) Testing program strings (GUI):

To test your translation, do the following (in following description replace LENMUS by the path to your LenMus installation, for instance "c:\Program files\LenMus4.0"):

  1. In folder 'LENMUS\locale' create subfolder 'xx' for your language: 'LENMUS\locale\xx'.
  2. Put wxwidgets_xx.mo, lenmus_xx.mo and wxmidi_xx.mo in this new subfolder 'LENMUS\locale\xx'.
  3. Now, execute the lenmus program and choose menu 'Options > Preferences'. In the 'language' section the new language must appear. Choose it and close the dialog.
  4. Close the program and re-start it. It should be now in your language, using your translation. Please, use the program extensively and try to verify the translation in all possible dialogs and places. Thank you.
b) Testing eBooks

Testing an eBook translation is more complex.

LenMus eBooks are written in English, using the XML format. The source XML eBook is compiled by using our program 'LangTool', that generates the LMB compiled eBook format used by LenMus. For translation, LangTool relies on PO files containing the translations for all strings in the eBook. LangTool is also used to generate a PO file from the source XML eBook.

To test a translation, once the PO file is ready it is necessary to use this file to process the eBook and generate the compiled eBook. Therefore, when you have translated one eBook you will have to send me back the translated PO file and I will send you, next day, the translated eBook (file .lmb) for verification and checking your translation.

Once you have received the LMB files, do the following (in following description, again replace LENMUS by the path to your LenMus installation, for instance "c:\Program files\LenMus4.0"):

  1. In folder 'LENMUS\books' create subfolder 'xx' for your language: 'LENMUS\books\xx'.
  2. Put the received eBook files (xxxxxxxxxx.lmb files) in this new subfolder 'LENMUS\locale\xx'.
  3. Now, execute the lenmus program in your language. The eBooks will be shown using your translation. Please, review the eBooks extensively and try to verify the translation in all pages. Thank you.

6. 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 SVN 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.

Additional files to translate

Apart of the PO files there is a need to translate two documents: the "release notes" document and the "editor quick reference guide". Both documents are HTML, that is, they are text files with tags. The work to do is that of translating a text document but taking very care of not removing/altering any mark-up.

Please consider translating also these two documents

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.

The two documents to translate can be downloaded from these links:

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: 2010/01/05