--------------------------------------------------

   TRANSLATION HOWTO for X-CD-Roast 0.98alpha14

 27.05.2003 Thomas Niederreiter <tn@xcdroast.org>

--------------------------------------------------


Whats this?
-----------

Starting with release 0.98alpha11 X-CD-Roast uses the widely
common translation package "GNU gettext". The old method of
translation is no longer supported and obsolete. 

This document describes how to do translations for X-CD-Roast and
points out the differences from the old system.

If you are familiar with gettext you probably don't need any more 
information. X-CD-Roast does it now the same way as almost all 
other internationalized open source software.

If you have a partly translated language file, which you had not
sent me yet, don't worry. Just send it to me and I will convert the
old format into the new gettext format. I will send it back to you
and you can continue using gettext.

The old concept of "language-ids" does not exist any longer - each
translation sits in its own file.

 
Introduction:
-------------

X-CD-Roast 0.98 allows easy internationalization of all its
texts. All it needs is somebody who is doing the translation.

If you want to be an official X-CD-Roast language-maintainer 
please contact me. I have to coordinate all your efforts - it would
be quite stupid to have more then one person working on a certain
translation without knowing about each other.

So - if you have contacted me and I have agreed you to be a 
language-maintainer you can start your work.

There are some issues with translations in general. First of all you
must know about locales - each country got a locale like "de_DE" for 
Germany. You have to set your operating system to a certain locale
in order to have X-CD-Roast working correctly with that language.
The locale got the information about charsets and the fonts to use.

X-CD-Roast allows in the setup to switch a locale/language on-the-fly.
This does not work very well, when you switch to a locale that requires
another charset or font. In this case you will get a lot of display
problems and its therefore only for the adventurous user. 

To correcly switch between languages you set the "LANG" or "LC_ALL"
environment variable to a given locale before you start X-CD-Roast. 
This ensures that the correct fonts will be loaded. 

Some background about Unix locales is offered here:

	http://www.in-ulm.de/~mascheck/locale

Some example:

To set your locale to german: 

	"export LANG=de_DE" 	(depends on your shell)

If you get a "Gdk-WARNING **: locale not supported by C library" when
you start X-CD-Roast then you don't have support for this locale on 
your system. This means (among other things) that your system does not 
know which fonts belong to that language. In this case you have to 
update your system or try to install support for this locale. 
See your system documentation about this.


GNU gettext:
------------

A very detailed description about gettext can be found in its
documentation:

	http://www.gnu.org/manual/gettext/ 

Here I offer a quick summary of things a translator has to know.
For details please always refer to the real documentation.


First of all - in order to do a translation you have to install the
source of X-CD-Roast. It's not possible to do the work on a RPM
installed version. Also you must have installed the gettext package, 
because its tools are required to build the language catalogues.

After you installed the source you have to run ./configure once to
create all the makefiles. If you have previously installed the RPM
version, you should use this command to recreate the same environment
as the RPM used.

	./configure --prefix=/usr --sysconfdir /etc --mandir=/usr/share/man

Now you can change into the "po" directory of the X-CD-Roast source
tree. This directory contains all the translations. 
For each translation you see two files. One ending in .po and one ending
in .gmo. The .gmo-files are created from the .po-files automatically and
contains a compiled message catalog. The .po files are human readable and
you edit them to create/update a translation.


Basic .po file format:
----------------------

.po files are human-editable text files.  A comment is begun by a '#'
character in the first column, and extends until the end of the line.
Comment lines are also used by gettext's programs to indicate special
"flags" and useful information.

All .po files contain "entries", one entry for each string to be
translated.  Entries should be separated from each other by a single
blank line.

A typical entry looks like:

	#: src/create.c:3366
	#, c-format
	msgid "Error writing file %s"
	msgstr "Fehler beim Schreiben von %s"

The first line of the entry, which begins "#:", is a list of all the
places in the source code that contains the string being translated.
There may be several of these lines.

