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

      TRANSLATION HOWTO for X-CD-Roast 1.18

 14.12.2017 Thomas Niederreiter 

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



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 

id 1: German, 	Thomas Niederreiter 
	      	Mathias Büttner 

id 2: Dutch, 	Edwin Hakkennes 
	     	Eric Hameleers 	

id 3: Italian, 	Andrea di Lecce 
	       	Giuseppe Di Mauro 
               	Roberto Rosselli Del Turco 
               	Daniela Di Candia 
	       	Olaf Marzocchi    
		Kostantino 

id 4: French, 	Sébastien Yapo 
	      	Ferdinand de Broich  
  	      	Adrien Rebollo 
 
id 5: Croatian, Denis Pleic 
		Krunoslav Gernhard 

id 6: Swedish, 	Richard Torkar 
               	Peter Karlsson 
	       	Henrik Sankala 

id 7: Danish, 	Lars Juul 
		Lars Sarauw Hansen 

id 9: Spanish, 	Jose Luis Benitez Crespo 
	       	Rafael Mun~oz Rodríguez 

id 10: Turkish, Alexander Neptun 

id 11: Estonian, Argo Vessmann 
	     	Triin Hannust 
		Ahti Akel 

id 12: Brasilian Portuguese, Till Kamppeter 
		Syndson Silva 

id 13: Japanese, Takeyuki Fujioka  
       		 Masaki Shinomiya 
		 Hyde Yamakawa 

id 14: Catalan, Pau Garcia i Quiles 

id 15: Czech, Adam Pribyl  
 
id 16: Hungarian, Balázs Gál 
       		  Marton Dosa  
       		  Mihály Gyulai 
       		  Lajos Kósa 

id 17: Romanian, Pauliuc George 

id 18: Traditional Chinese, Chih-Wei Huang 
			    Wei-Lun Chao 

id 19: Simplified Chinese, Chih-Wei Huang 
		           Su Baochen 
			   Wang zhi jun 

id 21: Norwegian, Stig Hornang 

id 22: Polish, 	Rafal Kura 
	       	Robert Gomulka 

id 23: Russian, Anthony Borisow 
	 	Vitaly Lipatov 

id 24: Slovak, 	Martin Petrák 

id 26: Indonesian, Didiet Wardhana Novianto 

id 27: Bulgarian, Andrei Uzunov  

id 28: Galician, Xosé Anxo Pereira Torreiro 
		Miguel Bouzada 

id 30: Finnish, Henry Palonen 

id 34: Ukranian, Maxim Dzumanenko  

id 35: Greek, 	Filippos Papadopoulos 

id 36: Latvian, Imants Treidis 

id 37: Albanian, Besnik Bleta 


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.


--

14.12.2017 Thomas Niederreiter 

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