--------------------------------------------------
TRANSLATION HOWTO for X-CD-Roast 1.19
11.11.2018 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 Krefting
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.
--
11.11.2018 Thomas Niederreiter
(parts of that document inspired by:
http://www.freeciv.org/notes/gettext-guide.txt)