The second line, which begins "#,", contains "flags".  The flags line
is not always present.  In this case a single flag (", c-format") is
specified -- this means that the string being translated is a C format
string.

The third line, which begins "msgid", is the English-language string
being translated.  It may span more than one line, as in:

	msgid ""
	"There is an empty CD-R/RW in the drive.\n"
	"Additional sessions cannot be written on\n"
	"unwritten media."

The fourth line, which begins "msgstr", is the translated string.  It
may span more than one line, as in:

	msgstr ""
	"Es ist ein leerer CD-Rohling im Laufwerk.\n"
	"Weitere Sessions können nur auf einem bereits\n"
	"teilweise beschriebenen Rohling erstellt werden."


Update an existing language file:
---------------------------------

To continue work on a existing language file (.po) is quite easy.
Basically you just enter it with a text-editor and look for untranslated
strings (Empty msgstr texts).

Because it can be hard to find the untranslated messages in the big po
files, you can use several tools to help you there. You can use 
"kbabel" or "gtranslator" if you want a graphical po file editor. These
help a lot to make the update process easier.

You fill then the missing parts with your translation. Please be sure
to try to keep your translations short and to keep all C-format strings
(like %d, %s or \n) intact! 

You will also notice that there are a lot of texts marked with the "fuzzy"
flag. This is an entry that was a close, but not exact match. Fuzzy
entries are *not* translated by 'msgfmt' (the program that takes your
'.po' file, and generates the run-time '.gmo' file).  So, you need to
look for "fuzzy"s, make sure the translation is still correct, and then
delete the ", fuzzy" flag for the entry (or, the whole "#, fuzzy" line,
if that is the only flag on the line).

When you filled in all the empty translations and looked through all
fuzzy entries you are finished. Type "make" and it will automatically
compile you new translation texts. Watch for error-messages and correct them
accordingly. 

After a "make install" in the po-directory you can startup X-CD-Roast to
verify your work. Check for string-length and display problems. 

Create a tar file from your .po file and send it to me. Thanks!


Create a new translation:
-------------------------

If you want to create a translation which is not already (partly) done, 
you have to start from scratch. First determine the correct locale-string
for that language. 
Copy the xcdroast.pot file to a new file with the name of your locale.
e.g. to create the german translation I used that command:

	cp xcdroast.pot de.po

Add now the new translation filename to the "LINGUAS" file in the same
directory. Just edit the file and you will see how it should look.

Now comes all the work. Edit your new '.po' file by filling all the 
empty texts. Be sure to fill all the values in the header with
correct values. Most important here are the Language-Team and the 
Content-Type where the charset is defined.

Please be sure to try to keep your translations short and to keep 
all C-format strings (like %d, %s or \n) intact! 

Type "make" to compile your translation and "make install" to install
it. If you set your LANG-environment varible to that locale you should
see your translation at startup of X-CD-Roast!  Please check for 
string-length and display problems. 

Create a tar file from your .po file and send it to me. Thanks!


The current translators/languages are:
--------------------------------------

id 0: English, Thomas Niederreiter <tn@xcdroast.org>

id 1: German, Thomas Niederreiter <tn@xcdroast.org>

id 2: Dutch, Edwin Hakkennes <E.Hakkennes@et.tudelft.nl>

id 3: Italian, Andrea di Lecce <dryu@octava.it>
	       Giuseppe Di Mauro <altosax@telemail.it>
               Roberto Rosselli Del Turco <rosselli@cisi.unito.it>
               Daniela Di Candia <ddicandia@gmx.net>
	
id 4: French, Sébastien Yapo <sebastien.yapo@free.fr> and
	      Ferdinand de Broich <firebird@chez.com> 
   
id 5: Croatian, Denis Pleic <dpleic@open.hr>

id 6: Swedish, Richard Torkar <ds98rito@thn.htu.se>
               Peter Karlsson <peter@softwolves.pp.se>

