- 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 formatEdit
.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'Edit
(The following "make" commands assume you've done a './configure'.)
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".
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.
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 fileEdit
'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 treeEdit
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 ...
LANG=<language> ./civ ...