Gettext Guide

:This is a quick description of the gettext system. For more complete, definitive information, see the gettext info pages.
----
Gettext is the i18n/l10n system that Freeciv uses.
==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:
 #: client/civclient.c:104 server/civserver.c:242
 #, c-format
 msgid "Usage: %s [option ...]\n"
 msgstr "Utilisation: %s [option ...]\n"
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 ""
 "Usage: %s [option ...]\n"
 "Valid options are:\n"
The fourth line, which begins "msgstr", is the translated string. It
may span more than one line, as in:
 msgstr ""
 "Utilisation: %s [option ...]\n"
 "Les options valides sont:\n"
==Gettext's three programs: 'xgettext', 'msgmerge' and 'msgfmt'==
(The following "make" commands assume you've done a './configure'.)
===xgettext===
Strings to be translated are automatically extracted from "marked"
source files by the 'xgettext' program. It's the programmer's job to
make sure the source files are correctly marked.
By convention, 'xgettext' produces a file named '<package>.pot' (in our
case, 'freeciv.pot' -- which you can find in the './po' directory after
doing a build). To rebuild 'freeciv.pot', cd into './po' and type
"make freeciv.pot".
===msgmerge===
However, 'freeciv.pot' is an *empty* localization file (it's in the same
format as a '.po' file, but it only has "msgid" strings and no "msgstr"
strings). You now need to "merge" the "new" 'freeciv.pot' file with
your "older" '<language>.po' file. This is the job of the 'msgmerge'
program.
Again by convention, 'msgmerge' produces a file named '<language>.pox'
(e.g., 'de.pox'). To build a '<language>.pox', cd into './po' and type
"make <language>.pox" (e.g., "make de.pox"). This will take the
existing '<language>.po' and a new 'freeciv.pot' and "merge" them into
a new '<language>.pox' file.
Now, you can move the new '<language>.pox' to '<language>.po', replacing
the old one, and begin to edit it. (E.g., "mv de.pox de.po".)
'msgmerge' will flag some entries in the new file in ways you should
know about:
* An entry flagged ", fuzzy" 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).
NOTE: All '.po' files have a fuzzy entry at the top of the file which
has a "msgid" string that is empty:
 #, fuzzy
 msgid ""
 msgstr ""
 "Project-Id-Version ...
It is important to *not* remove the "#, fuzzy" for this entry. It's a
fake entry, and allowing it to be translated confuses the run-time
libraries.
* Sometimes, old entries are completely commented out (using "#~").
These were entries that did not match anything in the new '.pot' file.
'msgmerge' leaves them in the file, but commented out, just in case
they may be useful in translating some new string. Once you are sure
that one of these old translations is no longer needed, you can delete
it.
===msgfmt===
When you are done editing your new '.po' file, you use 'msgfmt' to
generate the run-time translation file, called '<language>.gmo'. To
build '<language>.gmo', cd into './po' and type "make <language>.gmo"
(e.g., to build 'pt.gmo', type "make pt.gmo"). All the '.gmo' files
are also built during a full build of Freeciv.
==Two ways to check your .po file==
'msgfmt' can do more checking for you than it does by default: the "-c"
parameter asks for language-specific checking. For example, from the
'./po' directory, type "msgfmt -c -o junk.gmo <language>.po". This will
display several kinds of errors in translations of C format strings.
Unfortunately, for Freeciv "msgfmt -c" reports several problems that are
not problems! So, Freeciv comes with its own '.po' file checker:
'check_po.pl'.
You can find 'check_po.pl' in the './po' directory. Just run it from
the './po' directory by typing "./check_po.pl <language>.po". This will
display errors in your '.po' file -- and these problems probably are!
==A way to use your .gmo file as it is in your source tree==
I always run from my source tree (I never want to have to install just
to test). What I've done is kind of klugey, but it works for me. I've
gone into all the different locale directories, and made a symbolic link
from there to the various '.gmo' files in my development directory. For
example (your paths may be different):
 su # gotta have permission
 cd /usr/local/share/locale/<language>/LC_MESSAGES
 ln -s ~/prj/freeciv/po/<language>.gmo freeciv.mo
 exit
(Note that the link is called 'freeciv.mo', but the file it links to is
your generated '<language>.gmo'.)
Now, when I want to test the '<language>' locale, I do:
 LANG=<language> ./ser ...
or
 LANG=<language> ./civ ...
==== Howto for version 2.6 ====
You have to pay attention to where the source is looking for the .mo files. To do that, you need to check the Makefile in the utility directory. You want to find the value of LOCALEDIR, which is currently ${datarootdir}/locale. datarootdir is ${prefix}/share and prefix is /usr/local. So, the source is looking for mo files in /usr/local/share/locale (your current distribution is probably using a different directory, that is OK).
You have to remember that there are two .mo files, now: freeciv.mo and freeciv-nations.mo. The instructions, then become:
 sudo mkdir /usr/local/share/locale
 sudo mkdir /usr/local/share/locale/<your_language_code>
 sudo mkdir /usr/local/share/locale/<your_language_code>/LC_MESSAGES
 sudo ln -s ~/prj/translations/freeciv/<your_language_code>.gmo /usr/local/share/locale/<your_language_code>/LC_MESSAGES/freeciv.mo
 sudo ln -s ~/prj/translations/nations/<your_language_code>.gmo /usr/local/share/locale/<your_language_code>/LC_MESSAGES/freeciv-nations.mo
In order to play from source, you need to call freeciv from two scripts that will set all the variables as needed:
 ./fcser ... # you may add server options, this starts the server
and
 ./fcgui ... # you may add client options. You probably want -t amplio
Category:Localization