Mercurial > repos > rliterman > csp2

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