wiki:TranslationGuide

Making a Translation

I decided to opt for Subversion as the means of managing these files over an earlier idea of using a wiki page per language. The reason for this is due to the way the files themselves will change inclemently and a wiki page would have quickly become very unwieldy. Unfortunately this does mean the any translators will need to use SVN too. However, anyone who doesn't want to go to that difficultly can get in touch with me through email.

For those happy to use the SVN setup let me explain how to use it. To get write access to the lang folder you need to use the user name and password. To try and avoid casual spam these won't be posted but are available upon request, just send me a mail.

Using SVN commandline

In many ways the commandline svn approach is the easiest to explain. To login in for the first time cd the a desired working directory and issue the command

svn checkout svn://svn.geekisp.com/halite/lang

That should download all the language files. Now if there isn't already a translation for language make a copy of the Template.txt file renamed appropriately. Then add this file to the local repository with the command

svn add ./lang/NewLang.txt

In future you won't need to perform these two steps, instead you need only cd to your local working directory and issue the command

svn update

I would recommend always updating your local repo in case someone else has modified your translation file since you last updated it.

Finally after you've made changes you can commit them back to the online repository with the simple command

svn commit ./lang --username the_user_name --message "Some message just needed for the logs."

You'll also be asked for the password at this point.

Using RapidSVN

Alternatively I'd recommend RapidSVN as an easy to use GUI to Subversion. When you fire it goto 'Bookmmarks' >> 'Add existing repository' and use the URL  svn://svn.geekisp.com/halite.

The File Format

The language files are the .TXT files. So if you want to contribute a translation download the Template.txt file and rename it to your language. When naming the file try to stick to non-unicode file names, inside the files you can of course use unicode as necessary. Note the files should be saved as UTF-8 with no byte order mark. The template file should already be in the correct format so you probably will not need to worry about this point.

The file will look something like this-

"English" --->  ???
"MS Shell Dlg" --->  ???
"Torrent" --->  ???
"Tracker" --->  ???
"" --->  ???
"msctls_progress32" --->  ???
"N/A" --->  ???

Replace the '???'s with your translations, any you don't add will remain in English. This can be an incremental process, half translated files will work, they'll just still contain some English text. Also note that not all strings should be translated, for example "msctls_progress32" needs to remain as it is. In future I'll screen those bits of text out to avoid any confusion but for the moment if you do translate something which needed to remain unchanged I can fix that so it's no problem. So for example you might end up with a file like the following-

"English" --->  "1337"
"MS Shell Dlg" --->  ???
"Torrent" ---> "70|2|23n7"
"Tracker" ---> "7|24CK3|2"
"" --->  ???
"msctls_progress32" --->  ???
"N/A" ---> "N/4"

Also note that the very first string "English" should be set to the language name, here you can use unicode and this name is that the UI will use when presenting a list of language options to users. If you run into any troubles committing these files back onto the repository send them to me in an email and I'll do it.

Testing a Translation on the fly

Being able to test translations in the GUI while they are being worked on is something many have requested. The translation file are parsed into  .RC script files which are compiled into DLLs. This means that in order to test a translation you need to be able to generate that final DLL which Halite can use. I have tried to put together a small package to automate this whole process for non-developers.

Download and extract  archive. You will end up with two folders- res is a snapshot of the current Halite resource sourcecode and lang is a folder containing the current translations as well as some of the utilities needed to compile the translations into DLLs. Unfortunatly I can't really distribute all the necessary tools because to copyright issues and such. Thankfully the additional files necessary are freely available online.

What you need is the MS resource compiler, rc.exe, the linker link.exe, a tiny tool cvtres.exe and their support DLLs. These are available from a number of locations of which I'll list two here.

The smallest download containing these files which I'm aware of is the  Masm32 package for writing 32bit windows assembly programs. If you download that package you can open it in an archive manager like 7zip (i.e. you don't need to install it if you don't wish to). Browse to the bin folder and copy the following files into the lang folder- rc.exe, rcdll.dll, cvtres.exe, link.exe and mspdb50.dll.

Alternatively you can get the files from the Express edition of VC++. The files you want in that case would be rc.exe, rcdll.dll, cvtres.exe, link.exe and mspdb80.dll.

Compiling a DLL

To compile a DLL fire up you command prompt and navigate to the lang directory. In there you can use the batch file convert to compile the DLLS. The first argument to the batch file should be Halite (i.e. the name of the template .RC file in the res directory) followed by a list of language names. For example the following command should create the German and Russian DLLs.

convert.bat Halite German Russian

Copy those DLLs to the same for as the Halite EXE and they should be automatically picked up by Halite when you go into the options.

Gotcha's

This is all very hacked together so there are probably more than a few things that will go wrong. If you run into difficulties post on the forum and hopefully we'll get them sorted out.

Finally, a Big Thanks

Let me just say thanks to anyone and everyone who volunteers to do a translation, it's very much appreciated. I will put together a proper page to acknowledge everyone's input, it's the least I can do.