File: gettext.info,  Node: Overview,  Prev: Files,  Up: Introduction

1.5 Overview of GNU ‘gettext’
=============================

   The following diagram summarizes the relation between the files
handled by GNU ‘gettext’ and the tools acting on these files.  It is
followed by somewhat detailed explanations, which you should read while
keeping an eye on the diagram.  Having a clear understanding of these
interrelations will surely help programmers, translators and
maintainers.

     Original C Sources ---> Preparation ---> Marked C Sources ---.
                                                                  |
                   .---------<--- GNU gettext Library             |
     .--- make <---+                                              |
     |             `---------<--------------------+---------------'
     |                                            |
     |   .-----<--- PACKAGE.pot <--- xgettext <---'   .---<--- PO Compendium
     |   |                                            |              ^
     |   |                                            `---.          |
     |   `---.                                            +---> PO editor ---.
     |       +----> msgmerge ------> LANG.po ---->--------'                  |
     |   .---'                                                               |
     |   |                                                                   |
     |   `-------------<---------------.                                     |
     |                                 +--- New LANG.po <--------------------'
     |   .--- LANG.gmo <--- msgfmt <---'
     |   |
     |   `---> install ---> /.../LANG/PACKAGE.mo ---.
     |                                              +---> "Hello world!"
     `-------> install ---> /.../bin/PROGRAM -------'

   As a programmer, the first step to bringing GNU ‘gettext’ into your
package is identifying, right in the C sources, those strings which are
meant to be translatable, and those which are untranslatable.  This
tedious job can be done a little more comfortably using emacs PO mode,
but you can use any means familiar to you for modifying your C sources.
Beside this some other simple, standard changes are needed to properly
initialize the translation library.  *Note Sources::, for more
information about all this.

   For newly written software the strings of course can and should be
marked while writing it.  The ‘gettext’ approach makes this very easy.
Simply put the following lines at the beginning of each file or in a
central header file:

     #define _(String) (String)
     #define N_(String) String
     #define textdomain(Domain)
     #define bindtextdomain(Package, Directory)

Doing this allows you to prepare the sources for internationalization.
Later when you feel ready for the step to use the ‘gettext’ library
simply replace these definitions by the following:

     #include 
     #define _(String) gettext (String)
     #define gettext_noop(String) String
     #define N_(String) gettext_noop (String)

and link against ‘libintl.a’ or ‘libintl.so’.  Note that on GNU systems,
you don't need to link with ‘libintl’ because the ‘gettext’ library
functions are already contained in GNU libc.  That is all you have to
change.

   Once the C sources have been modified, the ‘xgettext’ program is used
to find and extract all translatable strings, and create a PO template
file out of all these.  This ‘PACKAGE.pot’ file contains all original
program strings.  It has sets of pointers to exactly where in C sources
each string is used.  All translations are set to empty.  The letter ‘t’
in ‘.pot’ marks this as a Template PO file, not yet oriented towards any
particular language.  *Note xgettext Invocation::, for more details
about how one calls the ‘xgettext’ program.  If you are _really_ lazy,
you might be interested at working a lot more right away, and preparing
the whole distribution setup (*note Maintainers::).  By doing so, you
spare yourself typing the ‘xgettext’ command, as ‘make’ should now
generate the proper things automatically for you!

   The first time through, there is no ‘LANG.po’ yet, so the ‘msgmerge’
step may be skipped and replaced by a mere copy of ‘PACKAGE.pot’ to
‘LANG.po’, where LANG represents the target language.  See *note
Creating:: for details.

   Then comes the initial translation of messages.  Translation in
itself is a whole matter, still exclusively meant for humans, and whose
complexity far overwhelms the level of this manual.  Nevertheless, a few
hints are given in some other chapter of this manual (*note
Translators::).  You will also find there indications about how to
contact translating teams, or becoming part of them, for sharing your
translating concerns with others who target the same native language.

   While adding the translated messages into the ‘LANG.po’ PO file, if
you are not using one of the dedicated PO file editors (*note
Editing::), you are on your own for ensuring that your efforts fully
respect the PO file format, and quoting conventions (*note PO Files::).
This is surely not an impossible task, as this is the way many people
have handled PO files around 1995.  On the other hand, by using a PO
file editor, most details of PO file format are taken care of for you,
but you have to acquire some familiarity with PO file editor itself.

   If some common translations have already been saved into a compendium
