gettext: Overview
1
1 1.5 Overview of GNU ‘gettext’
1 =============================
1
1 The following diagram summarizes the relation between the files
1 handled by GNU ‘gettext’ and the tools acting on these files. It is
1 followed by somewhat detailed explanations, which you should read while
1 keeping an eye on the diagram. Having a clear understanding of these
1 interrelations will surely help programmers, translators and
1 maintainers.
1
1 Original C Sources ---> Preparation ---> Marked C Sources ---.
1 |
1 .---------<--- GNU gettext Library |
1 .--- make <---+ |
1 | `---------<--------------------+---------------'
1 | |
1 | .-----<--- PACKAGE.pot <--- xgettext <---' .---<--- PO Compendium
1 | | | ^
1 | | `---. |
1 | `---. +---> PO editor ---.
1 | +----> msgmerge ------> LANG.po ---->--------' |
1 | .---' |
1 | | |
1 | `-------------<---------------. |
1 | +--- New LANG.po <--------------------'
1 | .--- LANG.gmo <--- msgfmt <---'
1 | |
1 | `---> install ---> /.../LANG/PACKAGE.mo ---.
1 | +---> "Hello world!"
1 `-------> install ---> /.../bin/PROGRAM -------'
1
1 As a programmer, the first step to bringing GNU ‘gettext’ into your
1 package is identifying, right in the C sources, those strings which are
1 meant to be translatable, and those which are untranslatable. This
1 tedious job can be done a little more comfortably using emacs PO mode,
1 but you can use any means familiar to you for modifying your C sources.
1 Beside this some other simple, standard changes are needed to properly
1 initialize the translation library. ⇒Sources, for more
1 information about all this.
1
1 For newly written software the strings of course can and should be
1 marked while writing it. The ‘gettext’ approach makes this very easy.
1 Simply put the following lines at the beginning of each file or in a
1 central header file:
1
1 #define _(String) (String)
1 #define N_(String) String
1 #define textdomain(Domain)
1 #define bindtextdomain(Package, Directory)
1
1 Doing this allows you to prepare the sources for internationalization.
1 Later when you feel ready for the step to use the ‘gettext’ library
1 simply replace these definitions by the following:
1
1 #include <libintl.h>
1 #define _(String) gettext (String)
1 #define gettext_noop(String) String
1 #define N_(String) gettext_noop (String)
1
1 and link against ‘libintl.a’ or ‘libintl.so’. Note that on GNU systems,
1 you don’t need to link with ‘libintl’ because the ‘gettext’ library
1 functions are already contained in GNU libc. That is all you have to
1 change.
1
1 Once the C sources have been modified, the ‘xgettext’ program is used
1 to find and extract all translatable strings, and create a PO template
1 file out of all these. This ‘PACKAGE.pot’ file contains all original
1 program strings. It has sets of pointers to exactly where in C sources
1 each string is used. All translations are set to empty. The letter ‘t’
1 in ‘.pot’ marks this as a Template PO file, not yet oriented towards any
1 particular language. ⇒xgettext Invocation, for more details
1 about how one calls the ‘xgettext’ program. If you are _really_ lazy,
1 you might be interested at working a lot more right away, and preparing
1 the whole distribution setup (⇒Maintainers). By doing so, you
1 spare yourself typing the ‘xgettext’ command, as ‘make’ should now
1 generate the proper things automatically for you!
1
1 The first time through, there is no ‘LANG.po’ yet, so the ‘msgmerge’
1 step may be skipped and replaced by a mere copy of ‘PACKAGE.pot’ to
11 ‘LANG.po’, where LANG represents the target language. See ⇒
Creating for details.
1
1 Then comes the initial translation of messages. Translation in
1 itself is a whole matter, still exclusively meant for humans, and whose
1 complexity far overwhelms the level of this manual. Nevertheless, a few
11 hints are given in some other chapter of this manual (⇒
Translators). You will also find there indications about how to
1 contact translating teams, or becoming part of them, for sharing your
1 translating concerns with others who target the same native language.
1
1 While adding the translated messages into the ‘LANG.po’ PO file, if
11 you are not using one of the dedicated PO file editors (⇒
Editing), you are on your own for ensuring that your efforts fully
1 respect the PO file format, and quoting conventions (⇒PO Files).
1 This is surely not an impossible task, as this is the way many people
1 have handled PO files around 1995. On the other hand, by using a PO
1 file editor, most details of PO file format are taken care of for you,
1 but you have to acquire some familiarity with PO file editor itself.
1
1 If some common translations have already been saved into a compendium
1 PO file, translators may use PO mode for initializing untranslated
1 entries from the compendium, and also save selected translations into
1 the compendium, updating it (⇒Compendium). Compendium files are
1 meant to be exchanged between members of a given translation team.
1
1 Programs, or packages of programs, are dynamic in nature: users write
1 bug reports and suggestion for improvements, maintainers react by
1 modifying programs in various ways. The fact that a package has already
1 been internationalized should not make maintainers shy of adding new
1 strings, or modifying strings already translated. They just do their
1 job the best they can. For the Translation Project to work smoothly, it
1 is important that maintainers do not carry translation concerns on their
1 already loaded shoulders, and that translators be kept as free as
1 possible of programming concerns.
1
1 The only concern maintainers should have is carefully marking new
1 strings as translatable, when they should be, and do not otherwise worry
1 about them being translated, as this will come in proper time.
1 Consequently, when programs and their strings are adjusted in various
1 ways by maintainers, and for matters usually unrelated to translation,
1 ‘xgettext’ would construct ‘PACKAGE.pot’ files which are evolving over
1 time, so the translations carried by ‘LANG.po’ are slowly fading out of
1 date.
1
1 It is important for translators (and even maintainers) to understand
1 that package translation is a continuous process in the lifetime of a
1 package, and not something which is done once and for all at the start.
1 After an initial burst of translation activity for a given package,
1 interventions are needed once in a while, because here and there,
1 translated entries become obsolete, and new untranslated entries appear,
1 needing translation.
1
1 The ‘msgmerge’ program has the purpose of refreshing an already
1 existing ‘LANG.po’ file, by comparing it with a newer ‘PACKAGE.pot’
1 template file, extracted by ‘xgettext’ out of recent C sources. The
1 refreshing operation adjusts all references to C source locations for
1 strings, since these strings move as programs are modified. Also,
1 ‘msgmerge’ comments out as obsolete, in ‘LANG.po’, those already
1 translated entries which are no longer used in the program sources
1 (⇒Obsolete Entries). It finally discovers new strings and
11 inserts them in the resulting PO file as untranslated entries (⇒
Untranslated Entries). ⇒msgmerge Invocation, for more
1 information about what ‘msgmerge’ really does.
1
1 Whatever route or means taken, the goal is to obtain an updated
1 ‘LANG.po’ file offering translations for all strings.
1
1 The temporal mobility, or fluidity of PO files, is an integral part
1 of the translation game, and should be well understood, and accepted.
1 People resisting it will have a hard time participating in the
1 Translation Project, or will give a hard time to other participants! In
1 particular, maintainers should relax and include all available official
1 PO files in their distributions, even if these have not recently been
1 updated, without exerting pressure on the translator teams to get the
1 job done. The pressure should rather come from the community of users
1 speaking a particular language, and maintainers should consider
1 themselves fairly relieved of any concern about the adequacy of
1 translation files. On the other hand, translators should reasonably try
1 updating the PO files they are responsible for, while the package is
1 undergoing pretest, prior to an official distribution.
1
1 Once the PO file is complete and dependable, the ‘msgfmt’ program is
1 used for turning the PO file into a machine-oriented format, which may
1 yield efficient retrieval of translations by the programs of the
DONTPRINTYET 1 package, whenever needed at runtime (⇒MO Files). *Notemsgfmt
1DONTPRINTYET 1 package, whenever needed at runtime (⇒MO Files). ⇒msgfmt
Invocation, for more information about all modes of execution for the
1 ‘msgfmt’ program.
1
1 Finally, the modified and marked C sources are compiled and linked
1 with the GNU ‘gettext’ library, usually through the operation of ‘make’,
1 given a suitable ‘Makefile’ exists for the project, and the resulting
1 executable is installed somewhere users will find it. The MO files
1 themselves should also be properly installed. Given the appropriate
1 environment variables are set (⇒Setting the POSIX Locale), the
1 program should localize itself automatically, whenever it executes.
1
1 The remainder of this manual has the purpose of explaining in depth
1 the various steps outlined above.
1