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

      TRANSLATION HOWTO for X-CD-Roast 1.19

 11.11.2018 Thomas Niederreiter <tn@xcdroast.org>

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



What's 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 is placed in its own file.

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

X-CD-Roast allows easy internationalization of all its
texts. All it needs is somebody who does 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 get X-CD-Roast working correctly with that language.
The locale got the information about charsets and the fonts to use.

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.

X-CD-Roast allows in the setup to switch to another language directly.


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 is not possible to do the work on a RPM/DEB
installed version. Also you need to have the gettext package installed,
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
contain 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 string of the English language
being translated. It may span more than one line, as in:

	msgid ""
	"There is an empty Disc 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 Rohling im Laufwerk.\n"
	"Weitere Sessions können nur auf einem bereits\n"
	"teilweise beschriebenen Rohling erstellt werden."

Some technical expressions in double quotes must not be translated,
while the ones in single quotes in the same text have to:

	msgid ""
	"In case of \"retry/skip errors\" do also try different values for 'read "
	"ahead buffer' or 'minimum overlap'."
	msgstr ""
	"Probieren Sie im Falle von \"retry/skip errors\" ebenfalls andere Werte für "
	"'Puffergröße' oder 'Mindestüberlappung' aus."



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

To continue work on an 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
file, you can use several tools to help you there. You can use 
"gtranslator" or "kbabel" if you want a graphical po file editor. These
help a lot to make the update process easier.

At the end of the po file there may be some commented out translations
which could not be allocated previously by gettext. You can use them
to do your translation and delete them completely afterwards.
Please note that those commented out lines beginning with the string "#~"
are not displayed by "gtranslator" or "kbabel". You need a regular text
editor to watch and delete them.

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 update-gmo" and it will automatically
compile your new translation texts. Watch for error messages and correct them
accordingly. 

After a "sudo make install" in the xcdroast directory you can run X-CD-Roast to
verify your work. Please check thoroughly 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 does not extist yet,
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 this 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. (I prefer to use UTF-8)

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 update-gmo" in the po directory to compile your translation
and "make install" in the xcdroast directory to install it.
If you set your LANG-environment variable 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!


Update the whole translation catalog:
-------------------------------------

In case you edit the X-CD-Roast source code and add/change texts there,
you have to rebuild the xcdroast.pot file.

This is done with this command:

	cd po
	make xcdroast.pot-update

Afterwards you have to merge the new text defines with all language files:

	make upate-po


The current translators/languages are:
(The last mentioned is always the most current)
-----------------------------------------------

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

id 1: German, 	Thomas Niederreiter <tn@xcdroast.org>
	      	Mathias Büttner <tn@xcdroast.org>

id 2: Dutch, 	Edwin Hakkennes <E.Hakkennes@et.tudelft.nl>
	     	Eric Hameleers <eric.hameleers@sox.homeip.net>	

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>
	       	Olaf Marzocchi <olaf.marzocchi@inwind.it>   
		Kostantino <inverness1@virgilio.it>

id 4: French, 	Sébastien Yapo <sebastien.yapo@free.fr>
	      	Ferdinand de Broich <firebird@chez.com> 
  	      	Adrien Rebollo <adrien.rebollo@gmx.fr>
 
id 5: Croatian, Denis Pleic <dpleic@open.hr>
		Krunoslav Gernhard <kruno@linux.hr>

id 6: Swedish, 	Richard Torkar <ds98rito@thn.htu.se>
               	Peter Krefting <peter@softwolves.pp.se>
	       	Henrik Sankala <hensan@gentoo.se>

id 7: Danish, 	Lars Juul <larsjuul@mail.dk>
		Lars Sarauw Hansen <lars_sarauw_hansen@hotmail.com>

id 9: Spanish, 	Jose Luis Benitez Crespo <jlbc@bigfoot.com>
	       	Rafael Mun~oz Rodríguez <muror@hotpop.com>

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

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

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

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

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>
       		  Marton Dosa <dm_@freemail.hu> 
       		  Mihály Gyulai <misibacsi@ecomail.org>
       		  Lajos Kósa <kosal@novonet.hu>

id 17: Romanian, Pauliuc George <pauliuc@gmx.net>

id 18: Traditional Chinese, Chih-Wei Huang <cwhuang@linux.org.tw>
			    Wei-Lun Chao <chaoweilun@pcmail.com.tw>

id 19: Simplified Chinese, Chih-Wei Huang <cwhuang@linux.org.tw>
		           Su Baochen <linuxman@sd163.net>
			   Wang zhi jun <wzjbox@bj163.com>

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

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

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

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

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>
		Miguel Bouzada <mbouzada@gmail.com>

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

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>

id 37: Albanian, Besnik Bleta <besnikbleta@hotmail.com>


NOTE: The most current version of this list is always on:

	http://www.xcdroast.org/release/translations.html 


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


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,
please contact me and I will register you as the new translator.


--

11.11.2018 Thomas Niederreiter <tn@xcdroast.org>

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