id 7: Danish, Lars Juul <larsjuul@mail.dk>

id 8: ?? Portuguese, Pedro Borges <pcb@mail.com>

id 9: Spanish, Jose Luis Benitez Crespo <jlbc@bigfoot.com> and
	       Jose Manuel Benitez Sanchez <J.M.Benitez@decsai.ugr.es>

id 10: Turkish: Alexander Neptun <alnep@gmx.net>

id 11: Estonian: Argo Vessmann <argo@ut.ee>,
	     	 Triin Hannust <specter@ut.ee> and
		 Ahti Akel <akel@stallion.ee>

id 12: Brasilian Portuguese: Till Kamppeter <Till.Kamppeter@uni-bayreuth.de>
		and Syndson Silva <syndson@telelistas.net>

id 13: Japanese, Takeyuki Fujioka <fujioka@bil.educ.fukushima-u.ac.jp> and
       Masaki Shinomiya <shino@pos.to>

id 14: Catalan, Pau Garcia i Quiles <pgq@poboxes.com>

id 15: Czech, Adam Pribyl <covex@io.pinknet.cz> 
 
id 16: Hungarian, Balázs Gál <gbalcsi@freemail.hu> and 
       		  Marton Dosa <dm_@freemail.hu> 
       		  (reworked by: Mihály Gyulai <misibacsi@ecomail.org>)
       		  (reworked again: Lajos Kósa <kosal@novonet.hu>)

id 17: ?? Romanian, Sandoiu Mihai <sandoiu_mihai@yahoo.com> 

id 18: Traditional Chinese, Chih-Wei Huang <cwhuang@linux.org.tw>

id 19: Simplified Chinese, Chih-Wei Huang <cwhuang@linux.org.tw>
		           Su Baochen <linuxman@sd163.net>

id 20: ?? Greek, Pancyber <pancyber@hotmail.com>

id 21: Norwegian, Stig Hornang <stig@rozinante.net>

id 22: Polish, Rafal Kura <jafal@usa.net> and 
	       Robert Gomulka <carramba@pf.pl>

id 23: Russian, Anthony Borisow <r2m@mail.ru> and
	 	Vitaly Lipatov <lav@altlinux.ru>

id 24: Slovak, Martin Petrák <petrak@frix.fri.utc.sk>

id 25: ?? Serbian, Dejan Dzodan <hobit@iname.com>

id 26: Indonesian, Didiet Wardhana Novianto <didet78@hotmail.com>

id 27: Bulgarian, Andrei Uzunov <andreiu@linuxmail.org> 

id 28: Galician, Xosé Anxo Pereira Torreiro <pereira@linux-gl.org>

id 29: ?? Euskera (Basque), Xabier Gońi <xabigoi@terra.es>

id 30: Finnish, Henry Palonen <henkka@yty.net>

id 31: ?? Malaysian, Ady R.Ahmad <adywarna@yahoo.com>

id 32: ?? Korean, BongShin Choi <tomboybs@hitel.net>,
		  Jeongdong Hwang <naondol@neowiz.com>

id 33: ?? Icelandic, John Paul <jonpall@juventus.is> 

id 34: Ukranian, Maxim Dzumanenko <mvd@mylinux.com.ua> 

id 35: Greek, Filippos Papadopoulos <csst9923@cs.uoi.gr>

id 36: Latvian, Imants Treidis. <buttonn01@yahoo.com>


If you are on this list and don't want to do any further translations,
please contact me so that I can find a new language maintainer.

Note: Entries marked with ?? are people that said they will make a 
      translation, but have never sent something to me. 

If you want to finish a translation started by someone else, please 
contact the old translator first. If he does not mind or does not
answer contact me and I will register you are new translator.


--

27.05.2003 Thomas Niederreiter <tn@xcdroast.org>

(parts of that document inspired by: 
 http://www.freeciv.org/notes/gettext-guide.txt)
