Translation Guide for winLAME
-----------------------------

This file describes how to translate winLAME into other languages. Since
winLAME 2009 it is possible to provide the winLAME author with a translation
for your native language. Note that you must provide translation under the
Creative Commons Attribution Share Alike license. See here for more:
   http://creativecommons.org/about/licenses/


* Prerequisites

This guide expects that you have a version of Microsoft Visual Studio 2005,
2008 or the Express variants of Visual Studio installed. Without this
installed, you can't try out your translation in winLAME directly.


* Getting the project files

You first have to check out the winLAME sources from CVS. Alternatively you
could download the last released source code zip file.

To get the latest sources, use the instructions on this page to do a CVS
checkout:
  http://sourceforge.net/scm/?type=cvs&group_id=21193

You can use TortoiseCVS to conveniently get the sources.

To get the latest released source code zip file, go to this page:
  http://sourceforge.net/project/showfiles.php?group_id=21193&package_id=15027

Unzip all files to a working folder.


* Creating a project

Go to the winLAME's "source" folder.

Make a copy of the template .vcproj file named "winlame_resXXXX.vcproj".
Replace the XXXX with the language code id (LCID) of your language. The
language code ids supported by Windows are listed in this Knowledge Base
article:
   http://support.microsoft.com/kb/221435

You need to use the second listed hexadecimal value, e.g. german would be
0407, english would be 0409, spanish would be 0c0a.

Open the .vcproj file with an editor, e.g. notepad, and replace all
appearances of XXXX with the language code id you selected.

Go to the winLAME's "source\winlame" folder.

Make a copy of the file winlame.rc and name it winlame.XXXX.rc (where XXXX
again is replaced with the language code id.

If you want to translate the about page, too, go to the source\winlame\res
folder and copy about.html to about.XXXX.html


* Translating text

Let's start with translating winlame.XXXX.rc, where all dialogs and text
strings are located. Translate all text strings inside double quotes (").
Don't translate "MS Shell Dlg" (as it's a font name) and paths to filenames,
e.g. "res\\help.bmp". Don't translate the VERSIONINFO block.

Note that there may be special characters that you must not translate, e.g.
"%s" or "%02u:%02u" (these are placeholders for text or numbers). In dialog
and menu resources the ampersand character (&) may appear before or inside
strings. This marks the character after it that is used for Alt+character
shortcuts. Note that every character in a dialog may only be used once. Try to
use simple characters for shortcuts, e.g. the first letter of the item and try
not to use complicated to type characters.

Finally put the english name of your language in the IDS_LANG_ENGLISH string,
and the local name of the language in IDS_LANG_NATIVE. If you are unsure about
anything in the translation process, just write an email and ask the
project administrator (that's me!).

When translation strings contain non-ASCII charactesr, try to save the file as
UTF-8. You can do this using notepad, just do a Save-As and select UTF-8 as
the format.

When also translating the about html page, make sure to not translate the
keywords between percent (%) characters, e.g. %winlamever%. You are free to
replace the "English translation (c) ..." text.


* Compiling the resource file

Open the .vcproj file, choose the "Release" configuration and use
"Build | Build Solution" to build the resource file. It should appear in the
folder "output\release". Copy it over to your winLAME installation or copy the
installed files over to your "release" folder.

When winLAME starts the first time, it tries to choose a language appropriate
to the language settings of the currently logged in user. The choice of the
current language is stored in the registry key
"HKEY_CURRENT_USER\Software\winLAME\LanguageId". When you delete that key, the
appropriate language is chosen again. This way you can test if your language
translation appears by default for users with the proper language settings. If
it doesn't work, you may have chosen the wrong language code id.

The generated language should also appear in the Options dialog reachable from
the winLAME icon menu.


* Sending translated files

Just send the translated files to the project manager, so that the files can
be checked into CVS. Note that you must provide translation under the
Creative Commons Attribution Share Alike license. See here for more:
   http://creativecommons.org/about/licenses/

Happy Translating!
