gnu/dist/gettext/gettext-tools/doc/gettext_1.html

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