Mercurial > repos > rliterman > csp2

comparison CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/share/doc/gettext/gettext_1.html @ 68:5028fdace37b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 16:23:26 -0400
parents
children
comparison
equal deleted inserted replaced
67:0e9998148a16 68:5028fdace37b
1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd">
2 <html>
3 <!-- Created on February, 21 2024 by texi2html 1.78a -->
4 <!--
5 Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
6 Karl Berry <karl@freefriends.org>
7 Olaf Bachmann <obachman@mathematik.uni-kl.de>
8 and many others.
9 Maintained by: Many creative people.
10 Send bugs and suggestions to <texi2html-bug@nongnu.org>
11
12 -->
13 <head>
14 <title>GNU gettext utilities: 1. Introduction</title>
15
16 <meta name="description" content="GNU gettext utilities: 1. Introduction">
17 <meta name="keywords" content="GNU gettext utilities: 1. Introduction">
18 <meta name="resource-type" content="document">
19 <meta name="distribution" content="global">
20 <meta name="Generator" content="texi2html 1.78a">
21 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
22 <style type="text/css">
23 <!--
24 a.summary-letter {text-decoration: none}
25 pre.display {font-family: serif}
26 pre.format {font-family: serif}
27 pre.menu-comment {font-family: serif}
28 pre.menu-preformatted {font-family: serif}
29 pre.smalldisplay {font-family: serif; font-size: smaller}
30 pre.smallexample {font-size: smaller}
31 pre.smallformat {font-family: serif; font-size: smaller}
32 pre.smalllisp {font-size: smaller}
33 span.roman {font-family:serif; font-weight:normal;}
34 span.sansserif {font-family:sans-serif; font-weight:normal;}
35 ul.toc {list-style: none}
36 -->
37 </style>
38
39
40 </head>
41
42 <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
43
44 <table cellpadding="1" cellspacing="1" border="0">
45 <tr><td valign="middle" align="left">[ &lt;&lt; ]</td>
46 <td valign="middle" align="left">[<a href="gettext_2.html#SEC7" title="Next chapter"> &gt;&gt; </a>]</td>
47 <td valign="middle" align="left"> &nbsp; </td>
48 <td valign="middle" align="left"> &nbsp; </td>
49 <td valign="middle" align="left"> &nbsp; </td>
50 <td valign="middle" align="left"> &nbsp; </td>
51 <td valign="middle" align="left"> &nbsp; </td>
52 <td valign="middle" align="left">[<a href="gettext_toc.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
53 <td valign="middle" align="left">[<a href="gettext_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
54 <td valign="middle" align="left">[<a href="gettext_21.html#SEC389" title="Index">Index</a>]</td>
55 <td valign="middle" align="left">[<a href="gettext_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
56 </tr></table>
57
58 <hr size="2">
59 <a name="Introduction"></a>
60 <a name="SEC1"></a>
61 <h1 class="chapter"> <a href="gettext_toc.html#TOC1">1. Introduction</a> </h1>
62
63 <p>This chapter explains the goals sought in the creation
64 of GNU <code>gettext</code> and the free Translation Project.
65 Then, it explains a few broad concepts around
66 Native Language Support, and positions message translation with regard
67 to other aspects of national and cultural variance, as they apply
68 to programs. It also surveys those files used to convey the
69 translations. It explains how the various tools interact in the
70 initial generation of these files, and later, how the maintenance
71 cycle should usually operate.
72 </p>
73 <a name="IDX1"></a>
74 <a name="IDX2"></a>
75 <a name="IDX3"></a>
76 <p>In this manual, we use <em>he</em> when speaking of the programmer or
77 maintainer, <em>she</em> when speaking of the translator, and <em>they</em>
78 when speaking of the installers or end users of the translated program.
79 This is only a convenience for clarifying the documentation. It is
80 <em>absolutely</em> not meant to imply that some roles are more appropriate
81 to males or females. Besides, as you might guess, GNU <code>gettext</code>
82 is meant to be useful for people using computers, whatever their sex,
83 race, religion or nationality!
84 </p>
85 <a name="IDX4"></a>
86 <p>Please submit suggestions and corrections
87 </p><ul>
88 <li>
89 either in the bug tracker at <a href="https://savannah.gnu.org/projects/gettext">https://savannah.gnu.org/projects/gettext</a>
90 </li><li>
91 or by email to <code>bug-gettext@gnu.org</code>.
92 </li></ul>
93
94 <p>Please include the manual's edition number and update date in your messages.
95 </p>
96
97
98 <a name="Why"></a>
99 <a name="SEC2"></a>
100 <h2 class="section"> <a href="gettext_toc.html#TOC2">1.1 The Purpose of GNU <code>gettext</code></a> </h2>
101
102 <p>Usually, programs are written and documented in English, and use
103 English at execution time to interact with users. This is true
104 not only of GNU software, but also of a great deal of proprietary
105 and free software. Using a common language is quite handy for
106 communication between developers, maintainers and users from all
107 countries. On the other hand, most people are less comfortable with
108 English than with their own native language, and would prefer to
109 use their mother tongue for day to day's work, as far as possible.
110 Many would simply <em>love</em> to see their computer screen showing
111 a lot less of English, and far more of their own language.
112 </p>
113 <a name="IDX5"></a>
114 <p>However, to many people, this dream might appear so far fetched that
115 they may believe it is not even worth spending time thinking about
116 it. They have no confidence at all that the dream might ever
117 become true. Yet some have not lost hope, and have organized themselves.
118 The Translation Project is a formalization of this hope into a
119 workable structure, which has a good chance to get all of us nearer
120 the achievement of a truly multi-lingual set of programs.
121 </p>
122 <p>GNU <code>gettext</code> is an important step for the Translation Project,
123 as it is an asset on which we may build many other steps. This package
124 offers to programmers, translators and even users, a well integrated
125 set of tools and documentation. Specifically, the GNU <code>gettext</code>
126 utilities are a set of tools that provides a framework within which
127 other free packages may produce multi-lingual messages. These tools
128 include
129 </p>
130 <ul>
131 <li>
132 A set of conventions about how programs should be written to support
133 message catalogs.
134
135 </li><li>
136 A directory and file naming organization for the message catalogs
137 themselves.
138
139 </li><li>
140 A runtime library supporting the retrieval of translated messages.
141
142 </li><li>
143 A few stand-alone programs to massage in various ways the sets of
144 translatable strings, or already translated strings.
145
146 </li><li>
147 A library supporting the parsing and creation of files containing
148 translated messages.
149
150 </li><li>
151 A special mode for Emacs<a name="DOCF1" href="gettext_fot.html#FOOT1">(1)</a> which helps preparing these sets
152 and bringing them up to date.
153 </li></ul>
154
155 <p>GNU <code>gettext</code> is designed to minimize the impact of
156 internationalization on program sources, keeping this impact as small
157 and hardly noticeable as possible. Internationalization has better
158 chances of succeeding if it is very light weighted, or at least,
159 appear to be so, when looking at program sources.
160 </p>
161 <p>The Translation Project also uses the GNU <code>gettext</code> distribution
162 as a vehicle for documenting its structure and methods. This goes
163 beyond the strict technicalities of documenting the GNU <code>gettext</code>
164 proper. By so doing, translators will find in a single place, as
165 far as possible, all they need to know for properly doing their
166 translating work. Also, this supplemental documentation might also
167 help programmers, and even curious users, in understanding how GNU
168 <code>gettext</code> is related to the remainder of the Translation
169 Project, and consequently, have a glimpse at the <em>big picture</em>.
170 </p>
171
172 <a name="Concepts"></a>
173 <a name="SEC3"></a>
174 <h2 class="section"> <a href="gettext_toc.html#TOC3">1.2 I18n, L10n, and Such</a> </h2>
175
176 <p>Two long words appear all the time when we discuss support of native
177 language in programs, and these words have a precise meaning, worth
178 being explained here, once and for all in this document. The words are
179 <em>internationalization</em> and <em>localization</em>. Many people,
180 tired of writing these long words over and over again, took the
181 habit of writing <em>i18n</em> and <em>l10n</em> instead, quoting the first
182 and last letter of each word, and replacing the run of intermediate
183 letters by a number merely telling how many such letters there are.
184 But in this manual, in the sake of clarity, we will patiently write
185 the names in full, each time&hellip;
186 </p>
187 <a name="IDX6"></a>
188 <p>By <em>internationalization</em>, one refers to the operation by which a
189 program, or a set of programs turned into a package, is made aware of and
190 able to support multiple languages. This is a generalization process,
191 by which the programs are untied from calling only English strings or
192 other English specific habits, and connected to generic ways of doing
193 the same, instead. Program developers may use various techniques to
194 internationalize their programs. Some of these have been standardized.
195 GNU <code>gettext</code> offers one of these standards. See section <a href="gettext_11.html#SEC197">The Programmer's View</a>.
196 </p>
197 <a name="IDX7"></a>
198 <p>By <em>localization</em>, one means the operation by which, in a set
199 of programs already internationalized, one gives the program all
200 needed information so that it can adapt itself to handle its input
201 and output in a fashion which is correct for some native language and
202 cultural habits. This is a particularisation process, by which generic
203 methods already implemented in an internationalized program are used
204 in specific ways. The programming environment puts several functions
205 to the programmers disposal which allow this runtime configuration.
206 The formal description of specific set of cultural habits for some
207 country, together with all associated translations targeted to the
208 same native language, is called the <em>locale</em> for this language
209 or country. Users achieve localization of programs by setting proper
210 values to special environment variables, prior to executing those
211 programs, identifying which locale should be used.
212 </p>
213 <p>In fact, locale message support is only one component of the cultural
214 data that makes up a particular locale. There are a whole host of
215 routines and functions provided to aid programmers in developing
216 internationalized software and which allow them to access the data
217 stored in a particular locale. When someone presently refers to a
218 particular locale, they are obviously referring to the data stored
219 within that particular locale. Similarly, if a programmer is referring
220 to &ldquo;accessing the locale routines&rdquo;, they are referring to the
221 complete suite of routines that access all of the locale's information.
222 </p>
223 <a name="IDX8"></a>
224 <a name="IDX9"></a>
225 <a name="IDX10"></a>
226 <p>One uses the expression <em>Native Language Support</em>, or merely NLS,
227 for speaking of the overall activity or feature encompassing both
228 internationalization and localization, allowing for multi-lingual
229 interactions in a program. In a nutshell, one could say that
230 internationalization is the operation by which further localizations
231 are made possible.
232 </p>
233 <p>Also, very roughly said, when it comes to multi-lingual messages,
234 internationalization is usually taken care of by programmers, and
235 localization is usually taken care of by translators.
236 </p>
237
238 <a name="Aspects"></a>
239 <a name="SEC4"></a>
240 <h2 class="section"> <a href="gettext_toc.html#TOC4">1.3 Aspects in Native Language Support</a> </h2>
241
242 <p>For a totally multi-lingual distribution, there are many things to
243 translate beyond output messages.
244 </p>
245 <ul>
246 <li>
247 As of today, GNU <code>gettext</code> offers a complete toolset for
248 translating messages output by C programs. Perl scripts and shell
249 scripts will also need to be translated. Even if there are today some hooks
250 by which this can be done, these hooks are not integrated as well as they
251 should be.
252
253 </li><li>
254 Some programs, like <code>autoconf</code> or <code>bison</code>, are able
255 to produce other programs (or scripts). Even if the generating
256 programs themselves are internationalized, the generated programs they
257 produce may need internationalization on their own, and this indirect
258 internationalization could be automated right from the generating
259 program. In fact, quite usually, generating and generated programs
260 could be internationalized independently, as the effort needed is
261 fairly orthogonal.
262
263 </li><li>
264 A few programs include textual tables which might need translation
265 themselves, independently of the strings contained in the program
266 itself. For example, RFC 1345 gives an English description for each
267 character which the <code>recode</code> program is able to reconstruct at execution.
268 Since these descriptions are extracted from the RFC by mechanical means,
269 translating them properly would require a prior translation of the RFC
270 itself.
271
272 </li><li>
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><li>
278 Many programs read, interpret, compile, or are somewhat driven by
279 input files which are texts containing keywords, identifiers, or
280 replies which are inherently translatable. For example, one may want
281 <code>gcc</code> to allow diacriticized characters in identifiers or use
282 translated keywords; &lsquo;<samp>rm -i</samp>&rsquo; might accept something else than
283 &lsquo;<samp>y</samp>&rsquo; or &lsquo;<samp>n</samp>&rsquo; for replies, etc. Even if the program will
284 eventually make most of its output in the foreign languages, one has
285 to decide whether the input syntax, option values, etc., are to be
286 localized or not.
287
288 </li><li>
289 The manual accompanying a package, as well as all documentation files
290 in the distribution, could surely be translated, too. Translating a
291 manual, with the intent of later keeping up with updates, is a major
292 undertaking in itself, generally.
293
294 </li></ul>
295
296 <p>As we already stressed, translation is only one aspect of locales.
297 Other internationalization aspects are system services and are handled
298 in GNU <code>libc</code>. There
299 are many attributes that are needed to define a country's cultural
300 conventions. These attributes include beside the country's native
301 language, the formatting of the date and time, the representation of
302 numbers, the symbols for currency, etc. These local <em>rules</em> are
303 termed the country's locale. The locale represents the knowledge
304 needed to support the country's native attributes.
305 </p>
306 <a name="IDX11"></a>
307 <p>There are a few major areas which may vary between countries and
308 hence, define what a locale must describe. The following list helps
309 putting multi-lingual messages into the proper context of other tasks
310 related to locales. See the GNU <code>libc</code> manual for details.
311 </p>
312 <dl compact="compact">
313 <dt> <em>Characters and Codesets</em></dt>
314 <dd><a name="IDX12"></a>
315 <a name="IDX13"></a>
316 <a name="IDX14"></a>
317 <a name="IDX15"></a>
318
319 <p>The codeset most commonly used through out the USA and most English
320 speaking parts of the world is the ASCII codeset. However, there are
321 many characters needed by various locales that are not found within
322 this codeset. The 8-bit ISO 8859-1 code set has most of the special
323 characters needed to handle the major European languages. However, in
324 many cases, choosing ISO 8859-1 is nevertheless not adequate: it
325 doesn't even handle the major European currency. Hence each locale
326 will need to specify which codeset they need to use and will need
327 to have the appropriate character handling routines to cope with
328 the codeset.
329 </p>
330 </dd>
331 <dt> <em>Currency</em></dt>
332 <dd><a name="IDX16"></a>
333 <a name="IDX17"></a>
334
335 <p>The symbols used vary from country to country as does the position
336 used by the symbol. Software needs to be able to transparently
337 display currency figures in the native mode for each locale.
338 </p>
339 </dd>
340 <dt> <em>Dates</em></dt>
341 <dd><a name="IDX18"></a>
342 <a name="IDX19"></a>
343
344 <p>The format of date varies between locales. For example, Christmas day
345 in 1994 is written as 12/25/94 in the USA and as 25/12/94 in Australia.
346 Other countries might use ISO 8601 dates, etc.
347 </p>
348 <p>Time of the day may be noted as <var>hh</var>:<var>mm</var>, <var>hh</var>.<var>mm</var>,
349 or otherwise. Some locales require time to be specified in 24-hour
350 mode rather than as AM or PM. Further, the nature and yearly extent
351 of the Daylight Saving correction vary widely between countries.
352 </p>
353 </dd>
354 <dt> <em>Numbers</em></dt>
355 <dd><a name="IDX20"></a>
356 <a name="IDX21"></a>
357
358 <p>Numbers can be represented differently in different locales.
359 For example, the following numbers are all written correctly for
360 their respective locales:
361 </p>
362 <table><tr><td>&nbsp;</td><td><pre class="example">12,345.67 English
363 12.345,67 German
364 12345,67 French
365 1,2345.67 Asia
366 </pre></td></tr></table>
367
368 <p>Some programs could go further and use different unit systems, like
369 English units or Metric units, or even take into account variants
370 about how numbers are spelled in full.
371 </p>
372 </dd>
373 <dt> <em>Messages</em></dt>
374 <dd><a name="IDX22"></a>
375 <a name="IDX23"></a>
376
377 <p>The most obvious area is the language support within a locale. This is
378 where GNU <code>gettext</code> provides the means for developers and users to
379 easily change the language that the software uses to communicate to
380 the user.
381 </p>
382 </dd>
383 </dl>
384
385 <a name="IDX24"></a>
386 <p>These areas of cultural conventions are called <em>locale categories</em>.
387 It is an unfortunate term; <em>locale aspects</em> or <em>locale feature
388 categories</em> would be a better term, because each &ldquo;locale category&rdquo;
389 describes an area or task that requires localization. The concrete data
390 that describes the cultural conventions for such an area and for a particular
391 culture is also called a <em>locale category</em>. In this sense, a locale
392 is composed of several locale categories: the locale category describing
393 the codeset, the locale category describing the formatting of numbers,
394 the locale category containing the translated messages, and so on.
395 </p>
396 <a name="IDX25"></a>
397 <p>Components of locale outside of message handling are standardized in
398 the ISO C standard and the POSIX:2001 standard (also known as the SUSV3
399 specification). GNU <code>libc</code>
400 fully implements this, and most other modern systems provide a more
401 or less reasonable support for at least some of the missing components.
402 </p>
403
404 <a name="Files"></a>
405 <a name="SEC5"></a>
406 <h2 class="section"> <a href="gettext_toc.html#TOC5">1.4 Files Conveying Translations</a> </h2>
407
408 <p>The letters PO in &lsquo;<tt>.po</tt>&rsquo; files means Portable Object, to
409 distinguish it from &lsquo;<tt>.mo</tt>&rsquo; 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 </p>
414 <p>PO files are meant to be read and edited by humans, and associate each
415 original, translatable string of a given package with its translation
416 in a particular target language. A single PO file is dedicated to
417 a single target language. If a package supports many languages,
418 there is one such PO file per language supported, and each package
419 has its own set of PO files. These PO files are best created by
420 the <code>xgettext</code> program, and later updated or refreshed through
421 the <code>msgmerge</code> program. Program <code>xgettext</code> extracts all
422 marked messages from a set of C files and initializes a PO file with
423 empty translations. Program <code>msgmerge</code> takes care of adjusting
424 PO files between releases of the corresponding sources, commenting
425 obsolete entries, initializing new ones, and updating all source
426 line references. Files ending with &lsquo;<tt>.pot</tt>&rsquo; are kind of base
427 translation files found in distributions, in PO file format.
428 </p>
429 <p>MO files are meant to be read by programs, and are binary in nature.
430 A few systems already offer tools for creating and handling MO files
431 as part of the Native Language Support coming with the system, but the
432 format of these MO files is often different from system to system,
433 and non-portable. The tools already provided with these systems don't
434 support all the features of GNU <code>gettext</code>. Therefore GNU
435 <code>gettext</code> uses its own format for MO files. Files ending with
436 &lsquo;<tt>.gmo</tt>&rsquo; are really MO files, when it is known that these files use
437 the GNU format.
438 </p>
439
440 <a name="Overview"></a>
441 <a name="SEC6"></a>
442 <h2 class="section"> <a href="gettext_toc.html#TOC6">1.5 Overview of GNU <code>gettext</code></a> </h2>
443
444 <p>The following diagram summarizes the relation between the files
445 handled by GNU <code>gettext</code> and the tools acting on these files.
446 It is followed by somewhat detailed explanations, which you should
447 read while keeping an eye on the diagram. Having a clear understanding
448 of these interrelations will surely help programmers, translators
449 and maintainers.
450 </p>
451 <table><tr><td>&nbsp;</td><td><pre class="example">Original C Sources ───&gt; Preparation ───&gt; Marked C Sources ───╮
452 │
453 ╭─────────&lt;─── GNU gettext Library │
454 ╭─── make &lt;───┤ │
455 │ ╰─────────&lt;────────────────────┬───────────────╯
456 │ │
457 │ ╭─────&lt;─── PACKAGE.pot &lt;─── xgettext &lt;───╯ ╭───&lt;─── PO Compendium
458 │ │ │ ↑
459 │ │ ╰───╮ │
460 │ ╰───╮ ├───&gt; PO editor ───╮
461 │ ├────&gt; msgmerge ──────&gt; LANG.po ────&gt;────────╯ │
462 │ ╭───╯ │
463 │ │ │
464 │ ╰─────────────&lt;───────────────╮ │
465 │ ├─── New LANG.po &lt;────────────────────╯
466 │ ╭─── LANG.gmo &lt;─── msgfmt &lt;───╯
467 │ │
468 │ ╰───&gt; install ───&gt; /.../LANG/PACKAGE.mo ───╮
469 │ ├───&gt; &quot;Hello world!&quot;
470 ╰───────&gt; install ───&gt; /.../bin/PROGRAM ───────╯
471 </pre></td></tr></table>
472
473 <a name="IDX26"></a>
474 <p>As a programmer, the first step to bringing GNU <code>gettext</code>
475 into your package is identifying, right in the C sources, those strings
476 which are meant to be translatable, and those which are untranslatable.
477 This tedious job can be done a little more comfortably using emacs PO
478 mode, but you can use any means familiar to you for modifying your
479 C sources. Beside this some other simple, standard changes are needed to
480 properly initialize the translation library. See section <a href="gettext_4.html#SEC17">Preparing Program Sources</a>, for
481 more information about all this.
482 </p>
483 <p>For newly written software the strings of course can and should be
484 marked while writing it. The <code>gettext</code> approach makes this
485 very easy. Simply put the following lines at the beginning of each file
486 or in a central header file:
487 </p>
488 <table><tr><td>&nbsp;</td><td><pre class="example">#define _(String) (String)
489 #define N_(String) String
490 #define textdomain(Domain)
491 #define bindtextdomain(Package, Directory)
492 </pre></td></tr></table>
493
494 <p>Doing this allows you to prepare the sources for internationalization.
495 Later when you feel ready for the step to use the <code>gettext</code> library
496 simply replace these definitions by the following:
497 </p>
498 <a name="IDX27"></a>
499 <table><tr><td>&nbsp;</td><td><pre class="example">#include &lt;libintl.h&gt;
500 #define _(String) gettext (String)
501 #define gettext_noop(String) String
502 #define N_(String) gettext_noop (String)
503 </pre></td></tr></table>
504
505 <a name="IDX28"></a>
506 <a name="IDX29"></a>
507 <p>and link against &lsquo;<tt>libintl.a</tt>&rsquo; or &lsquo;<tt>libintl.so</tt>&rsquo;. Note that on
508 GNU systems, you don't need to link with <code>libintl</code> because the
509 <code>gettext</code> library functions are already contained in GNU libc.
510 That is all you have to change.
511 </p>
512 <a name="IDX30"></a>
513 <a name="IDX31"></a>
514 <p>Once the C sources have been modified, the <code>xgettext</code> program
515 is used to find and extract all translatable strings, and create a
516 PO template file out of all these. This &lsquo;<tt><var>package</var>.pot</tt>&rsquo; file
517 contains all original program strings. It has sets of pointers to
518 exactly where in C sources each string is used. All translations
519 are set to empty. The letter <code>t</code> in &lsquo;<tt>.pot</tt>&rsquo; marks this as
520 a Template PO file, not yet oriented towards any particular language.
521 See section <a href="gettext_5.html#SEC36">Invoking the <code>xgettext</code> Program</a>, for more details about how one calls the
522 <code>xgettext</code> program. If you are <em>really</em> lazy, you might
523 be interested at working a lot more right away, and preparing the
524 whole distribution setup (see section <a href="gettext_13.html#SEC230">The Maintainer's View</a>). By doing so, you
525 spare yourself typing the <code>xgettext</code> command, as <code>make</code>
526 should now generate the proper things automatically for you!
527 </p>
528 <p>The first time through, there is no &lsquo;<tt><var>lang</var>.po</tt>&rsquo; yet, so the
529 <code>msgmerge</code> step may be skipped and replaced by a mere copy of
530 &lsquo;<tt><var>package</var>.pot</tt>&rsquo; to &lsquo;<tt><var>lang</var>.po</tt>&rsquo;, where <var>lang</var>
531 represents the target language. See <a href="gettext_6.html#SEC45">Creating a New PO File</a> for details.
532 </p>
533 <p>Then comes the initial translation of messages. Translation in
534 itself is a whole matter, still exclusively meant for humans,
535 and whose complexity far overwhelms the level of this manual.
536 Nevertheless, a few hints are given in some other chapter of this
537 manual (see section <a href="gettext_12.html#SEC217">The Translator's View</a>). You will also find there indications
538 about how to contact translating teams, or becoming part of them,
539 for sharing your translating concerns with others who target the same
540 native language.
541 </p>
542 <p>While adding the translated messages into the &lsquo;<tt><var>lang</var>.po</tt>&rsquo;
543 PO file, if you are not using one of the dedicated PO file editors
544 (see section <a href="gettext_8.html#SEC63">Editing PO Files</a>), you are on your own
545 for ensuring that your efforts fully respect the PO file format, and quoting
546 conventions (see section <a href="gettext_3.html#SEC16">The Format of PO Files</a>). This is surely not an impossible task,
547 as this is the way many people have handled PO files around 1995.
548 On the other hand, by using a PO file editor, most details
549 of PO file format are taken care of for you, but you have to acquire
550 some familiarity with PO file editor itself.
551 </p>
552 <p>If some common translations have already been saved into a compendium
553 PO file, translators may use PO mode for initializing untranslated
554 entries from the compendium, and also save selected translations into
555 the compendium, updating it (see section <a href="gettext_8.html#SEC80">Using Translation Compendia</a>). Compendium files
556 are meant to be exchanged between members of a given translation team.
557 </p>
558 <p>Programs, or packages of programs, are dynamic in nature: users write
559 bug reports and suggestion for improvements, maintainers react by
560 modifying programs in various ways. The fact that a package has
561 already been internationalized should not make maintainers shy
562 of adding new strings, or modifying strings already translated.
563 They just do their job the best they can. For the Translation
564 Project to work smoothly, it is important that maintainers do not
565 carry translation concerns on their already loaded shoulders, and that
566 translators be kept as free as possible of programming concerns.
567 </p>
568 <p>The only concern maintainers should have is carefully marking new
569 strings as translatable, when they should be, and do not otherwise
570 worry about them being translated, as this will come in proper time.
571 Consequently, when programs and their strings are adjusted in various
572 ways by maintainers, and for matters usually unrelated to translation,
573 <code>xgettext</code> would construct &lsquo;<tt><var>package</var>.pot</tt>&rsquo; files which are
574 evolving over time, so the translations carried by &lsquo;<tt><var>lang</var>.po</tt>&rsquo;
575 are slowly fading out of date.
576 </p>
577 <a name="IDX32"></a>
578 <p>It is important for translators (and even maintainers) to understand
579 that package translation is a continuous process in the lifetime of a
580 package, and not something which is done once and for all at the start.
581 After an initial burst of translation activity for a given package,
582 interventions are needed once in a while, because here and there,
583 translated entries become obsolete, and new untranslated entries
584 appear, needing translation.
585 </p>
586 <p>The <code>msgmerge</code> program has the purpose of refreshing an already
587 existing &lsquo;<tt><var>lang</var>.po</tt>&rsquo; file, by comparing it with a newer
588 &lsquo;<tt><var>package</var>.pot</tt>&rsquo; template file, extracted by <code>xgettext</code>
589 out of recent C sources. The refreshing operation adjusts all
590 references to C source locations for strings, since these strings
591 move as programs are modified. Also, <code>msgmerge</code> comments out as
592 obsolete, in &lsquo;<tt><var>lang</var>.po</tt>&rsquo;, those already translated entries
593 which are no longer used in the program sources (see section <a href="gettext_8.html#SEC74">Obsolete Entries</a>). It finally discovers new strings and inserts them in
594 the resulting PO file as untranslated entries (see section <a href="gettext_8.html#SEC73">Untranslated Entries</a>). See section <a href="gettext_7.html#SEC54">Invoking the <code>msgmerge</code> Program</a>, for more information about what
595 <code>msgmerge</code> really does.
596 </p>
597 <p>Whatever route or means taken, the goal is to obtain an updated
598 &lsquo;<tt><var>lang</var>.po</tt>&rsquo; file offering translations for all strings.
599 </p>
600 <p>The temporal mobility, or fluidity of PO files, is an integral part of
601 the translation game, and should be well understood, and accepted.
602 People resisting it will have a hard time participating in the
603 Translation Project, or will give a hard time to other participants! In
604 particular, maintainers should relax and include all available official
605 PO files in their distributions, even if these have not recently been
606 updated, without exerting pressure on the translator teams to get the
607 job done. The pressure should rather come
608 from the community of users speaking a particular language, and
609 maintainers should consider themselves fairly relieved of any concern
610 about the adequacy of translation files. On the other hand, translators
611 should reasonably try updating the PO files they are responsible for,
612 while the package is undergoing pretest, prior to an official
613 distribution.
614 </p>
615 <p>Once the PO file is complete and dependable, the <code>msgfmt</code> program
616 is used for turning the PO file into a machine-oriented format, which
617 may yield efficient retrieval of translations by the programs of the
618 package, whenever needed at runtime (see section <a href="gettext_10.html#SEC196">The Format of GNU MO Files</a>). See section <a href="gettext_10.html#SEC174">Invoking the <code>msgfmt</code> Program</a>, for more information about all modes of execution
619 for the <code>msgfmt</code> program.
620 </p>
621 <p>Finally, the modified and marked C sources are compiled and linked
622 with the GNU <code>gettext</code> library, usually through the operation of
623 <code>make</code>, given a suitable &lsquo;<tt>Makefile</tt>&rsquo; exists for the project,
624 and the resulting executable is installed somewhere users will find it.
625 The MO files themselves should also be properly installed. Given the
626 appropriate environment variables are set (see section <a href="gettext_2.html#SEC10">Setting the Locale through Environment Variables</a>),
627 the program should localize itself automatically, whenever it executes.
628 </p>
629 <p>The remainder of this manual has the purpose of explaining in depth the various
630 steps outlined above.
631 </p>
632
633 <table cellpadding="1" cellspacing="1" border="0">
634 <tr><td valign="middle" align="left">[<a href="#SEC1" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
635 <td valign="middle" align="left">[<a href="gettext_2.html#SEC7" title="Next chapter"> &gt;&gt; </a>]</td>
636 <td valign="middle" align="left"> &nbsp; </td>
637 <td valign="middle" align="left"> &nbsp; </td>
638 <td valign="middle" align="left"> &nbsp; </td>
639 <td valign="middle" align="left"> &nbsp; </td>
640 <td valign="middle" align="left"> &nbsp; </td>
641 <td valign="middle" align="left">[<a href="gettext_toc.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
642 <td valign="middle" align="left">[<a href="gettext_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
643 <td valign="middle" align="left">[<a href="gettext_21.html#SEC389" title="Index">Index</a>]</td>
644 <td valign="middle" align="left">[<a href="gettext_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
645 </tr></table>
646 <p>
647 <font size="-1">
648 This document was generated by <em>Bruno Haible</em> on <em>February, 21 2024</em> using <a href="https://www.nongnu.org/texi2html/"><em>texi2html 1.78a</em></a>.
649 </font>
650 <br>
651
652 </p>
653 </body>
654 </html>