/---------------------------------------------------------\
| TRANSLATION HOWTO                                       |
|                                                         |
| X-CD-Roast 0.98                                         |
|                                                         |
| 18.96.2001 Thomas Niederreiter                          |
\---------------------------------------------------------/


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.

This file describes all you have to know.

First of all you might wonder why I don't use GNU gettext for this - 
well, as I started this I did not know very much about gettext and my
system is a lot easier to understand. It also allows on-the-fly switching
of languages while the program is running and you also need not to recompile
anything to update the language-files.

I am aware of the problems with missing fontset when switching manually
to another language - The needed font for your locale is loaded at startup
and when you change the language then there is no way for me to reload
the necessary fonts for the new language. 
So, when switching languages at runtime you have to expect problems with
the display of any special characters the new languages needs. 

The only sure way to switch languages is by setting the LANG, LC_ALL or
LC_MESSAGE environment variable to your languages before starting X-CD-Roast. 
By default X-CD-Roast will always check these enviroment variables to
determine which language (and fonts) should be loaded! When you override
this setting in setup by setting a fixed language you may run into
problems! Please test your translation only with the correct set locale!
This is also the only way to get multi-byte fontset working fine.

E.g. 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" 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.


The files:
----------

There are two files which contain all text-strings used by X-CD-Roast.
Both files are read once at startup of X-CD-Roast in memory. The first file
- lib/lang/language.def - contains all the texts of the menus and dialog-
boxes. The second - lib/lang/langhelp.def - contain only the bubble
(tooltip) online help.  

Beginning from version 0.98alpha4 X-CD-Roast does a little syntax-checking
of the language files at startup. So when you get a "sequence-warning" from
X-CD-Roast check if you did not mix up some language-ids or messages. 
 
The format:
-----------

The "language.def" file has a header, in which all used languages are
defined.
Comments are starting with a hash "#" as the first char on a line.

--
# Translation done by: tn
LANG_0: English; us, uk

# Translation done by: tn
LANG_1: Deutsch; de
--

These lines define which languages are available. Be sure to use exactly
the number here which I have assigned you. 

The next field is the name of your language. Best expressed in your own
language - so I wrote "Deutsch" instead of "German". Its the text that
is displayed in the setup-menu.
After the semicolon you can add your iso-language-codes. If you have more
than one you can seperate them by comma.
This codes are used to identify your language by looking the LANG or 
LC_MESSAGES enviroment-variables. This is required to load the correct fonts
for your locale. 


Next are the texts itself. First is always an id-number (message-id) which 
is defined by me. Then, seperated by the underscore, is the language-id. 
So, 0012_1 means: "Text Nr. 12", in "Language Nr. 1" (German). 
Also only change and add texts with your language-id! All other languages
are handled by someone else.


Things to consider:
-------------------

It's good to know that you should fill out all texts - if you don't provide
a translation there will be an automatic fallback to language 0
(english). With new releases of X-CD-Roast there always will be new
texts added - I do try not to change any old texts - so usually you don't
have to look through all old text-definition to see if something changed.
If I really have to change something in the older texts, I will contact
you by email. 
 
The text itself is in quotes - if you want to have quotes in the text itself
you can escape them with a backslash. e.g. (\").
You also can't break up a long line in several short - the line can be as
long as you want - as long it's a single line.

Several lines are used as format-strings by printf. In this case you must
be sure to include the format-chars like %d and %s on the correct positions.
 
Also keep in mind that space in the menus is very limited. Try not use much
longer translations than the original texts. If you are not sure start 
X-CD-Roast from time to time to check if your texts fit on the screen.

Some texts go over more than one line - dialog-windows for example.
These texts contain \n to mark where to break long lines. Please see
where I used \n in my texts and try to use them also correctly.

You can use special chars of your language - as long X-CD-Roast (or GTK)
can display them and your system has support for this locale. 
You also need to have a text-editor which allows you to enter such
chars - I can't give you a hint here...my German keyboard is fully 
supported by my RedHat-distribution and allowed me to enter the umlauts
directly.

The "langhelp.def" file is the same as the "language.def" - you can just
leave the header away, because automatically the one from the "language.def"
is used. Because these texts are only used in the bubble-help of GTK, you
don't have to worry about breaking up long lines. GTK-bubble (tooltip) help
wraps them automatically.

Also when new versions of X-CD-Roast are released, be sure to check
your current translation-strings, because due some layout changes, there
might be problems with the length of them.


How to get started:
-------------------

Starting from version 0.98alpha4 I included a little shellscript
lib/lang/lang_extract.sh which should ease the translations.

Change your directory to lib/lang within the X-CD-Roast source tree
and call "./lang_extract.sh <id>". Replace <id> with your given language-id.
So e.g. the swedish translator would type: "./lang_extract.sh 6"

The script rips out all other languages except english and yours. So you
have a much smaller file to handle and can see more easily which parts
need translations. 

If you start completely new with translation and your language-id has not
been used before, you do exactly the same - in this case you only get a
language-file with english texts. Be sure to add your "LANG_"-string in
the header and add your text as described above. 

The lang_extract.sh shipped with alpha5 also has a nice feature which
automatically creates empty dummy translations, which saving you
the work to entering the message and language ids yourself.

When you are done translating language.def and langhelp.def just send
me back these (much smaller) files. 

You can also change your own old texts - I will remerge the complete file 
everytime I receive a translation-update from you!

You may have noticed that on some (mostly older) distributions the
special chars of your language are not correctly displayed when the
text is printed bold. This seems to be a libc problem which is fixed
in the most recent linux distributions. However I added a command-line
switch which disabled multi-byte-font support and causes that the 
characters are displayed correctly. Start X-CD-Roast with the -o switch
for that. 


Things I have to worry about:
-----------------------------

You might wonder how I merge various translations into one file.
When several people are working on different languages each one will
mail me back their version.
I have a script which will merge any number of translations into one
language file. You just have to be sure only to use your language-id
number.


I guess that's all you have to know. 
Please don't start translating stuff without contacting me first and
received your personal language-id. 


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>

id 4: French, Ferdinand de Broich <firebird@chez.com> and 
	      Sbastien Yapo <sebastien.yapo@free.fr>
   
id 5: Croatian, Denis Pleic <dpleic@open.hr>

id 6: Swedish, Richard Torkar <ds98rito@thn.htu.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>

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

id 11: Estonian: Argo Vessmann <argo@ut.ee> and Triin Hannust <specter@ut.ee>

id 12: Brasilian Portuguese: Till Kamppeter <Till.Kamppeter@uni-bayreuth.de>

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 <pgquiles@teleline.es>

id 15: Czech, Adam Pribyl <covex@io.pinknet.cz> 
 
id 16: Hungarian, Balzs Gl <gbalcsi@freemail.hu> and 
       Marton Dosa <dm_@freemail.hu> 

id 17: ?? Romanian, Adrian Costin <nc99@asterix.cj.wan.ro>

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

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

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

id 21: ?? Norwegian, Andreas-Johann Ulvestad <aj@lilo.no>

id 22: Polish, Rafal Kura <jafal@usa.net>

id 23: ?? Russian, Igor Pruchanskiy <igor@linuxinside.com>

id 24: Slovak, Martin Petrk <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 Goi <xabigoi@terra.es>

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


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 with ?? mark people that said they will make a 
      translation, but have not finished it yet. 


18.07.2001 Thomas Niederreiter <tn@xcdroast.org>