PO file, translators may use PO mode for initializing untranslated
entries from the compendium, and also save selected translations into
the compendium, updating it (*note Compendium::).  Compendium files are
meant to be exchanged between members of a given translation team.

   Programs, or packages of programs, are dynamic in nature: users write
bug reports and suggestion for improvements, maintainers react by
modifying programs in various ways.  The fact that a package has already
been internationalized should not make maintainers shy of adding new
strings, or modifying strings already translated.  They just do their
job the best they can.  For the Translation Project to work smoothly, it
is important that maintainers do not carry translation concerns on their
already loaded shoulders, and that translators be kept as free as
possible of programming concerns.

   The only concern maintainers should have is carefully marking new
strings as translatable, when they should be, and do not otherwise worry
about them being translated, as this will come in proper time.
Consequently, when programs and their strings are adjusted in various
ways by maintainers, and for matters usually unrelated to translation,
‘xgettext’ would construct ‘PACKAGE.pot’ files which are evolving over
time, so the translations carried by ‘LANG.po’ are slowly fading out of
date.

   It is important for translators (and even maintainers) to understand
that package translation is a continuous process in the lifetime of a
package, and not something which is done once and for all at the start.
After an initial burst of translation activity for a given package,
interventions are needed once in a while, because here and there,
translated entries become obsolete, and new untranslated entries appear,
needing translation.

   The ‘msgmerge’ program has the purpose of refreshing an already
existing ‘LANG.po’ file, by comparing it with a newer ‘PACKAGE.pot’
template file, extracted by ‘xgettext’ out of recent C sources.  The
refreshing operation adjusts all references to C source locations for
strings, since these strings move as programs are modified.  Also,
‘msgmerge’ comments out as obsolete, in ‘LANG.po’, those already
translated entries which are no longer used in the program sources
(*note Obsolete Entries::).  It finally discovers new strings and
inserts them in the resulting PO file as untranslated entries (*note
Untranslated Entries::).  *Note msgmerge Invocation::, for more
information about what ‘msgmerge’ really does.

   Whatever route or means taken, the goal is to obtain an updated
‘LANG.po’ file offering translations for all strings.

   The temporal mobility, or fluidity of PO files, is an integral part
of the translation game, and should be well understood, and accepted.
People resisting it will have a hard time participating in the
Translation Project, or will give a hard time to other participants!  In
particular, maintainers should relax and include all available official
PO files in their distributions, even if these have not recently been
updated, without exerting pressure on the translator teams to get the
job done.  The pressure should rather come from the community of users
speaking a particular language, and maintainers should consider
themselves fairly relieved of any concern about the adequacy of
translation files.  On the other hand, translators should reasonably try
updating the PO files they are responsible for, while the package is
undergoing pretest, prior to an official distribution.

   Once the PO file is complete and dependable, the ‘msgfmt’ program is
used for turning the PO file into a machine-oriented format, which may
yield efficient retrieval of translations by the programs of the
package, whenever needed at runtime (*note MO Files::).  *Note msgfmt
Invocation::, for more information about all modes of execution for the
‘msgfmt’ program.

   Finally, the modified and marked C sources are compiled and linked
with the GNU ‘gettext’ library, usually through the operation of ‘make’,
given a suitable ‘Makefile’ exists for the project, and the resulting
executable is installed somewhere users will find it.  The MO files
themselves should also be properly installed.  Given the appropriate
environment variables are set (*note Setting the POSIX Locale::), the
program should localize itself automatically, whenever it executes.

   Shipping the MO files as separate files, as opposed to embedding them
in the executable, has three advantages:
   • For the users: It allows users to prepare and install new
     translations, without needing to rebuild the package (which may
     require developer skills).
   • For the distributors: It allows distributions to ship translations
     that were produced after the release of the package.
   • For the vendors of complex packages: When lengthy quality assurance
     steps are required before making a release, this quality assurance
     can start before the translators have produced the translations,
     shortening the critical path of the release schedule by a week or
     two.
Embedding the translations in the executable, whether by the ISO C
‘#embed’ directive or through other means, would deprive users without
developer skills of the ability to fix translation mistakes and add new
translations.

   The remainder of this manual has the purpose of explaining in depth
the various steps outlined above.