<p>Go to the first, previous, <AHREF="gettext_2.html">next</A>, <AHREF="gettext_12.html">last</A> section, <AHREF="gettext_toc.html">table of contents</A>.
with easy repositioning to PO file lines showing errors.
</P>
<P>
As a programmer, the first step to bringing GNU <CODE>gettext</CODE>
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. See section <AHREF="gettext_3.html#SEC13">Preparing Program Sources</A>, for
more information about all this.
</P>
<P>
For newly written software the strings of course can and should be
marked while writing the it. The <CODE>gettext</CODE> approach makes this
very easy. Simply put the following lines at the beginning of each file
or in a central header file:
</P>
<PRE>
#define _(String) (String)
#define N_(String) (String)
#define textdomain(Domain)
#define bindtextdomain(Package, Directory)
</PRE>
<P>
Doing this allows you to prepare the sources for internationalization.
Later when you feel ready for the step to use the <CODE>gettext</CODE> library
simply remove these definitions, include <TT>`libintl.h'</TT> and link
against <TT>`libintl.a'</TT>. That is all you have to change.
</P>
<P>
Once the C sources have been modified, the <CODE>xgettext</CODE> program
is used to find and extract all translatable strings, and create an
initial PO file out of all these. This <TT>`<VAR>package</VAR>.pot'</TT> 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 <KBD>t</KBD> in <TT>`.pot'</TT> marks this as
a Template PO file, not yet oriented towards any particular language.
See section <AHREF="gettext_4.html#SEC20">Invoking the <CODE>xgettext</CODE> Program</A>, for more details about how one calls the
<CODE>xgettext</CODE> program. If you are <EM>really</EM> lazy, you might
be interested at working a lot more right away, and preparing the
whole distribution setup (see section <AHREF="gettext_10.html#SEC67">The Maintainer's View</A>). By doing so, you
spare yourself typing the <CODE>xgettext</CODE> command, as <CODE>make</CODE>
should now generate the proper things automatically for you!
</P>
<P>
The first time through, there is no <TT>`<VAR>lang</VAR>.po'</TT> yet, so the
<CODE>msgmerge</CODE> step may be skipped and replaced by a mere copy of
<TT>`<VAR>package</VAR>.pot'</TT> to <TT>`<VAR>lang</VAR>.pox'</TT>, where <VAR>lang</VAR>
represents the target language.
</P>
<P>
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 (see section <AHREF="gettext_9.html#SEC56">The Translator's View</A>). 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.
</P>
<P>
While adding the translated messages into the <TT>`<VAR>lang</VAR>.pox'</TT>
PO file, if you do not have GNU Emacs handy, you are on your own
for ensuring that your efforts fully respect the PO file format, and quoting
conventions (see section <AHREF="gettext_2.html#SEC9">The Format of PO Files</A>). This is surely not an impossible task,
as this is the way many people have handled PO files already for Uniforum or
Solaris. On the other hand, by using PO mode in GNU Emacs, most details
of PO file format are taken care of for you, but you have to acquire
some familiarity with PO mode itself. Besides main PO mode commands
(see section <AHREF="gettext_2.html#SEC10">Main PO mode Commands</A>), you should know how to move between entries
(see section <AHREF="gettext_2.html#SEC11">Entry Positioning</A>), and how to handle untranslated entries
(see section <AHREF="gettext_5.html#SEC27">Untranslated Entries</A>).
</P>
<P>
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 (see section <AHREF="gettext_4.html#SEC22">Using Translation Compendiums</A>). Compendium files
are meant to be exchanged between members of a given translation team.
</P>
<P>
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 programmatic concerns.
</P>
<P>
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,
<CODE>xgettext</CODE> would construct <TT>`<VAR>package</VAR>.pot'</TT> files which are
evolving over time, so the translations carried by <TT>`<VAR>lang</VAR>.po'</TT>
are slowly fading out of date.
</P>
<P>
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.
</P>
<P>
The <CODE>msgmerge</CODE> program has the purpose of refreshing an already
existing <TT>`<VAR>lang</VAR>.po'</TT> file, by comparing it with a newer
<TT>`<VAR>package</VAR>.pot'</TT> template file, extracted by <CODE>xgettext</CODE>
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, <CODE>msgmerge</CODE> comments out as
obsolete, in <TT>`<VAR>lang</VAR>.pox'</TT>, those already translated entries
which are no longer used in the program sources (see section <AHREF="gettext_5.html#SEC28">Obsolete Entries</A>). It finally discovers new strings and inserts them in
the resulting PO file as untranslated entries (see section <AHREF="gettext_5.html#SEC27">Untranslated Entries</A>). See section <AHREF="gettext_5.html#SEC24">Invoking the <CODE>msgmerge</CODE> Program</A>, for more information about what
<CODE>msgmerge</CODE> really does.
</P>
<P>
Whatever route or means taken, the goal is to obtain an updated
<TT>`<VAR>lang</VAR>.pox'</TT> file offering translations for all strings.
When this is properly achieved, this file <TT>`<VAR>lang</VAR>.pox'</TT> may
take the place of the previous official <TT>`<VAR>lang</VAR>.po'</TT> file.
</P>
<P>
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 banging or otherwise trying to exert 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.
</P>
<P>
Once the PO file is complete and dependable, the <CODE>msgfmt</CODE> 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 (see section <AHREF="gettext_6.html#SEC34">The Format of GNU MO Files</A>). See section <AHREF="gettext_6.html#SEC33">Invoking the <CODE>msgfmt</CODE> Program</A>, for more information about all modalities of execution
for the <CODE>msgfmt</CODE> program.
</P>
<P>
Finally, the modified and marked C sources are compiled and linked
with the GNU <CODE>gettext</CODE> library, usually through the operation of
<CODE>make</CODE>, given a suitable <TT>`Makefile'</TT> 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 (see section <AHREF="gettext_7.html#SEC38">Magic for End Users</A>), the
program should localize itself automatically, whenever it executes.
</P>
<P>
The remainder of this manual has the purpose of explaining in depth the various
steps outlined above.
</P>
<P><HR><P>
<p>Go to the first, previous, <AHREF="gettext_2.html">next</A>, <AHREF="gettext_12.html">last</A> section, <AHREF="gettext_toc.html">table of contents</A>.
