- 1 Introduction
- 2 Localizing MediaMonkey-specific Strings
- 3 Translating the Welcome Page, Online Help, and Readme
- 4 Localizing Inno Setup
- 5 Translating the Website
- 6 When You're Done
Localizing MediaMonkey involves localizing strings that appear within the application (the UI and context-sensitive help) and the installer (may be necessary for some languages). Additional localization of the Online help, and readme, Product description and basic Web template is also possible, but may be more than most would be willing to take on.
Localizing MediaMonkey-specific Strings
We use localization software to help translate the strings that appear inside MediaMonkey, including menus, buttons, and dialog boxes. All of the user visible strings are extracted from MediaMonkey source code and placed into several "message catalog" .po files. The localization software allows you to translate the strings in this file, and create new foreign language message catalogs (.po files). To get started:
1) Download the catalog files from:
- MediaMonkey 4: http://www.mediamonkey.com/contrib/localization/localization_catalog.zip
- MediaMonkey 3: http://www.mediamonkey.com/contrib/localization/localization_catalog_3.1.zip
It contains the following:
\Version.txt -version of the source files (important!) \Language.po -language info (english) \Default.po -application strings (english) \Default.isl -innosetup installer strings \Install.po -MediaMonkey installer strings (english) \Tips.po -tooltips strings (english) [NOT USED IN MM4] \DB.po -strings within DB \context.po -context-sensitive help strings
2) If you're going to update an existing translation, also download the existing translation from: http://www.mediamonkey.com/contrib/localization/localization_languages.zip . It contains one directory for each language e.g.:
\CS\language.po -the next four are the Czech message catalog \CS\default.po \CS\install.po \CS\tips.po [only for MM3] \CS\version.txt -indicates the version of the translation based on the catalog source used as the source \%languages%\.... -message catalogs for other foreign languages
3) Install the latest version of poedit. See: http://poedit.sourceforge.net/index.php
Note: There's a new String Translator tool called 'Gorm' that is supposed to be quite good (we've not yet tested it). If you wish to give it a try instead, you can find information about it at: http://compaspascal.blogspot.com/2008/11/new-po-file-editor-gorm.html
Translating to a New Language
The localization process for translating to a new language is fairly simple:
4) Use poedit to edit each of the source files, by double-clicking on each .po file.
- Translate default.po (application text), install.po (installer text), tips.po (tooltips text), context.po (context help), and DB.po (database text)
- For the language.po file, simply 'translate' language to the name of the languge to which the files are being translated (e.g. if you're translating to french, translate 'language' to 'Francais')
IMPORTANT: Strings involved in Mask Settings should not have a '-' as this will affect the manner in which the mask is parsed.
5) Click 'Save as...' to save each file after editing it. Save it to a new directory \%Language% where %Language% is the 2-letter code for the language as defined at http://www.unicode.org/unicode/onlinedat/languages.html . When saving each .po file, an .mo file will be generated (these are the files that MediaMonkey uses to localize the interface). See poedit Tips (below) if you get an error.
Editing an Existing Translation
If .po files have already been created for a particular language, the process is slightly different, since if the English language source .po file is newer than the foreign language .po file, you'll need first update the foreign language .po file with any changes that have been made to the newer English version. This will have the effect of updating the English sources in the foreign .po file so that any new/changed strings will be highlighted for translation.
4) Update the foreign .po files if necessary by following procedure a) OR b) for each of the .po files (except for language.po):
- a) In poedit, open the foreign language .po file you want to edit and click Catalog|Update from POT file.
- In the Open Catalog Template dialog that appears, change Files Types: *.POT to ALL Files, so that the dialog is capable of showing the English language source files.
- Select the English language .PO file associated with the foreign language .PO file you are editing (e.g. if editing /Languages/CS/default.po, select /default.po from the English source files)
- b) Go to the command line and switch to the root directory (which contains the English .po file) and then type: msgmerge -U %LANGUAGE%\default.po default.po and then do the same for the other catalogs.
5) Use poedit to edit each of the .po files (except for language.po). You can do so by simply double-clicking on each .po file in the /%Language% directory where %Language% is the language you wish to edit. If you've updated the .po files (step 3 above) you'll also probably notice that there are several new untranslated strings, as well as some strings that are tagged as 'fuzzy' due to changes to the original English string. These are the strings that you'll need to translate, though you might want to review others for consistency.
6) Save the .po files, overwriting the original ones with the updates. See poedit Tips (below) if you get an error.
Testing Your Translation and Assigning a Version Number
7) After all the .po files have been edited and saved, you'll want to test them out. Make sure that the \%Language% directory containing your .po files contains an \LC_MESSAGES subdirectory that contains all of the associated .mo files. If it doesn't, create the subdirectory, and move the .mo files to it. Then copy the \%Language% directory and its contents to the following locations:
- MediaMonkey 3: \Program Files\MediaMonkey\Locale\
- MediaMonkey 4: \ProgramData\MediaMonkey\Locale or \Users\All Users\MediaMonkey (depending on OS. Note that \Users\All Users\MediaMonkey may be hidden in which case you'll have to type the path in the navigation bar--you won't be able to browse to it.
Run MediaMonkey, and go to Tools|Options|General. The Language option should now show the newly created language. Select it and then restart MediaMonkey for the configuration change to take effect, and you can then verify that everything works as expected.
Note that you won't be able to test the install.po file--this has to be packaged directly into the installer by the developers.
8) Once you're satisfied with your translation, update the version.txt file with the translation version number as follows: MediaMonkey major string version number.MediaMonkey minor string version number.MediaMonkey string build number.Translation build number (sequential)
e.g. for MediaMonkey source strings from 188.8.131.525, if the last set of German translation files were 3.2.1294.4, then the new translation would be version 4.0.1375.5.
Tips about POEDIT
- You shouldn't have to change any of the poedit default settings
- Some people have received error messages when trying to SAVE a .po file. The error is similar to:
- field `Project-Id-Version' still has initial default value
- msgfmt: found 1 fatal error
- To get around this, replace the entry:
- msgstr "Project-Id-Version: PACKAGE VERSION\n"
- Project-Id-Version: MediaMonkey 2.2\n
- This can be configured via Catalog > Settings > Project Info
- '&' is used to modify menu shorcuts that are accessed via alt-key combinations. e.g. changing &file to f&ichier causes the expected text change, but also changes the command from alt-f to alt-i. This allows the translator to modify menu shortcuts along with text. Note that only existing menu shortcuts are localizable in this manner. Other shortcuts cannot be redefined. If you want the ampersand ('&') character to appear as within a string, use &&
- \"text\" is used to place quotes around the text in question.
- Some strings will have extra (and apparently needless) spaces within them. These spaces may be used for formatting/alignment purposes. Generally, they should be preserved in the translation.
- Some strings will have variables within them. For example:
- a) Preparing track %d of %d (%s) -- When translating such string make certain to leave the variables and the order of the variables intact.
- b) Copying file $src$ to $dest$ -- When translating such strings, make certain to leave the variables intact. In these cases, though, the order of the variables may be changed.
- Some people have received error messages when trying to update a .po file with new english source strings. The error is similar to:
C:\Documents and Settings\Fra\Documenti\Ricerche e lavori\Traduzione MM3\IT\context.po:432:159: invalid control sequence
- C:\Documents and Settings\Fra\Documenti\Ricerche e lavori\Traduzione MM3\IT\context.po:432:171: invalid control sequence
- msgfmt: found 2 fatal errors
- This can be caused if certain characters in the translated .po file have been changed e.g. if '\\' was changed to '\'. To fix this:
- a) Close poedit, and backup the problematic .po file. Open it in a text editor (you can change the extension to xxx.po.txt if needed)
- b) In the text editor, go to e.g. Row 432 Column 159, and manually correct the file and then save it.
- c) Rename it back to xxx.po. You should be back in business
- translated fields appear in white--you can also tag a field as translated 'fuzzily' (i.e. it needs more work) by clicking the 'ghost' button
For more information, see the poedit online help.
Translating the Welcome Page, Online Help, and Readme
9) There are several other items that can be optionally translated, including the Welcome Page, Help Content and readme:
- The Welcome Page appears when MediaMonkey is first run. It can be translated by editing welcome.txt with a text editor.
- The help content for MediaMonkey v4 is online and available at: http://www.mediamonkey.com/wiki/index.php/WebHelp:Content/4.0 . If you'd like to translate it to a new language that isn't yet listed on the wiki, let us know and we'll set up a template so that you can do so online.
- The readme is installed to C:\Program Files\MediaMonkey3\readme.txt . You can translate with a basic text editor.
Localizing Inno Setup
10) MediaMonkey currently uses a third-party installer called Inno Setup. Inno Setup is available in numerous versions and in numerous languages so usually nothing needs to be done. For new translations, to ensure that the entire MediaMonkey product is translated consistently, please:
- a) Recommend which translation file to use (since multiple files exist for many languages). See: http://www.jrsoftware.org/files/istrans/
- b) If no installer translation has been made for version 5.4.2 of Inno Setup, please update the existing Inno Setup translation so that it reflects the strings that are used in Inno Setup version 5.4.2. This can be done using the tool located at: http://www2.arnes.si/~sopjsimo/translator.html in conjunction with the English source files Default.isl (included in mm-local.zip) and the translation file chosen in step 8a). Please submit the changes to the innosetup team so that future updates to innosetup include the improvements you've made.
Translating the Website
11) If you'd like to help expose MediaMonkey to your part of the world, you can edit the following web page http://www.mediamonkey.com/language/template/ . To create a localized web page:
- Download the following template: http://www.mediamonkey.com/contrib/localization/web-template.zip
- Open each of the two files contained within in a text editor.
- Translate the content making certain to not change anything other than the template text.
12) You can also optionally translate the following MediaMonkey Descriptions that are at:
Also, just an fyi, here's a really useful tool for translating Web pages that let's you avoid having to deal with any html editing issues (note that this is now shareware): http://www.stormdance.net/software/catscradle/overview.htm
When You're Done
13) Once you've verified your translation (note that you can't verify installer.po, or innosetup.isl, zip up the directory containing the .po/.mo/.isl/.txt/.php files that you've generated and send them to: email@example.com .