TRANSLATIONS - A QUICK HOWTO

This is a short memo for translators and/or translators-to-be.

NOTE: Translators: if you use different parameter positioning as described in (2), please let
me know the places where you used that, because glib g_strdup_printf() can't handle positional
parameters so I'll have to replace these calls with a snprintf() then.


The following questions will be answered:
(1) HOW DOES THIS WHOLE TRANSLATION THING WORK? -----
(2) I WANT TO TRANSLATE THE GUI INTO MY LANGUAGE. HOW DO I DO THAT? -----
(3) I AM A TRANSLATOR. THE SOURCE CODE HAS CHANGED AND THERE ARE NEW STRINGS. WHAT TO DO? -----
(4) WHERE DO I GET CREDIT FOR THE TRANSLATION?

----- HOW DOES THIS WHOLE TRANSLATION THING WORK? -----

It's quite easy: There are these .po files, which are basically textfiles in a certain
format that contain all the original strings in English and the translated strings.
When the GUI source code is compiled with 'make' these .po translation files are
converted into more efficient machine-readable binary translation files (.gmo files).
These binary translation files are then installed on your system when 'make install' is run.

When the GUI is run the first thing that is checked is what the current 'locale' is
(=language and country settings). Then the GUI checks if there is a translation file
installed for that language, and if yes, then it is being used. Voila :)




----- I WANT TO TRANSLATE THE GUI INTO MY LANGUAGE. HOW DO I DO THAT? -----

First, you'll need some time to do that :)
Then, you should learn how to check out the very latest version of the source code
from the CVS repository. It's quite easy. The instructions for that are on the
GUI downloads page: http://ed2k-gtk-gui.sf.net/download.html

Now that you've checked out the latest source code, change into the po/ directory.

There you will find a file called ed2k_gui.pot. This is the translation 'template'. It
contains all the strings that need to be translated, but no translations.

Look up the two-letter language code of your language here:

http://www.gnu.org/manual/gettext/html_chapter/gettext_15.html

Let's assume you want to make a translation into Russian, then the language code is 'ru'.

Make a copy of the ed2k_gui.pot file in the po/ directory and call it ru.po

Now you can start filling in the translations into the ru.po file. You _can_ do this with
any normal text editor. However, I strongly advise you to use the program
KBabel (http://i18n.kde.org/tools/kbabel/) or a similar tool to do the translation.

If you choose to do it with a text editor, do it like this:
First, you will find that the ru.po file contains lines like this:

#: about_page.c:78
msgid "GUI: closing connection (socket) to core...\n"
msgstr ""

The first line tells you where the string comes from, so you know the context.
The 'msgid' line contains the English string and must not be changed. The
'msgstr' line is where you fill in the translation. Note that these are all
equivalent lines:

msgstr "aabbccdd"

is the same as

msgstr ""
"aabbccdd"

or

msgstr ""
"aa"
"bbcc"
"dd"


Now, the following points are important:

(1) Some strings are printf-function strings and will contain variables and/or special
characters. Here is their meaning:
%s		- a string
%20s	- a string, but don't print more than 20 characters
%d		- a signed integer number
%u		- an unsigned integer number
\n		- new line
\t		- tab

You MUST NOT change the order of any variables in the string, or leave them out!
If you need to change the order of two variables for grammatical reasons, you will
need to do it like this:

Original:	"%u apples cost %u dollars.\n"
New:		"%2$u dollars is the price of %1$u apples.\n"

(2)
Make sure you keep all 'new line' characters ('\n') and all spaces. They are probably there
for a reason. Well, you'll see how it looks in the end. You don't _have_ to keep them, but
if you leave them out it's likely that things will look messay ;)

That's it.

If you're finished, send me the ru.po file by e-mail. Or, if you know how CVS on
sourceforge works and you have a sourceforge account, let me know your sourceforge
username, so I can add you to the team, then you can check in your changes to the CVS
yourself.



----- I AM A TRANSLATOR. THE SOURCE CODE HAS CHANGED AND THERE ARE NEW STRINGS. WHAT TO DO? -----

First, update your whole CVS repository to make sure you have the latest version of the
source code with all the latest messages. Then change into the po/ directory.
There, run the script

./make_ed2k_gui_pot.sh

This will produce an up-to-date 'ed2k_gui.pot' file including the new messages to translate.

Now, merge these new messages into your existing translation file (e.g. de.po) with:

./merge_pot_with_po.sh de.po

This will produce a new de.pot file which contains your old translations and the new strings.
Check if the output is okay and nothing is screwed up. The new file should be bigger than the
old file as well... If everything looks okay, rename the file de.pot to de.po and fill in the
additional translations for the new strings.

When you're done, send me the new de.po file by mail or check it into CVS yourself if you are
part of the development team.



----- WHERE DO I GET CREDIT FOR THE TRANSLATION? -----

First of all, your name will be mentioned in the AUTHORS file in the GUI source code. If it
doesn't show up there, remind me about it.

Then, you should insert your name at the very beginning of the .po file as 'initial'
translator.

Finally, among the status_page.c strings look for the welcome message that is printed in the
status window when the GUI is started up. At the end of that message, just add a line like
'Russian translation by <your name>.' or something similar to your liking :)




