docs/html/gettext/gettext_1.html

   1 <HTML>
   2 <HEAD>
   3 <!-- This HTML file has been created by texi2html 1.54
   4      from gettext.texi on 25 January 1999 -->
   5
   6 <TITLE>GNU gettext utilities - Introduction</TITLE>
   7 <link href="gettext_2.html" rel=Next>
   8 <link href="gettext_toc.html" rel=ToC>
   9
  10 </HEAD>
  11 <BODY>
  12 <p>Go to the first, previous, <A HREF="gettext_2.html">next</A>, <A HREF="gettext_12.html">last</A> section, <A HREF="gettext_toc.html">table of contents</A>.
  13 <P><HR><P>
  14
  15
  16 <H1><A NAME="SEC1" HREF="gettext_toc.html#TOC1">Introduction</A></H1>
  17
  18
  19 <BLOCKQUOTE>
  20 <P>
  21 This manual is still in <EM>DRAFT</EM> state.  Some sections are still
  22 empty, or almost.  We keep merging material from other sources
  23 (essentially e-mail folders) while the proper integration of this
  24 material is delayed.
  25 </BLOCKQUOTE>
  26
  27 <P>
  28 In this manual, we use <EM>he</EM> when speaking of the programmer or
  29 maintainer, <EM>she</EM> when speaking of the translator, and <EM>they</EM>
  30 when speaking of the installers or end users of the translated program.
  31 This is only a convenience for clarifying the documentation.  It is
  32 <EM>absolutely</EM> not meant to imply that some roles are more appropriate
  33 to males or females.  Besides, as you might guess, GNU <CODE>gettext</CODE>
  34 is meant to be useful for people using computers, whatever their sex,
  35 race, religion or nationality!
  36
  37 </P>
  38 <P>
  39 This chapter explains the goals sought in the creation
  40 of GNU <CODE>gettext</CODE> and the free Translation Project.
  41 Then, it explains a few broad concepts around
  42 Native Language Support, and positions message translation with regard
  43 to other aspects of national and cultural variance, as they apply to
  44 to programs.  It also surveys those files used to convey the
  45 translations.  It explains how the various tools interact in the
  46 initial generation of these files, and later, how the maintenance
  47 cycle should usually operate.
  48
  49 </P>
  50 <P>
  51 Please send suggestions and corrections to:
  52
  53 </P>
  54
  55 <PRE>
  56 Internet address:
  57     bug-gnu-utils@prep.ai.mit.edu
  58 </PRE>
  59
  60 <P>
  61 Please include the manual's edition number and update date in your messages.
  62
  63 </P>
  64
  65
  66
  67 <H2><A NAME="SEC2" HREF="gettext_toc.html#TOC2">The Purpose of GNU <CODE>gettext</CODE></A></H2>
  68
  69 <P>
  70 Usually, programs are written and documented in English, and use
  71 English at execution time to interact with users.  This is true
  72 not only of GNU software, but also of a great deal of commercial
  73 and free software.  Using a common language is quite handy for
  74 communication between developers, maintainers and users from all
  75 countries.  On the other hand, most people are less comfortable with
  76 English than with their own native language, and would prefer to
  77 use their mother tongue for day to day's work, as far as possible.
  78 Many would simply <EM>love</EM> to see their computer screen showing
  79 a lot less of English, and far more of their own language.
  80
  81 </P>
  82 <P>
  83 However, to many people, this dream might appear so far fetched that
  84 they may believe it is not even worth spending time thinking about
  85 it.  They have no confidence at all that the dream might ever
  86 become true.  Yet some have not lost hope, and have organized themselves.
  87 The Translation Project is a formalization of this hope into a
  88 workable structure, which has a good chance to get all of us nearer
  89 the achievement of a truly multi-lingual set of programs.
  90
  91 </P>
  92 <P>
  93 GNU <CODE>gettext</CODE> is an important step for the Translation Project,
  94 as it is an asset on which we may build many other steps.  This package
  95 offers to programmers, translators and even users, a well integrated
  96 set of tools and documentation.  Specifically, the GNU <CODE>gettext</CODE>
  97 utilities are a set of tools that provides a framework within which
  98 other free packages may produce multi-lingual messages.  These tools
  99 include a set of conventions about how programs should be written to
 100 support message catalogs, a directory and file naming organization for the
 101 message catalogs themselves, a runtime library supporting the retrieval of
 102 translated messages, and a few stand-alone programs to massage in various
 103 ways the sets of translatable strings, or already translated strings.
 104 A special mode for GNU Emacs also helps ease interested parties into
 105 preparing these sets, or bringing them up to date.
 106
 107 </P>
 108 <P>
 109 GNU <CODE>gettext</CODE> is designed to minimize the impact of
 110 internationalization on program sources, keeping this impact as small
 111 and hardly noticeable as possible.  Internationalization has better
 112 chances of succeeding if it is very light weighted, or at least,
 113 appear to be so, when looking at program sources.
 114
 115 </P>
 116 <P>
 117 The Translation Project also uses the GNU <CODE>gettext</CODE>
 118 distribution as a vehicle for documenting its structure and methods.
 119 This goes beyond the strict technicalities of documenting the GNU <CODE>gettext</CODE>
 120 proper.  By so doing, translators will find in a single place, as
 121 far as possible, all they need to know for properly doing their
 122 translating work.  Also, this supplemental documentation might also
 123 help programmers, and even curious users, in understanding how GNU
 124 <CODE>gettext</CODE> is related to the remainder of the Translation
 125 Project, and consequently, have a glimpse at the <EM>big picture</EM>.
 126
 127 </P>
 128
 129
 130 <H2><A NAME="SEC3" HREF="gettext_toc.html#TOC3">I18n, L10n, and Such</A></H2>
 131
 132 <P>
 133 Two long words appear all the time when we discuss support of native
 134 language in programs, and these words have a precise meaning, worth
 135 being explained here, once and for all in this document.  The words are
 136 <EM>internationalization</EM> and <EM>localization</EM>.  Many people,
 137 tired of writing these long words over and over again, took the
 138 habit of writing <STRONG>i18n</STRONG> and <STRONG>l10n</STRONG> instead, quoting the first
 139 and last letter of each word, and replacing the run of intermediate
 140 letters by a number merely telling how many such letters there are.
 141 But in this manual, in the sake of clarity, we will patiently write
 142 the names in full, each time...
 143
 144 </P>
 145 <P>
 146 By <STRONG>internationalization</STRONG>, one refers to the operation by which a
 147 program, or a set of programs turned into a package, is made aware of and
 148 able to support multiple languages.  This is a generalization process,
 149 by which the programs are untied from calling only English strings or
 150 other English specific habits, and connected to generic ways of doing
 151 the same, instead.  Program developers may use various techniques to
 152 internationalize their programs.  Some of these have been standardized.
 153 GNU <CODE>gettext</CODE> offers one of these standards.  See section <A HREF="gettext_8.html#SEC39">The Programmer's View</A>.
 154
 155 </P>
 156 <P>
 157 By <STRONG>localization</STRONG>, one means the operation by which, in a set
 158 of programs already internationalized, one gives the program all
 159 needed information so that it can adapt itself to handle its input
 160 and output in a fashion which is correct for some native language and
 161 cultural habits.  This is a particularisation process, by which generic
 162 methods already implemented in an internationalized program are used
 163 in specific ways.  The programming environment puts several functions
 164 to the programmers disposal which allow this runtime configuration.
 165 The formal description of specific set of cultural habits for some
 166 country, together with all associated translations targeted to the
 167 same native language, is called the <STRONG>locale</STRONG> for this language
 168 or country.  Users achieve localization of programs by setting proper
 169 values to special environment variables, prior to executing those
 170 programs, identifying which locale should be used.
 171
 172 </P>
 173 <P>
 174 In fact, locale message support is only one component of the cultural
 175 data that makes up a particular locale.  There are a whole host of
 176 routines and functions provided to aid programmers in developing
 177 internationalized software and which allow them to access the data
 178 stored in a particular locale.  When someone presently refers to a
 179 particular locale, they are obviously referring to the data stored
 180 within that particular locale.  Similarly, if a programmer is referring
 181 to "accessing the locale routines", they are referring to the
 182 complete suite of routines that access all of the locale's information.
 183
 184 </P>
 185 <P>
 186 One uses the expression <STRONG>Native Language Support</STRONG>, or merely NLS,
 187 for speaking of the overall activity or feature encompassing both
 188 internationalization and localization, allowing for multi-lingual
 189 interactions in a program.  In a nutshell, one could say that
 190 internationalization is the operation by which further localizations
 191 are made possible.
 192
 193 </P>
 194 <P>
 195 Also, very roughly said, when it comes to multi-lingual messages,
 196 internationalization is usually taken care of by programmers, and
 197 localization is usually taken care of by translators.
 198
 199 </P>
 200
 201
 202 <H2><A NAME="SEC4" HREF="gettext_toc.html#TOC4">Aspects in Native Language Support</A></H2>
 203
 204 <P>
 205 For a totally multi-lingual distribution, there are many things to
 206 translate beyond output messages.
 207
 208 </P>
 209
 210 <UL>
 211 <LI>
 212
 213 As of today, GNU <CODE>gettext</CODE> offers a complete toolset for
 214 translating messages output by C programs.  Perl scripts and shell
 215 scripts will also need to be translated.  Even if there are today some hooks
 216 by which this can be done, these hooks are not integrated as well as they
 217 should be.
 218
 219 <LI>
 220
 221 Some programs, like <CODE>autoconf</CODE> or <CODE>bison</CODE>, are able
 222 to produce other programs (or scripts).  Even if the generating
 223 programs themselves are internationalized, the generated programs they
 224 produce may need internationalization on their own, and this indirect
 225 internationalization could be automated right from the generating
 226 program.  In fact, quite usually, generating and generated programs
 227 could be internationalized independently, as the effort needed is
 228 fairly orthogonal.
 229
 230 <LI>
 231
 232 A few programs include textual tables which might need translation
 233 themselves, independently of the strings contained in the program
 234 itself.  For example, RFC 1345 gives an English description for each
 235 character which GNU <CODE>recode</CODE> is able to reconstruct at execution.
 236 Since these descriptions are extracted from the RFC by mechanical means,
 237 translating them properly would require a prior translation of the RFC
 238 itself.
 239
 240 <LI>
 241
 242 Almost all programs accept options, which are often worded out so to
 243 be descriptive for the English readers; one might want to consider
 244 offering translated versions for program options as well.
 245
 246 <LI>
 247
 248 Many programs read, interpret, compile, or are somewhat driven by
 249 input files which are texts containing keywords, identifiers, or
 250 replies which are inherently translatable.  For example, one may want
 251 <CODE>gcc</CODE> to allow diacriticized characters in identifiers or use
 252 translated keywords; <SAMP>`rm -i'</SAMP> might accept something else than
 253 <SAMP>`y'</SAMP> or <SAMP>`n'</SAMP> for replies, etc.  Even if the program will
 254 eventually make most of its output in the foreign languages, one has
 255 to decide whether the input syntax, option values, etc., are to be
 256 localized or not.
 257
 258 <LI>
 259
 260 The manual accompanying a package, as well as all documentation files
 261 in the distribution, could surely be translated, too.  Translating a
 262 manual, with the intent of later keeping up with updates, is a major
 263 undertaking in itself, generally.
 264
 265 </UL>
 266
 267 <P>
 268 As we already stressed, translation is only one aspect of locales.
 269 Other internationalization aspects are not currently handled by GNU
 270 <CODE>gettext</CODE>, but perhaps may be handled in future versions.  There
 271 are many attributes that are needed to define a country's cultural
 272 conventions.  These attributes include beside the country's native
 273 language, the formatting of the date and time, the representation of
 274 numbers, the symbols for currency, etc.  These local <STRONG>rules</STRONG> are
 275 termed the country's locale.  The locale represents the knowledge
 276 needed to support the country's native attributes.
 277
 278 </P>
 279 <P>
 280 There are a few major areas which may vary between countries and
 281 hence, define what a locale must describe.  The following list helps
 282 putting multi-lingual messages into the proper context of other tasks
 283 related to locales, and also presents some other areas which GNU
 284 <CODE>gettext</CODE> might eventually tackle, maybe, one of these days.
 285
 286 </P>
 287 <DL COMPACT>
 288
 289 <DT><EM>Characters and Codesets</EM>
 290 <DD>
 291 The codeset most commonly used through out the USA and most English
 292 speaking parts of the world is the ASCII codeset.  However, there are
 293 many characters needed by various locales that are not found within
 294 this codeset.  The 8-bit ISO 8859-1 code set has most of the special
 295 characters needed to handle the major European languages.  However, in
 296 many cases, the ISO 8859-1 font is not adequate.  Hence each locale
 297 will need to specify which codeset they need to use and will need
 298 to have the appropriate character handling routines to cope with
 299 the codeset.
 300
 301 <DT><EM>Currency</EM>
 302 <DD>
 303 The symbols used vary from country to country as does the position
 304 used by the symbol.  Software needs to be able to transparently
 305 display currency figures in the native mode for each locale.
 306
 307 <DT><EM>Dates</EM>
 308 <DD>
 309 The format of date varies between locales.  For example, Christmas day
 310 in 1994 is written as 12/25/94 in the USA and as 25/12/94 in Australia.
 311 Other countries might use ISO 8061 dates, etc.
 312
 313 Time of the day may be noted as <VAR>hh</VAR>:<VAR>mm</VAR>, <VAR>hh</VAR>.<VAR>mm</VAR>,
 314 or otherwise.  Some locales require time to be specified in 24-hour
 315 mode rather than as AM or PM.  Further, the nature and yearly extent
 316 of the Daylight Saving correction vary widely between countries.
 317
 318 <DT><EM>Numbers</EM>
 319 <DD>
 320 Numbers can be represented differently in different locales.
 321 For example, the following numbers are all written correctly for
 322 their respective locales:
 323
 324
 325 <PRE>
 326 12,345.67       English
 327 12.345,67       French
 328 1,2345.67       Asia
 329 </PRE>
 330
 331 Some programs could go further and use different unit systems, like
 332 English units or Metric units, or even take into account variants
 333 about how numbers are spelled in full.
 334
 335 <DT><EM>Messages</EM>
 336 <DD>
 337 The most obvious area is the language support within a locale.  This is
 338 where GNU <CODE>gettext</CODE> provides the means for developers and users to
 339 easily change the language that the software uses to communicate to
 340 the user.
 341
 342 </DL>
 343
 344 <P>
 345 In the near future we see no chance that components of locale outside of
 346 message handling will be made available for use in other
 347 packages.  The reason for this is that most modern systems provide
 348 a more or less reasonable support for at least some of the missing
 349 components.  Another point is that the GNU <CODE>libc</CODE> and Linux will get
 350 a new and complete implementation of the whole locale functionality
 351 which could be adopted by system lacking a reasonable locale support.
 352
 353 </P>
 354
 355
 356 <H2><A NAME="SEC5" HREF="gettext_toc.html#TOC5">Files Conveying Translations</A></H2>
 357
 358 <P>
 359 The letters PO in <TT>`.po'</TT> files means Portable Object, to
 360 distinguish it from <TT>`.mo'</TT> files, where MO stands for Machine
 361 Object.  This paradigm, as well as the PO file format, is inspired
 362 by the NLS standard developed by Uniforum, and implemented by Sun
 363 in their Solaris system.
 364
 365 </P>
 366 <P>
 367 PO files are meant to be read and edited by humans, and associate each
 368 original, translatable string of a given package with its translation
 369 in a particular target language.  A single PO file is dedicated to
 370 a single target language.  If a package supports many languages,
 371 there is one such PO file per language supported, and each package
 372 has its own set of PO files.  These PO files are best created by
 373 the <CODE>xgettext</CODE> program, and later updated or refreshed through
 374 the <CODE>msgmerge</CODE> program.  Program <CODE>xgettext</CODE> extracts all
 375 marked messages from a set of C files and initializes a PO file with
 376 empty translations.  Program <CODE>msgmerge</CODE> takes care of adjusting
 377 PO files between releases of the corresponding sources, commenting
 378 obsolete entries, initializing new ones, and updating all source
 379 line references.  Files ending with <TT>`.pot'</TT> are kind of base
 380 translation files found in distributions, in PO file format, and
 381 <TT>`.pox'</TT> files are often temporary PO files.
 382
 383 </P>
 384 <P>
 385 MO files are meant to be read by programs, and are binary in nature.
 386 A few systems already offer tools for creating and handling MO files
 387 as part of the Native Language Support coming with the system, but the
 388 format of these MO files is often different from system to system,
 389 and non-portable.  They do not necessary use <TT>`.mo'</TT> for file
 390 extensions, but since system libraries are also used for accessing
 391 these files, it works as long as the system is self-consistent about
 392 it.  If GNU <CODE>gettext</CODE> is able to interface with the tools already
 393 provided with systems, it will consequently let these provided tools
 394 take care of generating the MO files.  Or else, if such tools are not
 395 found or do not seem usable, GNU <CODE>gettext</CODE> will use its own ways
 396 and its own format for MO files.  Files ending with <TT>`.gmo'</TT> are
 397 really MO files, when it is known that these files use the GNU format.
 398
 399 </P>
 400
 401
 402 <H2><A NAME="SEC6" HREF="gettext_toc.html#TOC6">Overview of GNU <CODE>gettext</CODE></A></H2>
 403
 404 <P>
 405 The following diagram summarizes the relation between the files
 406 handled by GNU <CODE>gettext</CODE> and the tools acting on these files.
 407 It is followed by a somewhat detailed explanations, which you should
 408 read while keeping an eye on the diagram.  Having a clear understanding
 409 of these interrelations would surely help programmers, translators
 410 and maintainers.
 411
 412 </P>
 413
 414 <PRE>
 415 Original C Sources ---&#62; PO mode ---&#62; Marked C Sources ---.
 416                                                          |
 417               .---------&#60;--- GNU gettext Library         |
 418 .--- make &#60;---+                                          |
 419 |             `---------&#60;--------------------+-----------'
 420 |                                            |
 421 |   .-----&#60;--- PACKAGE.pot &#60;--- xgettext &#60;---'   .---&#60;--- PO Compendium
 422 |   |                                            |             ^
 423 |   |                                            `---.         |
 424 |   `---.                                            +---&#62; PO mode ---.
 425 |       +----&#62; msgmerge ------&#62; LANG.pox ---&#62;--------'                |
 426 |   .---'                                                             |
 427 |   |                                                                 |
 428 |   `-------------&#60;---------------.                                   |
 429 |                                 +--- LANG.po &#60;--- New LANG.pox &#60;----'
 430 |   .--- LANG.gmo &#60;--- msgfmt &#60;---'
 431 |   |
 432 |   `---&#62; install ---&#62; /.../LANG/PACKAGE.mo ---.
 433 |                                              +---&#62; "Hello world!"
 434 `-------&#62; install ---&#62; /.../bin/PROGRAM -------'
 435 </PRE>
 436
 437 <P>
 438 The indication <SAMP>`PO mode'</SAMP> appears in two places in this picture,
 439 and you may safely read it as merely meaning "hand editing", using
 440 any editor of your choice, really.  However, for those of you being
 441 the lucky users of GNU Emacs, PO mode has been specifically created
 442 for providing a cozy environment for editing or modifying PO files.
 443 While editing a PO file, PO mode allows for the easy browsing of
 444 auxiliary and compendium PO files, as well as for following references into
 445 the set of C program sources from which PO files have been derived.
 446 It has a few special features, among which are the interactive marking
 447 of program strings as translatable, and the validation of PO files
 448 with easy repositioning to PO file lines showing errors.
 449
 450 </P>
 451 <P>
 452 As a programmer, the first step to bringing GNU <CODE>gettext</CODE>
 453 into your package is identifying, right in the C sources, those strings
 454 which are meant to be translatable, and those which are untranslatable.
 455 This tedious job can be done a little more comfortably using emacs PO
 456 mode, but you can use any means familiar to you for modifying your
 457 C sources.  Beside this some other simple, standard changes are needed to
 458 properly initialize the translation library.  See section <A HREF="gettext_3.html#SEC13">Preparing Program Sources</A>, for
 459 more information about all this.
 460
 461 </P>
 462 <P>
 463 For newly written software the strings of course can and should be
 464 marked while writing the it.  The <CODE>gettext</CODE> approach makes this
 465 very easy.  Simply put the following lines at the beginning of each file
 466 or in a central header file:
 467
 468 </P>
 469
 470 <PRE>
 471 #define _(String) (String)
 472 #define N_(String) (String)
 473 #define textdomain(Domain)
 474 #define bindtextdomain(Package, Directory)
 475 </PRE>
 476
 477 <P>
 478 Doing this allows you to prepare the sources for internationalization.
 479 Later when you feel ready for the step to use the <CODE>gettext</CODE> library
 480 simply remove these definitions, include <TT>`libintl.h'</TT> and link
 481 against <TT>`libintl.a'</TT>.  That is all you have to change.
 482
 483 </P>
 484 <P>
 485 Once the C sources have been modified, the <CODE>xgettext</CODE> program
 486 is used to find and extract all translatable strings, and create an
 487 initial PO file out of all these.  This <TT>`<VAR>package</VAR>.pot'</TT> file
 488 contains all original program strings.  It has sets of pointers to
 489 exactly where in C sources each string is used.  All translations
 490 are set to empty.  The letter <KBD>t</KBD> in <TT>`.pot'</TT> marks this as
 491 a Template PO file, not yet oriented towards any particular language.
 492 See section <A HREF="gettext_4.html#SEC20">Invoking the <CODE>xgettext</CODE> Program</A>, for more details about how one calls the
 493 <CODE>xgettext</CODE> program.  If you are <EM>really</EM> lazy, you might
 494 be interested at working a lot more right away, and preparing the
 495 whole distribution setup (see section <A HREF="gettext_10.html#SEC67">The Maintainer's View</A>).  By doing so, you
 496 spare yourself typing the <CODE>xgettext</CODE> command, as <CODE>make</CODE>
 497 should now generate the proper things automatically for you!
 498
 499 </P>
 500 <P>
 501 The first time through, there is no <TT>`<VAR>lang</VAR>.po'</TT> yet, so the
 502 <CODE>msgmerge</CODE> step may be skipped and replaced by a mere copy of
 503 <TT>`<VAR>package</VAR>.pot'</TT> to <TT>`<VAR>lang</VAR>.pox'</TT>, where <VAR>lang</VAR>
 504 represents the target language.
 505
 506 </P>
 507 <P>
 508 Then comes the initial translation of messages.  Translation in
 509 itself is a whole matter, still exclusively meant for humans,
 510 and whose complexity far overwhelms the level of this manual.
 511 Nevertheless, a few hints are given in some other chapter of this
 512 manual (see section <A HREF="gettext_9.html#SEC56">The Translator's View</A>).  You will also find there indications
 513 about how to contact translating teams, or becoming part of them,
 514 for sharing your translating concerns with others who target the same
 515 native language.
 516
 517 </P>
 518 <P>
 519 While adding the translated messages into the <TT>`<VAR>lang</VAR>.pox'</TT>
 520 PO file, if you do not have GNU Emacs handy, you are on your own
 521 for ensuring that your efforts fully respect the PO file format, and quoting
 522 conventions (see section <A HREF="gettext_2.html#SEC9">The Format of PO Files</A>).  This is surely not an impossible task,
 523 as this is the way many people have handled PO files already for Uniforum or
 524 Solaris.  On the other hand, by using PO mode in GNU Emacs, most details
 525 of PO file format are taken care of for you, but you have to acquire
 526 some familiarity with PO mode itself.  Besides main PO mode commands
 527 (see section <A HREF="gettext_2.html#SEC10">Main PO mode Commands</A>), you should know how to move between entries
 528 (see section <A HREF="gettext_2.html#SEC11">Entry Positioning</A>), and how to handle untranslated entries
 529 (see section <A HREF="gettext_5.html#SEC27">Untranslated Entries</A>).
 530
 531 </P>
 532 <P>
 533 If some common translations have already been saved into a compendium
 534 PO file, translators may use PO mode for initializing untranslated
 535 entries from the compendium, and also save selected translations into
 536 the compendium, updating it (see section <A HREF="gettext_4.html#SEC22">Using Translation Compendiums</A>).  Compendium files
 537 are meant to be exchanged between members of a given translation team.
 538
 539 </P>
 540 <P>
 541 Programs, or packages of programs, are dynamic in nature: users write
 542 bug reports and suggestion for improvements, maintainers react by
 543 modifying programs in various ways.  The fact that a package has
 544 already been internationalized should not make maintainers shy
 545 of adding new strings, or modifying strings already translated.
 546 They just do their job the best they can.  For the Translation
 547 Project to work smoothly, it is important that maintainers do not
 548 carry translation concerns on their already loaded shoulders, and that
 549 translators be kept as free as possible of programmatic concerns.
 550
 551 </P>
 552 <P>
 553 The only concern maintainers should have is carefully marking new
 554 strings as translatable, when they should be, and do not otherwise
 555 worry about them being translated, as this will come in proper time.
 556 Consequently, when programs and their strings are adjusted in various
 557 ways by maintainers, and for matters usually unrelated to translation,
 558 <CODE>xgettext</CODE> would construct <TT>`<VAR>package</VAR>.pot'</TT> files which are
 559 evolving over time, so the translations carried by <TT>`<VAR>lang</VAR>.po'</TT>
 560 are slowly fading out of date.
 561
 562 </P>
 563 <P>
 564 It is important for translators (and even maintainers) to understand
 565 that package translation is a continuous process in the lifetime of a
 566 package, and not something which is done once and for all at the start.
 567 After an initial burst of translation activity for a given package,
 568 interventions are needed once in a while, because here and there,
 569 translated entries become obsolete, and new untranslated entries
 570 appear, needing translation.
 571
 572 </P>
 573 <P>
 574 The <CODE>msgmerge</CODE> program has the purpose of refreshing an already
 575 existing <TT>`<VAR>lang</VAR>.po'</TT> file, by comparing it with a newer
 576 <TT>`<VAR>package</VAR>.pot'</TT> template file, extracted by <CODE>xgettext</CODE>
 577 out of recent C sources.  The refreshing operation adjusts all
 578 references to C source locations for strings, since these strings
 579 move as programs are modified.  Also, <CODE>msgmerge</CODE> comments out as
 580 obsolete, in <TT>`<VAR>lang</VAR>.pox'</TT>, those already translated entries
 581 which are no longer used in the program sources (see section <A HREF="gettext_5.html#SEC28">Obsolete Entries</A>).  It finally discovers new strings and inserts them in
 582 the resulting PO file as untranslated entries (see section <A HREF="gettext_5.html#SEC27">Untranslated Entries</A>).  See section <A HREF="gettext_5.html#SEC24">Invoking the <CODE>msgmerge</CODE> Program</A>, for more information about what
 583 <CODE>msgmerge</CODE> really does.
 584
 585 </P>
 586 <P>
 587 Whatever route or means taken, the goal is to obtain an updated
 588 <TT>`<VAR>lang</VAR>.pox'</TT> file offering translations for all strings.
 589 When this is properly achieved, this file <TT>`<VAR>lang</VAR>.pox'</TT> may
 590 take the place of the previous official <TT>`<VAR>lang</VAR>.po'</TT> file.
 591
 592 </P>
 593 <P>
 594 The temporal mobility, or fluidity of PO files, is an integral part of
 595 the translation game, and should be well understood, and accepted.
 596 People resisting it will have a hard time participating in the
 597 Translation Project, or will give a hard time to other participants!  In
 598 particular, maintainers should relax and include all available official
 599 PO files in their distributions, even if these have not recently been
 600 updated, without banging or otherwise trying to exert pressure on the
 601 translator teams to get the job done.  The pressure should rather come
 602 from the community of users speaking a particular language, and
 603 maintainers should consider themselves fairly relieved of any concern
 604 about the adequacy of translation files.  On the other hand, translators
 605 should reasonably try updating the PO files they are responsible for,
 606 while the package is undergoing pretest, prior to an official
 607 distribution.
 608
 609 </P>
 610 <P>
 611 Once the PO file is complete and dependable, the <CODE>msgfmt</CODE> program
 612 is used for turning the PO file into a machine-oriented format, which
 613 may yield efficient retrieval of translations by the programs of the
 614 package, whenever needed at runtime (see section <A HREF="gettext_6.html#SEC34">The Format of GNU MO Files</A>).  See section <A HREF="gettext_6.html#SEC33">Invoking the <CODE>msgfmt</CODE> Program</A>, for more information about all modalities of execution
 615 for the <CODE>msgfmt</CODE> program.
 616
 617 </P>
 618 <P>
 619 Finally, the modified and marked C sources are compiled and linked
 620 with the GNU <CODE>gettext</CODE> library, usually through the operation of
 621 <CODE>make</CODE>, given a suitable <TT>`Makefile'</TT> exists for the project,
 622 and the resulting executable is installed somewhere users will find it.
 623 The MO files themselves should also be properly installed.  Given the
 624 appropriate environment variables are set (see section <A HREF="gettext_7.html#SEC38">Magic for End Users</A>), the
 625 program should localize itself automatically, whenever it executes.
 626
 627 </P>
 628 <P>
 629 The remainder of this manual has the purpose of explaining in depth the various
 630 steps outlined above.
 631
 632 </P>
 633 <P><HR><P>
 634 <p>Go to the first, previous, <A HREF="gettext_2.html">next</A>, <A HREF="gettext_12.html">last</A> section, <A HREF="gettext_toc.html">table of contents</A>.
 635 </BODY>
 636 </HTML>