← Back to branch summary

~ubuntu-branches/ubuntu/breezy/gettext/breezy

« back to all changes in this revision

Viewing changes to gettext-tools/doc/gettext.info

  • Committer: Bazaar Package Importer
  • Author(s): Santiago Vila
  • Date: 2004-03-14 17:40:02 UTC
  • mfrom: (1.1.1 upstream)
  • Revision ID: james.westby@ubuntu.com-20040314174002-p1ad5ldve1hqzhye
Tags: 0.14.1-2
* Added libexpat1-dev to Build-Depends, for glade support.
* Added libc0.1-dev to Build-Depends, for GNU/kFreeBSD.
* Removed special-casing of knetbsd-gnu in debian/rules.

Show diffs side-by-side

added added

removed removed

Lines of Context:
gettext-tools/doc/gettext.info
 
1
This is gettext.info, produced by makeinfo version 4.6 from
 
2
gettext.texi.
 
3
 
 
4
INFO-DIR-SECTION GNU Gettext Utilities
 
5
START-INFO-DIR-ENTRY
 
6
* gettext: (gettext).                          GNU gettext utilities.
 
7
* autopoint: (gettext)autopoint Invocation.    Copy gettext infrastructure.
 
8
* envsubst: (gettext)envsubst Invocation.      Expand environment variables.
 
9
* gettextize: (gettext)gettextize Invocation.  Prepare a package for gettext.
 
10
* msgattrib: (gettext)msgattrib Invocation.    Select part of a PO file.
 
11
* msgcat: (gettext)msgcat Invocation.          Combine several PO files.
 
12
* msgcmp: (gettext)msgcmp Invocation.          Compare a PO file and template.
 
13
* msgcomm: (gettext)msgcomm Invocation.        Match two PO files.
 
14
* msgconv: (gettext)msgconv Invocation.        Convert PO file to encoding.
 
15
* msgen: (gettext)msgen Invocation.            Create an English PO file.
 
16
* msgexec: (gettext)msgexec Invocation.        Process a PO file.
 
17
* msgfilter: (gettext)msgfilter Invocation.    Pipe a PO file through a filter.
 
18
* msgfmt: (gettext)msgfmt Invocation.          Make MO files out of PO files.
 
19
* msggrep: (gettext)msggrep Invocation.        Select part of a PO file.
 
20
* msginit: (gettext)msginit Invocation.        Create a fresh PO file.
 
21
* msgmerge: (gettext)msgmerge Invocation.      Update a PO file from template.
 
22
* msgunfmt: (gettext)msgunfmt Invocation.      Uncompile MO file into PO file.
 
23
* msguniq: (gettext)msguniq Invocation.        Unify duplicates for PO file.
 
24
* ngettext: (gettext)ngettext Invocation.      Translate a message with plural.
 
25
* xgettext: (gettext)xgettext Invocation.      Extract strings into a PO file.
 
26
* ISO639: (gettext)Language Codes.             ISO 639 language codes.
 
27
* ISO3166: (gettext)Country Codes.             ISO 3166 country codes.
 
28
END-INFO-DIR-ENTRY
 
29
 
 
30
   This file provides documentation for GNU `gettext' utilities.  It
 
31
also serves as a reference for the free Translation Project.
 
32
 
 
33
   Copyright (C) 1995-1998, 2001-2004 Free Software Foundation, Inc.
 
34
 
 
35
   Permission is granted to make and distribute verbatim copies of this
 
36
manual provided the copyright notice and this permission notice are
 
37
preserved on all copies.
 
38
 
 
39
   Permission is granted to copy and distribute modified versions of
 
40
this manual under the conditions for verbatim copying, provided that
 
41
the entire resulting derived work is distributed under the terms of a
 
42
permission notice identical to this one.
 
43
 
 
44
   Permission is granted to copy and distribute translations of this
 
45
manual into another language, under the above conditions for modified
 
46
versions, except that this permission notice may be stated in a
 
47
translation approved by the Foundation.
 
48
 
 
49
 
 
50
File: gettext.info,  Node: Top,  Next: Introduction,  Prev: (dir),  Up: (dir)
 
51
 
 
52
GNU `gettext' utilities
 
53
***********************
 
54
 
 
55
This manual documents the GNU gettext tools and the GNU libintl library,
 
56
version 0.14.1.
 
57
 
 
58
* Menu:
 
59
 
 
60
* Introduction::                Introduction
 
61
* Basics::                      PO Files and PO Mode Basics
 
62
* Sources::                     Preparing Program Sources
 
63
* Template::                    Making the PO Template File
 
64
* Creating::                    Creating a New PO File
 
65
* Updating::                    Updating Existing PO Files
 
66
* Manipulating::                Manipulating PO Files
 
67
* Binaries::                    Producing Binary MO Files
 
68
* Users::                       The User's View
 
69
* Programmers::                 The Programmer's View
 
70
* Translators::                 The Translator's View
 
71
* Maintainers::                 The Maintainer's View
 
72
* Programming Languages::       Other Programming Languages
 
73
* Conclusion::                  Concluding Remarks
 
74
 
 
75
* Language Codes::              ISO 639 language codes
 
76
* Country Codes::               ISO 3166 country codes
 
77
 
 
78
* Program Index::               Index of Programs
 
79
* Option Index::                Index of Command-Line Options
 
80
* Variable Index::              Index of Environment Variables
 
81
* PO Mode Index::               Index of Emacs PO Mode Commands
 
82
* Autoconf Macro Index::        Index of Autoconf Macros
 
83
* Index::                       General Index
 
84
 
 
85
 --- The Detailed Node Listing ---
 
86
 
 
87
Introduction
 
88
 
 
89
* Why::                         The Purpose of GNU `gettext'
 
90
* Concepts::                    I18n, L10n, and Such
 
91
* Aspects::                     Aspects in Native Language Support
 
92
* Files::                       Files Conveying Translations
 
93
* Overview::                    Overview of GNU `gettext'
 
94
 
 
95
PO Files and PO Mode Basics
 
96
 
 
97
* Installation::                Completing GNU `gettext' Installation
 
98
* PO Files::                    The Format of PO Files
 
99
* Main PO Commands::            Main Commands
 
100
* Entry Positioning::           Entry Positioning
 
101
* Normalizing::                 Normalizing Strings in Entries
 
102
 
 
103
Preparing Program Sources
 
104
 
 
105
* Triggering::                  Triggering `gettext' Operations
 
106
* Preparing Strings::           Preparing Translatable Strings
 
107
* Mark Keywords::               How Marks Appear in Sources
 
108
* Marking::                     Marking Translatable Strings
 
109
* c-format Flag::               Telling something about the following string
 
110
* Special cases::               Special Cases of Translatable Strings
 
111
* Names::                       Marking Proper Names for Translation
 
112
* Libraries::                   Preparing Library Sources
 
113
 
 
114
Making the PO Template File
 
115
 
 
116
* xgettext Invocation::         Invoking the `xgettext' Program
 
117
 
 
118
Creating a New PO File
 
119
 
 
120
* msginit Invocation::          Invoking the `msginit' Program
 
121
* Header Entry::                Filling in the Header Entry
 
122
 
 
123
Updating Existing PO Files
 
124
 
 
125
* msgmerge Invocation::         Invoking the `msgmerge' Program
 
126
* Translated Entries::          Translated Entries
 
127
* Fuzzy Entries::               Fuzzy Entries
 
128
* Untranslated Entries::        Untranslated Entries
 
129
* Obsolete Entries::            Obsolete Entries
 
130
* Modifying Translations::      Modifying Translations
 
131
* Modifying Comments::          Modifying Comments
 
132
* Subedit::                     Mode for Editing Translations
 
133
* C Sources Context::           C Sources Context
 
134
* Auxiliary::                   Consulting Auxiliary PO Files
 
135
* Compendium::                  Using Translation Compendia
 
136
 
 
137
Using Translation Compendia
 
138
 
 
139
* Creating Compendia::          Merging translations for later use
 
140
* Using Compendia::             Using older translations if they fit
 
141
 
 
142
Manipulating PO Files
 
143
 
 
144
* msgcat Invocation::           Invoking the `msgcat' Program
 
145
* msgconv Invocation::          Invoking the `msgconv' Program
 
146
* msggrep Invocation::          Invoking the `msggrep' Program
 
147
* msgfilter Invocation::        Invoking the `msgfilter' Program
 
148
* msguniq Invocation::          Invoking the `msguniq' Program
 
149
* msgcomm Invocation::          Invoking the `msgcomm' Program
 
150
* msgcmp Invocation::           Invoking the `msgcmp' Program
 
151
* msgattrib Invocation::        Invoking the `msgattrib' Program
 
152
* msgen Invocation::            Invoking the `msgen' Program
 
153
* msgexec Invocation::          Invoking the `msgexec' Program
 
154
* libgettextpo::                Writing your own programs that process PO files
 
155
 
 
156
Producing Binary MO Files
 
157
 
 
158
* msgfmt Invocation::           Invoking the `msgfmt' Program
 
159
* msgunfmt Invocation::         Invoking the `msgunfmt' Program
 
160
* MO Files::                    The Format of GNU MO Files
 
161
 
 
162
The User's View
 
163
 
 
164
* Matrix::                      The Current `ABOUT-NLS' Matrix
 
165
* Installers::                  Magic for Installers
 
166
* End Users::                   Magic for End Users
 
167
 
 
168
The Programmer's View
 
169
 
 
170
* catgets::                     About `catgets'
 
171
* gettext::                     About `gettext'
 
172
* Comparison::                  Comparing the two interfaces
 
173
* Using libintl.a::             Using libintl.a in own programs
 
174
* gettext grok::                Being a `gettext' grok
 
175
* Temp Programmers::            Temporary Notes for the Programmers Chapter
 
176
 
 
177
About `catgets'
 
178
 
 
179
* Interface to catgets::        The interface
 
180
* Problems with catgets::       Problems with the `catgets' interface?!
 
181
 
 
182
About `gettext'
 
183
 
 
184
* Interface to gettext::        The interface
 
185
* Ambiguities::                 Solving ambiguities
 
186
* Locating Catalogs::           Locating message catalog files
 
187
* Charset conversion::          How to request conversion to Unicode
 
188
* Plural forms::                Additional functions for handling plurals
 
189
* GUI program problems::        Another technique for solving ambiguities
 
190
* Optimized gettext::           Optimization of the *gettext functions
 
191
 
 
192
Temporary Notes for the Programmers Chapter
 
193
 
 
194
* Temp Implementations::        Temporary - Two Possible Implementations
 
195
* Temp catgets::                Temporary - About `catgets'
 
196
* Temp WSI::                    Temporary - Why a single implementation
 
197
* Temp Notes::                  Temporary - Notes
 
198
 
 
199
The Translator's View
 
200
 
 
201
* Trans Intro 0::               Introduction 0
 
202
* Trans Intro 1::               Introduction 1
 
203
* Discussions::                 Discussions
 
204
* Organization::                Organization
 
205
* Information Flow::            Information Flow
 
206
* Prioritizing messages::       How to find which messages to translate first
 
207
 
 
208
Organization
 
209
 
 
210
* Central Coordination::        Central Coordination
 
211
* National Teams::              National Teams
 
212
* Mailing Lists::               Mailing Lists
 
213
 
 
214
National Teams
 
215
 
 
216
* Sub-Cultures::                Sub-Cultures
 
217
* Organizational Ideas::        Organizational Ideas
 
218
 
 
219
The Maintainer's View
 
220
 
 
221
* Flat and Non-Flat::           Flat or Non-Flat Directory Structures
 
222
* Prerequisites::               Prerequisite Works
 
223
* gettextize Invocation::       Invoking the `gettextize' Program
 
224
* Adjusting Files::             Files You Must Create or Alter
 
225
* autoconf macros::             Autoconf macros for use in `configure.in'
 
226
* CVS Issues::                  Integrating with CVS
 
227
 
 
228
Files You Must Create or Alter
 
229
 
 
230
* po/POTFILES.in::              `POTFILES.in' in `po/'
 
231
* po/LINGUAS::                  `LINGUAS' in `po/'
 
232
* po/Makevars::                 `Makefile' pieces in `po/'
 
233
* configure.in::                `configure.in' at top level
 
234
* config.guess::                `config.guess', `config.sub' at top level
 
235
* mkinstalldirs::               `mkinstalldirs' at top level
 
236
* aclocal::                     `aclocal.m4' at top level
 
237
* acconfig::                    `acconfig.h' at top level
 
238
* config.h.in::                 `config.h.in' at top level
 
239
* Makefile::                    `Makefile.in' at top level
 
240
* src/Makefile::                `Makefile.in' in `src/'
 
241
* lib/gettext.h::               `gettext.h' in `lib/'
 
242
 
 
243
Autoconf macros for use in `configure.in'
 
244
 
 
245
* AM_GNU_GETTEXT::              AM_GNU_GETTEXT in `gettext.m4'
 
246
* AM_GNU_GETTEXT_VERSION::      AM_GNU_GETTEXT_VERSION in `gettext.m4'
 
247
* AM_PO_SUBDIRS::               AM_PO_SUBDIRS in `po.m4'
 
248
* AM_ICONV::                    AM_ICONV in `iconv.m4'
 
249
 
 
250
Integrating with CVS
 
251
 
 
252
* Distributed CVS::             Avoiding version mismatch in distributed development
 
253
* Files under CVS::             Files to put under CVS version control
 
254
* autopoint Invocation::        Invoking the `autopoint' Program
 
255
 
 
256
Other Programming Languages
 
257
 
 
258
* Language Implementors::       The Language Implementor's View
 
259
* Programmers for other Languages::  The Programmer's View
 
260
* Translators for other Languages::  The Translator's View
 
261
* Maintainers for other Languages::  The Maintainer's View
 
262
* List of Programming Languages::  Individual Programming Languages
 
263
* List of Data Formats::        Internationalizable Data
 
264
 
 
265
The Translator's View
 
266
 
 
267
* c-format::                    C Format Strings
 
268
* objc-format::                 Objective C Format Strings
 
269
* sh-format::                   Shell Format Strings
 
270
* python-format::               Python Format Strings
 
271
* lisp-format::                 Lisp Format Strings
 
272
* elisp-format::                Emacs Lisp Format Strings
 
273
* librep-format::               librep Format Strings
 
274
* smalltalk-format::            Smalltalk Format Strings
 
275
* java-format::                 Java Format Strings
 
276
* csharp-format::               C# Format Strings
 
277
* awk-format::                  awk Format Strings
 
278
* object-pascal-format::        Object Pascal Format Strings
 
279
* ycp-format::                  YCP Format Strings
 
280
* tcl-format::                  Tcl Format Strings
 
281
* perl-format::                 Perl Format Strings
 
282
* php-format::                  PHP Format Strings
 
283
* gcc-internal-format::         GCC internal Format Strings
 
284
* qt-format::                   Qt Format Strings
 
285
 
 
286
Individual Programming Languages
 
287
 
 
288
* C::                           C, C++, Objective C
 
289
* sh::                          sh - Shell Script
 
290
* bash::                        bash - Bourne-Again Shell Script
 
291
* Python::                      Python
 
292
* Common Lisp::                 GNU clisp - Common Lisp
 
293
* clisp C::                     GNU clisp C sources
 
294
* Emacs Lisp::                  Emacs Lisp
 
295
* librep::                      librep
 
296
* Smalltalk::                   GNU Smalltalk
 
297
* Java::                        Java
 
298
* C#::                          C#
 
299
* gawk::                        GNU awk
 
300
* Pascal::                      Pascal - Free Pascal Compiler
 
301
* wxWindows::                   wxWindows library
 
302
* YCP::                         YCP - YaST2 scripting language
 
303
* Tcl::                         Tcl - Tk's scripting language
 
304
* Perl::                        Perl
 
305
* PHP::                         PHP Hypertext Preprocessor
 
306
* Pike::                        Pike
 
307
* GCC-source::                  GNU Compiler Collection sources
 
308
 
 
309
sh - Shell Script
 
310
 
 
311
* Preparing Shell Scripts::     Preparing Shell Scripts for Internationalization
 
312
* gettext.sh::                  Contents of `gettext.sh'
 
313
* gettext Invocation::          Invoking the `gettext' program
 
314
* ngettext Invocation::         Invoking the `ngettext' program
 
315
* envsubst Invocation::         Invoking the `envsubst' program
 
316
* eval_gettext Invocation::     Invoking the `eval_gettext' function
 
317
* eval_ngettext Invocation::    Invoking the `eval_ngettext' function
 
318
 
 
319
Perl
 
320
 
 
321
* General Problems::            General Problems Parsing Perl Code
 
322
* Default Keywords::            Which Keywords Will xgettext Look For?
 
323
* Special Keywords::            How to Extract Hash Keys
 
324
* Quote-like Expressions::      What are Strings And Quote-like Expressions?
 
325
* Interpolation I::             Invalid String Interpolation
 
326
* Interpolation II::            Valid String Interpolation
 
327
* Parentheses::                 When To Use Parentheses
 
328
* Long Lines::                  How To Grok with Long Lines
 
329
* Perl Pitfalls::               Bugs, Pitfalls, and Things That Do Not Work
 
330
 
 
331
Internationalizable Data
 
332
 
 
333
* POT::                         POT - Portable Object Template
 
334
* RST::                         Resource String Table
 
335
* Glade::                       Glade - GNOME user interface description
 
336
 
 
337
Concluding Remarks
 
338
 
 
339
* History::                     History of GNU `gettext'
 
340
* References::                  Related Readings
 
341
 
 
342
 
 
343
File: gettext.info,  Node: Introduction,  Next: Basics,  Prev: Top,  Up: Top
 
344
 
 
345
Introduction
 
346
************
 
347
 
 
348
     This manual is still in _DRAFT_ state.  Some sections are still
 
349
     empty, or almost.  We keep merging material from other sources
 
350
     (essentially e-mail folders) while the proper integration of this
 
351
     material is delayed.
 
352
 
 
353
   In this manual, we use _he_ when speaking of the programmer or
 
354
maintainer, _she_ when speaking of the translator, and _they_ when
 
355
speaking of the installers or end users of the translated program.
 
356
This is only a convenience for clarifying the documentation.  It is
 
357
_absolutely_ not meant to imply that some roles are more appropriate to
 
358
males or females.  Besides, as you might guess, GNU `gettext' is meant
 
359
to be useful for people using computers, whatever their sex, race,
 
360
religion or nationality!
 
361
 
 
362
   This chapter explains the goals sought in the creation of GNU
 
363
`gettext' and the free Translation Project.  Then, it explains a few
 
364
broad concepts around Native Language Support, and positions message
 
365
translation with regard to other aspects of national and cultural
 
366
variance, as they apply to to programs.  It also surveys those files
 
367
used to convey the translations.  It explains how the various tools
 
368
interact in the initial generation of these files, and later, how the
 
369
maintenance cycle should usually operate.
 
370
 
 
371
   Please send suggestions and corrections to:
 
372
 
 
373
     Internet address:
 
374
         bug-gnu-gettext@gnu.org
 
375
 
 
376
Please include the manual's edition number and update date in your
 
377
messages.
 
378
 
 
379
* Menu:
 
380
 
 
381
* Why::                         The Purpose of GNU `gettext'
 
382
* Concepts::                    I18n, L10n, and Such
 
383
* Aspects::                     Aspects in Native Language Support
 
384
* Files::                       Files Conveying Translations
 
385
* Overview::                    Overview of GNU `gettext'
 
386
 
 
387
 
 
388
File: gettext.info,  Node: Why,  Next: Concepts,  Prev: Introduction,  Up: Introduction
 
389
 
 
390
The Purpose of GNU `gettext'
 
391
============================
 
392
 
 
393
Usually, programs are written and documented in English, and use
 
394
English at execution time to interact with users.  This is true not
 
395
only of GNU software, but also of a great deal of commercial and free
 
396
software.  Using a common language is quite handy for communication
 
397
between developers, maintainers and users from all countries.  On the
 
398
other hand, most people are less comfortable with English than with
 
399
their own native language, and would prefer to use their mother tongue
 
400
for day to day's work, as far as possible.  Many would simply _love_ to
 
401
see their computer screen showing a lot less of English, and far more
 
402
of their own language.
 
403
 
 
404
   However, to many people, this dream might appear so far fetched that
 
405
they may believe it is not even worth spending time thinking about it.
 
406
They have no confidence at all that the dream might ever become true.
 
407
Yet some have not lost hope, and have organized themselves.  The
 
408
Translation Project is a formalization of this hope into a workable
 
409
structure, which has a good chance to get all of us nearer the
 
410
achievement of a truly multi-lingual set of programs.
 
411
 
 
412
   GNU `gettext' is an important step for the Translation Project, as
 
413
it is an asset on which we may build many other steps.  This package
 
414
offers to programmers, translators and even users, a well integrated
 
415
set of tools and documentation.  Specifically, the GNU `gettext'
 
416
utilities are a set of tools that provides a framework within which
 
417
other free packages may produce multi-lingual messages.  These tools
 
418
include
 
419
 
 
420
   * A set of conventions about how programs should be written to
 
421
     support message catalogs.
 
422
 
 
423
   * A directory and file naming organization for the message catalogs
 
424
     themselves.
 
425
 
 
426
   * A runtime library supporting the retrieval of translated messages.
 
427
 
 
428
   * A few stand-alone programs to massage in various ways the sets of
 
429
     translatable strings, or already translated strings.
 
430
 
 
431
   * A special mode for Emacs(1) which helps preparing these sets and
 
432
     bringing them up to date.
 
433
 
 
434
   GNU `gettext' is designed to minimize the impact of
 
435
internationalization on program sources, keeping this impact as small
 
436
and hardly noticeable as possible.  Internationalization has better
 
437
chances of succeeding if it is very light weighted, or at least, appear
 
438
to be so, when looking at program sources.
 
439
 
 
440
   The Translation Project also uses the GNU `gettext' distribution as
 
441
a vehicle for documenting its structure and methods.  This goes beyond
 
442
the strict technicalities of documenting the GNU `gettext' proper.  By
 
443
so doing, translators will find in a single place, as far as possible,
 
444
all they need to know for properly doing their translating work.  Also,
 
445
this supplemental documentation might also help programmers, and even
 
446
curious users, in understanding how GNU `gettext' is related to the
 
447
remainder of the Translation Project, and consequently, have a glimpse
 
448
at the _big picture_.
 
449
 
 
450
   ---------- Footnotes ----------
 
451
 
 
452
   (1) In this manual, all mentions of Emacs refers to either GNU Emacs
 
453
or to XEmacs, which people sometimes call FSF Emacs and Lucid Emacs,
 
454
respectively.
 
455
 
 
456
 
 
457
File: gettext.info,  Node: Concepts,  Next: Aspects,  Prev: Why,  Up: Introduction
 
458
 
 
459
I18n, L10n, and Such
 
460
====================
 
461
 
 
462
Two long words appear all the time when we discuss support of native
 
463
language in programs, and these words have a precise meaning, worth
 
464
being explained here, once and for all in this document.  The words are
 
465
_internationalization_ and _localization_.  Many people, tired of
 
466
writing these long words over and over again, took the habit of writing
 
467
"i18n" and "l10n" instead, quoting the first and last letter of each
 
468
word, and replacing the run of intermediate letters by a number merely
 
469
telling how many such letters there are.  But in this manual, in the
 
470
sake of clarity, we will patiently write the names in full, each time...
 
471
 
 
472
   By "internationalization", one refers to the operation by which a
 
473
program, or a set of programs turned into a package, is made aware of
 
474
and able to support multiple languages.  This is a generalization
 
475
process, by which the programs are untied from calling only English
 
476
strings or other English specific habits, and connected to generic ways
 
477
of doing the same, instead.  Program developers may use various
 
478
techniques to internationalize their programs.  Some of these have been
 
479
standardized.  GNU `gettext' offers one of these standards.  *Note
 
480
Programmers::.
 
481
 
 
482
   By "localization", one means the operation by which, in a set of
 
483
programs already internationalized, one gives the program all needed
 
484
information so that it can adapt itself to handle its input and output
 
485
in a fashion which is correct for some native language and cultural
 
486
habits.  This is a particularisation process, by which generic methods
 
487
already implemented in an internationalized program are used in
 
488
specific ways.  The programming environment puts several functions to
 
489
the programmers disposal which allow this runtime configuration.  The
 
490
formal description of specific set of cultural habits for some country,
 
491
together with all associated translations targeted to the same native
 
492
language, is called the "locale" for this language or country.  Users
 
493
achieve localization of programs by setting proper values to special
 
494
environment variables, prior to executing those programs, identifying
 
495
which locale should be used.
 
496
 
 
497
   In fact, locale message support is only one component of the cultural
 
498
data that makes up a particular locale.  There are a whole host of
 
499
routines and functions provided to aid programmers in developing
 
500
internationalized software and which allow them to access the data
 
501
stored in a particular locale.  When someone presently refers to a
 
502
particular locale, they are obviously referring to the data stored
 
503
within that particular locale.  Similarly, if a programmer is referring
 
504
to "accessing the locale routines", they are referring to the complete
 
505
suite of routines that access all of the locale's information.
 
506
 
 
507
   One uses the expression "Native Language Support", or merely NLS,
 
508
for speaking of the overall activity or feature encompassing both
 
509
internationalization and localization, allowing for multi-lingual
 
510
interactions in a program.  In a nutshell, one could say that
 
511
internationalization is the operation by which further localizations
 
512
are made possible.
 
513
 
 
514
   Also, very roughly said, when it comes to multi-lingual messages,
 
515
internationalization is usually taken care of by programmers, and
 
516
localization is usually taken care of by translators.
 
517
 
 
518
 
 
519
File: gettext.info,  Node: Aspects,  Next: Files,  Prev: Concepts,  Up: Introduction
 
520
 
 
521
Aspects in Native Language Support
 
522
==================================
 
523
 
 
524
For a totally multi-lingual distribution, there are many things to
 
525
translate beyond output messages.
 
526
 
 
527
   * As of today, GNU `gettext' offers a complete toolset for
 
528
     translating messages output by C programs.  Perl scripts and shell
 
529
     scripts will also need to be translated.  Even if there are today
 
530
     some hooks by which this can be done, these hooks are not
 
531
     integrated as well as they should be.
 
532
 
 
533
   * Some programs, like `autoconf' or `bison', are able to produce
 
534
     other programs (or scripts).  Even if the generating programs
 
535
     themselves are internationalized, the generated programs they
 
536
     produce may need internationalization on their own, and this
 
537
     indirect internationalization could be automated right from the
 
538
     generating program.  In fact, quite usually, generating and
 
539
     generated programs could be internationalized independently, as
 
540
     the effort needed is fairly orthogonal.
 
541
 
 
542
   * A few programs include textual tables which might need translation
 
543
     themselves, independently of the strings contained in the program
 
544
     itself.  For example, RFC 1345 gives an English description for
 
545
     each character which the `recode' program is able to reconstruct
 
546
     at execution.  Since these descriptions are extracted from the RFC
 
547
     by mechanical means, translating them properly would require a
 
548
     prior translation of the RFC itself.
 
549
 
 
550
   * Almost all programs accept options, which are often worded out so
 
551
     to be descriptive for the English readers; one might want to
 
552
     consider offering translated versions for program options as well.
 
553
 
 
554
   * Many programs read, interpret, compile, or are somewhat driven by
 
555
     input files which are texts containing keywords, identifiers, or
 
556
     replies which are inherently translatable.  For example, one may
 
557
     want `gcc' to allow diacriticized characters in identifiers or use
 
558
     translated keywords; `rm -i' might accept something else than `y'
 
559
     or `n' for replies, etc.  Even if the program will eventually make
 
560
     most of its output in the foreign languages, one has to decide
 
561
     whether the input syntax, option values, etc., are to be localized
 
562
     or not.
 
563
 
 
564
   * The manual accompanying a package, as well as all documentation
 
565
     files in the distribution, could surely be translated, too.
 
566
     Translating a manual, with the intent of later keeping up with
 
567
     updates, is a major undertaking in itself, generally.
 
568
 
 
569
 
 
570
   As we already stressed, translation is only one aspect of locales.
 
571
Other internationalization aspects are system services and are handled
 
572
in GNU `libc'.  There are many attributes that are needed to define a
 
573
country's cultural conventions.  These attributes include beside the
 
574
country's native language, the formatting of the date and time, the
 
575
representation of numbers, the symbols for currency, etc.  These local
 
576
"rules" are termed the country's locale.  The locale represents the
 
577
knowledge needed to support the country's native attributes.
 
578
 
 
579
   There are a few major areas which may vary between countries and
 
580
hence, define what a locale must describe.  The following list helps
 
581
putting multi-lingual messages into the proper context of other tasks
 
582
related to locales.  See the GNU `libc' manual for details.
 
583
 
 
584
_Characters and Codesets_
 
585
     The codeset most commonly used through out the USA and most English
 
586
     speaking parts of the world is the ASCII codeset.  However, there
 
587
     are many characters needed by various locales that are not found
 
588
     within this codeset.  The 8-bit ISO 8859-1 code set has most of
 
589
     the special characters needed to handle the major European
 
590
     languages.  However, in many cases, the ISO 8859-1 font is not
 
591
     adequate: it doesn't even handle the major European currency.
 
592
     Hence each locale will need to specify which codeset they need to
 
593
     use and will need to have the appropriate character handling
 
594
     routines to cope with the codeset.
 
595
 
 
596
_Currency_
 
597
     The symbols used vary from country to country as does the position
 
598
     used by the symbol.  Software needs to be able to transparently
 
599
     display currency figures in the native mode for each locale.
 
600
 
 
601
_Dates_
 
602
     The format of date varies between locales.  For example, Christmas
 
603
     day in 1994 is written as 12/25/94 in the USA and as 25/12/94 in
 
604
     Australia.  Other countries might use ISO 8061 dates, etc.
 
605
 
 
606
     Time of the day may be noted as HH:MM, HH.MM, or otherwise.  Some
 
607
     locales require time to be specified in 24-hour mode rather than
 
608
     as AM or PM.  Further, the nature and yearly extent of the
 
609
     Daylight Saving correction vary widely between countries.
 
610
 
 
611
_Numbers_
 
612
     Numbers can be represented differently in different locales.  For
 
613
     example, the following numbers are all written correctly for their
 
614
     respective locales:
 
615
 
 
616
          12,345.67       English
 
617
          12.345,67       German
 
618
           12345,67       French
 
619
          1,2345.67       Asia
 
620
 
 
621
     Some programs could go further and use different unit systems, like
 
622
     English units or Metric units, or even take into account variants
 
623
     about how numbers are spelled in full.
 
624
 
 
625
_Messages_
 
626
     The most obvious area is the language support within a locale.
 
627
     This is where GNU `gettext' provides the means for developers and
 
628
     users to easily change the language that the software uses to
 
629
     communicate to the user.
 
630
 
 
631
 
 
632
   Components of locale outside of message handling are standardized in
 
633
the ISO C standard and the SUSV2 specification.  GNU `libc' fully
 
634
implements this, and most other modern systems provide a more or less
 
635
reasonable support for at least some of the missing components.
 
636
 
 
637
 
 
638
File: gettext.info,  Node: Files,  Next: Overview,  Prev: Aspects,  Up: Introduction
 
639
 
 
640
Files Conveying Translations
 
641
============================
 
642
 
 
643
The letters PO in `.po' files means Portable Object, to distinguish it
 
644
from `.mo' files, where MO stands for Machine Object.  This paradigm,
 
645
as well as the PO file format, is inspired by the NLS standard
 
646
developed by Uniforum, and first implemented by Sun in their Solaris
 
647
system.
 
648
 
 
649
   PO files are meant to be read and edited by humans, and associate
 
650
each original, translatable string of a given package with its
 
651
translation in a particular target language.  A single PO file is
 
652
dedicated to a single target language.  If a package supports many
 
653
languages, there is one such PO file per language supported, and each
 
654
package has its own set of PO files.  These PO files are best created by
 
655
the `xgettext' program, and later updated or refreshed through the
 
656
`msgmerge' program.  Program `xgettext' extracts all marked messages
 
657
from a set of C files and initializes a PO file with empty
 
658
translations.  Program `msgmerge' takes care of adjusting PO files
 
659
between releases of the corresponding sources, commenting obsolete
 
660
entries, initializing new ones, and updating all source line
 
661
references.  Files ending with `.pot' are kind of base translation
 
662
files found in distributions, in PO file format.
 
663
 
 
664
   MO files are meant to be read by programs, and are binary in nature.
 
665
A few systems already offer tools for creating and handling MO files as
 
666
part of the Native Language Support coming with the system, but the
 
667
format of these MO files is often different from system to system, and
 
668
non-portable.  The tools already provided with these systems don't
 
669
support all the features of GNU `gettext'.  Therefore GNU `gettext'
 
670
uses its own format for MO files.  Files ending with `.gmo' are really
 
671
MO files, when it is known that these files use the GNU format.
 
672
 
 
673
 
 
674
File: gettext.info,  Node: Overview,  Prev: Files,  Up: Introduction
 
675
 
 
676
Overview of GNU `gettext'
 
677
=========================
 
678
 
 
679
The following diagram summarizes the relation between the files handled
 
680
by GNU `gettext' and the tools acting on these files.  It is followed
 
681
by somewhat detailed explanations, which you should read while keeping
 
682
an eye on the diagram.  Having a clear understanding of these
 
683
interrelations will surely help programmers, translators and
 
684
maintainers.
 
685
 
 
686
     Original C Sources ---> PO mode ---> Marked C Sources ---.
 
687
                                                              |
 
688
                   .---------<--- GNU gettext Library         |
 
689
     .--- make <---+                                          |
 
690
     |             `---------<--------------------+-----------'
 
691
     |                                            |
 
692
     |   .-----<--- PACKAGE.pot <--- xgettext <---'   .---<--- PO Compendium
 
693
     |   |                                            |             ^
 
694
     |   |                                            `---.         |
 
695
     |   `---.                                            +---> PO mode ---.
 
696
     |       +----> msgmerge ------> LANG.po ---->--------'                |
 
697
     |   .---'                                                             |
 
698
     |   |                                                                 |
 
699
     |   `-------------<---------------.                                   |
 
700
     |                                 +--- New LANG.po <------------------'
 
701
     |   .--- LANG.gmo <--- msgfmt <---'
 
702
     |   |
 
703
     |   `---> install ---> /.../LANG/PACKAGE.mo ---.
 
704
     |                                              +---> "Hello world!"
 
705
     `-------> install ---> /.../bin/PROGRAM -------'
 
706
 
 
707
   The indication `PO mode' appears in two places in this picture, and
 
708
you may safely read it as merely meaning "hand editing", using any
 
709
editor of your choice, really.  However, for those of you being the
 
710
lucky users of Emacs, PO mode has been specifically created for
 
711
providing a cozy environment for editing or modifying PO files.  While
 
712
editing a PO file, PO mode allows for the easy browsing of auxiliary
 
713
and compendium PO files, as well as for following references into the
 
714
set of C program sources from which PO files have been derived.  It has
 
715
a few special features, among which are the interactive marking of
 
716
program strings as translatable, and the validation of PO files with
 
717
easy repositioning to PO file lines showing errors.
 
718
 
 
719
   As a programmer, the first step to bringing GNU `gettext' into your
 
720
package is identifying, right in the C sources, those strings which are
 
721
meant to be translatable, and those which are untranslatable.  This
 
722
tedious job can be done a little more comfortably using emacs PO mode,
 
723
but you can use any means familiar to you for modifying your C sources.
 
724
Beside this some other simple, standard changes are needed to properly
 
725
initialize the translation library.  *Note Sources::, for more
 
726
information about all this.
 
727
 
 
728
   For newly written software the strings of course can and should be
 
729
marked while writing it.  The `gettext' approach makes this very easy.
 
730
Simply put the following lines at the beginning of each file or in a
 
731
central header file:
 
732
 
 
733
     #define _(String) (String)
 
734
     #define N_(String) String
 
735
     #define textdomain(Domain)
 
736
     #define bindtextdomain(Package, Directory)
 
737
 
 
738
Doing this allows you to prepare the sources for internationalization.
 
739
Later when you feel ready for the step to use the `gettext' library
 
740
simply replace these definitions by the following:
 
741
 
 
742
     #include <libintl.h>
 
743
     #define _(String) gettext (String)
 
744
     #define gettext_noop(String) String
 
745
     #define N_(String) gettext_noop (String)
 
746
 
 
747
and link against `libintl.a' or `libintl.so'.  Note that on GNU
 
748
systems, you don't need to link with `libintl' because the `gettext'
 
749
library functions are already contained in GNU libc.  That is all you
 
750
have to change.
 
751
 
 
752
   Once the C sources have been modified, the `xgettext' program is
 
753
used to find and extract all translatable strings, and create a PO
 
754
template file out of all these.  This `PACKAGE.pot' file contains all
 
755
original program strings.  It has sets of pointers to exactly where in
 
756
C sources each string is used.  All translations are set to empty.  The
 
757
letter `t' in `.pot' marks this as a Template PO file, not yet oriented
 
758
towards any particular language.  *Note xgettext Invocation::, for more
 
759
details about how one calls the `xgettext' program.  If you are
 
760
_really_ lazy, you might be interested at working a lot more right
 
761
away, and preparing the whole distribution setup (*note Maintainers::).
 
762
By doing so, you spare yourself typing the `xgettext' command, as
 
763
`make' should now generate the proper things automatically for you!
 
764
 
 
765
   The first time through, there is no `LANG.po' yet, so the `msgmerge'
 
766
step may be skipped and replaced by a mere copy of `PACKAGE.pot' to
 
767
`LANG.po', where LANG represents the target language.  See *Note
 
768
Creating:: for details.
 
769
 
 
770
   Then comes the initial translation of messages.  Translation in
 
771
itself is a whole matter, still exclusively meant for humans, and whose
 
772
complexity far overwhelms the level of this manual.  Nevertheless, a
 
773
few hints are given in some other chapter of this manual (*note
 
774
Translators::).  You will also find there indications about how to
 
775
contact translating teams, or becoming part of them, for sharing your
 
776
translating concerns with others who target the same native language.
 
777
 
 
778
   While adding the translated messages into the `LANG.po' PO file, if
 
779
you do not have Emacs handy, you are on your own for ensuring that your
 
780
efforts fully respect the PO file format, and quoting conventions
 
781
(*note PO Files::).  This is surely not an impossible task, as this is
 
782
the way many people have handled PO files already for Uniforum or
 
783
Solaris.  On the other hand, by using PO mode in Emacs, most details of
 
784
PO file format are taken care of for you, but you have to acquire some
 
785
familiarity with PO mode itself.  Besides main PO mode commands (*note
 
786
Main PO Commands::), you should know how to move between entries (*note
 
787
Entry Positioning::), and how to handle untranslated entries (*note
 
788
Untranslated Entries::).
 
789
 
 
790
   If some common translations have already been saved into a compendium
 
791
PO file, translators may use PO mode for initializing untranslated
 
792
entries from the compendium, and also save selected translations into
 
793
the compendium, updating it (*note Compendium::).  Compendium files are
 
794
meant to be exchanged between members of a given translation team.
 
795
 
 
796
   Programs, or packages of programs, are dynamic in nature: users write
 
797
bug reports and suggestion for improvements, maintainers react by
 
798
modifying programs in various ways.  The fact that a package has
 
799
already been internationalized should not make maintainers shy of
 
800
adding new strings, or modifying strings already translated.  They just
 
801
do their job the best they can.  For the Translation Project to work
 
802
smoothly, it is important that maintainers do not carry translation
 
803
concerns on their already loaded shoulders, and that translators be
 
804
kept as free as possible of programming concerns.
 
805
 
 
806
   The only concern maintainers should have is carefully marking new
 
807
strings as translatable, when they should be, and do not otherwise
 
808
worry about them being translated, as this will come in proper time.
 
809
Consequently, when programs and their strings are adjusted in various
 
810
ways by maintainers, and for matters usually unrelated to translation,
 
811
`xgettext' would construct `PACKAGE.pot' files which are evolving over
 
812
time, so the translations carried by `LANG.po' are slowly fading out of
 
813
date.
 
814
 
 
815
   It is important for translators (and even maintainers) to understand
 
816
that package translation is a continuous process in the lifetime of a
 
817
package, and not something which is done once and for all at the start.
 
818
After an initial burst of translation activity for a given package,
 
819
interventions are needed once in a while, because here and there,
 
820
translated entries become obsolete, and new untranslated entries
 
821
appear, needing translation.
 
822
 
 
823
   The `msgmerge' program has the purpose of refreshing an already
 
824
existing `LANG.po' file, by comparing it with a newer `PACKAGE.pot'
 
825
template file, extracted by `xgettext' out of recent C sources.  The
 
826
refreshing operation adjusts all references to C source locations for
 
827
strings, since these strings move as programs are modified.  Also,
 
828
`msgmerge' comments out as obsolete, in `LANG.po', those already
 
829
translated entries which are no longer used in the program sources
 
830
(*note Obsolete Entries::).  It finally discovers new strings and
 
831
inserts them in the resulting PO file as untranslated entries (*note
 
832
Untranslated Entries::).  *Note msgmerge Invocation::, for more
 
833
information about what `msgmerge' really does.
 
834
 
 
835
   Whatever route or means taken, the goal is to obtain an updated
 
836
`LANG.po' file offering translations for all strings.
 
837
 
 
838
   The temporal mobility, or fluidity of PO files, is an integral part
 
839
of the translation game, and should be well understood, and accepted.
 
840
People resisting it will have a hard time participating in the
 
841
Translation Project, or will give a hard time to other participants!  In
 
842
particular, maintainers should relax and include all available official
 
843
PO files in their distributions, even if these have not recently been
 
844
updated, without exerting pressure on the translator teams to get the
 
845
job done.  The pressure should rather come from the community of users
 
846
speaking a particular language, and maintainers should consider
 
847
themselves fairly relieved of any concern about the adequacy of
 
848
translation files.  On the other hand, translators should reasonably
 
849
try updating the PO files they are responsible for, while the package
 
850
is undergoing pretest, prior to an official distribution.
 
851
 
 
852
   Once the PO file is complete and dependable, the `msgfmt' program is
 
853
used for turning the PO file into a machine-oriented format, which may
 
854
yield efficient retrieval of translations by the programs of the
 
855
package, whenever needed at runtime (*note MO Files::).  *Note msgfmt
 
856
Invocation::, for more information about all modes of execution for the
 
857
`msgfmt' program.
 
858
 
 
859
   Finally, the modified and marked C sources are compiled and linked
 
860
with the GNU `gettext' library, usually through the operation of
 
861
`make', given a suitable `Makefile' exists for the project, and the
 
862
resulting executable is installed somewhere users will find it.  The MO
 
863
files themselves should also be properly installed.  Given the
 
864
appropriate environment variables are set (*note End Users::), the
 
865
program should localize itself automatically, whenever it executes.
 
866
 
 
867
   The remainder of this manual has the purpose of explaining in depth
 
868
the various steps outlined above.
 
869
 
 
870
 
 
871
File: gettext.info,  Node: Basics,  Next: Sources,  Prev: Introduction,  Up: Top
 
872
 
 
873
PO Files and PO Mode Basics
 
874
***************************
 
875
 
 
876
The GNU `gettext' toolset helps programmers and translators at
 
877
producing, updating and using translation files, mainly those PO files
 
878
which are textual, editable files.  This chapter stresses the format of
 
879
PO files, and contains a PO mode starter.  PO mode description is
 
880
spread throughout this manual instead of being concentrated in one
 
881
place.  Here we present only the basics of PO mode.
 
882
 
 
883
* Menu:
 
884
 
 
885
* Installation::                Completing GNU `gettext' Installation
 
886
* PO Files::                    The Format of PO Files
 
887
* Main PO Commands::            Main Commands
 
888
* Entry Positioning::           Entry Positioning
 
889
* Normalizing::                 Normalizing Strings in Entries
 
890
 
 
891
 
 
892
File: gettext.info,  Node: Installation,  Next: PO Files,  Prev: Basics,  Up: Basics
 
893
 
 
894
Completing GNU `gettext' Installation
 
895
=====================================
 
896
 
 
897
Once you have received, unpacked, configured and compiled the GNU
 
898
`gettext' distribution, the `make install' command puts in place the
 
899
programs `xgettext', `msgfmt', `gettext', and `msgmerge', as well as
 
900
their available message catalogs.  To top off a comfortable
 
901
installation, you might also want to make the PO mode available to your
 
902
Emacs users.
 
903
 
 
904
   During the installation of the PO mode, you might want to modify your
 
905
file `.emacs', once and for all, so it contains a few lines looking
 
906
like:
 
907
 
 
908
     (setq auto-mode-alist
 
909
           (cons '("\\.po\\'\\|\\.po\\." . po-mode) auto-mode-alist))
 
910
     (autoload 'po-mode "po-mode" "Major mode for translators to edit PO files" t)
 
911
 
 
912
   Later, whenever you edit some `.po' file, or any file having the
 
913
string `.po.' within its name, Emacs loads `po-mode.elc' (or
 
914
`po-mode.el') as needed, and automatically activates PO mode commands
 
915
for the associated buffer.  The string _PO_ appears in the mode line
 
916
for any buffer for which PO mode is active.  Many PO files may be
 
917
active at once in a single Emacs session.
 
918
 
 
919
   If you are using Emacs version 20 or newer, and have already
 
920
installed the appropriate international fonts on your system, you may
 
921
also tell Emacs how to determine automatically the coding system of
 
922
every PO file.  This will often (but not always) cause the necessary
 
923
fonts to be loaded and used for displaying the translations on your
 
924
Emacs screen.  For this to happen, add the lines:
 
925
 
 
926
     (modify-coding-system-alist 'file "\\.po\\'\\|\\.po\\."
 
927
                                 'po-find-file-coding-system)
 
928
     (autoload 'po-find-file-coding-system "po-mode")
 
929
 
 
930
to your `.emacs' file.  If, with this, you still see boxes instead of
 
931
international characters, try a different font set (via Shift Mouse
 
932
button 1).
 
933
 
 
934
 
 
935
File: gettext.info,  Node: PO Files,  Next: Main PO Commands,  Prev: Installation,  Up: Basics
 
936
 
 
937
The Format of PO Files
 
938
======================
 
939
 
 
940
A PO file is made up of many entries, each entry holding the relation
 
941
between an original untranslated string and its corresponding
 
942
translation.  All entries in a given PO file usually pertain to a
 
943
single project, and all translations are expressed in a single target
 
944
language.  One PO file "entry" has the following schematic structure:
 
945
 
 
946
     WHITE-SPACE
 
947
     #  TRANSLATOR-COMMENTS
 
948
     #. AUTOMATIC-COMMENTS
 
949
     #: REFERENCE...
 
950
     #, FLAG...
 
951
     msgid UNTRANSLATED-STRING
 
952
     msgstr TRANSLATED-STRING
 
953
 
 
954
   The general structure of a PO file should be well understood by the
 
955
translator.  When using PO mode, very little has to be known about the
 
956
format details, as PO mode takes care of them for her.
 
957
 
 
958
   A simple entry can look like this:
 
959
 
 
960
     #: lib/error.c:116
 
961
     msgid "Unknown system error"
 
962
     msgstr "Error desconegut del sistema"
 
963
 
 
964
   Entries begin with some optional white space.  Usually, when
 
965
generated through GNU `gettext' tools, there is exactly one blank line
 
966
between entries.  Then comments follow, on lines all starting with the
 
967
character `#'.  There are two kinds of comments: those which have some
 
968
white space immediately following the `#', which comments are created
 
969
and maintained exclusively by the translator, and those which have some
 
970
non-white character just after the `#', which comments are created and
 
971
maintained automatically by GNU `gettext' tools.  All comments, of
 
972
either kind, are optional.
 
973
 
 
974
   After white space and comments, entries show two strings, namely
 
975
first the untranslated string as it appears in the original program
 
976
sources, and then, the translation of this string.  The original string
 
977
is introduced by the keyword `msgid', and the translation, by `msgstr'.
 
978
The two strings, untranslated and translated, are quoted in various
 
979
ways in the PO file, using `"' delimiters and `\' escapes, but the
 
980
translator does not really have to pay attention to the precise quoting
 
981
format, as PO mode fully takes care of quoting for her.
 
982
 
 
983
   The `msgid' strings, as well as automatic comments, are produced and
 
984
managed by other GNU `gettext' tools, and PO mode does not provide
 
985
means for the translator to alter these.  The most she can do is merely
 
986
deleting them, and only by deleting the whole entry.  On the other
 
987
hand, the `msgstr' string, as well as translator comments, are really
 
988
meant for the translator, and PO mode gives her the full control she
 
989
needs.
 
990
 
 
991
   The comment lines beginning with `#,' are special because they are
 
992
not completely ignored by the programs as comments generally are.  The
 
993
comma separated list of FLAGs is used by the `msgfmt' program to give
 
994
the user some better diagnostic messages.  Currently there are two
 
995
forms of flags defined:
 
996
 
 
997
`fuzzy'
 
998
     This flag can be generated by the `msgmerge' program or it can be
 
999
     inserted by the translator herself.  It shows that the `msgstr'
 
1000
     string might not be a correct translation (anymore).  Only the
 
1001
     translator can judge if the translation requires further
 
1002
     modification, or is acceptable as is.  Once satisfied with the
 
1003
     translation, she then removes this `fuzzy' attribute.  The
 
1004
     `msgmerge' program inserts this when it combined the `msgid' and
 
1005
     `msgstr' entries after fuzzy search only.  *Note Fuzzy Entries::.
 
1006
 
 
1007
`c-format'
 
1008
`no-c-format'
 
1009
     These flags should not be added by a human.  Instead only the
 
1010
     `xgettext' program adds them.  In an automated PO file processing
 
1011
     system as proposed here the user changes would be thrown away
 
1012
     again as soon as the `xgettext' program generates a new template
 
1013
     file.
 
1014
 
 
1015
     The `c-format' flag tells that the untranslated string and the
 
1016
     translation are supposed to be C format strings.  The `no-c-format'
 
1017
     flag tells that they are not C format strings, even though the
 
1018
     untranslated string happens to look like a C format string (with
 
1019
     `%' directives).
 
1020
 
 
1021
     In case the `c-format' flag is given for a string the `msgfmt'
 
1022
     does some more tests to check to validity of the translation.
 
1023
     *Note msgfmt Invocation::, *Note c-format Flag:: and *Note
 
1024
     c-format::.
 
1025
 
 
1026
`objc-format'
 
1027
`no-objc-format'
 
1028
     Likewise for Objective C, see *Note objc-format::.
 
1029
 
 
1030
`sh-format'
 
1031
`no-sh-format'
 
1032
     Likewise for Shell, see *Note sh-format::.
 
1033
 
 
1034
`python-format'
 
1035
`no-python-format'
 
1036
     Likewise for Python, see *Note python-format::.
 
1037
 
 
1038
`lisp-format'
 
1039
`no-lisp-format'
 
1040
     Likewise for Lisp, see *Note lisp-format::.
 
1041
 
 
1042
`elisp-format'
 
1043
`no-elisp-format'
 
1044
     Likewise for Emacs Lisp, see *Note elisp-format::.
 
1045
 
 
1046
`librep-format'
 
1047
`no-librep-format'
 
1048
     Likewise for librep, see *Note librep-format::.
 
1049
 
 
1050
`smalltalk-format'
 
1051
`no-smalltalk-format'
 
1052
     Likewise for Smalltalk, see *Note smalltalk-format::.
 
1053
 
 
1054
`java-format'
 
1055
`no-java-format'
 
1056
     Likewise for Java, see *Note java-format::.
 
1057
 
 
1058
`csharp-format'
 
1059
`no-csharp-format'
 
1060
     Likewise for C#, see *Note csharp-format::.
 
1061
 
 
1062
`awk-format'
 
1063
`no-awk-format'
 
1064
     Likewise for awk, see *Note awk-format::.
 
1065
 
 
1066
`object-pascal-format'
 
1067
`no-object-pascal-format'
 
1068
     Likewise for Object Pascal, see *Note object-pascal-format::.
 
1069
 
 
1070
`ycp-format'
 
1071
`no-ycp-format'
 
1072
     Likewise for YCP, see *Note ycp-format::.
 
1073
 
 
1074
`tcl-format'
 
1075
`no-tcl-format'
 
1076
     Likewise for Tcl, see *Note tcl-format::.
 
1077
 
 
1078
`perl-format'
 
1079
`no-perl-format'
 
1080
     Likewise for Perl, see *Note perl-format::.
 
1081
 
 
1082
`perl-brace-format'
 
1083
`no-perl-brace-format'
 
1084
     Likewise for Perl brace, see *Note perl-format::.
 
1085
 
 
1086
`php-format'
 
1087
`no-php-format'
 
1088
     Likewise for PHP, see *Note php-format::.
 
1089
 
 
1090
`gcc-internal-format'
 
1091
`no-gcc-internal-format'
 
1092
     Likewise for the GCC sources, see *Note gcc-internal-format::.
 
1093
 
 
1094
`qt-format'
 
1095
`no-qt-format'
 
1096
     Likewise for Qt, see *Note qt-format::.
 
1097
 
 
1098
 
 
1099
   A different kind of entries is used for translations which involve
 
1100
plural forms.
 
1101
 
 
1102
     WHITE-SPACE
 
1103
     #  TRANSLATOR-COMMENTS
 
1104
     #. AUTOMATIC-COMMENTS
 
1105
     #: REFERENCE...
 
1106
     #, FLAG...
 
1107
     msgid UNTRANSLATED-STRING-SINGULAR
 
1108
     msgid_plural UNTRANSLATED-STRING-PLURAL
 
1109
     msgstr[0] TRANSLATED-STRING-CASE-0
 
1110
     ...
 
1111
     msgstr[N] TRANSLATED-STRING-CASE-N
 
1112
 
 
1113
   Such an entry can look like this:
 
1114
 
 
1115
     #: src/msgcmp.c:338 src/po-lex.c:699
 
1116
     #, c-format
 
1117
     msgid "found %d fatal error"
 
1118
     msgid_plural "found %d fatal errors"
 
1119
     msgstr[0] "s'ha trobat %d error fatal"
 
1120
     msgstr[1] "s'han trobat %d errors fatals"
 
1121
 
 
1122
   It happens that some lines, usually whitespace or comments, follow
 
1123
the very last entry of a PO file.  Such lines are not part of any entry,
 
1124
and PO mode is unable to take action on those lines.  By using the PO
 
1125
mode function `M-x po-normalize', the translator may get rid of those
 
1126
spurious lines.  *Note Normalizing::.
 
1127
 
 
1128
   The remainder of this section may be safely skipped by those using
 
1129
PO mode, yet it may be interesting for everybody to have a better idea
 
1130
of the precise format of a PO file.  On the other hand, those not
 
1131
having Emacs handy should carefully continue reading on.
 
1132
 
 
1133
   Each of UNTRANSLATED-STRING and TRANSLATED-STRING respects the C
 
1134
syntax for a character string, including the surrounding quotes and
 
1135
embedded backslashed escape sequences.  When the time comes to write
 
1136
multi-line strings, one should not use escaped newlines.  Instead, a
 
1137
closing quote should follow the last character on the line to be
 
1138
continued, and an opening quote should resume the string at the
 
1139
beginning of the following PO file line.  For example:
 
1140
 
 
1141
     msgid ""
 
1142
     "Here is an example of how one might continue a very long string\n"
 
1143
     "for the common case the string represents multi-line output.\n"
 
1144
 
 
1145
In this example, the empty string is used on the first line, to allow
 
1146
better alignment of the `H' from the word `Here' over the `f' from the
 
1147
word `for'.  In this example, the `msgid' keyword is followed by three
 
1148
strings, which are meant to be concatenated.  Concatenating the empty
 
1149
string does not change the resulting overall string, but it is a way
 
1150
for us to comply with the necessity of `msgid' to be followed by a
 
1151
string on the same line, while keeping the multi-line presentation
 
1152
left-justified, as we find this to be a cleaner disposition.  The empty
 
1153
string could have been omitted, but only if the string starting with
 
1154
`Here' was promoted on the first line, right after `msgid'.(1) It was
 
1155
not really necessary either to switch between the two last quoted
 
1156
strings immediately after the newline `\n', the switch could have
 
1157
occurred after _any_ other character, we just did it this way because
 
1158
it is neater.
 
1159
 
 
1160
   One should carefully distinguish between end of lines marked as `\n'
 
1161
_inside_ quotes, which are part of the represented string, and end of
 
1162
lines in the PO file itself, outside string quotes, which have no
 
1163
incidence on the represented string.
 
1164
 
 
1165
   Outside strings, white lines and comments may be used freely.
 
1166
Comments start at the beginning of a line with `#' and extend until the
 
1167
end of the PO file line.  Comments written by translators should have
 
1168
the initial `#' immediately followed by some white space.  If the `#'
 
1169
is not immediately followed by white space, this comment is most likely
 
1170
generated and managed by specialized GNU tools, and might disappear or
 
1171
be replaced unexpectedly when the PO file is given to `msgmerge'.
 
1172
 
 
1173
   ---------- Footnotes ----------
 
1174
 
 
1175
   (1) This limitation is not imposed by GNU `gettext', but is for
 
1176
compatibility with the `msgfmt' implementation on Solaris.
 
1177
 
 
1178
 
 
1179
File: gettext.info,  Node: Main PO Commands,  Next: Entry Positioning,  Prev: PO Files,  Up: Basics
 
1180
 
 
1181
Main PO mode Commands
 
1182
=====================
 
1183
 
 
1184
After setting up Emacs with something similar to the lines in *Note
 
1185
Installation::, PO mode is activated for a window when Emacs finds a PO
 
1186
file in that window.  This puts the window read-only and establishes a
 
1187
po-mode-map, which is a genuine Emacs mode, in a way that is not derived
 
1188
from text mode in any way.  Functions found on `po-mode-hook', if any,
 
1189
will be executed.
 
1190
 
 
1191
   When PO mode is active in a window, the letters `PO' appear in the
 
1192
mode line for that window.  The mode line also displays how many
 
1193
entries of each kind are held in the PO file.  For example, the string
 
1194
`132t+3f+10u+2o' would tell the translator that the PO mode contains
 
1195
132 translated entries (*note Translated Entries::, 3 fuzzy entries
 
1196
(*note Fuzzy Entries::), 10 untranslated entries (*note Untranslated
 
1197
Entries::) and 2 obsolete entries (*note Obsolete Entries::).
 
1198
Zero-coefficients items are not shown.  So, in this example, if the
 
1199
fuzzy entries were unfuzzied, the untranslated entries were translated
 
1200
and the obsolete entries were deleted, the mode line would merely
 
1201
display `145t' for the counters.
 
1202
 
 
1203
   The main PO commands are those which do not fit into the other
 
1204
categories of subsequent sections.  These allow for quitting PO mode or
 
1205
for managing windows in special ways.
 
1206
 
 
1207
`_'
 
1208
     Undo last modification to the PO file (`po-undo').
 
1209
 
 
1210
`Q'
 
1211
     Quit processing and save the PO file (`po-quit').
 
1212
 
 
1213
`q'
 
1214
     Quit processing, possibly after confirmation
 
1215
     (`po-confirm-and-quit').
 
1216
 
 
1217
`0'
 
1218
     Temporary leave the PO file window (`po-other-window').
 
1219
 
 
1220
`?'
 
1221
`h'
 
1222
     Show help about PO mode (`po-help').
 
1223
 
 
1224
`='
 
1225
     Give some PO file statistics (`po-statistics').
 
1226
 
 
1227
`V'
 
1228
     Batch validate the format of the whole PO file (`po-validate').
 
1229
 
 
1230
 
 
1231
   The command `_' (`po-undo') interfaces to the Emacs _undo_ facility.
 
1232
*Note Undoing Changes: (emacs)Undo.  Each time `U' is typed,
 
1233
modifications which the translator did to the PO file are undone a
 
1234
little more.  For the purpose of undoing, each PO mode command is
 
1235
atomic.  This is especially true for the `<RET>' command: the whole
 
1236
edition made by using a single use of this command is undone at once,
 
1237
even if the edition itself implied several actions.  However, while in
 
1238
the editing window, one can undo the edition work quite parsimoniously.
 
1239
 
 
1240
   The commands `Q' (`po-quit') and `q' (`po-confirm-and-quit') are
 
1241
used when the translator is done with the PO file.  The former is a bit
 
1242
less verbose than the latter.  If the file has been modified, it is
 
1243
saved to disk first.  In both cases, and prior to all this, the
 
1244
commands check if any untranslated messages remain in the PO file and,
 
1245
if so, the translator is asked if she really wants to leave off working
 
1246
with this PO file.  This is the preferred way of getting rid of an
 
1247
Emacs PO file buffer.  Merely killing it through the usual command
 
1248
`C-x k' (`kill-buffer') is not the tidiest way to proceed.
 
1249
 
 
1250
   The command `0' (`po-other-window') is another, softer way, to leave
 
1251
PO mode, temporarily.  It just moves the cursor to some other Emacs
 
1252
window, and pops one if necessary.  For example, if the translator just
 
1253
got PO mode to show some source context in some other, she might
 
1254
discover some apparent bug in the program source that needs correction.
 
1255
This command allows the translator to change sex, become a programmer,
 
1256
and have the cursor right into the window containing the program she
 
1257
(or rather _he_) wants to modify.  By later getting the cursor back in
 
1258
the PO file window, or by asking Emacs to edit this file once again, PO
 
1259
mode is then recovered.
 
1260
 
 
1261
   The command `h' (`po-help') displays a summary of all available PO
 
1262
mode commands.  The translator should then type any character to resume
 
1263
normal PO mode operations.  The command `?' has the same effect as `h'.
 
1264
 
 
1265
   The command `=' (`po-statistics') computes the total number of
 
1266
entries in the PO file, the ordinal of the current entry (counted from
 
1267
1), the number of untranslated entries, the number of obsolete entries,
 
1268
and displays all these numbers.
 
1269
 
 
1270
   The command `V' (`po-validate') launches `msgfmt' in checking and
 
1271
verbose mode over the current PO file.  This command first offers to
 
1272
save the current PO file on disk.  The `msgfmt' tool, from GNU
 
1273
`gettext', has the purpose of creating a MO file out of a PO file, and
 
1274
PO mode uses the features of this program for checking the overall
 
1275
format of a PO file, as well as all individual entries.
 
1276
 
 
1277
   The program `msgfmt' runs asynchronously with Emacs, so the
 
1278
translator regains control immediately while her PO file is being
 
1279
studied.  Error output is collected in the Emacs `*compilation*' buffer,
 
1280
displayed in another window.  The regular Emacs command `C-x`'
 
1281
(`next-error'), as well as other usual compile commands, allow the
 
1282
translator to reposition quickly to the offending parts of the PO file.
 
1283
Once the cursor is on the line in error, the translator may decide on
 
1284
any PO mode action which would help correcting the error.
 
1285
 
 
1286
 
 
1287
File: gettext.info,  Node: Entry Positioning,  Next: Normalizing,  Prev: Main PO Commands,  Up: Basics
 
1288
 
 
1289
Entry Positioning
 
1290
=================
 
1291
 
 
1292
The cursor in a PO file window is almost always part of an entry.  The
 
1293
only exceptions are the special case when the cursor is after the last
 
1294
entry in the file, or when the PO file is empty.  The entry where the
 
1295
cursor is found to be is said to be the current entry.  Many PO mode
 
1296
commands operate on the current entry, so moving the cursor does more
 
1297
than allowing the translator to browse the PO file, this also selects
 
1298
on which entry commands operate.
 
1299
 
 
1300
   Some PO mode commands alter the position of the cursor in a
 
1301
specialized way.  A few of those special purpose positioning are
 
1302
described here, the others are described in following sections (for a
 
1303
complete list try `C-h m'):
 
1304
 
 
1305
`.'
 
1306
     Redisplay the current entry (`po-current-entry').
 
1307
 
 
1308
`n'
 
1309
     Select the entry after the current one (`po-next-entry').
 
1310
 
 
1311
`p'
 
1312
     Select the entry before the current one (`po-previous-entry').
 
1313
 
 
1314
`<'
 
1315
     Select the first entry in the PO file (`po-first-entry').
 
1316
 
 
1317
`>'
 
1318
     Select the last entry in the PO file (`po-last-entry').
 
1319
 
 
1320
`m'
 
1321
     Record the location of the current entry for later use
 
1322
     (`po-push-location').
 
1323
 
 
1324
`r'
 
1325
     Return to a previously saved entry location (`po-pop-location').
 
1326
 
 
1327
`x'
 
1328
     Exchange the current entry location with the previously saved one
 
1329
     (`po-exchange-location').
 
1330
 
 
1331
 
 
1332
   Any Emacs command able to reposition the cursor may be used to
 
1333
select the current entry in PO mode, including commands which move by
 
1334
characters, lines, paragraphs, screens or pages, and search commands.
 
1335
However, there is a kind of standard way to display the current entry
 
1336
in PO mode, which usual Emacs commands moving the cursor do not
 
1337
especially try to enforce.  The command `.' (`po-current-entry') has
 
1338
the sole purpose of redisplaying the current entry properly, after the
 
1339
current entry has been changed by means external to PO mode, or the
 
1340
Emacs screen otherwise altered.
 
1341
 
 
1342
   It is yet to be decided if PO mode helps the translator, or otherwise
 
1343
irritates her, by forcing a rigid window disposition while she is doing
 
1344
her work.  We originally had quite precise ideas about how windows
 
1345
should behave, but on the other hand, anyone used to Emacs is often
 
1346
happy to keep full control.  Maybe a fixed window disposition might be
 
1347
offered as a PO mode option that the translator might activate or
 
1348
deactivate at will, so it could be offered on an experimental basis.
 
1349
If nobody feels a real need for using it, or a compulsion for writing
 
1350
it, we should drop this whole idea.  The incentive for doing it should
 
1351
come from translators rather than programmers, as opinions from an
 
1352
experienced translator are surely more worth to me than opinions from
 
1353
programmers _thinking_ about how _others_ should do translation.
 
1354
 
 
1355
   The commands `n' (`po-next-entry') and `p' (`po-previous-entry')
 
1356
move the cursor the entry following, or preceding, the current one.  If
 
1357
`n' is given while the cursor is on the last entry of the PO file, or
 
1358
if `p' is given while the cursor is on the first entry, no move is done.
 
1359
 
 
1360
   The commands `<' (`po-first-entry') and `>' (`po-last-entry') move
 
1361
the cursor to the first entry, or last entry, of the PO file.  When the
 
1362
cursor is located past the last entry in a PO file, most PO mode
 
1363
commands will return an error saying `After last entry'.  Moreover, the
 
1364
commands `<' and `>' have the special property of being able to work
 
1365
even when the cursor is not into some PO file entry, and one may use
 
1366
them for nicely correcting this situation.  But even these commands
 
1367
will fail on a truly empty PO file.  There are development plans for
 
1368
the PO mode for it to interactively fill an empty PO file from sources.
 
1369
*Note Marking::.
 
1370
 
 
1371
   The translator may decide, before working at the translation of a
 
1372
particular entry, that she needs to browse the remainder of the PO
 
1373
file, maybe for finding the terminology or phraseology used in related
 
1374
entries.  She can of course use the standard Emacs idioms for saving
 
1375
the current cursor location in some register, and use that register for
 
1376
getting back, or else, use the location ring.
 
1377
 
 
1378
   PO mode offers another approach, by which cursor locations may be
 
1379
saved onto a special stack.  The command `m' (`po-push-location')
 
1380
merely adds the location of current entry to the stack, pushing the
 
1381
already saved locations under the new one.  The command `r'
 
1382
(`po-pop-location') consumes the top stack element and repositions the
 
1383
cursor to the entry associated with that top element.  This position is
 
1384
then lost, for the next `r' will move the cursor to the previously
 
1385
saved location, and so on until no locations remain on the stack.
 
1386
 
 
1387
   If the translator wants the position to be kept on the location
 
1388
stack, maybe for taking a look at the entry associated with the top
 
1389
element, then go elsewhere with the intent of getting back later, she
 
1390
ought to use `m' immediately after `r'.
 
1391
 
 
1392
   The command `x' (`po-exchange-location') simultaneously repositions
 
1393
the cursor to the entry associated with the top element of the stack of
 
1394
saved locations, and replaces that top element with the location of the
 
1395
current entry before the move.  Consequently, repeating the `x' command
 
1396
toggles alternatively between two entries.  For achieving this, the
 
1397
translator will position the cursor on the first entry, use `m', then
 
1398
position to the second entry, and merely use `x' for making the switch.
 
1399
 
 
1400
 
 
1401
File: gettext.info,  Node: Normalizing,  Prev: Entry Positioning,  Up: Basics
 
1402
 
 
1403
Normalizing Strings in Entries
 
1404
==============================
 
1405
 
 
1406
There are many different ways for encoding a particular string into a
 
1407
PO file entry, because there are so many different ways to split and
 
1408
quote multi-line strings, and even, to represent special characters by
 
1409
backslashed escaped sequences.  Some features of PO mode rely on the
 
1410
ability for PO mode to scan an already existing PO file for a
 
1411
particular string encoded into the `msgid' field of some entry.  Even
 
1412
if PO mode has internally all the built-in machinery for implementing
 
1413
this recognition easily, doing it fast is technically difficult.  To
 
1414
facilitate a solution to this efficiency problem, we decided on a
 
1415
canonical representation for strings.
 
1416
 
 
1417
   A conventional representation of strings in a PO file is currently
 
1418
under discussion, and PO mode experiments with a canonical
 
1419
representation.  Having both `xgettext' and PO mode converging towards
 
1420
a uniform way of representing equivalent strings would be useful, as
 
1421
the internal normalization needed by PO mode could be automatically
 
1422
satisfied when using `xgettext' from GNU `gettext'.  An explicit PO
 
1423
mode normalization should then be only necessary for PO files imported
 
1424
from elsewhere, or for when the convention itself evolves.
 
1425
 
 
1426
   So, for achieving normalization of at least the strings of a given
 
1427
PO file needing a canonical representation, the following PO mode
 
1428
command is available:
 
1429
 
 
1430
`M-x po-normalize'
 
1431
     Tidy the whole PO file by making entries more uniform.
 
1432
 
 
1433
 
 
1434
   The special command `M-x po-normalize', which has no associated
 
1435
keys, revises all entries, ensuring that strings of both original and
 
1436
translated entries use uniform internal quoting in the PO file.  It
 
1437
also removes any crumb after the last entry.  This command may be
 
1438
useful for PO files freshly imported from elsewhere, or if we ever
 
1439
improve on the canonical quoting format we use.  This canonical format
 
1440
is not only meant for getting cleaner PO files, but also for greatly
 
1441
speeding up `msgid' string lookup for some other PO mode commands.
 
1442
 
 
1443
   `M-x po-normalize' presently makes three passes over the entries.
 
1444
The first implements heuristics for converting PO files for GNU
 
1445
`gettext' 0.6 and earlier, in which `msgid' and `msgstr' fields were
 
1446
using K&R style C string syntax for multi-line strings.  These
 
1447
heuristics may fail for comments not related to obsolete entries and
 
1448
ending with a backslash; they also depend on subsequent passes for
 
1449
finalizing the proper commenting of continued lines for obsolete
 
1450
entries.  This first pass might disappear once all oldish PO files
 
1451
would have been adjusted.  The second and third pass normalize all
 
1452
`msgid' and `msgstr' strings respectively.  They also clean out those
 
1453
trailing backslashes used by XView's `msgfmt' for continued lines.
 
1454
 
 
1455
   Having such an explicit normalizing command allows for importing PO
 
1456
files from other sources, but also eases the evolution of the current
 
1457
convention, evolution driven mostly by aesthetic concerns, as of now.
 
1458
It is easy to make suggested adjustments at a later time, as the
 
1459
normalizing command and eventually, other GNU `gettext' tools should
 
1460
greatly automate conformance.  A description of the canonical string
 
1461
format is given below, for the particular benefit of those not having
 
1462
Emacs handy, and who would nevertheless want to handcraft their PO
 
1463
files in nice ways.
 
1464
 
 
1465
   Right now, in PO mode, strings are single line or multi-line.  A
 
1466
string goes multi-line if and only if it has _embedded_ newlines, that
 
1467
is, if it matches `[^\n]\n+[^\n]'.  So, we would have:
 
1468
 
 
1469
     msgstr "\n\nHello, world!\n\n\n"
 
1470
 
 
1471
   but, replacing the space by a newline, this becomes:
 
1472
 
 
1473
     msgstr ""
 
1474
     "\n"
 
1475
     "\n"
 
1476
     "Hello,\n"
 
1477
     "world!\n"
 
1478
     "\n"
 
1479
     "\n"
 
1480
 
 
1481
   We are deliberately using a caricatural example, here, to make the
 
1482
point clearer.  Usually, multi-lines are not that bad looking.  It is
 
1483
probable that we will implement the following suggestion.  We might
 
1484
lump together all initial newlines into the empty string, and also all
 
1485
newlines introducing empty lines (that is, for N > 1, the N-1'th last
 
1486
newlines would go together on a separate string), so making the
 
1487
previous example appear:
 
1488
 
 
1489
     msgstr "\n\n"
 
1490
     "Hello,\n"
 
1491
     "world!\n"
 
1492
     "\n\n"
 
1493
 
 
1494
   There are a few yet undecided little points about string
 
1495
normalization, to be documented in this manual, once these questions
 
1496
settle.
 
1497
 
 
1498
 
 
1499
File: gettext.info,  Node: Sources,  Next: Template,  Prev: Basics,  Up: Top
 
1500
 
 
1501
Preparing Program Sources
 
1502
*************************
 
1503
 
 
1504
For the programmer, changes to the C source code fall into three
 
1505
categories.  First, you have to make the localization functions known
 
1506
to all modules needing message translation.  Second, you should
 
1507
properly trigger the operation of GNU `gettext' when the program
 
1508
initializes, usually from the `main' function.  Last, you should
 
1509
identify and especially mark all constant strings in your program
 
1510
needing translation.
 
1511
 
 
1512
   Presuming that your set of programs, or package, has been adjusted
 
1513
so all needed GNU `gettext' files are available, and your `Makefile'
 
1514
files are adjusted (*note Maintainers::), each C module having
 
1515
translated C strings should contain the line:
 
1516
 
 
1517
     #include <libintl.h>
 
1518
 
 
1519
   Similarly, each C module containing `printf()'/`fprintf()'/...
 
1520
calls with a format string that could be a translated C string (even if
 
1521
the C string comes from a different C module) should contain the line:
 
1522
 
 
1523
     #include <libintl.h>
 
1524
 
 
1525
   The remaining changes to your C sources are discussed in the further
 
1526
sections of this chapter.
 
1527
 
 
1528
* Menu:
 
1529
 
 
1530
* Triggering::                  Triggering `gettext' Operations
 
1531
* Preparing Strings::           Preparing Translatable Strings
 
1532
* Mark Keywords::               How Marks Appear in Sources
 
1533
* Marking::                     Marking Translatable Strings
 
1534
* c-format Flag::               Telling something about the following string
 
1535
* Special cases::               Special Cases of Translatable Strings
 
1536
* Names::                       Marking Proper Names for Translation
 
1537
* Libraries::                   Preparing Library Sources
 
1538
 
 
1539
 
 
1540
File: gettext.info,  Node: Triggering,  Next: Preparing Strings,  Prev: Sources,  Up: Sources
 
1541
 
 
1542
Triggering `gettext' Operations
 
1543
===============================
 
1544
 
 
1545
The initialization of locale data should be done with more or less the
 
1546
same code in every program, as demonstrated below:
 
1547
 
 
1548
     int
 
1549
     main (int argc, char *argv[])
 
1550
     {
 
1551
       ...
 
1552
       setlocale (LC_ALL, "");
 
1553
       bindtextdomain (PACKAGE, LOCALEDIR);
 
1554
       textdomain (PACKAGE);
 
1555
       ...
 
1556
     }
 
1557
 
 
1558
   PACKAGE and LOCALEDIR should be provided either by `config.h' or by
 
1559
the Makefile.  For now consult the `gettext' or `hello' sources for
 
1560
more information.
 
1561
 
 
1562
   The use of `LC_ALL' might not be appropriate for you.  `LC_ALL'
 
1563
includes all locale categories and especially `LC_CTYPE'.  This later
 
1564
category is responsible for determining character classes with the
 
1565
`isalnum' etc. functions from `ctype.h' which could especially for
 
1566
programs, which process some kind of input language, be wrong.  For
 
1567
example this would mean that a source code using the c, (c-cedilla
 
1568
character) is runnable in France but not in the U.S.
 
1569
 
 
1570
   Some systems also have problems with parsing numbers using the
 
1571
`scanf' functions if an other but the `LC_ALL' locale is used.  The
 
1572
standards say that additional formats but the one known in the `"C"'
 
1573
locale might be recognized.  But some systems seem to reject numbers in
 
1574
the `"C"' locale format.  In some situation, it might also be a problem
 
1575
with the notation itself which makes it impossible to recognize whether
 
1576
the number is in the `"C"' locale or the local format.  This can happen
 
1577
if thousands separator characters are used.  Some locales define this
 
1578
character according to the national conventions to `'.'' which is the
 
1579
same character used in the `"C"' locale to denote the decimal point.
 
1580
 
 
1581
   So it is sometimes necessary to replace the `LC_ALL' line in the
 
1582
code above by a sequence of `setlocale' lines
 
1583
 
 
1584
     {
 
1585
       ...
 
1586
       setlocale (LC_CTYPE, "");
 
1587
       setlocale (LC_MESSAGES, "");
 
1588
       ...
 
1589
     }
 
1590
 
 
1591
On all POSIX conformant systems the locale categories `LC_CTYPE',
 
1592
`LC_MESSAGES', `LC_COLLATE', `LC_MONETARY', `LC_NUMERIC', and `LC_TIME'
 
1593
are available.  On some systems which are only ISO C compliant,
 
1594
`LC_MESSAGES' is missing, but a substitute for it is defined in GNU
 
1595
gettext's `<libintl.h>'.
 
1596
 
 
1597
   Note that changing the `LC_CTYPE' also affects the functions
 
1598
declared in the `<ctype.h>' standard header.  If this is not desirable
 
1599
in your application (for example in a compiler's parser), you can use a
 
1600
set of substitute functions which hardwire the C locale, such as found
 
1601
in the `<c-ctype.h>' and `<c-ctype.c>' files in the gettext source
 
1602
distribution.
 
1603
 
 
1604
   It is also possible to switch the locale forth and back between the
 
1605
environment dependent locale and the C locale, but this approach is
 
1606
normally avoided because a `setlocale' call is expensive, because it is
 
1607
tedious to determine the places where a locale switch is needed in a
 
1608
large program's source, and because switching a locale is not
 
1609
multithread-safe.
 
1610
 
 
1611
 
 
1612
File: gettext.info,  Node: Preparing Strings,  Next: Mark Keywords,  Prev: Triggering,  Up: Sources
 
1613
 
 
1614
Preparing Translatable Strings
 
1615
==============================
 
1616
 
 
1617
Before strings can be marked for translations, they sometimes need to
 
1618
be adjusted.  Usually preparing a string for translation is done right
 
1619
before marking it, during the marking phase which is described in the
 
1620
next sections.  What you have to keep in mind while doing that is the
 
1621
following.
 
1622
 
 
1623
   * Decent English style.
 
1624
 
 
1625
   * Entire sentences.
 
1626
 
 
1627
   * Split at paragraphs.
 
1628
 
 
1629
   * Use format strings instead of string concatenation.
 
1630
 
 
1631
Let's look at some examples of these guidelines.
 
1632
 
 
1633
   Translatable strings should be in good English style.  If slang
 
1634
language with abbreviations and shortcuts is used, often translators
 
1635
will not understand the message and will produce very inappropriate
 
1636
translations.
 
1637
 
 
1638
     "%s: is parameter\n"
 
1639
 
 
1640
This is nearly untranslatable: Is the displayed item _a_ parameter or
 
1641
_the_ parameter?
 
1642
 
 
1643
     "No match"
 
1644
 
 
1645
The ambiguity in this message makes it ununderstandable: Is the program
 
1646
attempting to set something on fire? Does it mean "The given object does
 
1647
not match the template"? Does it mean "The template does not fit for any
 
1648
of the objects"?
 
1649
 
 
1650
   In both cases, adding more words to the message will help both the
 
1651
translator and the English speaking user.
 
1652
 
 
1653
   Translatable strings should be entire sentences.  It is often not
 
1654
possible to translate single verbs or adjectives in a substitutable way.
 
1655
 
 
1656
     printf ("File %s is %s protected", filename, rw ? "write" : "read");
 
1657
 
 
1658
Most translators will not look at the source and will thus only see the
 
1659
string `"File %s is %s protected"', which is unintelligible.  Change
 
1660
this to
 
1661
 
 
1662
     printf (rw ? "File %s is write protected" : "File %s is read protected",
 
1663
             filename);
 
1664
 
 
1665
This way the translator will not only understand the message, she will
 
1666
also be able to find the appropriate grammatical construction.  The
 
1667
French translator for example translates "write protected" like
 
1668
"protected against writing".
 
1669
 
 
1670
   Entire sentences are also important because in many languages, the
 
1671
declination of some word in a sentence depends on the gender or the
 
1672
number (singular/plural) of another part of the sentence.  There are
 
1673
usually more interdependencies between words than in English.  The
 
1674
consequence is that asking a translator to translate two half-sentences
 
1675
and then combining these two half-sentences through dumb string
 
1676
concatenation will not work, for many languages, even though it would
 
1677
work for English.  That's why translators need to handle entire
 
1678
sentences.
 
1679
 
 
1680
   Often sentences don't fit into a single line.  If a sentence is
 
1681
output using two subsequent `printf' statements, like this
 
1682
 
 
1683
     printf ("Locale charset \"%s\" is different from\n", lcharset);
 
1684
     printf ("input file charset \"%s\".\n", fcharset);
 
1685
 
 
1686
the translator would have to translate two half sentences, but nothing
 
1687
in the POT file would tell her that the two half sentences belong
 
1688
together.  It is necessary to merge the two `printf' statements so that
 
1689
the translator can handle the entire sentence at once and decide at
 
1690
which place to insert a line break in the translation (if at all):
 
1691
 
 
1692
     printf ("Locale charset \"%s\" is different from\n\
 
1693
     input file charset \"%s\".\n", lcharset, fcharset);
 
1694
 
 
1695
   You may now ask: how about two or more adjacent sentences? Like in
 
1696
this case:
 
1697
 
 
1698
     puts ("Apollo 13 scenario: Stack overflow handling failed.");
 
1699
     puts ("On the next stack overflow we will crash!!!");
 
1700
 
 
1701
Should these two statements merged into a single one? I would recommend
 
1702
to merge them if the two sentences are related to each other, because
 
1703
then it makes it easier for the translator to understand and translate
 
1704
both.  On the other hand, if one of the two messages is a stereotypic
 
1705
one, occurring in other places as well, you will do a favour to the
 
1706
translator by not merging the two.  (Identical messages occurring in
 
1707
several places are combined by xgettext, so the translator has to
 
1708
handle them once only.)
 
1709
 
 
1710
   Translatable strings should be limited to one paragraph; don't let a
 
1711
single message be longer than ten lines.  The reason is that when the
 
1712
translatable string changes, the translator is faced with the task of
 
1713
updating the entire translated string.  Maybe only a single word will
 
1714
have changed in the English string, but the translator doesn't see that
 
1715
(with the current translation tools), therefore she has to proofread
 
1716
the entire message.
 
1717
 
 
1718
   Many GNU programs have a `--help' output that extends over several
 
1719
screen pages.  It is a courtesy towards the translators to split such a
 
1720
message into several ones of five to ten lines each.  While doing that,
 
1721
you can also attempt to split the documented options into groups, such
 
1722
as the input options, the output options, and the informative output
 
1723
options.  This will help every user to find the option he is looking
 
1724
for.
 
1725
 
 
1726
   Hardcoded string concatenation is sometimes used to construct English
 
1727
strings:
 
1728
 
 
1729
     strcpy (s, "Replace ");
 
1730
     strcat (s, object1);
 
1731
     strcat (s, " with ");
 
1732
     strcat (s, object2);
 
1733
     strcat (s, "?");
 
1734
 
 
1735
In order to present to the translator only entire sentences, and also
 
1736
because in some languages the translator might want to swap the order
 
1737
of `object1' and `object2', it is necessary to change this to use a
 
1738
format string:
 
1739
 
 
1740
     sprintf (s, "Replace %s with %s?", object1, object2);
 
1741
 
 
1742
   A similar case is compile time concatenation of strings.  The ISO C
 
1743
99 include file `<inttypes.h>' contains a macro `PRId64' that can be
 
1744
used as a formatting directive for outputting an `int64_t' integer
 
1745
through `printf'.  It expands to a constant string, usually "d" or "ld"
 
1746
or "lld" or something like this, depending on the platform.  Assume you
 
1747
have code like
 
1748
 
 
1749
     printf ("The amount is %0" PRId64 "\n", number);
 
1750
 
 
1751
The `gettext' tools and library have special support for these
 
1752
`<inttypes.h>' macros.  You can therefore simply write
 
1753
 
 
1754
     printf (gettext ("The amount is %0" PRId64 "\n"), number);
 
1755
 
 
1756
The PO file will contain the string "The amount is %0<PRId64>\n".  The
 
1757
translators will provide a translation containing "%0<PRId64>" as well,
 
1758
and at runtime the `gettext' function's result will contain the
 
1759
appropriate constant string, "d" or "ld" or "lld".
 
1760
 
 
1761
   This works only for the predefined `<inttypes.h>' macros.  If you
 
1762
have defined your own similar macros, let's say `MYPRId64', that are
 
1763
not known to `xgettext', the solution for this problem is to change the
 
1764
code like this:
 
1765
 
 
1766
     char buf1[100];
 
1767
     sprintf (buf1, "%0" MYPRId64, number);
 
1768
     printf (gettext ("The amount is %s\n"), buf1);
 
1769
 
 
1770
   This means, you put the platform dependent code in one statement,
 
1771
and the internationalization code in a different statement.  Note that
 
1772
a buffer length of 100 is safe, because all available hardware integer
 
1773
types are limited to 128 bits, and to print a 128 bit integer one needs
 
1774
at most 54 characters, regardless whether in decimal, octal or
 
1775
hexadecimal.
 
1776
 
 
1777
   All this applies to other programming languages as well.  For
 
1778
example, in Java and C#, string contenation is very frequently used,
 
1779
because it is a compiler built-in operator.  Like in C, in Java, you
 
1780
would change
 
1781
 
 
1782
     System.out.println("Replace "+object1+" with "+object2+"?");
 
1783
 
 
1784
into a statement involving a format string:
 
1785
 
 
1786
     System.out.println(
 
1787
         MessageFormat.format("Replace {0} with {1}?",
 
1788
                              new Object[] { object1, object2 }));
 
1789
 
 
1790
Similarly, in C#, you would change
 
1791
 
 
1792
     Console.WriteLine("Replace "+object1+" with "+object2+"?");
 
1793
 
 
1794
into a statement involving a format string:
 
1795
 
 
1796
     Console.WriteLine(
 
1797
         String.Format("Replace {0} with {1}?", object1, object2));
 
1798
 
 
1799
 
 
1800
File: gettext.info,  Node: Mark Keywords,  Next: Marking,  Prev: Preparing Strings,  Up: Sources
 
1801
 
 
1802
How Marks Appear in Sources
 
1803
===========================
 
1804
 
 
1805
All strings requiring translation should be marked in the C sources.
 
1806
Marking is done in such a way that each translatable string appears to
 
1807
be the sole argument of some function or preprocessor macro.  There are
 
1808
only a few such possible functions or macros meant for translation, and
 
1809
their names are said to be marking keywords.  The marking is attached
 
1810
to strings themselves, rather than to what we do with them.  This
 
1811
approach has more uses.  A blatant example is an error message produced
 
1812
by formatting.  The format string needs translation, as well as some
 
1813
strings inserted through some `%s' specification in the format, while
 
1814
the result from `sprintf' may have so many different instances that it
 
1815
is impractical to list them all in some `error_string_out()' routine,
 
1816
say.
 
1817
 
 
1818
   This marking operation has two goals.  The first goal of marking is
 
1819
for triggering the retrieval of the translation, at run time.  The
 
1820
keyword are possibly resolved into a routine able to dynamically return
 
1821
the proper translation, as far as possible or wanted, for the argument
 
1822
string.  Most localizable strings are found in executable positions,
 
1823
that is, attached to variables or given as parameters to functions.
 
1824
But this is not universal usage, and some translatable strings appear
 
1825
in structured initializations.  *Note Special cases::.
 
1826
 
 
1827
   The second goal of the marking operation is to help `xgettext' at
 
1828
properly extracting all translatable strings when it scans a set of
 
1829
program sources and produces PO file templates.
 
1830
 
 
1831
   The canonical keyword for marking translatable strings is `gettext',
 
1832
it gave its name to the whole GNU `gettext' package.  For packages
 
1833
making only light use of the `gettext' keyword, macro or function, it
 
1834
is easily used _as is_.  However, for packages using the `gettext'
 
1835
interface more heavily, it is usually more convenient to give the main
 
1836
keyword a shorter, less obtrusive name.  Indeed, the keyword might
 
1837
appear on a lot of strings all over the package, and programmers
 
1838
usually do not want nor need their program sources to remind them
 
1839
forcefully, all the time, that they are internationalized.  Further, a
 
1840
long keyword has the disadvantage of using more horizontal space,
 
1841
forcing more indentation work on sources for those trying to keep them
 
1842
within 79 or 80 columns.
 
1843
 
 
1844
   Many packages use `_' (a simple underline) as a keyword, and write
 
1845
`_("Translatable string")' instead of `gettext ("Translatable
 
1846
string")'.  Further, the coding rule, from GNU standards, wanting that
 
1847
there is a space between the keyword and the opening parenthesis is
 
1848
relaxed, in practice, for this particular usage.  So, the textual
 
1849
overhead per translatable string is reduced to only three characters:
 
1850
the underline and the two parentheses.  However, even if GNU `gettext'
 
1851
uses this convention internally, it does not offer it officially.  The
 
1852
real, genuine keyword is truly `gettext' indeed.  It is fairly easy for
 
1853
those wanting to use `_' instead of `gettext' to declare:
 
1854
 
 
1855
     #include <libintl.h>
 
1856
     #define _(String) gettext (String)
 
1857
 
 
1858
instead of merely using `#include <libintl.h>'.
 
1859
 
 
1860
   Later on, the maintenance is relatively easy.  If, as a programmer,
 
1861
you add or modify a string, you will have to ask yourself if the new or
 
1862
altered string requires translation, and include it within `_()' if you
 
1863
think it should be translated.  `"%s: %d"' is an example of string
 
1864
_not_ requiring translation!
 
1865
 
 
1866
 
 
1867
File: gettext.info,  Node: Marking,  Next: c-format Flag,  Prev: Mark Keywords,  Up: Sources
 
1868
 
 
1869
Marking Translatable Strings
 
1870
============================
 
1871
 
 
1872
In PO mode, one set of features is meant more for the programmer than
 
1873
for the translator, and allows him to interactively mark which strings,
 
1874
in a set of program sources, are translatable, and which are not.  Even
 
1875
if it is a fairly easy job for a programmer to find and mark such
 
1876
strings by other means, using any editor of his choice, PO mode makes
 
1877
this work more comfortable.  Further, this gives translators who feel a
 
1878
little like programmers, or programmers who feel a little like
 
1879
translators, a tool letting them work at marking translatable strings
 
1880
in the program sources, while simultaneously producing a set of
 
1881
translation in some language, for the package being internationalized.
 
1882
 
 
1883
   The set of program sources, targetted by the PO mode commands
 
1884
describe here, should have an Emacs tags table constructed for your
 
1885
project, prior to using these PO file commands.  This is easy to do.
 
1886
In any shell window, change the directory to the root of your project,
 
1887
then execute a command resembling:
 
1888
 
 
1889
     etags src/*.[hc] lib/*.[hc]
 
1890
 
 
1891
presuming here you want to process all `.h' and `.c' files from the
 
1892
`src/' and `lib/' directories.  This command will explore all said
 
1893
files and create a `TAGS' file in your root directory, somewhat
 
1894
summarizing the contents using a special file format Emacs can
 
1895
understand.
 
1896
 
 
1897
   For packages following the GNU coding standards, there is a make
 
1898
goal `tags' or `TAGS' which constructs the tag files in all directories
 
1899
and for all files containing source code.
 
1900
 
 
1901
   Once your `TAGS' file is ready, the following commands assist the
 
1902
programmer at marking translatable strings in his set of sources.  But
 
1903
these commands are necessarily driven from within a PO file window, and
 
1904
it is likely that you do not even have such a PO file yet.  This is not
 
1905
a problem at all, as you may safely open a new, empty PO file, mainly
 
1906
for using these commands.  This empty PO file will slowly fill in while
 
1907
you mark strings as translatable in your program sources.
 
1908
 
 
1909
`,'
 
1910
     Search through program sources for a string which looks like a
 
1911
     candidate for translation (`po-tags-search').
 
1912
 
 
1913
`M-,'
 
1914
     Mark the last string found with `_()' (`po-mark-translatable').
 
1915
 
 
1916
`M-.'
 
1917
     Mark the last string found with a keyword taken from a set of
 
1918
     possible keywords.  This command with a prefix allows some
 
1919
     management of these keywords (`po-select-mark-and-mark').
 
1920
 
 
1921
 
 
1922
   The `,' (`po-tags-search') command searches for the next occurrence
 
1923
of a string which looks like a possible candidate for translation, and
 
1924
displays the program source in another Emacs window, positioned in such
 
1925
a way that the string is near the top of this other window.  If the
 
1926
string is too big to fit whole in this window, it is positioned so only
 
1927
its end is shown.  In any case, the cursor is left in the PO file
 
1928
window.  If the shown string would be better presented differently in
 
1929
different native languages, you may mark it using `M-,' or `M-.'.
 
1930
Otherwise, you might rather ignore it and skip to the next string by
 
1931
merely repeating the `,' command.
 
1932
 
 
1933
   A string is a good candidate for translation if it contains a
 
1934
sequence of three or more letters.  A string containing at most two
 
1935
letters in a row will be considered as a candidate if it has more
 
1936
letters than non-letters.  The command disregards strings containing no
 
1937
letters, or isolated letters only.  It also disregards strings within
 
1938
comments, or strings already marked with some keyword PO mode knows
 
1939
(see below).
 
1940
 
 
1941
   If you have never told Emacs about some `TAGS' file to use, the
 
1942
command will request that you specify one from the minibuffer, the
 
1943
first time you use the command.  You may later change your `TAGS' file
 
1944
by using the regular Emacs command `M-x visit-tags-table', which will
 
1945
ask you to name the precise `TAGS' file you want to use.  *Note Tag
 
1946
Tables: (emacs)Tags.
 
1947
 
 
1948
   Each time you use the `,' command, the search resumes from where it
 
1949
was left by the previous search, and goes through all program sources,
 
1950
obeying the `TAGS' file, until all sources have been processed.
 
1951
However, by giving a prefix argument to the command (`C-u ,'), you may
 
1952
request that the search be restarted all over again from the first
 
1953
program source; but in this case, strings that you recently marked as
 
1954
translatable will be automatically skipped.
 
1955
 
 
1956
   Using this `,' command does not prevent using of other regular Emacs
 
1957
tags commands.  For example, regular `tags-search' or
 
1958
`tags-query-replace' commands may be used without disrupting the
 
1959
independent `,' search sequence.  However, as implemented, the
 
1960
_initial_ `,' command (or the `,' command is used with a prefix) might
 
1961
also reinitialize the regular Emacs tags searching to the first tags
 
1962
file, this reinitialization might be considered spurious.
 
1963
 
 
1964
   The `M-,' (`po-mark-translatable') command will mark the recently
 
1965
found string with the `_' keyword.  The `M-.'
 
1966
(`po-select-mark-and-mark') command will request that you type one
 
1967
keyword from the minibuffer and use that keyword for marking the
 
1968
string.  Both commands will automatically create a new PO file
 
1969
untranslated entry for the string being marked, and make it the current
 
1970
entry (making it easy for you to immediately proceed to its
 
1971
translation, if you feel like doing it right away).  It is possible
 
1972
that the modifications made to the program source by `M-,' or `M-.'
 
1973
render some source line longer than 80 columns, forcing you to break
 
1974
and re-indent this line differently.  You may use the `O' command from
 
1975
PO mode, or any other window changing command from Emacs, to break out
 
1976
into the program source window, and do any needed adjustments.  You
 
1977
will have to use some regular Emacs command to return the cursor to the
 
1978
PO file window, if you want command `,' for the next string, say.
 
1979
 
 
1980
   The `M-.' command has a few built-in speedups, so you do not have to
 
1981
explicitly type all keywords all the time.  The first such speedup is
 
1982
that you are presented with a _preferred_ keyword, which you may accept
 
1983
by merely typing `<RET>' at the prompt.  The second speedup is that you
 
1984
may type any non-ambiguous prefix of the keyword you really mean, and
 
1985
the command will complete it automatically for you.  This also means
 
1986
that PO mode has to _know_ all your possible keywords, and that it will
 
1987
not accept mistyped keywords.
 
1988
 
 
1989
   If you reply `?' to the keyword request, the command gives a list of
 
1990
all known keywords, from which you may choose.  When the command is
 
1991
prefixed by an argument (`C-u M-.'), it inhibits updating any program
 
1992
source or PO file buffer, and does some simple keyword management
 
1993
instead.  In this case, the command asks for a keyword, written in
 
1994
full, which becomes a new allowed keyword for later `M-.' commands.
 
1995
Moreover, this new keyword automatically becomes the _preferred_
 
1996
keyword for later commands.  By typing an already known keyword in
 
1997
response to `C-u M-.', one merely changes the _preferred_ keyword and
 
1998
does nothing more.
 
1999
 
 
2000
   All keywords known for `M-.' are recognized by the `,' command when
 
2001
scanning for strings, and strings already marked by any of those known
 
2002
keywords are automatically skipped.  If many PO files are opened
 
2003
simultaneously, each one has its own independent set of known keywords.
 
2004
There is no provision in PO mode, currently, for deleting a known
 
2005
keyword, you have to quit the file (maybe using `q') and reopen it
 
2006
afresh.  When a PO file is newly brought up in an Emacs window, only
 
2007
`gettext' and `_' are known as keywords, and `gettext' is preferred for
 
2008
the `M-.' command.  In fact, this is not useful to prefer `_', as this
 
2009
one is already built in the `M-,' command.
 
2010
 
 
2011
 
 
2012
File: gettext.info,  Node: c-format Flag,  Next: Special cases,  Prev: Marking,  Up: Sources
 
2013
 
 
2014
Special Comments preceding Keywords
 
2015
===================================
 
2016
 
 
2017
In C programs strings are often used within calls of functions from the
 
2018
`printf' family.  The special thing about these format strings is that
 
2019
they can contain format specifiers introduced with `%'.  Assume we have
 
2020
the code
 
2021
 
 
2022
     printf (gettext ("String `%s' has %d characters\n"), s, strlen (s));
 
2023
 
 
2024
A possible German translation for the above string might be:
 
2025
 
 
2026
     "%d Zeichen lang ist die Zeichenkette `%s'"
 
2027
 
 
2028
   A C programmer, even if he cannot speak German, will recognize that
 
2029
there is something wrong here.  The order of the two format specifiers
 
2030
is changed but of course the arguments in the `printf' don't have.
 
2031
This will most probably lead to problems because now the length of the
 
2032
string is regarded as the address.
 
2033
 
 
2034
   To prevent errors at runtime caused by translations the `msgfmt'
 
2035
tool can check statically whether the arguments in the original and the
 
2036
translation string match in type and number.  If this is not the case
 
2037
and the `-c' option has been passed to `msgfmt', `msgfmt' will give an
 
2038
error and refuse to produce a MO file.  Thus consequent use of `msgfmt
 
2039
-c' will catch the error, so that it cannot cause cause problems at
 
2040
runtime.
 
2041
 
 
2042
If the word order in the above German translation would be correct one
 
2043
would have to write
 
2044
 
 
2045
     "%2$d Zeichen lang ist die Zeichenkette `%1$s'"
 
2046
 
 
2047
The routines in `msgfmt' know about this special notation.
 
2048
 
 
2049
   Because not all strings in a program must be format strings it is not
 
2050
useful for `msgfmt' to test all the strings in the `.po' file.  This
 
2051
might cause problems because the string might contain what looks like a
 
2052
format specifier, but the string is not used in `printf'.
 
2053
 
 
2054
   Therefore the `xgettext' adds a special tag to those messages it
 
2055
thinks might be a format string.  There is no absolute rule for this,
 
2056
only a heuristic.  In the `.po' file the entry is marked using the
 
2057
`c-format' flag in the `#,' comment line (*note PO Files::).
 
2058
 
 
2059
   The careful reader now might say that this again can cause problems.
 
2060
The heuristic might guess it wrong.  This is true and therefore
 
2061
`xgettext' knows about a special kind of comment which lets the
 
2062
programmer take over the decision.  If in the same line as or the
 
2063
immediately preceding line to the `gettext' keyword the `xgettext'
 
2064
program finds a comment containing the words `xgettext:c-format', it
 
2065
will mark the string in any case with the `c-format' flag.  This kind
 
2066
of comment should be used when `xgettext' does not recognize the string
 
2067
as a format string but it really is one and it should be tested.
 
2068
Please note that when the comment is in the same line as the `gettext'
 
2069
keyword, it must be before the string to be translated.
 
2070
 
 
2071
   This situation happens quite often.  The `printf' function is often
 
2072
called with strings which do not contain a format specifier.  Of course
 
2073
one would normally use `fputs' but it does happen.  In this case
 
2074
`xgettext' does not recognize this as a format string but what happens
 
2075
if the translation introduces a valid format specifier?  The `printf'
 
2076
function will try to access one of the parameters but none exists
 
2077
because the original code does not pass any parameters.
 
2078
 
 
2079
   `xgettext' of course could make a wrong decision the other way
 
2080
round, i.e. a string marked as a format string actually is not a format
 
2081
string.  In this case the `msgfmt' might give too many warnings and
 
2082
would prevent translating the `.po' file.  The method to prevent this
 
2083
wrong decision is similar to the one used above, only the comment to
 
2084
use must contain the string `xgettext:no-c-format'.
 
2085
 
 
2086
   If a string is marked with `c-format' and this is not correct the
 
2087
user can find out who is responsible for the decision.  See *Note
 
2088
xgettext Invocation:: to see how the `--debug' option can be used for
 
2089
solving this problem.
 
2090
 
 
2091
 
 
2092
File: gettext.info,  Node: Special cases,  Next: Names,  Prev: c-format Flag,  Up: Sources
 
2093
 
 
2094
Special Cases of Translatable Strings
 
2095
=====================================
 
2096
 
 
2097
The attentive reader might now point out that it is not always possible
 
2098
to mark translatable string with `gettext' or something like this.
 
2099
Consider the following case:
 
2100
 
 
2101
     {
 
2102
       static const char *messages[] = {
 
2103
         "some very meaningful message",
 
2104
         "and another one"
 
2105
       };
 
2106
       const char *string;
 
2107
       ...
 
2108
       string
 
2109
         = index > 1 ? "a default message" : messages[index];
 
2110
     
 
2111
       fputs (string);
 
2112
       ...
 
2113
     }
 
2114
 
 
2115
   While it is no problem to mark the string `"a default message"' it
 
2116
is not possible to mark the string initializers for `messages'.  What
 
2117
is to be done?  We have to fulfill two tasks.  First we have to mark the
 
2118
strings so that the `xgettext' program (*note xgettext Invocation::)
 
2119
can find them, and second we have to translate the string at runtime
 
2120
before printing them.
 
2121
 
 
2122
   The first task can be fulfilled by creating a new keyword, which
 
2123
names a no-op.  For the second we have to mark all access points to a
 
2124
string from the array.  So one solution can look like this:
 
2125
 
 
2126
     #define gettext_noop(String) String
 
2127
     
 
2128
     {
 
2129
       static const char *messages[] = {
 
2130
         gettext_noop ("some very meaningful message"),
 
2131
         gettext_noop ("and another one")
 
2132
       };
 
2133
       const char *string;
 
2134
       ...
 
2135
       string
 
2136
         = index > 1 ? gettext ("a default message") : gettext (messages[index]);
 
2137
     
 
2138
       fputs (string);
 
2139
       ...
 
2140
     }
 
2141
 
 
2142
   Please convince yourself that the string which is written by `fputs'
 
2143
is translated in any case.  How to get `xgettext' know the additional
 
2144
keyword `gettext_noop' is explained in *Note xgettext Invocation::.
 
2145
 
 
2146
   The above is of course not the only solution.  You could also come
 
2147
along with the following one:
 
2148
 
 
2149
     #define gettext_noop(String) String
 
2150
     
 
2151
     {
 
2152
       static const char *messages[] = {
 
2153
         gettext_noop ("some very meaningful message",
 
2154
         gettext_noop ("and another one")
 
2155
       };
 
2156
       const char *string;
 
2157
       ...
 
2158
       string
 
2159
         = index > 1 ? gettext_noop ("a default message") : messages[index];
 
2160
     
 
2161
       fputs (gettext (string));
 
2162
       ...
 
2163
     }
 
2164
 
 
2165
   But this has a drawback.  The programmer has to take care that he
 
2166
uses `gettext_noop' for the string `"a default message"'.  A use of
 
2167
`gettext' could have in rare cases unpredictable results.
 
2168
 
 
2169
   One advantage is that you need not make control flow analysis to make
 
2170
sure the output is really translated in any case.  But this analysis is
 
2171
generally not very difficult.  If it should be in any situation you can
 
2172
use this second method in this situation.
 
2173
 
 
2174
 
 
2175
File: gettext.info,  Node: Names,  Next: Libraries,  Prev: Special cases,  Up: Sources
 
2176
 
 
2177
Marking Proper Names for Translation
 
2178
====================================
 
2179
 
 
2180
Should names of persons, cities, locations etc. be marked for
 
2181
translation or not?  People who only know languages that can be written
 
2182
with Latin letters (English, Spanish, French, German, etc.) are tempted
 
2183
to say "no", because names usually do not change when transported
 
2184
between these languages.  However, in general when translating from one
 
2185
script to another, names are translated too, usually phonetically or by
 
2186
transliteration.  For example, Russian or Greek names are converted to
 
2187
the Latin alphabet when being translated to English, and English or
 
2188
French names are converted to the Katakana script when being translated
 
2189
to Japanese.  This is necessary because the speakers of the target
 
2190
language in general cannot read the script the name is originally
 
2191
written in.
 
2192
 
 
2193
   As a programmer, you should therefore make sure that names are marked
 
2194
for translation, with a special comment telling the translators that it
 
2195
is a proper name and how to pronounce it.  Like this:
 
2196
 
 
2197
     printf (_("Written by %s.\n"),
 
2198
             /* TRANSLATORS: This is a proper name.  See the gettext
 
2199
                manual, section Names.  Note this is actually a non-ASCII
 
2200
                name: The first name is (with Unicode escapes)
 
2201
                "Fran\u00e7ois" or (with HTML entities) "Fran&ccedil;ois".
 
2202
                Pronounciation is like "fraa-swa pee-nar".  */
 
2203
             _("Francois Pinard"));
 
2204
 
 
2205
   As a translator, you should use some care when translating names,
 
2206
because it is frustrating if people see their names mutilated or
 
2207
distorted.  If your language uses the Latin script, all you need to do
 
2208
is to reproduce the name as perfectly as you can within the usual
 
2209
character set of your language.  In this particular case, this means to
 
2210
provide a translation containing the c-cedilla character.  If your
 
2211
language uses a different script and the people speaking it don't
 
2212
usually read Latin words, it means transliteration; but you should
 
2213
still give, in parentheses, the original writing of the name - for the
 
2214
sake of the people that do read the Latin script.  Here is an example,
 
2215
using Greek as the target script:
 
2216
 
 
2217
     #. This is a proper name.  See the gettext
 
2218
     #. manual, section Names.  Note this is actually a non-ASCII
 
2219
     #. name: The first name is (with Unicode escapes)
 
2220
     #. "Fran\u00e7ois" or (with HTML entities) "Fran&ccedil;ois".
 
2221
     #. Pronounciation is like "fraa-swa pee-nar".
 
2222
     msgid "Francois Pinard"
 
2223
     msgstr "\phi\rho\alpha\sigma\omicron\alpha \pi\iota\nu\alpha\rho"
 
2224
            " (Francois Pinard)"
 
2225
 
 
2226
   Because translation of names is such a sensitive domain, it is a good
 
2227
idea to test your translation before submitting it.
 
2228
 
 
2229
   The translation project <http://sourceforge.net/projects/translation>
 
2230
has set up a POT file and translation domain consisting of program
 
2231
author names, with better facilities for the translator than those
 
2232
presented here.  Namely, there the original name is written directly in
 
2233
Unicode (rather than with Unicode escapes or HTML entities), and the
 
2234
pronounciation is denoted using the International Phonetic Alphabet (see
 
2235
<http://www.wikipedia.org/wiki/International_Phonetic_Alphabet>).
 
2236
 
 
2237
   However, we don't recommend this approach for all POT files in all
 
2238
packages, because this would force translators to use PO files in UTF-8
 
2239
encoding, which is - in the current state of software (as of 2003) - a
 
2240
major hassle for translators using GNU Emacs or XEmacs with po-mode.
 
2241
 
 
2242
 
 
2243
File: gettext.info,  Node: Libraries,  Prev: Names,  Up: Sources
 
2244
 
 
2245
Preparing Library Sources
 
2246
=========================
 
2247
 
 
2248
When you are preparing a library, not a program, for the use of
 
2249
`gettext', only a few details are different.  Here we assume that the
 
2250
library has a translation domain and a POT file of its own.  (If it
 
2251
uses the translation domain and POT file of the main program, then the
 
2252
previous sections apply without changes.)
 
2253
 
 
2254
  1. The library code doesn't call `setlocale (LC_ALL, "")'.  It's the
 
2255
     responsibility of the main program to set the locale.  The
 
2256
     library's documentation should mention this fact, so that
 
2257
     developers of programs using the library are aware of it.
 
2258
 
 
2259
  2. The library code doesn't call `textdomain (PACKAGE)', because it
 
2260
     would interfere with the text domain set by the main program.
 
2261
 
 
2262
  3. The initialization code for a program was
 
2263
 
 
2264
            setlocale (LC_ALL, "");
 
2265
            bindtextdomain (PACKAGE, LOCALEDIR);
 
2266
            textdomain (PACKAGE);
 
2267
 
 
2268
     For a library it is reduced to
 
2269
 
 
2270
            bindtextdomain (PACKAGE, LOCALEDIR);
 
2271
 
 
2272
     If your library's API doesn't already have an initialization
 
2273
     function, you need to create one, containing at least the
 
2274
     `bindtextdomain' invocation.  However, you usually don't need to
 
2275
     export and document this initialization function: It is sufficient
 
2276
     that all entry points of the library call the initialization
 
2277
     function if it hasn't been called before.  The typical idiom used
 
2278
     to achieve this is a static boolean variable that indicates
 
2279
     whether the initialization function has been called. Like this:
 
2280
 
 
2281
          static bool libfoo_initialized;
 
2282
          
 
2283
          static void
 
2284
          libfoo_initialize (void)
 
2285
          {
 
2286
            bindtextdomain (PACKAGE, LOCALEDIR);
 
2287
            libfoo_initialized = true;
 
2288
          }
 
2289
          
 
2290
          /* This function is part of the exported API.  */
 
2291
          struct foo *
 
2292
          create_foo (...)
 
2293
          {
 
2294
            /* Must ensure the initialization is performed.  */
 
2295
            if (!libfoo_initialized)
 
2296
              libfoo_initialize ();
 
2297
            ...
 
2298
          }
 
2299
          
 
2300
          /* This function is part of the exported API.  The argument must be
 
2301
             non-NULL and have been created through create_foo().  */
 
2302
          int
 
2303
          foo_refcount (struct foo *argument)
 
2304
          {
 
2305
            /* No need to invoke the initialization function here, because
 
2306
               create_foo() must already have been called before.  */
 
2307
            ...
 
2308
          }
 
2309
 
 
2310
  4. The usual declaration of the `_' macro in each source file was
 
2311
 
 
2312
          #include <libintl.h>
 
2313
          #define _(String) gettext (String)
 
2314
 
 
2315
     for a program.  For a library, which has its own translation
 
2316
     domain, it reads like this:
 
2317
 
 
2318
          #include <libintl.h>
 
2319
          #define _(String) dgettext (PACKAGE, String)
 
2320
 
 
2321
     In other words, `dgettext' is used instead of `gettext'.
 
2322
     Similary, the `dngettext' function should be used in place of the
 
2323
     `ngettext' function.
 
2324
 
 
2325
 
 
2326
File: gettext.info,  Node: Template,  Next: Creating,  Prev: Sources,  Up: Top
 
2327
 
 
2328
Making the PO Template File
 
2329
***************************
 
2330
 
 
2331
After preparing the sources, the programmer creates a PO template file.
 
2332
This section explains how to use `xgettext' for this purpose.
 
2333
 
 
2334
   `xgettext' creates a file named `DOMAINNAME.po'.  You should then
 
2335
rename it to `DOMAINNAME.pot'.  (Why doesn't `xgettext' create it under
 
2336
the name `DOMAINNAME.pot' right away?  The answer is: for historical
 
2337
reasons.  When `xgettext' was specified, the distinction between a PO
 
2338
file and PO file template was fuzzy, and the suffix `.pot' wasn't in
 
2339
use at that time.)
 
2340
 
 
2341
* Menu:
 
2342
 
 
2343
* xgettext Invocation::         Invoking the `xgettext' Program
 
2344
 
 
2345
 
 
2346
File: gettext.info,  Node: xgettext Invocation,  Prev: Template,  Up: Template
 
2347
 
 
2348
Invoking the `xgettext' Program
 
2349
===============================
 
2350
 
 
2351
     xgettext [OPTION] [INPUTFILE] ...
 
2352
 
 
2353
   The `xgettext' program extracts translatable strings from given
 
2354
input files.
 
2355
 
 
2356
Input file location
 
2357
-------------------
 
2358
 
 
2359
`INPUTFILE ...'
 
2360
     Input files.
 
2361
 
 
2362
`-f FILE'
 
2363
`--files-from=FILE'
 
2364
     Read the names of the input files from FILE instead of getting
 
2365
     them from the command line.
 
2366
 
 
2367
`-D DIRECTORY'
 
2368
`--directory=DIRECTORY'
 
2369
     Add DIRECTORY to the list of directories.  Source files are
 
2370
     searched relative to this list of directories.  The resulting `.po'
 
2371
     file will be written relative to the current directory, though.
 
2372
 
 
2373
 
 
2374
   If INPUTFILE is `-', standard input is read.
 
2375
 
 
2376
Output file location
 
2377
--------------------
 
2378
 
 
2379
`-d NAME'
 
2380
`--default-domain=NAME'
 
2381
     Use `NAME.po' for output (instead of `messages.po').
 
2382
 
 
2383
`-o FILE'
 
2384
`--output=FILE'
 
2385
     Write output to specified file (instead of `NAME.po' or
 
2386
     `messages.po').
 
2387
 
 
2388
`-p DIR'
 
2389
`--output-dir=DIR'
 
2390
     Output files will be placed in directory DIR.
 
2391
 
 
2392
 
 
2393
   If the output FILE is `-' or `/dev/stdout', the output is written to
 
2394
standard output.
 
2395
 
 
2396
Choice of input file language
 
2397
-----------------------------
 
2398
 
 
2399
`-L NAME'
 
2400
`--language=NAME'
 
2401
     Specifies the language of the input files.  The supported languages
 
2402
     are `C', `C++', `ObjectiveC', `PO', `Python', `Lisp', `EmacsLisp',
 
2403
     `librep', `Smalltalk', `Java', `JavaProperties', `C#', `awk',
 
2404
     `YCP', `Tcl', `Perl', `PHP', `GCC-source', `NXStringTable', `RST',
 
2405
     `Glade'.
 
2406
 
 
2407
`-C'
 
2408
`--c++'
 
2409
     This is a shorthand for `--language=C++'.
 
2410
 
 
2411
 
 
2412
   By default the language is guessed depending on the input file name
 
2413
extension.
 
2414
 
 
2415
Input file interpretation
 
2416
-------------------------
 
2417
 
 
2418
`--from-code=NAME'
 
2419
     Specifies the encoding of the input files.  This option is needed
 
2420
     only if some untranslated message strings or their corresponding
 
2421
     comments contain non-ASCII characters.  Note that Python, Tcl, and
 
2422
     Glade input files are always assumed to be in UTF-8, regardless of
 
2423
     this option.
 
2424
 
 
2425
 
 
2426
   By default the input files are assumed to be in ASCII.
 
2427
 
 
2428
Operation mode
 
2429
--------------
 
2430
 
 
2431
`-j'
 
2432
`--join-existing'
 
2433
     Join messages with existing file.
 
2434
 
 
2435
`-x FILE'
 
2436
`--exclude-file=FILE'
 
2437
     Entries from FILE are not extracted.  FILE should be a PO or POT
 
2438
     file.
 
2439
 
 
2440
`-c [TAG]'
 
2441
`--add-comments[=TAG]'
 
2442
     Place comment block with TAG (or those preceding keyword lines) in
 
2443
     output file.
 
2444
 
 
2445
 
 
2446
Language specific options
 
2447
-------------------------
 
2448
 
 
2449
`-a'
 
2450
`--extract-all'
 
2451
     Extract all strings.
 
2452
 
 
2453
     This option has an effect with most languages, namely C, C++,
 
2454
     ObjectiveC, Shell, Python, Lisp, EmacsLisp, librep, Java, C#, awk,
 
2455
     Tcl, Perl, PHP, GCC-source, Glade.
 
2456
 
 
2457
`-k KEYWORDSPEC'
 
2458
`--keyword[=KEYWORDSPEC]'
 
2459
     Additional keyword to be looked for (without KEYWORDSPEC means not
 
2460
     to use default keywords).
 
2461
 
 
2462
     If KEYWORDSPEC is a C identifer ID, `xgettext' looks for strings
 
2463
     in the first argument of each call to the function or macro ID.
 
2464
     If KEYWORDSPEC is of the form `ID:ARGNUM', `xgettext' looks for
 
2465
     strings in the ARGNUMth argument of the call.  If KEYWORDSPEC is
 
2466
     of the form `ID:ARGNUM1,ARGNUM2', `xgettext' looks for strings in
 
2467
     the ARGNUM1st argument and in the ARGNUM2nd argument of the call,
 
2468
     and treats them as singular/plural variants for a message with
 
2469
     plural handling.
 
2470
     The default keyword specifications, which are always looked for if
 
2471
     not explicitly disabled, are `gettext', `dgettext:2',
 
2472
     `dcgettext:2', `ngettext:1,2', `dngettext:2,3', `dcngettext:2,3',
 
2473
     and `gettext_noop'.
 
2474
     This option has an effect with most languages, namely C, C++,
 
2475
     ObjectiveC, Shell, Python, Lisp, EmacsLisp, librep, Java, C#, awk,
 
2476
     Tcl, Perl, PHP, GCC-source, Glade.
 
2477
 
 
2478
`--flag=WORD:ARG:FLAG'
 
2479
     Specifies additional flags for strings occurring as part of the
 
2480
     ARGth argument of the function WORD.  The possible flags are the
 
2481
     possible format string indicators, such as `c-format', and their
 
2482
     negations, such as `no-c-format', possibly prefixed with `pass-'.
 
2483
     The meaning of `--flag=FUNCTION:ARG:LANG-format' is that in
 
2484
     language LANG, the specified FUNCTION expects as ARGth argument a
 
2485
     format string.  (For those of you familiar with GCC function
 
2486
     attributes, `--flag=FUNCTION:ARG:c-format' is roughly equivalent
 
2487
     to the declaration `__attribute__ ((__format__ (__printf__, ARG,
 
2488
     ...)))' attached to FUNCTION in a C source file.)  For example, if
 
2489
     you use the `error' function from GNU libc, you can specify its
 
2490
     behaviour through `--flag=error:3:c-format'.  The effect of this
 
2491
     specification is that `xgettext' will mark as format strings all
 
2492
     `gettext' invocations that occur as ARGth argument of FUNCTION.
 
2493
     This is useful when such strings contain no format string
 
2494
     directives: together with the checks done by `msgfmt -c' it will
 
2495
     ensure that translators cannot accidentally use format string
 
2496
     directives that would lead to a crash at runtime.
 
2497
     The meaning of `--flag=FUNCTION:ARG:pass-LANG-format' is that in
 
2498
     language LANG, if the FUNCTION call occurs in a position that must
 
2499
     yield a format string, then its ARGth argument must yield a format
 
2500
     string of the same type as well.  (If you know GCC function
 
2501
     attributes, the `--flag=FUNCTION:ARG:pass-c-format' option is
 
2502
     roughly equivalent to the declaration `__attribute__
 
2503
     ((__format_arg__ (ARG)))' attached to FUNCTION in a C source file.)
 
2504
     For example, if you use the `_' shortcut for the `gettext'
 
2505
     function, you should use `--flag=_:1:pass-c-format'.  The effect
 
2506
     of this specification is that `xgettext' will propagate a format
 
2507
     string requirement for a `_("string")' call to its first argument,
 
2508
     the literal `"string"', and thus mark it as a format string.  This
 
2509
     is useful when such strings contain no format string directives:
 
2510
     together with the checks done by `msgfmt -c' it will ensure that
 
2511
     translators cannot accidentally use format string directives that
 
2512
     would lead to a crash at runtime.
 
2513
     This option has an effect with most languages, namely C, C++,
 
2514
     ObjectiveC, Shell, Python, Lisp, EmacsLisp, librep, Java, C#, awk,
 
2515
     YCP, Tcl, Perl, PHP, GCC-source.
 
2516
 
 
2517
`-T'
 
2518
`--trigraphs'
 
2519
     Understand ANSI C trigraphs for input.
 
2520
     This option has an effect only with the languages C, C++,
 
2521
     ObjectiveC.
 
2522
 
 
2523
`--qt'
 
2524
     Recognize Qt format strings.
 
2525
     This option has an effect only with the language C++.
 
2526
 
 
2527
`--debug'
 
2528
     Use the flags `c-format' and `possible-c-format' to show who was
 
2529
     responsible for marking a message as a format string.  The latter
 
2530
     form is used if the `xgettext' program decided, the format form is
 
2531
     used if the programmer prescribed it.
 
2532
 
 
2533
     By default only the `c-format' form is used.  The translator should
 
2534
     not have to care about these details.
 
2535
 
 
2536
 
 
2537
   This implementation of `xgettext' is able to process a few awkward
 
2538
cases, like strings in preprocessor macros, ANSI concatenation of
 
2539
adjacent strings, and escaped end of lines for continued strings.
 
2540
 
 
2541
Output details
 
2542
--------------
 
2543
 
 
2544
`--force-po'
 
2545
     Always write an output file even if no message is defined.
 
2546
 
 
2547
`-i'
 
2548
`--indent'
 
2549
     Write the .po file using indented style.
 
2550
 
 
2551
`--no-location'
 
2552
     Do not write `#: FILENAME:LINE' lines.
 
2553
 
 
2554
`-n'
 
2555
`--add-location'
 
2556
     Generate `#: FILENAME:LINE' lines (default).
 
2557
 
 
2558
`--strict'
 
2559
     Write out a strict Uniforum conforming PO file.  Note that this
 
2560
     Uniforum format should be avoided because it doesn't support the
 
2561
     GNU extensions.
 
2562
 
 
2563
`--properties-output'
 
2564
     Write out a Java ResourceBundle in Java `.properties' syntax.  Note
 
2565
     that this file format doesn't support plural forms and silently
 
2566
     drops obsolete messages.
 
2567
 
 
2568
`--stringtable-output'
 
2569
     Write out a NeXTstep/GNUstep localized resource file in `.strings'
 
2570
     syntax.  Note that this file format doesn't support plural forms.
 
2571
 
 
2572
`-w NUMBER'
 
2573
`--width=NUMBER'
 
2574
     Set the output page width.  Long strings in the output files will
 
2575
     be split across multiple lines in order to ensure that each line's
 
2576
     width (= number of screen columns) is less or equal to the given
 
2577
     NUMBER.
 
2578
 
 
2579
`--no-wrap'
 
2580
     Do not break long message lines.  Message lines whose width
 
2581
     exceeds the output page width will not be split into several
 
2582
     lines.  Only file reference lines which are wider than the output
 
2583
     page width will be split.
 
2584
 
 
2585
`-s'
 
2586
`--sort-output'
 
2587
     Generate sorted output.  Note that using this option makes it much
 
2588
     harder for the translator to understand each message's context.
 
2589
 
 
2590
`-F'
 
2591
`--sort-by-file'
 
2592
     Sort output by file location.
 
2593
 
 
2594
`--omit-header'
 
2595
     Don't write header with `msgid ""' entry.
 
2596
 
 
2597
     This is useful for testing purposes because it eliminates a source
 
2598
     of variance for generated `.gmo' files.  With `--omit-header', two
 
2599
     invocations of `xgettext' on the same files with the same options
 
2600
     at different times are guaranteed to produce the same results.
 
2601
 
 
2602
`--copyright-holder=STRING'
 
2603
     Set the copyright holder in the output.  STRING should be the
 
2604
     copyright holder of the surrounding package.  (Note that the msgstr
 
2605
     strings, extracted from the package's sources, belong to the
 
2606
     copyright holder of the package.)  Translators are expected to
 
2607
     transfer or disclaim the copyright for their translations, so that
 
2608
     package maintainers can distribute them without legal risk.  If
 
2609
     STRING is empty, the output files are marked as being in the
 
2610
     public domain; in this case, the translators are expected to
 
2611
     disclaim their copyright, again so that package maintainers can
 
2612
     distribute them without legal risk.
 
2613
 
 
2614
     The default value for STRING is the Free Software Foundation, Inc.,
 
2615
     simply because `xgettext' was first used in the GNU project.
 
2616
 
 
2617
`--foreign-user'
 
2618
     Omit FSF copyright in output.  This option is equivalent to
 
2619
     `--copyright-holder='''.  It can be useful for packages outside
 
2620
     the GNU project that want their translations to be in the public
 
2621
     domain.
 
2622
 
 
2623
`--msgid-bugs-address=EMAIL@ADDRESS'
 
2624
     Set the reporting address for msgid bugs.  This is the email
 
2625
     address or URL to which the translators shall report bugs in the
 
2626
     untranslated strings:
 
2627
 
 
2628
        - Strings which are not entire sentences, see the maintainer
 
2629
          guidelines in *Note Preparing Strings::.
 
2630
 
 
2631
        - Strings which use unclear terms or require additional context
 
2632
          to be understood.
 
2633
 
 
2634
        - Strings which make invalid assumptions about notation of
 
2635
          date, time or money.
 
2636
 
 
2637
        - Pluralisation problems.
 
2638
 
 
2639
        - Incorrect English spelling.
 
2640
 
 
2641
        - Incorrect formatting.
 
2642
 
 
2643
     It can be your email address, or a mailing list address where
 
2644
     translators can write to without being subscribed, or the URL of a
 
2645
     web page through which the translators can contact you.
 
2646
 
 
2647
     The default value is empty, which means that translators will be
 
2648
     clueless!  Don't forget to specify this option.
 
2649
 
 
2650
`-m [STRING]'
 
2651
`--msgstr-prefix[=STRING]'
 
2652
     Use STRING (or "" if not specified) as prefix for msgstr entries.
 
2653
 
 
2654
`-M [STRING]'
 
2655
`--msgstr-suffix[=STRING]'
 
2656
     Use STRING (or "" if not specified) as suffix for msgstr entries.
 
2657
 
 
2658
 
 
2659
Informative output
 
2660
------------------
 
2661
 
 
2662
`-h'
 
2663
`--help'
 
2664
     Display this help and exit.
 
2665
 
 
2666
`-V'
 
2667
`--version'
 
2668
     Output version information and exit.
 
2669
 
 
2670
 
 
2671
 
 
2672
File: gettext.info,  Node: Creating,  Next: Updating,  Prev: Template,  Up: Top
 
2673
 
 
2674
Creating a New PO File
 
2675
**********************
 
2676
 
 
2677
When starting a new translation, the translator creates a file called
 
2678
`LANG.po', as a copy of the `PACKAGE.pot' template file with
 
2679
modifications in the initial comments (at the beginning of the file)
 
2680
and in the header entry (the first entry, near the beginning of the
 
2681
file).
 
2682
 
 
2683
   The easiest way to do so is by use of the `msginit' program.  For
 
2684
example:
 
2685
 
 
2686
     $ cd PACKAGE-VERSION
 
2687
     $ cd po
 
2688
     $ msginit
 
2689
 
 
2690
   The alternative way is to do the copy and modifications by hand.  To
 
2691
do so, the translator copies `PACKAGE.pot' to `LANG.po'.  Then she
 
2692
modifies the initial comments and the header entry of this file.
 
2693
 
 
2694
* Menu:
 
2695
 
 
2696
* msginit Invocation::          Invoking the `msginit' Program
 
2697
* Header Entry::                Filling in the Header Entry
 
2698
 
 
2699
 
 
2700
File: gettext.info,  Node: msginit Invocation,  Next: Header Entry,  Prev: Creating,  Up: Creating
 
2701
 
 
2702
Invoking the `msginit' Program
 
2703
==============================
 
2704
 
 
2705
     msginit [OPTION]
 
2706
 
 
2707
   The `msginit' program creates a new PO file, initializing the meta
 
2708
information with values from the user's environment.
 
2709
 
 
2710
Input file location
 
2711
-------------------
 
2712
 
 
2713
`-i INPUTFILE'
 
2714
`--input=INPUTFILE'
 
2715
     Input POT file.
 
2716
 
 
2717
 
 
2718
   If no INPUTFILE is given, the current directory is searched for the
 
2719
POT file.  If it is `-', standard input is read.
 
2720
 
 
2721
Output file location
 
2722
--------------------
 
2723
 
 
2724
`-o FILE'
 
2725
`--output-file=FILE'
 
2726
     Write output to specified PO file.
 
2727
 
 
2728
 
 
2729
   If no output file is given, it depends on the `--locale' option or
 
2730
the user's locale setting.  If it is `-', the results are written to
 
2731
standard output.
 
2732
 
 
2733
Input file syntax
 
2734
-----------------
 
2735
 
 
2736
`-P'
 
2737
`--properties-input'
 
2738
     Assume the input file is a Java ResourceBundle in Java
 
2739
     `.properties' syntax, not in PO file syntax.
 
2740
 
 
2741
`--stringtable-input'
 
2742
     Assume the input file is a NeXTstep/GNUstep localized resource
 
2743
     file in `.strings' syntax, not in PO file syntax.
 
2744
 
 
2745
 
 
2746
Output details
 
2747
--------------
 
2748
 
 
2749
`-l LL_CC'
 
2750
`--locale=LL_CC'
 
2751
     Set target locale.  LL should be a language code, and CC should be
 
2752
     a country code.  The command `locale -a' can be used to output a
 
2753
     list of all installed locales.  The default is the user's locale
 
2754
     setting.
 
2755
 
 
2756
`--no-translator'
 
2757
     Declares that the PO file will not have a human translator and is
 
2758
     instead automatically generated.
 
2759
 
 
2760
`-p'
 
2761
`--properties-output'
 
2762
     Write out a Java ResourceBundle in Java `.properties' syntax.  Note
 
2763
     that this file format doesn't support plural forms and silently
 
2764
     drops obsolete messages.
 
2765
 
 
2766
`--stringtable-output'
 
2767
     Write out a NeXTstep/GNUstep localized resource file in `.strings'
 
2768
     syntax.  Note that this file format doesn't support plural forms.
 
2769
 
 
2770
`-w NUMBER'
 
2771
`--width=NUMBER'
 
2772
     Set the output page width.  Long strings in the output files will
 
2773
     be split across multiple lines in order to ensure that each line's
 
2774
     width (= number of screen columns) is less or equal to the given
 
2775
     NUMBER.
 
2776
 
 
2777
`--no-wrap'
 
2778
     Do not break long message lines.  Message lines whose width
 
2779
     exceeds the output page width will not be split into several
 
2780
     lines.  Only file reference lines which are wider than the output
 
2781
     page width will be split.
 
2782
 
 
2783
 
 
2784
Informative output
 
2785
------------------
 
2786
 
 
2787
`-h'
 
2788
`--help'
 
2789
     Display this help and exit.
 
2790
 
 
2791
`-V'
 
2792
`--version'
 
2793
     Output version information and exit.
 
2794
 
 
2795
 
 
2796
 
 
2797
File: gettext.info,  Node: Header Entry,  Prev: msginit Invocation,  Up: Creating
 
2798
 
 
2799
Filling in the Header Entry
 
2800
===========================
 
2801
 
 
2802
The initial comments "SOME DESCRIPTIVE TITLE", "YEAR" and "FIRST AUTHOR
 
2803
<EMAIL@ADDRESS>, YEAR" ought to be replaced by sensible information.
 
2804
This can be done in any text editor; if Emacs is used and it switched
 
2805
to PO mode automatically (because it has recognized the file's suffix),
 
2806
you can disable it by typing `M-x fundamental-mode'.
 
2807
 
 
2808
   Modifying the header entry can already be done using PO mode: in
 
2809
Emacs, type `M-x po-mode RET' and then `RET' again to start editing the
 
2810
entry.  You should fill in the following fields.
 
2811
 
 
2812
Project-Id-Version
 
2813
     This is the name and version of the package.
 
2814
 
 
2815
Report-Msgid-Bugs-To
 
2816
     This has already been filled in by `xgettext'.  It contains an
 
2817
     email address or URL where you can report bugs in the untranslated
 
2818
     strings:
 
2819
 
 
2820
        - Strings which are not entire sentences, see the maintainer
 
2821
          guidelines in *Note Preparing Strings::.
 
2822
 
 
2823
        - Strings which use unclear terms or require additional context
 
2824
          to be understood.
 
2825
 
 
2826
        - Strings which make invalid assumptions about notation of
 
2827
          date, time or money.
 
2828
 
 
2829
        - Pluralisation problems.
 
2830
 
 
2831
        - Incorrect English spelling.
 
2832
 
 
2833
        - Incorrect formatting.
 
2834
 
 
2835
POT-Creation-Date
 
2836
     This has already been filled in by `xgettext'.
 
2837
 
 
2838
PO-Revision-Date
 
2839
     You don't need to fill this in.  It will be filled by the Emacs PO
 
2840
     mode when you save the file.
 
2841
 
 
2842
Last-Translator
 
2843
     Fill in your name and email address (without double quotes).
 
2844
 
 
2845
Language-Team
 
2846
     Fill in the English name of the language, and the email address or
 
2847
     homepage URL of the language team you are part of.
 
2848
 
 
2849
     Before starting a translation, it is a good idea to get in touch
 
2850
     with your translation team, not only to make sure you don't do
 
2851
     duplicated work, but also to coordinate difficult linguistic
 
2852
     issues.
 
2853
 
 
2854
     In the Free Translation Project, each translation team has its own
 
2855
     mailing list.  The up-to-date list of teams can be found at the
 
2856
     Free Translation Project's homepage,
 
2857
     `http://www.iro.umontreal.ca/contrib/po/HTML/', in the "National
 
2858
     teams" area.
 
2859
 
 
2860
Content-Type
 
2861
     Replace `CHARSET' with the character encoding used for your
 
2862
     language, in your locale, or UTF-8.  This field is needed for
 
2863
     correct operation of the `msgmerge' and `msgfmt' programs, as well
 
2864
     as for users whose locale's character encoding differs from yours
 
2865
     (see *Note Charset conversion::).
 
2866
 
 
2867
     You get the character encoding of your locale by running the shell
 
2868
     command `locale charmap'.  If the result is `C' or
 
2869
     `ANSI_X3.4-1968', which is equivalent to `ASCII' (= `US-ASCII'),
 
2870
     it means that your locale is not correctly configured.  In this
 
2871
     case, ask your translation team which charset to use.  `ASCII' is
 
2872
     not usable for any language except Latin.
 
2873
 
 
2874
     Because the PO files must be portable to operating systems with
 
2875
     less advanced internationalization facilities, the character
 
2876
     encodings that can be used are limited to those supported by both
 
2877
     GNU `libc' and GNU `libiconv'.  These are: `ASCII', `ISO-8859-1',
 
2878
     `ISO-8859-2', `ISO-8859-3', `ISO-8859-4', `ISO-8859-5',
 
2879
     `ISO-8859-6', `ISO-8859-7', `ISO-8859-8', `ISO-8859-9',
 
2880
     `ISO-8859-13', `ISO-8859-14', `ISO-8859-15', `KOI8-R', `KOI8-U',
 
2881
     `KOI8-T', `CP850', `CP866', `CP874', `CP932', `CP949', `CP950',
 
2882
     `CP1250', `CP1251', `CP1252', `CP1253', `CP1254', `CP1255',
 
2883
     `CP1256', `CP1257', `GB2312', `EUC-JP', `EUC-KR', `EUC-TW',
 
2884
     `BIG5', `BIG5-HKSCS', `GBK', `GB18030', `SHIFT_JIS', `JOHAB',
 
2885
     `TIS-620', `VISCII', `GEORGIAN-PS', `UTF-8'.
 
2886
 
 
2887
     In the GNU system, the following encodings are frequently used for
 
2888
     the corresponding languages.
 
2889
 
 
2890
        * `ISO-8859-1' for Afrikaans, Albanian, Basque, Breton,
 
2891
          Catalan, Cornish, Danish, Dutch, English, Estonian, Faroese,
 
2892
          Finnish, French, Galician, German, Greenlandic, Icelandic,
 
2893
          Indonesian, Irish, Italian, Malay, Manx, Norwegian, Occitan,
 
2894
          Portuguese, Spanish, Swedish, Tagalog, Uzbek, Walloon,
 
2895
 
 
2896
        * `ISO-8859-2' for Bosnian, Croatian, Czech, Hungarian, Polish,
 
2897
          Romanian, Serbian, Slovak, Slovenian,
 
2898
 
 
2899
        * `ISO-8859-3' for Maltese,
 
2900
 
 
2901
        * `ISO-8859-5' for Macedonian, Serbian,
 
2902
 
 
2903
        * `ISO-8859-6' for Arabic,
 
2904
 
 
2905
        * `ISO-8859-7' for Greek,
 
2906
 
 
2907
        * `ISO-8859-8' for Hebrew,
 
2908
 
 
2909
        * `ISO-8859-9' for Turkish,
 
2910
 
 
2911
        * `ISO-8859-13' for Latvian, Lithuanian, Maori,
 
2912
 
 
2913
        * `ISO-8859-14' for Welsh,
 
2914
 
 
2915
        * `ISO-8859-15' for Basque, Catalan, Dutch, English, Finnish,
 
2916
          French, Galician, German, Irish, Italian, Portuguese,
 
2917
          Spanish, Swedish, Walloon,
 
2918
 
 
2919
        * `KOI8-R' for Russian,
 
2920
 
 
2921
        * `KOI8-U' for Ukrainian,
 
2922
 
 
2923
        * `KOI8-T' for Tajik,
 
2924
 
 
2925
        * `CP1251' for Bulgarian, Byelorussian,
 
2926
 
 
2927
        * `GB2312', `GBK', `GB18030' for simplified writing of Chinese,
 
2928
 
 
2929
        * `BIG5', `BIG5-HKSCS' for traditional writing of Chinese,
 
2930
 
 
2931
        * `EUC-JP' for Japanese,
 
2932
 
 
2933
        * `EUC-KR' for Korean,
 
2934
 
 
2935
        * `TIS-620' for Thai,
 
2936
 
 
2937
        * `GEORGIAN-PS' for Georgian,
 
2938
 
 
2939
        * `UTF-8' for any language, including those listed above.
 
2940
 
 
2941
     When single quote characters or double quote characters are used in
 
2942
     translations for your language, and your locale's encoding is one
 
2943
     of the ISO-8859-* charsets, it is best if you create your PO files
 
2944
     in UTF-8 encoding, instead of your locale's encoding.  This is
 
2945
     because in UTF-8 the real quote characters can be represented
 
2946
     (single quote characters: U+2018, U+2019, double quote characters:
 
2947
     U+201C, U+201D), whereas none of ISO-8859-* charsets has them all.
 
2948
     Users in UTF-8 locales will see the real quote characters,
 
2949
     whereas users in ISO-8859-* locales will see the vertical
 
2950
     apostrophe and the vertical double quote instead (because that's
 
2951
     what the character set conversion will transliterate them to).
 
2952
 
 
2953
     To enter such quote characters under X11, you can change your
 
2954
     keyboard mapping using the `xmodmap' program.  The X11 names of
 
2955
     the quote characters are "leftsinglequotemark",
 
2956
     "rightsinglequotemark", "leftdoublequotemark",
 
2957
     "rightdoublequotemark", "singlelowquotemark", "doublelowquotemark".
 
2958
 
 
2959
     Note that only recent versions of GNU Emacs support the UTF-8
 
2960
     encoding: Emacs 20 with Mule-UCS, and Emacs 21.  As of January
 
2961
     2001, XEmacs doesn't support the UTF-8 encoding.
 
2962
 
 
2963
     The character encoding name can be written in either upper or
 
2964
     lower case.  Usually upper case is preferred.
 
2965
 
 
2966
Content-Transfer-Encoding
 
2967
     Set this to `8bit'.
 
2968
 
 
2969
Plural-Forms
 
2970
     This field is optional.  It is only needed if the PO file has
 
2971
     plural forms.  You can find them by searching for the
 
2972
     `msgid_plural' keyword.  The format of the plural forms field is
 
2973
     described in *Note Plural forms::.
 
2974
 
 
2975
 
 
2976
File: gettext.info,  Node: Updating,  Next: Manipulating,  Prev: Creating,  Up: Top
 
2977
 
 
2978
Updating Existing PO Files
 
2979
**************************
 
2980
 
 
2981
* Menu:
 
2982
 
 
2983
* msgmerge Invocation::         Invoking the `msgmerge' Program
 
2984
* Translated Entries::          Translated Entries
 
2985
* Fuzzy Entries::               Fuzzy Entries
 
2986
* Untranslated Entries::        Untranslated Entries
 
2987
* Obsolete Entries::            Obsolete Entries
 
2988
* Modifying Translations::      Modifying Translations
 
2989
* Modifying Comments::          Modifying Comments
 
2990
* Subedit::                     Mode for Editing Translations
 
2991
* C Sources Context::           C Sources Context
 
2992
* Auxiliary::                   Consulting Auxiliary PO Files
 
2993
* Compendium::                  Using Translation Compendia
 
2994
 
 
2995
 
 
2996
File: gettext.info,  Node: msgmerge Invocation,  Next: Translated Entries,  Prev: Updating,  Up: Updating
 
2997
 
 
2998
Invoking the `msgmerge' Program
 
2999
===============================
 
3000
 
 
3001
     msgmerge [OPTION] DEF.po REF.pot
 
3002
 
 
3003
   The `msgmerge' program merges two Uniforum style .po files together.
 
3004
The DEF.po file is an existing PO file with translations which will be
 
3005
taken over to the newly created file as long as they still match;
 
3006
comments will be preserved, but extracted comments and file positions
 
3007
will be discarded.  The REF.pot file is the last created PO file with
 
3008
up-to-date source references but old translations, or a PO Template file
 
3009
(generally created by `xgettext'); any translations or comments in the
 
3010
file will be discarded, however dot comments and file positions will be
 
3011
preserved.  Where an exact match cannot be found, fuzzy matching is
 
3012
used to produce better results.
 
3013
 
 
3014
Input file location
 
3015
-------------------
 
3016
 
 
3017
`DEF.po'
 
3018
     Translations referring to old sources.
 
3019
 
 
3020
`REF.pot'
 
3021
     References to the new sources.
 
3022
 
 
3023
`-D DIRECTORY'
 
3024
`--directory=DIRECTORY'
 
3025
     Add DIRECTORY to the list of directories.  Source files are
 
3026
     searched relative to this list of directories.  The resulting `.po'
 
3027
     file will be written relative to the current directory, though.
 
3028
 
 
3029
`-C FILE'
 
3030
`--compendium=FILE'
 
3031
     Specify an additional library of message translations.  *Note
 
3032
     Compendium::.  This option may be specified more than once.
 
3033
 
 
3034
 
 
3035
Operation mode
 
3036
--------------
 
3037
 
 
3038
`-U'
 
3039
`--update'
 
3040
     Update DEF.po.  Do nothing if DEF.po is already up to date.
 
3041
 
 
3042
 
 
3043
Output file location
 
3044
--------------------
 
3045
 
 
3046
`-o FILE'
 
3047
`--output-file=FILE'
 
3048
     Write output to specified file.
 
3049
 
 
3050
 
 
3051
   The results are written to standard output if no output file is
 
3052
specified or if it is `-'.
 
3053
 
 
3054
Output file location in update mode
 
3055
-----------------------------------
 
3056
 
 
3057
The result is written back to DEF.po.
 
3058
 
 
3059
`--backup=CONTROL'
 
3060
     Make a backup of DEF.po
 
3061
 
 
3062
`--suffix=SUFFIX'
 
3063
     Override the usual backup suffix.
 
3064
 
 
3065
 
 
3066
   The version control method may be selected via the `--backup' option
 
3067
or through the `VERSION_CONTROL' environment variable.  Here are the
 
3068
values:
 
3069
 
 
3070
`none'
 
3071
`off'
 
3072
     Never make backups (even if `--backup' is given).
 
3073
 
 
3074
`numbered'
 
3075
`t'
 
3076
     Make numbered backups.
 
3077
 
 
3078
`existing'
 
3079
`nil'
 
3080
     Make numbered backups if numbered backups for this file already
 
3081
     exist, otherwise make simple backups.
 
3082
 
 
3083
`simple'
 
3084
`never'
 
3085
     Always make simple backups.
 
3086
 
 
3087
 
 
3088
   The backup suffix is `~', unless set with `--suffix' or the
 
3089
`SIMPLE_BACKUP_SUFFIX' environment variable.
 
3090
 
 
3091
Operation modifiers
 
3092
-------------------
 
3093
 
 
3094
`-m'
 
3095
`--multi-domain'
 
3096
     Apply REF.pot to each of the domains in DEF.po.
 
3097
 
 
3098
`-N'
 
3099
`--no-fuzzy-matching'
 
3100
     Do not use fuzzy matching when an exact match is not found.  This
 
3101
     may speed up the operation considerably.
 
3102
 
 
3103
Input file syntax
 
3104
-----------------
 
3105
 
 
3106
`-P'
 
3107
`--properties-input'
 
3108
     Assume the input files are Java ResourceBundles in Java
 
3109
     `.properties' syntax, not in PO file syntax.
 
3110
 
 
3111
`--stringtable-input'
 
3112
     Assume the input files are NeXTstep/GNUstep localized resource
 
3113
     files in `.strings' syntax, not in PO file syntax.
 
3114
 
 
3115
 
 
3116
Output details
 
3117
--------------
 
3118
 
 
3119
`--force-po'
 
3120
     Always write an output file even if it contains no message.
 
3121
 
 
3122
`-i'
 
3123
`--indent'
 
3124
     Write the .po file using indented style.
 
3125
 
 
3126
`--no-location'
 
3127
     Do not write `#: FILENAME:LINE' lines.
 
3128
 
 
3129
`--add-location'
 
3130
     Generate `#: FILENAME:LINE' lines (default).
 
3131
 
 
3132
`--strict'
 
3133
     Write out a strict Uniforum conforming PO file.  Note that this
 
3134
     Uniforum format should be avoided because it doesn't support the
 
3135
     GNU extensions.
 
3136
 
 
3137
`-p'
 
3138
`--properties-output'
 
3139
     Write out a Java ResourceBundle in Java `.properties' syntax.  Note
 
3140
     that this file format doesn't support plural forms and silently
 
3141
     drops obsolete messages.
 
3142
 
 
3143
`--stringtable-output'
 
3144
     Write out a NeXTstep/GNUstep localized resource file in `.strings'
 
3145
     syntax.  Note that this file format doesn't support plural forms.
 
3146
 
 
3147
`-w NUMBER'
 
3148
`--width=NUMBER'
 
3149
     Set the output page width.  Long strings in the output files will
 
3150
     be split across multiple lines in order to ensure that each line's
 
3151
     width (= number of screen columns) is less or equal to the given
 
3152
     NUMBER.
 
3153
 
 
3154
`--no-wrap'
 
3155
     Do not break long message lines.  Message lines whose width
 
3156
     exceeds the output page width will not be split into several
 
3157
     lines.  Only file reference lines which are wider than the output
 
3158
     page width will be split.
 
3159
 
 
3160
`-s'
 
3161
`--sort-output'
 
3162
     Generate sorted output.  Note that using this option makes it much
 
3163
     harder for the translator to understand each message's context.
 
3164
 
 
3165
`-F'
 
3166
`--sort-by-file'
 
3167
     Sort output by file location.
 
3168
 
 
3169
 
 
3170
Informative output
 
3171
------------------
 
3172
 
 
3173
`-h'
 
3174
`--help'
 
3175
     Display this help and exit.
 
3176
 
 
3177
`-V'
 
3178
`--version'
 
3179
     Output version information and exit.
 
3180
 
 
3181
`-v'
 
3182
`--verbose'
 
3183
     Increase verbosity level.
 
3184
 
 
3185
`-q'
 
3186
`--quiet'
 
3187
`--silent'
 
3188
     Suppress progress indicators.
 
3189
 
 
3190
 
 
3191
 
 
3192
File: gettext.info,  Node: Translated Entries,  Next: Fuzzy Entries,  Prev: msgmerge Invocation,  Up: Updating
 
3193
 
 
3194
Translated Entries
 
3195
==================
 
3196
 
 
3197
Each PO file entry for which the `msgstr' field has been filled with a
 
3198
translation, and which is not marked as fuzzy (*note Fuzzy Entries::),
 
3199
is said to be a "translated" entry.  Only translated entries will later
 
3200
be compiled by GNU `msgfmt' and become usable in programs.  Other entry
 
3201
types will be excluded; translation will not occur for them.
 
3202
 
 
3203
   Some commands are more specifically related to translated entry
 
3204
processing.
 
3205
 
 
3206
`t'
 
3207
     Find the next translated entry (`po-next-translated-entry').
 
3208
 
 
3209
`T'
 
3210
     Find the previous translated entry
 
3211
     (`po-previous-translated-entry').
 
3212
 
 
3213
 
 
3214
   The commands `t' (`po-next-translated-entry') and `T'
 
3215
(`po-previous-translated-entry') move forwards or backwards, chasing
 
3216
for an translated entry.  If none is found, the search is extended and
 
3217
wraps around in the PO file buffer.
 
3218
 
 
3219
   Translated entries usually result from the translator having edited
 
3220
in a translation for them, *Note Modifying Translations::.  However, if
 
3221
the variable `po-auto-fuzzy-on-edit' is not `nil', the entry having
 
3222
received a new translation first becomes a fuzzy entry, which ought to
 
3223
be later unfuzzied before becoming an official, genuine translated
 
3224
entry.  *Note Fuzzy Entries::.
 
3225
 
 
3226
 
 
3227
File: gettext.info,  Node: Fuzzy Entries,  Next: Untranslated Entries,  Prev: Translated Entries,  Up: Updating
 
3228
 
 
3229
Fuzzy Entries
 
3230
=============
 
3231
 
 
3232
Each PO file entry may have a set of "attributes", which are qualities
 
3233
given a name and explicitly associated with the translation, using a
 
3234
special system comment.  One of these attributes has the name `fuzzy',
 
3235
and entries having this attribute are said to have a fuzzy translation.
 
3236
They are called fuzzy entries, for short.
 
3237
 
 
3238
   Fuzzy entries, even if they account for translated entries for most
 
3239
other purposes, usually call for revision by the translator.  Those may
 
3240
be produced by applying the program `msgmerge' to update an older
 
3241
translated PO files according to a new PO template file, when this tool
 
3242
hypothesises that some new `msgid' has been modified only slightly out
 
3243
of an older one, and chooses to pair what it thinks to be the old
 
3244
translation for the new modified entry.  The slight alteration in the
 
3245
original string (the `msgid' string) should often be reflected in the
 
3246
translated string, and this requires the intervention of the
 
3247
translator.  For this reason, `msgmerge' might mark some entries as
 
3248
being fuzzy.
 
3249
 
 
3250
   Also, the translator may decide herself to mark an entry as fuzzy
 
3251
for her own convenience, when she wants to remember that the entry has
 
3252
to be later revisited.  So, some commands are more specifically related
 
3253
to fuzzy entry processing.
 
3254
 
 
3255
`z'
 
3256
     Find the next fuzzy entry (`po-next-fuzzy-entry').
 
3257
 
 
3258
`Z'
 
3259
     Find the previous fuzzy entry (`po-previous-fuzzy-entry').
 
3260
 
 
3261
`<TAB>'
 
3262
     Remove the fuzzy attribute of the current entry (`po-unfuzzy').
 
3263
 
 
3264
 
 
3265
   The commands `z' (`po-next-fuzzy-entry') and `Z'
 
3266
(`po-previous-fuzzy-entry') move forwards or backwards, chasing for a
 
3267
fuzzy entry.  If none is found, the search is extended and wraps around
 
3268
in the PO file buffer.
 
3269
 
 
3270
   The command `<TAB>' (`po-unfuzzy') removes the fuzzy attribute
 
3271
associated with an entry, usually leaving it translated.  Further, if
 
3272
the variable `po-auto-select-on-unfuzzy' has not the `nil' value, the
 
3273
`<TAB>' command will automatically chase for another interesting entry
 
3274
to work on.  The initial value of `po-auto-select-on-unfuzzy' is `nil'.
 
3275
 
 
3276
   The initial value of `po-auto-fuzzy-on-edit' is `nil'.  However, if
 
3277
the variable `po-auto-fuzzy-on-edit' is set to `t', any entry edited
 
3278
through the `<RET>' command is marked fuzzy, as a way to ensure some
 
3279
kind of double check, later.  In this case, the usual paradigm is that
 
3280
an entry becomes fuzzy (if not already) whenever the translator
 
3281
modifies it.  If she is satisfied with the translation, she then uses
 
3282
`<TAB>' to pick another entry to work on, clearing the fuzzy attribute
 
3283
on the same blow.  If she is not satisfied yet, she merely uses `<SPC>'
 
3284
to chase another entry, leaving the entry fuzzy.
 
3285
 
 
3286
   The translator may also use the `<DEL>' command
 
3287
(`po-fade-out-entry') over any translated entry to mark it as being
 
3288
fuzzy, when she wants to easily leave a trace she wants to later return
 
3289
working at this entry.
 
3290
 
 
3291
   Also, when time comes to quit working on a PO file buffer with the
 
3292
`q' command, the translator is asked for confirmation, if fuzzy string
 
3293
still exists.
 
3294
 
 
3295
 
 
3296
File: gettext.info,  Node: Untranslated Entries,  Next: Obsolete Entries,  Prev: Fuzzy Entries,  Up: Updating
 
3297
 
 
3298
Untranslated Entries
 
3299
====================
 
3300
 
 
3301
When `xgettext' originally creates a PO file, unless told otherwise, it
 
3302
initializes the `msgid' field with the untranslated string, and leaves
 
3303
the `msgstr' string to be empty.  Such entries, having an empty
 
3304
translation, are said to be "untranslated" entries.  Later, when the
 
3305
programmer slightly modifies some string right in the program, this
 
3306
change is later reflected in the PO file by the appearance of a new
 
3307
untranslated entry for the modified string.
 
3308
 
 
3309
   The usual commands moving from entry to entry consider untranslated
 
3310
entries on the same level as active entries.  Untranslated entries are
 
3311
easily recognizable by the fact they end with `msgstr ""'.
 
3312
 
 
3313
   The work of the translator might be (quite naively) seen as the
 
3314
process of seeking for an untranslated entry, editing a translation for
 
3315
it, and repeating these actions until no untranslated entries remain.
 
3316
Some commands are more specifically related to untranslated entry
 
3317
processing.
 
3318
 
 
3319
`u'
 
3320
     Find the next untranslated entry (`po-next-untranslated-entry').
 
3321
 
 
3322
`U'
 
3323
     Find the previous untranslated entry
 
3324
     (`po-previous-untransted-entry').
 
3325
 
 
3326
`k'
 
3327
     Turn the current entry into an untranslated one (`po-kill-msgstr').
 
3328
 
 
3329
 
 
3330
   The commands `u' (`po-next-untranslated-entry') and `U'
 
3331
(`po-previous-untransted-entry') move forwards or backwards, chasing
 
3332
for an untranslated entry.  If none is found, the search is extended
 
3333
and wraps around in the PO file buffer.
 
3334
 
 
3335
   An entry can be turned back into an untranslated entry by merely
 
3336
emptying its translation, using the command `k' (`po-kill-msgstr').
 
3337
*Note Modifying Translations::.
 
3338
 
 
3339
   Also, when time comes to quit working on a PO file buffer with the
 
3340
`q' command, the translator is asked for confirmation, if some
 
3341
untranslated string still exists.
 
3342
 
 
3343
 
 
3344
File: gettext.info,  Node: Obsolete Entries,  Next: Modifying Translations,  Prev: Untranslated Entries,  Up: Updating
 
3345
 
 
3346
Obsolete Entries
 
3347
================
 
3348
 
 
3349
By "obsolete" PO file entries, we mean those entries which are
 
3350
commented out, usually by `msgmerge' when it found that the translation
 
3351
is not needed anymore by the package being localized.
 
3352
 
 
3353
   The usual commands moving from entry to entry consider obsolete
 
3354
entries on the same level as active entries.  Obsolete entries are
 
3355
easily recognizable by the fact that all their lines start with `#',
 
3356
even those lines containing `msgid' or `msgstr'.
 
3357
 
 
3358
   Commands exist for emptying the translation or reinitializing it to
 
3359
the original untranslated string.  Commands interfacing with the kill
 
3360
ring may force some previously saved text into the translation.  The
 
3361
user may interactively edit the translation.  All these commands may
 
3362
apply to obsolete entries, carefully leaving the entry obsolete after
 
3363
the fact.
 
3364
 
 
3365
   Moreover, some commands are more specifically related to obsolete
 
3366
entry processing.
 
3367
 
 
3368
`o'
 
3369
     Find the next obsolete entry (`po-next-obsolete-entry').
 
3370
 
 
3371
`O'
 
3372
     Find the previous obsolete entry (`po-previous-obsolete-entry').
 
3373
 
 
3374
`<DEL>'
 
3375
     Make an active entry obsolete, or zap out an obsolete entry
 
3376
     (`po-fade-out-entry').
 
3377
 
 
3378
 
 
3379
   The commands `o' (`po-next-obsolete-entry') and `O'
 
3380
(`po-previous-obsolete-entry') move forwards or backwards, chasing for
 
3381
an obsolete entry.  If none is found, the search is extended and wraps
 
3382
around in the PO file buffer.
 
3383
 
 
3384
   PO mode does not provide ways for un-commenting an obsolete entry
 
3385
and making it active, because this would reintroduce an original
 
3386
untranslated string which does not correspond to any marked string in
 
3387
the program sources.  This goes with the philosophy of never
 
3388
introducing useless `msgid' values.
 
3389
 
 
3390
   However, it is possible to comment out an active entry, so making it
 
3391
obsolete.  GNU `gettext' utilities will later react to the
 
3392
disappearance of a translation by using the untranslated string.  The
 
3393
command `<DEL>' (`po-fade-out-entry') pushes the current entry a little
 
3394
further towards annihilation.  If the entry is active (it is a
 
3395
translated entry), then it is first made fuzzy.  If it is already fuzzy,
 
3396
then the entry is merely commented out, with confirmation.  If the entry
 
3397
is already obsolete, then it is completely deleted from the PO file.
 
3398
It is easy to recycle the translation so deleted into some other PO file
 
3399
entry, usually one which is untranslated.  *Note Modifying
 
3400
Translations::.
 
3401
 
 
3402
   Here is a quite interesting problem to solve for later development of
 
3403
PO mode, for those nights you are not sleepy.  The idea would be that
 
3404
PO mode might become bright enough, one of these days, to make good
 
3405
guesses at retrieving the most probable candidate, among all obsolete
 
3406
entries, for initializing the translation of a newly appeared string.
 
3407
I think it might be a quite hard problem to do this algorithmically, as
 
3408
we have to develop good and efficient measures of string similarity.
 
3409
Right now, PO mode completely lets the decision to the translator, when
 
3410
the time comes to find the adequate obsolete translation, it merely
 
3411
tries to provide handy tools for helping her to do so.
 
3412
 
 
3413
 
 
3414
File: gettext.info,  Node: Modifying Translations,  Next: Modifying Comments,  Prev: Obsolete Entries,  Up: Updating
 
3415
 
 
3416
Modifying Translations
 
3417
======================
 
3418
 
 
3419
PO mode prevents direct modification of the PO file, by the usual means
 
3420
Emacs gives for altering a buffer's contents.  By doing so, it pretends
 
3421
helping the translator to avoid little clerical errors about the
 
3422
overall file format, or the proper quoting of strings, as those errors
 
3423
would be easily made.  Other kinds of errors are still possible, but
 
3424
some may be caught and diagnosed by the batch validation process, which
 
3425
the translator may always trigger by the `V' command.  For all other
 
3426
errors, the translator has to rely on her own judgment, and also on the
 
3427
linguistic reports submitted to her by the users of the translated
 
3428
package, having the same mother tongue.
 
3429
 
 
3430
   When the time comes to create a translation, correct an error
 
3431
diagnosed mechanically or reported by a user, the translators have to
 
3432
resort to using the following commands for modifying the translations.
 
3433
 
 
3434
`<RET>'
 
3435
     Interactively edit the translation (`po-edit-msgstr').
 
3436
 
 
3437
`<LFD>'
 
3438
`C-j'
 
3439
     Reinitialize the translation with the original, untranslated string
 
3440
     (`po-msgid-to-msgstr').
 
3441
 
 
3442
`k'
 
3443
     Save the translation on the kill ring, and delete it
 
3444
     (`po-kill-msgstr').
 
3445
 
 
3446
`w'
 
3447
     Save the translation on the kill ring, without deleting it
 
3448
     (`po-kill-ring-save-msgstr').
 
3449
 
 
3450
`y'
 
3451
     Replace the translation, taking the new from the kill ring
 
3452
     (`po-yank-msgstr').
 
3453
 
 
3454
 
 
3455
   The command `<RET>' (`po-edit-msgstr') opens a new Emacs window
 
3456
meant to edit in a new translation, or to modify an already existing
 
3457
translation.  The new window contains a copy of the translation taken
 
3458
from the current PO file entry, all ready for edition, expunged of all
 
3459
quoting marks, fully modifiable and with the complete extent of Emacs
 
3460
modifying commands.  When the translator is done with her
 
3461
modifications, she may use `C-c C-c' to close the subedit window with
 
3462
the automatically requoted results, or `C-c C-k' to abort her
 
3463
modifications.  *Note Subedit::, for more information.
 
3464
 
 
3465
   The command `<LFD>' (`po-msgid-to-msgstr') initializes, or
 
3466
reinitializes the translation with the original string.  This command is
 
3467
normally used when the translator wants to redo a fresh translation of
 
3468
the original string, disregarding any previous work.
 
3469
 
 
3470
   It is possible to arrange so, whenever editing an untranslated
 
3471
entry, the `<LFD>' command be automatically executed.  If you set
 
3472
`po-auto-edit-with-msgid' to `t', the translation gets initialised with
 
3473
the original string, in case none exists already.  The default value
 
3474
for `po-auto-edit-with-msgid' is `nil'.
 
3475
 
 
3476
   In fact, whether it is best to start a translation with an empty
 
3477
string, or rather with a copy of the original string, is a matter of
 
3478
taste or habit.  Sometimes, the source language and the target language
 
3479
are so different that is simply best to start writing on an empty page.
 
3480
At other times, the source and target languages are so close that it
 
3481
would be a waste to retype a number of words already being written in
 
3482
the original string.  A translator may also like having the original
 
3483
string right under her eyes, as she will progressively overwrite the
 
3484
original text with the translation, even if this requires some extra
 
3485
editing work to get rid of the original.
 
3486
 
 
3487
   The command `k' (`po-kill-msgstr') merely empties the translation
 
3488
string, so turning the entry into an untranslated one.  But while doing
 
3489
so, its previous contents is put apart in a special place, known as the
 
3490
kill ring.  The command `w' (`po-kill-ring-save-msgstr') has also the
 
3491
effect of taking a copy of the translation onto the kill ring, but it
 
3492
otherwise leaves the entry alone, and does _not_ remove the translation
 
3493
from the entry.  Both commands use exactly the Emacs kill ring, which
 
3494
is shared between buffers, and which is well known already to Emacs
 
3495
lovers.
 
3496
 
 
3497
   The translator may use `k' or `w' many times in the course of her
 
3498
work, as the kill ring may hold several saved translations.  From the
 
3499
kill ring, strings may later be reinserted in various Emacs buffers.
 
3500
In particular, the kill ring may be used for moving translation strings
 
3501
between different entries of a single PO file buffer, or if the
 
3502
translator is handling many such buffers at once, even between PO files.
 
3503
 
 
3504
   To facilitate exchanges with buffers which are not in PO mode, the
 
3505
translation string put on the kill ring by the `k' command is fully
 
3506
unquoted before being saved: external quotes are removed, multi-line
 
3507
strings are concatenated, and backslash escaped sequences are turned
 
3508
into their corresponding characters.  In the special case of obsolete
 
3509
entries, the translation is also uncommented prior to saving.
 
3510
 
 
3511
   The command `y' (`po-yank-msgstr') completely replaces the
 
3512
translation of the current entry by a string taken from the kill ring.
 
3513
Following Emacs terminology, we then say that the replacement string is
 
3514
"yanked" into the PO file buffer.  *Note Yanking: (emacs)Yanking.  The
 
3515
first time `y' is used, the translation receives the value of the most
 
3516
recent addition to the kill ring.  If `y' is typed once again,
 
3517
immediately, without intervening keystrokes, the translation just
 
3518
inserted is taken away and replaced by the second most recent addition
 
3519
to the kill ring.  By repeating `y' many times in a row, the translator
 
3520
may travel along the kill ring for saved strings, until she finds the
 
3521
string she really wanted.
 
3522
 
 
3523
   When a string is yanked into a PO file entry, it is fully and
 
3524
automatically requoted for complying with the format PO files should
 
3525
have.  Further, if the entry is obsolete, PO mode then appropriately
 
3526
push the inserted string inside comments.  Once again, translators
 
3527
should not burden themselves with quoting considerations besides, of
 
3528
course, the necessity of the translated string itself respective to the
 
3529
program using it.
 
3530
 
 
3531
   Note that `k' or `w' are not the only commands pushing strings on
 
3532
the kill ring, as almost any PO mode command replacing translation
 
3533
strings (or the translator comments) automatically saves the old string
 
3534
on the kill ring.  The main exceptions to this general rule are the
 
3535
yanking commands themselves.
 
3536
 
 
3537
   To better illustrate the operation of killing and yanking, let's use
 
3538
an actual example, taken from a common situation.  When the programmer
 
3539
slightly modifies some string right in the program, his change is later
 
3540
reflected in the PO file by the appearance of a new untranslated entry
 
3541
for the modified string, and the fact that the entry translating the
 
3542
original or unmodified string becomes obsolete.  In many cases, the
 
3543
translator might spare herself some work by retrieving the unmodified
 
3544
translation from the obsolete entry, then initializing the untranslated
 
3545
entry `msgstr' field with this retrieved translation.  Once this done,
 
3546
the obsolete entry is not wanted anymore, and may be safely deleted.
 
3547
 
 
3548
   When the translator finds an untranslated entry and suspects that a
 
3549
slight variant of the translation exists, she immediately uses `m' to
 
3550
mark the current entry location, then starts chasing obsolete entries
 
3551
with `o', hoping to find some translation corresponding to the
 
3552
unmodified string.  Once found, she uses the `<DEL>' command for
 
3553
deleting the obsolete entry, knowing that `<DEL>' also _kills_ the
 
3554
translation, that is, pushes the translation on the kill ring.  Then,
 
3555
`r' returns to the initial untranslated entry, and `y' then _yanks_ the
 
3556
saved translation right into the `msgstr' field.  The translator is
 
3557
then free to use `<RET>' for fine tuning the translation contents, and
 
3558
maybe to later use `u', then `m' again, for going on with the next
 
3559
untranslated string.
 
3560
 
 
3561
   When some sequence of keys has to be typed over and over again, the
 
3562
translator may find it useful to become better acquainted with the Emacs
 
3563
capability of learning these sequences and playing them back under
 
3564
request.  *Note Keyboard Macros: (emacs)Keyboard Macros.
 
3565
 
 
3566
 
 
3567
File: gettext.info,  Node: Modifying Comments,  Next: Subedit,  Prev: Modifying Translations,  Up: Updating
 
3568
 
 
3569
Modifying Comments
 
3570
==================
 
3571
 
 
3572
Any translation work done seriously will raise many linguistic
 
3573
difficulties, for which decisions have to be made, and the choices
 
3574
further documented.  These documents may be saved within the PO file in
 
3575
form of translator comments, which the translator is free to create,
 
3576
delete, or modify at will.  These comments may be useful to herself
 
3577
when she returns to this PO file after a while.
 
3578
 
 
3579
   Comments not having whitespace after the initial `#', for example,
 
3580
those beginning with `#.' or `#:', are _not_ translator comments, they
 
3581
are exclusively created by other `gettext' tools.  So, the commands
 
3582
below will never alter such system added comments, they are not meant
 
3583
for the translator to modify.  *Note PO Files::.
 
3584
 
 
3585
   The following commands are somewhat similar to those modifying
 
3586
translations, so the general indications given for those apply here.
 
3587
*Note Modifying Translations::.
 
3588
 
 
3589
`#'
 
3590
     Interactively edit the translator comments (`po-edit-comment').
 
3591
 
 
3592
`K'
 
3593
     Save the translator comments on the kill ring, and delete it
 
3594
     (`po-kill-comment').
 
3595
 
 
3596
`W'
 
3597
     Save the translator comments on the kill ring, without deleting it
 
3598
     (`po-kill-ring-save-comment').
 
3599
 
 
3600
`Y'
 
3601
     Replace the translator comments, taking the new from the kill ring
 
3602
     (`po-yank-comment').
 
3603
 
 
3604
 
 
3605
   These commands parallel PO mode commands for modifying the
 
3606
translation strings, and behave much the same way as they do, except
 
3607
that they handle this part of PO file comments meant for translator
 
3608
usage, rather than the translation strings.  So, if the descriptions
 
3609
given below are slightly succinct, it is because the full details have
 
3610
already been given.  *Note Modifying Translations::.
 
3611
 
 
3612
   The command `#' (`po-edit-comment') opens a new Emacs window
 
3613
containing a copy of the translator comments on the current PO file
 
3614
entry.  If there are no such comments, PO mode understands that the
 
3615
translator wants to add a comment to the entry, and she is presented
 
3616
with an empty screen.  Comment marks (`#') and the space following them
 
3617
are automatically removed before edition, and reinstated after.  For
 
3618
translator comments pertaining to obsolete entries, the uncommenting
 
3619
and recommenting operations are done twice.  Once in the editing
 
3620
window, the keys `C-c C-c' allow the translator to tell she is finished
 
3621
with editing the comment.  *Note Subedit::, for further details.
 
3622
 
 
3623
   Functions found on `po-subedit-mode-hook', if any, are executed after
 
3624
the string has been inserted in the edit buffer.
 
3625
 
 
3626
   The command `K' (`po-kill-comment') gets rid of all translator
 
3627
comments, while saving those comments on the kill ring.  The command
 
3628
`W' (`po-kill-ring-save-comment') takes a copy of the translator
 
3629
comments on the kill ring, but leaves them undisturbed in the current
 
3630
entry.  The command `Y' (`po-yank-comment') completely replaces the
 
3631
translator comments by a string taken at the front of the kill ring.
 
3632
When this command is immediately repeated, the comments just inserted
 
3633
are withdrawn, and replaced by other strings taken along the kill ring.
 
3634
 
 
3635
   On the kill ring, all strings have the same nature.  There is no
 
3636
distinction between _translation_ strings and _translator comments_
 
3637
strings.  So, for example, let's presume the translator has just
 
3638
finished editing a translation, and wants to create a new translator
 
3639
comment to document why the previous translation was not good, just to
 
3640
remember what was the problem.  Foreseeing that she will do that in her
 
3641
documentation, the translator may want to quote the previous
 
3642
translation in her translator comments.  To do so, she may initialize
 
3643
the translator comments with the previous translation, still at the
 
3644
head of the kill ring.  Because editing already pushed the previous
 
3645
translation on the kill ring, she merely has to type `M-w' prior to
 
3646
`#', and the previous translation will be right there, all ready for
 
3647
being introduced by some explanatory text.
 
3648
 
 
3649
   On the other hand, presume there are some translator comments already
 
3650
and that the translator wants to add to those comments, instead of
 
3651
wholly replacing them.  Then, she should edit the comment right away
 
3652
with `#'.  Once inside the editing window, she can use the regular
 
3653
Emacs commands `C-y' (`yank') and `M-y' (`yank-pop') to get the
 
3654
previous translation where she likes.
 
3655
 
 
3656
 
 
3657
File: gettext.info,  Node: Subedit,  Next: C Sources Context,  Prev: Modifying Comments,  Up: Updating
 
3658
 
 
3659
Details of Sub Edition
 
3660
======================
 
3661
 
 
3662
The PO subedit minor mode has a few peculiarities worth being described
 
3663
in fuller detail.  It installs a few commands over the usual editing set
 
3664
of Emacs, which are described below.
 
3665
 
 
3666
`C-c C-c'
 
3667
     Complete edition (`po-subedit-exit').
 
3668
 
 
3669
`C-c C-k'
 
3670
     Abort edition (`po-subedit-abort').
 
3671
 
 
3672
`C-c C-a'
 
3673
     Consult auxiliary PO files (`po-subedit-cycle-auxiliary').
 
3674
 
 
3675
 
 
3676
   The window's contents represents a translation for a given message,
 
3677
or a translator comment.  The translator may modify this window to her
 
3678
heart's content.  Once this is done, the command `C-c C-c'
 
3679
(`po-subedit-exit') may be used to return the edited translation into
 
3680
the PO file, replacing the original translation, even if it moved out of
 
3681
sight or if buffers were switched.
 
3682
 
 
3683
   If the translator becomes unsatisfied with her translation or
 
3684
comment, to the extent she prefers keeping what was existent prior to
 
3685
the `<RET>' or `#' command, she may use the command `C-c C-k'
 
3686
(`po-subedit-abort') to merely get rid of edition, while preserving the
 
3687
original translation or comment.  Another way would be for her to exit
 
3688
normally with `C-c C-c', then type `U' once for undoing the whole
 
3689
effect of last edition.
 
3690
 
 
3691
   The command `C-c C-a' (`po-subedit-cycle-auxiliary') allows for
 
3692
glancing through translations already achieved in other languages,
 
3693
directly while editing the current translation.  This may be quite
 
3694
convenient when the translator is fluent at many languages, but of
 
3695
course, only makes sense when such completed auxiliary PO files are
 
3696
already available to her (*note Auxiliary::).
 
3697
 
 
3698
   Functions found on `po-subedit-mode-hook', if any, are executed after
 
3699
the string has been inserted in the edit buffer.
 
3700
 
 
3701
   While editing her translation, the translator should pay attention
 
3702
to not inserting unwanted `<RET>' (newline) characters at the end of
 
3703
the translated string if those are not meant to be there, or to removing
 
3704
such characters when they are required.  Since these characters are not
 
3705
visible in the editing buffer, they are easily introduced by mistake.
 
3706
To help her, `<RET>' automatically puts the character `<' at the end of
 
3707
the string being edited, but this `<' is not really part of the string.
 
3708
On exiting the editing window with `C-c C-c', PO mode automatically
 
3709
removes such `<' and all whitespace added after it.  If the translator
 
3710
adds characters after the terminating `<', it looses its delimiting
 
3711
property and integrally becomes part of the string.  If she removes the
 
3712
delimiting `<', then the edited string is taken _as is_, with all
 
3713
trailing newlines, even if invisible.  Also, if the translated string
 
3714
ought to end itself with a genuine `<', then the delimiting `<' may not
 
3715
be removed; so the string should appear, in the editing window, as
 
3716
ending with two `<' in a row.
 
3717
 
 
3718
   When a translation (or a comment) is being edited, the translator
 
3719
may move the cursor back into the PO file buffer and freely move to
 
3720
other entries, browsing at will.  If, with an edition pending, the
 
3721
translator wanders in the PO file buffer, she may decide to start
 
3722
modifying another entry.  Each entry being edited has its own subedit
 
3723
buffer.  It is possible to simultaneously edit the translation _and_
 
3724
the comment of a single entry, or to edit entries in different PO
 
3725
files, all at once.  Typing `<RET>' on a field already being edited
 
3726
merely resumes that particular edit.  Yet, the translator should better
 
3727
be comfortable at handling many Emacs windows!
 
3728
 
 
3729
   Pending subedits may be completed or aborted in any order, regardless
 
3730
of how or when they were started.  When many subedits are pending and
 
3731
the translator asks for quitting the PO file (with the `q' command),
 
3732
subedits are automatically resumed one at a time, so she may decide for
 
3733
each of them.
 
3734
 
 
3735
 
 
3736
File: gettext.info,  Node: C Sources Context,  Next: Auxiliary,  Prev: Subedit,  Up: Updating
 
3737
 
 
3738
C Sources Context
 
3739
=================
 
3740
 
 
3741
PO mode is particularly powerful when used with PO files created
 
3742
through GNU `gettext' utilities, as those utilities insert special
 
3743
comments in the PO files they generate.  Some of these special comments
 
3744
relate the PO file entry to exactly where the untranslated string
 
3745
appears in the program sources.
 
3746
 
 
3747
   When the translator gets to an untranslated entry, she is fairly
 
3748
often faced with an original string which is not as informative as it
 
3749
normally should be, being succinct, cryptic, or otherwise ambiguous.
 
3750
Before choosing how to translate the string, she needs to understand
 
3751
better what the string really means and how tight the translation has
 
3752
to be.  Most of the time, when problems arise, the only way left to make
 
3753
her judgment is looking at the true program sources from where this
 
3754
string originated, searching for surrounding comments the programmer
 
3755
might have put in there, and looking around for helping clues of _any_
 
3756
kind.
 
3757
 
 
3758
   Surely, when looking at program sources, the translator will receive
 
3759
more help if she is a fluent programmer.  However, even if she is not
 
3760
versed in programming and feels a little lost in C code, the translator
 
3761
should not be shy at taking a look, once in a while.  It is most
 
3762
probable that she will still be able to find some of the hints she
 
3763
needs.  She will learn quickly to not feel uncomfortable in program
 
3764
code, paying more attention to programmer's comments, variable and
 
3765
function names (if he dared choosing them well), and overall
 
3766
organization, than to the program code itself.
 
3767
 
 
3768
   The following commands are meant to help the translator at getting
 
3769
program source context for a PO file entry.
 
3770
 
 
3771
`s'
 
3772
     Resume the display of a program source context, or cycle through
 
3773
     them (`po-cycle-source-reference').
 
3774
 
 
3775
`M-s'
 
3776
     Display of a program source context selected by menu
 
3777
     (`po-select-source-reference').
 
3778
 
 
3779
`S'
 
3780
     Add a directory to the search path for source files
 
3781
     (`po-consider-source-path').
 
3782
 
 
3783
`M-S'
 
3784
     Delete a directory from the search path for source files
 
3785
     (`po-ignore-source-path').
 
3786
 
 
3787
 
 
3788
   The commands `s' (`po-cycle-source-reference') and `M-s'
 
3789
(`po-select-source-reference') both open another window displaying some
 
3790
source program file, and already positioned in such a way that it shows
 
3791
an actual use of the string to be translated.  By doing so, the command
 
3792
gives source program context for the string.  But if the entry has no
 
3793
source context references, or if all references are unresolved along
 
3794
the search path for program sources, then the command diagnoses this as
 
3795
an error.
 
3796
 
 
3797
   Even if `s' (or `M-s') opens a new window, the cursor stays in the
 
3798
PO file window.  If the translator really wants to get into the program
 
3799
source window, she ought to do it explicitly, maybe by using command
 
3800
`O'.
 
3801
 
 
3802
   When `s' is typed for the first time, or for a PO file entry which
 
3803
is different of the last one used for getting source context, then the
 
3804
command reacts by giving the first context available for this entry, if
 
3805
any.  If some context has already been recently displayed for the
 
3806
current PO file entry, and the translator wandered off to do other
 
3807
things, typing `s' again will merely resume, in another window, the
 
3808
context last displayed.  In particular, if the translator moved the
 
3809
cursor away from the context in the source file, the command will bring
 
3810
the cursor back to the context.  By using `s' many times in a row, with
 
3811
no other commands intervening, PO mode will cycle to the next available
 
3812
contexts for this particular entry, getting back to the first context
 
3813
once the last has been shown.
 
3814
 
 
3815
   The command `M-s' behaves differently.  Instead of cycling through
 
3816
references, it lets the translator choose a particular reference among
 
3817
many, and displays that reference.  It is best used with completion, if
 
3818
the translator types `<TAB>' immediately after `M-s', in response to
 
3819
the question, she will be offered a menu of all possible references, as
 
3820
a reminder of which are the acceptable answers.  This command is useful
 
3821
only where there are really many contexts available for a single string
 
3822
to translate.
 
3823
 
 
3824
   Program source files are usually found relative to where the PO file
 
3825
stands.  As a special provision, when this fails, the file is also
 
3826
looked for, but relative to the directory immediately above it.  Those
 
3827
two cases take proper care of most PO files.  However, it might happen
 
3828
that a PO file has been moved, or is edited in a different place than
 
3829
its normal location.  When this happens, the translator should tell PO
 
3830
mode in which directory normally sits the genuine PO file.  Many such
 
3831
directories may be specified, and all together, they constitute what is
 
3832
called the "search path" for program sources.  The command `S'
 
3833
(`po-consider-source-path') is used to interactively enter a new
 
3834
directory at the front of the search path, and the command `M-S'
 
3835
(`po-ignore-source-path') is used to select, with completion, one of
 
3836
the directories she does not want anymore on the search path.
 
3837
 
 
3838
 
 
3839
File: gettext.info,  Node: Auxiliary,  Next: Compendium,  Prev: C Sources Context,  Up: Updating
 
3840
 
 
3841
Consulting Auxiliary PO Files
 
3842
=============================
 
3843
 
 
3844
PO mode is able to help the knowledgeable translator, being fluent in
 
3845
many languages, at taking advantage of translations already achieved in
 
3846
other languages she just happens to know.  It provides these other
 
3847
language translations as additional context for her own work.  Moreover,
 
3848
it has features to ease the production of translations for many
 
3849
languages at once, for translators preferring to work in this way.
 
3850
 
 
3851
   An "auxiliary" PO file is an existing PO file meant for the same
 
3852
package the translator is working on, but targeted to a different mother
 
3853
tongue language.  Commands exist for declaring and handling auxiliary
 
3854
PO files, and also for showing contexts for the entry under work.
 
3855
 
 
3856
   Here are the auxiliary file commands available in PO mode.
 
3857
 
 
3858
`a'
 
3859
     Seek auxiliary files for another translation for the same entry
 
3860
     (`po-cycle-auxiliary').
 
3861
 
 
3862
`C-c C-a'
 
3863
     Switch to a particular auxiliary file (`po-select-auxiliary').
 
3864
 
 
3865
`A'
 
3866
     Declare this PO file as an auxiliary file
 
3867
     (`po-consider-as-auxiliary').
 
3868
 
 
3869
`M-A'
 
3870
     Remove this PO file from the list of auxiliary files
 
3871
     (`po-ignore-as-auxiliary').
 
3872
 
 
3873
 
 
3874
   Command `A' (`po-consider-as-auxiliary') adds the current PO file to
 
3875
the list of auxiliary files, while command `M-A'
 
3876
(`po-ignore-as-auxiliary' just removes it.
 
3877
 
 
3878
   The command `a' (`po-cycle-auxiliary') seeks all auxiliary PO files,
 
3879
round-robin, searching for a translated entry in some other language
 
3880
having an `msgid' field identical as the one for the current entry.
 
3881
The found PO file, if any, takes the place of the current PO file in
 
3882
the display (its window gets on top).  Before doing so, the current PO
 
3883
file is also made into an auxiliary file, if not already.  So, `a' in
 
3884
this newly displayed PO file will seek another PO file, and so on, so
 
3885
repeating `a' will eventually yield back the original PO file.
 
3886
 
 
3887
   The command `C-c C-a' (`po-select-auxiliary') asks the translator
 
3888
for her choice of a particular auxiliary file, with completion, and
 
3889
then switches to that selected PO file.  The command also checks if the
 
3890
selected file has an `msgid' field identical as the one for the current
 
3891
entry, and if yes, this entry becomes current.  Otherwise, the cursor
 
3892
of the selected file is left undisturbed.
 
3893
 
 
3894
   For all this to work fully, auxiliary PO files will have to be
 
3895
normalized, in that way that `msgid' fields should be written _exactly_
 
3896
the same way.  It is possible to write `msgid' fields in various ways
 
3897
for representing the same string, different writing would break the
 
3898
proper behaviour of the auxiliary file commands of PO mode.  This is not
 
3899
expected to be much a problem in practice, as most existing PO files
 
3900
have their `msgid' entries written by the same GNU `gettext' tools.
 
3901
 
 
3902
   However, PO files initially created by PO mode itself, while marking
 
3903
strings in source files, are normalised differently.  So are PO files
 
3904
resulting of the the `M-x normalize' command.  Until these
 
3905
discrepancies between PO mode and other GNU `gettext' tools get fully
 
3906
resolved, the translator should stay aware of normalisation issues.
 
3907
 
 
3908
 
 
3909
File: gettext.info,  Node: Compendium,  Prev: Auxiliary,  Up: Updating
 
3910
 
 
3911
Using Translation Compendia
 
3912
===========================
 
3913
 
 
3914
A "compendium" is a special PO file containing a set of translations
 
3915
recurring in many different packages.  The translator can use gettext
 
3916
tools to build a new compendium, to add entries to her compendium, and
 
3917
to initialize untranslated entries, or to update already translated
 
3918
entries, from translations kept in the compendium.
 
3919
 
 
3920
* Menu:
 
3921
 
 
3922
* Creating Compendia::          Merging translations for later use
 
3923
* Using Compendia::             Using older translations if they fit
 
3924
 
 
3925
 
 
3926
File: gettext.info,  Node: Creating Compendia,  Next: Using Compendia,  Prev: Compendium,  Up: Compendium
 
3927
 
 
3928
Creating Compendia
 
3929
------------------
 
3930
 
 
3931
Basically every PO file consisting of translated entries only can be
 
3932
declared as a valid compendium.  Often the translator wants to have
 
3933
special compendia; let's consider two cases: `concatenating PO files'
 
3934
and `extracting a message subset from a PO file'.
 
3935
 
 
3936
Concatenate PO Files
 
3937
....................
 
3938
 
 
3939
To concatenate several valid PO files into one compendium file you can
 
3940
use `msgcomm' or `msgcat' (the latter preferred):
 
3941
 
 
3942
     msgcat -o compendium.po file1.po file2.po
 
3943
 
 
3944
   By default, `msgcat' will accumulate divergent translations for the
 
3945
same string.  Those occurences will be marked as `fuzzy' and highly
 
3946
visible decorated; calling `msgcat' on `file1.po':
 
3947
 
 
3948
     #: src/hello.c:200
 
3949
     #, c-format
 
3950
     msgid "Report bugs to <%s>.\n"
 
3951
     msgstr "Comunicar `bugs' a <%s>.\n"
 
3952
 
 
3953
and `file2.po':
 
3954
 
 
3955
     #: src/bye.c:100
 
3956
     #, c-format
 
3957
     msgid "Report bugs to <%s>.\n"
 
3958
     msgstr "Comunicar \"bugs\" a <%s>.\n"
 
3959
 
 
3960
will result in:
 
3961
 
 
3962
     #: src/hello.c:200 src/bye.c:100
 
3963
     #, fuzzy, c-format
 
3964
     msgid "Report bugs to <%s>.\n"
 
3965
     msgstr ""
 
3966
     "#-#-#-#-#  file1.po  #-#-#-#-#\n"
 
3967
     "Comunicar `bugs' a <%s>.\n"
 
3968
     "#-#-#-#-#  file2.po  #-#-#-#-#\n"
 
3969
     "Comunicar \"bugs\" a <%s>.\n"
 
3970
 
 
3971
The translator will have to resolve this "conflict" manually; she has
 
3972
to decide whether the first or the second version is appropriate (or
 
3973
provide a new translation), to delete the "marker lines", and finally
 
3974
to remove the `fuzzy' mark.
 
3975
 
 
3976
   If the translator knows in advance the first found translation of a
 
3977
message is always the best translation she can make use to the
 
3978
`--use-first' switch:
 
3979
 
 
3980
     msgcat --use-first -o compendium.po file1.po file2.po
 
3981
 
 
3982
   A good compendium file must not contain `fuzzy' or untranslated
 
3983
entries.  If input files are "dirty" you must preprocess the input
 
3984
files or postprocess the result using `msgattrib --translated
 
3985
--no-fuzzy'.
 
3986
 
 
3987
Extract a Message Subset from a PO File
 
3988
.......................................
 
3989
 
 
3990
Nobody wants to translate the same messages again and again; thus you
 
3991
may wish to have a compendium file containing `getopt.c' messages.
 
3992
 
 
3993
   To extract a message subset (e.g., all `getopt.c' messages) from an
 
3994
existing PO file into one compendium file you can use `msggrep':
 
3995
 
 
3996
     msggrep --location src/getopt.c -o compendium.po file.po
 
3997
 
 
3998
 
 
3999
File: gettext.info,  Node: Using Compendia,  Prev: Creating Compendia,  Up: Compendium
 
4000
 
 
4001
Using Compendia
 
4002
---------------
 
4003
 
 
4004
You can use a compendium file to initialize a translation from scratch
 
4005
or to update an already existing translation.
 
4006
 
 
4007
Initialize a New Translation File
 
4008
.................................
 
4009
 
 
4010
Since a PO file with translations does not exist the translator can
 
4011
merely use `/dev/null' to fake the "old" translation file.
 
4012
 
 
4013
     msgmerge --compendium compendium.po -o file.po /dev/null file.pot
 
4014
 
 
4015
Update an Existing Translation File
 
4016
...................................
 
4017
 
 
4018
Concatenate the compendium file(s) and the existing PO, merge the
 
4019
result with the POT file and remove the obsolete entries (optional,
 
4020
here done using `sed'):
 
4021
 
 
4022
     msgcat --use-first -o update.po compendium1.po compendium2.po file.po
 
4023
     msgmerge update.po file.pot | sed -e '/^#~/d' > file.po
 
4024
 
 
4025
 
 
4026
File: gettext.info,  Node: Manipulating,  Next: Binaries,  Prev: Updating,  Up: Top
 
4027
 
 
4028
Manipulating PO Files
 
4029
*********************
 
4030
 
 
4031
Sometimes it is necessary to manipulate PO files in a way that is better
 
4032
performed automatically than by hand.  GNU `gettext' includes a
 
4033
complete set of tools for this purpose.
 
4034
 
 
4035
   When merging two packages into a single package, the resulting POT
 
4036
file will be the concatenation of the two packages' POT files.  Thus the
 
4037
maintainer must concatenate the two existing package translations into
 
4038
a single translation catalog, for each language.  This is best performed
 
4039
using `msgcat'.  It is then the translators' duty to deal with any
 
4040
possible conflicts that arose during the merge.
 
4041
 
 
4042
   When a translator takes over the translation job from another
 
4043
translator, but she uses a different character encoding in her locale,
 
4044
she will convert the catalog to her character encoding.  This is best
 
4045
done through the `msgconv' program.
 
4046
 
 
4047
   When a maintainer takes a source file with tagged messages from
 
4048
another package, he should also take the existing translations for this
 
4049
source file (and not let the translators do the same job twice).  One
 
4050
way to do this is through `msggrep', another is to create a POT file for
 
4051
that source file and use `msgmerge'.
 
4052
 
 
4053
   When a translator wants to adjust some translation catalog for a
 
4054
special dialect or orthography -- for example, German as written in
 
4055
Switzerland versus German as written in Germany -- she needs to apply
 
4056
some text processing to every message in the catalog.  The tool for
 
4057
doing this is `msgfilter'.
 
4058
 
 
4059
   Another use of `msgfilter' is to produce approximately the POT file
 
4060
for which a given PO file was made.  This can be done through a filter
 
4061
command like `msgfilter sed -e d | sed -e '/^# /d''.  Note that the
 
4062
original POT file may have had different comments and different plural
 
4063
message counts, that's why it's better to use the original POT file if
 
4064
available.
 
4065
 
 
4066
   When a translator wants to check her translations, for example
 
4067
according to orthography rules or using a non-interactive spell
 
4068
checker, she can do so using the `msgexec' program.
 
4069
 
 
4070
   When third party tools create PO or POT files, sometimes duplicates
 
4071
cannot be avoided.  But the GNU `gettext' tools give an error when they
 
4072
encounter duplicate msgids in the same file and in the same domain.  To
 
4073
merge duplicates, the `msguniq' program can be used.
 
4074
 
 
4075
   `msgcomm' is a more general tool for keeping or throwing away
 
4076
duplicates, occurring in different files.
 
4077
 
 
4078
   `msgcmp' can be used to check whether a translation catalog is
 
4079
completely translated.
 
4080
 
 
4081
   `msgattrib' can be used to select and extract only the fuzzy or
 
4082
untranslated messages of a translation catalog.
 
4083
 
 
4084
   `msgen' is useful as a first step for preparing English translation
 
4085
catalogs.  It copies each message's msgid to its msgstr.
 
4086
 
 
4087
   Finally, for those applications where all these various programs are
 
4088
not sufficient, a library `libgettextpo' is provided that can be used to
 
4089
write other specialized programs that process PO files.
 
4090
 
 
4091
* Menu:
 
4092
 
 
4093
* msgcat Invocation::           Invoking the `msgcat' Program
 
4094
* msgconv Invocation::          Invoking the `msgconv' Program
 
4095
* msggrep Invocation::          Invoking the `msggrep' Program
 
4096
* msgfilter Invocation::        Invoking the `msgfilter' Program
 
4097
* msguniq Invocation::          Invoking the `msguniq' Program
 
4098
* msgcomm Invocation::          Invoking the `msgcomm' Program
 
4099
* msgcmp Invocation::           Invoking the `msgcmp' Program
 
4100
* msgattrib Invocation::        Invoking the `msgattrib' Program
 
4101
* msgen Invocation::            Invoking the `msgen' Program
 
4102
* msgexec Invocation::          Invoking the `msgexec' Program
 
4103
* libgettextpo::                Writing your own programs that process PO files
 
4104
 
 
4105
 
 
4106
File: gettext.info,  Node: msgcat Invocation,  Next: msgconv Invocation,  Prev: Manipulating,  Up: Manipulating
 
4107
 
 
4108
Invoking the `msgcat' Program
 
4109
=============================
 
4110
 
 
4111
     msgcat [OPTION] [INPUTFILE]...
 
4112
 
 
4113
   The `msgcat' program concatenates and merges the specified PO files.
 
4114
It finds messages which are common to two or more of the specified PO
 
4115
files.  By using the `--more-than' option, greater commonality may be
 
4116
requested before messages are printed.  Conversely, the `--less-than'
 
4117
option may be used to specify less commonality before messages are
 
4118
printed (i.e.  `--less-than=2' will only print the unique messages).
 
4119
Translations, comments and extract comments will be cumulated, except
 
4120
that if `--use-first' is specified, they will be taken from the first
 
4121
PO file to define them.  File positions from all PO files will be
 
4122
cumulated.
 
4123
 
 
4124
Input file location
 
4125
-------------------
 
4126
 
 
4127
`INPUTFILE ...'
 
4128
     Input files.
 
4129
 
 
4130
`-f FILE'
 
4131
`--files-from=FILE'
 
4132
     Read the names of the input files from FILE instead of getting
 
4133
     them from the command line.
 
4134
 
 
4135
`-D DIRECTORY'
 
4136
`--directory=DIRECTORY'
 
4137
     Add DIRECTORY to the list of directories.  Source files are
 
4138
     searched relative to this list of directories.  The resulting `.po'
 
4139
     file will be written relative to the current directory, though.
 
4140
 
 
4141
 
 
4142
   If INPUTFILE is `-', standard input is read.
 
4143
 
 
4144
Output file location
 
4145
--------------------
 
4146
 
 
4147
`-o FILE'
 
4148
`--output-file=FILE'
 
4149
     Write output to specified file.
 
4150
 
 
4151
 
 
4152
   The results are written to standard output if no output file is
 
4153
specified or if it is `-'.
 
4154
 
 
4155
Message selection
 
4156
-----------------
 
4157
 
 
4158
`-< NUMBER'
 
4159
`--less-than=NUMBER'
 
4160
     Print messages with less than NUMBER definitions, defaults to
 
4161
     infinite if not set.
 
4162
 
 
4163
`-> NUMBER'
 
4164
`--more-than=NUMBER'
 
4165
     Print messages with more than NUMBER definitions, defaults to 0 if
 
4166
     not set.
 
4167
 
 
4168
`-u'
 
4169
`--unique'
 
4170
     Shorthand for `--less-than=2'.  Requests that only unique messages
 
4171
     be printed.
 
4172
 
 
4173
 
 
4174
Input file syntax
 
4175
-----------------
 
4176
 
 
4177
`-P'
 
4178
`--properties-input'
 
4179
     Assume the input files are Java ResourceBundles in Java
 
4180
     `.properties' syntax, not in PO file syntax.
 
4181
 
 
4182
`--stringtable-input'
 
4183
     Assume the input files are NeXTstep/GNUstep localized resource
 
4184
     files in `.strings' syntax, not in PO file syntax.
 
4185
 
 
4186
 
 
4187
Output details
 
4188
--------------
 
4189
 
 
4190
`-t'
 
4191
`--to-code=NAME'
 
4192
     Specify encoding for output.
 
4193
 
 
4194
`--use-first'
 
4195
     Use first available translation for each message.  Don't merge
 
4196
     several translations into one.
 
4197
 
 
4198
`--force-po'
 
4199
     Always write an output file even if it contains no message.
 
4200
 
 
4201
`-i'
 
4202
`--indent'
 
4203
     Write the .po file using indented style.
 
4204
 
 
4205
`--no-location'
 
4206
     Do not write `#: FILENAME:LINE' lines.
 
4207
 
 
4208
`-n'
 
4209
`--add-location'
 
4210
     Generate `#: FILENAME:LINE' lines (default).
 
4211
 
 
4212
`--strict'
 
4213
     Write out a strict Uniforum conforming PO file.  Note that this
 
4214
     Uniforum format should be avoided because it doesn't support the
 
4215
     GNU extensions.
 
4216
 
 
4217
`-p'
 
4218
`--properties-output'
 
4219
     Write out a Java ResourceBundle in Java `.properties' syntax.  Note
 
4220
     that this file format doesn't support plural forms and silently
 
4221
     drops obsolete messages.
 
4222
 
 
4223
`--stringtable-output'
 
4224
     Write out a NeXTstep/GNUstep localized resource file in `.strings'
 
4225
     syntax.  Note that this file format doesn't support plural forms.
 
4226
 
 
4227
`-w NUMBER'
 
4228
`--width=NUMBER'
 
4229
     Set the output page width.  Long strings in the output files will
 
4230
     be split across multiple lines in order to ensure that each line's
 
4231
     width (= number of screen columns) is less or equal to the given
 
4232
     NUMBER.
 
4233
 
 
4234
`--no-wrap'
 
4235
     Do not break long message lines.  Message lines whose width
 
4236
     exceeds the output page width will not be split into several
 
4237
     lines.  Only file reference lines which are wider than the output
 
4238
     page width will be split.
 
4239
 
 
4240
`-s'
 
4241
`--sort-output'
 
4242
     Generate sorted output.  Note that using this option makes it much
 
4243
     harder for the translator to understand each message's context.
 
4244
 
 
4245
`-F'
 
4246
`--sort-by-file'
 
4247
     Sort output by file location.
 
4248
 
 
4249
 
 
4250
Informative output
 
4251
------------------
 
4252
 
 
4253
`-h'
 
4254
`--help'
 
4255
     Display this help and exit.
 
4256
 
 
4257
`-V'
 
4258
`--version'
 
4259
     Output version information and exit.
 
4260
 
 
4261
 
 
4262
 
 
4263
File: gettext.info,  Node: msgconv Invocation,  Next: msggrep Invocation,  Prev: msgcat Invocation,  Up: Manipulating
 
4264
 
 
4265
Invoking the `msgconv' Program
 
4266
==============================
 
4267
 
 
4268
     msgconv [OPTION] [INPUTFILE]
 
4269
 
 
4270
   The `msgconv' program converts a translation catalog to a different
 
4271
character encoding.
 
4272
 
 
4273
Input file location
 
4274
-------------------
 
4275
 
 
4276
`INPUTFILE'
 
4277
     Input PO file.
 
4278
 
 
4279
`-D DIRECTORY'
 
4280
`--directory=DIRECTORY'
 
4281
     Add DIRECTORY to the list of directories.  Source files are
 
4282
     searched relative to this list of directories.  The resulting `.po'
 
4283
     file will be written relative to the current directory, though.
 
4284
 
 
4285
 
 
4286
   If no INPUTFILE is given or if it is `-', standard input is read.
 
4287
 
 
4288
Output file location
 
4289
--------------------
 
4290
 
 
4291
`-o FILE'
 
4292
`--output-file=FILE'
 
4293
     Write output to specified file.
 
4294
 
 
4295
 
 
4296
   The results are written to standard output if no output file is
 
4297
specified or if it is `-'.
 
4298
 
 
4299
Conversion target
 
4300
-----------------
 
4301
 
 
4302
`-t'
 
4303
`--to-code=NAME'
 
4304
     Specify encoding for output.
 
4305
 
 
4306
 
 
4307
   The default encoding is the current locale's encoding.
 
4308
 
 
4309
Input file syntax
 
4310
-----------------
 
4311
 
 
4312
`-P'
 
4313
`--properties-input'
 
4314
     Assume the input file is a Java ResourceBundle in Java
 
4315
     `.properties' syntax, not in PO file syntax.
 
4316
 
 
4317
`--stringtable-input'
 
4318
     Assume the input file is a NeXTstep/GNUstep localized resource
 
4319
     file in `.strings' syntax, not in PO file syntax.
 
4320
 
 
4321
 
 
4322
Output details
 
4323
--------------
 
4324
 
 
4325
`--force-po'
 
4326
     Always write an output file even if it contains no message.
 
4327
 
 
4328
`-i'
 
4329
`--indent'
 
4330
     Write the .po file using indented style.
 
4331
 
 
4332
`--no-location'
 
4333
     Do not write `#: FILENAME:LINE' lines.
 
4334
 
 
4335
`--add-location'
 
4336
     Generate `#: FILENAME:LINE' lines (default).
 
4337
 
 
4338
`--strict'
 
4339
     Write out a strict Uniforum conforming PO file.  Note that this
 
4340
     Uniforum format should be avoided because it doesn't support the
 
4341
     GNU extensions.
 
4342
 
 
4343
`-p'
 
4344
`--properties-output'
 
4345
     Write out a Java ResourceBundle in Java `.properties' syntax.  Note
 
4346
     that this file format doesn't support plural forms and silently
 
4347
     drops obsolete messages.
 
4348
 
 
4349
`--stringtable-output'
 
4350
     Write out a NeXTstep/GNUstep localized resource file in `.strings'
 
4351
     syntax.  Note that this file format doesn't support plural forms.
 
4352
 
 
4353
`-w NUMBER'
 
4354
`--width=NUMBER'
 
4355
     Set the output page width.  Long strings in the output files will
 
4356
     be split across multiple lines in order to ensure that each line's
 
4357
     width (= number of screen columns) is less or equal to the given
 
4358
     NUMBER.
 
4359
 
 
4360
`--no-wrap'
 
4361
     Do not break long message lines.  Message lines whose width
 
4362
     exceeds the output page width will not be split into several
 
4363
     lines.  Only file reference lines which are wider than the output
 
4364
     page width will be split.
 
4365
 
 
4366
`-s'
 
4367
`--sort-output'
 
4368
     Generate sorted output.  Note that using this option makes it much
 
4369
     harder for the translator to understand each message's context.
 
4370
 
 
4371
`-F'
 
4372
`--sort-by-file'
 
4373
     Sort output by file location.
 
4374
 
 
4375
 
 
4376
Informative output
 
4377
------------------
 
4378
 
 
4379
`-h'
 
4380
`--help'
 
4381
     Display this help and exit.
 
4382
 
 
4383
`-V'
 
4384
`--version'
 
4385
     Output version information and exit.
 
4386
 
 
4387
 
 
4388
 
 
4389
File: gettext.info,  Node: msggrep Invocation,  Next: msgfilter Invocation,  Prev: msgconv Invocation,  Up: Manipulating
 
4390
 
 
4391
Invoking the `msggrep' Program
 
4392
==============================
 
4393
 
 
4394
     msggrep [OPTION] [INPUTFILE]
 
4395
 
 
4396
   The `msggrep' program extracts all messages of a translation catalog
 
4397
that match a given pattern or belong to some given source files.
 
4398
 
 
4399
Input file location
 
4400
-------------------
 
4401
 
 
4402
`INPUTFILE'
 
4403
     Input PO file.
 
4404
 
 
4405
`-D DIRECTORY'
 
4406
`--directory=DIRECTORY'
 
4407
     Add DIRECTORY to the list of directories.  Source files are
 
4408
     searched relative to this list of directories.  The resulting `.po'
 
4409
     file will be written relative to the current directory, though.
 
4410
 
 
4411
 
 
4412
   If no INPUTFILE is given or if it is `-', standard input is read.
 
4413
 
 
4414
Output file location
 
4415
--------------------
 
4416
 
 
4417
`-o FILE'
 
4418
`--output-file=FILE'
 
4419
     Write output to specified file.
 
4420
 
 
4421
 
 
4422
   The results are written to standard output if no output file is
 
4423
specified or if it is `-'.
 
4424
 
 
4425
Message selection
 
4426
-----------------
 
4427
 
 
4428
       [-N SOURCEFILE]... [-M DOMAINNAME]...
 
4429
       [-K MSGID-PATTERN] [-T MSGSTR-PATTERN] [-C COMMENT-PATTERN]
 
4430
 
 
4431
   A message is selected if
 
4432
   * it comes from one of the specified source files,
 
4433
 
 
4434
   * or if it comes from one of the specified domains,
 
4435
 
 
4436
   * or if `-K' is given and its key (msgid or msgid_plural) matches
 
4437
       MSGID-PATTERN,
 
4438
 
 
4439
   * or if `-T' is given and its translation (msgstr) matches
 
4440
     MSGSTR-PATTERN,
 
4441
 
 
4442
   * or if `-C' is given and the translator's comment matches
 
4443
     COMMENT-PATTERN.
 
4444
 
 
4445
   When more than one selection criterion is specified, the set of
 
4446
selected messages is the union of the selected messages of each
 
4447
criterion.
 
4448
 
 
4449
   MSGID-PATTERN or MSGSTR-PATTERN syntax:
 
4450
       [-E | -F] [-e PATTERN | -f FILE]...
 
4451
   PATTERNs are basic regular expressions by default, or extended
 
4452
regular expressions if -E is given, or fixed strings if -F is given.
 
4453
 
 
4454
`-N SOURCEFILE'
 
4455
`--location=SOURCEFILE'
 
4456
     Select messages extracted from SOURCEFILE.  SOURCEFILE can be
 
4457
     either a literal file name or a wildcard pattern.
 
4458
 
 
4459
`-M DOMAINNAME'
 
4460
`--domain=DOMAINNAME'
 
4461
     Select messages belonging to domain DOMAINNAME.
 
4462
 
 
4463
`-K'
 
4464
`--msgid'
 
4465
     Start of patterns for the msgid.
 
4466
 
 
4467
`-T'
 
4468
`--msgstr'
 
4469
     Start of patterns for the msgstr.
 
4470
 
 
4471
`-C'
 
4472
`--comment'
 
4473
     Start of patterns for the translator's comment.
 
4474
 
 
4475
`-E'
 
4476
`--extended-regexp'
 
4477
     Specify that PATTERN is an extended regular expression.
 
4478
 
 
4479
`-F'
 
4480
`--fixed-strings'
 
4481
     Specify that PATTERN is a set of newline-separated strings.
 
4482
 
 
4483
`-e PATTERN'
 
4484
`--regexp=PATTERN'
 
4485
     Use PATTERN as a regular expression.
 
4486
 
 
4487
`-f FILE'
 
4488
`--file=FILE'
 
4489
     Obtain PATTERN from FILE.
 
4490
 
 
4491
`-i'
 
4492
`--ignore-case'
 
4493
     Ignore case distinctions.
 
4494
 
 
4495
 
 
4496
Input file syntax
 
4497
-----------------
 
4498
 
 
4499
`-P'
 
4500
`--properties-input'
 
4501
     Assume the input file is a Java ResourceBundle in Java
 
4502
     `.properties' syntax, not in PO file syntax.
 
4503
 
 
4504
`--stringtable-input'
 
4505
     Assume the input file is a NeXTstep/GNUstep localized resource
 
4506
     file in `.strings' syntax, not in PO file syntax.
 
4507
 
 
4508
 
 
4509
Output details
 
4510
--------------
 
4511
 
 
4512
`--force-po'
 
4513
     Always write an output file even if it contains no message.
 
4514
 
 
4515
`--indent'
 
4516
     Write the .po file using indented style.
 
4517
 
 
4518
`--no-location'
 
4519
     Do not write `#: FILENAME:LINE' lines.
 
4520
 
 
4521
`--add-location'
 
4522
     Generate `#: FILENAME:LINE' lines (default).
 
4523
 
 
4524
`--strict'
 
4525
     Write out a strict Uniforum conforming PO file.  Note that this
 
4526
     Uniforum format should be avoided because it doesn't support the
 
4527
     GNU extensions.
 
4528
 
 
4529
`-p'
 
4530
`--properties-output'
 
4531
     Write out a Java ResourceBundle in Java `.properties' syntax.  Note
 
4532
     that this file format doesn't support plural forms and silently
 
4533
     drops obsolete messages.
 
4534
 
 
4535
`--stringtable-output'
 
4536
     Write out a NeXTstep/GNUstep localized resource file in `.strings'
 
4537
     syntax.  Note that this file format doesn't support plural forms.
 
4538
 
 
4539
`-w NUMBER'
 
4540
`--width=NUMBER'
 
4541
     Set the output page width.  Long strings in the output files will
 
4542
     be split across multiple lines in order to ensure that each line's
 
4543
     width (= number of screen columns) is less or equal to the given
 
4544
     NUMBER.
 
4545
 
 
4546
`--no-wrap'
 
4547
     Do not break long message lines.  Message lines whose width
 
4548
     exceeds the output page width will not be split into several
 
4549
     lines.  Only file reference lines which are wider than the output
 
4550
     page width will be split.
 
4551
 
 
4552
`--sort-output'
 
4553
     Generate sorted output.  Note that using this option makes it much
 
4554
     harder for the translator to understand each message's context.
 
4555
 
 
4556
`--sort-by-file'
 
4557
     Sort output by file location.
 
4558
 
 
4559
 
 
4560
Informative output
 
4561
------------------
 
4562
 
 
4563
`-h'
 
4564
`--help'
 
4565
     Display this help and exit.
 
4566
 
 
4567
`-V'
 
4568
`--version'
 
4569
     Output version information and exit.
 
4570
 
 
4571
 
 
4572
 
 
4573
File: gettext.info,  Node: msgfilter Invocation,  Next: msguniq Invocation,  Prev: msggrep Invocation,  Up: Manipulating
 
4574
 
 
4575
Invoking the `msgfilter' Program
 
4576
================================
 
4577
 
 
4578
     msgfilter [OPTION] FILTER [FILTER-OPTION]
 
4579
 
 
4580
   The `msgfilter' program applies a filter to all translations of a
 
4581
translation catalog.
 
4582
 
 
4583
Input file location
 
4584
-------------------
 
4585
 
 
4586
`-i INPUTFILE'
 
4587
`--input=INPUTFILE'
 
4588
     Input PO file.
 
4589
 
 
4590
`-D DIRECTORY'
 
4591
`--directory=DIRECTORY'
 
4592
     Add DIRECTORY to the list of directories.  Source files are
 
4593
     searched relative to this list of directories.  The resulting `.po'
 
4594
     file will be written relative to the current directory, though.
 
4595
 
 
4596
 
 
4597
   If no INPUTFILE is given or if it is `-', standard input is read.
 
4598
 
 
4599
Output file location
 
4600
--------------------
 
4601
 
 
4602
`-o FILE'
 
4603
`--output-file=FILE'
 
4604
     Write output to specified file.
 
4605
 
 
4606
 
 
4607
   The results are written to standard output if no output file is
 
4608
specified or if it is `-'.
 
4609
 
 
4610
The filter
 
4611
----------
 
4612
 
 
4613
The FILTER can be any program that reads a translation from standard
 
4614
input and writes a modified translation to standard output.  A
 
4615
frequently used filter is `sed'.
 
4616
 
 
4617
   Note: It is your responsibility to ensure that the FILTER can cope
 
4618
with input encoded in the translation catalog's encoding.  If the
 
4619
FILTER wants input in a particular encoding, you can in a first step
 
4620
convert the translation catalog to that encoding using the `msgconv'
 
4621
program, before invoking `msgfilter'.  If the FILTER wants input in the
 
4622
locale's encoding, but you want to avoid the locale's encoding, then
 
4623
you can first convert the translation catalog to UTF-8 using the
 
4624
`msgconv' program and then make `msgfilter' work in an UTF-8 locale, by
 
4625
using the `LC_ALL' environment variable.
 
4626
 
 
4627
   Note: Most translations in a translation catalog don't end with a
 
4628
newline character.  For this reason, it is important that the FILTER
 
4629
recognizes its last input line even if it ends without a newline, and
 
4630
that it doesn't add an undesired trailing newline at the end.  The `sed'
 
4631
program on some platforms is known to ignore the last line of input if
 
4632
it is not terminated with a newline.  You can use GNU `sed' instead; it
 
4633
does not have this limitation.
 
4634
 
 
4635
Useful FILTER-OPTIONs when the FILTER is `sed'
 
4636
----------------------------------------------
 
4637
 
 
4638
`-e SCRIPT'
 
4639
`--expression=SCRIPT'
 
4640
     Add SCRIPT to the commands to be executed.
 
4641
 
 
4642
`-f SCRIPTFILE'
 
4643
`--file=SCRIPTFILE'
 
4644
     Add the contents of SCRIPTFILE to the commands to be executed.
 
4645
 
 
4646
`-n'
 
4647
`--quiet'
 
4648
`--silent'
 
4649
     Suppress automatic printing of pattern space.
 
4650
 
 
4651
 
 
4652
Input file syntax
 
4653
-----------------
 
4654
 
 
4655
`-P'
 
4656
`--properties-input'
 
4657
     Assume the input file is a Java ResourceBundle in Java
 
4658
     `.properties' syntax, not in PO file syntax.
 
4659
 
 
4660
`--stringtable-input'
 
4661
     Assume the input file is a NeXTstep/GNUstep localized resource
 
4662
     file in `.strings' syntax, not in PO file syntax.
 
4663
 
 
4664
 
 
4665
Output details
 
4666
--------------
 
4667
 
 
4668
`--force-po'
 
4669
     Always write an output file even if it contains no message.
 
4670
 
 
4671
`--indent'
 
4672
     Write the .po file using indented style.
 
4673
 
 
4674
`--keep-header'
 
4675
     Keep the header entry, i.e. the message with `msgid ""',
 
4676
     unmodified, instead of filtering it.  By default, the header entry
 
4677
     is subject to filtering like any other message.
 
4678
 
 
4679
`--no-location'
 
4680
     Do not write `#: FILENAME:LINE' lines.
 
4681
 
 
4682
`--add-location'
 
4683
     Generate `#: FILENAME:LINE' lines (default).
 
4684
 
 
4685
`--strict'
 
4686
     Write out a strict Uniforum conforming PO file.  Note that this
 
4687
     Uniforum format should be avoided because it doesn't support the
 
4688
     GNU extensions.
 
4689
 
 
4690
`-p'
 
4691
`--properties-output'
 
4692
     Write out a Java ResourceBundle in Java `.properties' syntax.  Note
 
4693
     that this file format doesn't support plural forms and silently
 
4694
     drops obsolete messages.
 
4695
 
 
4696
`--stringtable-output'
 
4697
     Write out a NeXTstep/GNUstep localized resource file in `.strings'
 
4698
     syntax.  Note that this file format doesn't support plural forms.
 
4699
 
 
4700
`-w NUMBER'
 
4701
`--width=NUMBER'
 
4702
     Set the output page width.  Long strings in the output files will
 
4703
     be split across multiple lines in order to ensure that each line's
 
4704
     width (= number of screen columns) is less or equal to the given
 
4705
     NUMBER.
 
4706
 
 
4707
`--no-wrap'
 
4708
     Do not break long message lines.  Message lines whose width
 
4709
     exceeds the output page width will not be split into several
 
4710
     lines.  Only file reference lines which are wider than the output
 
4711
     page width will be split.
 
4712
 
 
4713
`-s'
 
4714
`--sort-output'
 
4715
     Generate sorted output.  Note that using this option makes it much
 
4716
     harder for the translator to understand each message's context.
 
4717
 
 
4718
`-F'
 
4719
`--sort-by-file'
 
4720
     Sort output by file location.
 
4721
 
 
4722
 
 
4723
Informative output
 
4724
------------------
 
4725
 
 
4726
`-h'
 
4727
`--help'
 
4728
     Display this help and exit.
 
4729
 
 
4730
`-V'
 
4731
`--version'
 
4732
     Output version information and exit.
 
4733
 
 
4734
 
 
4735
 
 
4736
File: gettext.info,  Node: msguniq Invocation,  Next: msgcomm Invocation,  Prev: msgfilter Invocation,  Up: Manipulating
 
4737
 
 
4738
Invoking the `msguniq' Program
 
4739
==============================
 
4740
 
 
4741
     msguniq [OPTION] [INPUTFILE]
 
4742
 
 
4743
   The `msguniq' program unifies duplicate translations in a translation
 
4744
catalog.  It finds duplicate translations of the same message ID.  Such
 
4745
duplicates are invalid input for other programs like `msgfmt',
 
4746
`msgmerge' or `msgcat'.  By default, duplicates are merged together.
 
4747
When using the `--repeated' option, only duplicates are output, and all
 
4748
other messages are discarded.  Comments and extracted comments will be
 
4749
cumulated, except that if `--use-first' is specified, they will be
 
4750
taken from the first translation.  File positions will be cumulated.
 
4751
When using the `--unique' option, duplicates are discarded.
 
4752
 
 
4753
Input file location
 
4754
-------------------
 
4755
 
 
4756
`INPUTFILE'
 
4757
     Input PO file.
 
4758
 
 
4759
`-D DIRECTORY'
 
4760
`--directory=DIRECTORY'
 
4761
     Add DIRECTORY to the list of directories.  Source files are
 
4762
     searched relative to this list of directories.  The resulting `.po'
 
4763
     file will be written relative to the current directory, though.
 
4764
 
 
4765
 
 
4766
   If no INPUTFILE is given or if it is `-', standard input is read.
 
4767
 
 
4768
Output file location
 
4769
--------------------
 
4770
 
 
4771
`-o FILE'
 
4772
`--output-file=FILE'
 
4773
     Write output to specified file.
 
4774
 
 
4775
 
 
4776
   The results are written to standard output if no output file is
 
4777
specified or if it is `-'.
 
4778
 
 
4779
Message selection
 
4780
-----------------
 
4781
 
 
4782
`-d'
 
4783
`--repeated'
 
4784
     Print only duplicates.
 
4785
 
 
4786
`-u'
 
4787
`--unique'
 
4788
     Print only unique messages, discard duplicates.
 
4789
 
 
4790
 
 
4791
Input file syntax
 
4792
-----------------
 
4793
 
 
4794
`-P'
 
4795
`--properties-input'
 
4796
     Assume the input file is a Java ResourceBundle in Java
 
4797
     `.properties' syntax, not in PO file syntax.
 
4798
 
 
4799
`--stringtable-input'
 
4800
     Assume the input file is a NeXTstep/GNUstep localized resource
 
4801
     file in `.strings' syntax, not in PO file syntax.
 
4802
 
 
4803
 
 
4804
Output details
 
4805
--------------
 
4806
 
 
4807
`-t'
 
4808
`--to-code=NAME'
 
4809
     Specify encoding for output.
 
4810
 
 
4811
`--use-first'
 
4812
     Use first available translation for each message.  Don't merge
 
4813
     several translations into one.
 
4814
 
 
4815
`--force-po'
 
4816
     Always write an output file even if it contains no message.
 
4817
 
 
4818
`-i'
 
4819
`--indent'
 
4820
     Write the .po file using indented style.
 
4821
 
 
4822
`--no-location'
 
4823
     Do not write `#: FILENAME:LINE' lines.
 
4824
 
 
4825
`-n'
 
4826
`--add-location'
 
4827
     Generate `#: FILENAME:LINE' lines (default).
 
4828
 
 
4829
`--strict'
 
4830
     Write out a strict Uniforum conforming PO file.  Note that this
 
4831
     Uniforum format should be avoided because it doesn't support the
 
4832
     GNU extensions.
 
4833
 
 
4834
`-p'
 
4835
`--properties-output'
 
4836
     Write out a Java ResourceBundle in Java `.properties' syntax.  Note
 
4837
     that this file format doesn't support plural forms and silently
 
4838
     drops obsolete messages.
 
4839
 
 
4840
`--stringtable-output'
 
4841
     Write out a NeXTstep/GNUstep localized resource file in `.strings'
 
4842
     syntax.  Note that this file format doesn't support plural forms.
 
4843
 
 
4844
`-w NUMBER'
 
4845
`--width=NUMBER'
 
4846
     Set the output page width.  Long strings in the output files will
 
4847
     be split across multiple lines in order to ensure that each line's
 
4848
     width (= number of screen columns) is less or equal to the given
 
4849
     NUMBER.
 
4850
 
 
4851
`--no-wrap'
 
4852
     Do not break long message lines.  Message lines whose width
 
4853
     exceeds the output page width will not be split into several
 
4854
     lines.  Only file reference lines which are wider than the output
 
4855
     page width will be split.
 
4856
 
 
4857
`-s'
 
4858
`--sort-output'
 
4859
     Generate sorted output.  Note that using this option makes it much
 
4860
     harder for the translator to understand each message's context.
 
4861
 
 
4862
`-F'
 
4863
`--sort-by-file'
 
4864
     Sort output by file location.
 
4865
 
 
4866
 
 
4867
Informative output
 
4868
------------------
 
4869
 
 
4870
`-h'
 
4871
`--help'
 
4872
     Display this help and exit.
 
4873
 
 
4874
`-V'
 
4875
`--version'
 
4876
     Output version information and exit.
 
4877
 
 
4878
 
 
4879
 
 
4880
File: gettext.info,  Node: msgcomm Invocation,  Next: msgcmp Invocation,  Prev: msguniq Invocation,  Up: Manipulating
 
4881
 
 
4882
Invoking the `msgcomm' Program
 
4883
==============================
 
4884
 
 
4885
     msgcomm [OPTION] [INPUTFILE]...
 
4886
 
 
4887
   The `msgcomm' program finds messages which are common to two or more
 
4888
of the specified PO files.  By using the `--more-than' option, greater
 
4889
commonality may be requested before messages are printed.  Conversely,
 
4890
the `--less-than' option may be used to specify less commonality before
 
4891
messages are printed (i.e.  `--less-than=2' will only print the unique
 
4892
messages).  Translations, comments and extract comments will be
 
4893
preserved, but only from the first PO file to define them.  File
 
4894
positions from all PO files will be cumulated.
 
4895
 
 
4896
Input file location
 
4897
-------------------
 
4898
 
 
4899
`INPUTFILE ...'
 
4900
     Input files.
 
4901
 
 
4902
`-f FILE'
 
4903
`--files-from=FILE'
 
4904
     Read the names of the input files from FILE instead of getting
 
4905
     them from the command line.
 
4906
 
 
4907
`-D DIRECTORY'
 
4908
`--directory=DIRECTORY'
 
4909
     Add DIRECTORY to the list of directories.  Source files are
 
4910
     searched relative to this list of directories.  The resulting `.po'
 
4911
     file will be written relative to the current directory, though.
 
4912
 
 
4913
 
 
4914
   If INPUTFILE is `-', standard input is read.
 
4915
 
 
4916
Output file location
 
4917
--------------------
 
4918
 
 
4919
`-o FILE'
 
4920
`--output-file=FILE'
 
4921
     Write output to specified file.
 
4922
 
 
4923
 
 
4924
   The results are written to standard output if no output file is
 
4925
specified or if it is `-'.
 
4926
 
 
4927
Message selection
 
4928
-----------------
 
4929
 
 
4930
`-< NUMBER'
 
4931
`--less-than=NUMBER'
 
4932
     Print messages with less than NUMBER definitions, defaults to
 
4933
     infinite if not set.
 
4934
 
 
4935
`-> NUMBER'
 
4936
`--more-than=NUMBER'
 
4937
     Print messages with more than NUMBER definitions, defaults to 1 if
 
4938
     not set.
 
4939
 
 
4940
`-u'
 
4941
`--unique'
 
4942
     Shorthand for `--less-than=2'.  Requests that only unique messages
 
4943
     be printed.
 
4944
 
 
4945
 
 
4946
Input file syntax
 
4947
-----------------
 
4948
 
 
4949
`-P'
 
4950
`--properties-input'
 
4951
     Assume the input files are Java ResourceBundles in Java
 
4952
     `.properties' syntax, not in PO file syntax.
 
4953
 
 
4954
`--stringtable-input'
 
4955
     Assume the input files are NeXTstep/GNUstep localized resource
 
4956
     files in `.strings' syntax, not in PO file syntax.
 
4957
 
 
4958
 
 
4959
Output details
 
4960
--------------
 
4961
 
 
4962
`--force-po'
 
4963
     Always write an output file even if it contains no message.
 
4964
 
 
4965
`-i'
 
4966
`--indent'
 
4967
     Write the .po file using indented style.
 
4968
 
 
4969
`--no-location'
 
4970
     Do not write `#: FILENAME:LINE' lines.
 
4971
 
 
4972
`-n'
 
4973
`--add-location'
 
4974
     Generate `#: FILENAME:LINE' lines (default).
 
4975
 
 
4976
`--strict'
 
4977
     Write out a strict Uniforum conforming PO file.  Note that this
 
4978
     Uniforum format should be avoided because it doesn't support the
 
4979
     GNU extensions.
 
4980
 
 
4981
`-p'
 
4982
`--properties-output'
 
4983
     Write out a Java ResourceBundle in Java `.properties' syntax.  Note
 
4984
     that this file format doesn't support plural forms and silently
 
4985
     drops obsolete messages.
 
4986
 
 
4987
`--stringtable-output'
 
4988
     Write out a NeXTstep/GNUstep localized resource file in `.strings'
 
4989
     syntax.  Note that this file format doesn't support plural forms.
 
4990
 
 
4991
`-w NUMBER'
 
4992
`--width=NUMBER'
 
4993
     Set the output page width.  Long strings in the output files will
 
4994
     be split across multiple lines in order to ensure that each line's
 
4995
     width (= number of screen columns) is less or equal to the given
 
4996
     NUMBER.
 
4997
 
 
4998
`--no-wrap'
 
4999
     Do not break long message lines.  Message lines whose width
 
5000
     exceeds the output page width will not be split into several
 
5001
     lines.  Only file reference lines which are wider than the output
 
5002
     page width will be split.
 
5003
 
 
5004
`-s'
 
5005
`--sort-output'
 
5006
     Generate sorted output.  Note that using this option makes it much
 
5007
     harder for the translator to understand each message's context.
 
5008
 
 
5009
`-F'
 
5010
`--sort-by-file'
 
5011
     Sort output by file location.
 
5012
 
 
5013
`--omit-header'
 
5014
     Don't write header with `msgid ""' entry.
 
5015
 
 
5016
 
 
5017
Informative output
 
5018
------------------
 
5019
 
 
5020
`-h'
 
5021
`--help'
 
5022
     Display this help and exit.
 
5023
 
 
5024
`-V'
 
5025
`--version'
 
5026
     Output version information and exit.
 
5027
 
 
5028
 
 
5029
 
 
5030
File: gettext.info,  Node: msgcmp Invocation,  Next: msgattrib Invocation,  Prev: msgcomm Invocation,  Up: Manipulating
 
5031
 
 
5032
Invoking the `msgcmp' Program
 
5033
=============================
 
5034
 
 
5035
     msgcmp [OPTION] DEF.po REF.pot
 
5036
 
 
5037
   The `msgcmp' program compares two Uniforum style .po files to check
 
5038
that both contain the same set of msgid strings.  The DEF.po file is an
 
5039
existing PO file with the translations.  The REF.pot file is the last
 
5040
created PO file, or a PO Template file (generally created by
 
5041
`xgettext').  This is useful for checking that you have translated each
 
5042
and every message in your program.  Where an exact match cannot be
 
5043
found, fuzzy matching is used to produce better diagnostics.
 
5044
 
 
5045
Input file location
 
5046
-------------------
 
5047
 
 
5048
`DEF.po'
 
5049
     Translations.
 
5050
 
 
5051
`REF.pot'
 
5052
     References to the sources.
 
5053
 
 
5054
`-D DIRECTORY'
 
5055
`--directory=DIRECTORY'
 
5056
     Add DIRECTORY to the list of directories.  Source files are
 
5057
     searched relative to this list of directories.
 
5058
 
 
5059
 
 
5060
Operation modifiers
 
5061
-------------------
 
5062
 
 
5063
`-m'
 
5064
`--multi-domain'
 
5065
     Apply REF.pot to each of the domains in DEF.po.
 
5066
 
 
5067
 
 
5068
Input file syntax
 
5069
-----------------
 
5070
 
 
5071
`-P'
 
5072
`--properties-input'
 
5073
     Assume the input files are Java ResourceBundles in Java
 
5074
     `.properties' syntax, not in PO file syntax.
 
5075
 
 
5076
`--stringtable-input'
 
5077
     Assume the input files are NeXTstep/GNUstep localized resource
 
5078
     files in `.strings' syntax, not in PO file syntax.
 
5079
 
 
5080
 
 
5081
Informative output
 
5082
------------------
 
5083
 
 
5084
`-h'
 
5085
`--help'
 
5086
     Display this help and exit.
 
5087
 
 
5088
`-V'
 
5089
`--version'
 
5090
     Output version information and exit.
 
5091
 
 
5092
 
 
5093
 
 
5094
File: gettext.info,  Node: msgattrib Invocation,  Next: msgen Invocation,  Prev: msgcmp Invocation,  Up: Manipulating
 
5095
 
 
5096
Invoking the `msgattrib' Program
 
5097
================================
 
5098
 
 
5099
     msgattrib [OPTION] [INPUTFILE]
 
5100
 
 
5101
   The `msgattrib' program filters the messages of a translation catalog
 
5102
according to their attributes, and manipulates the attributes.
 
5103
 
 
5104
Input file location
 
5105
-------------------
 
5106
 
 
5107
`INPUTFILE'
 
5108
     Input PO file.
 
5109
 
 
5110
`-D DIRECTORY'
 
5111
`--directory=DIRECTORY'
 
5112
     Add DIRECTORY to the list of directories.  Source files are
 
5113
     searched relative to this list of directories.  The resulting `.po'
 
5114
     file will be written relative to the current directory, though.
 
5115
 
 
5116
 
 
5117
   If no INPUTFILE is given or if it is `-', standard input is read.
 
5118
 
 
5119
Output file location
 
5120
--------------------
 
5121
 
 
5122
`-o FILE'
 
5123
`--output-file=FILE'
 
5124
     Write output to specified file.
 
5125
 
 
5126
 
 
5127
   The results are written to standard output if no output file is
 
5128
specified or if it is `-'.
 
5129
 
 
5130
Message selection
 
5131
-----------------
 
5132
 
 
5133
`--translated'
 
5134
     Keep translated messages, remove untranslated messages.
 
5135
 
 
5136
`--untranslated'
 
5137
     Keep untranslated messages, remove translated messages.
 
5138
 
 
5139
`--no-fuzzy'
 
5140
     Remove `fuzzy' marked messages.
 
5141
 
 
5142
`--only-fuzzy'
 
5143
     Keep `fuzzy' marked messages, remove all other messsages.
 
5144
 
 
5145
`--no-obsolete'
 
5146
     Remove obsolete #~ messages.
 
5147
 
 
5148
`--only-obsolete'
 
5149
     Keep obsolete #~ messages, remove all other messages.
 
5150
 
 
5151
 
 
5152
Attribute manipulation
 
5153
----------------------
 
5154
 
 
5155
Attributes are modified after the message selection/removal has been
 
5156
performed.  If the `--only-file' or `--ignore-file' option is
 
5157
specified, the attribute modification is applied only to those messages
 
5158
that are listed in the ONLY-FILE and not listed in the IGNORE-FILE.
 
5159
 
 
5160
`--set-fuzzy'
 
5161
     Set all messages `fuzzy'.
 
5162
 
 
5163
`--clear-fuzzy'
 
5164
     Set all messages non-`fuzzy'.
 
5165
 
 
5166
`--set-obsolete'
 
5167
     Set all messages obsolete.
 
5168
 
 
5169
`--clear-obsolete'
 
5170
     Set all messages non-obsolete.
 
5171
 
 
5172
`--only-file=FILE'
 
5173
     Limit the attribute changes to entries that are listed in FILE.
 
5174
     FILE should be a PO or POT file.
 
5175
 
 
5176
`--ignore-file=FILE'
 
5177
     Limit the attribute changes to entries that are not listed in FILE.
 
5178
     FILE should be a PO or POT file.
 
5179
 
 
5180
`--fuzzy'
 
5181
     Synonym for `--only-fuzzy --clear-fuzzy': It keeps only the fuzzy
 
5182
     messages and removes their `fuzzy' mark.
 
5183
 
 
5184
`--obsolete'
 
5185
     Synonym for `--only-obsolete --clear-obsolete': It keeps only the
 
5186
     obsolete messages and makes them non-obsolete.
 
5187
 
 
5188
 
 
5189
Input file syntax
 
5190
-----------------
 
5191
 
 
5192
`-P'
 
5193
`--properties-input'
 
5194
     Assume the input file is a Java ResourceBundle in Java
 
5195
     `.properties' syntax, not in PO file syntax.
 
5196
 
 
5197
`--stringtable-input'
 
5198
     Assume the input file is a NeXTstep/GNUstep localized resource
 
5199
     file in `.strings' syntax, not in PO file syntax.
 
5200
 
 
5201
 
 
5202
Output details
 
5203
--------------
 
5204
 
 
5205
`--force-po'
 
5206
     Always write an output file even if it contains no message.
 
5207
 
 
5208
`-i'
 
5209
`--indent'
 
5210
     Write the .po file using indented style.
 
5211
 
 
5212
`--no-location'
 
5213
     Do not write `#: FILENAME:LINE' lines.
 
5214
 
 
5215
`-n'
 
5216
`--add-location'
 
5217
     Generate `#: FILENAME:LINE' lines (default).
 
5218
 
 
5219
`--strict'
 
5220
     Write out a strict Uniforum conforming PO file.  Note that this
 
5221
     Uniforum format should be avoided because it doesn't support the
 
5222
     GNU extensions.
 
5223
 
 
5224
`-p'
 
5225
`--properties-output'
 
5226
     Write out a Java ResourceBundle in Java `.properties' syntax.  Note
 
5227
     that this file format doesn't support plural forms and silently
 
5228
     drops obsolete messages.
 
5229
 
 
5230
`--stringtable-output'
 
5231
     Write out a NeXTstep/GNUstep localized resource file in `.strings'
 
5232
     syntax.  Note that this file format doesn't support plural forms.
 
5233
 
 
5234
`-w NUMBER'
 
5235
`--width=NUMBER'
 
5236
     Set the output page width.  Long strings in the output files will
 
5237
     be split across multiple lines in order to ensure that each line's
 
5238
     width (= number of screen columns) is less or equal to the given
 
5239
     NUMBER.
 
5240
 
 
5241
`--no-wrap'
 
5242
     Do not break long message lines.  Message lines whose width
 
5243
     exceeds the output page width will not be split into several
 
5244
     lines.  Only file reference lines which are wider than the output
 
5245
     page width will be split.
 
5246
 
 
5247
`-s'
 
5248
`--sort-output'
 
5249
     Generate sorted output.  Note that using this option makes it much
 
5250
     harder for the translator to understand each message's context.
 
5251
 
 
5252
`-F'
 
5253
`--sort-by-file'
 
5254
     Sort output by file location.
 
5255
 
 
5256
 
 
5257
Informative output
 
5258
------------------
 
5259
 
 
5260
`-h'
 
5261
`--help'
 
5262
     Display this help and exit.
 
5263
 
 
5264
`-V'
 
5265
`--version'
 
5266
     Output version information and exit.
 
5267
 
 
5268
 
 
5269
 
 
5270
File: gettext.info,  Node: msgen Invocation,  Next: msgexec Invocation,  Prev: msgattrib Invocation,  Up: Manipulating
 
5271
 
 
5272
Invoking the `msgen' Program
 
5273
============================
 
5274
 
 
5275
     msgen [OPTION] INPUTFILE
 
5276
 
 
5277
   The `msgen' program creates an English translation catalog.  The
 
5278
input file is the last created English PO file, or a PO Template file
 
5279
(generally created by xgettext).  Untranslated entries are assigned a
 
5280
translation that is identical to the msgid.
 
5281
 
 
5282
   Note: `msginit --no-translator --locale=en' performs a very similar
 
5283
task.  The main difference is that `msginit' cares specially about the
 
5284
header entry, whereas `msgen' doesn't.
 
5285
 
 
5286
Input file location
 
5287
-------------------
 
5288
 
 
5289
`INPUTFILE'
 
5290
     Input PO or POT file.
 
5291
 
 
5292
`-D DIRECTORY'
 
5293
`--directory=DIRECTORY'
 
5294
     Add DIRECTORY to the list of directories.  Source files are
 
5295
     searched relative to this list of directories.  The resulting `.po'
 
5296
     file will be written relative to the current directory, though.
 
5297
 
 
5298
 
 
5299
   If INPUTFILE is `-', standard input is read.
 
5300
 
 
5301
Output file location
 
5302
--------------------
 
5303
 
 
5304
`-o FILE'
 
5305
`--output-file=FILE'
 
5306
     Write output to specified file.
 
5307
 
 
5308
 
 
5309
   The results are written to standard output if no output file is
 
5310
specified or if it is `-'.
 
5311
 
 
5312
Input file syntax
 
5313
-----------------
 
5314
 
 
5315
`-P'
 
5316
`--properties-input'
 
5317
     Assume the input file is a Java ResourceBundle in Java
 
5318
     `.properties' syntax, not in PO file syntax.
 
5319
 
 
5320
`--stringtable-input'
 
5321
     Assume the input file is a NeXTstep/GNUstep localized resource
 
5322
     file in `.strings' syntax, not in PO file syntax.
 
5323
 
 
5324
 
 
5325
Output details
 
5326
--------------
 
5327
 
 
5328
`--force-po'
 
5329
     Always write an output file even if it contains no message.
 
5330
 
 
5331
`-i'
 
5332
`--indent'
 
5333
     Write the .po file using indented style.
 
5334
 
 
5335
`--no-location'
 
5336
     Do not write `#: FILENAME:LINE' lines.
 
5337
 
 
5338
`--add-location'
 
5339
     Generate `#: FILENAME:LINE' lines (default).
 
5340
 
 
5341
`--strict'
 
5342
     Write out a strict Uniforum conforming PO file.  Note that this
 
5343
     Uniforum format should be avoided because it doesn't support the
 
5344
     GNU extensions.
 
5345
 
 
5346
`-p'
 
5347
`--properties-output'
 
5348
     Write out a Java ResourceBundle in Java `.properties' syntax.  Note
 
5349
     that this file format doesn't support plural forms and silently
 
5350
     drops obsolete messages.
 
5351
 
 
5352
`--stringtable-output'
 
5353
     Write out a NeXTstep/GNUstep localized resource file in `.strings'
 
5354
     syntax.  Note that this file format doesn't support plural forms.
 
5355
 
 
5356
`-w NUMBER'
 
5357
`--width=NUMBER'
 
5358
     Set the output page width.  Long strings in the output files will
 
5359
     be split across multiple lines in order to ensure that each line's
 
5360
     width (= number of screen columns) is less or equal to the given
 
5361
     NUMBER.
 
5362
 
 
5363
`--no-wrap'
 
5364
     Do not break long message lines.  Message lines whose width
 
5365
     exceeds the output page width will not be split into several
 
5366
     lines.  Only file reference lines which are wider than the output
 
5367
     page width will be split.
 
5368
 
 
5369
`-s'
 
5370
`--sort-output'
 
5371
     Generate sorted output.  Note that using this option makes it much
 
5372
     harder for the translator to understand each message's context.
 
5373
 
 
5374
`-F'
 
5375
`--sort-by-file'
 
5376
     Sort output by file location.
 
5377
 
 
5378
 
 
5379
Informative output
 
5380
------------------
 
5381
 
 
5382
`-h'
 
5383
`--help'
 
5384
     Display this help and exit.
 
5385
 
 
5386
`-V'
 
5387
`--version'
 
5388
     Output version information and exit.
 
5389
 
 
5390
 
 
5391
 
 
5392
File: gettext.info,  Node: msgexec Invocation,  Next: libgettextpo,  Prev: msgen Invocation,  Up: Manipulating
 
5393
 
 
5394
Invoking the `msgexec' Program
 
5395
==============================
 
5396
 
 
5397
     msgexec [OPTION] COMMAND [COMMAND-OPTION]
 
5398
 
 
5399
   The `msgexec' program applies a command to all translations of a
 
5400
translation catalog.  The COMMAND can be any program that reads a
 
5401
translation from standard input.  It is invoked once for each
 
5402
translation.  Its output becomes msgexec's output.  `msgexec''s return
 
5403
code is the maximum return code across all invocations.
 
5404
 
 
5405
   A special builtin command called `0' outputs the translation,
 
5406
followed by a null byte.  The output of `msgexec 0' is suitable as
 
5407
input for `xargs -0'.
 
5408
 
 
5409
   During each COMMAND invocation, the environment variable
 
5410
`MSGEXEC_MSGID' is bound to the message's msgid, and the environment
 
5411
variable `MSGEXEC_LOCATION' is bound to the location in the PO file of
 
5412
the message.
 
5413
 
 
5414
   Note: It is your responsibility to ensure that the COMMAND can cope
 
5415
with input encoded in the translation catalog's encoding.  If the
 
5416
COMMAND wants input in a particular encoding, you can in a first step
 
5417
convert the translation catalog to that encoding using the `msgconv'
 
5418
program, before invoking `msgexec'.  If the COMMAND wants input in the
 
5419
locale's encoding, but you want to avoid the locale's encoding, then
 
5420
you can first convert the translation catalog to UTF-8 using the
 
5421
`msgconv' program and then make `msgexec' work in an UTF-8 locale, by
 
5422
using the `LC_ALL' environment variable.
 
5423
 
 
5424
Input file location
 
5425
-------------------
 
5426
 
 
5427
`-i INPUTFILE'
 
5428
`--input=INPUTFILE'
 
5429
     Input PO file.
 
5430
 
 
5431
`-D DIRECTORY'
 
5432
`--directory=DIRECTORY'
 
5433
     Add DIRECTORY to the list of directories.  Source files are
 
5434
     searched relative to this list of directories.  The resulting `.po'
 
5435
     file will be written relative to the current directory, though.
 
5436
 
 
5437
 
 
5438
   If no INPUTFILE is given or if it is `-', standard input is read.
 
5439
 
 
5440
Input file syntax
 
5441
-----------------
 
5442
 
 
5443
`-P'
 
5444
`--properties-input'
 
5445
     Assume the input file is a Java ResourceBundle in Java
 
5446
     `.properties' syntax, not in PO file syntax.
 
5447
 
 
5448
`--stringtable-input'
 
5449
     Assume the input file is a NeXTstep/GNUstep localized resource
 
5450
     file in `.strings' syntax, not in PO file syntax.
 
5451
 
 
5452
 
 
5453
Informative output
 
5454
------------------
 
5455
 
 
5456
`-h'
 
5457
`--help'
 
5458
     Display this help and exit.
 
5459
 
 
5460
`-V'
 
5461
`--version'
 
5462
     Output version information and exit.
 
5463
 
 
5464
 
 
5465
 
 
5466
File: gettext.info,  Node: libgettextpo,  Prev: msgexec Invocation,  Up: Manipulating
 
5467
 
 
5468
Writing your own programs that process PO files
 
5469
===============================================
 
5470
 
 
5471
For the tasks for which a combination of `msgattrib', `msgcat' etc.  is
 
5472
not sufficient, a set of C functions is provided in a library, to make
 
5473
it possible to process PO files in your own programs.  When you use
 
5474
this library, you don't need to write routines to parse the PO file;
 
5475
instead, you retreive a pointer in memory to each of messages contained
 
5476
in the PO file.  Functions for writing PO files are not provided at
 
5477
this time.
 
5478
 
 
5479
   The functions are declared in the header file `<gettext-po.h>', and
 
5480
are defined in a library called `libgettextpo'.
 
5481
 
 
5482
 - Data Type: po_file_t
 
5483
     This is a pointer type that refers to the contents of a PO file,
 
5484
     after it has been read into memory.
 
5485
 
 
5486
 - Data Type: po_message_iterator_t
 
5487
     This is a pointer type that refers to an iterator that produces a
 
5488
     sequence of messages.
 
5489
 
 
5490
 - Data Type: po_message_t
 
5491
     This is a pointer type that refers to a message of a PO file,
 
5492
     including its translation.
 
5493
 
 
5494
 - Function: po_file_t po_file_read (const char *FILENAME)
 
5495
     The `po_file_read' function reads a PO file into memory.  The file
 
5496
     name is given as argument.  The return value is a handle to the PO
 
5497
     file's contents, valid until `po_file_free' is called on it.  In
 
5498
     case of error, the return value is `NULL', and `errno' is set.
 
5499
 
 
5500
 - Function: void po_file_free (po_file_t FILE)
 
5501
     The `po_file_free' function frees a PO file's contents from memory,
 
5502
     including all messages that are only implicitly accessible through
 
5503
     iterators.
 
5504
 
 
5505
 - Function: const char * const * po_file_domains (po_file_t FILE)
 
5506
     The `po_file_domains' function returns the domains for which the
 
5507
     given PO file has messages.  The return value is a `NULL'
 
5508
     terminated array which is valid as long as the FILE handle is
 
5509
     valid.  For PO files which contain no `domain' directive, the
 
5510
     return value contains only one domain, namely the default domain
 
5511
     `"messages"'.
 
5512
 
 
5513
 - Function: po_message_iterator_t po_message_iterator (po_file_t FILE,
 
5514
          const char *DOMAIN)
 
5515
     The `po_message_iterator' returns an iterator that will produce the
 
5516
     messages of FILE that belong to the given DOMAIN.  If DOMAIN is
 
5517
     `NULL', the default domain is used instead.  To list the messages,
 
5518
     use the function `po_next_message' repeatedly.
 
5519
 
 
5520
 - Function: void po_message_iterator_free (po_message_iterator_t
 
5521
          ITERATOR)
 
5522
     The `po_message_iterator_free' function frees an iterator
 
5523
     previously allocated through the `po_message_iterator' function.
 
5524
 
 
5525
 - Function: po_message_t po_next_message (po_message_iterator_t
 
5526
          ITERATOR)
 
5527
     The `po_next_message' function returns the next message from
 
5528
     ITERATOR and advances the iterator.  It returns `NULL' when the
 
5529
     iterator has reached the end of its message list.
 
5530
 
 
5531
   The following functions returns details of a `po_message_t'.  Recall
 
5532
that the results are valid as long as the FILE handle is valid.
 
5533
 
 
5534
 - Function: const char * po_message_msgid (po_message_t MESSAGE)
 
5535
     The `po_message_msgid' function returns the `msgid' (untranslated
 
5536
     English string) of a message.  This is guaranteed to be non-`NULL'.
 
5537
 
 
5538
 - Function: const char * po_message_msgid_plural (po_message_t MESSAGE)
 
5539
     The `po_message_msgid_plural' function returns the `msgid_plural'
 
5540
     (untranslated English plural string) of a message with plurals, or
 
5541
     `NULL' for a message without plural.
 
5542
 
 
5543
 - Function: const char * po_message_msgstr (po_message_t MESSAGE)
 
5544
     The `po_message_msgstr' function returns the `msgstr' (translation)
 
5545
     of a message.  For an untranslated message, the return value is an
 
5546
     empty string.
 
5547
 
 
5548
 - Function: const char * po_message_msgstr_plural (po_message_t
 
5549
          MESSAGE, int INDEX)
 
5550
     The `po_message_msgstr_plural' function returns the
 
5551
     `msgstr[INDEX]' of a message with plurals, or `NULL' when the
 
5552
     INDEX is out of range or for a message without plural.
 
5553
 
 
5554
   Here is an example code how these functions can be used.
 
5555
 
 
5556
     const char *filename = ...;
 
5557
     po_file_t file = po_file_read (filename);
 
5558
     
 
5559
     if (file == NULL)
 
5560
       error (EXIT_FAILURE, errno, "couldn't open the PO file %s", filename);
 
5561
     {
 
5562
       const char * const *domains = po_file_domains (file);
 
5563
       const char * const *domainp;
 
5564
     
 
5565
       for (domainp = domains; *domainp; domainp++)
 
5566
         {
 
5567
           const char *domain = *domainp;
 
5568
           po_message_iterator_t iterator = po_message_iterator (file, domain);
 
5569
     
 
5570
           for (;;)
 
5571
             {
 
5572
               po_message_t *message = po_next_message (iterator);
 
5573
     
 
5574
               if (message == NULL)
 
5575
                 break;
 
5576
               {
 
5577
                 const char *msgid = po_message_msgid (message);
 
5578
                 const char *msgstr = po_message_msgstr (message);
 
5579
     
 
5580
                 ...
 
5581
               }
 
5582
             }
 
5583
           po_message_iterator_free (iterator);
 
5584
         }
 
5585
     }
 
5586
     po_file_free (file);
 
5587
 
 
5588
 
 
5589
File: gettext.info,  Node: Binaries,  Next: Users,  Prev: Manipulating,  Up: Top
 
5590
 
 
5591
Producing Binary MO Files
 
5592
*************************
 
5593
 
 
5594
* Menu:
 
5595
 
 
5596
* msgfmt Invocation::           Invoking the `msgfmt' Program
 
5597
* msgunfmt Invocation::         Invoking the `msgunfmt' Program
 
5598
* MO Files::                    The Format of GNU MO Files
 
5599
 
 
5600
 
 
5601
File: gettext.info,  Node: msgfmt Invocation,  Next: msgunfmt Invocation,  Prev: Binaries,  Up: Binaries
 
5602
 
 
5603
Invoking the `msgfmt' Program
 
5604
=============================
 
5605
 
 
5606
     msgfmt [OPTION] FILENAME.po ...
 
5607
 
 
5608
   The `msgfmt' programs generates a binary message catalog from a
 
5609
textual translation description.
 
5610
 
 
5611
Input file location
 
5612
-------------------
 
5613
 
 
5614
`FILENAME.po ...'
 
5615
 
 
5616
`-D DIRECTORY'
 
5617
`--directory=DIRECTORY'
 
5618
     Add DIRECTORY to the list of directories.  Source files are
 
5619
     searched relative to this list of directories.  The resulting `.po'
 
5620
     file will be written relative to the current directory, though.
 
5621
 
 
5622
 
 
5623
   If an input file is `-', standard input is read.
 
5624
 
 
5625
Operation mode
 
5626
--------------
 
5627
 
 
5628
`-j'
 
5629
`--java'
 
5630
     Java mode: generate a Java `ResourceBundle' class.
 
5631
 
 
5632
`--java2'
 
5633
     Like -java, and assume Java2 (JDK 1.2 or higher).
 
5634
 
 
5635
`--csharp'
 
5636
     C# mode: generate a .NET .dll file containing a subclass of
 
5637
     `GettextResourceSet'.
 
5638
 
 
5639
`--csharp-resources'
 
5640
     C# resources mode: generate a .NET `.resources' file.
 
5641
 
 
5642
`--tcl'
 
5643
     Tcl mode: generate a tcl/msgcat `.msg' file.
 
5644
 
 
5645
`--qt'
 
5646
     Qt mode: generate a Qt `.qm' file.
 
5647
 
 
5648
 
 
5649
Output file location
 
5650
--------------------
 
5651
 
 
5652
`-o FILE'
 
5653
`--output-file=FILE'
 
5654
     Write output to specified file.
 
5655
 
 
5656
`--strict'
 
5657
     Direct the program to work strictly following the Uniforum/Sun
 
5658
     implementation.  Currently this only affects the naming of the
 
5659
     output file.  If this option is not given the name of the output
 
5660
     file is the same as the domain name.  If the strict Uniforum mode
 
5661
     is enabled the suffix `.mo' is added to the file name if it is not
 
5662
     already present.
 
5663
 
 
5664
     We find this behaviour of Sun's implementation rather silly and so
 
5665
     by default this mode is _not_ selected.
 
5666
 
 
5667
 
 
5668
   If the output FILE is `-', output is written to standard output.
 
5669
 
 
5670
Output file location in Java mode
 
5671
---------------------------------
 
5672
 
 
5673
`-r RESOURCE'
 
5674
`--resource=RESOURCE'
 
5675
     Specify the resource name.
 
5676
 
 
5677
`-l LOCALE'
 
5678
`--locale=LOCALE'
 
5679
     Specify the locale name, either a language specification of the
 
5680
     form LL or a combined language and country specification of the
 
5681
     form LL_CC.
 
5682
 
 
5683
`-d DIRECTORY'
 
5684
     Specify the base directory of classes directory hierarchy.
 
5685
 
 
5686
 
 
5687
   The class name is determined by appending the locale name to the
 
5688
resource name, separated with an underscore.  The `-d' option is
 
5689
mandatory.  The class is written under the specified directory.
 
5690
 
 
5691
Output file location in C# mode
 
5692
-------------------------------
 
5693
 
 
5694
`-r RESOURCE'
 
5695
`--resource=RESOURCE'
 
5696
     Specify the resource name.
 
5697
 
 
5698
`-l LOCALE'
 
5699
`--locale=LOCALE'
 
5700
     Specify the locale name, either a language specification of the
 
5701
     form LL or a combined language and country specification of the
 
5702
     form LL_CC.
 
5703
 
 
5704
`-d DIRECTORY'
 
5705
     Specify the base directory for locale dependent `.dll' files.
 
5706
 
 
5707
 
 
5708
   The `-l' and `-d' options are mandatory.  The `.dll' file is written
 
5709
in a subdirectory of the specified directory whose name depends on the
 
5710
locale.
 
5711
 
 
5712
Output file location in Tcl mode
 
5713
--------------------------------
 
5714
 
 
5715
`-l LOCALE'
 
5716
`--locale=LOCALE'
 
5717
     Specify the locale name, either a language specification of the
 
5718
     form LL or a combined language and country specification of the
 
5719
     form LL_CC.
 
5720
 
 
5721
`-d DIRECTORY'
 
5722
     Specify the base directory of `.msg' message catalogs.
 
5723
 
 
5724
 
 
5725
   The `-l' and `-d' options are mandatory.  The `.msg' file is written
 
5726
in the specified directory.
 
5727
 
 
5728
Input file syntax
 
5729
-----------------
 
5730
 
 
5731
`-P'
 
5732
`--properties-input'
 
5733
     Assume the input files are Java ResourceBundles in Java
 
5734
     `.properties' syntax, not in PO file syntax.
 
5735
 
 
5736
`--stringtable-input'
 
5737
     Assume the input files are NeXTstep/GNUstep localized resource
 
5738
     files in `.strings' syntax, not in PO file syntax.
 
5739
 
 
5740
 
 
5741
Input file interpretation
 
5742
-------------------------
 
5743
 
 
5744
`-c'
 
5745
`--check'
 
5746
     Perform all the checks implied by `--check-format',
 
5747
     `--check-header', `--check-domain'.
 
5748
 
 
5749
`--check-format'
 
5750
     Check language dependent format strings.
 
5751
 
 
5752
     If the string represents a format string used in a `printf'-like
 
5753
     function both strings should have the same number of `%' format
 
5754
     specifiers, with matching types.  If the flag `c-format' or
 
5755
     `possible-c-format' appears in the special comment <#,> for this
 
5756
     entry a check is performed.  For example, the check will diagnose
 
5757
     using `%.*s' against `%s', or `%d' against `%s', or `%d' against
 
5758
     `%x'.  It can even handle positional parameters.
 
5759
 
 
5760
     Normally the `xgettext' program automatically decides whether a
 
5761
     string is a format string or not.  This algorithm is not perfect,
 
5762
     though.  It might regard a string as a format string though it is
 
5763
     not used in a `printf'-like function and so `msgfmt' might report
 
5764
     errors where there are none.
 
5765
 
 
5766
     To solve this problem the programmer can dictate the decision to
 
5767
     the `xgettext' program (*note c-format::).  The translator should
 
5768
     not consider removing the flag from the <#,> line.  This "fix"
 
5769
     would be reversed again as soon as `msgmerge' is called the next
 
5770
     time.
 
5771
 
 
5772
`--check-header'
 
5773
     Verify presence and contents of the header entry.  *Note Header
 
5774
     Entry::, for a description of the various fields in the header
 
5775
     entry.
 
5776
 
 
5777
`--check-domain'
 
5778
     Check for conflicts between domain directives and the
 
5779
     `--output-file' option
 
5780
 
 
5781
`-C'
 
5782
`--check-compatibility'
 
5783
     Check that GNU msgfmt behaves like X/Open msgfmt.  This will give
 
5784
     an error when attempting to use the GNU extensions.
 
5785
 
 
5786
`--check-accelerators[=CHAR]'
 
5787
     Check presence of keyboard accelerators for menu items.  This is
 
5788
     based on the convention used in some GUIs that a keyboard
 
5789
     accelerator in a menu item string is designated by an immediately
 
5790
     preceding `&' character.  Sometimes a keyboard accelerator is also
 
5791
     called "keyboard mnemonic".  This check verifies that if the
 
5792
     untranslated string has exactly one `&' character, the translated
 
5793
     string has exactly one `&' as well.  If this option is given with
 
5794
     a CHAR argument, this CHAR should be a non-alphanumeric character
 
5795
     and is used as keyboard acceleator mark instead of `&'.
 
5796
 
 
5797
`-f'
 
5798
`--use-fuzzy'
 
5799
     Use fuzzy entries in output.  Note that using this option is
 
5800
     usually wrong, because fuzzy messages are exactly those which have
 
5801
     not been validated by a human translator.
 
5802
 
 
5803
 
 
5804
Output details
 
5805
--------------
 
5806
 
 
5807
`-a NUMBER'
 
5808
`--alignment=NUMBER'
 
5809
     Align strings to NUMBER bytes (default: 1).
 
5810
 
 
5811
`--no-hash'
 
5812
     Don't include a hash table in the binary file.  Lookup will be
 
5813
     more expensive at run time (binary search instead of hash table
 
5814
     lookup).
 
5815
 
 
5816
 
 
5817
Informative output
 
5818
------------------
 
5819
 
 
5820
`-h'
 
5821
`--help'
 
5822
     Display this help and exit.
 
5823
 
 
5824
`-V'
 
5825
`--version'
 
5826
     Output version information and exit.
 
5827
 
 
5828
`--statistics'
 
5829
     Print statistics about translations.
 
5830
 
 
5831
`-v'
 
5832
`--verbose'
 
5833
     Increase verbosity level.
 
5834
 
 
5835
 
 
5836
 
 
5837
File: gettext.info,  Node: msgunfmt Invocation,  Next: MO Files,  Prev: msgfmt Invocation,  Up: Binaries
 
5838
 
 
5839
Invoking the `msgunfmt' Program
 
5840
===============================
 
5841
 
 
5842
     msgunfmt [OPTION] [FILE]...
 
5843
 
 
5844
   The `msgunfmt' program converts a binary message catalog to a
 
5845
Uniforum style .po file.
 
5846
 
 
5847
Operation mode
 
5848
--------------
 
5849
 
 
5850
`-j'
 
5851
`--java'
 
5852
     Java mode: input is a Java `ResourceBundle' class.
 
5853
 
 
5854
`--csharp'
 
5855
     C# mode: input is a .NET .dll file containing a subclass of
 
5856
     `GettextResourceSet'.
 
5857
 
 
5858
`--csharp-resources'
 
5859
     C# resources mode: input is a .NET `.resources' file.
 
5860
 
 
5861
`--tcl'
 
5862
     Tcl mode: input is a tcl/msgcat `.msg' file.
 
5863
 
 
5864
 
 
5865
Input file location
 
5866
-------------------
 
5867
 
 
5868
`FILE ...'
 
5869
     Input .mo files.
 
5870
 
 
5871
 
 
5872
   If no input FILE is given or if it is `-', standard input is read.
 
5873
 
 
5874
Input file location in Java mode
 
5875
--------------------------------
 
5876
 
 
5877
`-r RESOURCE'
 
5878
`--resource=RESOURCE'
 
5879
     Specify the resource name.
 
5880
 
 
5881
`-l LOCALE'
 
5882
`--locale=LOCALE'
 
5883
     Specify the locale name, either a language specification of the
 
5884
     form LL or a combined language and country specification of the
 
5885
     form LL_CC.
 
5886
 
 
5887
 
 
5888
   The class name is determined by appending the locale name to the
 
5889
resource name, separated with an underscore.  The class is located
 
5890
using the `CLASSPATH'.
 
5891
 
 
5892
Input file location in C# mode
 
5893
------------------------------
 
5894
 
 
5895
`-r RESOURCE'
 
5896
`--resource=RESOURCE'
 
5897
     Specify the resource name.
 
5898
 
 
5899
`-l LOCALE'
 
5900
`--locale=LOCALE'
 
5901
     Specify the locale name, either a language specification of the
 
5902
     form LL or a combined language and country specification of the
 
5903
     form LL_CC.
 
5904
 
 
5905
`-d DIRECTORY'
 
5906
     Specify the base directory for locale dependent `.dll' files.
 
5907
 
 
5908
 
 
5909
   The `-l' and `-d' options are mandatory.  The `.msg' file is located
 
5910
in a subdirectory of the specified directory whose name depends on the
 
5911
locale.
 
5912
 
 
5913
Input file location in Tcl mode
 
5914
-------------------------------
 
5915
 
 
5916
`-l LOCALE'
 
5917
`--locale=LOCALE'
 
5918
     Specify the locale name, either a language specification of the
 
5919
     form LL or a combined language and country specification of the
 
5920
     form LL_CC.
 
5921
 
 
5922
`-d DIRECTORY'
 
5923
     Specify the base directory of `.msg' message catalogs.
 
5924
 
 
5925
 
 
5926
   The `-l' and `-d' options are mandatory.  The `.msg' file is located
 
5927
in the specified directory.
 
5928
 
 
5929
Output file location
 
5930
--------------------
 
5931
 
 
5932
`-o FILE'
 
5933
`--output-file=FILE'
 
5934
     Write output to specified file.
 
5935
 
 
5936
 
 
5937
   The results are written to standard output if no output file is
 
5938
specified or if it is `-'.
 
5939
 
 
5940
Output details
 
5941
--------------
 
5942
 
 
5943
`--force-po'
 
5944
     Always write an output file even if it contains no message.
 
5945
 
 
5946
`-i'
 
5947
`--indent'
 
5948
     Write the .po file using indented style.
 
5949
 
 
5950
`--strict'
 
5951
     Write out a strict Uniforum conforming PO file.  Note that this
 
5952
     Uniforum format should be avoided because it doesn't support the
 
5953
     GNU extensions.
 
5954
 
 
5955
`-p'
 
5956
`--properties-output'
 
5957
     Write out a Java ResourceBundle in Java `.properties' syntax.  Note
 
5958
     that this file format doesn't support plural forms and silently
 
5959
     drops obsolete messages.
 
5960
 
 
5961
`--stringtable-output'
 
5962
     Write out a NeXTstep/GNUstep localized resource file in `.strings'
 
5963
     syntax.  Note that this file format doesn't support plural forms.
 
5964
 
 
5965
`-w NUMBER'
 
5966
`--width=NUMBER'
 
5967
     Set the output page width.  Long strings in the output files will
 
5968
     be split across multiple lines in order to ensure that each line's
 
5969
     width (= number of screen columns) is less or equal to the given
 
5970
     NUMBER.
 
5971
 
 
5972
`--no-wrap'
 
5973
     Do not break long message lines.  Message lines whose width
 
5974
     exceeds the output page width will not be split into several
 
5975
     lines.  Only file reference lines which are wider than the output
 
5976
     page width will be split.
 
5977
 
 
5978
`-s'
 
5979
`--sort-output'
 
5980
     Generate sorted output.  Note that using this option makes it much
 
5981
     harder for the translator to understand each message's context.
 
5982
 
 
5983
 
 
5984
Informative output
 
5985
------------------
 
5986
 
 
5987
`-h'
 
5988
`--help'
 
5989
     Display this help and exit.
 
5990
 
 
5991
`-V'
 
5992
`--version'
 
5993
     Output version information and exit.
 
5994
 
 
5995
`-v'
 
5996
`--verbose'
 
5997
     Increase verbosity level.
 
5998
 
 
5999
 
 
6000
 
 
6001
File: gettext.info,  Node: MO Files,  Prev: msgunfmt Invocation,  Up: Binaries
 
6002
 
 
6003
The Format of GNU MO Files
 
6004
==========================
 
6005
 
 
6006
The format of the generated MO files is best described by a picture,
 
6007
which appears below.
 
6008
 
 
6009
   The first two words serve the identification of the file.  The magic
 
6010
number will always signal GNU MO files.  The number is stored in the
 
6011
byte order of the generating machine, so the magic number really is two
 
6012
numbers: `0x950412de' and `0xde120495'.  The second word describes the
 
6013
current revision of the file format.  For now the revision is 0.  This
 
6014
might change in future versions, and ensures that the readers of MO
 
6015
files can distinguish new formats from old ones, so that both can be
 
6016
handled correctly.  The version is kept separate from the magic number,
 
6017
instead of using different magic numbers for different formats, mainly
 
6018
because `/etc/magic' is not updated often.  It might be better to have
 
6019
magic separated from internal format version identification.
 
6020
 
 
6021
   Follow a number of pointers to later tables in the file, allowing
 
6022
for the extension of the prefix part of MO files without having to
 
6023
recompile programs reading them.  This might become useful for later
 
6024
inserting a few flag bits, indication about the charset used, new
 
6025
tables, or other things.
 
6026
 
 
6027
   Then, at offset O and offset T in the picture, two tables of string
 
6028
descriptors can be found.  In both tables, each string descriptor uses
 
6029
two 32 bits integers, one for the string length, another for the offset
 
6030
of the string in the MO file, counting in bytes from the start of the
 
6031
file.  The first table contains descriptors for the original strings,
 
6032
and is sorted so the original strings are in increasing lexicographical
 
6033
order.  The second table contains descriptors for the translated
 
6034
strings, and is parallel to the first table: to find the corresponding
 
6035
translation one has to access the array slot in the second array with
 
6036
the same index.
 
6037
 
 
6038
   Having the original strings sorted enables the use of simple binary
 
6039
search, for when the MO file does not contain an hashing table, or for
 
6040
when it is not practical to use the hashing table provided in the MO
 
6041
file.  This also has another advantage, as the empty string in a PO
 
6042
file GNU `gettext' is usually _translated_ into some system information
 
6043
attached to that particular MO file, and the empty string necessarily
 
6044
becomes the first in both the original and translated tables, making
 
6045
the system information very easy to find.
 
6046
 
 
6047
   The size S of the hash table can be zero.  In this case, the hash
 
6048
table itself is not contained in the MO file.  Some people might prefer
 
6049
this because a precomputed hashing table takes disk space, and does not
 
6050
win _that_ much speed.  The hash table contains indices to the sorted
 
6051
array of strings in the MO file.  Conflict resolution is done by double
 
6052
hashing.  The precise hashing algorithm used is fairly dependent on GNU
 
6053
`gettext' code, and is not documented here.
 
6054
 
 
6055
   As for the strings themselves, they follow the hash file, and each
 
6056
is terminated with a <NUL>, and this <NUL> is not counted in the length
 
6057
which appears in the string descriptor.  The `msgfmt' program has an
 
6058
option selecting the alignment for MO file strings.  With this option,
 
6059
each string is separately aligned so it starts at an offset which is a
 
6060
multiple of the alignment value.  On some RISC machines, a correct
 
6061
alignment will speed things up.
 
6062
 
 
6063
   Plural forms are stored by letting the plural of the original string
 
6064
follow the singular of the original string, separated through a <NUL>
 
6065
byte.  The length which appears in the string descriptor includes both.
 
6066
However, only the singular of the original string takes part in the
 
6067
hash table lookup.  The plural variants of the translation are all
 
6068
stored consecutively, separated through a <NUL> byte.  Here also, the
 
6069
length in the string descriptor includes all of them.
 
6070
 
 
6071
   Nothing prevents a MO file from having embedded <NUL>s in strings.
 
6072
However, the program interface currently used already presumes that
 
6073
strings are <NUL> terminated, so embedded <NUL>s are somewhat useless.
 
6074
But the MO file format is general enough so other interfaces would be
 
6075
later possible, if for example, we ever want to implement wide
 
6076
characters right in MO files, where <NUL> bytes may accidently appear.
 
6077
(No, we don't want to have wide characters in MO files.  They would
 
6078
make the file unnecessarily large, and the `wchar_t' type being
 
6079
platform dependent, MO files would be platform dependent as well.)
 
6080
 
 
6081
   This particular issue has been strongly debated in the GNU `gettext'
 
6082
development forum, and it is expectable that MO file format will evolve
 
6083
or change over time.  It is even possible that many formats may later
 
6084
be supported concurrently.  But surely, we have to start somewhere, and
 
6085
the MO file format described here is a good start.  Nothing is cast in
 
6086
concrete, and the format may later evolve fairly easily, so we should
 
6087
feel comfortable with the current approach.
 
6088
 
 
6089
             byte
 
6090
                  +------------------------------------------+
 
6091
               0  | magic number = 0x950412de                |
 
6092
                  |                                          |
 
6093
               4  | file format revision = 0                 |
 
6094
                  |                                          |
 
6095
               8  | number of strings                        |  == N
 
6096
                  |                                          |
 
6097
              12  | offset of table with original strings    |  == O
 
6098
                  |                                          |
 
6099
              16  | offset of table with translation strings |  == T
 
6100
                  |                                          |
 
6101
              20  | size of hashing table                    |  == S
 
6102
                  |                                          |
 
6103
              24  | offset of hashing table                  |  == H
 
6104
                  |                                          |
 
6105
                  .                                          .
 
6106
                  .    (possibly more entries later)         .
 
6107
                  .                                          .
 
6108
                  |                                          |
 
6109
               O  | length & offset 0th string  ----------------.
 
6110
           O + 8  | length & offset 1st string  ------------------.
 
6111
                   ...                                    ...   | |
 
6112
     O + ((N-1)*8)| length & offset (N-1)th string           |  | |
 
6113
                  |                                          |  | |
 
6114
               T  | length & offset 0th translation  ---------------.
 
6115
           T + 8  | length & offset 1st translation  -----------------.
 
6116
                   ...                                    ...   | | | |
 
6117
     T + ((N-1)*8)| length & offset (N-1)th translation      |  | | | |
 
6118
                  |                                          |  | | | |
 
6119
               H  | start hash table                         |  | | | |
 
6120
                   ...                                    ...   | | | |
 
6121
       H + S * 4  | end hash table                           |  | | | |
 
6122
                  |                                          |  | | | |
 
6123
                  | NUL terminated 0th string  <----------------' | | |
 
6124
                  |                                          |    | | |
 
6125
                  | NUL terminated 1st string  <------------------' | |
 
6126
                  |                                          |      | |
 
6127
                   ...                                    ...       | |
 
6128
                  |                                          |      | |
 
6129
                  | NUL terminated 0th translation  <---------------' |
 
6130
                  |                                          |        |
 
6131
                  | NUL terminated 1st translation  <-----------------'
 
6132
                  |                                          |
 
6133
                   ...                                    ...
 
6134
                  |                                          |
 
6135
                  +------------------------------------------+
 
6136
 
 
6137
 
 
6138
File: gettext.info,  Node: Users,  Next: Programmers,  Prev: Binaries,  Up: Top
 
6139
 
 
6140
The User's View
 
6141
***************
 
6142
 
 
6143
When GNU `gettext' will truly have reached its goal, average users
 
6144
should feel some kind of astonished pleasure, seeing the effect of that
 
6145
strange kind of magic that just makes their own native language appear
 
6146
everywhere on their screens.  As for naive users, they would ideally
 
6147
have no special pleasure about it, merely taking their own language for
 
6148
_granted_, and becoming rather unhappy otherwise.
 
6149
 
 
6150
   So, let's try to describe here how we would like the magic to
 
6151
operate, as we want the users' view to be the simplest, among all ways
 
6152
one could look at GNU `gettext'.  All other software engineers:
 
6153
programmers, translators, maintainers, should work together in such a
 
6154
way that the magic becomes possible.  This is a long and progressive
 
6155
undertaking, and information is available about the progress of the
 
6156
Translation Project.
 
6157
 
 
6158
   When a package is distributed, there are two kinds of users:
 
6159
"installers" who fetch the distribution, unpack it, configure it,
 
6160
compile it and install it for themselves or others to use; and "end
 
6161
users" that call programs of the package, once these have been
 
6162
installed at their site.  GNU `gettext' is offering magic for both
 
6163
installers and end users.
 
6164
 
 
6165
* Menu:
 
6166
 
 
6167
* Matrix::                      The Current `ABOUT-NLS' Matrix
 
6168
* Installers::                  Magic for Installers
 
6169
* End Users::                   Magic for End Users
 
6170
 
 
6171
 
 
6172
File: gettext.info,  Node: Matrix,  Next: Installers,  Prev: Users,  Up: Users
 
6173
 
 
6174
The Current `ABOUT-NLS' Matrix
 
6175
==============================
 
6176
 
 
6177
Languages are not equally supported in all packages using GNU
 
6178
`gettext'.  To know if some package uses GNU `gettext', one may check
 
6179
the distribution for the `ABOUT-NLS' information file, for some `LL.po'
 
6180
files, often kept together into some `po/' directory, or for an `intl/'
 
6181
directory.  Internationalized packages have usually many `LL.po' files,
 
6182
where LL represents the language.  *Note End Users:: for a complete
 
6183
description of the format for LL.
 
6184
 
 
6185
   More generally, a matrix is available for showing the current state
 
6186
of the Translation Project, listing which packages are prepared for
 
6187
multi-lingual messages, and which languages are supported by each.
 
6188
Because this information changes often, this matrix is not kept within
 
6189
this GNU `gettext' manual.  This information is often found in file
 
6190
`ABOUT-NLS' from various distributions, but is also as old as the
 
6191
distribution itself.  A recent copy of this `ABOUT-NLS' file,
 
6192
containing up-to-date information, should generally be found on the
 
6193
Translation Project sites, and also on most GNU archive sites.
 
6194
 
 
6195
 
 
6196
File: gettext.info,  Node: Installers,  Next: End Users,  Prev: Matrix,  Up: Users
 
6197
 
 
6198
Magic for Installers
 
6199
====================
 
6200
 
 
6201
By default, packages fully using GNU `gettext', internally, are
 
6202
installed in such a way that they to allow translation of messages.  At
 
6203
_configuration_ time, those packages should automatically detect
 
6204
whether the underlying host system already provides the GNU `gettext'
 
6205
functions.  If not, the GNU `gettext' library should be automatically
 
6206
prepared and used.  Installers may use special options at configuration
 
6207
time for changing this behavior.  The command `./configure
 
6208
--with-included-gettext' bypasses system `gettext' to use the included
 
6209
GNU `gettext' instead, while `./configure --disable-nls' produces
 
6210
programs totally unable to translate messages.
 
6211
 
 
6212
   Internationalized packages have usually many `LL.po' files.  Unless
 
6213
translations are disabled, all those available are installed together
 
6214
with the package.  However, the environment variable `LINGUAS' may be
 
6215
set, prior to configuration, to limit the installed set.  `LINGUAS'
 
6216
should then contain a space separated list of two-letter codes, stating
 
6217
which languages are allowed.
 
6218
 
 
6219
 
 
6220
File: gettext.info,  Node: End Users,  Prev: Installers,  Up: Users
 
6221
 
 
6222
Magic for End Users
 
6223
===================
 
6224
 
 
6225
We consider here those packages using GNU `gettext' internally, and for
 
6226
which the installers did not disable translation at _configure_ time.
 
6227
Then, users only have to set the `LANG' environment variable to the
 
6228
appropriate `LL_CC' combination prior to using the programs in the
 
6229
package.  *Note Matrix::.  For example, let's presume a German site.
 
6230
At the shell prompt, users merely have to execute `setenv LANG de_DE'
 
6231
(in `csh') or `export LANG; LANG=de_DE' (in `sh').  They could even do
 
6232
this from their `.login' or `.profile' file.
 
6233
 
 
6234
 
 
6235
File: gettext.info,  Node: Programmers,  Next: Translators,  Prev: Users,  Up: Top
 
6236
 
 
6237
The Programmer's View
 
6238
*********************
 
6239
 
 
6240
One aim of the current message catalog implementation provided by GNU
 
6241
`gettext' was to use the system's message catalog handling, if the
 
6242
installer wishes to do so.  So we perhaps should first take a look at
 
6243
the solutions we know about.  The people in the POSIX committee did not
 
6244
manage to agree on one of the semi-official standards which we'll
 
6245
describe below.  In fact they couldn't agree on anything, so they
 
6246
decided only to include an example of an interface.  The major Unix
 
6247
vendors are split in the usage of the two most important
 
6248
specifications: X/Open's catgets vs. Uniforum's gettext interface.
 
6249
We'll describe them both and later explain our solution of this dilemma.
 
6250
 
 
6251
* Menu:
 
6252
 
 
6253
* catgets::                     About `catgets'
 
6254
* gettext::                     About `gettext'
 
6255
* Comparison::                  Comparing the two interfaces
 
6256
* Using libintl.a::             Using libintl.a in own programs
 
6257
* gettext grok::                Being a `gettext' grok
 
6258
* Temp Programmers::            Temporary Notes for the Programmers Chapter
 
6259
 
 
6260
 
 
6261
File: gettext.info,  Node: catgets,  Next: gettext,  Prev: Programmers,  Up: Programmers
 
6262
 
 
6263
About `catgets'
 
6264
===============
 
6265
 
 
6266
The `catgets' implementation is defined in the X/Open Portability
 
6267
Guide, Volume 3, XSI Supplementary Definitions, Chapter 5.  But the
 
6268
process of creating this standard seemed to be too slow for some of the
 
6269
Unix vendors so they created their implementations on preliminary
 
6270
versions of the standard.  Of course this leads again to problems while
 
6271
writing platform independent programs: even the usage of `catgets' does
 
6272
not guarantee a unique interface.
 
6273
 
 
6274
   Another, personal comment on this that only a bunch of committee
 
6275
members could have made this interface.  They never really tried to
 
6276
program using this interface.  It is a fast, memory-saving
 
6277
implementation, an user can happily live with it.  But programmers hate
 
6278
it (at least I and some others do...)
 
6279
 
 
6280
   But we must not forget one point: after all the trouble with
 
6281
transfering the rights on Unix(tm) they at last came to X/Open, the
 
6282
very same who published this specification.  This leads me to making
 
6283
the prediction that this interface will be in future Unix standards
 
6284
(e.g. Spec1170) and therefore part of all Unix implementation
 
6285
(implementations, which are _allowed_ to wear this name).
 
6286
 
 
6287
* Menu:
 
6288
 
 
6289
* Interface to catgets::        The interface
 
6290
* Problems with catgets::       Problems with the `catgets' interface?!
 
6291
 
 
6292
 
 
6293
File: gettext.info,  Node: Interface to catgets,  Next: Problems with catgets,  Prev: catgets,  Up: catgets
 
6294
 
 
6295
The Interface
 
6296
-------------
 
6297
 
 
6298
The interface to the `catgets' implementation consists of three
 
6299
functions which correspond to those used in file access: `catopen' to
 
6300
open the catalog for using, `catgets' for accessing the message tables,
 
6301
and `catclose' for closing after work is done.  Prototypes for the
 
6302
functions and the needed definitions are in the `<nl_types.h>' header
 
6303
file.
 
6304
 
 
6305
   `catopen' is used like in this:
 
6306
 
 
6307
     nl_catd catd = catopen ("catalog_name", 0);
 
6308
 
 
6309
   The function takes as the argument the name of the catalog.  This
 
6310
usual refers to the name of the program or the package.  The second
 
6311
parameter is not further specified in the standard.  I don't even know
 
6312
whether it is implemented consistently among various systems.  So the
 
6313
common advice is to use `0' as the value.  The return value is a handle
 
6314
to the message catalog, equivalent to handles to file returned by
 
6315
`open'.
 
6316
 
 
6317
   This handle is of course used in the `catgets' function which can be
 
6318
used like this:
 
6319
 
 
6320
     char *translation = catgets (catd, set_no, msg_id, "original string");
 
6321
 
 
6322
   The first parameter is this catalog descriptor.  The second parameter
 
6323
specifies the set of messages in this catalog, in which the message
 
6324
described by `msg_id' is obtained.  `catgets' therefore uses a
 
6325
three-stage addressing:
 
6326
 
 
6327
     catalog name => set number => message ID => translation
 
6328
 
 
6329
   The fourth argument is not used to address the translation.  It is
 
6330
given as a default value in case when one of the addressing stages
 
6331
fail.  One important thing to remember is that although the return type
 
6332
of catgets is `char *' the resulting string _must not_ be changed.  It
 
6333
should better be `const char *', but the standard is published in 1988,
 
6334
one year before ANSI C.
 
6335
 
 
6336
The last of these functions is used and behaves as expected:
 
6337
 
 
6338
     catclose (catd);
 
6339
 
 
6340
   After this no `catgets' call using the descriptor is legal anymore.
 
6341
 
 
6342
 
 
6343
File: gettext.info,  Node: Problems with catgets,  Prev: Interface to catgets,  Up: catgets
 
6344
 
 
6345
Problems with the `catgets' Interface?!
 
6346
---------------------------------------
 
6347
 
 
6348
Now that this description seemed to be really easy -- where are the
 
6349
problems we speak of?  In fact the interface could be used in a
 
6350
reasonable way, but constructing the message catalogs is a pain.  The
 
6351
reason for this lies in the third argument of `catgets': the unique
 
6352
message ID.  This has to be a numeric value for all messages in a single
 
6353
set.  Perhaps you could imagine the problems keeping such a list while
 
6354
changing the source code.  Add a new message here, remove one there.  Of
 
6355
course there have been developed a lot of tools helping to organize this
 
6356
chaos but one as the other fails in one aspect or the other.  We don't
 
6357
want to say that the other approach has no problems but they are far
 
6358
more easy to manage.
 
6359
 
 
6360
 
 
6361
File: gettext.info,  Node: gettext,  Next: Comparison,  Prev: catgets,  Up: Programmers
 
6362
 
 
6363
About `gettext'
 
6364
===============
 
6365
 
 
6366
The definition of the `gettext' interface comes from a Uniforum
 
6367
proposal.  It was submitted there by Sun, who had implemented the
 
6368
`gettext' function in SunOS 4, around 1990.  Nowadays, the `gettext'
 
6369
interface is specified by the OpenI18N standard.
 
6370
 
 
6371
   The main point about this solution is that it does not follow the
 
6372
method of normal file handling (open-use-close) and that it does not
 
6373
burden the programmer with so many tasks, especially the unique key
 
6374
handling.  Of course here also a unique key is needed, but this key is
 
6375
the message itself (how long or short it is).  See *Note Comparison::
 
6376
for a more detailed comparison of the two methods.
 
6377
 
 
6378
   The following section contains a rather detailed description of the
 
6379
interface.  We make it that detailed because this is the interface we
 
6380
chose for the GNU `gettext' Library.  Programmers interested in using
 
6381
this library will be interested in this description.
 
6382
 
 
6383
* Menu:
 
6384
 
 
6385
* Interface to gettext::        The interface
 
6386
* Ambiguities::                 Solving ambiguities
 
6387
* Locating Catalogs::           Locating message catalog files
 
6388
* Charset conversion::          How to request conversion to Unicode
 
6389
* Plural forms::                Additional functions for handling plurals
 
6390
* GUI program problems::        Another technique for solving ambiguities
 
6391
* Optimized gettext::           Optimization of the *gettext functions
 
6392
 
 
6393
 
 
6394
File: gettext.info,  Node: Interface to gettext,  Next: Ambiguities,  Prev: gettext,  Up: gettext
 
6395
 
 
6396
The Interface
 
6397
-------------
 
6398
 
 
6399
The minimal functionality an interface must have is a) to select a
 
6400
domain the strings are coming from (a single domain for all programs is
 
6401
not reasonable because its construction and maintenance is difficult,
 
6402
perhaps impossible) and b) to access a string in a selected domain.
 
6403
 
 
6404
   This is principally the description of the `gettext' interface.  It
 
6405
has a global domain which unqualified usages reference.  Of course this
 
6406
domain is selectable by the user.
 
6407
 
 
6408
     char *textdomain (const char *domain_name);
 
6409
 
 
6410
   This provides the possibility to change or query the current status
 
6411
of the current global domain of the `LC_MESSAGE' category.  The
 
6412
argument is a null-terminated string, whose characters must be legal in
 
6413
the use in filenames.  If the DOMAIN_NAME argument is `NULL', the
 
6414
function returns the current value.  If no value has been set before,
 
6415
the name of the default domain is returned: _messages_.  Please note
 
6416
that although the return value of `textdomain' is of type `char *' no
 
6417
changing is allowed.  It is also important to know that no checks of
 
6418
the availability are made.  If the name is not available you will see
 
6419
this by the fact that no translations are provided.
 
6420
 
 
6421
To use a domain set by `textdomain' the function
 
6422
 
 
6423
     char *gettext (const char *msgid);
 
6424
 
 
6425
is to be used.  This is the simplest reasonable form one can imagine.
 
6426
The translation of the string MSGID is returned if it is available in
 
6427
the current domain.  If it is not available, the argument itself is
 
6428
returned.  If the argument is `NULL' the result is undefined.
 
6429
 
 
6430
   One thing which should come into mind is that no explicit dependency
 
6431
to the used domain is given.  The current value of the domain for the
 
6432
`LC_MESSAGES' locale is used.  If this changes between two executions
 
6433
of the same `gettext' call in the program, both calls reference a
 
6434
different message catalog.
 
6435
 
 
6436
   For the easiest case, which is normally used in internationalized
 
6437
packages, once at the beginning of execution a call to `textdomain' is
 
6438
issued, setting the domain to a unique name, normally the package name.
 
6439
In the following code all strings which have to be translated are
 
6440
filtered through the gettext function.  That's all, the package speaks
 
6441
your language.
 
6442
 
 
6443
 
 
6444
File: gettext.info,  Node: Ambiguities,  Next: Locating Catalogs,  Prev: Interface to gettext,  Up: gettext
 
6445
 
 
6446
Solving Ambiguities
 
6447
-------------------
 
6448
 
 
6449
While this single name domain works well for most applications there
 
6450
might be the need to get translations from more than one domain.  Of
 
6451
course one could switch between different domains with calls to
 
6452
`textdomain', but this is really not convenient nor is it fast.  A
 
6453
possible situation could be one case subject to discussion during this
 
6454
writing:  all error messages of functions in the set of common used
 
6455
functions should go into a separate domain `error'.  By this mean we
 
6456
would only need to translate them once.  Another case are messages from
 
6457
a library, as these _have_ to be independent of the current domain set
 
6458
by the application.
 
6459
 
 
6460
For this reasons there are two more functions to retrieve strings:
 
6461
 
 
6462
     char *dgettext (const char *domain_name, const char *msgid);
 
6463
     char *dcgettext (const char *domain_name, const char *msgid,
 
6464
                      int category);
 
6465
 
 
6466
   Both take an additional argument at the first place, which
 
6467
corresponds to the argument of `textdomain'.  The third argument of
 
6468
`dcgettext' allows to use another locale but `LC_MESSAGES'.  But I
 
6469
really don't know where this can be useful.  If the DOMAIN_NAME is
 
6470
`NULL' or CATEGORY has an value beside the known ones, the result is
 
6471
undefined.  It should also be noted that this function is not part of
 
6472
the second known implementation of this function family, the one found
 
6473
in Solaris.
 
6474
 
 
6475
   A second ambiguity can arise by the fact, that perhaps more than one
 
6476
domain has the same name.  This can be solved by specifying where the
 
6477
needed message catalog files can be found.
 
6478
 
 
6479
     char *bindtextdomain (const char *domain_name,
 
6480
                           const char *dir_name);
 
6481
 
 
6482
   Calling this function binds the given domain to a file in the
 
6483
specified directory (how this file is determined follows below).
 
6484
Especially a file in the systems default place is not favored against
 
6485
the specified file anymore (as it would be by solely using
 
6486
`textdomain').  A `NULL' pointer for the DIR_NAME parameter returns the
 
6487
binding associated with DOMAIN_NAME.  If DOMAIN_NAME itself is `NULL'
 
6488
nothing happens and a `NULL' pointer is returned.  Here again as for
 
6489
all the other functions is true that none of the return value must be
 
6490
changed!
 
6491
 
 
6492
   It is important to remember that relative path names for the
 
6493
DIR_NAME parameter can be trouble.  Since the path is always computed
 
6494
relative to the current directory different results will be achieved
 
6495
when the program executes a `chdir' command.  Relative paths should
 
6496
always be avoided to avoid dependencies and unreliabilities.
 
6497
 
 
6498
 
 
6499
File: gettext.info,  Node: Locating Catalogs,  Next: Charset conversion,  Prev: Ambiguities,  Up: gettext
 
6500
 
 
6501
Locating Message Catalog Files
 
6502
------------------------------
 
6503
 
 
6504
Because many different languages for many different packages have to be
 
6505
stored we need some way to add these information to file message catalog
 
6506
files.  The way usually used in Unix environments is have this encoding
 
6507
in the file name.  This is also done here.  The directory name given in
 
6508
`bindtextdomain's second argument (or the default directory), followed
 
6509
by the value and name of the locale and the domain name are
 
6510
concatenated:
 
6511
 
 
6512
     DIR_NAME/LOCALE/LC_CATEGORY/DOMAIN_NAME.mo
 
6513
 
 
6514
   The default value for DIR_NAME is system specific.  For the GNU
 
6515
library, and for packages adhering to its conventions, it's:
 
6516
     /usr/local/share/locale
 
6517
 
 
6518
LOCALE is the value of the locale whose name is this `LC_CATEGORY'.
 
6519
For `gettext' and `dgettext' this `LC_CATEGORY' is always
 
6520
`LC_MESSAGES'.(1) The value of the locale is determined through
 
6521
`setlocale (LC_CATEGORY, NULL)'.  (2) `dcgettext' specifies the locale
 
6522
category by the third argument.
 
6523
 
 
6524
   ---------- Footnotes ----------
 
6525
 
 
6526
   (1) Some system, eg Ultrix, don't have `LC_MESSAGES'.  Here we use a
 
6527
more or less arbitrary value for it, namely 1729, the smallest positive
 
6528
integer which can be represented in two different ways as the sum of
 
6529
two cubes.
 
6530
 
 
6531
   (2) When the system does not support `setlocale' its behavior in
 
6532
setting the locale values is simulated by looking at the environment
 
6533
variables.
 
6534
 
 
6535
 
 
6536
File: gettext.info,  Node: Charset conversion,  Next: Plural forms,  Prev: Locating Catalogs,  Up: gettext
 
6537
 
 
6538
How to specify the output character set `gettext' uses
 
6539
------------------------------------------------------
 
6540
 
 
6541
`gettext' not only looks up a translation in a message catalog.  It
 
6542
also converts the translation on the fly to the desired output character
 
6543
set.  This is useful if the user is working in a different character set
 
6544
than the translator who created the message catalog, because it avoids
 
6545
distributing variants of message catalogs which differ only in the
 
6546
character set.
 
6547
 
 
6548
   The output character set is, by default, the value of `nl_langinfo
 
6549
(CODESET)', which depends on the `LC_CTYPE' part of the current locale.
 
6550
But programs which store strings in a locale independent way (e.g.
 
6551
UTF-8) can request that `gettext' and related functions return the
 
6552
translations in that encoding, by use of the `bind_textdomain_codeset'
 
6553
function.
 
6554
 
 
6555
   Note that the MSGID argument to `gettext' is not subject to
 
6556
character set conversion.  Also, when `gettext' does not find a
 
6557
translation for MSGID, it returns MSGID unchanged - independently of
 
6558
the current output character set.  It is therefore recommended that all
 
6559
MSGIDs be US-ASCII strings.
 
6560
 
 
6561
 - Function: char * bind_textdomain_codeset (const char *DOMAINNAME,
 
6562
          const char *CODESET)
 
6563
     The `bind_textdomain_codeset' function can be used to specify the
 
6564
     output character set for message catalogs for domain DOMAINNAME.
 
6565
     The CODESET argument must be a valid codeset name which can be used
 
6566
     for the `iconv_open' function, or a null pointer.
 
6567
 
 
6568
     If the CODESET parameter is the null pointer,
 
6569
     `bind_textdomain_codeset' returns the currently selected codeset
 
6570
     for the domain with the name DOMAINNAME.  It returns `NULL' if no
 
6571
     codeset has yet been selected.
 
6572
 
 
6573
     The `bind_textdomain_codeset' function can be used several times.
 
6574
     If used multiple times with the same DOMAINNAME argument, the
 
6575
     later call overrides the settings made by the earlier one.
 
6576
 
 
6577
     The `bind_textdomain_codeset' function returns a pointer to a
 
6578
     string containing the name of the selected codeset.  The string is
 
6579
     allocated internally in the function and must not be changed by the
 
6580
     user.  If the system went out of core during the execution of
 
6581
     `bind_textdomain_codeset', the return value is `NULL' and the
 
6582
     global variable ERRNO is set accordingly.
 
6583
 
 
6584
 
 
6585
File: gettext.info,  Node: Plural forms,  Next: GUI program problems,  Prev: Charset conversion,  Up: gettext
 
6586
 
 
6587
Additional functions for plural forms
 
6588
-------------------------------------
 
6589
 
 
6590
The functions of the `gettext' family described so far (and all the
 
6591
`catgets' functions as well) have one problem in the real world which
 
6592
have been neglected completely in all existing approaches.  What is
 
6593
meant here is the handling of plural forms.
 
6594
 
 
6595
   Looking through Unix source code before the time anybody thought
 
6596
about internationalization (and, sadly, even afterwards) one can often
 
6597
find code similar to the following:
 
6598
 
 
6599
        printf ("%d file%s deleted", n, n == 1 ? "" : "s");
 
6600
 
 
6601
After the first complaints from people internationalizing the code
 
6602
people either completely avoided formulations like this or used strings
 
6603
like `"file(s)"'.  Both look unnatural and should be avoided.  First
 
6604
tries to solve the problem correctly looked like this:
 
6605
 
 
6606
        if (n == 1)
 
6607
          printf ("%d file deleted", n);
 
6608
        else
 
6609
          printf ("%d files deleted", n);
 
6610
 
 
6611
   But this does not solve the problem.  It helps languages where the
 
6612
plural form of a noun is not simply constructed by adding an `s' but
 
6613
that is all.  Once again people fell into the trap of believing the
 
6614
rules their language is using are universal.  But the handling of plural
 
6615
forms differs widely between the language families.  For example, Rafal
 
6616
Maszkowski `<rzm@mat.uni.torun.pl>' reports:
 
6617
 
 
6618
     In Polish we use e.g. plik (file) this way:
 
6619
          1 plik
 
6620
          2,3,4 pliki
 
6621
          5-21 pliko'w
 
6622
          22-24 pliki
 
6623
          25-31 pliko'w
 
6624
     and so on (o' means 8859-2 oacute which should be rather okreska,
 
6625
     similar to aogonek).
 
6626
 
 
6627
   There are two things which can differ between languages (and even
 
6628
inside language families);
 
6629
 
 
6630
   * The form how plural forms are built differs.  This is a problem
 
6631
     with languages which have many irregularities.  German, for
 
6632
     instance, is a drastic case.  Though English and German are part
 
6633
     of the same language family (Germanic), the almost regular forming
 
6634
     of plural noun forms (appending an `s') is hardly found in German.
 
6635
 
 
6636
   * The number of plural forms differ.  This is somewhat surprising for
 
6637
     those who only have experiences with Romanic and Germanic languages
 
6638
     since here the number is the same (there are two).
 
6639
 
 
6640
     But other language families have only one form or many forms.  More
 
6641
     information on this in an extra section.
 
6642
 
 
6643
   The consequence of this is that application writers should not try to
 
6644
solve the problem in their code.  This would be localization since it is
 
6645
only usable for certain, hardcoded language environments.  Instead the
 
6646
extended `gettext' interface should be used.
 
6647
 
 
6648
   These extra functions are taking instead of the one key string two
 
6649
strings and a numerical argument.  The idea behind this is that using
 
6650
the numerical argument and the first string as a key, the implementation
 
6651
can select using rules specified by the translator the right plural
 
6652
form.  The two string arguments then will be used to provide a return
 
6653
value in case no message catalog is found (similar to the normal
 
6654
`gettext' behavior).  In this case the rules for Germanic language is
 
6655
used and it is assumed that the first string argument is the singular
 
6656
form, the second the plural form.
 
6657
 
 
6658
   This has the consequence that programs without language catalogs can
 
6659
display the correct strings only if the program itself is written using
 
6660
a Germanic language.  This is a limitation but since the GNU C library
 
6661
(as well as the GNU `gettext' package) are written as part of the GNU
 
6662
package and the coding standards for the GNU project require program
 
6663
being written in English, this solution nevertheless fulfills its
 
6664
purpose.
 
6665
 
 
6666
 - Function: char * ngettext (const char *MSGID1, const char *MSGID2,
 
6667
          unsigned long int N)
 
6668
     The `ngettext' function is similar to the `gettext' function as it
 
6669
     finds the message catalogs in the same way.  But it takes two
 
6670
     extra arguments.  The MSGID1 parameter must contain the singular
 
6671
     form of the string to be converted.  It is also used as the key
 
6672
     for the search in the catalog.  The MSGID2 parameter is the plural
 
6673
     form.  The parameter N is used to determine the plural form.  If no
 
6674
     message catalog is found MSGID1 is returned if `n == 1', otherwise
 
6675
     `msgid2'.
 
6676
 
 
6677
     An example for the use of this function is:
 
6678
 
 
6679
          printf (ngettext ("%d file removed", "%d files removed", n), n);
 
6680
 
 
6681
     Please note that the numeric value N has to be passed to the
 
6682
     `printf' function as well.  It is not sufficient to pass it only to
 
6683
     `ngettext'.
 
6684
 
 
6685
 - Function: char * dngettext (const char *DOMAIN, const char *MSGID1,
 
6686
          const char *MSGID2, unsigned long int N)
 
6687
     The `dngettext' is similar to the `dgettext' function in the way
 
6688
     the message catalog is selected.  The difference is that it takes
 
6689
     two extra parameter to provide the correct plural form.  These two
 
6690
     parameters are handled in the same way `ngettext' handles them.
 
6691
 
 
6692
 - Function: char * dcngettext (const char *DOMAIN, const char *MSGID1,
 
6693
          const char *MSGID2, unsigned long int N, int CATEGORY)
 
6694
     The `dcngettext' is similar to the `dcgettext' function in the way
 
6695
     the message catalog is selected.  The difference is that it takes
 
6696
     two extra parameter to provide the correct plural form.  These two
 
6697
     parameters are handled in the same way `ngettext' handles them.
 
6698
 
 
6699
   Now, how do these functions solve the problem of the plural forms?
 
6700
Without the input of linguists (which was not available) it was not
 
6701
possible to determine whether there are only a few different forms in
 
6702
which plural forms are formed or whether the number can increase with
 
6703
every new supported language.
 
6704
 
 
6705
   Therefore the solution implemented is to allow the translator to
 
6706
specify the rules of how to select the plural form.  Since the formula
 
6707
varies with every language this is the only viable solution except for
 
6708
hardcoding the information in the code (which still would require the
 
6709
possibility of extensions to not prevent the use of new languages).
 
6710
 
 
6711
   The information about the plural form selection has to be stored in
 
6712
the header entry of the PO file (the one with the empty `msgid' string).
 
6713
The plural form information looks like this:
 
6714
 
 
6715
     Plural-Forms: nplurals=2; plural=n == 1 ? 0 : 1;
 
6716
 
 
6717
   The `nplurals' value must be a decimal number which specifies how
 
6718
many different plural forms exist for this language.  The string
 
6719
following `plural' is an expression which is using the C language
 
6720
syntax.  Exceptions are that no negative numbers are allowed, numbers
 
6721
must be decimal, and the only variable allowed is `n'.  This expression
 
6722
will be evaluated whenever one of the functions `ngettext',
 
6723
`dngettext', or `dcngettext' is called.  The numeric value passed to
 
6724
these functions is then substituted for all uses of the variable `n' in
 
6725
the expression.  The resulting value then must be greater or equal to
 
6726
zero and smaller than the value given as the value of `nplurals'.
 
6727
 
 
6728
The following rules are known at this point.  The language with families
 
6729
are listed.  But this does not necessarily mean the information can be
 
6730
generalized for the whole family (as can be easily seen in the table
 
6731
below).(1)
 
6732
 
 
6733
Only one form:
 
6734
     Some languages only require one single form.  There is no
 
6735
     distinction between the singular and plural form.  An appropriate
 
6736
     header entry would look like this:
 
6737
 
 
6738
          Plural-Forms: nplurals=1; plural=0;
 
6739
 
 
6740
     Languages with this property include:
 
6741
 
 
6742
    Finno-Ugric family
 
6743
          Hungarian
 
6744
 
 
6745
    Asian family
 
6746
          Japanese, Korean
 
6747
 
 
6748
    Turkic/Altaic family
 
6749
          Turkish
 
6750
 
 
6751
Two forms, singular used for one only
 
6752
     This is the form used in most existing programs since it is what
 
6753
     English is using.  A header entry would look like this:
 
6754
 
 
6755
          Plural-Forms: nplurals=2; plural=n != 1;
 
6756
 
 
6757
     (Note: this uses the feature of C expressions that boolean
 
6758
     expressions have to value zero or one.)
 
6759
 
 
6760
     Languages with this property include:
 
6761
 
 
6762
    Germanic family
 
6763
          Danish, Dutch, English, Faroese, German, Norwegian, Swedish
 
6764
 
 
6765
    Finno-Ugric family
 
6766
          Estonian, Finnish
 
6767
 
 
6768
    Latin/Greek family
 
6769
          Greek
 
6770
 
 
6771
    Semitic family
 
6772
          Hebrew
 
6773
 
 
6774
    Romanic family
 
6775
          Italian, Portuguese, Spanish
 
6776
 
 
6777
    Artificial
 
6778
          Esperanto
 
6779
 
 
6780
Two forms, singular used for zero and one
 
6781
     Exceptional case in the language family.  The header entry would
 
6782
     be:
 
6783
 
 
6784
          Plural-Forms: nplurals=2; plural=n>1;
 
6785
 
 
6786
     Languages with this property include:
 
6787
 
 
6788
    Romanic family
 
6789
          French, Brazilian Portuguese
 
6790
 
 
6791
Three forms, special case for zero
 
6792
     The header entry would be:
 
6793
 
 
6794
          Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n != 0 ? 1 : 2;
 
6795
 
 
6796
     Languages with this property include:
 
6797
 
 
6798
    Baltic family
 
6799
          Latvian
 
6800
 
 
6801
Three forms, special cases for one and two
 
6802
     The header entry would be:
 
6803
 
 
6804
          Plural-Forms: nplurals=3; plural=n==1 ? 0 : n==2 ? 1 : 2;
 
6805
 
 
6806
     Languages with this property include:
 
6807
 
 
6808
    Celtic
 
6809
          Gaeilge (Irish)
 
6810
 
 
6811
Three forms, special case for numbers ending in 1[2-9]
 
6812
     The header entry would look like this:
 
6813
 
 
6814
          Plural-Forms: nplurals=3; \
 
6815
              plural=n%10==1 && n%100!=11 ? 0 : \
 
6816
                     n%10>=2 && (n%100<10 || n%100>=20) ? 1 : 2;
 
6817
 
 
6818
     Languages with this property include:
 
6819
 
 
6820
    Baltic family
 
6821
          Lithuanian
 
6822
 
 
6823
Three forms, special cases for numbers ending in 1 and 2, 3, 4, except those ending in 1[1-4]
 
6824
     The header entry would look like this:
 
6825
 
 
6826
          Plural-Forms: nplurals=3; \
 
6827
              plural=n%10==1 && n%100!=11 ? 0 : \
 
6828
                     n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;
 
6829
 
 
6830
     Languages with this property include:
 
6831
 
 
6832
    Slavic family
 
6833
          Croatian, Czech, Russian, Ukrainian
 
6834
 
 
6835
Three forms, special cases for 1 and 2, 3, 4
 
6836
     The header entry would look like this:
 
6837
 
 
6838
          Plural-Forms: nplurals=3; \
 
6839
              plural=(n==1) ? 0 : (n>=2 && n<=4) ? 1 : 2;
 
6840
 
 
6841
     Languages with this property include:
 
6842
 
 
6843
    Slavic family
 
6844
          Slovak
 
6845
 
 
6846
Three forms, special case for one and some numbers ending in 2, 3, or 4
 
6847
     The header entry would look like this:
 
6848
 
 
6849
          Plural-Forms: nplurals=3; \
 
6850
              plural=n==1 ? 0 : \
 
6851
                     n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;
 
6852
 
 
6853
     Languages with this property include:
 
6854
 
 
6855
    Slavic family
 
6856
          Polish
 
6857
 
 
6858
Four forms, special case for one and all numbers ending in 02, 03, or 04
 
6859
     The header entry would look like this:
 
6860
 
 
6861
          Plural-Forms: nplurals=4; \
 
6862
              plural=n%100==1 ? 0 : n%100==2 ? 1 : n%100==3 || n%100==4 ? 2 : 3;
 
6863
 
 
6864
     Languages with this property include:
 
6865
 
 
6866
    Slavic family
 
6867
          Slovenian
 
6868
 
 
6869
   ---------- Footnotes ----------
 
6870
 
 
6871
   (1) Additions are welcome.  Send appropriate information to
 
6872
<bug-glibc-manual@gnu.org>.
 
6873
 
 
6874
 
 
6875
File: gettext.info,  Node: GUI program problems,  Next: Optimized gettext,  Prev: Plural forms,  Up: gettext
 
6876
 
 
6877
How to use `gettext' in GUI programs
 
6878
------------------------------------
 
6879
 
 
6880
One place where the `gettext' functions, if used normally, have big
 
6881
problems is within programs with graphical user interfaces (GUIs).  The
 
6882
problem is that many of the strings which have to be translated are very
 
6883
short.  They have to appear in pull-down menus which restricts the
 
6884
length.  But strings which are not containing entire sentences or at
 
6885
least large fragments of a sentence may appear in more than one
 
6886
situation in the program but might have different translations.  This is
 
6887
especially true for the one-word strings which are frequently used in
 
6888
GUI programs.
 
6889
 
 
6890
   As a consequence many people say that the `gettext' approach is
 
6891
wrong and instead `catgets' should be used which indeed does not have
 
6892
this problem.  But there is a very simple and powerful method to handle
 
6893
these kind of problems with the `gettext' functions.
 
6894
 
 
6895
As as example consider the following fictional situation.  A GUI program
 
6896
has a menu bar with the following entries:
 
6897
 
 
6898
     +------------+------------+--------------------------------------+
 
6899
     | File       | Printer    |                                      |
 
6900
     +------------+------------+--------------------------------------+
 
6901
     | Open     | | Select   |
 
6902
     | New      | | Open     |
 
6903
     +----------+ | Connect  |
 
6904
                  +----------+
 
6905
 
 
6906
   To have the strings `File', `Printer', `Open', `New', `Select', and
 
6907
`Connect' translated there has to be at some point in the code a call
 
6908
to a function of the `gettext' family.  But in two places the string
 
6909
passed into the function would be `Open'.  The translations might not
 
6910
be the same and therefore we are in the dilemma described above.
 
6911
 
 
6912
   One solution to this problem is to artificially enlengthen the
 
6913
strings to make them unambiguous.  But what would the program do if no
 
6914
translation is available?  The enlengthened string is not what should be
 
6915
printed.  So we should use a little bit modified version of the
 
6916
functions.
 
6917
 
 
6918
   To enlengthen the strings a uniform method should be used.  E.g., in
 
6919
the example above the strings could be chosen as
 
6920
 
 
6921
     Menu|File
 
6922
     Menu|Printer
 
6923
     Menu|File|Open
 
6924
     Menu|File|New
 
6925
     Menu|Printer|Select
 
6926
     Menu|Printer|Open
 
6927
     Menu|Printer|Connect
 
6928
 
 
6929
   Now all the strings are different and if now instead of `gettext'
 
6930
the following little wrapper function is used, everything works just
 
6931
fine:
 
6932
 
 
6933
       char *
 
6934
       sgettext (const char *msgid)
 
6935
       {
 
6936
         char *msgval = gettext (msgid);
 
6937
         if (msgval == msgid)
 
6938
           msgval = strrchr (msgid, '|') + 1;
 
6939
         return msgval;
 
6940
       }
 
6941
 
 
6942
   What this little function does is to recognize the case when no
 
6943
translation is available.  This can be done very efficiently by a
 
6944
pointer comparison since the return value is the input value.  If there
 
6945
is no translation we know that the input string is in the format we used
 
6946
for the Menu entries and therefore contains a `|' character.  We simply
 
6947
search for the last occurrence of this character and return a pointer
 
6948
to the character following it.  That's it!
 
6949
 
 
6950
   If one now consistently uses the enlengthened string form and
 
6951
replaces the `gettext' calls with calls to `sgettext' (this is normally
 
6952
limited to very few places in the GUI implementation) then it is
 
6953
possible to produce a program which can be internationalized.
 
6954
 
 
6955
   The other `gettext' functions (`dgettext', `dcgettext' and the
 
6956
`ngettext' equivalents) can and should have corresponding functions as
 
6957
well which look almost identical, except for the parameters and the
 
6958
call to the underlying function.
 
6959
 
 
6960
   Now there is of course the question why such functions do not exist
 
6961
in the GNU gettext package?  There are two parts of the answer to this
 
6962
question.
 
6963
 
 
6964
   * They are easy to write and therefore can be provided by the
 
6965
     project they are used in.  This is not an answer by itself and
 
6966
     must be seen together with the second part which is:
 
6967
 
 
6968
   * There is no way the gettext package can contain a version which
 
6969
     can work everywhere.  The problem is the selection of the
 
6970
     character to separate the prefix from the actual string in the
 
6971
     enlenghtened string.  The examples above used `|' which is a quite
 
6972
     good choice because it resembles a notation frequently used in
 
6973
     this context and it also is a character not often used in message
 
6974
     strings.
 
6975
 
 
6976
     But what if the character is used in message strings?  Or if the
 
6977
     chose character is not available in the character set on the
 
6978
     machine one compiles (e.g., `|' is not required to exist for
 
6979
     ISO C; this is why the `iso646.h' file exists in ISO C programming
 
6980
     environments).
 
6981
 
 
6982
   There is only one more comment to be said.  The wrapper function
 
6983
above requires that the translations strings are not enlengthened
 
6984
themselves.  This is only logical.  There is no need to disambiguate
 
6985
the strings (since they are never used as keys for a search) and one
 
6986
also saves quite some memory and disk space by doing this.
 
6987
 
 
6988
 
 
6989
File: gettext.info,  Node: Optimized gettext,  Prev: GUI program problems,  Up: gettext
 
6990
 
 
6991
Optimization of the *gettext functions
 
6992
--------------------------------------
 
6993
 
 
6994
At this point of the discussion we should talk about an advantage of the
 
6995
GNU `gettext' implementation.  Some readers might have pointed out that
 
6996
an internationalized program might have a poor performance if some
 
6997
string has to be translated in an inner loop.  While this is unavoidable
 
6998
when the string varies from one run of the loop to the other it is
 
6999
simply a waste of time when the string is always the same.  Take the
 
7000
following example:
 
7001
 
 
7002
     {
 
7003
       while (...)
 
7004
         {
 
7005
           puts (gettext ("Hello world"));
 
7006
         }
 
7007
     }
 
7008
 
 
7009
When the locale selection does not change between two runs the resulting
 
7010
string is always the same.  One way to use this is:
 
7011
 
 
7012
     {
 
7013
       str = gettext ("Hello world");
 
7014
       while (...)
 
7015
         {
 
7016
           puts (str);
 
7017
         }
 
7018
     }
 
7019
 
 
7020
But this solution is not usable in all situation (e.g. when the locale
 
7021
selection changes) nor does it lead to legible code.
 
7022
 
 
7023
   For this reason, GNU `gettext' caches previous translation results.
 
7024
When the same translation is requested twice, with no new message
 
7025
catalogs being loaded in between, `gettext' will, the second time, find
 
7026
the result through a single cache lookup.
 
7027
 
 
7028
 
 
7029
File: gettext.info,  Node: Comparison,  Next: Using libintl.a,  Prev: gettext,  Up: Programmers
 
7030
 
 
7031
Comparing the Two Interfaces
 
7032
============================
 
7033
 
 
7034
The following discussion is perhaps a little bit colored.  As said
 
7035
above we implemented GNU `gettext' following the Uniforum proposal and
 
7036
this surely has its reasons.  But it should show how we came to this
 
7037
decision.
 
7038
 
 
7039
   First we take a look at the developing process.  When we write an
 
7040
application using NLS provided by `gettext' we proceed as always.  Only
 
7041
when we come to a string which might be seen by the users and thus has
 
7042
to be translated we use `gettext("...")' instead of `"..."'.  At the
 
7043
beginning of each source file (or in a central header file) we define
 
7044
 
 
7045
     #define gettext(String) (String)
 
7046
 
 
7047
   Even this definition can be avoided when the system supports the
 
7048
`gettext' function in its C library.  When we compile this code the
 
7049
result is the same as if no NLS code is used.  When  you take a look at
 
7050
the GNU `gettext' code you will see that we use `_("...")' instead of
 
7051
`gettext("...")'.  This reduces the number of additional characters per
 
7052
translatable string to _3_ (in words: three).
 
7053
 
 
7054
   When now a production version of the program is needed we simply
 
7055
replace the definition
 
7056
 
 
7057
     #define _(String) (String)
 
7058
 
 
7059
by
 
7060
 
 
7061
     #include <libintl.h>
 
7062
     #define _(String) gettext (String)
 
7063
 
 
7064
Additionally we run the program `xgettext' on all source code file
 
7065
which contain translatable strings and that's it: we have a running
 
7066
program which does not depend on translations to be available, but which
 
7067
can use any that becomes available.
 
7068
 
 
7069
   The same procedure can be done for the `gettext_noop' invocations
 
7070
(*note Special cases::).  One usually defines `gettext_noop' as a no-op
 
7071
macro.  So you should consider the following code for your project:
 
7072
 
 
7073
     #define gettext_noop(String) String
 
7074
     #define N_(String) gettext_noop (String)
 
7075
 
 
7076
   `N_' is a short form similar to `_'.  The `Makefile' in the `po/'
 
7077
directory of GNU `gettext' knows by default both of the mentioned short
 
7078
forms so you are invited to follow this proposal for your own ease.
 
7079
 
 
7080
   Now to `catgets'.  The main problem is the work for the programmer.
 
7081
Every time he comes to a translatable string he has to define a number
 
7082
(or a symbolic constant) which has also be defined in the message
 
7083
catalog file.  He also has to take care for duplicate entries,
 
7084
duplicate message IDs etc.  If he wants to have the same quality in the
 
7085
message catalog as the GNU `gettext' program provides he also has to
 
7086
put the descriptive comments for the strings and the location in all
 
7087
source code files in the message catalog.  This is nearly a Mission:
 
7088
Impossible.
 
7089
 
 
7090
   But there are also some points people might call advantages speaking
 
7091
for `catgets'.  If you have a single word in a string and this string
 
7092
is used in different contexts it is likely that in one or the other
 
7093
language the word has different translations.  Example:
 
7094
 
 
7095
     printf ("%s: %d", gettext ("number"), number_of_errors)
 
7096
     
 
7097
     printf ("you should see %d %s", number_count,
 
7098
             number_count == 1 ? gettext ("number") : gettext ("numbers"))
 
7099
 
 
7100
   Here we have to translate two times the string `"number"'.  Even if
 
7101
you do not speak a language beside English it might be possible to
 
7102
recognize that the two words have a different meaning.  In German the
 
7103
first appearance has to be translated to `"Anzahl"' and the second to
 
7104
`"Zahl"'.
 
7105
 
 
7106
   Now you can say that this example is really esoteric.  And you are
 
7107
right!  This is exactly how we felt about this problem and decide that
 
7108
it does not weight that much.  The solution for the above problem could
 
7109
be very easy:
 
7110
 
 
7111
     printf ("%s %d", gettext ("number:"), number_of_errors)
 
7112
     
 
7113
     printf (number_count == 1 ? gettext ("you should see %d number")
 
7114
                               : gettext ("you should see %d numbers"),
 
7115
             number_count)
 
7116
 
 
7117
   We believe that we can solve all conflicts with this method.  If it
 
7118
is difficult one can also consider changing one of the conflicting
 
7119
string a little bit.  But it is not impossible to overcome.
 
7120
 
 
7121
   `catgets' allows same original entry to have different translations,
 
7122
but `gettext' has another, scalable approach for solving ambiguities of
 
7123
this kind: *Note Ambiguities::.
 
7124
 
 
7125
 
 
7126
File: gettext.info,  Node: Using libintl.a,  Next: gettext grok,  Prev: Comparison,  Up: Programmers
 
7127
 
 
7128
Using libintl.a in own programs
 
7129
===============================
 
7130
 
 
7131
Starting with version 0.9.4 the library `libintl.h' should be
 
7132
self-contained.  I.e., you can use it in your own programs without
 
7133
providing additional functions.  The `Makefile' will put the header and
 
7134
the library in directories selected using the `$(prefix)'.
 
7135
 
 
7136
 
 
7137
File: gettext.info,  Node: gettext grok,  Next: Temp Programmers,  Prev: Using libintl.a,  Up: Programmers
 
7138
 
 
7139
Being a `gettext' grok
 
7140
======================
 
7141
 
 
7142
To fully exploit the functionality of the GNU `gettext' library it is
 
7143
surely helpful to read the source code.  But for those who don't want
 
7144
to spend that much time in reading the (sometimes complicated) code here
 
7145
is a list comments:
 
7146
 
 
7147
   * Changing the language at runtime
 
7148
 
 
7149
     For interactive programs it might be useful to offer a selection
 
7150
     of the used language at runtime.  To understand how to do this one
 
7151
     need to know how the used language is determined while executing
 
7152
     the `gettext' function.  The method which is presented here only
 
7153
     works correctly with the GNU implementation of the `gettext'
 
7154
     functions.
 
7155
 
 
7156
     In the function `dcgettext' at every call the current setting of
 
7157
     the highest priority environment variable is determined and used.
 
7158
     Highest priority means here the following list with decreasing
 
7159
     priority:
 
7160
 
 
7161
       1. `LANGUAGE'
 
7162
 
 
7163
       2. `LC_ALL'
 
7164
 
 
7165
       3. `LC_xxx', according to selected locale
 
7166
 
 
7167
       4. `LANG'
 
7168
 
 
7169
     Afterwards the path is constructed using the found value and the
 
7170
     translation file is loaded if available.
 
7171
 
 
7172
     What happens now when the value for, say, `LANGUAGE' changes?
 
7173
     According to the process explained above the new value of this
 
7174
     variable is found as soon as the `dcgettext' function is called.
 
7175
     But this also means the (perhaps) different message catalog file
 
7176
     is loaded.  In other words: the used language is changed.
 
7177
 
 
7178
     But there is one little hook.  The code for gcc-2.7.0 and up
 
7179
     provides some optimization.  This optimization normally prevents
 
7180
     the calling of the `dcgettext' function as long as no new catalog
 
7181
     is loaded.  But if `dcgettext' is not called the program also
 
7182
     cannot find the `LANGUAGE' variable be changed (*note Optimized
 
7183
     gettext::).  A solution for this is very easy.  Include the
 
7184
     following code in the language switching function.
 
7185
 
 
7186
            /* Change language.  */
 
7187
            setenv ("LANGUAGE", "fr", 1);
 
7188
          
 
7189
            /* Make change known.  */
 
7190
            {
 
7191
              extern int  _nl_msg_cat_cntr;
 
7192
              ++_nl_msg_cat_cntr;
 
7193
            }
 
7194
 
 
7195
     The variable `_nl_msg_cat_cntr' is defined in `loadmsgcat.c'.  You
 
7196
     don't need to know what this is for.  But it can be used to detect
 
7197
     whether a `gettext' implementation is GNU gettext and not non-GNU
 
7198
     system's native gettext implementation.
 
7199
 
 
7200
 
 
7201
 
 
7202
File: gettext.info,  Node: Temp Programmers,  Prev: gettext grok,  Up: Programmers
 
7203
 
 
7204
Temporary Notes for the Programmers Chapter
 
7205
===========================================
 
7206
 
 
7207
* Menu:
 
7208
 
 
7209
* Temp Implementations::        Temporary - Two Possible Implementations
 
7210
* Temp catgets::                Temporary - About `catgets'
 
7211
* Temp WSI::                    Temporary - Why a single implementation
 
7212
* Temp Notes::                  Temporary - Notes
 
7213
 
 
7214
 
 
7215
File: gettext.info,  Node: Temp Implementations,  Next: Temp catgets,  Prev: Temp Programmers,  Up: Temp Programmers
 
7216
 
 
7217
Temporary - Two Possible Implementations
 
7218
----------------------------------------
 
7219
 
 
7220
There are two competing methods for language independent messages: the
 
7221
X/Open `catgets' method, and the Uniforum `gettext' method.  The
 
7222
`catgets' method indexes messages by integers; the `gettext' method
 
7223
indexes them by their English translations.  The `catgets' method has
 
7224
been around longer and is supported by more vendors.  The `gettext'
 
7225
method is supported by Sun, and it has been heard that the COSE
 
7226
multi-vendor initiative is supporting it.  Neither method is a POSIX
 
7227
standard; the POSIX.1 committee had a lot of disagreement in this area.
 
7228
 
 
7229
   Neither one is in the POSIX standard.  There was much disagreement
 
7230
in the POSIX.1 committee about using the `gettext' routines vs.
 
7231
`catgets' (XPG).  In the end the committee couldn't agree on anything,
 
7232
so no messaging system was included as part of the standard.  I believe
 
7233
the informative annex of the standard includes the XPG3 messaging
 
7234
interfaces, "...as an example of a messaging system that has been
 
7235
implemented..."
 
7236
 
 
7237
   They were very careful not to say anywhere that you should use one
 
7238
set of interfaces over the other.  For more on this topic please see
 
7239
the Programming for Internationalization FAQ.
 
7240
 
 
7241
 
 
7242
File: gettext.info,  Node: Temp catgets,  Next: Temp WSI,  Prev: Temp Implementations,  Up: Temp Programmers
 
7243
 
 
7244
Temporary - About `catgets'
 
7245
---------------------------
 
7246
 
 
7247
There have been a few discussions of late on the use of `catgets' as a
 
7248
base.  I think it important to present both sides of the argument and
 
7249
hence am opting to play devil's advocate for a little bit.
 
7250
 
 
7251
   I'll not deny the fact that `catgets' could have been designed a lot
 
7252
better.  It currently has quite a number of limitations and these have
 
7253
already been pointed out.
 
7254
 
 
7255
   However there is a great deal to be said for consistency and
 
7256
standardization.  A common recurring problem when writing Unix software
 
7257
is the myriad portability problems across Unix platforms.  It seems as
 
7258
if every Unix vendor had a look at the operating system and found parts
 
7259
they could improve upon.  Undoubtedly, these modifications are probably
 
7260
innovative and solve real problems.  However, software developers have
 
7261
a hard time keeping up with all these changes across so many platforms.
 
7262
 
 
7263
   And this has prompted the Unix vendors to begin to standardize their
 
7264
systems.  Hence the impetus for Spec1170.  Every major Unix vendor has
 
7265
committed to supporting this standard and every Unix software developer
 
7266
waits with glee the day they can write software to this standard and
 
7267
simply recompile (without having to use autoconf) across different
 
7268
platforms.
 
7269
 
 
7270
   As I understand it, Spec1170 is roughly based upon version 4 of the
 
7271
X/Open Portability Guidelines (XPG4).  Because `catgets' and friends
 
7272
are defined in XPG4, I'm led to believe that `catgets' is a part of
 
7273
Spec1170 and hence will become a standardized component of all Unix
 
7274
systems.
 
7275
 
 
7276
 
 
7277
File: gettext.info,  Node: Temp WSI,  Next: Temp Notes,  Prev: Temp catgets,  Up: Temp Programmers
 
7278
 
 
7279
Temporary - Why a single implementation
 
7280
---------------------------------------
 
7281
 
 
7282
Now it seems kind of wasteful to me to have two different systems
 
7283
installed for accessing message catalogs.  If we do want to remedy
 
7284
`catgets' deficiencies why don't we try to expand `catgets' (in a
 
7285
compatible manner) rather than implement an entirely new system.
 
7286
Otherwise, we'll end up with two message catalog access systems
 
7287
installed with an operating system - one set of routines for packages
 
7288
using GNU `gettext' for their internationalization, and another set of
 
7289
routines (catgets) for all other software.  Bloated?
 
7290
 
 
7291
   Supposing another catalog access system is implemented.  Which do we
 
7292
recommend?  At least for Linux, we need to attract as many software
 
7293
developers as possible.  Hence we need to make it as easy for them to
 
7294
port their software as possible.  Which means supporting `catgets'.  We
 
7295
will be implementing the `libintl' code within our `libc', but does
 
7296
this mean we also have to incorporate another message catalog access
 
7297
scheme within our `libc' as well?  And what about people who are going
 
7298
to be using the `libintl' + non-`catgets' routines.  When they port
 
7299
their software to other platforms, they're now going to have to include
 
7300
the front-end (`libintl') code plus the back-end code (the non-`catgets'
 
7301
access routines) with their software instead of just including the
 
7302
`libintl' code with their software.
 
7303
 
 
7304
   Message catalog support is however only the tip of the iceberg.
 
7305
What about the data for the other locale categories.  They also have a
 
7306
number of deficiencies.  Are we going to abandon them as well and
 
7307
develop another duplicate set of routines (should `libintl' expand
 
7308
beyond message catalog support)?
 
7309
 
 
7310
   Like many parts of Unix that can be improved upon, we're stuck with
 
7311
balancing compatibility with the past with useful improvements and
 
7312
innovations for the future.
 
7313
 
 
7314
 
 
7315
File: gettext.info,  Node: Temp Notes,  Prev: Temp WSI,  Up: Temp Programmers
 
7316
 
 
7317
Temporary - Notes
 
7318
-----------------
 
7319
 
 
7320
X/Open agreed very late on the standard form so that many
 
7321
implementations differ from the final form.  Both of my system (old
 
7322
Linux catgets and Ultrix-4) have a strange variation.
 
7323
 
 
7324
   OK.  After incorporating the last changes I have to spend some time
 
7325
on making the GNU/Linux `libc' `gettext' functions.  So in future
 
7326
Solaris is not the only system having `gettext'.
 
7327
 
 
7328
 
 
7329
File: gettext.info,  Node: Translators,  Next: Maintainers,  Prev: Programmers,  Up: Top
 
7330
 
 
7331
The Translator's View
 
7332
*********************
 
7333
 
 
7334
* Menu:
 
7335
 
 
7336
* Trans Intro 0::               Introduction 0
 
7337
* Trans Intro 1::               Introduction 1
 
7338
* Discussions::                 Discussions
 
7339
* Organization::                Organization
 
7340
* Information Flow::            Information Flow
 
7341
* Prioritizing messages::       How to find which messages to translate first
 
7342
 
 
7343
 
 
7344
File: gettext.info,  Node: Trans Intro 0,  Next: Trans Intro 1,  Prev: Translators,  Up: Translators
 
7345
 
 
7346
Introduction 0
 
7347
==============
 
7348
 
 
7349
Free software is going international!  The Translation Project is a way
 
7350
to get maintainers, translators and users all together, so free software
 
7351
will gradually become able to speak many native languages.
 
7352
 
 
7353
   The GNU `gettext' tool set contains _everything_ maintainers need
 
7354
for internationalizing their packages for messages.  It also contains
 
7355
quite useful tools for helping translators at localizing messages to
 
7356
their native language, once a package has already been
 
7357
internationalized.
 
7358
 
 
7359
   To achieve the Translation Project, we need many interested people
 
7360
who like their own language and write it well, and who are also able to
 
7361
synergize with other translators speaking the same language.  If you'd
 
7362
like to volunteer to _work_ at translating messages, please send mail
 
7363
to your translating team.
 
7364
 
 
7365
   Each team has its own mailing list, courtesy of Linux International.
 
7366
You may reach your translating team at the address `LL@li.org',
 
7367
replacing LL by the two-letter ISO 639 code for your language.
 
7368
Language codes are _not_ the same as country codes given in ISO 3166.
 
7369
The following translating teams exist:
 
7370
 
 
7371
     Chinese `zh', Czech `cs', Danish `da', Dutch `nl', Esperanto `eo',
 
7372
     Finnish `fi', French `fr', Irish `ga', German `de', Greek `el',
 
7373
     Italian `it', Japanese `ja', Indonesian `in', Norwegian `no',
 
7374
     Polish `pl', Portuguese `pt', Russian `ru', Spanish `es', Swedish
 
7375
     `sv' and Turkish `tr'.
 
7376
 
 
7377
For example, you may reach the Chinese translating team by writing to
 
7378
`zh@li.org'.  When you become a member of the translating team for your
 
7379
own language, you may subscribe to its list.  For example, Swedish
 
7380
people can send a message to `sv-request@li.org', having this message
 
7381
body:
 
7382
 
 
7383
     subscribe
 
7384
 
 
7385
   Keep in mind that team members should be interested in _working_ at
 
7386
translations, or at solving translational difficulties, rather than
 
7387
merely lurking around.  If your team does not exist yet and you want to
 
7388
start one, please write to `translation@iro.umontreal.ca'; you will
 
7389
then reach the coordinator for all translator teams.
 
7390
 
 
7391
   A handful of GNU packages have already been adapted and provided
 
7392
with message translations for several languages.  Translation teams
 
7393
have begun to organize, using these packages as a starting point.  But
 
7394
there are many more packages and many languages for which we have no
 
7395
volunteer translators.  If you would like to volunteer to work at
 
7396
translating messages, please send mail to
 
7397
`translation@iro.umontreal.ca' indicating what language(s) you can work
 
7398
on.
 
7399
 
 
7400
 
 
7401
File: gettext.info,  Node: Trans Intro 1,  Next: Discussions,  Prev: Trans Intro 0,  Up: Translators
 
7402
 
 
7403
Introduction 1
 
7404
==============
 
7405
 
 
7406
This is now official, GNU is going international!  Here is the
 
7407
announcement submitted for the January 1995 GNU Bulletin:
 
7408
 
 
7409
     A handful of GNU packages have already been adapted and provided
 
7410
     with message translations for several languages.  Translation
 
7411
     teams have begun to organize, using these packages as a starting
 
7412
     point.  But there are many more packages and many languages for
 
7413
     which we have no volunteer translators.  If you'd like to
 
7414
     volunteer to work at translating messages, please send mail to
 
7415
     `translation@iro.umontreal.ca' indicating what language(s) you can
 
7416
     work on.
 
7417
 
 
7418
   This document should answer many questions for those who are curious
 
7419
about the process or would like to contribute.  Please at least skim
 
7420
over it, hoping to cut down a little of the high volume of e-mail
 
7421
generated by this collective effort towards internationalization of
 
7422
free software.
 
7423
 
 
7424
   Most free programming which is widely shared is done in English, and
 
7425
currently, English is used as the main communicating language between
 
7426
national communities collaborating to free software.  This very document
 
7427
is written in English.  This will not change in the foreseeable future.
 
7428
 
 
7429
   However, there is a strong appetite from national communities for
 
7430
having more software able to write using national language and habits,
 
7431
and there is an on-going effort to modify free software in such a way
 
7432
that it becomes able to do so.  The experiments driven so far raised an
 
7433
enthusiastic response from pretesters, so we believe that
 
7434
internationalization of free software is dedicated to succeed.
 
7435
 
 
7436
   For suggestion clarifications, additions or corrections to this
 
7437
document, please e-mail to `translation@iro.umontreal.ca'.
 
7438
 
 
7439
 
 
7440
File: gettext.info,  Node: Discussions,  Next: Organization,  Prev: Trans Intro 1,  Up: Translators
 
7441
 
 
7442
Discussions
 
7443
===========
 
7444
 
 
7445
Facing this internationalization effort, a few users expressed their
 
7446
concerns.  Some of these doubts are presented and discussed, here.
 
7447
 
 
7448
   * Smaller groups
 
7449
 
 
7450
     Some languages are not spoken by a very large number of people, so
 
7451
     people speaking them sometimes consider that there may not be all
 
7452
     that much demand such versions of free software packages.
 
7453
     Moreover, many people being _into computers_, in some countries,
 
7454
     generally seem to prefer English versions of their software.
 
7455
 
 
7456
     On the other end, people might enjoy their own language a lot, and
 
7457
     be very motivated at providing to themselves the pleasure of
 
7458
     having their beloved free software speaking their mother tongue.
 
7459
     They do themselves a personal favor, and do not pay that much
 
7460
     attention to the number of people benefiting of their work.
 
7461
 
 
7462
   * Misinterpretation
 
7463
 
 
7464
     Other users are shy to push forward their own language, seeing in
 
7465
     this some kind of misplaced propaganda.  Someone thought there
 
7466
     must be some users of the language over the networks pestering
 
7467
     other people with it.
 
7468
 
 
7469
     But any spoken language is worth localization, because there are
 
7470
     people behind the language for whom the language is important and
 
7471
     dear to their hearts.
 
7472
 
 
7473
   * Odd translations
 
7474
 
 
7475
     The biggest problem is to find the right translations so that
 
7476
     everybody can understand the messages.  Translations are usually a
 
7477
     little odd.  Some people get used to English, to the extent they
 
7478
     may find translations into their own language "rather pushy,
 
7479
     obnoxious and sometimes even hilarious."  As a French speaking
 
7480
     man, I have the experience of those instruction manuals for goods,
 
7481
     so poorly translated in French in Korea or Taiwan...
 
7482
 
 
7483
     The fact is that we sometimes have to create a kind of national
 
7484
     computer culture, and this is not easy without the collaboration of
 
7485
     many people liking their mother tongue.  This is why translations
 
7486
     are better achieved by people knowing and loving their own
 
7487
     language, and ready to work together at improving the results they
 
7488
     obtain.
 
7489
 
 
7490
   * Dependencies over the GPL or LGPL
 
7491
 
 
7492
     Some people wonder if using GNU `gettext' necessarily brings their
 
7493
     package under the protective wing of the GNU General Public
 
7494
     License or the GNU Library General Public License, when they do
 
7495
     not want to make their program free, or want other kinds of
 
7496
     freedom.  The simplest answer is "normally not".
 
7497
 
 
7498
     The `gettext-runtime' part of GNU `gettext', i.e. the contents of
 
7499
     `libintl', is covered by the GNU Library General Public License.
 
7500
     The `gettext-tools' part of GNU `gettext', i.e. the rest of the
 
7501
     GNU `gettext' package, is covered by the GNU General Public
 
7502
     License.
 
7503
 
 
7504
     The mere marking of localizable strings in a package, or
 
7505
     conditional inclusion of a few lines for initialization, is not
 
7506
     really including GPL'ed or LGPL'ed code.  However, since the
 
7507
     localization routines in `libintl' are under the LGPL, the LGPL
 
7508
     needs to be considered.  It gives the right to distribute the
 
7509
     complete unmodified source of `libintl' even with non-free
 
7510
     programs.  It also gives the right to use `libintl' as a shared
 
7511
     library, even for non-free programs.  But it gives the right to
 
7512
     use `libintl' as a static library or to incorporate `libintl' into
 
7513
     another library only to free software.
 
7514
 
 
7515
 
 
7516
 
 
7517
File: gettext.info,  Node: Organization,  Next: Information Flow,  Prev: Discussions,  Up: Translators
 
7518
 
 
7519
Organization
 
7520
============
 
7521
 
 
7522
On a larger scale, the true solution would be to organize some kind of
 
7523
fairly precise set up in which volunteers could participate.  I gave
 
7524
some thought to this idea lately, and realize there will be some touchy
 
7525
points.  I thought of writing to Richard Stallman to launch such a
 
7526
project, but feel it might be good to shake out the ideas between
 
7527
ourselves first.  Most probably that Linux International has some
 
7528
experience in the field already, or would like to orchestrate the
 
7529
volunteer work, maybe.  Food for thought, in any case!
 
7530
 
 
7531
   I guess we have to setup something early, somehow, that will help
 
7532
many possible contributors of the same language to interlock and avoid
 
7533
work duplication, and further be put in contact for solving together
 
7534
problems particular to their tongue (in most languages, there are many
 
7535
difficulties peculiar to translating technical English).  My Swedish
 
7536
contributor acknowledged these difficulties, and I'm well aware of them
 
7537
for French.
 
7538
 
 
7539
   This is surely not a technical issue, but we should manage so the
 
7540
effort of locale contributors be maximally useful, despite the national
 
7541
team layer interface between contributors and maintainers.
 
7542
 
 
7543
   The Translation Project needs some setup for coordinating language
 
7544
coordinators.  Localizing evolving programs will surely become a
 
7545
permanent and continuous activity in the free software community, once
 
7546
well started.  The setup should be minimally completed and tested
 
7547
before GNU `gettext' becomes an official reality.  The e-mail address
 
7548
`translation@iro.umontreal.ca' has been setup for receiving offers from
 
7549
volunteers and general e-mail on these topics.  This address reaches
 
7550
the Translation Project coordinator.
 
7551
 
 
7552
* Menu:
 
7553
 
 
7554
* Central Coordination::        Central Coordination
 
7555
* National Teams::              National Teams
 
7556
* Mailing Lists::               Mailing Lists
 
7557
 
 
7558
 
 
7559
File: gettext.info,  Node: Central Coordination,  Next: National Teams,  Prev: Organization,  Up: Organization
 
7560
 
 
7561
Central Coordination
 
7562
--------------------
 
7563
 
 
7564
I also think GNU will need sooner than it thinks, that someone setup a
 
7565
way to organize and coordinate these groups.  Some kind of group of
 
7566
groups.  My opinion is that it would be good that GNU delegates this
 
7567
task to a small group of collaborating volunteers, shortly.  Perhaps in
 
7568
`gnu.announce' a list of this national committee's can be published.
 
7569
 
 
7570
   My role as coordinator would simply be to refer to Ulrich any German
 
7571
speaking volunteer interested to localization of free software
 
7572
packages, and maybe helping national groups to initially organize,
 
7573
while maintaining national registries for until national groups are
 
7574
ready to take over.  In fact, the coordinator should ease volunteers to
 
7575
get in contact with one another for creating national teams, which
 
7576
should then select one coordinator per language, or country
 
7577
(regionalized language).  If well done, the coordination should be
 
7578
useful without being an overwhelming task, the time to put delegations
 
7579
in place.
 
7580
 
 
7581
 
 
7582
File: gettext.info,  Node: National Teams,  Next: Mailing Lists,  Prev: Central Coordination,  Up: Organization
 
7583
 
 
7584
National Teams
 
7585
--------------
 
7586
 
 
7587
I suggest we look for volunteer coordinators/editors for individual
 
7588
languages.  These people will scan contributions of translation files
 
7589
for various programs, for their own languages, and will ensure high and
 
7590
uniform standards of diction.
 
7591
 
 
7592
   From my current experience with other people in these days, those who
 
7593
provide localizations are very enthusiastic about the process, and are
 
7594
more interested in the localization process than in the program they
 
7595
localize, and want to do many programs, not just one.  This seems to
 
7596
confirm that having a coordinator/editor for each language is a good
 
7597
idea.
 
7598
 
 
7599
   We need to choose someone who is good at writing clear and concise
 
7600
prose in the language in question.  That is hard--we can't check it
 
7601
ourselves.  So we need to ask a few people to judge each others'
 
7602
writing and select the one who is best.
 
7603
 
 
7604
   I announce my prerelease to a few dozen people, and you would not
 
7605
believe all the discussions it generated already.  I shudder to think
 
7606
what will happen when this will be launched, for true, officially,
 
7607
world wide.  Who am I to arbitrate between two Czekolsovak users
 
7608
contradicting each other, for example?
 
7609
 
 
7610
   I assume that your German is not much better than my French so that
 
7611
I would not be able to judge about these formulations.  What I would
 
7612
suggest is that for each language there is a group for people who
 
7613
maintain the PO files and judge about changes.  I suspect there will be
 
7614
cultural differences between how such groups of people will behave.
 
7615
Some will have relaxed ways, reach consensus easily, and have anyone of
 
7616
the group relate to the maintainers, while others will fight to death,
 
7617
organize heavy administrations up to national standards, and use strict
 
7618
channels.
 
7619
 
 
7620
   The German team is putting out a good example.  Right now, they are
 
7621
maybe half a dozen people revising translations of each other and
 
7622
discussing the linguistic issues.  I do not even have all the names.
 
7623
Ulrich Drepper is taking care of coordinating the German team.  He
 
7624
subscribed to all my pretest lists, so I do not even have to warn him
 
7625
specifically of incoming releases.
 
7626
 
 
7627
   I'm sure, that is a good idea to get teams for each language working
 
7628
on translations.  That will make the translations better and more
 
7629
consistent.
 
7630
 
 
7631
* Menu:
 
7632
 
 
7633
* Sub-Cultures::                Sub-Cultures
 
7634
* Organizational Ideas::        Organizational Ideas
 
7635
 
 
7636
 
 
7637
File: gettext.info,  Node: Sub-Cultures,  Next: Organizational Ideas,  Prev: National Teams,  Up: National Teams
 
7638
 
 
7639
Sub-Cultures
 
7640
............
 
7641
 
 
7642
Taking French for example, there are a few sub-cultures around computers
 
7643
which developed diverging vocabularies.  Picking volunteers here and
 
7644
there without addressing this problem in an organized way, soon in the
 
7645
project, might produce a distasteful mix of internationalized programs,
 
7646
and possibly trigger endless quarrels among those who really care.
 
7647
 
 
7648
   Keeping some kind of unity in the way French localization of
 
7649
internationalized programs is achieved is a difficult (and delicate)
 
7650
job.  Knowing the latin character of French people (:-), if we take this
 
7651
the wrong way, we could end up nowhere, or spoil a lot of energies.
 
7652
Maybe we should begin to address this problem seriously _before_ GNU
 
7653
`gettext' become officially published.  And I suspect that this means
 
7654
soon!
 
7655
 
 
7656
 
 
7657
File: gettext.info,  Node: Organizational Ideas,  Prev: Sub-Cultures,  Up: National Teams
 
7658
 
 
7659
Organizational Ideas
 
7660
....................
 
7661
 
 
7662
I expect the next big changes after the official release.  Please note
 
7663
that I use the German translation of the short GPL message.  We need to
 
7664
set a few good examples before the localization goes out for true in
 
7665
the free software community.  Here are a few points to discuss:
 
7666
 
 
7667
   * Each group should have one FTP server (at least one master).
 
7668
 
 
7669
   * The files on the server should reflect the latest version (of
 
7670
     course!) and it should also contain a RCS directory with the
 
7671
     corresponding archives (I don't have this now).
 
7672
 
 
7673
   * There should also be a ChangeLog file (this is more useful than the
 
7674
     RCS archive but can be generated automatically from the later by
 
7675
     Emacs).
 
7676
 
 
7677
   * A "core group" should judge about questionable changes (for now
 
7678
     this group consists solely by me but I ask some others
 
7679
     occasionally; this also seems to work).
 
7680
 
 
7681
 
 
7682
 
 
7683
File: gettext.info,  Node: Mailing Lists,  Prev: National Teams,  Up: Organization
 
7684
 
 
7685
Mailing Lists
 
7686
-------------
 
7687
 
 
7688
If we get any inquiries about GNU `gettext', send them on to:
 
7689
 
 
7690
     `translation@iro.umontreal.ca'
 
7691
 
 
7692
   The `*-pretest' lists are quite useful to me, maybe the idea could
 
7693
be generalized to many GNU, and non-GNU packages.  But each maintainer
 
7694
his/her way!
 
7695
 
 
7696
   Franc,ois, we have a mechanism in place here at `gnu.ai.mit.edu' to
 
7697
track teams, support mailing lists for them and log members.  We have a
 
7698
slight preference that you use it.  If this is OK with you, I can get
 
7699
you clued in.
 
7700
 
 
7701
   Things are changing!  A few years ago, when Daniel Fekete and I
 
7702
asked for a mailing list for GNU localization, nested at the FSF, we
 
7703
were politely invited to organize it anywhere else, and so did we.  For
 
7704
communicating with my pretesters, I later made a handful of mailing
 
7705
lists located at iro.umontreal.ca and administrated by `majordomo'.
 
7706
These lists have been _very_ dependable so far...
 
7707
 
 
7708
   I suspect that the German team will organize itself a mailing list
 
7709
located in Germany, and so forth for other countries.  But before they
 
7710
organize for true, it could surely be useful to offer mailing lists
 
7711
located at the FSF to each national team.  So yes, please explain me
 
7712
how I should proceed to create and handle them.
 
7713
 
 
7714
   We should create temporary mailing lists, one per country, to help
 
7715
people organize.  Temporary, because once regrouped and structured, it
 
7716
would be fair the volunteers from country bring back _their_ list in
 
7717
there and manage it as they want.  My feeling is that, in the long run,
 
7718
each team should run its own list, from within their country.  There
 
7719
also should be some central list to which all teams could subscribe as
 
7720
they see fit, as long as each team is represented in it.
 
7721
 
 
7722
 
 
7723
File: gettext.info,  Node: Information Flow,  Next: Prioritizing messages,  Prev: Organization,  Up: Translators
 
7724
 
 
7725
Information Flow
 
7726
================
 
7727
 
 
7728
There will surely be some discussion about this messages after the
 
7729
packages are finally released.  If people now send you some proposals
 
7730
for better messages, how do you proceed?  Jim, please note that right
 
7731
now, as I put forward nearly a dozen of localizable programs, I receive
 
7732
both the translations and the coordination concerns about them.
 
7733
 
 
7734
   If I put one of my things to pretest, Ulrich receives the
 
7735
announcement and passes it on to the German team, who make last minute
 
7736
revisions.  Then he submits the translation files to me _as the
 
7737
maintainer_.  For free packages I do not maintain, I would not even
 
7738
hear about it.  This scheme could be made to work for the whole
 
7739
Translation Project, I think.  For security reasons, maybe Ulrich
 
7740
(national coordinators, in fact) should update central registry kept at
 
7741
the Translation Project (Jim, me, or Len's recruits) once in a while.
 
7742
 
 
7743
   In December/January, I was aggressively ready to internationalize
 
7744
all of GNU, giving myself the duty of one small GNU package per week or
 
7745
so, taking many weeks or months for bigger packages.  But it does not
 
7746
work this way.  I first did all the things I'm responsible for.  I've
 
7747
nothing against some missionary work on other maintainers, but I'm also
 
7748
loosing a lot of energy over it--same debates over again.
 
7749
 
 
7750
   And when the first localized packages are released we'll get a lot of
 
7751
responses about ugly translations :-).  Surely, and we need to have
 
7752
beforehand a fairly good idea about how to handle the information flow
 
7753
between the national teams and the package maintainers.
 
7754
 
 
7755
   Please start saving somewhere a quick history of each PO file.  I
 
7756
know for sure that the file format will change, allowing for comments.
 
7757
It would be nice that each file has a kind of log, and references for
 
7758
those who want to submit comments or gripes, or otherwise contribute.
 
7759
I sent a proposal for a fast and flexible format, but it is not
 
7760
receiving acceptance yet by the GNU deciders.  I'll tell you when I
 
7761
have more information about this.
 
7762
 
 
7763
 
 
7764
File: gettext.info,  Node: Prioritizing messages,  Prev: Information Flow,  Up: Translators
 
7765
 
 
7766
Prioritizing messages: How to determine which messages to translate first
 
7767
=========================================================================
 
7768
 
 
7769
A translator sometimes has only a limited amount of time per week to
 
7770
spend on a package, and some packages have quite large message catalogs
 
7771
(over 1000 messages).  Therefore she wishes to translate the messages
 
7772
first that are the most visible to the user, or that occur most
 
7773
frequently.  This section describes how to determine these "most
 
7774
urgent" messages.  It also applies to determine the "next most urgent"
 
7775
messages after the message catalog has already been partially
 
7776
translated.
 
7777
 
 
7778
   In a first step, she uses the programs like a user would do.  While
 
7779
she does this, the GNU `gettext' library logs into a file the not yet
 
7780
translated messages for which a translation was requested from the
 
7781
program.
 
7782
 
 
7783
   In a second step, she uses the PO mode to translate precisely this
 
7784
set of messages.
 
7785
 
 
7786
   Here a more details.  The GNU `libintl' library (but not the
 
7787
corresponding functions in GNU `libc') supports an environment variable
 
7788
`GETTEXT_LOG_UNTRANSLATED'.  The GNU `libintl' library will log into
 
7789
this file the messages for which `gettext()' and related functions
 
7790
couldn't find the translation.  If the file doesn't exist, it will be
 
7791
created as needed.  On systems with GNU `libc' a shared library
 
7792
`preloadable_libintl.so' is provided that can be used with the ELF
 
7793
`LD_PRELOAD' mechanism.
 
7794
 
 
7795
   So, in the first step, the translator uses these commands on systems
 
7796
with GNU `libc':
 
7797
 
 
7798
     $ LD_PRELOAD=/usr/local/lib/preloadable_libintl.so
 
7799
     $ export LD_PRELOAD
 
7800
     $ GETTEXT_LOG_UNTRANSLATED=$HOME/gettextlogused
 
7801
     $ export GETTEXT_LOG_UNTRANSLATED
 
7802
 
 
7803
and these commands on other systems:
 
7804
 
 
7805
     $ GETTEXT_LOG_UNTRANSLATED=$HOME/gettextlogused
 
7806
     $ export GETTEXT_LOG_UNTRANSLATED
 
7807
 
 
7808
   Then she uses and peruses the programs.  (It is a good and
 
7809
recommended practice to use the programs for which you provide
 
7810
translations: it gives you the needed context.)  When done, she removes
 
7811
the environment variables:
 
7812
 
 
7813
     $ unset LD_PRELOAD
 
7814
     $ unset GETTEXT_LOG_UNTRANSLATED
 
7815
 
 
7816
   The second step starts with removing duplicates:
 
7817
 
 
7818
     $ msguniq $HOME/gettextlogused > missing.po
 
7819
 
 
7820
   The result is a PO file, but needs some preprocessing before the
 
7821
Emacs PO mode can be used with it.  First, it is a multi-domain PO
 
7822
file, containing messages from many translation domains.  Second, it
 
7823
lacks all translator comments and source references.  Here is how to
 
7824
get a list of the affected translation domains:
 
7825
 
 
7826
     $ sed -n -e 's,^domain "\(.*\)"$,\1,p' < missing.po | sort | uniq
 
7827
 
 
7828
   Then the translator can handle the domains one by one.  For
 
7829
simplicity, let's use environment variables to denote the language,
 
7830
domain and source package.
 
7831
 
 
7832
     $ lang=nl             # your language
 
7833
     $ domain=coreutils    # the name of the domain to be handled
 
7834
     $ package=/usr/src/gnu/coreutils-4.5.4   # the package where it comes from
 
7835
 
 
7836
   She takes the latest copy of `$lang.po' from the Translation Project,
 
7837
or from the package (in most cases, `$package/po/$lang.po'), or creates
 
7838
a fresh one if she's the first translator (see *Note Creating::).  She
 
7839
then uses the following commands to mark the not urgent messages as
 
7840
"obsolete".  (This doesn't mean that these messages - translated and
 
7841
untranslated ones - will go away.  It simply means that Emacs PO mode
 
7842
will ignore them in the following editing session.)
 
7843
 
 
7844
     $ msggrep --domain=$domain missing.po | grep -v '^domain' \
 
7845
       > $domain-missing.po
 
7846
     $ msgattrib --set-obsolete --ignore-file $domain-missing.po $domain.$lang.po \
 
7847
       > $domain.$lang-urgent.po
 
7848
 
 
7849
   The she translates `$domain.$lang-urgent.po' by use of Emacs PO mode.
 
7850
(FIXME: I don't know whether `KBabel' and `gtranslator' also preserve
 
7851
obsolete messages, as they should.)  Finally she restores the not
 
7852
urgent messages (with their earlier translations, for those which were
 
7853
already translated) through this command:
 
7854
 
 
7855
     $ msgmerge --no-fuzzy-matching $domain.$lang-urgent.po $package/po/$domain.pot \
 
7856
       > $domain.$lang.po
 
7857
 
 
7858
   Then she can submit `$domain.$lang.po' and proceed to the next
 
7859
domain.
 
7860
 
 
7861
 
 
7862
File: gettext.info,  Node: Maintainers,  Next: Programming Languages,  Prev: Translators,  Up: Top
 
7863
 
 
7864
The Maintainer's View
 
7865
*********************
 
7866
 
 
7867
The maintainer of a package has many responsibilities.  One of them is
 
7868
ensuring that the package will install easily on many platforms, and
 
7869
that the magic we described earlier (*note Users::) will work for
 
7870
installers and end users.
 
7871
 
 
7872
   Of course, there are many possible ways by which GNU `gettext' might
 
7873
be integrated in a distribution, and this chapter does not cover them
 
7874
in all generality.  Instead, it details one possible approach which is
 
7875
especially adequate for many free software distributions following GNU
 
7876
standards, or even better, Gnits standards, because GNU `gettext' is
 
7877
purposely for helping the internationalization of the whole GNU
 
7878
project, and as many other good free packages as possible.  So, the
 
7879
maintainer's view presented here presumes that the package already has
 
7880
a `configure.in' file and uses GNU Autoconf.
 
7881
 
 
7882
   Nevertheless, GNU `gettext' may surely be useful for free packages
 
7883
not following GNU standards and conventions, but the maintainers of such
 
7884
packages might have to show imagination and initiative in organizing
 
7885
their distributions so `gettext' work for them in all situations.
 
7886
There are surely many, out there.
 
7887
 
 
7888
   Even if `gettext' methods are now stabilizing, slight adjustments
 
7889
might be needed between successive `gettext' versions, so you should
 
7890
ideally revise this chapter in subsequent releases, looking for changes.
 
7891
 
 
7892
* Menu:
 
7893
 
 
7894
* Flat and Non-Flat::           Flat or Non-Flat Directory Structures
 
7895
* Prerequisites::               Prerequisite Works
 
7896
* gettextize Invocation::       Invoking the `gettextize' Program
 
7897
* Adjusting Files::             Files You Must Create or Alter
 
7898
* autoconf macros::             Autoconf macros for use in `configure.in'
 
7899
* CVS Issues::                  Integrating with CVS
 
7900
 
 
7901
 
 
7902
File: gettext.info,  Node: Flat and Non-Flat,  Next: Prerequisites,  Prev: Maintainers,  Up: Maintainers
 
7903
 
 
7904
Flat or Non-Flat Directory Structures
 
7905
=====================================
 
7906
 
 
7907
Some free software packages are distributed as `tar' files which unpack
 
7908
in a single directory, these are said to be "flat" distributions.
 
7909
Other free software packages have a one level hierarchy of
 
7910
subdirectories, using for example a subdirectory named `doc/' for the
 
7911
Texinfo manual and man pages, another called `lib/' for holding
 
7912
functions meant to replace or complement C libraries, and a
 
7913
subdirectory `src/' for holding the proper sources for the package.
 
7914
These other distributions are said to be "non-flat".
 
7915
 
 
7916
   We cannot say much about flat distributions.  A flat directory
 
7917
structure has the disadvantage of increasing the difficulty of updating
 
7918
to a new version of GNU `gettext'.  Also, if you have many PO files,
 
7919
this could somewhat pollute your single directory.  Also, GNU
 
7920
`gettext''s libintl sources consist of C sources, shell scripts, `sed'
 
7921
scripts and complicated Makefile rules, which don't fit well into an
 
7922
existing flat structure.  For these reasons, we recommend to use
 
7923
non-flat approach in this case as well.
 
7924
 
 
7925
   Maybe because GNU `gettext' itself has a non-flat structure, we have
 
7926
more experience with this approach, and this is what will be described
 
7927
in the remaining of this chapter.  Some maintainers might use this as
 
7928
an opportunity to unflatten their package structure.
 
7929
 
 
7930
 
 
7931
File: gettext.info,  Node: Prerequisites,  Next: gettextize Invocation,  Prev: Flat and Non-Flat,  Up: Maintainers
 
7932
 
 
7933
Prerequisite Works
 
7934
==================
 
7935
 
 
7936
There are some works which are required for using GNU `gettext' in one
 
7937
of your package.  These works have some kind of generality that escape
 
7938
the point by point descriptions used in the remainder of this chapter.
 
7939
So, we describe them here.
 
7940
 
 
7941
   * Before attempting to use `gettextize' you should install some
 
7942
     other packages first.  Ensure that recent versions of GNU `m4',
 
7943
     GNU Autoconf and GNU `gettext' are already installed at your site,
 
7944
     and if not, proceed to do this first.  If you get to install these
 
7945
     things, beware that GNU `m4' must be fully installed before GNU
 
7946
     Autoconf is even _configured_.
 
7947
 
 
7948
     To further ease the task of a package maintainer the `automake'
 
7949
     package was designed and implemented.  GNU `gettext' now uses this
 
7950
     tool and the `Makefile's in the `intl/' and `po/' therefore know
 
7951
     about all the goals necessary for using `automake' and `libintl'
 
7952
     in one project.
 
7953
 
 
7954
     Those four packages are only needed by you, as a maintainer; the
 
7955
     installers of your own package and end users do not really need
 
7956
     any of GNU `m4', GNU Autoconf, GNU `gettext', or GNU `automake'
 
7957
     for successfully installing and running your package, with messages
 
7958
     properly translated.  But this is not completely true if you
 
7959
     provide internationalized shell scripts within your own package:
 
7960
     GNU `gettext' shall then be installed at the user site if the end
 
7961
     users want to see the translation of shell script messages.
 
7962
 
 
7963
   * Your package should use Autoconf and have a `configure.in' or
 
7964
     `configure.ac' file.  If it does not, you have to learn how.  The
 
7965
     Autoconf documentation is quite well written, it is a good idea
 
7966
     that you print it and get familiar with it.
 
7967
 
 
7968
   * Your C sources should have already been modified according to
 
7969
     instructions given earlier in this manual.  *Note Sources::.
 
7970
 
 
7971
   * Your `po/' directory should receive all PO files submitted to you
 
7972
     by the translator teams, each having `LL.po' as a name.  This is
 
7973
     not usually easy to get translation work done before your package
 
7974
     gets internationalized and available!  Since the cycle has to
 
7975
     start somewhere, the easiest for the maintainer is to start with
 
7976
     absolutely no PO files, and wait until various translator teams
 
7977
     get interested in your package, and submit PO files.
 
7978
 
 
7979
 
 
7980
   It is worth adding here a few words about how the maintainer should
 
7981
ideally behave with PO files submissions.  As a maintainer, your role is
 
7982
to authenticate the origin of the submission as being the representative
 
7983
of the appropriate translating teams of the Translation Project (forward
 
7984
the submission to `translation@iro.umontreal.ca' in case of doubt), to
 
7985
ensure that the PO file format is not severely broken and does not
 
7986
prevent successful installation, and for the rest, to merely put these
 
7987
PO files in `po/' for distribution.
 
7988
 
 
7989
   As a maintainer, you do not have to take on your shoulders the
 
7990
responsibility of checking if the translations are adequate or
 
7991
complete, and should avoid diving into linguistic matters.  Translation
 
7992
teams drive themselves and are fully responsible of their linguistic
 
7993
choices for the Translation Project.  Keep in mind that translator
 
7994
teams are _not_ driven by maintainers.  You can help by carefully
 
7995
redirecting all communications and reports from users about linguistic
 
7996
matters to the appropriate translation team, or explain users how to
 
7997
reach or join their team.  The simplest might be to send them the
 
7998
`ABOUT-NLS' file.
 
7999
 
 
8000
   Maintainers should _never ever_ apply PO file bug reports
 
8001
themselves, short-cutting translation teams.  If some translator has
 
8002
difficulty to get some of her points through her team, it should not be
 
8003
an option for her to directly negotiate translations with maintainers.
 
8004
Teams ought to settle their problems themselves, if any.  If you, as a
 
8005
maintainer, ever think there is a real problem with a team, please
 
8006
never try to _solve_ a team's problem on your own.
 
8007
 
 
8008
 
 
8009
File: gettext.info,  Node: gettextize Invocation,  Next: Adjusting Files,  Prev: Prerequisites,  Up: Maintainers
 
8010
 
 
8011
Invoking the `gettextize' Program
 
8012
=================================
 
8013
 
 
8014
The `gettextize' program is an interactive tool that helps the
 
8015
maintainer of a package internationalized through GNU `gettext'.  It is
 
8016
used for two purposes:
 
8017
 
 
8018
   * As a wizard, when a package is modified to use GNU `gettext' for
 
8019
     the first time.
 
8020
 
 
8021
   * As a migration tool, for upgrading the GNU `gettext' support in a
 
8022
     package from a previous to a newer version of GNU `gettext'.
 
8023
 
 
8024
   This program performs the following tasks:
 
8025
 
 
8026
   * It copies into the package some files that are consistently and
 
8027
     identically needed in every package internationalized through GNU
 
8028
     `gettext'.
 
8029
 
 
8030
   * It performs as many of the tasks mentioned in the next section
 
8031
     *Note Adjusting Files:: as can be performed automatically.
 
8032
 
 
8033
   * It removes obsolete files and idioms used for previous GNU
 
8034
     `gettext' versions to the form recommended for the current GNU
 
8035
     `gettext' version.
 
8036
 
 
8037
   * It prints a summary of the tasks that ought to be done manually
 
8038
     and could not be done automatically by `gettextize'.
 
8039
 
 
8040
   It can be invoked as follows:
 
8041
 
 
8042
     gettextize [ OPTION... ] [ DIRECTORY ]
 
8043
 
 
8044
and accepts the following options:
 
8045
 
 
8046
`-c'
 
8047
`--copy'
 
8048
     Copy the needed files instead of making symbolic links.  Using
 
8049
     links would allow the package to always use the latest `gettext'
 
8050
     code available on the system, but it might disturb some mechanism
 
8051
     the maintainer is used to apply to the sources.  Because running
 
8052
     `gettextize' is easy there shouldn't be problems with using copies.
 
8053
 
 
8054
`-f'
 
8055
`--force'
 
8056
     Force replacement of files which already exist.
 
8057
 
 
8058
`--intl'
 
8059
     Install the libintl sources in a subdirectory named `intl/'.  This
 
8060
     libintl will be used to provide internationalization on systems
 
8061
     that don't have GNU libintl installed.  If this option is omitted,
 
8062
     the call to `AM_GNU_GETTEXT' in `configure.in' should read:
 
8063
     `AM_GNU_GETTEXT([external])', and internationalization will not be
 
8064
     enabled on systems lacking GNU gettext.
 
8065
 
 
8066
`--no-changelog'
 
8067
     Don't update or create ChangeLog files.  By default, `gettextize'
 
8068
     logs all changes (file additions, modifications and removals) in a
 
8069
     file called `ChangeLog' in each affected directory.
 
8070
 
 
8071
`-n'
 
8072
`--dry-run'
 
8073
     Print modifications but don't perform them.  All actions that
 
8074
     `gettextize' would normally execute are inhibited and instead only
 
8075
     listed on standard output.
 
8076
 
 
8077
`--help'
 
8078
     Display this help and exit.
 
8079
 
 
8080
`--version'
 
8081
     Output version information and exit.
 
8082
 
 
8083
 
 
8084
   If DIRECTORY is given, this is the top level directory of a package
 
8085
to prepare for using GNU `gettext'.  If not given, it is assumed that
 
8086
the current directory is the top level directory of such a package.
 
8087
 
 
8088
   The program `gettextize' provides the following files.  However, no
 
8089
existing file will be replaced unless the option `--force' (`-f') is
 
8090
specified.
 
8091
 
 
8092
  1. The `ABOUT-NLS' file is copied in the main directory of your
 
8093
     package, the one being at the top level.  This file gives the main
 
8094
     indications about how to install and use the Native Language
 
8095
     Support features of your program.  You might elect to use a more
 
8096
     recent copy of this `ABOUT-NLS' file than the one provided through
 
8097
     `gettextize', if you have one handy.  You may also fetch a more
 
8098
     recent copy of file `ABOUT-NLS' from Translation Project sites,
 
8099
     and from most GNU archive sites.
 
8100
 
 
8101
  2. A `po/' directory is created for eventually holding all
 
8102
     translation files, but initially only containing the file
 
8103
     `po/Makefile.in.in' from the GNU `gettext' distribution (beware
 
8104
     the double `.in' in the file name) and a few auxiliary files.  If
 
8105
     the `po/' directory already exists, it will be preserved along
 
8106
     with the files it contains, and only `Makefile.in.in' and the
 
8107
     auxiliary files will be overwritten.
 
8108
 
 
8109
  3. Only if `--intl' has been specified: A `intl/' directory is
 
8110
     created and filled with most of the files originally in the
 
8111
     `intl/' directory of the GNU `gettext' distribution.  Also, if
 
8112
     option `--force' (`-f') is given, the `intl/' directory is emptied
 
8113
     first.
 
8114
 
 
8115
  4. The files `config.rpath' and `mkinstalldirs' are copied into the
 
8116
     directory containing configuration support files.  It is needed by
 
8117
     the `AM_GNU_GETTEXT' autoconf macro.
 
8118
 
 
8119
  5. Only if the project is using GNU `automake': A set of `autoconf'
 
8120
     macro files is copied into the package's `autoconf' macro
 
8121
     repository, usually in a directory called `m4/'.
 
8122
 
 
8123
   If your site support symbolic links, `gettextize' will not actually
 
8124
copy the files into your package, but establish symbolic links instead.
 
8125
This avoids duplicating the disk space needed in all packages.  Merely
 
8126
using the `-h' option while creating the `tar' archive of your
 
8127
distribution will resolve each link by an actual copy in the
 
8128
distribution archive.  So, to insist, you really should use `-h' option
 
8129
with `tar' within your `dist' goal of your main `Makefile.in'.
 
8130
 
 
8131
   Furthermore, `gettextize' will update all `Makefile.am' files in
 
8132
each affected directory, as well as the top level `configure.in' or
 
8133
`configure.ac' file.
 
8134
 
 
8135
   It is interesting to understand that most new files for supporting
 
8136
GNU `gettext' facilities in one package go in `intl/', `po/' and `m4/'
 
8137
subdirectories.  One distinction between `intl/' and the two other
 
8138
directories is that `intl/' is meant to be completely identical in all
 
8139
packages using GNU `gettext', while the other directories will mostly
 
8140
contain package dependent files.
 
8141
 
 
8142
   The `gettextize' program makes backup files for all files it
 
8143
replaces or changes, and also write ChangeLog entries about these
 
8144
changes.  This way, the careful maintainer can check after running
 
8145
`gettextize' whether its changes are acceptable to him, and possibly
 
8146
adjust them.  An exception to this rule is the `intl/' directory, which
 
8147
is added or replaced or removed as a whole.
 
8148
 
 
8149
   It is important to understand that `gettextize' can not do the
 
8150
entire job of adapting a package for using GNU `gettext'.  The amount
 
8151
of remaining work depends on whether the package uses GNU `automake' or
 
8152
not.  But in any case, the maintainer should still read the section
 
8153
*Note Adjusting Files:: after invoking `gettextize'.
 
8154
 
 
8155
   It is also important to understand that `gettextize' is not part of
 
8156
the GNU build system, in the sense that it should not be invoked
 
8157
automatically, and not be invoked by someone who doesn't assume the
 
8158
responsibilities of a package maintainer.  For the latter purpose, a
 
8159
separate tool is provided, see *Note autopoint Invocation::.
 
8160
 
 
8161
 
 
8162
File: gettext.info,  Node: Adjusting Files,  Next: autoconf macros,  Prev: gettextize Invocation,  Up: Maintainers
 
8163
 
 
8164
Files You Must Create or Alter
 
8165
==============================
 
8166
 
 
8167
Besides files which are automatically added through `gettextize', there
 
8168
are many files needing revision for properly interacting with GNU
 
8169
`gettext'.  If you are closely following GNU standards for Makefile
 
8170
engineering and auto-configuration, the adaptations should be easier to
 
8171
achieve.  Here is a point by point description of the changes needed in
 
8172
each.
 
8173
 
 
8174
   So, here comes a list of files, each one followed by a description of
 
8175
all alterations it needs.  Many examples are taken out from the GNU
 
8176
`gettext' 0.14.1 distribution itself, or from the GNU `hello'
 
8177
distribution (`http://www.franken.de/users/gnu/ke/hello' or
 
8178
`http://www.gnu.franken.de/ke/hello/')  You may indeed refer to the
 
8179
source code of the GNU `gettext' and GNU `hello' packages, as they are
 
8180
intended to be good examples for using GNU gettext functionality.
 
8181
 
 
8182
* Menu:
 
8183
 
 
8184
* po/POTFILES.in::              `POTFILES.in' in `po/'
 
8185
* po/LINGUAS::                  `LINGUAS' in `po/'
 
8186
* po/Makevars::                 `Makefile' pieces in `po/'
 
8187
* configure.in::                `configure.in' at top level
 
8188
* config.guess::                `config.guess', `config.sub' at top level
 
8189
* mkinstalldirs::               `mkinstalldirs' at top level
 
8190
* aclocal::                     `aclocal.m4' at top level
 
8191
* acconfig::                    `acconfig.h' at top level
 
8192
* config.h.in::                 `config.h.in' at top level
 
8193
* Makefile::                    `Makefile.in' at top level
 
8194
* src/Makefile::                `Makefile.in' in `src/'
 
8195
* lib/gettext.h::               `gettext.h' in `lib/'
 
8196
 
 
8197
 
 
8198
File: gettext.info,  Node: po/POTFILES.in,  Next: po/LINGUAS,  Prev: Adjusting Files,  Up: Adjusting Files
 
8199
 
 
8200
`POTFILES.in' in `po/'
 
8201
----------------------
 
8202
 
 
8203
The `po/' directory should receive a file named `POTFILES.in'.  This
 
8204
file tells which files, among all program sources, have marked strings
 
8205
needing translation.  Here is an example of such a file:
 
8206
 
 
8207
     # List of source files containing translatable strings.
 
8208
     # Copyright (C) 1995 Free Software Foundation, Inc.
 
8209
     
 
8210
     # Common library files
 
8211
     lib/error.c
 
8212
     lib/getopt.c
 
8213
     lib/xmalloc.c
 
8214
     
 
8215
     # Package source files
 
8216
     src/gettext.c
 
8217
     src/msgfmt.c
 
8218
     src/xgettext.c
 
8219
 
 
8220
Hash-marked comments and white lines are ignored.  All other lines list
 
8221
those source files containing strings marked for translation (*note
 
8222
Mark Keywords::), in a notation relative to the top level of your whole
 
8223
distribution, rather than the location of the `POTFILES.in' file itself.
 
8224
 
 
8225
   When a C file is automatically generated by a tool, like `flex' or
 
8226
`bison', that doesn't introduce translatable strings by itself, it is
 
8227
recommended to list in `po/POTFILES.in' the real source file (ending in
 
8228
`.l' in the case of `flex', or in `.y' in the case of `bison'), not the
 
8229
generated C file.
 
8230
 
 
8231
 
 
8232
File: gettext.info,  Node: po/LINGUAS,  Next: po/Makevars,  Prev: po/POTFILES.in,  Up: Adjusting Files
 
8233
 
 
8234
`LINGUAS' in `po/'
 
8235
------------------
 
8236
 
 
8237
The `po/' directory should also receive a file named `LINGUAS'.  This
 
8238
file contains the list of available translations.  It is a whitespace
 
8239
separated list.  Hash-marked comments and white lines are ignored.
 
8240
Here is an example file:
 
8241
 
 
8242
     # Set of available languages.
 
8243
     de fr
 
8244
 
 
8245
This example means that German and French PO files are available, so
 
8246
that these languages are currently supported by your package.  If you
 
8247
want to further restrict, at installation time, the set of installed
 
8248
languages, this should not be done by modifying the `LINGUAS' file, but
 
8249
rather by using the `LINGUAS' environment variable (*note Installers::).
 
8250
 
 
8251
   It is recommended that you add the "languages" `en@quot' and
 
8252
`en@boldquot' to the `LINGUAS' file.  `en@quot' is a variant of English
 
8253
message catalogs (`en') which uses real quotation marks instead of the
 
8254
ugly looking asymmetric ASCII substitutes ``' and `''.  `en@boldquot'
 
8255
is a variant of `en@quot' that additionally outputs quoted pieces of
 
8256
text in a bold font, when used in a terminal emulator which supports
 
8257
the VT100 escape sequences (such as `xterm' or the Linux console, but
 
8258
not Emacs in `M-x shell' mode).
 
8259
 
 
8260
   These extra message catalogs `en@quot' and `en@boldquot' are
 
8261
constructed automatically, not by translators; to support them, you
 
8262
need the files `Rules-quot', `quot.sed', `boldquot.sed',
 
8263
`en@quot.header', `en@boldquot.header', `insert-header.sin' in the
 
8264
`po/' directory.  You can copy them from GNU gettext's `po/' directory;
 
8265
they are also installed by running `gettextize'.
 
8266
 
 
8267
 
 
8268
File: gettext.info,  Node: po/Makevars,  Next: configure.in,  Prev: po/LINGUAS,  Up: Adjusting Files
 
8269
 
 
8270
`Makefile' pieces in `po/'
 
8271
--------------------------
 
8272
 
 
8273
The `po/' directory also has a file named `Makevars'.  It can be left
 
8274
unmodified if your package has a single message domain and,
 
8275
accordingly, a single `po/' directory.  Only packages which have
 
8276
multiple `po/' directories at different locations need to adjust the
 
8277
three variables defined in `Makevars'.
 
8278
 
 
8279
   `po/Makevars' gets inserted into the `po/Makefile' when the latter
 
8280
is created.  At the same time, all files called `Rules-*' in the `po/'
 
8281
directory get appended to the `po/Makefile'.  They present an
 
8282
opportunity to add rules for special PO files to the Makefile, without
 
8283
needing to mess with `po/Makefile.in.in'.
 
8284
 
 
8285
   GNU gettext comes with a `Rules-quot' file, containing rules for
 
8286
building catalogs `en@quot.po' and `en@boldquot.po'.  The effect of
 
8287
`en@quot.po' is that people who set their `LANGUAGE' environment
 
8288
variable to `en@quot' will get messages with proper looking symmetric
 
8289
Unicode quotation marks instead of abusing the ASCII grave accent and
 
8290
the ASCII apostrophe for indicating quotations.  To enable this
 
8291
catalog, simply add `en@quot' to the `po/LINGUAS' file.  The effect of
 
8292
`en@boldquot.po' is that people who set `LANGUAGE' to `en@boldquot'
 
8293
will get not only proper quotation marks, but also the quoted text will
 
8294
be shown in a bold font on terminals and consoles.  This catalog is
 
8295
useful only for command-line programs, not GUI programs.  To enable it,
 
8296
similarly add `en@boldquot' to the `po/LINGUAS' file.
 
8297
 
 
8298
 
 
8299
File: gettext.info,  Node: configure.in,  Next: config.guess,  Prev: po/Makevars,  Up: Adjusting Files
 
8300
 
 
8301
`configure.in' at top level
 
8302
---------------------------
 
8303
 
 
8304
`configure.in' or `configure.ac' - this is the source from which
 
8305
`autoconf' generates the `configure' script.
 
8306
 
 
8307
  1. Declare the package and version.
 
8308
 
 
8309
     This is done by a set of lines like these:
 
8310
 
 
8311
          PACKAGE=gettext
 
8312
          VERSION=0.14.1
 
8313
          AC_DEFINE_UNQUOTED(PACKAGE, "$PACKAGE")
 
8314
          AC_DEFINE_UNQUOTED(VERSION, "$VERSION")
 
8315
          AC_SUBST(PACKAGE)
 
8316
          AC_SUBST(VERSION)
 
8317
 
 
8318
     or, if you are using GNU `automake', by a line like this:
 
8319
 
 
8320
          AM_INIT_AUTOMAKE(gettext, 0.14.1)
 
8321
 
 
8322
     Of course, you replace `gettext' with the name of your package,
 
8323
     and `0.14.1' by its version numbers, exactly as they should appear
 
8324
     in the packaged `tar' file name of your distribution
 
8325
     (`gettext-0.14.1.tar.gz', here).
 
8326
 
 
8327
  2. Check for internationalization support.
 
8328
 
 
8329
     Here is the main `m4' macro for triggering internationalization
 
8330
     support.  Just add this line to `configure.in':
 
8331
 
 
8332
          AM_GNU_GETTEXT
 
8333
 
 
8334
     This call is purposely simple, even if it generates a lot of
 
8335
     configure time checking and actions.
 
8336
 
 
8337
     If you have suppressed the `intl/' subdirectory by calling
 
8338
     `gettextize' without `--intl' option, this call should read
 
8339
 
 
8340
          AM_GNU_GETTEXT([external])
 
8341
 
 
8342
  3. Have output files created.
 
8343
 
 
8344
     The `AC_OUTPUT' directive, at the end of your `configure.in' file,
 
8345
     needs to be modified in two ways:
 
8346
 
 
8347
          AC_OUTPUT([EXISTING CONFIGURATION FILES intl/Makefile po/Makefile.in],
 
8348
          [EXISTING ADDITIONAL ACTIONS])
 
8349
 
 
8350
     The modification to the first argument to `AC_OUTPUT' asks for
 
8351
     substitution in the `intl/' and `po/' directories.  Note the `.in'
 
8352
     suffix used for `po/' only.  This is because the distributed file
 
8353
     is really `po/Makefile.in.in'.
 
8354
 
 
8355
     If you have suppressed the `intl/' subdirectory by calling
 
8356
     `gettextize' without `--intl' option, then you don't need to add
 
8357
     `intl/Makefile' to the `AC_OUTPUT' line.
 
8358
 
 
8359
 
 
8360
 
 
8361
File: gettext.info,  Node: config.guess,  Next: mkinstalldirs,  Prev: configure.in,  Up: Adjusting Files
 
8362
 
 
8363
`config.guess', `config.sub' at top level
 
8364
-----------------------------------------
 
8365
 
 
8366
If you haven't suppressed the `intl/' subdirectory, you need to add the
 
8367
GNU `config.guess' and `config.sub' files to your distribution.  They
 
8368
are needed because the `intl/' directory has platform dependent support
 
8369
for determining the locale's character encoding and therefore needs to
 
8370
identify the platform.
 
8371
 
 
8372
   You can obtain the newest version of `config.guess' and `config.sub'
 
8373
from `ftp://ftp.gnu.org/pub/gnu/config/'.  Less recent versions are
 
8374
also contained in the GNU `automake' and GNU `libtool' packages.
 
8375
 
 
8376
   Normally, `config.guess' and `config.sub' are put at the top level
 
8377
of a distribution.  But it is also possible to put them in a
 
8378
subdirectory, altogether with other configuration support files like
 
8379
`install-sh', `ltconfig', `ltmain.sh', `mkinstalldirs' or `missing'.
 
8380
All you need to do, other than moving the files, is to add the
 
8381
following line to your `configure.in'.
 
8382
 
 
8383
     AC_CONFIG_AUX_DIR([SUBDIR])
 
8384
 
 
8385
 
 
8386
File: gettext.info,  Node: mkinstalldirs,  Next: aclocal,  Prev: config.guess,  Up: Adjusting Files
 
8387
 
 
8388
`mkinstalldirs' at top level
 
8389
----------------------------
 
8390
 
 
8391
If `gettextize' has not already done it, you need to add the GNU
 
8392
`mkinstalldirs' script to your distribution.  It is needed because
 
8393
`mkdir -p' is not portable enough.  You find this script in the GNU
 
8394
`automake' distribution.
 
8395
 
 
8396
   Normally, `mkinstalldirs' is put at the top level of a distribution.
 
8397
But it is also possible to put it in a subdirectory, altogether with
 
8398
other configuration support files like `install-sh', `ltconfig',
 
8399
`ltmain.sh' or `missing'.  All you need to do, other than moving the
 
8400
files, is to add the following line to your `configure.in'.
 
8401
 
 
8402
     AC_CONFIG_AUX_DIR([SUBDIR])
 
8403
 
 
8404
 
 
8405
File: gettext.info,  Node: aclocal,  Next: acconfig,  Prev: mkinstalldirs,  Up: Adjusting Files
 
8406
 
 
8407
`aclocal.m4' at top level
 
8408
-------------------------
 
8409
 
 
8410
If you do not have an `aclocal.m4' file in your distribution, the
 
8411
simplest is to concatenate the files `codeset.m4', `gettext.m4',
 
8412
`glibc21.m4', `iconv.m4', `intdiv0.m4', `intmax.m4', `inttypes.m4',
 
8413
`inttypes_h.m4', `inttypes-pri.m4', `isc-posix.m4', `lcmessage.m4',
 
8414
`lib-ld.m4', `lib-link.m4', `lib-prefix.m4', `longdouble.m4',
 
8415
`longlong.m4', `printf-posix.m4', `progtest.m4', `signed.m4',
 
8416
`size_max.m4', `stdint_h.m4', `uintmax_t.m4', `ulonglong.m4',
 
8417
`wchar_t.m4', `wint_t.m4', `xsize.m4' from GNU `gettext''s `m4/'
 
8418
directory into a single file.  If you have suppressed the `intl/'
 
8419
directory, only `gettext.m4', `iconv.m4', `lib-ld.m4', `lib-link.m4',
 
8420
`lib-prefix.m4', `progtest.m4' need to be concatenated.
 
8421
 
 
8422
   If you already have an `aclocal.m4' file, then you will have to
 
8423
merge the said macro files into your `aclocal.m4'.  Note that if you
 
8424
are upgrading from a previous release of GNU `gettext', you should most
 
8425
probably _replace_ the macros (`AM_GNU_GETTEXT', etc.), as they usually
 
8426
change a little from one release of GNU `gettext' to the next.  Their
 
8427
contents may vary as we get more experience with strange systems out
 
8428
there.
 
8429
 
 
8430
   If you are using GNU `automake' 1.5 or newer, it is enough to put
 
8431
these macro files into a subdirectory named `m4/' and add the line
 
8432
 
 
8433
     ACLOCAL_AMFLAGS = -I m4
 
8434
 
 
8435
to your top level `Makefile.am'.
 
8436
 
 
8437
   These macros check for the internationalization support functions
 
8438
and related informations.  Hopefully, once stabilized, these macros
 
8439
might be integrated in the standard Autoconf set, because this piece of
 
8440
`m4' code will be the same for all projects using GNU `gettext'.
 
8441
 
 
8442
 
 
8443
File: gettext.info,  Node: acconfig,  Next: config.h.in,  Prev: aclocal,  Up: Adjusting Files
 
8444
 
 
8445
`acconfig.h' at top level
 
8446
-------------------------
 
8447
 
 
8448
Earlier GNU `gettext' releases required to put definitions for
 
8449
`ENABLE_NLS', `HAVE_GETTEXT' and `HAVE_LC_MESSAGES', `HAVE_STPCPY',
 
8450
`PACKAGE' and `VERSION' into an `acconfig.h' file.  This is not needed
 
8451
any more; you can remove them from your `acconfig.h' file unless your
 
8452
package uses them independently from the `intl/' directory.
 
8453
 
 
8454
 
 
8455
File: gettext.info,  Node: config.h.in,  Next: Makefile,  Prev: acconfig,  Up: Adjusting Files
 
8456
 
 
8457
`config.h.in' at top level
 
8458
--------------------------
 
8459
 
 
8460
The include file template that holds the C macros to be defined by
 
8461
`configure' is usually called `config.h.in' and may be maintained
 
8462
either manually or automatically.
 
8463
 
 
8464
   If it is maintained automatically, by use of the `autoheader'
 
8465
program, you need to do nothing about it.  This is the case in
 
8466
particular if you are using GNU `automake'.
 
8467
 
 
8468
   If it is maintained manually, and if `gettextize' has created an
 
8469
`intl/' directory, you should switch to using `autoheader'.  The list
 
8470
of C macros to be added for the sake of the `intl/' directory is just
 
8471
too long to be maintained manually; it also changes between different
 
8472
versions of GNU `gettext'.
 
8473
 
 
8474
   If it is maintained manually, and if on the other hand you have
 
8475
suppressed the `intl/' directory by calling `gettextize' without
 
8476
`--intl' option, then you can get away by adding the following lines to
 
8477
`config.h.in':
 
8478
 
 
8479
     /* Define to 1 if translation of program messages to the user's
 
8480
        native language is requested. */
 
8481
     #undef ENABLE_NLS
 
8482
 
 
8483
 
 
8484
File: gettext.info,  Node: Makefile,  Next: src/Makefile,  Prev: config.h.in,  Up: Adjusting Files
 
8485
 
 
8486
`Makefile.in' at top level
 
8487
--------------------------
 
8488
 
 
8489
Here are a few modifications you need to make to your main, top-level
 
8490
`Makefile.in' file.
 
8491
 
 
8492
  1. Add the following lines near the beginning of your `Makefile.in',
 
8493
     so the `dist:' goal will work properly (as explained further down):
 
8494
 
 
8495
          PACKAGE = @PACKAGE@
 
8496
          VERSION = @VERSION@
 
8497
 
 
8498
  2. Add file `ABOUT-NLS' to the `DISTFILES' definition, so the file
 
8499
     gets distributed.
 
8500
 
 
8501
  3. Wherever you process subdirectories in your `Makefile.in', be sure
 
8502
     you also process the subdirectories `intl' and `po'.  Special
 
8503
     rules in the `Makefiles' take care for the case where no
 
8504
     internationalization is wanted.
 
8505
 
 
8506
     If you are using Makefiles, either generated by automake, or
 
8507
     hand-written so they carefully follow the GNU coding standards,
 
8508
     the effected goals for which the new subdirectories must be
 
8509
     handled include `installdirs', `install', `uninstall', `clean',
 
8510
     `distclean'.
 
8511
 
 
8512
     Here is an example of a canonical order of processing.  In this
 
8513
     example, we also define `SUBDIRS' in `Makefile.in' for it to be
 
8514
     further used in the `dist:' goal.
 
8515
 
 
8516
          SUBDIRS = doc intl lib src po
 
8517
 
 
8518
     Note that you must arrange for `make' to descend into the `intl'
 
8519
     directory before descending into other directories containing code
 
8520
     which make use of the `libintl.h' header file.  For this reason,
 
8521
     here we mention `intl' before `lib' and `src'.
 
8522
 
 
8523
  4. A delicate point is the `dist:' goal, as both `intl/Makefile' and
 
8524
     `po/Makefile' will later assume that the proper directory has been
 
8525
     set up from the main `Makefile'.  Here is an example at what the
 
8526
     `dist:' goal might look like:
 
8527
 
 
8528
          distdir = $(PACKAGE)-$(VERSION)
 
8529
          dist: Makefile
 
8530
                rm -fr $(distdir)
 
8531
                mkdir $(distdir)
 
8532
                chmod 777 $(distdir)
 
8533
                for file in $(DISTFILES); do \
 
8534
                  ln $$file $(distdir) 2>/dev/null || cp -p $$file $(distdir); \
 
8535
                done
 
8536
                for subdir in $(SUBDIRS); do \
 
8537
                  mkdir $(distdir)/$$subdir || exit 1; \
 
8538
                  chmod 777 $(distdir)/$$subdir; \
 
8539
                  (cd $$subdir && $(MAKE) $@) || exit 1; \
 
8540
                done
 
8541
                tar chozf $(distdir).tar.gz $(distdir)
 
8542
                rm -fr $(distdir)
 
8543
 
 
8544
 
 
8545
   Note that if you are using GNU `automake', `Makefile.in' is
 
8546
automatically generated from `Makefile.am', and all needed changes to
 
8547
`Makefile.am' are already made by running `gettextize'.
 
8548
 
 
8549
 
 
8550
File: gettext.info,  Node: src/Makefile,  Next: lib/gettext.h,  Prev: Makefile,  Up: Adjusting Files
 
8551
 
 
8552
`Makefile.in' in `src/'
 
8553
-----------------------
 
8554
 
 
8555
Some of the modifications made in the main `Makefile.in' will also be
 
8556
needed in the `Makefile.in' from your package sources, which we assume
 
8557
here to be in the `src/' subdirectory.  Here are all the modifications
 
8558
needed in `src/Makefile.in':
 
8559
 
 
8560
  1. In view of the `dist:' goal, you should have these lines near the
 
8561
     beginning of `src/Makefile.in':
 
8562
 
 
8563
          PACKAGE = @PACKAGE@
 
8564
          VERSION = @VERSION@
 
8565
 
 
8566
  2. If not done already, you should guarantee that `top_srcdir' gets
 
8567
     defined.  This will serve for `cpp' include files.  Just add the
 
8568
     line:
 
8569
 
 
8570
          top_srcdir = @top_srcdir@
 
8571
 
 
8572
  3. You might also want to define `subdir' as `src', later allowing
 
8573
     for almost uniform `dist:' goals in all your `Makefile.in'.  At
 
8574
     list, the `dist:' goal below assume that you used:
 
8575
 
 
8576
          subdir = src
 
8577
 
 
8578
  4. The `main' function of your program will normally call
 
8579
     `bindtextdomain' (see *note Triggering::), like this:
 
8580
 
 
8581
          bindtextdomain (PACKAGE, LOCALEDIR);
 
8582
          textdomain (PACKAGE);
 
8583
 
 
8584
     To make LOCALEDIR known to the program, add the following lines to
 
8585
     Makefile.in:
 
8586
 
 
8587
          datadir = @datadir@
 
8588
          localedir = $(datadir)/locale
 
8589
          DEFS = -DLOCALEDIR=\"$(localedir)\" @DEFS@
 
8590
 
 
8591
     Note that `@datadir@' defaults to `$(prefix)/share', thus
 
8592
     `$(localedir)' defaults to `$(prefix)/share/locale'.
 
8593
 
 
8594
  5. You should ensure that the final linking will use `@LIBINTL@' or
 
8595
     `@LTLIBINTL@' as a library.  `@LIBINTL@' is for use without
 
8596
     `libtool', `@LTLIBINTL@' is for use with `libtool'.  An easy way
 
8597
     to achieve this is to manage that it gets into `LIBS', like this:
 
8598
 
 
8599
          LIBS = @LIBINTL@ @LIBS@
 
8600
 
 
8601
     In most packages internationalized with GNU `gettext', one will
 
8602
     find a directory `lib/' in which a library containing some helper
 
8603
     functions will be build.  (You need at least the few functions
 
8604
     which the GNU `gettext' Library itself needs.)  However some of
 
8605
     the functions in the `lib/' also give messages to the user which
 
8606
     of course should be translated, too.  Taking care of this, the
 
8607
     support library (say `libsupport.a') should be placed before
 
8608
     `@LIBINTL@' and `@LIBS@' in the above example.  So one has to
 
8609
     write this:
 
8610
 
 
8611
          LIBS = ../lib/libsupport.a @LIBINTL@ @LIBS@
 
8612
 
 
8613
  6. You should also ensure that directory `intl/' will be searched for
 
8614
     C preprocessor include files in all circumstances.  So, you have to
 
8615
     manage so both `-I../intl' and `-I$(top_srcdir)/intl' will be
 
8616
     given to the C compiler.
 
8617
 
 
8618
  7. Your `dist:' goal has to conform with others.  Here is a
 
8619
     reasonable definition for it:
 
8620
 
 
8621
          distdir = ../$(PACKAGE)-$(VERSION)/$(subdir)
 
8622
          dist: Makefile $(DISTFILES)
 
8623
                for file in $(DISTFILES); do \
 
8624
                  ln $$file $(distdir) 2>/dev/null || cp -p $$file $(distdir); \
 
8625
                done
 
8626
 
 
8627
 
 
8628
 
 
8629
File: gettext.info,  Node: lib/gettext.h,  Prev: src/Makefile,  Up: Adjusting Files
 
8630
 
 
8631
`gettext.h' in `lib/'
 
8632
---------------------
 
8633
 
 
8634
Internationalization of packages, as provided by GNU `gettext', is
 
8635
optional.  It can be turned off in two situations:
 
8636
 
 
8637
   * When the installer has specified `./configure --disable-nls'.  This
 
8638
     can be useful when small binaries are more important than
 
8639
     features, for example when building utilities for boot diskettes.
 
8640
     It can also be useful in order to get some specific C compiler
 
8641
     warnings about code quality with some older versions of GCC (older
 
8642
     than 3.0).
 
8643
 
 
8644
   * When the package does not include the `intl/' subdirectory, and the
 
8645
     libintl.h header (with its associated libintl library, if any) is
 
8646
     not already installed on the system, it is preferrable that the
 
8647
     package builds without internationalization support, rather than
 
8648
     to give a compilation error.
 
8649
 
 
8650
   A C preprocessor macro can be used to detect these two cases.
 
8651
Usually, when `libintl.h' was found and not explicitly disabled, the
 
8652
`ENABLE_NLS' macro will be defined to 1 in the autoconf generated
 
8653
configuration file (usually called `config.h').  In the two negative
 
8654
situations, however, this macro will not be defined, thus it will
 
8655
evaluate to 0 in C preprocessor expressions.
 
8656
 
 
8657
   `gettext.h' is a convenience header file for conditional use of
 
8658
`<libintl.h>', depending on the `ENABLE_NLS' macro.  If `ENABLE_NLS' is
 
8659
set, it includes `<libintl.h>'; otherwise it defines no-op substitutes
 
8660
for the libintl.h functions.  We recommend the use of `"gettext.h"'
 
8661
over direct use of `<libintl.h>', so that portability to older systems
 
8662
is guaranteed and installers can turn off internationalization if they
 
8663
want to.  In the C code, you will then write
 
8664
 
 
8665
     #include "gettext.h"
 
8666
 
 
8667
instead of
 
8668
 
 
8669
     #include <libintl.h>
 
8670
 
 
8671
   The location of `gettext.h' is usually in a directory containing
 
8672
auxiliary include files.  In many GNU packages, there is a directory
 
8673
`lib/' containing helper functions; `gettext.h' fits there.  In other
 
8674
packages, it can go into the `src' directory.
 
8675
 
 
8676
   Do not install the `gettext.h' file in public locations.  Every
 
8677
package that needs it should contain a copy of it on its own.
 
8678
 
 
8679
 
 
8680
File: gettext.info,  Node: autoconf macros,  Next: CVS Issues,  Prev: Adjusting Files,  Up: Maintainers
 
8681
 
 
8682
Autoconf macros for use in `configure.in'
 
8683
=========================================
 
8684
 
 
8685
GNU `gettext' installs macros for use in a package's `configure.in' or
 
8686
`configure.ac'.  *Note Introduction: (autoconf)Top.  The primary macro
 
8687
is, of course, `AM_GNU_GETTEXT'.
 
8688
 
 
8689
* Menu:
 
8690
 
 
8691
* AM_GNU_GETTEXT::              AM_GNU_GETTEXT in `gettext.m4'
 
8692
* AM_GNU_GETTEXT_VERSION::      AM_GNU_GETTEXT_VERSION in `gettext.m4'
 
8693
* AM_PO_SUBDIRS::               AM_PO_SUBDIRS in `po.m4'
 
8694
* AM_ICONV::                    AM_ICONV in `iconv.m4'
 
8695
 
 
8696
 
 
8697
File: gettext.info,  Node: AM_GNU_GETTEXT,  Next: AM_GNU_GETTEXT_VERSION,  Prev: autoconf macros,  Up: autoconf macros
 
8698
 
 
8699
AM_GNU_GETTEXT in `gettext.m4'
 
8700
------------------------------
 
8701
 
 
8702
The `AM_GNU_GETTEXT' macro tests for the presence of the GNU gettext
 
8703
function family in either the C library or a separate `libintl' library
 
8704
(shared or static libraries are both supported) or in the package's
 
8705
`intl/' directory.  It also invokes `AM_PO_SUBDIRS', thus preparing the
 
8706
`po/' directories of the package for building.
 
8707
 
 
8708
   `AM_GNU_GETTEXT' accepts up to three optional arguments.  The general
 
8709
syntax is
 
8710
 
 
8711
     AM_GNU_GETTEXT([INTLSYMBOL], [NEEDSYMBOL], [INTLDIR])
 
8712
 
 
8713
   INTLSYMBOL can be `external' or `no-libtool'.  The default (if it is
 
8714
not specified or empty) is `no-libtool'.  INTLSYMBOL should be
 
8715
`external' for packages with no `intl/' directory, and `no-libtool' for
 
8716
packages with an `intl/' directory.  In the latter case, a static
 
8717
library `$(top_builddir)/intl/libintl.a' will be created.
 
8718
 
 
8719
   If NEEDSYMBOL is specified and is `need-ngettext', then GNU gettext
 
8720
implementations (in libc or libintl) without the `ngettext()' function
 
8721
will be ignored.  If NEEDSYMBOL is specified and is
 
8722
`need-formatstring-macros', then GNU gettext implementations that don't
 
8723
support the ISO C 99 `<inttypes.h>' formatstring macros will be ignored.
 
8724
Only one NEEDSYMBOL can be specified.  To specify more than one
 
8725
requirement, just specify the strongest one among them.  The hierarchy
 
8726
among the various alternatives is as follows: `need-formatstring-macros'
 
8727
implies `need-ngettext'.
 
8728
 
 
8729
   INTLDIR is used to find the intl libraries.  If empty, the value
 
8730
`$(top_builddir)/intl/' is used.
 
8731
 
 
8732
   The `AM_GNU_GETTEXT' macro determines whether GNU gettext is
 
8733
available and should be used.  If so, it sets the `USE_NLS' variable to
 
8734
`yes'; it defines `ENABLE_NLS' to 1 in the autoconf generated
 
8735
configuration file (usually called `config.h'); it sets the variables
 
8736
`LIBINTL' and `LTLIBINTL' to the linker options for use in a Makefile
 
8737
(`LIBINTL' for use without libtool, `LTLIBINTL' for use with libtool);
 
8738
it adds an `-I' option to `CPPFLAGS' if necessary.  In the negative
 
8739
case, it sets `USE_NLS' to `no'; it sets `LIBINTL' and `LTLIBINTL' to
 
8740
empty and doesn't change `CPPFLAGS'.
 
8741
 
 
8742
   The complexities that `AM_GNU_GETTEXT' deals with are the following:
 
8743
 
 
8744
   * Some operating systems have `gettext' in the C library, for example
 
8745
     glibc.  Some have it in a separate library `libintl'.  GNU
 
8746
     `libintl' might have been installed as part of the GNU `gettext'
 
8747
     package.
 
8748
 
 
8749
   * GNU `libintl', if installed, is not necessarily already in the
 
8750
     search path (`CPPFLAGS' for the include file search path,
 
8751
     `LDFLAGS' for the library search path).
 
8752
 
 
8753
   * Except for glibc, the operating system's native `gettext' cannot
 
8754
     exploit the GNU mo files, doesn't have the necessary locale
 
8755
     dependency features, and cannot convert messages from the
 
8756
     catalog's text encoding to the user's locale encoding.
 
8757
 
 
8758
   * GNU `libintl', if installed, is not necessarily already in the run
 
8759
     time library search path.  To avoid the need for setting an
 
8760
     environment variable like `LD_LIBRARY_PATH', the macro adds the
 
8761
     appropriate run time search path options to the `LIBINTL' and
 
8762
     `LTLIBINTL' variables.  This works on most systems, but not on
 
8763
     some operating systems with limited shared library support, like
 
8764
     SCO.
 
8765
 
 
8766
   * GNU `libintl' relies on POSIX/XSI `iconv'.  The macro checks for
 
8767
     linker options needed to use iconv and appends them to the
 
8768
     `LIBINTL' and `LTLIBINTL' variables.
 
8769
 
 
8770
 
 
8771
File: gettext.info,  Node: AM_GNU_GETTEXT_VERSION,  Next: AM_PO_SUBDIRS,  Prev: AM_GNU_GETTEXT,  Up: autoconf macros
 
8772
 
 
8773
AM_GNU_GETTEXT_VERSION in `gettext.m4'
 
8774
--------------------------------------
 
8775
 
 
8776
The `AM_GNU_GETTEXT_VERSION' macro declares the version number of the
 
8777
GNU gettext infrastructure that is used by the package.
 
8778
 
 
8779
   The use of this macro is optional; only the `autopoint' program makes
 
8780
use of it (*note CVS Issues::).
 
8781
 
 
8782
 
 
8783
File: gettext.info,  Node: AM_PO_SUBDIRS,  Next: AM_ICONV,  Prev: AM_GNU_GETTEXT_VERSION,  Up: autoconf macros
 
8784
 
 
8785
AM_PO_SUBDIRS in `po.m4'
 
8786
------------------------
 
8787
 
 
8788
The `AM_PO_SUBDIRS' macro prepares the `po/' directories of the package
 
8789
for building.  This macro should be used in internationalized programs
 
8790
written in other programming languages than C, C++, Objective C, for
 
8791
example `sh', `Python', `Lisp'.  See *Note Programming Languages:: for
 
8792
a list of programming languages that support localization through PO
 
8793
files.
 
8794
 
 
8795
   The `AM_PO_SUBDIRS' macro determines whether internationalization
 
8796
should be used.  If so, it sets the `USE_NLS' variable to `yes',
 
8797
otherwise to `no'.  It also determines the right values for Makefile
 
8798
variables in each `po/' directory.
 
8799
 
 
8800
 
 
8801
File: gettext.info,  Node: AM_ICONV,  Prev: AM_PO_SUBDIRS,  Up: autoconf macros
 
8802
 
 
8803
AM_ICONV in `iconv.m4'
 
8804
----------------------
 
8805
 
 
8806
The `AM_ICONV' macro tests for the presence of the POSIX/XSI `iconv'
 
8807
function family in either the C library or a separate `libiconv'
 
8808
library.  If found, it sets the `am_cv_func_iconv' variable to `yes';
 
8809
it defines `HAVE_ICONV' to 1 in the autoconf generated configuration
 
8810
file (usually called `config.h'); it defines `ICONV_CONST' to `const'
 
8811
or to empty, depending on whether the second argument of `iconv()' is
 
8812
of type `const char **' or `char **'; it sets the variables `LIBICONV'
 
8813
and `LTLIBICONV' to the linker options for use in a Makefile
 
8814
(`LIBICONV' for use without libtool, `LTLIBICONV' for use with
 
8815
libtool); it adds an `-I' option to `CPPFLAGS' if necessary.  If not
 
8816
found, it sets `LIBICONV' and `LTLIBICONV' to empty and doesn't change
 
8817
`CPPFLAGS'.
 
8818
 
 
8819
   The complexities that `AM_ICONV' deals with are the following:
 
8820
 
 
8821
   * Some operating systems have `iconv' in the C library, for example
 
8822
     glibc.  Some have it in a separate library `libiconv', for example
 
8823
     OSF/1 or FreeBSD.  Regardless of the operating system, GNU
 
8824
     `libiconv' might have been installed.  In that case, it should be
 
8825
     used instead of the operating system's native `iconv'.
 
8826
 
 
8827
   * GNU `libiconv', if installed, is not necessarily already in the
 
8828
     search path (`CPPFLAGS' for the include file search path,
 
8829
     `LDFLAGS' for the library search path).
 
8830
 
 
8831
   * GNU `libiconv' is binary incompatible with some operating system's
 
8832
     native `iconv', for example on FreeBSD.  Use of an `iconv.h' and
 
8833
     `libiconv.so' that don't fit together would produce program
 
8834
     crashes.
 
8835
 
 
8836
   * GNU `libiconv', if installed, is not necessarily already in the
 
8837
     run time library search path.  To avoid the need for setting an
 
8838
     environment variable like `LD_LIBRARY_PATH', the macro adds the
 
8839
     appropriate run time search path options to the `LIBICONV'
 
8840
     variable.  This works on most systems, but not on some operating
 
8841
     systems with limited shared library support, like SCO.
 
8842
 
 
8843
   `iconv.m4' is distributed with the GNU gettext package because
 
8844
`gettext.m4' relies on it.
 
8845
 
 
8846
 
 
8847
File: gettext.info,  Node: CVS Issues,  Prev: autoconf macros,  Up: Maintainers
 
8848
 
 
8849
Integrating with CVS
 
8850
====================
 
8851
 
 
8852
Many projects use CVS for distributed development, version control and
 
8853
source backup.  This section gives some advice how to manage the uses
 
8854
of `cvs', `gettextize', `autopoint' and `autoconf'.
 
8855
 
 
8856
* Menu:
 
8857
 
 
8858
* Distributed CVS::             Avoiding version mismatch in distributed development
 
8859
* Files under CVS::             Files to put under CVS version control
 
8860
* autopoint Invocation::        Invoking the `autopoint' Program
 
8861
 
 
8862
 
 
8863
File: gettext.info,  Node: Distributed CVS,  Next: Files under CVS,  Prev: CVS Issues,  Up: CVS Issues
 
8864
 
 
8865
Avoiding version mismatch in distributed development
 
8866
----------------------------------------------------
 
8867
 
 
8868
In a project development with multiple developers, using CVS, there
 
8869
should be a single developer who occasionally - when there is desire to
 
8870
upgrade to a new `gettext' version - runs `gettextize' and performs the
 
8871
changes listed in *Note Adjusting Files::, and then commits his changes
 
8872
to the CVS.
 
8873
 
 
8874
   It is highly recommended that all developers on a project use the
 
8875
same version of GNU `gettext' in the package.  In other words, if a
 
8876
developer runs `gettextize', he should go the whole way, make the
 
8877
necessary remaining changes and commit his changes to the CVS.
 
8878
Otherwise the following damages will likely occur:
 
8879
 
 
8880
   * Apparent version mismatch between developers.  Since some `gettext'
 
8881
     specific portions in `configure.in', `configure.ac' and
 
8882
     `Makefile.am', `Makefile.in' files depend on the `gettext'
 
8883
     version, the use of infrastructure files belonging to different
 
8884
     `gettext' versions can easily lead to build errors.
 
8885
 
 
8886
   * Hidden version mismatch.  Such version mismatch can also lead to
 
8887
     malfunctioning of the package, that may be undiscovered by the
 
8888
     developers.  The worst case of hidden version mismatch is that
 
8889
     internationalization of the package doesn't work at all.
 
8890
 
 
8891
   * Release risks.  All developers implicitly perform constant testing
 
8892
     on a package.  This is important in the days and weeks before a
 
8893
     release.  If the guy who makes the release tar files uses a
 
8894
     different version of GNU `gettext' than the other developers, the
 
8895
     distribution will be less well tested than if all had been using
 
8896
     the same `gettext' version.  For example, it is possible that a
 
8897
     platform specific bug goes undiscovered due to this constellation.
 
8898
 
 
8899
 
 
8900
File: gettext.info,  Node: Files under CVS,  Next: autopoint Invocation,  Prev: Distributed CVS,  Up: CVS Issues
 
8901
 
 
8902
Files to put under CVS version control
 
8903
--------------------------------------
 
8904
 
 
8905
There are basically three ways to deal with generated files in the
 
8906
context of a CVS repository, such as `configure' generated from
 
8907
`configure.in', `PARSER.c' generated from `PARSER.y', or
 
8908
`po/Makefile.in.in' autoinstalled by `gettextize' or `autopoint'.
 
8909
 
 
8910
  1. All generated files are always committed into the repository.
 
8911
 
 
8912
  2. All generated files are committed into the repository occasionally,
 
8913
     for example each time a release is made.
 
8914
 
 
8915
  3. Generated files are never committed into the repository.
 
8916
 
 
8917
   Each of these three approaches has different advantages and
 
8918
drawbacks.
 
8919
 
 
8920
  1. The advantage is that anyone can check out the CVS at any moment
 
8921
     and gets a working build.  The drawbacks are:  1a. It requires
 
8922
     some frequent "cvs commit" actions by the maintainers.  1b. The
 
8923
     repository grows in size quite fast.
 
8924
 
 
8925
  2. The advantage is that anyone can check out the CVS, and the usual
 
8926
     "./configure; make" will work.  The drawbacks are:  2a. The one who
 
8927
     checks out the repository needs tools like GNU `automake', GNU
 
8928
     `autoconf', GNU `m4' installed in his PATH; sometimes he even
 
8929
     needs particular versions of them.  2b. When a release is made and
 
8930
     a commit is made on the generated files, the other developers get
 
8931
     conflicts on the generated files after doing "cvs update".
 
8932
     Although these conflicts are easy to resolve, they are annoying.
 
8933
 
 
8934
  3. The advantage is less work for the maintainers.  The drawback is
 
8935
     that anyone who checks out the CVS not only needs tools like GNU
 
8936
     `automake', GNU `autoconf', GNU `m4' installed in his PATH, but
 
8937
     also that he needs to perform a package specific pre-build step
 
8938
     before being able to "./configure; make".
 
8939
 
 
8940
   For the first and second approach, all files modified or brought in
 
8941
by the occasional `gettextize' invocation and update should be
 
8942
committed into the CVS.
 
8943
 
 
8944
   For the third approach, the maintainer can omit from the CVS
 
8945
repository all the files that `gettextize' mentions as "copy".
 
8946
Instead, he adds to the `configure.in' or `configure.ac' a line of the
 
8947
form
 
8948
 
 
8949
     AM_GNU_GETTEXT_VERSION(0.14.1)
 
8950
 
 
8951
and adds to the package's pre-build script an invocation of
 
8952
`autopoint'.  For everyone who checks out the CVS, this `autopoint'
 
8953
invocation will copy into the right place the `gettext' infrastructure
 
8954
files that have been omitted from the CVS.
 
8955
 
 
8956
 
 
8957
File: gettext.info,  Node: autopoint Invocation,  Prev: Files under CVS,  Up: CVS Issues
 
8958
 
 
8959
Invoking the `autopoint' Program
 
8960
--------------------------------
 
8961
 
 
8962
     autopoint [OPTION]...
 
8963
 
 
8964
   The `autopoint' program copies standard gettext infrastructure files
 
8965
into a source package.  It extracts from a macro call of the form
 
8966
`AM_GNU_GETTEXT_VERSION(VERSION)', found in the package's
 
8967
`configure.in' or `configure.ac' file, the gettext version used by the
 
8968
package, and copies the infrastructure files belonging to this version
 
8969
into the package.
 
8970
 
 
8971
Options
 
8972
.......
 
8973
 
 
8974
`-f'
 
8975
`--force'
 
8976
     Force overwriting of files that already exist.
 
8977
 
 
8978
`-n'
 
8979
`--dry-run'
 
8980
     Print modifications but don't perform them.  All file copying
 
8981
     actions that `autopoint' would normally execute are inhibited and
 
8982
     instead only listed on standard output.
 
8983
 
 
8984
 
 
8985
Informative output
 
8986
..................
 
8987
 
 
8988
`--help'
 
8989
     Display this help and exit.
 
8990
 
 
8991
`--version'
 
8992
     Output version information and exit.
 
8993
 
 
8994
 
 
8995
   `autopoint' supports the GNU `gettext' versions from 0.10.35 to the
 
8996
current one, 0.14.1.  In order to apply `autopoint' to a package using
 
8997
a `gettext' version newer than 0.14.1, you need to install this same
 
8998
version of GNU `gettext' at least.
 
8999
 
 
9000
   In packages using GNU `automake', an invocation of `autopoint'
 
9001
should be followed by invocations of `aclocal' and then `autoconf' and
 
9002
`autoheader'.  The reason is that `autopoint' installs some autoconf
 
9003
macro files, which are used by `aclocal' to create `aclocal.m4', and
 
9004
the latter is used by `autoconf' to create the package's `configure'
 
9005
script and by `autoheader' to create the package's `config.h.in'
 
9006
include file template.
 
9007
 
 
9008
   The name `autopoint' is an abbreviation of `auto-po-intl-m4'; the
 
9009
tool copies or updates mostly files in the `po', `intl', `m4'
 
9010
directories.
 
9011
 
 
9012
 
 
9013
File: gettext.info,  Node: Programming Languages,  Next: Conclusion,  Prev: Maintainers,  Up: Top
 
9014
 
 
9015
Other Programming Languages
 
9016
***************************
 
9017
 
 
9018
While the presentation of `gettext' focuses mostly on C and implicitly
 
9019
applies to C++ as well, its scope is far broader than that: Many
 
9020
programming languages, scripting languages and other textual data like
 
9021
GUI resources or package descriptions can make use of the gettext
 
9022
approach.
 
9023
 
 
9024
* Menu:
 
9025
 
 
9026
* Language Implementors::       The Language Implementor's View
 
9027
* Programmers for other Languages::  The Programmer's View
 
9028
* Translators for other Languages::  The Translator's View
 
9029
* Maintainers for other Languages::  The Maintainer's View
 
9030
* List of Programming Languages::  Individual Programming Languages
 
9031
* List of Data Formats::        Internationalizable Data
 
9032
 
 
9033
 
 
9034
File: gettext.info,  Node: Language Implementors,  Next: Programmers for other Languages,  Prev: Programming Languages,  Up: Programming Languages
 
9035
 
 
9036
The Language Implementor's View
 
9037
===============================
 
9038
 
 
9039
All programming and scripting languages that have the notion of strings
 
9040
are eligible to supporting `gettext'.  Supporting `gettext' means the
 
9041
following:
 
9042
 
 
9043
  1. You should add to the language a syntax for translatable strings.
 
9044
     In principle, a function call of `gettext' would do, but a
 
9045
     shorthand syntax helps keeping the legibility of internationalized
 
9046
     programs.  For example, in C we use the syntax `_("string")', and
 
9047
     in GNU awk we use the shorthand `_"string"'.
 
9048
 
 
9049
  2. You should arrange that evaluation of such a translatable string at
 
9050
     runtime calls the `gettext' function, or performs equivalent
 
9051
     processing.
 
9052
 
 
9053
  3. Similarly, you should make the functions `ngettext', `dcgettext',
 
9054
     `dcngettext' available from within the language.  These functions
 
9055
     are less often used, but are nevertheless necessary for particular
 
9056
     purposes: `ngettext' for correct plural handling, and `dcgettext'
 
9057
     and `dcngettext' for obeying other locale environment variables
 
9058
     than `LC_MESSAGES', such as `LC_TIME' or `LC_MONETARY'.  For these
 
9059
     latter functions, you need to make the `LC_*' constants, available
 
9060
     in the C header `<locale.h>', referenceable from within the
 
9061
     language, usually either as enumeration values or as strings.
 
9062
 
 
9063
  4. You should allow the programmer to designate a message domain,
 
9064
     either by making the `textdomain' function available from within
 
9065
     the language, or by introducing a magic variable called
 
9066
     `TEXTDOMAIN'.  Similarly, you should allow the programmer to
 
9067
     designate where to search for message catalogs, by providing
 
9068
     access to the `bindtextdomain' function.
 
9069
 
 
9070
  5. You should either perform a `setlocale (LC_ALL, "")' call during
 
9071
     the startup of your language runtime, or allow the programmer to
 
9072
     do so.  Remember that gettext will act as a no-op if the
 
9073
     `LC_MESSAGES' and `LC_CTYPE' locale facets are not both set.
 
9074
 
 
9075
  6. A programmer should have a way to extract translatable strings
 
9076
     from a program into a PO file.  The GNU `xgettext' program is being
 
9077
     extended to support very different programming languages.  Please
 
9078
     contact the GNU `gettext' maintainers to help them doing this.  If
 
9079
     the string extractor is best integrated into your language's
 
9080
     parser, GNU `xgettext' can function as a front end to your string
 
9081
     extractor.
 
9082
 
 
9083
  7. The language's library should have a string formatting facility
 
9084
     where the arguments of a format string are denoted by a positional
 
9085
     number or a name.  This is needed because for some languages and
 
9086
     some messages with more than one substitutable argument, the
 
9087
     translation will need to output the substituted arguments in
 
9088
     different order.  *Note c-format Flag::.
 
9089
 
 
9090
  8. If the language has more than one implementation, and not all of
 
9091
     the implementations use `gettext', but the programs should be
 
9092
     portable across implementations, you should provide a no-i18n
 
9093
     emulation, that makes the other implementations accept programs
 
9094
     written for yours, without actually translating the strings.
 
9095
 
 
9096
  9. To help the programmer in the task of marking translatable strings,
 
9097
     which is usually performed using the Emacs PO mode, you are
 
9098
     welcome to contact the GNU `gettext' maintainers, so they can add
 
9099
     support for your language to `po-mode.el'.
 
9100
 
 
9101
   On the implementation side, three approaches are possible, with
 
9102
different effects on portability and copyright:
 
9103
 
 
9104
   * You may integrate the GNU `gettext''s `intl/' directory in your
 
9105
     package, as described in *Note Maintainers::.  This allows you to
 
9106
     have internationalization on all kinds of platforms.  Note that
 
9107
     when you then distribute your package, it legally falls under the
 
9108
     GNU General Public License, and the GNU project will be glad about
 
9109
     your contribution to the Free Software pool.
 
9110
 
 
9111
   * You may link against GNU `gettext' functions if they are found in
 
9112
     the C library.  For example, an autoconf test for `gettext()' and
 
9113
     `ngettext()' will detect this situation.  For the moment, this test
 
9114
     will succeed on GNU systems and not on other platforms.  No severe
 
9115
     copyright restrictions apply.
 
9116
 
 
9117
   * You may emulate or reimplement the GNU `gettext' functionality.
 
9118
     This has the advantage of full portability and no copyright
 
9119
     restrictions, but also the drawback that you have to reimplement
 
9120
     the GNU `gettext' features (such as the `LANGUAGE' environment
 
9121
     variable, the locale aliases database, the automatic charset
 
9122
     conversion, and plural handling).
 
9123
 
 
9124
 
 
9125
File: gettext.info,  Node: Programmers for other Languages,  Next: Translators for other Languages,  Prev: Language Implementors,  Up: Programming Languages
 
9126
 
 
9127
The Programmer's View
 
9128
=====================
 
9129
 
 
9130
For the programmer, the general procedure is the same as for the C
 
9131
language.  The Emacs PO mode supports other languages, and the GNU
 
9132
`xgettext' string extractor recognizes other languages based on the
 
9133
file extension or a command-line option.  In some languages,
 
9134
`setlocale' is not needed because it is already performed by the
 
9135
underlying language runtime.
 
9136
 
 
9137
 
 
9138
File: gettext.info,  Node: Translators for other Languages,  Next: Maintainers for other Languages,  Prev: Programmers for other Languages,  Up: Programming Languages
 
9139
 
 
9140
The Translator's View
 
9141
=====================
 
9142
 
 
9143
The translator works exactly as in the C language case.  The only
 
9144
difference is that when translating format strings, she has to be aware
 
9145
of the language's particular syntax for positional arguments in format
 
9146
strings.
 
9147
 
 
9148
* Menu:
 
9149
 
 
9150
* c-format::                    C Format Strings
 
9151
* objc-format::                 Objective C Format Strings
 
9152
* sh-format::                   Shell Format Strings
 
9153
* python-format::               Python Format Strings
 
9154
* lisp-format::                 Lisp Format Strings
 
9155
* elisp-format::                Emacs Lisp Format Strings
 
9156
* librep-format::               librep Format Strings
 
9157
* smalltalk-format::            Smalltalk Format Strings
 
9158
* java-format::                 Java Format Strings
 
9159
* csharp-format::               C# Format Strings
 
9160
* awk-format::                  awk Format Strings
 
9161
* object-pascal-format::        Object Pascal Format Strings
 
9162
* ycp-format::                  YCP Format Strings
 
9163
* tcl-format::                  Tcl Format Strings
 
9164
* perl-format::                 Perl Format Strings
 
9165
* php-format::                  PHP Format Strings
 
9166
* gcc-internal-format::         GCC internal Format Strings
 
9167
* qt-format::                   Qt Format Strings
 
9168
 
 
9169
 
 
9170
File: gettext.info,  Node: c-format,  Next: objc-format,  Prev: Translators for other Languages,  Up: Translators for other Languages
 
9171
 
 
9172
C Format Strings
 
9173
----------------
 
9174
 
 
9175
C format strings are described in POSIX (IEEE P1003.1 2001), section
 
9176
XSH 3 fprintf(),
 
9177
`http://www.opengroup.org/onlinepubs/007904975/functions/fprintf.html'.
 
9178
See also the fprintf(3) manual page,
 
9179
`http://www.linuxvalley.it/encyclopedia/ldp/manpage/man3/printf.3.php',
 
9180
`http://informatik.fh-wuerzburg.de/student/i510/man/printf.html'.
 
9181
 
 
9182
   Although format strings with positions that reorder arguments, such
 
9183
as
 
9184
 
 
9185
     "Only %2$d bytes free on '%1$s'."
 
9186
 
 
9187
which is semantically equivalent to
 
9188
 
 
9189
     "'%s' has only %d bytes free."
 
9190
 
 
9191
are a POSIX/XSI feature and not specified by ISO C 99, translators can
 
9192
rely on this reordering ability: On the few platforms where `printf()',
 
9193
`fprintf()' etc. don't support this feature natively, `libintl.a' or
 
9194
`libintl.so' provides replacement functions, and GNU `<libintl.h>'
 
9195
activates these replacement functions automatically.
 
9196
 
 
9197
   As a special feature for Farsi (Persian) and maybe Arabic,
 
9198
translators can insert an `I' flag into numeric format directives.  For
 
9199
example, the translation of `"%d"' can be `"%Id"'.  The effect of this
 
9200
flag, on systems with GNU `libc', is that in the output, the ASCII
 
9201
digits are replaced with the `outdigits' defined in the `LC_CTYPE'
 
9202
locale facet.  On other systems, the `gettext' function removes this
 
9203
flag, so that it has no effect.
 
9204
 
 
9205
   Note that the programmer should _not_ put this flag into the
 
9206
untranslated string.  (Putting the `I' format directive flag into an
 
9207
MSGID string would lead to undefined behaviour on platforms without
 
9208
glibc when NLS is disabled.)
 
9209
 
 
9210
 
 
9211
File: gettext.info,  Node: objc-format,  Next: sh-format,  Prev: c-format,  Up: Translators for other Languages
 
9212
 
 
9213
Objective C Format Strings
 
9214
--------------------------
 
9215
 
 
9216
Objective C format strings are like C format strings.  They support an
 
9217
additional format directive: "$@", which when executed consumes an
 
9218
argument of type `Object *'.
 
9219
 
 
9220
 
 
9221
File: gettext.info,  Node: sh-format,  Next: python-format,  Prev: objc-format,  Up: Translators for other Languages
 
9222
 
 
9223
Shell Format Strings
 
9224
--------------------
 
9225
 
 
9226
Shell format strings, as supported by GNU gettext and the `envsubst'
 
9227
program, are strings with references to shell variables in the form
 
9228
`$VARIABLE' or `${VARIABLE}'.  References of the form
 
9229
`${VARIABLE-DEFAULT}', `${VARIABLE:-DEFAULT}', `${VARIABLE=DEFAULT}',
 
9230
`${VARIABLE:=DEFAULT}', `${VARIABLE+REPLACEMENT}',
 
9231
`${VARIABLE:+REPLACEMENT}', `${VARIABLE?IGNORED}',
 
9232
`${VARIABLE:?IGNORED}', that would be valid inside shell scripts, are
 
9233
not supported.  The VARIABLE names must consist solely of alphanumeric
 
9234
or underscore ASCII characters, not start with a digit and be nonempty;
 
9235
otherwise such a variable reference is ignored.
 
9236
 
 
9237
 
 
9238
File: gettext.info,  Node: python-format,  Next: lisp-format,  Prev: sh-format,  Up: Translators for other Languages
 
9239
 
 
9240
Python Format Strings
 
9241
---------------------
 
9242
 
 
9243
Python format strings are described in Python Library reference /
 
9244
2. Built-in Types, Exceptions and Functions / 2.2. Built-in Types /
 
9245
2.2.6. Sequence Types / 2.2.6.2. String Formatting Operations.
 
9246
`http://www.python.org/doc/2.2.1/lib/typesseq-strings.html'.
 
9247
 
 
9248
 
 
9249
File: gettext.info,  Node: lisp-format,  Next: elisp-format,  Prev: python-format,  Up: Translators for other Languages
 
9250
 
 
9251
Lisp Format Strings
 
9252
-------------------
 
9253
 
 
9254
Lisp format strings are described in the Common Lisp HyperSpec, chapter
 
9255
22.3 Formatted Output,
 
9256
`http://www.lisp.org/HyperSpec/Body/sec_22-3.html'.
 
9257
 
 
9258
 
 
9259
File: gettext.info,  Node: elisp-format,  Next: librep-format,  Prev: lisp-format,  Up: Translators for other Languages
 
9260
 
 
9261
Emacs Lisp Format Strings
 
9262
-------------------------
 
9263
 
 
9264
Emacs Lisp format strings are documented in the Emacs Lisp reference,
 
9265
section Formatting Strings,
 
9266
`http://www.gnu.org/manual/elisp-manual-21-2.8/html_chapter/elisp_4.html#SEC75'.
 
9267
Note that as of version 21, XEmacs supports numbered argument
 
9268
specifications in format strings while FSF Emacs doesn't.
 
9269
 
 
9270
 
 
9271
File: gettext.info,  Node: librep-format,  Next: smalltalk-format,  Prev: elisp-format,  Up: Translators for other Languages
 
9272
 
 
9273
librep Format Strings
 
9274
---------------------
 
9275
 
 
9276
librep format strings are documented in the librep manual, section
 
9277
Formatted Output,
 
9278
<http://librep.sourceforge.net/librep-manual.html#Formatted%20Output>,
 
9279
<http://www.gwinnup.org/research/docs/librep.html#SEC122>.
 
9280
 
 
9281
 
 
9282
File: gettext.info,  Node: smalltalk-format,  Next: java-format,  Prev: librep-format,  Up: Translators for other Languages
 
9283
 
 
9284
Smalltalk Format Strings
 
9285
------------------------
 
9286
 
 
9287
Smalltalk format strings are described in the GNU Smalltalk
 
9288
documentation, class `CharArray', methods `bindWith:' and
 
9289
`bindWithArguments:'.
 
9290
`http://www.gnu.org/software/smalltalk/gst-manual/gst_68.html#SEC238'.
 
9291
In summary, a directive starts with `%' and is followed by `%' or a
 
9292
nonzero digit (`1' to `9').
 
9293
 
 
9294
 
 
9295
File: gettext.info,  Node: java-format,  Next: csharp-format,  Prev: smalltalk-format,  Up: Translators for other Languages
 
9296
 
 
9297
Java Format Strings
 
9298
-------------------
 
9299
 
 
9300
Java format strings are described in the JDK documentation for class
 
9301
`java.text.MessageFormat',
 
9302
`http://java.sun.com/j2se/1.4/docs/api/java/text/MessageFormat.html'.
 
9303
See also the ICU documentation
 
9304
`http://oss.software.ibm.com/icu/apiref/classMessageFormat.html'.
 
9305
 
 
9306
 
 
9307
File: gettext.info,  Node: csharp-format,  Next: awk-format,  Prev: java-format,  Up: Translators for other Languages
 
9308
 
 
9309
C# Format Strings
 
9310
-----------------
 
9311
 
 
9312
C# format strings are described in the .NET documentation for class
 
9313
`System.String' and in
 
9314
`http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpConFormattingOverview.asp'.
 
9315
 
 
9316
 
 
9317
File: gettext.info,  Node: awk-format,  Next: object-pascal-format,  Prev: csharp-format,  Up: Translators for other Languages
 
9318
 
 
9319
awk Format Strings
 
9320
------------------
 
9321
 
 
9322
awk format strings are described in the gawk documentation, section
 
9323
Printf, `http://www.gnu.org/manual/gawk/html_node/Printf.html#Printf'.
 
9324
 
 
9325
 
 
9326
File: gettext.info,  Node: object-pascal-format,  Next: ycp-format,  Prev: awk-format,  Up: Translators for other Languages
 
9327
 
 
9328
Object Pascal Format Strings
 
9329
----------------------------
 
9330
 
 
9331
Where is this documented?
 
9332
 
 
9333
 
 
9334
File: gettext.info,  Node: ycp-format,  Next: tcl-format,  Prev: object-pascal-format,  Up: Translators for other Languages
 
9335
 
 
9336
YCP Format Strings
 
9337
------------------
 
9338
 
 
9339
YCP sformat strings are described in the libycp documentation
 
9340
`file:/usr/share/doc/packages/libycp/YCP-builtins.html'.  In summary, a
 
9341
directive starts with `%' and is followed by `%' or a nonzero digit
 
9342
(`1' to `9').
 
9343
 
 
9344
 
 
9345
File: gettext.info,  Node: tcl-format,  Next: perl-format,  Prev: ycp-format,  Up: Translators for other Languages
 
9346
 
 
9347
Tcl Format Strings
 
9348
------------------
 
9349
 
 
9350
Tcl format strings are described in the `format.n' manual page,
 
9351
`http://www.scriptics.com/man/tcl8.3/TclCmd/format.htm'.
 
9352
 
 
9353
 
 
9354
File: gettext.info,  Node: perl-format,  Next: php-format,  Prev: tcl-format,  Up: Translators for other Languages
 
9355
 
 
9356
Perl Format Strings
 
9357
-------------------
 
9358
 
 
9359
There are two kinds format strings in Perl: those acceptable to the
 
9360
Perl built-in function `printf', labelled as `perl-format', and those
 
9361
acceptable to the `libintl-perl' function `__x', labelled as
 
9362
`perl-brace-format'.
 
9363
 
 
9364
   Perl `printf' format strings are described in the `sprintf' section
 
9365
of `man perlfunc'.
 
9366
 
 
9367
   Perl brace format strings are described in the
 
9368
`Locale::TextDomain(3pm)' manual page of the CPAN package libintl-perl.
 
9369
In brief, Perl format uses placeholders put between braces (`{' and
 
9370
`}').  The placeholder must have the syntax of simple identifiers.
 
9371
 
 
9372
 
 
9373
File: gettext.info,  Node: php-format,  Next: gcc-internal-format,  Prev: perl-format,  Up: Translators for other Languages
 
9374
 
 
9375
PHP Format Strings
 
9376
------------------
 
9377
 
 
9378
PHP format strings are described in the documentation of the PHP
 
9379
function `sprintf', in `phpdoc/manual/function.sprintf.html' or
 
9380
`http://www.php.net/manual/en/function.sprintf.php'.
 
9381
 
 
9382
 
 
9383
File: gettext.info,  Node: gcc-internal-format,  Next: qt-format,  Prev: php-format,  Up: Translators for other Languages
 
9384
 
 
9385
GCC internal Format Strings
 
9386
---------------------------
 
9387
 
 
9388
These format strings are used inside the GCC sources.  In such a format
 
9389
string, a directive starts with `%', is optionally followed by a size
 
9390
specifier `l', an optional flag `+', another optional flag `#', and is
 
9391
finished by a specifier: `%' denotes a literal percent sign, `c'
 
9392
denotes a character, `s' denotes a string, `i' and `d' denote an
 
9393
integer, `o', `u', `x' denote an unsigned integer, `.*s' denotes a
 
9394
string preceded by a width specification, `H' denotes a `location_t *'
 
9395
pointer, `D' denotes a general declaration, `F' denotes a function
 
9396
declaration, `T' denotes a type, `A' denotes a function argument, `C'
 
9397
denotes a tree code, `E' denotes an expression, `L' denotes a
 
9398
programming language, `O' denotes a binary operator, `P' denotes a
 
9399
function parameter, `Q' denotes an assignment operator, `V' denotes a
 
9400
const/volatile qualifier.
 
9401
 
 
9402
 
 
9403
File: gettext.info,  Node: qt-format,  Prev: gcc-internal-format,  Up: Translators for other Languages
 
9404
 
 
9405
Qt Format Strings
 
9406
-----------------
 
9407
 
 
9408
Qt format strings are described in the documentation of the QString
 
9409
class `file:/usr/lib/qt-3.0.5/doc/html/qstring.html'.  In summary, a
 
9410
directive consists of a `%' followed by a digit. The same directive
 
9411
cannot occur more than once in a format string.
 
9412
 
 
9413
 
 
9414
File: gettext.info,  Node: Maintainers for other Languages,  Next: List of Programming Languages,  Prev: Translators for other Languages,  Up: Programming Languages
 
9415
 
 
9416
The Maintainer's View
 
9417
=====================
 
9418
 
 
9419
For the maintainer, the general procedure differs from the C language
 
9420
case in two ways.
 
9421
 
 
9422
   * For those languages that don't use GNU gettext, the `intl/'
 
9423
     directory is not needed and can be omitted.  This means that the
 
9424
     maintainer calls the `gettextize' program without the `--intl'
 
9425
     option, and that he invokes the `AM_GNU_GETTEXT' autoconf macro via
 
9426
     `AM_GNU_GETTEXT([external])'.
 
9427
 
 
9428
   * If only a single programming language is used, the
 
9429
     `XGETTEXT_OPTIONS' variable in `po/Makevars' (*note po/Makevars::)
 
9430
     should be adjusted to match the `xgettext' options for that
 
9431
     particular programming language.  If the package uses more than
 
9432
     one programming language with `gettext' support, it becomes
 
9433
     necessary to change the POT file construction rule in
 
9434
     `po/Makefile.in.in'.  It is recommended to make one `xgettext'
 
9435
     invocation per programming language, each with the options
 
9436
     appropriate for that language, and to combine the resulting files
 
9437
     using `msgcat'.
 
9438
 
 
9439
 
 
9440
File: gettext.info,  Node: List of Programming Languages,  Next: List of Data Formats,  Prev: Maintainers for other Languages,  Up: Programming Languages
 
9441
 
 
9442
Individual Programming Languages
 
9443
================================
 
9444
 
 
9445
* Menu:
 
9446
 
 
9447
* C::                           C, C++, Objective C
 
9448
* sh::                          sh - Shell Script
 
9449
* bash::                        bash - Bourne-Again Shell Script
 
9450
* Python::                      Python
 
9451
* Common Lisp::                 GNU clisp - Common Lisp
 
9452
* clisp C::                     GNU clisp C sources
 
9453
* Emacs Lisp::                  Emacs Lisp
 
9454
* librep::                      librep
 
9455
* Smalltalk::                   GNU Smalltalk
 
9456
* Java::                        Java
 
9457
* C#::                          C#
 
9458
* gawk::                        GNU awk
 
9459
* Pascal::                      Pascal - Free Pascal Compiler
 
9460
* wxWindows::                   wxWindows library
 
9461
* YCP::                         YCP - YaST2 scripting language
 
9462
* Tcl::                         Tcl - Tk's scripting language
 
9463
* Perl::                        Perl
 
9464
* PHP::                         PHP Hypertext Preprocessor
 
9465
* Pike::                        Pike
 
9466
* GCC-source::                  GNU Compiler Collection sources
 
9467
 
 
9468
 
 
9469
File: gettext.info,  Node: C,  Next: sh,  Prev: List of Programming Languages,  Up: List of Programming Languages
 
9470
 
 
9471
C, C++, Objective C
 
9472
-------------------
 
9473
 
 
9474
RPMs
 
9475
     gcc, gpp, gobjc, glibc, gettext
 
9476
 
 
9477
File extension
 
9478
     For C: `c', `h'.
 
9479
     For C++: `C', `c++', `cc', `cxx', `cpp', `hpp'.
 
9480
     For Objective C: `m'.
 
9481
 
 
9482
String syntax
 
9483
     `"abc"'
 
9484
 
 
9485
gettext shorthand
 
9486
     `_("abc")'
 
9487
 
 
9488
gettext/ngettext functions
 
9489
     `gettext', `dgettext', `dcgettext', `ngettext', `dngettext',
 
9490
     `dcngettext'
 
9491
 
 
9492
textdomain
 
9493
     `textdomain' function
 
9494
 
 
9495
bindtextdomain
 
9496
     `bindtextdomain' function
 
9497
 
 
9498
setlocale
 
9499
     Programmer must call `setlocale (LC_ALL, "")'
 
9500
 
 
9501
Prerequisite
 
9502
     `#include <libintl.h>'
 
9503
     `#include <locale.h>'
 
9504
     `#define _(string) gettext (string)'
 
9505
 
 
9506
Use or emulate GNU gettext
 
9507
     Use
 
9508
 
 
9509
Extractor
 
9510
     `xgettext -k_'
 
9511
 
 
9512
Formatting with positions
 
9513
     `fprintf "%2$d %1$d"'
 
9514
     In C++: `autosprintf "%2$d %1$d"' (*note Introduction:
 
9515
     (autosprintf)Top.)
 
9516
 
 
9517
Portability
 
9518
     autoconf (gettext.m4) and #if ENABLE_NLS
 
9519
 
 
9520
po-mode marking
 
9521
     yes
 
9522
 
 
9523
   The following examples are available in the `examples' directory:
 
9524
`hello-c', `hello-c-gnome', `hello-c++', `hello-c++-qt',
 
9525
`hello-c++-kde', `hello-c++-gnome', `hello-objc', `hello-objc-gnustep',
 
9526
`hello-objc-gnome'.
 
9527
 
 
9528
 
 
9529
File: gettext.info,  Node: sh,  Next: bash,  Prev: C,  Up: List of Programming Languages
 
9530
 
 
9531
sh - Shell Script
 
9532
-----------------
 
9533
 
 
9534
RPMs
 
9535
     bash, gettext
 
9536
 
 
9537
File extension
 
9538
     `sh'
 
9539
 
 
9540
String syntax
 
9541
     `"abc"', `'abc'', `abc'
 
9542
 
 
9543
gettext shorthand
 
9544
     `"`gettext \"abc\"`"'
 
9545
 
 
9546
gettext/ngettext functions
 
9547
     `gettext', `ngettext' programs
 
9548
     `eval_gettext', `eval_ngettext' shell functions
 
9549
 
 
9550
textdomain
 
9551
     environment variable `TEXTDOMAIN'
 
9552
 
 
9553
bindtextdomain
 
9554
     environment variable `TEXTDOMAINDIR'
 
9555
 
 
9556
setlocale
 
9557
     automatic
 
9558
 
 
9559
Prerequisite
 
9560
     `. gettext.sh'
 
9561
 
 
9562
Use or emulate GNU gettext
 
9563
     use
 
9564
 
 
9565
Extractor
 
9566
     `xgettext'
 
9567
 
 
9568
Formatting with positions
 
9569
     --
 
9570
 
 
9571
Portability
 
9572
     fully portable
 
9573
 
 
9574
po-mode marking
 
9575
     --
 
9576
 
 
9577
   An example is available in the `examples' directory: `hello-sh'.
 
9578
 
 
9579
* Menu:
 
9580
 
 
9581
* Preparing Shell Scripts::     Preparing Shell Scripts for Internationalization
 
9582
* gettext.sh::                  Contents of `gettext.sh'
 
9583
* gettext Invocation::          Invoking the `gettext' program
 
9584
* ngettext Invocation::         Invoking the `ngettext' program
 
9585
* envsubst Invocation::         Invoking the `envsubst' program
 
9586
* eval_gettext Invocation::     Invoking the `eval_gettext' function
 
9587
* eval_ngettext Invocation::    Invoking the `eval_ngettext' function
 
9588
 
 
9589
 
 
9590
File: gettext.info,  Node: Preparing Shell Scripts,  Next: gettext.sh,  Prev: sh,  Up: sh
 
9591
 
 
9592
Preparing Shell Scripts for Internationalization
 
9593
................................................
 
9594
 
 
9595
Preparing a shell script for internationalization is conceptually
 
9596
similar to the steps described in *Note Sources::.  The concrete steps
 
9597
for shell scripts are as follows.
 
9598
 
 
9599
  1. Insert the line
 
9600
 
 
9601
          . gettext.sh
 
9602
 
 
9603
     near the top of the script.  `gettext.sh' is a shell function
 
9604
     library that provides the functions `eval_gettext' (see *Note
 
9605
     eval_gettext Invocation::) and `eval_ngettext' (see *Note
 
9606
     eval_ngettext Invocation::).  You have to ensure that `gettext.sh'
 
9607
     can be found in the `PATH'.
 
9608
 
 
9609
  2. Set and export the `TEXTDOMAIN' and `TEXTDOMAINDIR' environment
 
9610
     variables.  Usually `TEXTDOMAIN' is the package or program name,
 
9611
     and `TEXTDOMAINDIR' is the absolute pathname corresponding to
 
9612
     `$prefix/share/locale', where `$prefix' is the installation
 
9613
     location.
 
9614
 
 
9615
          TEXTDOMAIN=@PACKAGE@
 
9616
          export TEXTDOMAIN
 
9617
          TEXTDOMAINDIR=@LOCALEDIR@
 
9618
          export TEXTDOMAINDIR
 
9619
 
 
9620
  3. Prepare the strings for translation, as described in *Note
 
9621
     Preparing Strings::.
 
9622
 
 
9623
  4. Simplify translatable strings so that they don't contain command
 
9624
     substitution (`"`...`"' or `"$(...)"'), variable access with
 
9625
     defaulting (like `${VARIABLE-DEFAULT}'), access to positional
 
9626
     arguments (like `$0', `$1', ...) or highly volatile shell
 
9627
     variables (like `$?'). This can always be done through simple
 
9628
     local code restructuring.  For example,
 
9629
 
 
9630
          echo "Usage: $0 [OPTION] FILE..."
 
9631
 
 
9632
     becomes
 
9633
 
 
9634
          program_name=$0
 
9635
          echo "Usage: $program_name [OPTION] FILE..."
 
9636
 
 
9637
     Similarly,
 
9638
 
 
9639
          echo "Remaining files: `ls | wc -l`"
 
9640
 
 
9641
     becomes
 
9642
 
 
9643
          filecount="`ls | wc -l`"
 
9644
          echo "Remaining files: $filecount"
 
9645
 
 
9646
  5. For each translatable string, change the output command `echo' or
 
9647
     `$echo' to `gettext' (if the string contains no references to
 
9648
     shell variables) or to `eval_gettext' (if it refers to shell
 
9649
     variables), followed by a no-argument `echo' command (to account
 
9650
     for the terminating newline). Similarly, for cases with plural
 
9651
     handling, replace a conditional `echo' command with an invocation
 
9652
     of `ngettext' or `eval_ngettext', followed by a no-argument `echo'
 
9653
     command.
 
9654
 
 
9655
 
 
9656
File: gettext.info,  Node: gettext.sh,  Next: gettext Invocation,  Prev: Preparing Shell Scripts,  Up: sh
 
9657
 
 
9658
Contents of `gettext.sh'
 
9659
........................
 
9660
 
 
9661
`gettext.sh', contained in the run-time package of GNU gettext, provides
 
9662
the following:
 
9663
 
 
9664
   * $echo The variable `echo' is set to a command that outputs its
 
9665
     first argument and a newline, without interpreting backslashes in
 
9666
     the argument string.
 
9667
 
 
9668
   * eval_gettext See *Note eval_gettext Invocation::.
 
9669
 
 
9670
   * eval_ngettext See *Note eval_ngettext Invocation::.
 
9671
 
 
9672
 
 
9673
File: gettext.info,  Node: gettext Invocation,  Next: ngettext Invocation,  Prev: gettext.sh,  Up: sh
 
9674
 
 
9675
Invoking the `gettext' program
 
9676
..............................
 
9677
 
 
9678
     gettext [OPTION] [[TEXTDOMAIN] MSGID]
 
9679
     gettext [OPTION] -s [MSGID]...
 
9680
 
 
9681
   The `gettext' program displays the native language translation of a
 
9682
textual message.
 
9683
 
 
9684
*Arguments*
 
9685
 
 
9686
`-d TEXTDOMAIN'
 
9687
`--domain=TEXTDOMAIN'
 
9688
     Retrieve translated messages from TEXTDOMAIN.  Usually a TEXTDOMAIN
 
9689
     corresponds to a package, a program, or a module of a program.
 
9690
 
 
9691
`-e'
 
9692
     Enable expansion of some escape sequences.  This option is for
 
9693
     compatibility with the `echo' program or shell built-in.  The
 
9694
     escape sequences `\b', `\c', `\f', `\n', `\r', `\t', `\v', `\\',
 
9695
     and `\' followed by one to three octal digits, are interpreted
 
9696
     like the `echo' program does.
 
9697
 
 
9698
`-E'
 
9699
     This option is only for compatibility with the `echo' program or
 
9700
     shell built-in.  It has no effect.
 
9701
 
 
9702
`-h'
 
9703
`--help'
 
9704
     Display this help and exit.
 
9705
 
 
9706
`-n'
 
9707
     Suppress trailing newline.  By default, `gettext' adds a newline to
 
9708
     the output.
 
9709
 
 
9710
`-V'
 
9711
`--version'
 
9712
     Output version information and exit.
 
9713
 
 
9714
`[TEXTDOMAIN] MSGID'
 
9715
     Retrieve translated message corresponding to MSGID from TEXTDOMAIN.
 
9716
 
 
9717
 
 
9718
   If the TEXTDOMAIN parameter is not given, the domain is determined
 
9719
from the environment variable `TEXTDOMAIN'.  If the message catalog is
 
9720
not found in the regular directory, another location can be specified
 
9721
with the environment variable `TEXTDOMAINDIR'.
 
9722
 
 
9723
   When used with the `-s' option the program behaves like the `echo'
 
9724
command.  But it does not simply copy its arguments to stdout.  Instead
 
9725
those messages found in the selected catalog are translated.
 
9726
 
 
9727
 
 
9728
File: gettext.info,  Node: ngettext Invocation,  Next: envsubst Invocation,  Prev: gettext Invocation,  Up: sh
 
9729
 
 
9730
Invoking the `ngettext' program
 
9731
...............................
 
9732
 
 
9733
     ngettext [OPTION] [TEXTDOMAIN] MSGID MSGID-PLURAL COUNT
 
9734
 
 
9735
   The `ngettext' program displays the native language translation of a
 
9736
textual message whose grammatical form depends on a number.
 
9737
 
 
9738
*Arguments*
 
9739
 
 
9740
`-d TEXTDOMAIN'
 
9741
`--domain=TEXTDOMAIN'
 
9742
     Retrieve translated messages from TEXTDOMAIN.  Usually a TEXTDOMAIN
 
9743
     corresponds to a package, a program, or a module of a program.
 
9744
 
 
9745
`-e'
 
9746
     Enable expansion of some escape sequences.  This option is for
 
9747
     compatibility with the `gettext' program.  The escape sequences
 
9748
     `\b', `\c', `\f', `\n', `\r', `\t', `\v', `\\', and `\' followed
 
9749
     by one to three octal digits, are interpreted like the `echo'
 
9750
     program does.
 
9751
 
 
9752
`-E'
 
9753
     This option is only for compatibility with the `gettext' program.
 
9754
     It has no effect.
 
9755
 
 
9756
`-h'
 
9757
`--help'
 
9758
     Display this help and exit.
 
9759
 
 
9760
`-V'
 
9761
`--version'
 
9762
     Output version information and exit.
 
9763
 
 
9764
`TEXTDOMAIN'
 
9765
     Retrieve translated message from TEXTDOMAIN.
 
9766
 
 
9767
`MSGID MSGID-PLURAL'
 
9768
     Translate MSGID (English singular) / MSGID-PLURAL (English plural).
 
9769
 
 
9770
`COUNT'
 
9771
     Choose singular/plural form based on this value.
 
9772
 
 
9773
 
 
9774
   If the TEXTDOMAIN parameter is not given, the domain is determined
 
9775
from the environment variable `TEXTDOMAIN'.  If the message catalog is
 
9776
not found in the regular directory, another location can be specified
 
9777
with the environment variable `TEXTDOMAINDIR'.
 
9778
 
 
9779
 
 
9780
File: gettext.info,  Node: envsubst Invocation,  Next: eval_gettext Invocation,  Prev: ngettext Invocation,  Up: sh
 
9781
 
 
9782
Invoking the `envsubst' program
 
9783
...............................
 
9784
 
 
9785
     envsubst [OPTION] [SHELL-FORMAT]
 
9786
 
 
9787
   The `envsubst' program substitutes the values of environment
 
9788
variables.
 
9789
 
 
9790
*Operation mode*
 
9791
 
 
9792
`-v'
 
9793
`--variables'
 
9794
     Output the variables occurring in SHELL-FORMAT.
 
9795
 
 
9796
 
 
9797
*Informative output*
 
9798
 
 
9799
`-h'
 
9800
`--help'
 
9801
     Display this help and exit.
 
9802
 
 
9803
`-V'
 
9804
`--version'
 
9805
     Output version information and exit.
 
9806
 
 
9807
 
 
9808
   In normal operation mode, standard input is copied to standard
 
9809
output, with references to environment variables of the form
 
9810
`$VARIABLE' or `${VARIABLE}' being replaced with the corresponding
 
9811
values.  If a SHELL-FORMAT is given, only those environment variables
 
9812
that are referenced in SHELL-FORMAT are substituted; otherwise all
 
9813
environment variables references occurring in standard input are
 
9814
substituted.
 
9815
 
 
9816
   These substitutions are a subset of the substitutions that a shell
 
9817
performs on unquoted and double-quoted strings.  Other kinds of
 
9818
substitutions done by a shell, such as `${VARIABLE-DEFAULT}' or
 
9819
`$(COMMAND-LIST)' or ``COMMAND-LIST`', are not performed by the
 
9820
`envsubst' program, due to security reasons.
 
9821
 
 
9822
   When `--variables' is used, standard input is ignored, and the output
 
9823
consists of the environment variables that are referenced in
 
9824
SHELL-FORMAT, one per line.
 
9825
 
 
9826
 
 
9827
File: gettext.info,  Node: eval_gettext Invocation,  Next: eval_ngettext Invocation,  Prev: envsubst Invocation,  Up: sh
 
9828
 
 
9829
Invoking the `eval_gettext' function
 
9830
....................................
 
9831
 
 
9832
     eval_gettext MSGID
 
9833
 
 
9834
   This function outputs the native language translation of a textual
 
9835
message, performing dollar-substitution on the result.  Note that only
 
9836
shell variables mentioned in MSGID will be dollar-substituted in the
 
9837
result.
 
9838
 
 
9839
 
 
9840
File: gettext.info,  Node: eval_ngettext Invocation,  Prev: eval_gettext Invocation,  Up: sh
 
9841
 
 
9842
Invoking the `eval_ngettext' function
 
9843
.....................................
 
9844
 
 
9845
     eval_ngettext MSGID MSGID-PLURAL COUNT
 
9846
 
 
9847
   This function outputs the native language translation of a textual
 
9848
message whose grammatical form depends on a number, performing
 
9849
dollar-substitution on the result.  Note that only shell variables
 
9850
mentioned in MSGID or MSGID-PLURAL will be dollar-substituted in the
 
9851
result.
 
9852
 
 
9853
 
 
9854
File: gettext.info,  Node: bash,  Next: Python,  Prev: sh,  Up: List of Programming Languages
 
9855
 
 
9856
bash - Bourne-Again Shell Script
 
9857
--------------------------------
 
9858
 
 
9859
GNU `bash' 2.0 or newer has a special shorthand for translating a
 
9860
string and substituting variable values in it: `$"msgid"'.  But the use
 
9861
of this construct is *discouraged*, due to the security holes it opens
 
9862
and due to its portability problems.
 
9863
 
 
9864
   The security holes of `$"..."' come from the fact that after looking
 
9865
up the translation of the string, `bash' processes it like it processes
 
9866
any double-quoted string: dollar and backquote processing, like `eval'
 
9867
does.
 
9868
 
 
9869
  1. In a locale whose encoding is one of BIG5, BIG5-HKSCS, GBK,
 
9870
     GB18030, SHIFT_JIS, JOHAB, some double-byte characters have a
 
9871
     second byte whose value is `0x60'.  For example, the byte sequence
 
9872
     `\xe0\x60' is a single character in these locales.  Many versions
 
9873
     of `bash' (all versions up to bash-2.05, and newer versions on
 
9874
     platforms without `mbsrtowcs()' function) don't know about
 
9875
     character boundaries and see a backquote character where there is
 
9876
     only a particular Chinese character.  Thus it can start executing
 
9877
     part of the translation as a command list.  This situation can
 
9878
     occur even without the translator being aware of it: if the
 
9879
     translator provides translations in the UTF-8 encoding, it is the
 
9880
     `gettext()' function which will, during its conversion from the
 
9881
     translator's encoding to the user's locale's encoding, produce the
 
9882
     dangerous `\x60' bytes.
 
9883
 
 
9884
  2. A translator could - voluntarily or inadvertantly - use backquotes
 
9885
     `"`...`"' or dollar-parentheses `"$(...)"' in her translations.
 
9886
     The enclosed strings would be executed as command lists by the
 
9887
     shell.
 
9888
 
 
9889
   The portability problem is that `bash' must be built with
 
9890
internationalization support; this is normally not the case on systems
 
9891
that don't have the `gettext()' function in libc.
 
9892
 
 
9893
 
 
9894
File: gettext.info,  Node: Python,  Next: Common Lisp,  Prev: bash,  Up: List of Programming Languages
 
9895
 
 
9896
Python
 
9897
------
 
9898
 
 
9899
RPMs
 
9900
     python
 
9901
 
 
9902
File extension
 
9903
     `py'
 
9904
 
 
9905
String syntax
 
9906
     `'abc'', `u'abc'', `r'abc'', `ur'abc'',
 
9907
     `"abc"', `u"abc"', `r"abc"', `ur"abc"',
 
9908
     `'''abc'''', `u'''abc'''', `r'''abc'''', `ur'''abc'''',
 
9909
     `"""abc"""', `u"""abc"""', `r"""abc"""', `ur"""abc"""'
 
9910
 
 
9911
gettext shorthand
 
9912
     `_('abc')' etc.
 
9913
 
 
9914
gettext/ngettext functions
 
9915
     `gettext.gettext', `gettext.dgettext', `gettext.ngettext',
 
9916
     `gettext.dngettext', also `ugettext', `ungettext'
 
9917
 
 
9918
textdomain
 
9919
     `gettext.textdomain' function, or `gettext.install(DOMAIN)'
 
9920
     function
 
9921
 
 
9922
bindtextdomain
 
9923
     `gettext.bindtextdomain' function, or
 
9924
     `gettext.install(DOMAIN,LOCALEDIR)' function
 
9925
 
 
9926
setlocale
 
9927
     not used by the gettext emulation
 
9928
 
 
9929
Prerequisite
 
9930
     `import gettext'
 
9931
 
 
9932
Use or emulate GNU gettext
 
9933
     emulate.  Bug: uses only the first found .mo file, not all of them
 
9934
 
 
9935
Extractor
 
9936
     `xgettext'
 
9937
 
 
9938
Formatting with positions
 
9939
     `'...%(ident)d...' % { 'ident': value }'
 
9940
 
 
9941
Portability
 
9942
     fully portable
 
9943
 
 
9944
po-mode marking
 
9945
     --
 
9946
 
 
9947
   An example is available in the `examples' directory: `hello-python'.
 
9948
 
 
9949
 
 
9950
File: gettext.info,  Node: Common Lisp,  Next: clisp C,  Prev: Python,  Up: List of Programming Languages
 
9951
 
 
9952
GNU clisp - Common Lisp
 
9953
-----------------------
 
9954
 
 
9955
RPMs
 
9956
     clisp 2.28 or newer
 
9957
 
 
9958
File extension
 
9959
     `lisp'
 
9960
 
 
9961
String syntax
 
9962
     `"abc"'
 
9963
 
 
9964
gettext shorthand
 
9965
     `(_ "abc")', `(ENGLISH "abc")'
 
9966
 
 
9967
gettext/ngettext functions
 
9968
     `i18n:gettext', `i18n:ngettext'
 
9969
 
 
9970
textdomain
 
9971
     `i18n:textdomain'
 
9972
 
 
9973
bindtextdomain
 
9974
     `i18n:textdomaindir'
 
9975
 
 
9976
setlocale
 
9977
     automatic
 
9978
 
 
9979
Prerequisite
 
9980
     --
 
9981
 
 
9982
Use or emulate GNU gettext
 
9983
     use
 
9984
 
 
9985
Extractor
 
9986
     `xgettext -k_ -kENGLISH'
 
9987
 
 
9988
Formatting with positions
 
9989
     `format "~1@*~D ~0@*~D"'
 
9990
 
 
9991
Portability
 
9992
     On platforms without gettext, no translation.
 
9993
 
 
9994
po-mode marking
 
9995
     --
 
9996
 
 
9997
   An example is available in the `examples' directory: `hello-clisp'.
 
9998
 
 
9999
 
 
10000
File: gettext.info,  Node: clisp C,  Next: Emacs Lisp,  Prev: Common Lisp,  Up: List of Programming Languages
 
10001
 
 
10002
GNU clisp C sources
 
10003
-------------------
 
10004
 
 
10005
RPMs
 
10006
     clisp
 
10007
 
 
10008
File extension
 
10009
     `d'
 
10010
 
 
10011
String syntax
 
10012
     `"abc"'
 
10013
 
 
10014
gettext shorthand
 
10015
     `ENGLISH ? "abc" : ""'
 
10016
     `GETTEXT("abc")'
 
10017
     `GETTEXTL("abc")'
 
10018
 
 
10019
gettext/ngettext functions
 
10020
     `clgettext', `clgettextl'
 
10021
 
 
10022
textdomain
 
10023
     --
 
10024
 
 
10025
bindtextdomain
 
10026
     --
 
10027
 
 
10028
setlocale
 
10029
     automatic
 
10030
 
 
10031
Prerequisite
 
10032
     `#include "lispbibl.c"'
 
10033
 
 
10034
Use or emulate GNU gettext
 
10035
     use
 
10036
 
 
10037
Extractor
 
10038
     `clisp-xgettext'
 
10039
 
 
10040
Formatting with positions
 
10041
     `fprintf "%2$d %1$d"'
 
10042
 
 
10043
Portability
 
10044
     On platforms without gettext, no translation.
 
10045
 
 
10046
po-mode marking
 
10047
     --
 
10048
 
 
10049
 
 
10050
File: gettext.info,  Node: Emacs Lisp,  Next: librep,  Prev: clisp C,  Up: List of Programming Languages
 
10051
 
 
10052
Emacs Lisp
 
10053
----------
 
10054
 
 
10055
RPMs
 
10056
     emacs, xemacs
 
10057
 
 
10058
File extension
 
10059
     `el'
 
10060
 
 
10061
String syntax
 
10062
     `"abc"'
 
10063
 
 
10064
gettext shorthand
 
10065
     `(_"abc")'
 
10066
 
 
10067
gettext/ngettext functions
 
10068
     `gettext', `dgettext' (xemacs only)
 
10069
 
 
10070
textdomain
 
10071
     `domain' special form (xemacs only)
 
10072
 
 
10073
bindtextdomain
 
10074
     `bind-text-domain' function (xemacs only)
 
10075
 
 
10076
setlocale
 
10077
     automatic
 
10078
 
 
10079
Prerequisite
 
10080
     --
 
10081
 
 
10082
Use or emulate GNU gettext
 
10083
     use
 
10084
 
 
10085
Extractor
 
10086
     `xgettext'
 
10087
 
 
10088
Formatting with positions
 
10089
     `format "%2$d %1$d"'
 
10090
 
 
10091
Portability
 
10092
     Only XEmacs.  Without `I18N3' defined at build time, no
 
10093
     translation.
 
10094
 
 
10095
po-mode marking
 
10096
     --
 
10097
 
 
10098
 
 
10099
File: gettext.info,  Node: librep,  Next: Smalltalk,  Prev: Emacs Lisp,  Up: List of Programming Languages
 
10100
 
 
10101
librep
 
10102
------
 
10103
 
 
10104
RPMs
 
10105
     librep 0.15.3 or newer
 
10106
 
 
10107
File extension
 
10108
     `jl'
 
10109
 
 
10110
String syntax
 
10111
     `"abc"'
 
10112
 
 
10113
gettext shorthand
 
10114
     `(_"abc")'
 
10115
 
 
10116
gettext/ngettext functions
 
10117
     `gettext'
 
10118
 
 
10119
textdomain
 
10120
     `textdomain' function
 
10121
 
 
10122
bindtextdomain
 
10123
     `bindtextdomain' function
 
10124
 
 
10125
setlocale
 
10126
     --
 
10127
 
 
10128
Prerequisite
 
10129
     `(require 'rep.i18n.gettext)'
 
10130
 
 
10131
Use or emulate GNU gettext
 
10132
     use
 
10133
 
 
10134
Extractor
 
10135
     `xgettext'
 
10136
 
 
10137
Formatting with positions
 
10138
     `format "%2$d %1$d"'
 
10139
 
 
10140
Portability
 
10141
     On platforms without gettext, no translation.
 
10142
 
 
10143
po-mode marking
 
10144
     --
 
10145
 
 
10146
   An example is available in the `examples' directory: `hello-librep'.
 
10147
 
 
10148
 
 
10149
File: gettext.info,  Node: Smalltalk,  Next: Java,  Prev: librep,  Up: List of Programming Languages
 
10150
 
 
10151
GNU Smalltalk
 
10152
-------------
 
10153
 
 
10154
RPMs
 
10155
     smalltalk
 
10156
 
 
10157
File extension
 
10158
     `st'
 
10159
 
 
10160
String syntax
 
10161
     `'abc''
 
10162
 
 
10163
gettext shorthand
 
10164
     `NLS ? 'abc''
 
10165
 
 
10166
gettext/ngettext functions
 
10167
     `LcMessagesDomain>>#at:', `LcMessagesDomain>>#at:plural:with:'
 
10168
 
 
10169
textdomain
 
10170
     `LcMessages>>#domain:localeDirectory:' (returns a
 
10171
     `LcMessagesDomain' object).
 
10172
     Example: `I18N Locale default messages domain: 'gettext'
 
10173
     localeDirectory: /usr/local/share/locale''
 
10174
 
 
10175
bindtextdomain
 
10176
     `LcMessages>>#domain:localeDirectory:', see above.
 
10177
 
 
10178
setlocale
 
10179
     Automatic if you use `I18N Locale default'.
 
10180
 
 
10181
Prerequisite
 
10182
     `PackageLoader fileInPackage: 'I18N'!'
 
10183
 
 
10184
Use or emulate GNU gettext
 
10185
     emulate
 
10186
 
 
10187
Extractor
 
10188
     `xgettext'
 
10189
 
 
10190
Formatting with positions
 
10191
     `'%1 %2' bindWith: 'Hello' with: 'world''
 
10192
 
 
10193
Portability
 
10194
     fully portable
 
10195
 
 
10196
po-mode marking
 
10197
     --
 
10198
 
 
10199
   An example is available in the `examples' directory:
 
10200
`hello-smalltalk'.
 
10201
 
 
10202
 
 
10203
File: gettext.info,  Node: Java,  Next: C#,  Prev: Smalltalk,  Up: List of Programming Languages
 
10204
 
 
10205
Java
 
10206
----
 
10207
 
 
10208
RPMs
 
10209
     java, java2
 
10210
 
 
10211
File extension
 
10212
     `java'
 
10213
 
 
10214
String syntax
 
10215
     "abc"
 
10216
 
 
10217
gettext shorthand
 
10218
     _("abc")
 
10219
 
 
10220
gettext/ngettext functions
 
10221
     `GettextResource.gettext', `GettextResource.ngettext'
 
10222
 
 
10223
textdomain
 
10224
     --, use `ResourceBundle.getResource' instead
 
10225
 
 
10226
bindtextdomain
 
10227
     --, use CLASSPATH instead
 
10228
 
 
10229
setlocale
 
10230
     automatic
 
10231
 
 
10232
Prerequisite
 
10233
     --
 
10234
 
 
10235
Use or emulate GNU gettext
 
10236
     --, uses a Java specific message catalog format
 
10237
 
 
10238
Extractor
 
10239
     `xgettext -k_'
 
10240
 
 
10241
Formatting with positions
 
10242
     `MessageFormat.format "{1,number} {0,number}"'
 
10243
 
 
10244
Portability
 
10245
     fully portable
 
10246
 
 
10247
po-mode marking
 
10248
     --
 
10249
 
 
10250
   Before marking strings as internationalizable, uses of the string
 
10251
concatenation operator need to be converted to `MessageFormat'
 
10252
applications.  For example, `"file "+filename+" not found"' becomes
 
10253
`MessageFormat.format("file {0} not found", new Object[] { filename })'.
 
10254
Only after this is done, can the strings be marked and extracted.
 
10255
 
 
10256
   GNU gettext uses the native Java internationalization mechanism,
 
10257
namely `ResourceBundle's.  There are two formats of `ResourceBundle's:
 
10258
`.properties' files and `.class' files.  The `.properties' format is a
 
10259
text file which the translators can directly edit, like PO files, but
 
10260
which doesn't support plural forms.  Whereas the `.class' format is
 
10261
compiled from `.java' source code and can support plural forms
 
10262
(provided it is accessed through an appropriate API, see below).
 
10263
 
 
10264
   To convert a PO file to a `.properties' file, the `msgcat' program
 
10265
can be used with the option `--properties-output'.  To convert a
 
10266
`.properties' file back to a PO file, the `msgcat' program can be used
 
10267
with the option `--properties-input'.  All the tools that manipulate PO
 
10268
files can work with `.properties' files as well, if given the
 
10269
`--properties-input' and/or `--properties-output' option.
 
10270
 
 
10271
   To convert a PO file to a ResourceBundle class, the `msgfmt' program
 
10272
can be used with the option `--java' or `--java2'.  To convert a
 
10273
ResourceBundle back to a PO file, the `msgunfmt' program can be used
 
10274
with the option `--java'.
 
10275
 
 
10276
   Two different programmatic APIs can be used to access
 
10277
ResourceBundles.  Note that both APIs work with all kinds of
 
10278
ResourceBundles, whether GNU gettext generated classes, or other
 
10279
`.class' or `.properties' files.
 
10280
 
 
10281
  1. The `java.util.ResourceBundle' API.
 
10282
 
 
10283
     In particular, its `getString' function returns a string
 
10284
     translation.  Note that a missing translation yields a
 
10285
     `MissingResourceException'.
 
10286
 
 
10287
     This has the advantage of being the standard API.  And it does not
 
10288
     require any additional libraries, only the `msgcat' generated
 
10289
     `.properties' files or the `msgfmt' generated `.class' files.  But
 
10290
     it cannot do plural handling, even if the resource was generated
 
10291
     by `msgfmt' from a PO file with plural handling.
 
10292
 
 
10293
  2. The `gnu.gettext.GettextResource' API.
 
10294
 
 
10295
     Reference documentation in Javadoc 1.1 style format is in the
 
10296
     javadoc1 directory (javadoc1/tree.html) and in Javadoc 2 style
 
10297
     format in the javadoc2 directory (javadoc2/index.html).
 
10298
 
 
10299
     Its `gettext' function returns a string translation.  Note that
 
10300
     when a translation is missing, the MSGID argument is returned
 
10301
     unchanged.
 
10302
 
 
10303
     This has the advantage of having the `ngettext' function for plural
 
10304
     handling.
 
10305
 
 
10306
     To use this API, one needs the `libintl.jar' file which is part of
 
10307
     the GNU gettext package and distributed under the LGPL.
 
10308
 
 
10309
   Three examples, using the second API, are available in the `examples'
 
10310
directory: `hello-java', `hello-java-awt', `hello-java-swing'.
 
10311
 
 
10312
   Now, to make use of the API and define a shorthand for `getString',
 
10313
there are two idioms that you can choose from:
 
10314
 
 
10315
   * In a unique class of your project, say `Util', define a static
 
10316
     variable holding the `ResourceBundle' instance:
 
10317
 
 
10318
          public static ResourceBundle myResources =
 
10319
            ResourceBundle.getBundle("domain-name");
 
10320
 
 
10321
     All classes containing internationalized strings then contain
 
10322
 
 
10323
          private static ResourceBundle res = Util.myResources;
 
10324
          private static String _(String s) { return res.getString(s); }
 
10325
 
 
10326
     and the shorthand is used like this:
 
10327
 
 
10328
          System.out.println(_("Operation completed."));
 
10329
 
 
10330
   * You add a class with a very short name, say `S', containing just
 
10331
     the definition of the resource bundle and of the shorthand:
 
10332
 
 
10333
          public class S {
 
10334
            public static ResourceBundle myResources =
 
10335
              ResourceBundle.getBundle("domain-name");
 
10336
            public static String _(String s) {
 
10337
              return myResources.getString(s);
 
10338
            }
 
10339
          }
 
10340
 
 
10341
     and the shorthand is used like this:
 
10342
 
 
10343
          System.out.println(S._("Operation completed."));
 
10344
 
 
10345
   Which of the two idioms you choose, will depend on whether copying
 
10346
two lines of codes into every class is more acceptable in your project
 
10347
than a class with a single-letter name.
 
10348
 
 
10349
 
 
10350
File: gettext.info,  Node: C#,  Next: gawk,  Prev: Java,  Up: List of Programming Languages
 
10351
 
 
10352
C#
 
10353
--
 
10354
 
 
10355
RPMs
 
10356
     pnet, pnetlib 0.6.2 or newer, or mono 0.29 or newer
 
10357
 
 
10358
File extension
 
10359
     `cs'
 
10360
 
 
10361
String syntax
 
10362
     `"abc"', `@"abc"'
 
10363
 
 
10364
gettext shorthand
 
10365
     _("abc")
 
10366
 
 
10367
gettext/ngettext functions
 
10368
     `GettextResourceManager.GetString',
 
10369
     `GettextResourceManager.GetPluralString'
 
10370
 
 
10371
textdomain
 
10372
     `new GettextResourceManager(domain)'
 
10373
 
 
10374
bindtextdomain
 
10375
     --, compiled message catalogs are located in subdirectories of the
 
10376
     directory containing the executable
 
10377
 
 
10378
setlocale
 
10379
     automatic
 
10380
 
 
10381
Prerequisite
 
10382
     --
 
10383
 
 
10384
Use or emulate GNU gettext
 
10385
     --, uses a C# specific message catalog format
 
10386
 
 
10387
Extractor
 
10388
     `xgettext -k_'
 
10389
 
 
10390
Formatting with positions
 
10391
     `String.Format "{1} {0}"'
 
10392
 
 
10393
Portability
 
10394
     fully portable
 
10395
 
 
10396
po-mode marking
 
10397
     --
 
10398
 
 
10399
   Before marking strings as internationalizable, uses of the string
 
10400
concatenation operator need to be converted to `String.Format'
 
10401
invocations.  For example, `"file "+filename+" not found"' becomes
 
10402
`String.Format("file {0} not found", filename)'.  Only after this is
 
10403
done, can the strings be marked and extracted.
 
10404
 
 
10405
   GNU gettext uses the native C#/.NET internationalization mechanism,
 
10406
namely the classes `ResourceManager' and `ResourceSet'.  Applications
 
10407
use the `ResourceManager' methods to retrieve the native language
 
10408
translation of strings.  An instance of `ResourceSet' is the in-memory
 
10409
representation of a message catalog file.  The `ResourceManager' loads
 
10410
and accesses `ResourceSet' instances as needed to look up the
 
10411
translations.
 
10412
 
 
10413
   There are two formats of `ResourceSet's that can be directly loaded
 
10414
by the C# runtime: `.resources' files and `.dll' files.
 
10415
 
 
10416
   * The `.resources' format is a binary file usually generated through
 
10417
     the `resgen' or `monoresgen' utility, but which doesn't support
 
10418
     plural forms.  `.resources' files can also be embedded in .NET
 
10419
     `.exe' files.  This only affects whether a file system access is
 
10420
     performed to load the message catalog; it doesn't affect the
 
10421
     contents of the message catalog.
 
10422
 
 
10423
   * On the other hand, the `.dll' format is a binary file that is
 
10424
     compiled from `.cs' source code and can support plural forms
 
10425
     (provided it is accessed through the GNU gettext API, see below).
 
10426
 
 
10427
   Note that these .NET `.dll' and `.exe' files are not tied to a
 
10428
particular platform; their file format and GNU gettext for C# can be
 
10429
used on any platform.
 
10430
 
 
10431
   To convert a PO file to a `.resources' file, the `msgfmt' program
 
10432
can be used with the option `--csharp-resources'.  To convert a
 
10433
`.resources' file back to a PO file, the `msgunfmt' program can be used
 
10434
with the option `--csharp-resources'.  You can also, in some cases, use
 
10435
the `resgen' program (from the `pnet' package) or the `monoresgen'
 
10436
program (from the `mono'/`mcs' package).  These programs can also
 
10437
convert a `.resources' file back to a PO file.  But beware: as of this
 
10438
writing (January 2004), the `monoresgen' converter is quite buggy and
 
10439
the `resgen' converter ignores the encoding of the PO files.
 
10440
 
 
10441
   To convert a PO file to a `.dll' file, the `msgfmt' program can be
 
10442
used with the option `--csharp'.  The result will be a `.dll' file
 
10443
containing a subclass of `GettextResourceSet', which itself is a
 
10444
subclass of `ResourceSet'.  To convert a `.dll' file containing a
 
10445
`GettextResourceSet' subclass back to a PO file, the `msgunfmt' program
 
10446
can be used with the option `--csharp'.
 
10447
 
 
10448
   The advantages of the `.dll' format over the `.resources' format are:
 
10449
 
 
10450
  1. Freedom to localize: Users can add their own translations to an
 
10451
     application after it has been built and distributed.  Whereas when
 
10452
     the programmer uses a `ResourceManager' constructor provided by
 
10453
     the system, the set of `.resources' files for an application must
 
10454
     be specified when the application is built and cannot be extended
 
10455
     afterwards.
 
10456
 
 
10457
  2. Plural handling: A message catalog in `.dll' format supports the
 
10458
     plural handling function `GetPluralString'.  Whereas `.resources'
 
10459
     files can only contain data and only support lookups that depend
 
10460
     on a single string.
 
10461
 
 
10462
  3. The `GettextResourceManager' that loads the message catalogs in
 
10463
     `.dll' format also provides for inheritance on a per-message basis.
 
10464
     For example, in Austrian (`de_AT') locale, translations from the
 
10465
     German (`de') message catalog will be used for messages not found
 
10466
     in the Austrian message catalog.  This has the consequence that
 
10467
     the Austrian translators need only translate those few messages
 
10468
     for which the translation into Austrian differs from the German
 
10469
     one.  Whereas when working with `.resources' files, each message
 
10470
     catalog must provide the translations of all messages by itself.
 
10471
 
 
10472
  4. The `GettextResourceManager' that loads the message catalogs in
 
10473
     `.dll' format also provides for a fallback: The English MSGID is
 
10474
     returned when no translation can be found.  Whereas when working
 
10475
     with `.resources' files, a language-neutral `.resources' file must
 
10476
     explicitly be provided as a fallback.
 
10477
 
 
10478
   On the side of the programmatic APIs, the programmer can use either
 
10479
the standard `ResourceManager' API and the GNU `GettextResourceManager'
 
10480
API.  The latter is an extension of the former, because
 
10481
`GettextResourceManager' is a subclass of `ResourceManager'.
 
10482
 
 
10483
  1. The `System.Resources.ResourceManager' API.
 
10484
 
 
10485
     This API works with resources in `.resources' format.
 
10486
 
 
10487
     The creation of the `ResourceManager' is done through
 
10488
            new ResourceManager(domainname, Assembly.GetExecutingAssembly())
 
10489
 
 
10490
     The `GetString' function returns a string's translation.  Note
 
10491
     that this function returns null when a translation is missing
 
10492
     (i.e. not even found in the fallback resource file).
 
10493
 
 
10494
  2. The `GNU.Gettext.GettextResourceManager' API.
 
10495
 
 
10496
     This API works with resources in `.dll' format.
 
10497
 
 
10498
     Reference documentation is in the csharpdoc directory
 
10499
     (csharpdoc/index.html).
 
10500
 
 
10501
     The creation of the `ResourceManager' is done through
 
10502
            new GettextResourceManager(domainname)
 
10503
 
 
10504
     The `GetString' function returns a string's translation.  Note
 
10505
     that when a translation is missing, the MSGID argument is returned
 
10506
     unchanged.
 
10507
 
 
10508
     The `GetPluralString' function returns a string translation with
 
10509
     plural handling, like the `ngettext' function in C.
 
10510
 
 
10511
     To use this API, one needs the `GNU.Gettext.dll' file which is
 
10512
     part of the GNU gettext package and distributed under the LGPL.
 
10513
 
 
10514
   You can also mix both approaches: use the
 
10515
`GNU.Gettext.GettextResourceManager' constructor, but otherwise use
 
10516
only the `ResourceManager' type and only the `GetString' method.  This
 
10517
is appropriate when you want to profit from the tools for PO files, but
 
10518
don't want to change an existing source code that uses
 
10519
`ResourceManager' and don't (yet) need the `GetPluralString' method.
 
10520
 
 
10521
   Two examples, using the second API, are available in the `examples'
 
10522
directory: `hello-csharp', `hello-csharp-forms'.
 
10523
 
 
10524
   Now, to make use of the API and define a shorthand for `GetString',
 
10525
there are two idioms that you can choose from:
 
10526
 
 
10527
   * In a unique class of your project, say `Util', define a static
 
10528
     variable holding the `ResourceManager' instance:
 
10529
 
 
10530
          public static GettextResourceManager MyResourceManager =
 
10531
            new GettextResourceManager("domain-name");
 
10532
 
 
10533
     All classes containing internationalized strings then contain
 
10534
 
 
10535
          private static GettextResourceManager Res = Util.MyResourceManager;
 
10536
          private static String _(String s) { return Res.GetString(s); }
 
10537
 
 
10538
     and the shorthand is used like this:
 
10539
 
 
10540
          Console.WriteLine(_("Operation completed."));
 
10541
 
 
10542
   * You add a class with a very short name, say `S', containing just
 
10543
     the definition of the resource manager and of the shorthand:
 
10544
 
 
10545
          public class S {
 
10546
            public static GettextResourceManager MyResourceManager =
 
10547
              new GettextResourceManager("domain-name");
 
10548
            public static String _(String s) {
 
10549
               return MyResourceManager.GetString(s);
 
10550
            }
 
10551
          }
 
10552
 
 
10553
     and the shorthand is used like this:
 
10554
 
 
10555
          Console.WriteLine(S._("Operation completed."));
 
10556
 
 
10557
   Which of the two idioms you choose, will depend on whether copying
 
10558
two lines of codes into every class is more acceptable in your project
 
10559
than a class with a single-letter name.
 
10560
 
 
10561
 
 
10562
File: gettext.info,  Node: gawk,  Next: Pascal,  Prev: C#,  Up: List of Programming Languages
 
10563
 
 
10564
GNU awk
 
10565
-------
 
10566
 
 
10567
RPMs
 
10568
     gawk 3.1 or newer
 
10569
 
 
10570
File extension
 
10571
     `awk'
 
10572
 
 
10573
String syntax
 
10574
     `"abc"'
 
10575
 
 
10576
gettext shorthand
 
10577
     `_"abc"'
 
10578
 
 
10579
gettext/ngettext functions
 
10580
     `dcgettext', missing `dcngettext' in gawk-3.1.0
 
10581
 
 
10582
textdomain
 
10583
     `TEXTDOMAIN' variable
 
10584
 
 
10585
bindtextdomain
 
10586
     `bindtextdomain' function
 
10587
 
 
10588
setlocale
 
10589
     automatic, but missing `setlocale (LC_MESSAGES, "")' in gawk-3.1.0
 
10590
 
 
10591
Prerequisite
 
10592
     --
 
10593
 
 
10594
Use or emulate GNU gettext
 
10595
     use
 
10596
 
 
10597
Extractor
 
10598
     `xgettext'
 
10599
 
 
10600
Formatting with positions
 
10601
     `printf "%2$d %1$d"' (GNU awk only)
 
10602
 
 
10603
Portability
 
10604
     On platforms without gettext, no translation.  On non-GNU awks,
 
10605
     you must define `dcgettext', `dcngettext' and `bindtextdomain'
 
10606
     yourself.
 
10607
 
 
10608
po-mode marking
 
10609
     --
 
10610
 
 
10611
   An example is available in the `examples' directory: `hello-gawk'.
 
10612
 
 
10613
 
 
10614
File: gettext.info,  Node: Pascal,  Next: wxWindows,  Prev: gawk,  Up: List of Programming Languages
 
10615
 
 
10616
Pascal - Free Pascal Compiler
 
10617
-----------------------------
 
10618
 
 
10619
RPMs
 
10620
     fpk
 
10621
 
 
10622
File extension
 
10623
     `pp', `pas'
 
10624
 
 
10625
String syntax
 
10626
     `'abc''
 
10627
 
 
10628
gettext shorthand
 
10629
     automatic
 
10630
 
 
10631
gettext/ngettext functions
 
10632
     --, use `ResourceString' data type instead
 
10633
 
 
10634
textdomain
 
10635
     --, use `TranslateResourceStrings' function instead
 
10636
 
 
10637
bindtextdomain
 
10638
     --, use `TranslateResourceStrings' function instead
 
10639
 
 
10640
setlocale
 
10641
     automatic, but uses only LANG, not LC_MESSAGES or LC_ALL
 
10642
 
 
10643
Prerequisite
 
10644
     `{$mode delphi}' or `{$mode objfpc}'
 
10645
     `uses gettext;'
 
10646
 
 
10647
Use or emulate GNU gettext
 
10648
     emulate partially
 
10649
 
 
10650
Extractor
 
10651
     `ppc386' followed by `xgettext' or `rstconv'
 
10652
 
 
10653
Formatting with positions
 
10654
     `uses sysutils;'
 
10655
     `format "%1:d %0:d"'
 
10656
 
 
10657
Portability
 
10658
     ?
 
10659
 
 
10660
po-mode marking
 
10661
     --
 
10662
 
 
10663
   The Pascal compiler has special support for the `ResourceString' data
 
10664
type.  It generates a `.rst' file.  This is then converted to a `.pot'
 
10665
file by use of `xgettext' or `rstconv'.  At runtime, a `.mo' file
 
10666
corresponding to translations of this `.pot' file can be loaded using
 
10667
the `TranslateResourceStrings' function in the `gettext' unit.
 
10668
 
 
10669
   An example is available in the `examples' directory: `hello-pascal'.
 
10670
 
 
10671
 
 
10672
File: gettext.info,  Node: wxWindows,  Next: YCP,  Prev: Pascal,  Up: List of Programming Languages
 
10673
 
 
10674
wxWindows library
 
10675
-----------------
 
10676
 
 
10677
RPMs
 
10678
     wxGTK, gettext
 
10679
 
 
10680
File extension
 
10681
     `cpp'
 
10682
 
 
10683
String syntax
 
10684
     `"abc"'
 
10685
 
 
10686
gettext shorthand
 
10687
     `_("abc")'
 
10688
 
 
10689
gettext/ngettext functions
 
10690
     `wxLocale::GetString', `wxGetTranslation'
 
10691
 
 
10692
textdomain
 
10693
     `wxLocale::AddCatalog'
 
10694
 
 
10695
bindtextdomain
 
10696
     `wxLocale::AddCatalogLookupPathPrefix'
 
10697
 
 
10698
setlocale
 
10699
     `wxLocale::Init', `wxSetLocale'
 
10700
 
 
10701
Prerequisite
 
10702
     `#include <wx/intl.h>'
 
10703
 
 
10704
Use or emulate GNU gettext
 
10705
     emulate, see `include/wx/intl.h' and `src/common/intl.cpp'
 
10706
 
 
10707
Extractor
 
10708
     `xgettext'
 
10709
 
 
10710
Formatting with positions
 
10711
     --
 
10712
 
 
10713
Portability
 
10714
     fully portable
 
10715
 
 
10716
po-mode marking
 
10717
     yes
 
10718
 
 
10719
 
 
10720
File: gettext.info,  Node: YCP,  Next: Tcl,  Prev: wxWindows,  Up: List of Programming Languages
 
10721
 
 
10722
YCP - YaST2 scripting language
 
10723
------------------------------
 
10724
 
 
10725
RPMs
 
10726
     libycp, libycp-devel, yast2-core, yast2-core-devel
 
10727
 
 
10728
File extension
 
10729
     `ycp'
 
10730
 
 
10731
String syntax
 
10732
     `"abc"'
 
10733
 
 
10734
gettext shorthand
 
10735
     `_("abc")'
 
10736
 
 
10737
gettext/ngettext functions
 
10738
     `_()' with 1 or 3 arguments
 
10739
 
 
10740
textdomain
 
10741
     `textdomain' statement
 
10742
 
 
10743
bindtextdomain
 
10744
     --
 
10745
 
 
10746
setlocale
 
10747
     --
 
10748
 
 
10749
Prerequisite
 
10750
     --
 
10751
 
 
10752
Use or emulate GNU gettext
 
10753
     use
 
10754
 
 
10755
Extractor
 
10756
     `xgettext'
 
10757
 
 
10758
Formatting with positions
 
10759
     `sformat "%2 %1"'
 
10760
 
 
10761
Portability
 
10762
     fully portable
 
10763
 
 
10764
po-mode marking
 
10765
     --
 
10766
 
 
10767
   An example is available in the `examples' directory: `hello-ycp'.
 
10768
 
 
10769
 
 
10770
File: gettext.info,  Node: Tcl,  Next: Perl,  Prev: YCP,  Up: List of Programming Languages
 
10771
 
 
10772
Tcl - Tk's scripting language
 
10773
-----------------------------
 
10774
 
 
10775
RPMs
 
10776
     tcl
 
10777
 
 
10778
File extension
 
10779
     `tcl'
 
10780
 
 
10781
String syntax
 
10782
     `"abc"'
 
10783
 
 
10784
gettext shorthand
 
10785
     `[_ "abc"]'
 
10786
 
 
10787
gettext/ngettext functions
 
10788
     `::msgcat::mc'
 
10789
 
 
10790
textdomain
 
10791
     --
 
10792
 
 
10793
bindtextdomain
 
10794
     --, use `::msgcat::mcload' instead
 
10795
 
 
10796
setlocale
 
10797
     automatic, uses LANG, but ignores LC_MESSAGES and LC_ALL
 
10798
 
 
10799
Prerequisite
 
10800
     `package require msgcat'
 
10801
     `proc _ {s} {return [::msgcat::mc $s]}'
 
10802
 
 
10803
Use or emulate GNU gettext
 
10804
     --, uses a Tcl specific message catalog format
 
10805
 
 
10806
Extractor
 
10807
     `xgettext -k_'
 
10808
 
 
10809
Formatting with positions
 
10810
     `format "%2\$d %1\$d"'
 
10811
 
 
10812
Portability
 
10813
     fully portable
 
10814
 
 
10815
po-mode marking
 
10816
     --
 
10817
 
 
10818
   Two examples are available in the `examples' directory: `hello-tcl',
 
10819
`hello-tcl-tk'.
 
10820
 
 
10821
   Before marking strings as internationalizable, substitutions of
 
10822
variables into the string need to be converted to `format'
 
10823
applications.  For example, `"file $filename not found"' becomes
 
10824
`[format "file %s not found" $filename]'.  Only after this is done, can
 
10825
the strings be marked and extracted.  After marking, this example
 
10826
becomes `[format [_ "file %s not found"] $filename]' or `[msgcat::mc
 
10827
"file %s not found" $filename]'.  Note that the `msgcat::mc' function
 
10828
implicitly calls `format' when more than one argument is given.
 
10829
 
 
10830
 
 
10831
File: gettext.info,  Node: Perl,  Next: PHP,  Prev: Tcl,  Up: List of Programming Languages
 
10832
 
 
10833
Perl
 
10834
----
 
10835
 
 
10836
RPMs
 
10837
     perl
 
10838
 
 
10839
File extension
 
10840
     `pl', `PL', `pm', `cgi'
 
10841
 
 
10842
String syntax
 
10843
        * `"abc"'
 
10844
 
 
10845
        * `'abc''
 
10846
 
 
10847
        * `qq (abc)'
 
10848
 
 
10849
        * `q (abc)'
 
10850
 
 
10851
        * `qr /abc/'
 
10852
 
 
10853
        * `qx (/bin/date)'
 
10854
 
 
10855
        * `/pattern match/'
 
10856
 
 
10857
        * `?pattern match?'
 
10858
 
 
10859
        * `s/substitution/operators/'
 
10860
 
 
10861
        * `$tied_hash{"message"}'
 
10862
 
 
10863
        * `$tied_hash_reference->{"message"}'
 
10864
 
 
10865
        * etc., issue the command `man perlsyn' for details
 
10866
 
 
10867
 
 
10868
gettext shorthand
 
10869
     `__' (double underscore)
 
10870
 
 
10871
gettext/ngettext functions
 
10872
     `gettext', `dgettext', `dcgettext', `ngettext', `dngettext',
 
10873
     `dcngettext'
 
10874
 
 
10875
textdomain
 
10876
     `textdomain' function
 
10877
 
 
10878
bindtextdomain
 
10879
     `bindtextdomain' function
 
10880
 
 
10881
bind_textdomain_codeset
 
10882
     `bind_textdomain_codeset' function
 
10883
 
 
10884
setlocale
 
10885
     Use `setlocale (LC_ALL, "");'
 
10886
 
 
10887
Prerequisite
 
10888
     `use POSIX;'
 
10889
     `use Locale::TextDomain;' (included in the package libintl-perl
 
10890
     which is available on the Comprehensive Perl Archive Network CPAN,
 
10891
     http://www.cpan.org/).
 
10892
 
 
10893
Use or emulate GNU gettext
 
10894
     platform dependent: gettext_pp emulates, gettext_xs uses GNU
 
10895
     gettext
 
10896
 
 
10897
Extractor
 
10898
     `xgettext -k__ -k\$__ -k%__ -k__x -k__n:1,2 -k__nx:1,2 -k__xn:1,2
 
10899
     -kN__ -k'
 
10900
 
 
10901
Formatting with positions
 
10902
     Both kinds of format strings support formatting with positions.
 
10903
     `printf "%2\$d %1\$d", ...' (requires Perl 5.8.0 or newer)
 
10904
     `__expand("[new] replaces [old]", old => $oldvalue, new =>
 
10905
     $newvalue)'
 
10906
 
 
10907
Portability
 
10908
     The `libintl-perl' package is platform independent but is not part
 
10909
     of the Perl core.  The programmer is responsible for providing a
 
10910
     dummy implementation of the required functions if the package is
 
10911
     not installed on the target system.
 
10912
 
 
10913
po-mode marking
 
10914
     --
 
10915
 
 
10916
Documentation
 
10917
     Included in `libintl-perl', available on CPAN
 
10918
     (http://www.cpan.org/).
 
10919
 
 
10920
 
 
10921
   An example is available in the `examples' directory: `hello-perl'.
 
10922
 
 
10923
   The `xgettext' parser backend for Perl differs significantly from
 
10924
the parser backends for other programming languages, just as Perl
 
10925
itself differs significantly from other programming languages.  The
 
10926
Perl parser backend offers many more string marking facilities than the
 
10927
other backends but it also has some Perl specific limitations, the
 
10928
worst probably being its imperfectness.
 
10929
 
 
10930
* Menu:
 
10931
 
 
10932
* General Problems::            General Problems Parsing Perl Code
 
10933
* Default Keywords::            Which Keywords Will xgettext Look For?
 
10934
* Special Keywords::            How to Extract Hash Keys
 
10935
* Quote-like Expressions::      What are Strings And Quote-like Expressions?
 
10936
* Interpolation I::             Invalid String Interpolation
 
10937
* Interpolation II::            Valid String Interpolation
 
10938
* Parentheses::                 When To Use Parentheses
 
10939
* Long Lines::                  How To Grok with Long Lines
 
10940
* Perl Pitfalls::               Bugs, Pitfalls, and Things That Do Not Work
 
10941
 
 
10942
 
 
10943
File: gettext.info,  Node: General Problems,  Next: Default Keywords,  Up: Perl
 
10944
 
 
10945
General Problems Parsing Perl Code
 
10946
..................................
 
10947
 
 
10948
It is often heard that only Perl can parse Perl.  This is not true.
 
10949
Perl cannot be _parsed_ at all, it can only be _executed_.  Perl has
 
10950
various built-in ambiguities that can only be resolved at runtime.
 
10951
 
 
10952
   The following example may illustrate one common problem:
 
10953
 
 
10954
     print gettext "Hello World!";
 
10955
 
 
10956
   Although this example looks like a bullet-proof case of a function
 
10957
invocation, it is not:
 
10958
 
 
10959
     open gettext, ">testfile" or die;
 
10960
     print gettext "Hello world!"
 
10961
 
 
10962
   In this context, the string `gettext' looks more like a file handle.
 
10963
But not necessarily:
 
10964
 
 
10965
     use Locale::Messages qw (:libintl_h);
 
10966
     open gettext ">testfile" or die;
 
10967
     print gettext "Hello world!";
 
10968
 
 
10969
   Now, the file is probably syntactically incorrect, provided that the
 
10970
module `Locale::Messages' found first in the Perl include path exports a
 
10971
function `gettext'.  But what if the module `Locale::Messages' really
 
10972
looks like this?
 
10973
 
 
10974
     use vars qw (*gettext);
 
10975
     
 
10976
     1;
 
10977
 
 
10978
   In this case, the string `gettext' will be interpreted as a file
 
10979
handle again, and the above example will create a file `testfile' and
 
10980
write the string "Hello world!" into it.  Even advanced control flow
 
10981
analysis will not really help:
 
10982
 
 
10983
     if (0.5 < rand) {
 
10984
        eval "use Sane";
 
10985
     } else {
 
10986
        eval "use InSane";
 
10987
     }
 
10988
     print gettext "Hello world!";
 
10989
 
 
10990
   If the module `Sane' exports a function `gettext' that does what we
 
10991
expect, and the module `InSane' opens a file for writing and associates
 
10992
the _handle_ `gettext' with this output stream, we are clueless again
 
10993
about what will happen at runtime.  It is completely unpredictable.
 
10994
The truth is that Perl has so many ways to fill its symbol table at
 
10995
runtime that it is impossible to interpret a particular piece of code
 
10996
without executing it.
 
10997
 
 
10998
   Of course, `xgettext' will not execute your Perl sources while
 
10999
scanning for translatable strings, but rather use heuristics in order
 
11000
to guess what you meant.
 
11001
 
 
11002
   Another problem is the ambiguity of the slash and the question mark.
 
11003
Their interpretation depends on the context:
 
11004
 
 
11005
     # A pattern match.
 
11006
     print "OK\n" if /foobar/;
 
11007
     
 
11008
     # A division.
 
11009
     print 1 / 2;
 
11010
     
 
11011
     # Another pattern match.
 
11012
     print "OK\n" if ?foobar?;
 
11013
     
 
11014
     # Conditional.
 
11015
     print $x ? "foo" : "bar";
 
11016
 
 
11017
   The slash may either act as the division operator or introduce a
 
11018
pattern match, whereas the question mark may act as the ternary
 
11019
conditional operator or as a pattern match, too.  Other programming
 
11020
languages like `awk' present similar problems, but the consequences of a
 
11021
misinterpretation are particularly nasty with Perl sources.  In `awk'
 
11022
for instance, a statement can never exceed one line and the parser can
 
11023
recover from a parsing error at the next newline and interpret the rest
 
11024
of the input stream correctly.  Perl is different, as a pattern match
 
11025
is terminated by the next appearance of the delimiter (the slash or the
 
11026
question mark) in the input stream, regardless of the semantic context.
 
11027
If a slash is really a division sign but mis-interpreted as a pattern
 
11028
match, the rest of the input file is most probably parsed incorrectly.
 
11029
 
 
11030
   If you find that `xgettext' fails to extract strings from portions
 
11031
of your sources, you should therefore look out for slashes and/or
 
11032
question marks preceding these sections.  You may have come across a
 
11033
bug in `xgettext''s Perl parser (and of course you should report that
 
11034
bug).  In the meantime you should consider to reformulate your code in
 
11035
a manner less challenging to `xgettext'.
 
11036
 
 
11037
 
 
11038
File: gettext.info,  Node: Default Keywords,  Next: Special Keywords,  Prev: General Problems,  Up: Perl
 
11039
 
 
11040
Which keywords will xgettext look for?
 
11041
......................................
 
11042
 
 
11043
Unless you instruct `xgettext' otherwise by invoking it with one of the
 
11044
options `--keyword' or `-k', it will recognize the following keywords
 
11045
in your Perl sources:
 
11046
 
 
11047
   * `gettext'
 
11048
 
 
11049
   * `dgettext'
 
11050
 
 
11051
   * `dcgettext'
 
11052
 
 
11053
   * `ngettext:1,2'
 
11054
 
 
11055
     The first (singular) and the second (plural) argument will be
 
11056
     extracted.
 
11057
 
 
11058
   * `dngettext:1,2'
 
11059
 
 
11060
     The first (singular) and the second (plural) argument will be
 
11061
     extracted.
 
11062
 
 
11063
   * `dcngettext:1,2'
 
11064
 
 
11065
     The first (singular) and the second (plural) argument will be
 
11066
     extracted.
 
11067
 
 
11068
   * `gettext_noop'
 
11069
 
 
11070
   * `%gettext'
 
11071
 
 
11072
     The keys of lookups into the hash `%gettext' will be extracted.
 
11073
 
 
11074
   * `$gettext'
 
11075
 
 
11076
     The keys of lookups into the hash reference `$gettext' will be
 
11077
     extracted.
 
11078
 
 
11079
 
 
11080
 
 
11081
File: gettext.info,  Node: Special Keywords,  Next: Quote-like Expressions,  Prev: Default Keywords,  Up: Perl
 
11082
 
 
11083
How to Extract Hash Keys
 
11084
........................
 
11085
 
 
11086
Translating messages at runtime is normally performed by looking up the
 
11087
original string in the translation database and returning the
 
11088
translated version.  The "natural" Perl implementation is a hash
 
11089
lookup, and, of course, `xgettext' supports such practice.
 
11090
 
 
11091
     print __"Hello world!";
 
11092
     print $__{"Hello world!"};
 
11093
     print $__->{"Hello world!"};
 
11094
     print $$__{"Hello world!"};
 
11095
 
 
11096
   The above four lines all do the same thing.  The Perl module
 
11097
`Locale::TextDomain' exports by default a hash `%__' that is tied to
 
11098
the function `__()'.  It also exports a reference `$__' to `%__'.
 
11099
 
 
11100
   If an argument to the `xgettext' option `--keyword', resp. `-k'
 
11101
starts with a percent sign, the rest of the keyword is interpreted as
 
11102
the name of a hash.  If it starts with a dollar sign, the rest of the
 
11103
keyword is interpreted as a reference to a hash.
 
11104
 
 
11105
   Note that you can omit the quotation marks (single or double) around
 
11106
the hash key (almost) whenever Perl itself allows it:
 
11107
 
 
11108
     print $gettext{Error};
 
11109
 
 
11110
   The exact rule is: You can omit the surrounding quotes, when the hash
 
11111
key is a valid C (!) identifier, i. e. when it starts with an
 
11112
underscore or an ASCII letter and is followed by an arbitrary number of
 
11113
underscores, ASCII letters or digits.  Other Unicode characters are
 
11114
_not_ allowed, regardless of the `use utf8' pragma.
 
11115
 
 
11116
 
 
11117
File: gettext.info,  Node: Quote-like Expressions,  Next: Interpolation I,  Prev: Special Keywords,  Up: Perl
 
11118
 
 
11119
What are Strings And Quote-like Expressions?
 
11120
............................................
 
11121
 
 
11122
Perl offers a plethora of different string constructs.  Those that can
 
11123
be used either as arguments to functions or inside braces for hash
 
11124
lookups are generally supported by `xgettext'.
 
11125
 
 
11126
   * *double-quoted strings*
 
11127
          print gettext "Hello World!";
 
11128
 
 
11129
   * *single-quoted strings*
 
11130
          print gettext 'Hello World!';
 
11131
 
 
11132
   * *the operator qq*
 
11133
          print gettext qq |Hello World!|;
 
11134
          print gettext qq <E-mail: <guido\@imperia.net>>;
 
11135
 
 
11136
     The operator `qq' is fully supported.  You can use arbitrary
 
11137
     delimiters, including the four bracketing delimiters (round, angle,
 
11138
     square, curly) that nest.
 
11139
 
 
11140
   * *the operator q*
 
11141
          print gettext q |Hello World!|;
 
11142
          print gettext q <E-mail: <guido@imperia.net>>;
 
11143
 
 
11144
     The operator `q' is fully supported.  You can use arbitrary
 
11145
     delimiters, including the four bracketing delimiters (round, angle,
 
11146
     square, curly) that nest.
 
11147
 
 
11148
   * *the operator qx*
 
11149
          print gettext qx ;LANGUAGE=C /bin/date;
 
11150
          print gettext qx [/usr/bin/ls | grep '^[A-Z]*'];
 
11151
 
 
11152
     The operator `qx' is fully supported.  You can use arbitrary
 
11153
     delimiters, including the four bracketing delimiters (round, angle,
 
11154
     square, curly) that nest.
 
11155
 
 
11156
     The example is actually a useless use of `gettext'.  It will
 
11157
     invoke the `gettext' function on the output of the command
 
11158
     specified with the `qx' operator.  The feature was included in
 
11159
     order to make the interface consistent (the parser will extract
 
11160
     all strings and quote-like expressions).
 
11161
 
 
11162
   * *here documents*
 
11163
          print gettext <<'EOF';
 
11164
          program not found in $PATH
 
11165
          EOF
 
11166
          
 
11167
          print ngettext <<EOF, <<"EOF";
 
11168
          one file deleted
 
11169
          EOF
 
11170
          several files deleted
 
11171
          EOF
 
11172
 
 
11173
     Here-documents are recognized.  If the delimiter is enclosed in
 
11174
     single quotes, the string is not interpolated.  If it is enclosed
 
11175
     in double quotes or has no quotes at all, the string is
 
11176
     interpolated.
 
11177
 
 
11178
     Delimiters that start with a digit are not supported!
 
11179
 
 
11180
 
 
11181
 
 
11182
File: gettext.info,  Node: Interpolation I,  Next: Interpolation II,  Prev: Quote-like Expressions,  Up: Perl
 
11183
 
 
11184
Invalid Uses Of String Interpolation
 
11185
....................................
 
11186
 
 
11187
Perl is capable of interpolating variables into strings.  This offers
 
11188
some nice features in localized programs but can also lead to problems.
 
11189
 
 
11190
   A common error is a construct like the following:
 
11191
 
 
11192
     print gettext "This is the program $0!\n";
 
11193
 
 
11194
   Perl will interpolate at runtime the value of the variable `$0' into
 
11195
the argument of the `gettext()' function.  Hence, this argument is not
 
11196
a string constant but a variable argument (`$0' is a global variable
 
11197
that holds the name of the Perl script being executed).  The
 
11198
interpolation is performed by Perl before the string argument is passed
 
11199
to `gettext()' and will therefore depend on the name of the script
 
11200
which can only be determined at runtime.  Consequently, it is almost
 
11201
impossible that a translation can be looked up at runtime (except if,
 
11202
by accident, the interpolated string is found in the message catalog).
 
11203
 
 
11204
   The `xgettext' program will therefore terminate parsing with a fatal
 
11205
error if it encounters a variable inside of an extracted string.  In
 
11206
general, this will happen for all kinds of string interpolations that
 
11207
cannot be safely performed at compile time.  If you absolutely know
 
11208
what you are doing, you can always circumvent this behavior:
 
11209
 
 
11210
     my $know_what_i_am_doing = "This is program $0!\n";
 
11211
     print gettext $know_what_i_am_doing;
 
11212
 
 
11213
   Since the parser only recognizes strings and quote-like expressions,
 
11214
but not variables or other terms, the above construct will be accepted.
 
11215
You will have to find another way, however, to let your original
 
11216
string make it into your message catalog.
 
11217
 
 
11218
   If invoked with the option `--extract-all', resp. `-a', variable
 
11219
interpolation will be accepted.  Rationale: You will generally use this
 
11220
option in order to prepare your sources for internationalization.
 
11221
 
 
11222
   Please see the manual page `man perlop' for details of strings and
 
11223
quote-like expressions that are subject to interpolation and those that
 
11224
are not.  Safe interpolations (that will not lead to a fatal error) are:
 
11225
 
 
11226
   * the escape sequences `\t' (tab, HT, TAB), `\n' (newline, NL), `\r'
 
11227
     (return, CR), `\f' (form feed, FF), `\b' (backspace, BS), `\a'
 
11228
     (alarm, bell, BEL), and `\e' (escape, ESC).
 
11229
 
 
11230
   * octal chars, like `\033'
 
11231
     Note that octal escapes in the range of 400-777 are translated
 
11232
     into a UTF-8 representation, regardless of the presence of the
 
11233
     `use utf8' pragma.
 
11234
 
 
11235
   * hex chars, like `\x1b'
 
11236
 
 
11237
   * wide hex chars, like `\x{263a}'
 
11238
     Note that this escape is translated into a UTF-8 representation,
 
11239
     regardless of the presence of the `use utf8' pragma.
 
11240
 
 
11241
   * control chars, like `\c[' (CTRL-[)
 
11242
 
 
11243
   * named Unicode chars, like `\N{LATIN CAPITAL LETTER C WITH CEDILLA}'
 
11244
     Note that this escape is translated into a UTF-8 representation,
 
11245
     regardless of the presence of the `use utf8' pragma.
 
11246
 
 
11247
   The following escapes are considered partially safe:
 
11248
 
 
11249
   * `\l' lowercase next char
 
11250
 
 
11251
   * `\u' uppercase next char
 
11252
 
 
11253
   * `\L' lowercase till \E
 
11254
 
 
11255
   * `\U' uppercase till \E
 
11256
 
 
11257
   * `\E' end case modification
 
11258
 
 
11259
   * `\Q' quote non-word characters till \E
 
11260
 
 
11261
 
 
11262
   These escapes are only considered safe if the string consists of
 
11263
ASCII characters only.  Translation of characters outside the range
 
11264
defined by ASCII is locale-dependent and can actually only be performed
 
11265
at runtime; `xgettext' doesn't do these locale-dependent translations
 
11266
at extraction time.
 
11267
 
 
11268
   Except for the modifier `\Q', these translations, albeit valid, are
 
11269
generally useless and only obfuscate your sources.  If a translation
 
11270
can be safely performed at compile time you can just as well write what
 
11271
you mean.
 
11272
 
 
11273
 
 
11274
File: gettext.info,  Node: Interpolation II,  Next: Parentheses,  Prev: Interpolation I,  Up: Perl
 
11275
 
 
11276
Valid Uses Of String Interpolation
 
11277
..................................
 
11278
 
 
11279
Perl is often used to generate sources for other programming languages
 
11280
or arbitrary file formats.  Web applications that output HTML code make
 
11281
a prominent example for such usage.
 
11282
 
 
11283
   You will often come across situations where you want to intersperse
 
11284
code written in the target (programming) language with translatable
 
11285
messages, like in the following HTML example:
 
11286
 
 
11287
     print gettext <<EOF;
 
11288
     <h1>My Homepage</h1>
 
11289
     <script language="JavaScript"><!--
 
11290
     for (i = 0; i < 100; ++i) {
 
11291
         alert ("Thank you so much for visiting my homepage!");
 
11292
     }
 
11293
     //--></script>
 
11294
     EOF
 
11295
 
 
11296
   The parser will extract the entire here document, and it will appear
 
11297
entirely in the resulting PO file, including the JavaScript snippet
 
11298
embedded in the HTML code.  If you exaggerate with constructs like the
 
11299
above, you will run the risk that the translators of your package will
 
11300
look out for a less challenging project.  You should consider an
 
11301
alternative expression here:
 
11302
 
 
11303
     print <<EOF;
 
11304
     <h1>$gettext{"My Homepage"}</h1>
 
11305
     <script language="JavaScript"><!--
 
11306
     for (i = 0; i < 100; ++i) {
 
11307
         alert ("$gettext{'Thank you so much for visiting my homepage!'}");
 
11308
     }
 
11309
     //--></script>
 
11310
     EOF
 
11311
 
 
11312
   Only the translatable portions of the code will be extracted here,
 
11313
and the resulting PO file will begrudgingly improve in terms of
 
11314
readability.
 
11315
 
 
11316
   You can interpolate hash lookups in all strings or quote-like
 
11317
expressions that are subject to interpolation (see the manual page `man
 
11318
perlop' for details).  Double interpolation is invalid, however:
 
11319
 
 
11320
     # TRANSLATORS: Replace "the earth" with the name of your planet.
 
11321
     print gettext qq{Welcome to $gettext->{"the earth"}};
 
11322
 
 
11323
   The `qq'-quoted string is recognized as an argument to `xgettext' in
 
11324
the first place, and checked for invalid variable interpolation.  The
 
11325
dollar sign of hash-dereferencing will therefore terminate the parser
 
11326
with an "invalid interpolation" error.
 
11327
 
 
11328
   It is valid to interpolate hash lookups in regular expressions:
 
11329
 
 
11330
     if ($var =~ /$gettext{"the earth"}/) {
 
11331
        print gettext "Match!\n";
 
11332
     }
 
11333
     s/$gettext{"U. S. A."}/$gettext{"U. S. A."} $gettext{"(dial +0)"}/g;
 
11334
 
 
11335
 
 
11336
File: gettext.info,  Node: Parentheses,  Next: Long Lines,  Prev: Interpolation II,  Up: Perl
 
11337
 
 
11338
When To Use Parentheses
 
11339
.......................
 
11340
 
 
11341
In Perl, parentheses around function arguments are mostly optional.
 
11342
`xgettext' will always assume that all recognized keywords (except for
 
11343
hashs and hash references) are names of properly prototyped functions,
 
11344
and will (hopefully) only require parentheses where Perl itself
 
11345
requires them.  All constructs in the following example are therefore
 
11346
ok to use:
 
11347
 
 
11348
     print gettext ("Hello World!\n");
 
11349
     print gettext "Hello World!\n";
 
11350
     print dgettext ($package => "Hello World!\n");
 
11351
     print dgettext $package, "Hello World!\n";
 
11352
     
 
11353
     # The "fat comma" => turns the left-hand side argument into a
 
11354
     # single-quoted string!
 
11355
     print dgettext smellovision => "Hello World!\n";
 
11356
     
 
11357
     # The following assignment only works with prototyped functions.
 
11358
     # Otherwise, the functions will act as "greedy" list operators and
 
11359
     # eat up all following arguments.
 
11360
     my $anonymous_hash = {
 
11361
        planet => gettext "earth",
 
11362
        cakes => ngettext "one cake", "several cakes", $n,
 
11363
        still => $works,
 
11364
     };
 
11365
     # The same without fat comma:
 
11366
     my $other_hash = {
 
11367
        'planet', gettext "earth",
 
11368
        'cakes', ngettext "one cake", "several cakes", $n,
 
11369
        'still', $works,
 
11370
     };
 
11371
     
 
11372
     # Parentheses are only significant for the first argument.
 
11373
     print dngettext 'package', ("one cake", "several cakes", $n), $discarded;
 
11374
 
 
11375
 
 
11376
File: gettext.info,  Node: Long Lines,  Next: Perl Pitfalls,  Prev: Parentheses,  Up: Perl
 
11377
 
 
11378
How To Grok with Long Lines
 
11379
...........................
 
11380
 
 
11381
The necessity of long messages can often lead to a cumbersome or
 
11382
unreadable coding style.  Perl has several options that may prevent you
 
11383
from writing unreadable code, and `xgettext' does its best to do
 
11384
likewise.  This is where the dot operator (the string concatenation
 
11385
operator) may come in handy:
 
11386
 
 
11387
     print gettext ("This is a very long"
 
11388
                    . " message that is still"
 
11389
                    . " readable, because"
 
11390
                    . " it is split into"
 
11391
                    . " multiple lines.\n");
 
11392
 
 
11393
   Perl is smart enough to concatenate these constant string fragments
 
11394
into one long string at compile time, and so is `xgettext'.  You will
 
11395
only find one long message in the resulting POT file.
 
11396
 
 
11397
   Note that the future Perl 6 will probably use the underscore (`_')
 
11398
as the string concatenation operator, and the dot (`.') for
 
11399
dereferencing.  This new syntax is not yet supported by `xgettext'.
 
11400
 
 
11401
   If embedded newline characters are not an issue, or even desired, you
 
11402
may also insert newline characters inside quoted strings wherever you
 
11403
feel like it:
 
11404
 
 
11405
     print gettext ("<em>In HTML output
 
11406
     embedded newlines are generally no
 
11407
     problem, since adjacent whitespace
 
11408
     is always rendered into a single
 
11409
     space character.</em>");
 
11410
 
 
11411
   You may also consider to use here documents:
 
11412
 
 
11413
     print gettext <<EOF;
 
11414
     <em>In HTML output
 
11415
     embedded newlines are generally no
 
11416
     problem, since adjacent whitespace
 
11417
     is always rendered into a single
 
11418
     space character.</em>
 
11419
     EOF
 
11420
 
 
11421
   Please do not forget, that the line breaks are real, i. e. they
 
11422
translate into newline characters that will consequently show up in the
 
11423
resulting POT file.
 
11424
 
 
11425
 
 
11426
File: gettext.info,  Node: Perl Pitfalls,  Prev: Long Lines,  Up: Perl
 
11427
 
 
11428
Bugs, Pitfalls, And Things That Do Not Work
 
11429
...........................................
 
11430
 
 
11431
The foregoing sections should have proven that `xgettext' is quite
 
11432
smart in extracting translatable strings from Perl sources.  Yet, some
 
11433
more or less exotic constructs that could be expected to work, actually
 
11434
do not work.
 
11435
 
 
11436
   One of the more relevant limitations can be found in the
 
11437
implementation of variable interpolation inside quoted strings.  Only
 
11438
simple hash lookups can be used there:
 
11439
 
 
11440
     print <<EOF;
 
11441
     $gettext{"The dot operator"
 
11442
               . " does not work"
 
11443
               . "here!"}
 
11444
     Likewise, you cannot @{[ gettext ("interpolate function calls") ]}
 
11445
     inside quoted strings or quote-like expressions.
 
11446
     EOF
 
11447
 
 
11448
   This is valid Perl code and will actually trigger invocations of the
 
11449
`gettext' function at runtime.  Yet, the Perl parser in `xgettext' will
 
11450
fail to recognize the strings.  A less obvious example can be found in
 
11451
the interpolation of regular expressions:
 
11452
 
 
11453
     s/<!--START_OF_WEEK-->/gettext ("Sunday")/e;
 
11454
 
 
11455
   The modifier `e' will cause the substitution to be interpreted as an
 
11456
evaluable statement.  Consequently, at runtime the function `gettext()'
 
11457
is called, but again, the parser fails to extract the string "Sunday".
 
11458
Use a temporary variable as a simple workaround if you really happen to
 
11459
need this feature:
 
11460
 
 
11461
     my $sunday = gettext "Sunday";
 
11462
     s/<!--START_OF_WEEK-->/$sunday/;
 
11463
 
 
11464
   Hash slices would also be handy but are not recognized:
 
11465
 
 
11466
     my @weekdays = @gettext{'Sunday', 'Monday', 'Tuesday', 'Wednesday',
 
11467
                             'Thursday', 'Friday', 'Saturday'};
 
11468
     # Or even:
 
11469
     @weekdays = @gettext{qw (Sunday Monday Tuesday Wednesday Thursday
 
11470
                              Friday Saturday) };
 
11471
 
 
11472
   This is perfectly valid usage of the tied hash `%gettext' but the
 
11473
strings are not recognized and therefore will not be extracted.
 
11474
 
 
11475
   Another caveat of the current version is its rudimentary support for
 
11476
non-ASCII characters in identifiers.  You may encounter serious
 
11477
problems if you use identifiers with characters outside the range of
 
11478
'A'-'Z', 'a'-'z', '0'-'9' and the underscore '_'.
 
11479
 
 
11480
   Maybe some of these missing features will be implemented in future
 
11481
versions, but since you can always make do without them at minimal
 
11482
effort, these todos have very low priority.
 
11483
 
 
11484
   A nasty problem are brace format strings that already contain braces
 
11485
as part of the normal text, for example the usage strings typically
 
11486
encountered in programs:
 
11487
 
 
11488
     die "usage: $0 {OPTIONS} FILENAME...\n";
 
11489
 
 
11490
   If you want to internationalize this code with Perl brace format
 
11491
strings, you will run into a problem:
 
11492
 
 
11493
     die __x ("usage: {program} {OPTIONS} FILENAME...\n", program => $0);
 
11494
 
 
11495
   Whereas `{program}' is a placeholder, `{OPTIONS}' is not and should
 
11496
probably be translated. Yet, there is no way to teach the Perl parser
 
11497
in `xgettext' to recognize the first one, and leave the other one alone.
 
11498
 
 
11499
   There are two possible work-arounds for this problem.  If you are
 
11500
sure that your program will run under Perl 5.8.0 or newer (these Perl
 
11501
versions handle positional parameters in `printf()') or if you are sure
 
11502
that the translator will not have to reorder the arguments in her
 
11503
translation - for example if you have only one brace placeholder in
 
11504
your string, or if it describes a syntax, like in this one -, you can
 
11505
mark the string as `no-perl-brace-format' and use `printf()':
 
11506
 
 
11507
     # xgettext: no-perl-brace-format
 
11508
     die sprintf ("usage: %s {OPTIONS} FILENAME...\n", $0);
 
11509
 
 
11510
   If you want to use the more portable Perl brace format, you will
 
11511
have to do put placeholders in place of the literal braces:
 
11512
 
 
11513
     die __x ("usage: {program} {[}OPTIONS{]} FILENAME...\n",
 
11514
              program => $0, '[' => '{', ']' => '}');
 
11515
 
 
11516
   Perl brace format strings know no escaping mechanism.  No matter how
 
11517
this escaping mechanism looked like, it would either give the
 
11518
programmer a hard time, make translating Perl brace format strings
 
11519
heavy-going, or result in a performance penalty at runtime, when the
 
11520
format directives get executed.  Most of the time you will happily get
 
11521
along with `printf()' for this special case.
 
11522
 
 
11523
 
 
11524
File: gettext.info,  Node: PHP,  Next: Pike,  Prev: Perl,  Up: List of Programming Languages
 
11525
 
 
11526
PHP Hypertext Preprocessor
 
11527
--------------------------
 
11528
 
 
11529
RPMs
 
11530
     mod_php4, mod_php4-core, phpdoc
 
11531
 
 
11532
File extension
 
11533
     `php', `php3', `php4'
 
11534
 
 
11535
String syntax
 
11536
     `"abc"', `'abc''
 
11537
 
 
11538
gettext shorthand
 
11539
     `_("abc")'
 
11540
 
 
11541
gettext/ngettext functions
 
11542
     `gettext', `dgettext', `dcgettext'; starting with PHP 4.2.0 also
 
11543
     `ngettext', `dngettext', `dcngettext'
 
11544
 
 
11545
textdomain
 
11546
     `textdomain' function
 
11547
 
 
11548
bindtextdomain
 
11549
     `bindtextdomain' function
 
11550
 
 
11551
setlocale
 
11552
     Programmer must call `setlocale (LC_ALL, "")'
 
11553
 
 
11554
Prerequisite
 
11555
     --
 
11556
 
 
11557
Use or emulate GNU gettext
 
11558
     use
 
11559
 
 
11560
Extractor
 
11561
     `xgettext'
 
11562
 
 
11563
Formatting with positions
 
11564
     `printf "%2\$d %1\$d"'
 
11565
 
 
11566
Portability
 
11567
     On platforms without gettext, the functions are not available.
 
11568
 
 
11569
po-mode marking
 
11570
     --
 
11571
 
 
11572
   An example is available in the `examples' directory: `hello-php'.
 
11573
 
 
11574
 
 
11575
File: gettext.info,  Node: Pike,  Next: GCC-source,  Prev: PHP,  Up: List of Programming Languages
 
11576
 
 
11577
Pike
 
11578
----
 
11579
 
 
11580
RPMs
 
11581
     roxen
 
11582
 
 
11583
File extension
 
11584
     `pike'
 
11585
 
 
11586
String syntax
 
11587
     `"abc"'
 
11588
 
 
11589
gettext shorthand
 
11590
     --
 
11591
 
 
11592
gettext/ngettext functions
 
11593
     `gettext', `dgettext', `dcgettext'
 
11594
 
 
11595
textdomain
 
11596
     `textdomain' function
 
11597
 
 
11598
bindtextdomain
 
11599
     `bindtextdomain' function
 
11600
 
 
11601
setlocale
 
11602
     `setlocale' function
 
11603
 
 
11604
Prerequisite
 
11605
     `import Locale.Gettext;'
 
11606
 
 
11607
Use or emulate GNU gettext
 
11608
     use
 
11609
 
 
11610
Extractor
 
11611
     --
 
11612
 
 
11613
Formatting with positions
 
11614
     --
 
11615
 
 
11616
Portability
 
11617
     On platforms without gettext, the functions are not available.
 
11618
 
 
11619
po-mode marking
 
11620
     --
 
11621
 
 
11622
 
 
11623
File: gettext.info,  Node: GCC-source,  Prev: Pike,  Up: List of Programming Languages
 
11624
 
 
11625
GNU Compiler Collection sources
 
11626
-------------------------------
 
11627
 
 
11628
RPMs
 
11629
     gcc
 
11630
 
 
11631
File extension
 
11632
     `c', `h'.
 
11633
 
 
11634
String syntax
 
11635
     `"abc"'
 
11636
 
 
11637
gettext shorthand
 
11638
     `_("abc")'
 
11639
 
 
11640
gettext/ngettext functions
 
11641
     `gettext', `dgettext', `dcgettext', `ngettext', `dngettext',
 
11642
     `dcngettext'
 
11643
 
 
11644
textdomain
 
11645
     `textdomain' function
 
11646
 
 
11647
bindtextdomain
 
11648
     `bindtextdomain' function
 
11649
 
 
11650
setlocale
 
11651
     Programmer must call `setlocale (LC_ALL, "")'
 
11652
 
 
11653
Prerequisite
 
11654
     `#include "intl.h"'
 
11655
 
 
11656
Use or emulate GNU gettext
 
11657
     Use
 
11658
 
 
11659
Extractor
 
11660
     `xgettext -k_'
 
11661
 
 
11662
Formatting with positions
 
11663
     --
 
11664
 
 
11665
Portability
 
11666
     Uses autoconf macros
 
11667
 
 
11668
po-mode marking
 
11669
     yes
 
11670
 
 
11671
 
 
11672
File: gettext.info,  Node: List of Data Formats,  Prev: List of Programming Languages,  Up: Programming Languages
 
11673
 
 
11674
Internationalizable Data
 
11675
========================
 
11676
 
 
11677
Here is a list of other data formats which can be internationalized
 
11678
using GNU gettext.
 
11679
 
 
11680
* Menu:
 
11681
 
 
11682
* POT::                         POT - Portable Object Template
 
11683
* RST::                         Resource String Table
 
11684
* Glade::                       Glade - GNOME user interface description
 
11685
 
 
11686
 
 
11687
File: gettext.info,  Node: POT,  Next: RST,  Prev: List of Data Formats,  Up: List of Data Formats
 
11688
 
 
11689
POT - Portable Object Template
 
11690
------------------------------
 
11691
 
 
11692
RPMs
 
11693
     gettext
 
11694
 
 
11695
File extension
 
11696
     `pot', `po'
 
11697
 
 
11698
Extractor
 
11699
     `xgettext'
 
11700
 
 
11701
 
 
11702
File: gettext.info,  Node: RST,  Next: Glade,  Prev: POT,  Up: List of Data Formats
 
11703
 
 
11704
Resource String Table
 
11705
---------------------
 
11706
 
 
11707
RPMs
 
11708
     fpk
 
11709
 
 
11710
File extension
 
11711
     `rst'
 
11712
 
 
11713
Extractor
 
11714
     `xgettext', `rstconv'
 
11715
 
 
11716
 
 
11717
File: gettext.info,  Node: Glade,  Prev: RST,  Up: List of Data Formats
 
11718
 
 
11719
Glade - GNOME user interface description
 
11720
----------------------------------------
 
11721
 
 
11722
RPMs
 
11723
     glade, libglade, glade2, libglade2, intltool
 
11724
 
 
11725
File extension
 
11726
     `glade', `glade2'
 
11727
 
 
11728
Extractor
 
11729
     `xgettext', `libglade-xgettext', `xml-i18n-extract',
 
11730
     `intltool-extract'
 
11731
 
 
11732
 
 
11733
File: gettext.info,  Node: Conclusion,  Next: Language Codes,  Prev: Programming Languages,  Up: Top
 
11734
 
 
11735
Concluding Remarks
 
11736
******************
 
11737
 
 
11738
We would like to conclude this GNU `gettext' manual by presenting an
 
11739
history of the Translation Project so far.  We finally give a few
 
11740
pointers for those who want to do further research or readings about
 
11741
Native Language Support matters.
 
11742
 
 
11743
* Menu:
 
11744
 
 
11745
* History::                     History of GNU `gettext'
 
11746
* References::                  Related Readings
 
11747
 
 
11748
 
 
11749
File: gettext.info,  Node: History,  Next: References,  Prev: Conclusion,  Up: Conclusion
 
11750
 
 
11751
History of GNU `gettext'
 
11752
========================
 
11753
 
 
11754
Internationalization concerns and algorithms have been informally and
 
11755
casually discussed for years in GNU, sometimes around GNU `libc', maybe
 
11756
around the incoming `Hurd', or otherwise (nobody clearly remembers).
 
11757
And even then, when the work started for real, this was somewhat
 
11758
independently of these previous discussions.
 
11759
 
 
11760
   This all began in July 1994, when Patrick D'Cruze had the idea and
 
11761
initiative of internationalizing version 3.9.2 of GNU `fileutils'.  He
 
11762
then asked Jim Meyering, the maintainer, how to get those changes
 
11763
folded into an official release.  That first draft was full of
 
11764
`#ifdef's and somewhat disconcerting, and Jim wanted to find nicer
 
11765
ways.  Patrick and Jim shared some tries and experimentations in this
 
11766
area.  Then, feeling that this might eventually have a deeper impact on
 
11767
GNU, Jim wanted to know what standards were, and contacted Richard
 
11768
Stallman, who very quickly and verbally described an overall design for
 
11769
what was meant to become `glocale', at that time.
 
11770
 
 
11771
   Jim implemented `glocale' and got a lot of exhausting feedback from
 
11772
Patrick and Richard, of course, but also from Mitchum DSouza (who wrote
 
11773
a `catgets'-like package), Roland McGrath, maybe David MacKenzie,
 
11774
Franc,ois Pinard, and Paul Eggert, all pushing and pulling in various
 
11775
directions, not always compatible, to the extent that after a couple of
 
11776
test releases, `glocale' was torn apart.  In particular, Paul Eggert -
 
11777
always keeping an eye on developments in Solaris - advocated the use of
 
11778
the `gettext' API over `glocale''s `catgets'-based API.
 
11779
 
 
11780
   While Jim took some distance and time and became dad for a second
 
11781
time, Roland wanted to get GNU `libc' internationalized, and got Ulrich
 
11782
Drepper involved in that project.  Instead of starting from `glocale',
 
11783
Ulrich rewrote something from scratch, but more conformant to the set
 
11784
of guidelines who emerged out of the `glocale' effort.  Then, Ulrich
 
11785
got people from the previous forum to involve themselves into this new
 
11786
project, and the switch from `glocale' to what was first named
 
11787
`msgutils', renamed `nlsutils', and later `gettext', became officially
 
11788
accepted by Richard in May 1995 or so.
 
11789
 
 
11790
   Let's summarize by saying that Ulrich Drepper wrote GNU `gettext' in
 
11791
April 1995.  The first official release of the package, including PO
 
11792
mode, occurred in July 1995, and was numbered 0.7.  Other people
 
11793
contributed to the effort by providing a discussion forum around
 
11794
Ulrich, writing little pieces of code, or testing.  These are quoted in
 
11795
the `THANKS' file which comes with the GNU `gettext' distribution.
 
11796
 
 
11797
   While this was being done, Franc,ois adapted half a dozen of GNU
 
11798
packages to `glocale' first, then later to `gettext', putting them in
 
11799
pretest, so providing along the way an effective user environment for
 
11800
fine tuning the evolving tools.  He also took the responsibility of
 
11801
organizing and coordinating the Translation Project.  After nearly a
 
11802
year of informal exchanges between people from many countries,
 
11803
translator teams started to exist in May 1995, through the creation and
 
11804
support by Patrick D'Cruze of twenty unmoderated mailing lists for that
 
11805
many native languages, and two moderated lists: one for reaching all
 
11806
teams at once, the other for reaching all willing maintainers of
 
11807
internationalized free software packages.
 
11808
 
 
11809
   Franc,ois also wrote PO mode in June 1995 with the collaboration of
 
11810
Greg McGary, as a kind of contribution to Ulrich's package.  He also
 
11811
gave a hand with the GNU `gettext' Texinfo manual.
 
11812
 
 
11813
   In 1997, Ulrich Drepper released the GNU libc 2.0, which included the
 
11814
`gettext', `textdomain' and `bindtextdomain' functions.
 
11815
 
 
11816
   In 2000, Ulrich Drepper added plural form handling (the `ngettext'
 
11817
function) to GNU libc.  Later, in 2001, he released GNU libc 2.2.x,
 
11818
which is the first free C library with full internationalization
 
11819
support.
 
11820
 
 
11821
   Ulrich being quite busy in his role of General Maintainer of GNU
 
11822
libc, he handed over the GNU `gettext' maintenance to Bruno Haible in
 
11823
2000.  Bruno added the plural form handling to the tools as well, added
 
11824
support for UTF-8 and CJK locales, and wrote a few new tools for
 
11825
manipulating PO files.
 
11826
 
 
11827
 
 
11828
File: gettext.info,  Node: References,  Prev: History,  Up: Conclusion
 
11829
 
 
11830
Related Readings
 
11831
================
 
11832
 
 
11833
Eugene H. Dorr (`dorre@well.com') maintains an interesting bibliography
 
11834
on internationalization matters, called `Internationalization Reference
 
11835
List', which is available as:
 
11836
     ftp://ftp.ora.com/pub/examples/nutshell/ujip/doc/i18n-books.txt
 
11837
 
 
11838
   Michael Gschwind (`mike@vlsivie.tuwien.ac.at') maintains a
 
11839
Frequently Asked Questions (FAQ) list, entitled `Programming for
 
11840
Internationalisation'.  This FAQ discusses writing programs which can
 
11841
handle different language conventions, character sets, etc.; and is
 
11842
applicable to all character set encodings, with particular emphasis on
 
11843
ISO 8859-1.  It is regularly published in Usenet groups
 
11844
`comp.unix.questions', `comp.std.internat',
 
11845
`comp.software.international', `comp.lang.c', `comp.windows.x',
 
11846
`comp.std.c', `comp.answers' and `news.answers'.  The home location of
 
11847
this document is:
 
11848
     ftp://ftp.vlsivie.tuwien.ac.at/pub/8bit/ISO-programming
 
11849
 
 
11850
   Patrick D'Cruze (`pdcruze@li.org') wrote a tutorial about NLS
 
11851
matters, and Jochen Hein (`Hein@student.tu-clausthal.de') took over the
 
11852
responsibility of maintaining it.  It may be found as:
 
11853
     ftp://sunsite.unc.edu/pub/Linux/utils/nls/catalogs/Incoming/...
 
11854
          ...locale-tutorial-0.8.txt.gz
 
11855
 
 
11856
This site is mirrored in:
 
11857
     ftp://ftp.ibp.fr/pub/linux/sunsite/
 
11858
 
 
11859
   A French version of the same tutorial should be findable at:
 
11860
     ftp://ftp.ibp.fr/pub/linux/french/docs/
 
11861
 
 
11862
together with French translations of many Linux-related documents.
 
11863
 
 
11864
 
 
11865
File: gettext.info,  Node: Language Codes,  Next: Country Codes,  Prev: Conclusion,  Up: Top
 
11866
 
 
11867
Language Codes
 
11868
**************
 
11869
 
 
11870
The ISO 639 standard defines two character codes for many languages.
 
11871
All abbreviations for languages used in the Translation Project should
 
11872
come from this standard.
 
11873
 
 
11874
`aa'
 
11875
     Afar.
 
11876
 
 
11877
`ab'
 
11878
     Abkhazian.
 
11879
 
 
11880
`ae'
 
11881
     Avestan.
 
11882
 
 
11883
`af'
 
11884
     Afrikaans.
 
11885
 
 
11886
`ak'
 
11887
     Akan.
 
11888
 
 
11889
`am'
 
11890
     Amharic.
 
11891
 
 
11892
`an'
 
11893
     Aragonese.
 
11894
 
 
11895
`ar'
 
11896
     Arabic.
 
11897
 
 
11898
`as'
 
11899
     Assamese.
 
11900
 
 
11901
`av'
 
11902
     Avaric.
 
11903
 
 
11904
`ay'
 
11905
     Aymara.
 
11906
 
 
11907
`az'
 
11908
     Azerbaijani.
 
11909
 
 
11910
`ba'
 
11911
     Bashkir.
 
11912
 
 
11913
`be'
 
11914
     Byelorussian; Belarusian.
 
11915
 
 
11916
`bg'
 
11917
     Bulgarian.
 
11918
 
 
11919
`bh'
 
11920
     Bihari.
 
11921
 
 
11922
`bi'
 
11923
     Bislama.
 
11924
 
 
11925
`bm'
 
11926
     Bambara.
 
11927
 
 
11928
`bn'
 
11929
     Bengali; Bangla.
 
11930
 
 
11931
`bo'
 
11932
     Tibetan.
 
11933
 
 
11934
`br'
 
11935
     Breton.
 
11936
 
 
11937
`bs'
 
11938
     Bosnian.
 
11939
 
 
11940
`ca'
 
11941
     Catalan.
 
11942
 
 
11943
`ce'
 
11944
     Chechen.
 
11945
 
 
11946
`ch'
 
11947
     Chamorro.
 
11948
 
 
11949
`co'
 
11950
     Corsican.
 
11951
 
 
11952
`cr'
 
11953
     Cree.
 
11954
 
 
11955
`cs'
 
11956
     Czech.
 
11957
 
 
11958
`cu'
 
11959
     Church Slavic.
 
11960
 
 
11961
`cv'
 
11962
     Chuvash.
 
11963
 
 
11964
`cy'
 
11965
     Welsh.
 
11966
 
 
11967
`da'
 
11968
     Danish.
 
11969
 
 
11970
`de'
 
11971
     German.
 
11972
 
 
11973
`dv'
 
11974
     Divehi.
 
11975
 
 
11976
`dz'
 
11977
     Dzongkha; Bhutani.
 
11978
 
 
11979
`ee'
 
11980
     E'we'.
 
11981
 
 
11982
`el'
 
11983
     Greek.
 
11984
 
 
11985
`en'
 
11986
     English.
 
11987
 
 
11988
`eo'
 
11989
     Esperanto.
 
11990
 
 
11991
`es'
 
11992
     Spanish.
 
11993
 
 
11994
`et'
 
11995
     Estonian.
 
11996
 
 
11997
`eu'
 
11998
     Basque.
 
11999
 
 
12000
`fa'
 
12001
     Persian.
 
12002
 
 
12003
`ff'
 
12004
     Fulah.
 
12005
 
 
12006
`fi'
 
12007
     Finnish.
 
12008
 
 
12009
`fj'
 
12010
     Fijian; Fiji.
 
12011
 
 
12012
`fo'
 
12013
     Faroese.
 
12014
 
 
12015
`fr'
 
12016
     French.
 
12017
 
 
12018
`fy'
 
12019
     Frisian.
 
12020
 
 
12021
`ga'
 
12022
     Irish.
 
12023
 
 
12024
`gd'
 
12025
     Scots; Gaelic.
 
12026
 
 
12027
`gl'
 
12028
     Gallegan; Galician.
 
12029
 
 
12030
`gn'
 
12031
     Guarani.
 
12032
 
 
12033
`gu'
 
12034
     Gujarati.
 
12035
 
 
12036
`gv'
 
12037
     Manx.
 
12038
 
 
12039
`ha'
 
12040
     Hausa (?).
 
12041
 
 
12042
`he'
 
12043
     Hebrew (formerly iw).
 
12044
 
 
12045
`hi'
 
12046
     Hindi.
 
12047
 
 
12048
`ho'
 
12049
     Hiri Motu.
 
12050
 
 
12051
`hr'
 
12052
     Croatian.
 
12053
 
 
12054
`ht'
 
12055
     Haitian; Haitian Creole.
 
12056
 
 
12057
`hu'
 
12058
     Hungarian.
 
12059
 
 
12060
`hy'
 
12061
     Armenian.
 
12062
 
 
12063
`hz'
 
12064
     Herero.
 
12065
 
 
12066
`ia'
 
12067
     Interlingua.
 
12068
 
 
12069
`id'
 
12070
     Indonesian (formerly in).
 
12071
 
 
12072
`ie'
 
12073
     Interlingue.
 
12074
 
 
12075
`ig'
 
12076
     Igbo.
 
12077
 
 
12078
`ii'
 
12079
     Sichuan Yi.
 
12080
 
 
12081
`ik'
 
12082
     Inupiak.
 
12083
 
 
12084
`io'
 
12085
     Ido.
 
12086
 
 
12087
`is'
 
12088
     Icelandic.
 
12089
 
 
12090
`it'
 
12091
     Italian.
 
12092
 
 
12093
`iu'
 
12094
     Inuktitut.
 
12095
 
 
12096
`ja'
 
12097
     Japanese.
 
12098
 
 
12099
`jv'
 
12100
     Javanese.
 
12101
 
 
12102
`ka'
 
12103
     Georgian.
 
12104
 
 
12105
`kg'
 
12106
     Kongo.
 
12107
 
 
12108
`ki'
 
12109
     Kikuyu.
 
12110
 
 
12111
`kj'
 
12112
     Kuanyama.
 
12113
 
 
12114
`kk'
 
12115
     Kazakh.
 
12116
 
 
12117
`kl'
 
12118
     Kalaallisut; Greenlandic.
 
12119
 
 
12120
`km'
 
12121
     Khmer; Cambodian.
 
12122
 
 
12123
`kn'
 
12124
     Kannada.
 
12125
 
 
12126
`ko'
 
12127
     Korean.
 
12128
 
 
12129
`kr'
 
12130
     Kanuri.
 
12131
 
 
12132
`ks'
 
12133
     Kashmiri.
 
12134
 
 
12135
`ku'
 
12136
     Kurdish.
 
12137
 
 
12138
`kv'
 
12139
     Komi.
 
12140
 
 
12141
`kw'
 
12142
     Cornish.
 
12143
 
 
12144
`ky'
 
12145
     Kirghiz.
 
12146
 
 
12147
`la'
 
12148
     Latin.
 
12149
 
 
12150
`lb'
 
12151
     Letzeburgesch.
 
12152
 
 
12153
`lg'
 
12154
     Ganda.
 
12155
 
 
12156
`li'
 
12157
     Limburgish; Limburger; Limburgan.
 
12158
 
 
12159
`ln'
 
12160
     Lingala.
 
12161
 
 
12162
`lo'
 
12163
     Lao; Laotian.
 
12164
 
 
12165
`lt'
 
12166
     Lithuanian.
 
12167
 
 
12168
`lu'
 
12169
     Luba-Katanga.
 
12170
 
 
12171
`lv'
 
12172
     Latvian; Lettish.
 
12173
 
 
12174
`mg'
 
12175
     Malagasy.
 
12176
 
 
12177
`mh'
 
12178
     Marshall.
 
12179
 
 
12180
`mi'
 
12181
     Maori.
 
12182
 
 
12183
`mk'
 
12184
     Macedonian.
 
12185
 
 
12186
`ml'
 
12187
     Malayalam.
 
12188
 
 
12189
`mn'
 
12190
     Mongolian.
 
12191
 
 
12192
`mo'
 
12193
     Moldavian.
 
12194
 
 
12195
`mr'
 
12196
     Marathi.
 
12197
 
 
12198
`ms'
 
12199
     Malay.
 
12200
 
 
12201
`mt'
 
12202
     Maltese.
 
12203
 
 
12204
`my'
 
12205
     Burmese.
 
12206
 
 
12207
`na'
 
12208
     Nauru.
 
12209
 
 
12210
`nb'
 
12211
     Norwegian Bokmaal.
 
12212
 
 
12213
`nd'
 
12214
     Ndebele, North.
 
12215
 
 
12216
`ne'
 
12217
     Nepali.
 
12218
 
 
12219
`ng'
 
12220
     Ndonga.
 
12221
 
 
12222
`nl'
 
12223
     Dutch.
 
12224
 
 
12225
`nn'
 
12226
     Norwegian Nynorsk.
 
12227
 
 
12228
`no'
 
12229
     Norwegian.
 
12230
 
 
12231
`nr'
 
12232
     Ndebele, South.
 
12233
 
 
12234
`nv'
 
12235
     Navajo.
 
12236
 
 
12237
`ny'
 
12238
     Chichewa; Nyanja.
 
12239
 
 
12240
`oc'
 
12241
     Occitan; Provenc,al.
 
12242
 
 
12243
`oj'
 
12244
     Ojibwa.
 
12245
 
 
12246
`om'
 
12247
     (Afan) Oromo.
 
12248
 
 
12249
`or'
 
12250
     Oriya.
 
12251
 
 
12252
`os'
 
12253
     Ossetian; Ossetic.
 
12254
 
 
12255
`pa'
 
12256
     Panjabi; Punjabi.
 
12257
 
 
12258
`pi'
 
12259
     Pali.
 
12260
 
 
12261
`pl'
 
12262
     Polish.
 
12263
 
 
12264
`ps'
 
12265
     Pashto, Pushto.
 
12266
 
 
12267
`pt'
 
12268
     Portuguese.
 
12269
 
 
12270
`qu'
 
12271
     Quechua.
 
12272
 
 
12273
`rm'
 
12274
     Rhaeto-Romance.
 
12275
 
 
12276
`rn'
 
12277
     Rundi; Kirundi.
 
12278
 
 
12279
`ro'
 
12280
     Romanian.
 
12281
 
 
12282
`ru'
 
12283
     Russian.
 
12284
 
 
12285
`rw'
 
12286
     Kinyarwanda.
 
12287
 
 
12288
`sa'
 
12289
     Sanskrit.
 
12290
 
 
12291
`sc'
 
12292
     Sardinian.
 
12293
 
 
12294
`sd'
 
12295
     Sindhi.
 
12296
 
 
12297
`se'
 
12298
     Northern Sami.
 
12299
 
 
12300
`sg'
 
12301
     Sango; Sangro.
 
12302
 
 
12303
`si'
 
12304
     Sinhalese.
 
12305
 
 
12306
`sk'
 
12307
     Slovak.
 
12308
 
 
12309
`sl'
 
12310
     Slovenian.
 
12311
 
 
12312
`sm'
 
12313
     Samoan.
 
12314
 
 
12315
`sn'
 
12316
     Shona.
 
12317
 
 
12318
`so'
 
12319
     Somali.
 
12320
 
 
12321
`sq'
 
12322
     Albanian.
 
12323
 
 
12324
`sr'
 
12325
     Serbian.
 
12326
 
 
12327
`ss'
 
12328
     Swati; Siswati.
 
12329
 
 
12330
`st'
 
12331
     Sesotho; Sotho, Southern.
 
12332
 
 
12333
`su'
 
12334
     Sundanese.
 
12335
 
 
12336
`sv'
 
12337
     Swedish.
 
12338
 
 
12339
`sw'
 
12340
     Swahili.
 
12341
 
 
12342
`ta'
 
12343
     Tamil.
 
12344
 
 
12345
`te'
 
12346
     Telugu.
 
12347
 
 
12348
`tg'
 
12349
     Tajik.
 
12350
 
 
12351
`th'
 
12352
     Thai.
 
12353
 
 
12354
`ti'
 
12355
     Tigrinya.
 
12356
 
 
12357
`tk'
 
12358
     Turkmen.
 
12359
 
 
12360
`tl'
 
12361
     Tagalog.
 
12362
 
 
12363
`tn'
 
12364
     Tswana; Setswana.
 
12365
 
 
12366
`to'
 
12367
     Tonga (?).
 
12368
 
 
12369
`tr'
 
12370
     Turkish.
 
12371
 
 
12372
`ts'
 
12373
     Tsonga.
 
12374
 
 
12375
`tt'
 
12376
     Tatar.
 
12377
 
 
12378
`tw'
 
12379
     Twi.
 
12380
 
 
12381
`ty'
 
12382
     Tahitian.
 
12383
 
 
12384
`ug'
 
12385
     Uighur.
 
12386
 
 
12387
`uk'
 
12388
     Ukrainian.
 
12389
 
 
12390
`ur'
 
12391
     Urdu.
 
12392
 
 
12393
`uz'
 
12394
     Uzbek.
 
12395
 
 
12396
`ve'
 
12397
     Venda.
 
12398
 
 
12399
`vi'
 
12400
     Vietnamese.
 
12401
 
 
12402
`vo'
 
12403
     Volapu"k; Volapuk.
 
12404
 
 
12405
`wa'
 
12406
     Walloon.
 
12407
 
 
12408
`wo'
 
12409
     Wolof.
 
12410
 
 
12411
`xh'
 
12412
     Xhosa.
 
12413
 
 
12414
`yi'
 
12415
     Yiddish (formerly ji).
 
12416
 
 
12417
`yo'
 
12418
     Yoruba.
 
12419
 
 
12420
`za'
 
12421
     Zhuang.
 
12422
 
 
12423
`zh'
 
12424
     Chinese.
 
12425
 
 
12426
`zu'
 
12427
     Zulu.
 
12428
 
 
12429
 
 
12430
File: gettext.info,  Node: Country Codes,  Next: Program Index,  Prev: Language Codes,  Up: Top
 
12431
 
 
12432
Country Codes
 
12433
*************
 
12434
 
 
12435
The ISO 3166 standard defines two character codes for many countries
 
12436
and territories.  All abbreviations for countries used in the
 
12437
Translation Project should come from this standard.
 
12438
 
 
12439
`AD'
 
12440
     Andorra.
 
12441
 
 
12442
`AE'
 
12443
     United Arab Emirates.
 
12444
 
 
12445
`AF'
 
12446
     Afghanistan.
 
12447
 
 
12448
`AG'
 
12449
     Antigua and Barbuda.
 
12450
 
 
12451
`AI'
 
12452
     Anguilla.
 
12453
 
 
12454
`AL'
 
12455
     Albania.
 
12456
 
 
12457
`AM'
 
12458
     Armenia.
 
12459
 
 
12460
`AN'
 
12461
     Netherlands Antilles.
 
12462
 
 
12463
`AO'
 
12464
     Angola.
 
12465
 
 
12466
`AQ'
 
12467
     Antarctica.
 
12468
 
 
12469
`AR'
 
12470
     Argentina.
 
12471
 
 
12472
`AS'
 
12473
     Samoa (American).
 
12474
 
 
12475
`AT'
 
12476
     Austria.
 
12477
 
 
12478
`AU'
 
12479
     Australia.
 
12480
 
 
12481
`AW'
 
12482
     Aruba.
 
12483
 
 
12484
`AZ'
 
12485
     Azerbaijan.
 
12486
 
 
12487
`BA'
 
12488
     Bosnia and Herzegovina.
 
12489
 
 
12490
`BB'
 
12491
     Barbados.
 
12492
 
 
12493
`BD'
 
12494
     Bangladesh.
 
12495
 
 
12496
`BE'
 
12497
     Belgium.
 
12498
 
 
12499
`BF'
 
12500
     Burkina Faso.
 
12501
 
 
12502
`BG'
 
12503
     Bulgaria.
 
12504
 
 
12505
`BH'
 
12506
     Bahrain.
 
12507
 
 
12508
`BI'
 
12509
     Burundi.
 
12510
 
 
12511
`BJ'
 
12512
     Benin.
 
12513
 
 
12514
`BM'
 
12515
     Bermuda.
 
12516
 
 
12517
`BN'
 
12518
     Brunei.
 
12519
 
 
12520
`BO'
 
12521
     Bolivia.
 
12522
 
 
12523
`BR'
 
12524
     Brazil.
 
12525
 
 
12526
`BS'
 
12527
     Bahamas.
 
12528
 
 
12529
`BT'
 
12530
     Bhutan.
 
12531
 
 
12532
`BV'
 
12533
     Bouvet Island.
 
12534
 
 
12535
`BW'
 
12536
     Botswana.
 
12537
 
 
12538
`BY'
 
12539
     Belarus.
 
12540
 
 
12541
`BZ'
 
12542
     Belize.
 
12543
 
 
12544
`CA'
 
12545
     Canada.
 
12546
 
 
12547
`CC'
 
12548
     Cocos (Keeling) Islands.
 
12549
 
 
12550
`CD'
 
12551
     Congo (Dem. Rep.).
 
12552
 
 
12553
`CF'
 
12554
     Central African Rep..
 
12555
 
 
12556
`CG'
 
12557
     Congo (Rep.).
 
12558
 
 
12559
`CH'
 
12560
     Switzerland.
 
12561
 
 
12562
`CI'
 
12563
     Co^te d'Ivoire.
 
12564
 
 
12565
`CK'
 
12566
     Cook Islands.
 
12567
 
 
12568
`CL'
 
12569
     Chile.
 
12570
 
 
12571
`CM'
 
12572
     Cameroon.
 
12573
 
 
12574
`CN'
 
12575
     China.
 
12576
 
 
12577
`CO'
 
12578
     Colombia.
 
12579
 
 
12580
`CR'
 
12581
     Costa Rica.
 
12582
 
 
12583
`CS'
 
12584
     Serbia and Montenegro.
 
12585
 
 
12586
`CU'
 
12587
     Cuba.
 
12588
 
 
12589
`CV'
 
12590
     Cape Verde.
 
12591
 
 
12592
`CX'
 
12593
     Christmas Island.
 
12594
 
 
12595
`CY'
 
12596
     Cyprus.
 
12597
 
 
12598
`CZ'
 
12599
     Czech Republic.
 
12600
 
 
12601
`DE'
 
12602
     Germany.
 
12603
 
 
12604
`DJ'
 
12605
     Djibouti.
 
12606
 
 
12607
`DK'
 
12608
     Denmark.
 
12609
 
 
12610
`DM'
 
12611
     Dominica.
 
12612
 
 
12613
`DO'
 
12614
     Dominican Republic.
 
12615
 
 
12616
`DZ'
 
12617
     Algeria.
 
12618
 
 
12619
`EC'
 
12620
     Ecuador.
 
12621
 
 
12622
`EE'
 
12623
     Estonia.
 
12624
 
 
12625
`EG'
 
12626
     Egypt.
 
12627
 
 
12628
`EH'
 
12629
     Western Sahara.
 
12630
 
 
12631
`ER'
 
12632
     Eritrea.
 
12633
 
 
12634
`ES'
 
12635
     Spain.
 
12636
 
 
12637
`ET'
 
12638
     Ethiopia.
 
12639
 
 
12640
`FI'
 
12641
     Finland.
 
12642
 
 
12643
`FJ'
 
12644
     Fiji.
 
12645
 
 
12646
`FK'
 
12647
     Falkland Islands.
 
12648
 
 
12649
`FM'
 
12650
     Micronesia.
 
12651
 
 
12652
`FO'
 
12653
     Faeroe Islands.
 
12654
 
 
12655
`FR'
 
12656
     France.
 
12657
 
 
12658
`GA'
 
12659
     Gabon.
 
12660
 
 
12661
`GB'
 
12662
     Britain (UK).
 
12663
 
 
12664
`GD'
 
12665
     Grenada.
 
12666
 
 
12667
`GE'
 
12668
     Georgia.
 
12669
 
 
12670
`GF'
 
12671
     French Guiana.
 
12672
 
 
12673
`GH'
 
12674
     Ghana.
 
12675
 
 
12676
`GI'
 
12677
     Gibraltar.
 
12678
 
 
12679
`GL'
 
12680
     Greenland.
 
12681
 
 
12682
`GM'
 
12683
     Gambia.
 
12684
 
 
12685
`GN'
 
12686
     Guinea.
 
12687
 
 
12688
`GP'
 
12689
     Guadeloupe.
 
12690
 
 
12691
`GQ'
 
12692
     Equatorial Guinea.
 
12693
 
 
12694
`GR'
 
12695
     Greece.
 
12696
 
 
12697
`GS'
 
12698
     South Georgia and the South Sandwich Islands.
 
12699
 
 
12700
`GT'
 
12701
     Guatemala.
 
12702
 
 
12703
`GU'
 
12704
     Guam.
 
12705
 
 
12706
`GW'
 
12707
     Guinea-Bissau.
 
12708
 
 
12709
`GY'
 
12710
     Guyana.
 
12711
 
 
12712
`HK'
 
12713
     Hong Kong.
 
12714
 
 
12715
`HM'
 
12716
     Heard Island and McDonald Islands.
 
12717
 
 
12718
`HN'
 
12719
     Honduras.
 
12720
 
 
12721
`HR'
 
12722
     Croatia.
 
12723
 
 
12724
`HT'
 
12725
     Haiti.
 
12726
 
 
12727
`HU'
 
12728
     Hungary.
 
12729
 
 
12730
`ID'
 
12731
     Indonesia.
 
12732
 
 
12733
`IE'
 
12734
     Ireland.
 
12735
 
 
12736
`IL'
 
12737
     Israel.
 
12738
 
 
12739
`IN'
 
12740
     India.
 
12741
 
 
12742
`IO'
 
12743
     British Indian Ocean Territory.
 
12744
 
 
12745
`IQ'
 
12746
     Iraq.
 
12747
 
 
12748
`IR'
 
12749
     Iran.
 
12750
 
 
12751
`IS'
 
12752
     Iceland.
 
12753
 
 
12754
`IT'
 
12755
     Italy.
 
12756
 
 
12757
`JM'
 
12758
     Jamaica.
 
12759
 
 
12760
`JO'
 
12761
     Jordan.
 
12762
 
 
12763
`JP'
 
12764
     Japan.
 
12765
 
 
12766
`KE'
 
12767
     Kenya.
 
12768
 
 
12769
`KG'
 
12770
     Kyrgyzstan.
 
12771
 
 
12772
`KH'
 
12773
     Cambodia.
 
12774
 
 
12775
`KI'
 
12776
     Kiribati.
 
12777
 
 
12778
`KM'
 
12779
     Comoros.
 
12780
 
 
12781
`KN'
 
12782
     St Kitts and Nevis.
 
12783
 
 
12784
`KP'
 
12785
     Korea (North).
 
12786
 
 
12787
`KR'
 
12788
     Korea (South).
 
12789
 
 
12790
`KW'
 
12791
     Kuwait.
 
12792
 
 
12793
`KY'
 
12794
     Cayman Islands.
 
12795
 
 
12796
`KZ'
 
12797
     Kazakhstan.
 
12798
 
 
12799
`LA'
 
12800
     Laos.
 
12801
 
 
12802
`LB'
 
12803
     Lebanon.
 
12804
 
 
12805
`LC'
 
12806
     St Lucia.
 
12807
 
 
12808
`LI'
 
12809
     Liechtenstein.
 
12810
 
 
12811
`LK'
 
12812
     Sri Lanka.
 
12813
 
 
12814
`LR'
 
12815
     Liberia.
 
12816
 
 
12817
`LS'
 
12818
     Lesotho.
 
12819
 
 
12820
`LT'
 
12821
     Lithuania.
 
12822
 
 
12823
`LU'
 
12824
     Luxembourg.
 
12825
 
 
12826
`LV'
 
12827
     Latvia.
 
12828
 
 
12829
`LY'
 
12830
     Libya.
 
12831
 
 
12832
`MA'
 
12833
     Morocco.
 
12834
 
 
12835
`MC'
 
12836
     Monaco.
 
12837
 
 
12838
`MD'
 
12839
     Moldova.
 
12840
 
 
12841
`MG'
 
12842
     Madagascar.
 
12843
 
 
12844
`MH'
 
12845
     Marshall Islands.
 
12846
 
 
12847
`MK'
 
12848
     Macedonia.
 
12849
 
 
12850
`ML'
 
12851
     Mali.
 
12852
 
 
12853
`MM'
 
12854
     Myanmar (Burma).
 
12855
 
 
12856
`MN'
 
12857
     Mongolia.
 
12858
 
 
12859
`MO'
 
12860
     Macao.
 
12861
 
 
12862
`MP'
 
12863
     Northern Mariana Islands.
 
12864
 
 
12865
`MQ'
 
12866
     Martinique.
 
12867
 
 
12868
`MR'
 
12869
     Mauritania.
 
12870
 
 
12871
`MS'
 
12872
     Montserrat.
 
12873
 
 
12874
`MT'
 
12875
     Malta.
 
12876
 
 
12877
`MU'
 
12878
     Mauritius.
 
12879
 
 
12880
`MV'
 
12881
     Maldives.
 
12882
 
 
12883
`MW'
 
12884
     Malawi.
 
12885
 
 
12886
`MX'
 
12887
     Mexico.
 
12888
 
 
12889
`MY'
 
12890
     Malaysia.
 
12891
 
 
12892
`MZ'
 
12893
     Mozambique.
 
12894
 
 
12895
`NA'
 
12896
     Namibia.
 
12897
 
 
12898
`NC'
 
12899
     New Caledonia.
 
12900
 
 
12901
`NE'
 
12902
     Niger.
 
12903
 
 
12904
`NF'
 
12905
     Norfolk Island.
 
12906
 
 
12907
`NG'
 
12908
     Nigeria.
 
12909
 
 
12910
`NI'
 
12911
     Nicaragua.
 
12912
 
 
12913
`NL'
 
12914
     Netherlands.
 
12915
 
 
12916
`NO'
 
12917
     Norway.
 
12918
 
 
12919
`NP'
 
12920
     Nepal.
 
12921
 
 
12922
`NR'
 
12923
     Nauru.
 
12924
 
 
12925
`NU'
 
12926
     Niue.
 
12927
 
 
12928
`NZ'
 
12929
     New Zealand.
 
12930
 
 
12931
`OM'
 
12932
     Oman.
 
12933
 
 
12934
`PA'
 
12935
     Panama.
 
12936
 
 
12937
`PE'
 
12938
     Peru.
 
12939
 
 
12940
`PF'
 
12941
     French Polynesia.
 
12942
 
 
12943
`PG'
 
12944
     Papua New Guinea.
 
12945
 
 
12946
`PH'
 
12947
     Philippines.
 
12948
 
 
12949
`PK'
 
12950
     Pakistan.
 
12951
 
 
12952
`PL'
 
12953
     Poland.
 
12954
 
 
12955
`PM'
 
12956
     St Pierre and Miquelon.
 
12957
 
 
12958
`PN'
 
12959
     Pitcairn.
 
12960
 
 
12961
`PR'
 
12962
     Puerto Rico.
 
12963
 
 
12964
`PS'
 
12965
     Palestine.
 
12966
 
 
12967
`PT'
 
12968
     Portugal.
 
12969
 
 
12970
`PW'
 
12971
     Palau.
 
12972
 
 
12973
`PY'
 
12974
     Paraguay.
 
12975
 
 
12976
`QA'
 
12977
     Qatar.
 
12978
 
 
12979
`RE'
 
12980
     Reunion.
 
12981
 
 
12982
`RO'
 
12983
     Romania.
 
12984
 
 
12985
`RU'
 
12986
     Russia.
 
12987
 
 
12988
`RW'
 
12989
     Rwanda.
 
12990
 
 
12991
`SA'
 
12992
     Saudi Arabia.
 
12993
 
 
12994
`SB'
 
12995
     Solomon Islands.
 
12996
 
 
12997
`SC'
 
12998
     Seychelles.
 
12999
 
 
13000
`SD'
 
13001
     Sudan.
 
13002
 
 
13003
`SE'
 
13004
     Sweden.
 
13005
 
 
13006
`SG'
 
13007
     Singapore.
 
13008
 
 
13009
`SH'
 
13010
     St Helena.
 
13011
 
 
13012
`SI'
 
13013
     Slovenia.
 
13014
 
 
13015
`SJ'
 
13016
     Svalbard and Jan Mayen.
 
13017
 
 
13018
`SK'
 
13019
     Slovakia.
 
13020
 
 
13021
`SL'
 
13022
     Sierra Leone.
 
13023
 
 
13024
`SM'
 
13025
     San Marino.
 
13026
 
 
13027
`SN'
 
13028
     Senegal.
 
13029
 
 
13030
`SO'
 
13031
     Somalia.
 
13032
 
 
13033
`SR'
 
13034
     Suriname.
 
13035
 
 
13036
`ST'
 
13037
     Sao Tome and Principe.
 
13038
 
 
13039
`SV'
 
13040
     El Salvador.
 
13041
 
 
13042
`SY'
 
13043
     Syria.
 
13044
 
 
13045
`SZ'
 
13046
     Swaziland.
 
13047
 
 
13048
`TC'
 
13049
     Turks and Caicos Islands.
 
13050
 
 
13051
`TD'
 
13052
     Chad.
 
13053
 
 
13054
`TF'
 
13055
     French Southern and Antarctic Lands.
 
13056
 
 
13057
`TG'
 
13058
     Togo.
 
13059
 
 
13060
`TH'
 
13061
     Thailand.
 
13062
 
 
13063
`TJ'
 
13064
     Tajikistan.
 
13065
 
 
13066
`TK'
 
13067
     Tokelau.
 
13068
 
 
13069
`TL'
 
13070
     Timor-Leste.
 
13071
 
 
13072
`TM'
 
13073
     Turkmenistan.
 
13074
 
 
13075
`TN'
 
13076
     Tunisia.
 
13077
 
 
13078
`TO'
 
13079
     Tonga.
 
13080
 
 
13081
`TR'
 
13082
     Turkey.
 
13083
 
 
13084
`TT'
 
13085
     Trinidad and Tobago.
 
13086
 
 
13087
`TV'
 
13088
     Tuvalu.
 
13089
 
 
13090
`TW'
 
13091
     Taiwan.
 
13092
 
 
13093
`TZ'
 
13094
     Tanzania.
 
13095
 
 
13096
`UA'
 
13097
     Ukraine.
 
13098
 
 
13099
`UG'
 
13100
     Uganda.
 
13101
 
 
13102
`UM'
 
13103
     US minor outlying islands.
 
13104
 
 
13105
`US'
 
13106
     United States.
 
13107
 
 
13108
`UY'
 
13109
     Uruguay.
 
13110
 
 
13111
`UZ'
 
13112
     Uzbekistan.
 
13113
 
 
13114
`VA'
 
13115
     Vatican City.
 
13116
 
 
13117
`VC'
 
13118
     St Vincent.
 
13119
 
 
13120
`VE'
 
13121
     Venezuela.
 
13122
 
 
13123
`VG'
 
13124
     Virgin Islands (UK).
 
13125
 
 
13126
`VI'
 
13127
     Virgin Islands (US).
 
13128
 
 
13129
`VN'
 
13130
     Vietnam.
 
13131
 
 
13132
`VU'
 
13133
     Vanuatu.
 
13134
 
 
13135
`WF'
 
13136
     Wallis and Futuna.
 
13137
 
 
13138
`WS'
 
13139
     Samoa (Western).
 
13140
 
 
13141
`YE'
 
13142
     Yemen.
 
13143
 
 
13144
`YT'
 
13145
     Mayotte.
 
13146
 
 
13147
`ZA'
 
13148
     South Africa.
 
13149
 
 
13150
`ZM'
 
13151
     Zambia.
 
13152
 
 
13153
`ZW'
 
13154
     Zimbabwe.
 
13155
 
 
13156
 
 
13157
File: gettext.info,  Node: Program Index,  Next: Option Index,  Prev: Country Codes,  Up: Top
 
13158
 
 
13159
Program Index
 
13160
*************
 
13161
 
 
13162
* Menu:
 
13163
 
 
13164
* autopoint:                             autopoint Invocation.
 
13165
* envsubst:                              envsubst Invocation.
 
13166
* gettext <1>:                           gettext Invocation.
 
13167
* gettext:                               sh.
 
13168
* gettextize:                            gettextize Invocation.
 
13169
* msgattrib:                             msgattrib Invocation.
 
13170
* msgcat:                                msgcat Invocation.
 
13171
* msgcmp:                                msgcmp Invocation.
 
13172
* msgcomm:                               msgcomm Invocation.
 
13173
* msgconv:                               msgconv Invocation.
 
13174
* msgen:                                 msgen Invocation.
 
13175
* msgexec:                               msgexec Invocation.
 
13176
* msgfilter:                             msgfilter Invocation.
 
13177
* msgfmt:                                msgfmt Invocation.
 
13178
* msggrep:                               msggrep Invocation.
 
13179
* msginit:                               msginit Invocation.
 
13180
* msgmerge:                              msgmerge Invocation.
 
13181
* msgunfmt:                              msgunfmt Invocation.
 
13182
* msguniq:                               msguniq Invocation.
 
13183
* ngettext <1>:                          ngettext Invocation.
 
13184
* ngettext:                              sh.
 
13185
* xgettext:                              xgettext Invocation.
 
13186
 
 
13187
 
 
13188
File: gettext.info,  Node: Option Index,  Next: Variable Index,  Prev: Program Index,  Up: Top
 
13189
 
 
13190
Option Index
 
13191
************
 
13192
 
 
13193
* Menu:
 
13194
 
 
13195
* --add-comments, xgettext option:       xgettext Invocation.
 
13196
* --add-location, msgattrib option:      msgattrib Invocation.
 
13197
* --add-location, msgcat option:         msgcat Invocation.
 
13198
* --add-location, msgcomm option:        msgcomm Invocation.
 
13199
* --add-location, msgconv option:        msgconv Invocation.
 
13200
* --add-location, msgen option:          msgen Invocation.
 
13201
* --add-location, msgfilter option:      msgfilter Invocation.
 
13202
* --add-location, msggrep option:        msggrep Invocation.
 
13203
* --add-location, msgmerge option:       msgmerge Invocation.
 
13204
* --add-location, msguniq option:        msguniq Invocation.
 
13205
* --add-location, xgettext option:       xgettext Invocation.
 
13206
* --alignment, msgfmt option:            msgfmt Invocation.
 
13207
* --backup, msgmerge option:             msgmerge Invocation.
 
13208
* --c++, xgettext option:                xgettext Invocation.
 
13209
* --check, msgfmt option:                msgfmt Invocation.
 
13210
* --check-accelerators, msgfmt option:   msgfmt Invocation.
 
13211
* --check-compatibility, msgfmt option:  msgfmt Invocation.
 
13212
* --check-domain, msgfmt option:         msgfmt Invocation.
 
13213
* --check-format, msgfmt option:         msgfmt Invocation.
 
13214
* --check-header, msgfmt option:         msgfmt Invocation.
 
13215
* --clear-fuzzy, msgattrib option:       msgattrib Invocation.
 
13216
* --clear-obsolete, msgattrib option:    msgattrib Invocation.
 
13217
* --comment, msggrep option:             msggrep Invocation.
 
13218
* --compendium, msgmerge option:         msgmerge Invocation.
 
13219
* --copy, gettextize option:             gettextize Invocation.
 
13220
* --copyright-holder, xgettext option:   xgettext Invocation.
 
13221
* --csharp, msgfmt option:               msgfmt Invocation.
 
13222
* --csharp, msgunfmt option:             msgunfmt Invocation.
 
13223
* --csharp-resources, msgfmt option:     msgfmt Invocation.
 
13224
* --csharp-resources, msgunfmt option:   msgunfmt Invocation.
 
13225
* --debug, xgettext option:              xgettext Invocation.
 
13226
* --default-domain, xgettext option:     xgettext Invocation.
 
13227
* --directory, msgattrib option:         msgattrib Invocation.
 
13228
* --directory, msgcat option:            msgcat Invocation.
 
13229
* --directory, msgcmp option:            msgcmp Invocation.
 
13230
* --directory, msgcomm option:           msgcomm Invocation.
 
13231
* --directory, msgconv option:           msgconv Invocation.
 
13232
* --directory, msgen option:             msgen Invocation.
 
13233
* --directory, msgexec option:           msgexec Invocation.
 
13234
* --directory, msgfilter option:         msgfilter Invocation.
 
13235
* --directory, msgfmt option:            msgfmt Invocation.
 
13236
* --directory, msggrep option:           msggrep Invocation.
 
13237
* --directory, msgmerge option:          msgmerge Invocation.
 
13238
* --directory, msguniq option:           msguniq Invocation.
 
13239
* --directory, xgettext option:          xgettext Invocation.
 
13240
* --domain, gettext option:              gettext Invocation.
 
13241
* --domain, msggrep option:              msggrep Invocation.
 
13242
* --domain, ngettext option:             ngettext Invocation.
 
13243
* --dry-run, autopoint option:           autopoint Invocation.
 
13244
* --dry-run, gettextize option:          gettextize Invocation.
 
13245
* --exclude-file, xgettext option:       xgettext Invocation.
 
13246
* --expression, msgfilter option:        msgfilter Invocation.
 
13247
* --extended-regexp, msggrep option:     msggrep Invocation.
 
13248
* --extract-all, xgettext option:        xgettext Invocation.
 
13249
* --file, msgfilter option:              msgfilter Invocation.
 
13250
* --file, msggrep option:                msggrep Invocation.
 
13251
* --files-from, msgcat option:           msgcat Invocation.
 
13252
* --files-from, msgcomm option:          msgcomm Invocation.
 
13253
* --files-from, xgettext option:         xgettext Invocation.
 
13254
* --fixed-strings, msggrep option:       msggrep Invocation.
 
13255
* --flag, xgettext option:               xgettext Invocation.
 
13256
* --force, autopoint option:             autopoint Invocation.
 
13257
* --force, gettextize option:            gettextize Invocation.
 
13258
* --force-po, msgattrib option:          msgattrib Invocation.
 
13259
* --force-po, msgcat option:             msgcat Invocation.
 
13260
* --force-po, msgcomm option:            msgcomm Invocation.
 
13261
* --force-po, msgconv option:            msgconv Invocation.
 
13262
* --force-po, msgen option:              msgen Invocation.
 
13263
* --force-po, msgfilter option:          msgfilter Invocation.
 
13264
* --force-po, msggrep option:            msggrep Invocation.
 
13265
* --force-po, msgmerge option:           msgmerge Invocation.
 
13266
* --force-po, msgunfmt option:           msgunfmt Invocation.
 
13267
* --force-po, msguniq option:            msguniq Invocation.
 
13268
* --force-po, xgettext option:           xgettext Invocation.
 
13269
* --foreign-user, xgettext option:       xgettext Invocation.
 
13270
* --from-code, xgettext option:          xgettext Invocation.
 
13271
* --fuzzy, msgattrib option:             msgattrib Invocation.
 
13272
* --help, autopoint option:              autopoint Invocation.
 
13273
* --help, envsubst option:               envsubst Invocation.
 
13274
* --help, gettext option:                gettext Invocation.
 
13275
* --help, gettextize option:             gettextize Invocation.
 
13276
* --help, msgattrib option:              msgattrib Invocation.
 
13277
* --help, msgcat option:                 msgcat Invocation.
 
13278
* --help, msgcmp option:                 msgcmp Invocation.
 
13279
* --help, msgcomm option:                msgcomm Invocation.
 
13280
* --help, msgconv option:                msgconv Invocation.
 
13281
* --help, msgen option:                  msgen Invocation.
 
13282
* --help, msgexec option:                msgexec Invocation.
 
13283
* --help, msgfilter option:              msgfilter Invocation.
 
13284
* --help, msgfmt option:                 msgfmt Invocation.
 
13285
* --help, msggrep option:                msggrep Invocation.
 
13286
* --help, msginit option:                msginit Invocation.
 
13287
* --help, msgmerge option:               msgmerge Invocation.
 
13288
* --help, msgunfmt option:               msgunfmt Invocation.
 
13289
* --help, msguniq option:                msguniq Invocation.
 
13290
* --help, ngettext option:               ngettext Invocation.
 
13291
* --help, xgettext option:               xgettext Invocation.
 
13292
* --ignore-case, msggrep option:         msggrep Invocation.
 
13293
* --ignore-file, msgattrib option:       msgattrib Invocation.
 
13294
* --indent, msgattrib option:            msgattrib Invocation.
 
13295
* --indent, msgcat option:               msgcat Invocation.
 
13296
* --indent, msgcomm option:              msgcomm Invocation.
 
13297
* --indent, msgconv option:              msgconv Invocation.
 
13298
* --indent, msgen option:                msgen Invocation.
 
13299
* --indent, msgfilter option:            msgfilter Invocation.
 
13300
* --indent, msggrep option:              msggrep Invocation.
 
13301
* --indent, msgmerge option:             msgmerge Invocation.
 
13302
* --indent, msgunfmt option:             msgunfmt Invocation.
 
13303
* --indent, msguniq option:              msguniq Invocation.
 
13304
* --indent, xgettext option:             xgettext Invocation.
 
13305
* --input, msgexec option:               msgexec Invocation.
 
13306
* --input, msgfilter option:             msgfilter Invocation.
 
13307
* --input, msginit option:               msginit Invocation.
 
13308
* --intl, gettextize option:             gettextize Invocation.
 
13309
* --java, msgfmt option:                 msgfmt Invocation.
 
13310
* --java, msgunfmt option:               msgunfmt Invocation.
 
13311
* --java2, msgfmt option:                msgfmt Invocation.
 
13312
* --join-existing, xgettext option:      xgettext Invocation.
 
13313
* --keep-header, msgfilter option:       msgfilter Invocation.
 
13314
* --keyword, xgettext option:            xgettext Invocation.
 
13315
* --language, xgettext option:           xgettext Invocation.
 
13316
* --less-than, msgcat option:            msgcat Invocation.
 
13317
* --less-than, msgcomm option:           msgcomm Invocation.
 
13318
* --locale, msgfmt option:               msgfmt Invocation.
 
13319
* --locale, msginit option:              msginit Invocation.
 
13320
* --locale, msgunfmt option:             msgunfmt Invocation.
 
13321
* --location, msggrep option:            msggrep Invocation.
 
13322
* --more-than, msgcat option:            msgcat Invocation.
 
13323
* --more-than, msgcomm option:           msgcomm Invocation.
 
13324
* --msgid, msggrep option:               msggrep Invocation.
 
13325
* --msgid-bugs-address, xgettext option: xgettext Invocation.
 
13326
* --msgstr, msggrep option:              msggrep Invocation.
 
13327
* --msgstr-prefix, xgettext option:      xgettext Invocation.
 
13328
* --msgstr-suffix, xgettext option:      xgettext Invocation.
 
13329
* --multi-domain, msgcmp option:         msgcmp Invocation.
 
13330
* --multi-domain, msgmerge option:       msgmerge Invocation.
 
13331
* --no-changelog, gettextize option:     gettextize Invocation.
 
13332
* --no-fuzzy, msgattrib option:          msgattrib Invocation.
 
13333
* --no-fuzzy-matching, msgmerge option:  msgmerge Invocation.
 
13334
* --no-hash, msgfmt option:              msgfmt Invocation.
 
13335
* --no-location, msgattrib option:       msgattrib Invocation.
 
13336
* --no-location, msgcat option:          msgcat Invocation.
 
13337
* --no-location, msgcomm option:         msgcomm Invocation.
 
13338
* --no-location, msgconv option:         msgconv Invocation.
 
13339
* --no-location, msgen option:           msgen Invocation.
 
13340
* --no-location, msgfilter option:       msgfilter Invocation.
 
13341
* --no-location, msggrep option:         msggrep Invocation.
 
13342
* --no-location, msgmerge option:        msgmerge Invocation.
 
13343
* --no-location, msguniq option:         msguniq Invocation.
 
13344
* --no-location, xgettext option:        xgettext Invocation.
 
13345
* --no-obsolete, msgattrib option:       msgattrib Invocation.
 
13346
* --no-translator, msginit option:       msginit Invocation.
 
13347
* --no-wrap, msgattrib option:           msgattrib Invocation.
 
13348
* --no-wrap, msgcat option:              msgcat Invocation.
 
13349
* --no-wrap, msgcomm option:             msgcomm Invocation.
 
13350
* --no-wrap, msgconv option:             msgconv Invocation.
 
13351
* --no-wrap, msgen option:               msgen Invocation.
 
13352
* --no-wrap, msgfilter option:           msgfilter Invocation.
 
13353
* --no-wrap, msggrep option:             msggrep Invocation.
 
13354
* --no-wrap, msginit option:             msginit Invocation.
 
13355
* --no-wrap, msgmerge option:            msgmerge Invocation.
 
13356
* --no-wrap, msgunfmt option:            msgunfmt Invocation.
 
13357
* --no-wrap, msguniq option:             msguniq Invocation.
 
13358
* --no-wrap, xgettext option:            xgettext Invocation.
 
13359
* --obsolete, msgattrib option:          msgattrib Invocation.
 
13360
* --omit-header, msgcomm option:         msgcomm Invocation.
 
13361
* --omit-header, xgettext option:        xgettext Invocation.
 
13362
* --only-file, msgattrib option:         msgattrib Invocation.
 
13363
* --only-fuzzy, msgattrib option:        msgattrib Invocation.
 
13364
* --only-obsolete, msgattrib option:     msgattrib Invocation.
 
13365
* --output, xgettext option:             xgettext Invocation.
 
13366
* --output-dir, xgettext option:         xgettext Invocation.
 
13367
* --output-file, msgattrib option:       msgattrib Invocation.
 
13368
* --output-file, msgcat option:          msgcat Invocation.
 
13369
* --output-file, msgcomm option:         msgcomm Invocation.
 
13370
* --output-file, msgconv option:         msgconv Invocation.
 
13371
* --output-file, msgen option:           msgen Invocation.
 
13372
* --output-file, msgfilter option:       msgfilter Invocation.
 
13373
* --output-file, msgfmt option:          msgfmt Invocation.
 
13374
* --output-file, msggrep option:         msggrep Invocation.
 
13375
* --output-file, msginit option:         msginit Invocation.
 
13376
* --output-file, msgmerge option:        msgmerge Invocation.
 
13377
* --output-file, msgunfmt option:        msgunfmt Invocation.
 
13378
* --output-file, msguniq option:         msguniq Invocation.
 
13379
* --properties-input, msgattrib option:  msgattrib Invocation.
 
13380
* --properties-input, msgcat option:     msgcat Invocation.
 
13381
* --properties-input, msgcmp option:     msgcmp Invocation.
 
13382
* --properties-input, msgcomm option:    msgcomm Invocation.
 
13383
* --properties-input, msgconv option:    msgconv Invocation.
 
13384
* --properties-input, msgen option:      msgen Invocation.
 
13385
* --properties-input, msgexec option:    msgexec Invocation.
 
13386
* --properties-input, msgfilter option:  msgfilter Invocation.
 
13387
* --properties-input, msgfmt option:     msgfmt Invocation.
 
13388
* --properties-input, msggrep option:    msggrep Invocation.
 
13389
* --properties-input, msginit option:    msginit Invocation.
 
13390
* --properties-input, msgmerge option:   msgmerge Invocation.
 
13391
* --properties-input, msguniq option:    msguniq Invocation.
 
13392
* --properties-output, msgattrib option: msgattrib Invocation.
 
13393
* --properties-output, msgcat option:    msgcat Invocation.
 
13394
* --properties-output, msgcomm option:   msgcomm Invocation.
 
13395
* --properties-output, msgconv option:   msgconv Invocation.
 
13396
* --properties-output, msgen option:     msgen Invocation.
 
13397
* --properties-output, msgfilter option: msgfilter Invocation.
 
13398
* --properties-output, msggrep option:   msggrep Invocation.
 
13399
* --properties-output, msginit option:   msginit Invocation.
 
13400
* --properties-output, msgmerge option:  msgmerge Invocation.
 
13401
* --properties-output, msgunfmt option:  msgunfmt Invocation.
 
13402
* --properties-output, msguniq option:   msguniq Invocation.
 
13403
* --properties-output, xgettext option:  xgettext Invocation.
 
13404
* --qt, msgfmt option:                   msgfmt Invocation.
 
13405
* --qt, xgettext option:                 xgettext Invocation.
 
13406
* --quiet, msgfilter option:             msgfilter Invocation.
 
13407
* --quiet, msgmerge option:              msgmerge Invocation.
 
13408
* --regexp=, msggrep option:             msggrep Invocation.
 
13409
* --repeated, msguniq option:            msguniq Invocation.
 
13410
* --resource, msgfmt option:             msgfmt Invocation.
 
13411
* --resource, msgunfmt option:           msgunfmt Invocation.
 
13412
* --set-fuzzy, msgattrib option:         msgattrib Invocation.
 
13413
* --set-obsolete, msgattrib option:      msgattrib Invocation.
 
13414
* --silent, msgfilter option:            msgfilter Invocation.
 
13415
* --silent, msgmerge option:             msgmerge Invocation.
 
13416
* --sort-by-file, msgattrib option:      msgattrib Invocation.
 
13417
* --sort-by-file, msgcat option:         msgcat Invocation.
 
13418
* --sort-by-file, msgcomm option:        msgcomm Invocation.
 
13419
* --sort-by-file, msgconv option:        msgconv Invocation.
 
13420
* --sort-by-file, msgen option:          msgen Invocation.
 
13421
* --sort-by-file, msgfilter option:      msgfilter Invocation.
 
13422
* --sort-by-file, msggrep option:        msggrep Invocation.
 
13423
* --sort-by-file, msgmerge option:       msgmerge Invocation.
 
13424
* --sort-by-file, msguniq option:        msguniq Invocation.
 
13425
* --sort-by-file, xgettext option:       xgettext Invocation.
 
13426
* --sort-output, msgattrib option:       msgattrib Invocation.
 
13427
* --sort-output, msgcat option:          msgcat Invocation.
 
13428
* --sort-output, msgcomm option:         msgcomm Invocation.
 
13429
* --sort-output, msgconv option:         msgconv Invocation.
 
13430
* --sort-output, msgen option:           msgen Invocation.
 
13431
* --sort-output, msgfilter option:       msgfilter Invocation.
 
13432
* --sort-output, msggrep option:         msggrep Invocation.
 
13433
* --sort-output, msgmerge option:        msgmerge Invocation.
 
13434
* --sort-output, msgunfmt option:        msgunfmt Invocation.
 
13435
* --sort-output, msguniq option:         msguniq Invocation.
 
13436
* --sort-output, xgettext option:        xgettext Invocation.
 
13437
* --statistics, msgfmt option:           msgfmt Invocation.
 
13438
* --strict, msgattrib option:            msgattrib Invocation.
 
13439
* --strict, msgcat option:               msgcat Invocation.
 
13440
* --strict, msgcomm option:              msgcomm Invocation.
 
13441
* --strict, msgconv option:              msgconv Invocation.
 
13442
* --strict, msgen option:                msgen Invocation.
 
13443
* --strict, msgfilter option:            msgfilter Invocation.
 
13444
* --strict, msgfmt option:               msgfmt Invocation.
 
13445
* --strict, msggrep option:              msggrep Invocation.
 
13446
* --strict, msgmerge option:             msgmerge Invocation.
 
13447
* --strict, msgunfmt option:             msgunfmt Invocation.
 
13448
* --strict, msguniq option:              msguniq Invocation.
 
13449
* --strict, xgettext option:             xgettext Invocation.
 
13450
* --stringtable-input, msgattrib option: msgattrib Invocation.
 
13451
* --stringtable-input, msgcat option:    msgcat Invocation.
 
13452
* --stringtable-input, msgcmp option:    msgcmp Invocation.
 
13453
* --stringtable-input, msgcomm option:   msgcomm Invocation.
 
13454
* --stringtable-input, msgen option:     msgen Invocation.
 
13455
* --stringtable-input, msgexec option:   msgexec Invocation.
 
13456
* --stringtable-input, msgfilter option: msgfilter Invocation.
 
13457
* --stringtable-input, msgfmt option:    msgfmt Invocation.
 
13458
* --stringtable-input, msggrep option:   msggrep Invocation.
 
13459
* --stringtable-input, msginit option:   msginit Invocation.
 
13460
* --stringtable-input, msgmerge option:  msgmerge Invocation.
 
13461
* --stringtable-input, msgonv option:    msgconv Invocation.
 
13462
* --stringtable-input, msguniq option:   msguniq Invocation.
 
13463
* --stringtable-output, msgattrib option: msgattrib Invocation.
 
13464
* --stringtable-output, msgcat option:   msgcat Invocation.
 
13465
* --stringtable-output, msgcomm option:  msgcomm Invocation.
 
13466
* --stringtable-output, msgconv option:  msgconv Invocation.
 
13467
* --stringtable-output, msgen option:    msgen Invocation.
 
13468
* --stringtable-output, msgfilter option: msgfilter Invocation.
 
13469
* --stringtable-output, msggrep option:  msggrep Invocation.
 
13470
* --stringtable-output, msginit option:  msginit Invocation.
 
13471
* --stringtable-output, msgmerge option: msgmerge Invocation.
 
13472
* --stringtable-output, msgunfmt option: msgunfmt Invocation.
 
13473
* --stringtable-output, msguniq option:  msguniq Invocation.
 
13474
* --stringtable-output, xgettext option: xgettext Invocation.
 
13475
* --suffix, msgmerge option:             msgmerge Invocation.
 
13476
* --tcl, msgfmt option:                  msgfmt Invocation.
 
13477
* --tcl, msgunfmt option:                msgunfmt Invocation.
 
13478
* --to-code, msgcat option:              msgcat Invocation.
 
13479
* --to-code, msgconv option:             msgconv Invocation.
 
13480
* --to-code, msguniq option:             msguniq Invocation.
 
13481
* --translated, msgattrib option:        msgattrib Invocation.
 
13482
* --trigraphs, xgettext option:          xgettext Invocation.
 
13483
* --unique, msgcat option:               msgcat Invocation.
 
13484
* --unique, msgcomm option:              msgcomm Invocation.
 
13485
* --unique, msguniq option:              msguniq Invocation.
 
13486
* --untranslated, msgattrib option:      msgattrib Invocation.
 
13487
* --update, msgmerge option:             msgmerge Invocation.
 
13488
* --use-first, msgcat option:            msgcat Invocation.
 
13489
* --use-first, msguniq option:           msguniq Invocation.
 
13490
* --use-fuzzy, msgfmt option:            msgfmt Invocation.
 
13491
* --variables, envsubst option:          envsubst Invocation.
 
13492
* --verbose, msgfmt option:              msgfmt Invocation.
 
13493
* --verbose, msgmerge option:            msgmerge Invocation.
 
13494
* --verbose, msgunfmt option:            msgunfmt Invocation.
 
13495
* --version, autopoint option:           autopoint Invocation.
 
13496
* --version, envsubst option:            envsubst Invocation.
 
13497
* --version, gettext option:             gettext Invocation.
 
13498
* --version, gettextize option:          gettextize Invocation.
 
13499
* --version, msgattrib option:           msgattrib Invocation.
 
13500
* --version, msgcat option:              msgcat Invocation.
 
13501
* --version, msgcmp option:              msgcmp Invocation.
 
13502
* --version, msgcomm option:             msgcomm Invocation.
 
13503
* --version, msgconv option:             msgconv Invocation.
 
13504
* --version, msgen option:               msgen Invocation.
 
13505
* --version, msgexec option:             msgexec Invocation.
 
13506
* --version, msgfilter option:           msgfilter Invocation.
 
13507
* --version, msgfmt option:              msgfmt Invocation.
 
13508
* --version, msggrep option:             msggrep Invocation.
 
13509
* --version, msginit option:             msginit Invocation.
 
13510
* --version, msgmerge option:            msgmerge Invocation.
 
13511
* --version, msgunfmt option:            msgunfmt Invocation.
 
13512
* --version, msguniq option:             msguniq Invocation.
 
13513
* --version, ngettext option:            ngettext Invocation.
 
13514
* --version, xgettext option:            xgettext Invocation.
 
13515
* --width, msgattrib option:             msgattrib Invocation.
 
13516
* --width, msgcat option:                msgcat Invocation.
 
13517
* --width, msgcomm option:               msgcomm Invocation.
 
13518
* --width, msgconv option:               msgconv Invocation.
 
13519
* --width, msgen option:                 msgen Invocation.
 
13520
* --width, msgfilter option:             msgfilter Invocation.
 
13521
* --width, msggrep option:               msggrep Invocation.
 
13522
* --width, msginit option:               msginit Invocation.
 
13523
* --width, msgmerge option:              msgmerge Invocation.
 
13524
* --width, msgunfmt option:              msgunfmt Invocation.
 
13525
* --width, msguniq option:               msguniq Invocation.
 
13526
* --width, xgettext option:              xgettext Invocation.
 
13527
* -<, msgcat option:                     msgcat Invocation.
 
13528
* -<, msgcomm option:                    msgcomm Invocation.
 
13529
* ->, msgcat option:                     msgcat Invocation.
 
13530
* ->, msgcomm option:                    msgcomm Invocation.
 
13531
* -a, msgfmt option:                     msgfmt Invocation.
 
13532
* -a, xgettext option:                   xgettext Invocation.
 
13533
* -c, gettextize option:                 gettextize Invocation.
 
13534
* -C, msgfmt option:                     msgfmt Invocation.
 
13535
* -c, msgfmt option:                     msgfmt Invocation.
 
13536
* -C, msggrep option:                    msggrep Invocation.
 
13537
* -C, msgmerge option:                   msgmerge Invocation.
 
13538
* -c, xgettext option:                   xgettext Invocation.
 
13539
* -C, xgettext option:                   xgettext Invocation.
 
13540
* -d, autopoint option:                  autopoint Invocation.
 
13541
* -d, gettext option:                    gettext Invocation.
 
13542
* -d, gettextize option:                 gettextize Invocation.
 
13543
* -D, msgattrib option:                  msgattrib Invocation.
 
13544
* -D, msgcat option:                     msgcat Invocation.
 
13545
* -D, msgcmp option:                     msgcmp Invocation.
 
13546
* -D, msgcomm option:                    msgcomm Invocation.
 
13547
* -D, msgconv option:                    msgconv Invocation.
 
13548
* -D, msgen option:                      msgen Invocation.
 
13549
* -D, msgexec option:                    msgexec Invocation.
 
13550
* -D, msgfilter option:                  msgfilter Invocation.
 
13551
* -d, msgfmt option:                     msgfmt Invocation.
 
13552
* -D, msgfmt option:                     msgfmt Invocation.
 
13553
* -D, msggrep option:                    msggrep Invocation.
 
13554
* -D, msgmerge option:                   msgmerge Invocation.
 
13555
* -d, msgunfmt option:                   msgunfmt Invocation.
 
13556
* -d, msguniq option:                    msguniq Invocation.
 
13557
* -D, msguniq option:                    msguniq Invocation.
 
13558
* -d, ngettext option:                   ngettext Invocation.
 
13559
* -d, xgettext option:                   xgettext Invocation.
 
13560
* -D, xgettext option:                   xgettext Invocation.
 
13561
* -E, gettext option:                    gettext Invocation.
 
13562
* -e, gettext option:                    gettext Invocation.
 
13563
* -e, msgfilter option:                  msgfilter Invocation.
 
13564
* -e, msggrep option:                    msggrep Invocation.
 
13565
* -E, msggrep option:                    msggrep Invocation.
 
13566
* -E, ngettext option:                   ngettext Invocation.
 
13567
* -e, ngettext option:                   ngettext Invocation.
 
13568
* -f, autopoint option:                  autopoint Invocation.
 
13569
* -f, gettextize option:                 gettextize Invocation.
 
13570
* -F, msgattrib option:                  msgattrib Invocation.
 
13571
* -F, msgcat option:                     msgcat Invocation.
 
13572
* -f, msgcat option:                     msgcat Invocation.
 
13573
* -F, msgcomm option:                    msgcomm Invocation.
 
13574
* -f, msgcomm option:                    msgcomm Invocation.
 
13575
* -F, msgconv option:                    msgconv Invocation.
 
13576
* -F, msgen option:                      msgen Invocation.
 
13577
* -F, msgfilter option:                  msgfilter Invocation.
 
13578
* -f, msgfilter option:                  msgfilter Invocation.
 
13579
* -f, msgfmt option:                     msgfmt Invocation.
 
13580
* -f, msggrep option:                    msggrep Invocation.
 
13581
* -F, msggrep option:                    msggrep Invocation.
 
13582
* -F, msgmerge option:                   msgmerge Invocation.
 
13583
* -F, msguniq option:                    msguniq Invocation.
 
13584
* -F, xgettext option:                   xgettext Invocation.
 
13585
* -f, xgettext option:                   xgettext Invocation.
 
13586
* -h, envsubst option:                   envsubst Invocation.
 
13587
* -h, gettext option:                    gettext Invocation.
 
13588
* -h, msgattrib option:                  msgattrib Invocation.
 
13589
* -h, msgcat option:                     msgcat Invocation.
 
13590
* -h, msgcmp option:                     msgcmp Invocation.
 
13591
* -h, msgcomm option:                    msgcomm Invocation.
 
13592
* -h, msgconv option:                    msgconv Invocation.
 
13593
* -h, msgen option:                      msgen Invocation.
 
13594
* -h, msgexec option:                    msgexec Invocation.
 
13595
* -h, msgfilter option:                  msgfilter Invocation.
 
13596
* -h, msgfmt option:                     msgfmt Invocation.
 
13597
* -h, msggrep option:                    msggrep Invocation.
 
13598
* -h, msginit option:                    msginit Invocation.
 
13599
* -h, msgmerge option:                   msgmerge Invocation.
 
13600
* -h, msgunfmt option:                   msgunfmt Invocation.
 
13601
* -h, msguniq option:                    msguniq Invocation.
 
13602
* -h, ngettext option:                   ngettext Invocation.
 
13603
* -h, xgettext option:                   xgettext Invocation.
 
13604
* -i, msgattrib option:                  msgattrib Invocation.
 
13605
* -i, msgcat option:                     msgcat Invocation.
 
13606
* -i, msgcomm option:                    msgcomm Invocation.
 
13607
* -i, msgconv option:                    msgconv Invocation.
 
13608
* -i, msgen option:                      msgen Invocation.
 
13609
* -i, msgexec option:                    msgexec Invocation.
 
13610
* -i, msgfilter option:                  msgfilter Invocation.
 
13611
* -i, msggrep option:                    msggrep Invocation.
 
13612
* -i, msginit option:                    msginit Invocation.
 
13613
* -i, msgmerge option:                   msgmerge Invocation.
 
13614
* -i, msgunfmt option:                   msgunfmt Invocation.
 
13615
* -i, msguniq option:                    msguniq Invocation.
 
13616
* -i, xgettext option:                   xgettext Invocation.
 
13617
* -j, msgfmt option:                     msgfmt Invocation.
 
13618
* -j, msgunfmt option:                   msgunfmt Invocation.
 
13619
* -j, xgettext option:                   xgettext Invocation.
 
13620
* -K, msggrep option:                    msggrep Invocation.
 
13621
* -k, xgettext option:                   xgettext Invocation.
 
13622
* -l, msgfmt option:                     msgfmt Invocation.
 
13623
* -l, msginit option:                    msginit Invocation.
 
13624
* -l, msgunfmt option:                   msgunfmt Invocation.
 
13625
* -L, xgettext option:                   xgettext Invocation.
 
13626
* -m, msgcmp option:                     msgcmp Invocation.
 
13627
* -M, msggrep option:                    msggrep Invocation.
 
13628
* -m, msgmerge option:                   msgmerge Invocation.
 
13629
* -M, xgettext option:                   xgettext Invocation.
 
13630
* -m, xgettext option:                   xgettext Invocation.
 
13631
* -n, gettext option:                    gettext Invocation.
 
13632
* -n, msgattrib option:                  msgattrib Invocation.
 
13633
* -n, msgcat option:                     msgcat Invocation.
 
13634
* -n, msgcomm option:                    msgcomm Invocation.
 
13635
* -n, msgfilter option:                  msgfilter Invocation.
 
13636
* -N, msggrep option:                    msggrep Invocation.
 
13637
* -N, msgmerge option:                   msgmerge Invocation.
 
13638
* -n, msguniq option:                    msguniq Invocation.
 
13639
* -n, xgettext option:                   xgettext Invocation.
 
13640
* -o, msgattrib option:                  msgattrib Invocation.
 
13641
* -o, msgcat option:                     msgcat Invocation.
 
13642
* -o, msgcomm option:                    msgcomm Invocation.
 
13643
* -o, msgconv option:                    msgconv Invocation.
 
13644
* -o, msgen option:                      msgen Invocation.
 
13645
* -o, msgfilter option:                  msgfilter Invocation.
 
13646
* -o, msgfmt option:                     msgfmt Invocation.
 
13647
* -o, msggrep option:                    msggrep Invocation.
 
13648
* -o, msginit option:                    msginit Invocation.
 
13649
* -o, msgmerge option:                   msgmerge Invocation.
 
13650
* -o, msgunfmt option:                   msgunfmt Invocation.
 
13651
* -o, msguniq option:                    msguniq Invocation.
 
13652
* -o, xgettext option:                   xgettext Invocation.
 
13653
* -p, msgattrib option:                  msgattrib Invocation.
 
13654
* -P, msgattrib option:                  msgattrib Invocation.
 
13655
* -p, msgcat option:                     msgcat Invocation.
 
13656
* -P, msgcat option:                     msgcat Invocation.
 
13657
* -P, msgcmp option:                     msgcmp Invocation.
 
13658
* -p, msgcomm option:                    msgcomm Invocation.
 
13659
* -P, msgcomm option:                    msgcomm Invocation.
 
13660
* -p, msgconv option:                    msgconv Invocation.
 
13661
* -P, msgconv option:                    msgconv Invocation.
 
13662
* -p, msgen option:                      msgen Invocation.
 
13663
* -P, msgen option:                      msgen Invocation.
 
13664
* -P, msgexec option:                    msgexec Invocation.
 
13665
* -p, msgfilter option:                  msgfilter Invocation.
 
13666
* -P, msgfilter option:                  msgfilter Invocation.
 
13667
* -P, msgfmt option:                     msgfmt Invocation.
 
13668
* -p, msggrep option:                    msggrep Invocation.
 
13669
* -P, msggrep option:                    msggrep Invocation.
 
13670
* -p, msginit option:                    msginit Invocation.
 
13671
* -P, msginit option:                    msginit Invocation.
 
13672
* -p, msgmerge option:                   msgmerge Invocation.
 
13673
* -P, msgmerge option:                   msgmerge Invocation.
 
13674
* -p, msgunfmt option:                   msgunfmt Invocation.
 
13675
* -p, msguniq option:                    msguniq Invocation.
 
13676
* -P, msguniq option:                    msguniq Invocation.
 
13677
* -p, xgettext option:                   xgettext Invocation.
 
13678
* -q, msgmerge option:                   msgmerge Invocation.
 
13679
* -r, msgfmt option:                     msgfmt Invocation.
 
13680
* -r, msgunfmt option:                   msgunfmt Invocation.
 
13681
* -s, msgattrib option:                  msgattrib Invocation.
 
13682
* -s, msgcat option:                     msgcat Invocation.
 
13683
* -s, msgcomm option:                    msgcomm Invocation.
 
13684
* -s, msgconv option:                    msgconv Invocation.
 
13685
* -s, msgen option:                      msgen Invocation.
 
13686
* -s, msgfilter option:                  msgfilter Invocation.
 
13687
* -s, msgmerge option:                   msgmerge Invocation.
 
13688
* -s, msgunfmt option:                   msgunfmt Invocation.
 
13689
* -s, msguniq option:                    msguniq Invocation.
 
13690
* -s, xgettext option:                   xgettext Invocation.
 
13691
* -t, msgcat option:                     msgcat Invocation.
 
13692
* -t, msgconv option:                    msgconv Invocation.
 
13693
* -T, msggrep option:                    msggrep Invocation.
 
13694
* -t, msguniq option:                    msguniq Invocation.
 
13695
* -T, xgettext option:                   xgettext Invocation.
 
13696
* -u, msgcat option:                     msgcat Invocation.
 
13697
* -u, msgcomm option:                    msgcomm Invocation.
 
13698
* -U, msgmerge option:                   msgmerge Invocation.
 
13699
* -u, msguniq option:                    msguniq Invocation.
 
13700
* -V, envsubst option:                   envsubst Invocation.
 
13701
* -v, envsubst option:                   envsubst Invocation.
 
13702
* -V, gettext option:                    gettext Invocation.
 
13703
* -V, msgattrib option:                  msgattrib Invocation.
 
13704
* -V, msgcat option:                     msgcat Invocation.
 
13705
* -V, msgcmp option:                     msgcmp Invocation.
 
13706
* -V, msgcomm option:                    msgcomm Invocation.
 
13707
* -V, msgconv option:                    msgconv Invocation.
 
13708
* -V, msgen option:                      msgen Invocation.
 
13709
* -V, msgexec option:                    msgexec Invocation.
 
13710
* -V, msgfilter option:                  msgfilter Invocation.
 
13711
* -v, msgfmt option:                     msgfmt Invocation.
 
13712
* -V, msgfmt option:                     msgfmt Invocation.
 
13713
* -V, msggrep option:                    msggrep Invocation.
 
13714
* -V, msginit option:                    msginit Invocation.
 
13715
* -v, msgmerge option:                   msgmerge Invocation.
 
13716
* -V, msgmerge option:                   msgmerge Invocation.
 
13717
* -v, msgunfmt option:                   msgunfmt Invocation.
 
13718
* -V, msgunfmt option:                   msgunfmt Invocation.
 
13719
* -V, msguniq option:                    msguniq Invocation.
 
13720
* -V, ngettext option:                   ngettext Invocation.
 
13721
* -V, xgettext option:                   xgettext Invocation.
 
13722
* -w, msgattrib option:                  msgattrib Invocation.
 
13723
* -w, msgcat option:                     msgcat Invocation.
 
13724
* -w, msgcomm option:                    msgcomm Invocation.
 
13725
* -w, msgconv option:                    msgconv Invocation.
 
13726
* -w, msgen option:                      msgen Invocation.
 
13727
* -w, msgfilter option:                  msgfilter Invocation.
 
13728
* -w, msggrep option:                    msggrep Invocation.
 
13729
* -w, msginit option:                    msginit Invocation.
 
13730
* -w, msgmerge option:                   msgmerge Invocation.
 
13731
* -w, msgunfmt option:                   msgunfmt Invocation.
 
13732
* -w, msguniq option:                    msguniq Invocation.
 
13733
* -w, xgettext option:                   xgettext Invocation.
 
13734
* -x, xgettext option:                   xgettext Invocation.
 
13735
 
 
13736
 
 
13737
File: gettext.info,  Node: Variable Index,  Next: PO Mode Index,  Prev: Option Index,  Up: Top
 
13738
 
 
13739
Variable Index
 
13740
**************
 
13741
 
 
13742
* Menu:
 
13743
 
 
13744
* GETTEXT_LOG_UNTRANSLATED, environment variable: Prioritizing messages.
 
13745
* LANG, environment variable <1>:        gettext grok.
 
13746
* LANG, environment variable:            End Users.
 
13747
* LANGUAGE, environment variable <1>:    po/Makevars.
 
13748
* LANGUAGE, environment variable:        gettext grok.
 
13749
* LC_ALL, environment variable:          gettext grok.
 
13750
* LC_COLLATE, environment variable:      gettext grok.
 
13751
* LC_CTYPE, environment variable:        gettext grok.
 
13752
* LC_MESSAGES, environment variable:     gettext grok.
 
13753
* LC_MONETARY, environment variable:     gettext grok.
 
13754
* LC_NUMERIC, environment variable:      gettext grok.
 
13755
* LC_TIME, environment variable:         gettext grok.
 
13756
* LINGUAS, environment variable:         Installers.
 
13757
* MSGEXEC_LOCATION, environment variable: msgexec Invocation.
 
13758
* MSGEXEC_MSGID, environment variable:   msgexec Invocation.
 
13759
* TEXTDOMAIN, environment variable:      sh.
 
13760
* TEXTDOMAINDIR, environment variable:   sh.
 
13761
 
 
13762
 
 
13763
File: gettext.info,  Node: PO Mode Index,  Next: Autoconf Macro Index,  Prev: Variable Index,  Up: Top
 
13764
 
 
13765
PO Mode Index
 
13766
*************
 
13767
 
 
13768
* Menu:
 
13769
 
 
13770
* #, PO Mode command:                    Modifying Comments.
 
13771
* ,, PO Mode command:                    Marking.
 
13772
* ., PO Mode command:                    Entry Positioning.
 
13773
* .emacs customizations:                 Installation.
 
13774
* 0, PO Mode command:                    Main PO Commands.
 
13775
* <, PO Mode command:                    Entry Positioning.
 
13776
* =, PO Mode command:                    Main PO Commands.
 
13777
* >, PO Mode command:                    Entry Positioning.
 
13778
* ?, PO Mode command:                    Main PO Commands.
 
13779
* _, PO Mode command:                    Main PO Commands.
 
13780
* a, PO Mode command:                    Auxiliary.
 
13781
* A, PO Mode command:                    Auxiliary.
 
13782
* a, PO Mode command:                    Auxiliary.
 
13783
* auxiliary PO file:                     Auxiliary.
 
13784
* C-c C-a, PO Mode command <1>:          Auxiliary.
 
13785
* C-c C-a, PO Mode command:              Subedit.
 
13786
* C-c C-c, PO Mode command:              Subedit.
 
13787
* C-c C-k, PO Mode command:              Subedit.
 
13788
* C-j, PO Mode command:                  Modifying Translations.
 
13789
* commands:                              Main PO Commands.
 
13790
* comment out PO file entry:             Obsolete Entries.
 
13791
* consulting program sources:            C Sources Context.
 
13792
* consulting translations to other languages: Auxiliary.
 
13793
* current entry of a PO file:            Entry Positioning.
 
13794
* cut and paste for translated strings:  Modifying Translations.
 
13795
* DEL, PO Mode command <1>:              Obsolete Entries.
 
13796
* DEL, PO Mode command:                  Fuzzy Entries.
 
13797
* editing comments:                      Modifying Comments.
 
13798
* editing multiple entries:              Subedit.
 
13799
* editing translations:                  Modifying Translations.
 
13800
* etags, using for marking strings:      Marking.
 
13801
* exiting PO subedit:                    Subedit.
 
13802
* find source fragment for a PO file entry: C Sources Context.
 
13803
* h, PO Mode command:                    Main PO Commands.
 
13804
* installing PO mode:                    Installation.
 
13805
* K, PO Mode command:                    Modifying Comments.
 
13806
* k, PO Mode command <1>:                Modifying Translations.
 
13807
* k, PO Mode command:                    Untranslated Entries.
 
13808
* LFD, PO Mode command:                  Modifying Translations.
 
13809
* looking at the source to aid translation: C Sources Context.
 
13810
* m, PO Mode command:                    Entry Positioning.
 
13811
* M-,, PO Mode command:                  Marking.
 
13812
* M-., PO Mode command:                  Marking.
 
13813
* M-A, PO Mode command:                  Auxiliary.
 
13814
* M-S, PO Mode command:                  C Sources Context.
 
13815
* M-s, PO Mode command:                  C Sources Context.
 
13816
* M-S, PO Mode command:                  C Sources Context.
 
13817
* M-s, PO Mode command:                  C Sources Context.
 
13818
* marking strings for translation:       Marking.
 
13819
* moving by fuzzy entries:               Fuzzy Entries.
 
13820
* moving by obsolete entries:            Obsolete Entries.
 
13821
* moving by translated entries:          Translated Entries.
 
13822
* moving by untranslated entries:        Untranslated Entries.
 
13823
* moving through a PO file:              Entry Positioning.
 
13824
* n, PO Mode command:                    Entry Positioning.
 
13825
* next-error, stepping through PO file validation results: Main PO Commands.
 
13826
* normalize, PO Mode command:            Auxiliary.
 
13827
* O, PO Mode command:                    Obsolete Entries.
 
13828
* o, PO Mode command:                    Obsolete Entries.
 
13829
* O, PO Mode command:                    Obsolete Entries.
 
13830
* o, PO Mode command:                    Obsolete Entries.
 
13831
* obsolete active entry:                 Obsolete Entries.
 
13832
* p, PO Mode command:                    Entry Positioning.
 
13833
* pending subedits:                      Subedit.
 
13834
* po-auto-edit-with-msgid, PO Mode variable: Modifying Translations.
 
13835
* po-auto-fuzzy-on-edit, PO Mode variable: Translated Entries.
 
13836
* po-auto-select-on-unfuzzy, PO Mode variable: Fuzzy Entries.
 
13837
* po-confirm-and-quit, PO Mode command:  Main PO Commands.
 
13838
* po-consider-as-auxiliary, PO Mode command: Auxiliary.
 
13839
* po-consider-source-path, PO Mode command: C Sources Context.
 
13840
* po-current-entry, PO Mode command:     Entry Positioning.
 
13841
* po-cycle-auxiliary, PO Mode command:   Auxiliary.
 
13842
* po-cycle-source-reference, PO Mode command: C Sources Context.
 
13843
* po-edit-comment, PO Mode command:      Modifying Comments.
 
13844
* po-edit-msgstr, PO Mode command:       Modifying Translations.
 
13845
* po-exchange-location, PO Mode command: Entry Positioning.
 
13846
* po-fade-out-entry, PO Mode command <1>: Obsolete Entries.
 
13847
* po-fade-out-entry, PO Mode command:    Fuzzy Entries.
 
13848
* po-first-entry, PO Mode command:       Entry Positioning.
 
13849
* po-help, PO Mode command:              Main PO Commands.
 
13850
* po-ignore-as-auxiliary, PO Mode command: Auxiliary.
 
13851
* po-ignore-source-path, PO Mode command: C Sources Context.
 
13852
* po-kill-comment, PO Mode command:      Modifying Comments.
 
13853
* po-kill-msgstr, PO Mode command <1>:   Modifying Translations.
 
13854
* po-kill-msgstr, PO Mode command:       Untranslated Entries.
 
13855
* po-kill-ring-save-comment, PO Mode command: Modifying Comments.
 
13856
* po-kill-ring-save-msgstr, PO Mode command: Modifying Translations.
 
13857
* po-last-entry, PO Mode command:        Entry Positioning.
 
13858
* po-mark-translatable, PO Mode command: Marking.
 
13859
* po-msgid-to-msgstr, PO Mode command:   Modifying Translations.
 
13860
* po-next-entry, PO Mode command:        Entry Positioning.
 
13861
* po-next-fuzzy-entry, PO Mode command:  Fuzzy Entries.
 
13862
* po-next-obsolete-entry, PO Mode command: Obsolete Entries.
 
13863
* po-next-translated-entry, PO Mode command: Translated Entries.
 
13864
* po-next-untranslated-entry, PO Mode command: Untranslated Entries.
 
13865
* po-normalize, PO Mode command <1>:     Normalizing.
 
13866
* po-normalize, PO Mode command:         PO Files.
 
13867
* po-other-window, PO Mode command:      Main PO Commands.
 
13868
* po-pop-location, PO Mode command:      Entry Positioning.
 
13869
* po-previous-entry, PO Mode command:    Entry Positioning.
 
13870
* po-previous-fuzzy-entry, PO Mode command: Fuzzy Entries.
 
13871
* po-previous-obsolete-entry, PO Mode command: Obsolete Entries.
 
13872
* po-previous-translated-entry, PO Mode command: Translated Entries.
 
13873
* po-previous-untransted-entry, PO Mode command: Untranslated Entries.
 
13874
* po-push-location, PO Mode command:     Entry Positioning.
 
13875
* po-quit, PO Mode command:              Main PO Commands.
 
13876
* po-select-auxiliary, PO Mode command:  Auxiliary.
 
13877
* po-select-mark-and-mark, PO Mode command: Marking.
 
13878
* po-select-source-reference, PO Mode command: C Sources Context.
 
13879
* po-statistics, PO Mode command:        Main PO Commands.
 
13880
* po-subedit-abort, PO Mode command:     Subedit.
 
13881
* po-subedit-cycle-auxiliary, PO Mode command: Subedit.
 
13882
* po-subedit-exit, PO Mode command:      Subedit.
 
13883
* po-subedit-mode-hook, PO Mode variable: Modifying Comments.
 
13884
* po-tags-search, PO Mode command:       Marking.
 
13885
* po-undo, PO Mode command:              Main PO Commands.
 
13886
* po-unfuzzy, PO Mode command:           Fuzzy Entries.
 
13887
* po-validate, PO Mode command:          Main PO Commands.
 
13888
* po-yank-comment, PO Mode command:      Modifying Comments.
 
13889
* po-yank-msgstr, PO Mode command:       Modifying Translations.
 
13890
* q, PO Mode command:                    Main PO Commands.
 
13891
* Q, PO Mode command:                    Main PO Commands.
 
13892
* q, PO Mode command:                    Main PO Commands.
 
13893
* Q, PO Mode command:                    Main PO Commands.
 
13894
* r, PO Mode command:                    Entry Positioning.
 
13895
* RET, PO Mode command:                  Modifying Translations.
 
13896
* S, PO Mode command:                    C Sources Context.
 
13897
* s, PO Mode command:                    C Sources Context.
 
13898
* S, PO Mode command:                    C Sources Context.
 
13899
* s, PO Mode command:                    C Sources Context.
 
13900
* starting a string translation:         Modifying Translations.
 
13901
* string normalization in entries:       Normalizing.
 
13902
* subedit minor mode:                    Subedit.
 
13903
* T, PO Mode command:                    Translated Entries.
 
13904
* t, PO Mode command:                    Translated Entries.
 
13905
* T, PO Mode command:                    Translated Entries.
 
13906
* t, PO Mode command:                    Translated Entries.
 
13907
* TAB, PO Mode command:                  Fuzzy Entries.
 
13908
* TAGS, and marking translatable strings: Marking.
 
13909
* U, PO Mode command:                    Untranslated Entries.
 
13910
* u, PO Mode command:                    Untranslated Entries.
 
13911
* U, PO Mode command:                    Untranslated Entries.
 
13912
* u, PO Mode command:                    Untranslated Entries.
 
13913
* use the source, Luke:                  C Sources Context.
 
13914
* using obsolete translations to make new entries: Modifying Translations.
 
13915
* using translation compendia:           Compendium.
 
13916
* V, PO Mode command:                    Main PO Commands.
 
13917
* W, PO Mode command:                    Modifying Comments.
 
13918
* w, PO Mode command:                    Modifying Translations.
 
13919
* x, PO Mode command:                    Entry Positioning.
 
13920
* Y, PO Mode command:                    Modifying Comments.
 
13921
* y, PO Mode command:                    Modifying Translations.
 
13922
* Z, PO Mode command:                    Fuzzy Entries.
 
13923
* z, PO Mode command:                    Fuzzy Entries.
 
13924
* Z, PO Mode command:                    Fuzzy Entries.
 
13925
* z, PO Mode command:                    Fuzzy Entries.
 
13926
 
 
13927
 
 
13928
File: gettext.info,  Node: Autoconf Macro Index,  Next: Index,  Prev: PO Mode Index,  Up: Top
 
13929
 
 
13930
Autoconf Macro Index
 
13931
********************
 
13932
 
 
13933
* Menu:
 
13934
 
 
13935
* AM_GNU_GETTEXT:                        AM_GNU_GETTEXT.
 
13936
* AM_GNU_GETTEXT_VERSION:                AM_GNU_GETTEXT_VERSION.
 
13937
* AM_ICONV:                              AM_ICONV.
 
13938
* AM_PO_SUBDIRS:                         AM_PO_SUBDIRS.
 
13939
 
 
13940
 
 
13941
File: gettext.info,  Node: Index,  Prev: Autoconf Macro Index,  Up: Top
 
13942
 
 
13943
General Index
 
13944
*************
 
13945
 
 
13946
* Menu:
 
13947
 
 
13948
* _, a macro to mark strings for translation: Mark Keywords.
 
13949
* _nl_msg_cat_cntr:                      gettext grok.
 
13950
* ABOUT-NLS file:                        Matrix.
 
13951
* acconfig.h file:                       acconfig.
 
13952
* accumulating translations:             Creating Compendia.
 
13953
* aclocal.m4 file:                       aclocal.
 
13954
* adding keywords, xgettext:             xgettext Invocation.
 
13955
* ambiguities:                           Preparing Strings.
 
13956
* apply a filter to translations:        msgfilter Invocation.
 
13957
* apply command to all translations in a catalog: msgexec Invocation.
 
13958
* Arabic digits:                         c-format.
 
13959
* attribute manipulation:                msgattrib Invocation.
 
13960
* attribute, fuzzy:                      Fuzzy Entries.
 
13961
* attributes of a PO file entry:         Fuzzy Entries.
 
13962
* attributes, manipulating:              Manipulating.
 
13963
* autoconf macros for gettext:           autoconf macros.
 
13964
* autopoint program, usage:              autopoint Invocation.
 
13965
* auxiliary PO file:                     Auxiliary.
 
13966
* available translations:                Matrix.
 
13967
* awk:                                   gawk.
 
13968
* awk-format flag:                       PO Files.
 
13969
* backup old file, and msgmerge program: msgmerge Invocation.
 
13970
* bash:                                  bash.
 
13971
* bibliography:                          References.
 
13972
* big picture:                           Overview.
 
13973
* bind_textdomain_codeset:               Charset conversion.
 
13974
* bug report address:                    Introduction.
 
13975
* C and C-like languages:                C.
 
13976
* C trigraphs:                           xgettext Invocation.
 
13977
* C#:                                    C#.
 
13978
* C# mode, and msgfmt program:           msgfmt Invocation.
 
13979
* C# mode, and msgunfmt program:         msgunfmt Invocation.
 
13980
* C# resources mode, and msgfmt program: msgfmt Invocation.
 
13981
* C# resources mode, and msgunfmt program: msgunfmt Invocation.
 
13982
* C#, string concatenation:              Preparing Strings.
 
13983
* c-format flag:                         PO Files.
 
13984
* c-format, and xgettext:                c-format Flag.
 
13985
* catalog encoding and msgexec output:   msgexec Invocation.
 
13986
* catclose, a catgets function:          Interface to catgets.
 
13987
* catgets, a catgets function:           Interface to catgets.
 
13988
* catgets, X/Open specification:         catgets.
 
13989
* catopen, a catgets function:           Interface to catgets.
 
13990
* character encoding:                    Aspects.
 
13991
* charset conversion at runtime:         Charset conversion.
 
13992
* charset of PO files:                   Header Entry.
 
13993
* check format strings:                  msgfmt Invocation.
 
13994
* checking of translations:              Manipulating.
 
13995
* clisp:                                 Common Lisp.
 
13996
* clisp C sources:                       clisp C.
 
13997
* codeset:                               Aspects.
 
13998
* comments in PO files:                  PO Files.
 
13999
* Common Lisp:                           Common Lisp.
 
14000
* compare PO files:                      msgcmp Invocation.
 
14001
* comparison of interfaces:              Comparison.
 
14002
* compatibility with X/Open msgfmt:      msgfmt Invocation.
 
14003
* compendium:                            Compendium.
 
14004
* compendium, creating:                  Creating Compendia.
 
14005
* concatenate PO files:                  msgcat Invocation.
 
14006
* concatenating PO files into a compendium: Creating Compendia.
 
14007
* concatenation of strings:              Preparing Strings.
 
14008
* config.h.in file:                      config.h.in.
 
14009
* convert binary message catalog into PO file: msgunfmt Invocation.
 
14010
* convert translations to a different encoding: msgconv Invocation.
 
14011
* converting a package to use gettext:   Prerequisites.
 
14012
* country codes:                         Country Codes.
 
14013
* create new PO file:                    msginit Invocation.
 
14014
* creating a new PO file:                Creating.
 
14015
* creating compendia:                    Creating Compendia.
 
14016
* csharp-format flag:                    PO Files.
 
14017
* currency symbols:                      Aspects.
 
14018
* date format:                           Aspects.
 
14019
* dcngettext:                            Plural forms.
 
14020
* debugging messages marked as format strings: xgettext Invocation.
 
14021
* dialect:                               Manipulating.
 
14022
* disabling NLS:                         lib/gettext.h.
 
14023
* dngettext:                             Plural forms.
 
14024
* dollar substitution:                   envsubst Invocation.
 
14025
* domain ambiguities:                    Ambiguities.
 
14026
* duplicate elimination:                 Manipulating.
 
14027
* duplicate removal:                     msguniq Invocation.
 
14028
* editing comments in PO files:          Modifying Comments.
 
14029
* editing translations:                  Modifying Translations.
 
14030
* elisp-format flag:                     PO Files.
 
14031
* Emacs Lisp:                            Emacs Lisp.
 
14032
* encoding:                              Aspects.
 
14033
* encoding conversion:                   Manipulating.
 
14034
* encoding conversion at runtime:        Charset conversion.
 
14035
* encoding for your language:            Header Entry.
 
14036
* encoding list:                         Header Entry.
 
14037
* encoding of PO files:                  Header Entry.
 
14038
* environment variables:                 envsubst Invocation.
 
14039
* envsubst program, usage:               envsubst Invocation.
 
14040
* eval_gettext function, usage:          eval_gettext Invocation.
 
14041
* eval_ngettext function, usage:         eval_ngettext Invocation.
 
14042
* evolution of packages:                 Overview.
 
14043
* extracting parts of a PO file into a compendium: Creating Compendia.
 
14044
* file format, .mo:                      MO Files.
 
14045
* file format, .po:                      PO Files.
 
14046
* files, .po and .mo:                    Files.
 
14047
* files, .pot:                           Overview.
 
14048
* filter messages according to attributes: msgattrib Invocation.
 
14049
* find common messages:                  msgcomm Invocation.
 
14050
* force use of fuzzy entries:            msgfmt Invocation.
 
14051
* format strings:                        c-format Flag.
 
14052
* Free Pascal:                           Pascal.
 
14053
* function attribute, __format__:        xgettext Invocation.
 
14054
* function attribute, __format_arg__:    xgettext Invocation.
 
14055
* fuzzy entries:                         Fuzzy Entries.
 
14056
* fuzzy flag:                            PO Files.
 
14057
* gawk:                                  gawk.
 
14058
* gcc-internal-format flag:              PO Files.
 
14059
* GCC-source:                            GCC-source.
 
14060
* generate binary message catalog from PO file: msgfmt Invocation.
 
14061
* generate translation catalog in English: msgen Invocation.
 
14062
* gettext files:                         Adjusting Files.
 
14063
* gettext installation:                  Installation.
 
14064
* gettext interface:                     Interface to gettext.
 
14065
* gettext program, usage:                gettext Invocation.
 
14066
* gettext vs catgets:                    Comparison.
 
14067
* gettext, a programmer's view:          gettext.
 
14068
* gettext.h file:                        lib/gettext.h.
 
14069
* gettextize program, usage:             gettextize Invocation.
 
14070
* GUI programs:                          GUI program problems.
 
14071
* hash table, inside MO files:           MO Files.
 
14072
* he, she, and they:                     Introduction.
 
14073
* header entry of a PO file:             Header Entry.
 
14074
* help option:                           Preparing Strings.
 
14075
* history of GNU gettext:                History.
 
14076
* i18n:                                  Concepts.
 
14077
* importing PO files:                    Normalizing.
 
14078
* include file libintl.h <1>:            lib/gettext.h.
 
14079
* include file libintl.h <2>:            Comparison.
 
14080
* include file libintl.h <3>:            Sources.
 
14081
* include file libintl.h:                Overview.
 
14082
* initialization:                        Triggering.
 
14083
* initialize new PO file:                msginit Invocation.
 
14084
* initialize translations from a compendium: Using Compendia.
 
14085
* installing gettext:                    Installation.
 
14086
* interface to catgets:                  Interface to catgets.
 
14087
* internationalization:                  Concepts.
 
14088
* inttypes.h:                            Preparing Strings.
 
14089
* ISO 3166:                              Country Codes.
 
14090
* ISO 639:                               Language Codes.
 
14091
* Java:                                  Java.
 
14092
* Java mode, and msgfmt program:         msgfmt Invocation.
 
14093
* Java mode, and msgunfmt program:       msgunfmt Invocation.
 
14094
* Java, string concatenation:            Preparing Strings.
 
14095
* java-format flag:                      PO Files.
 
14096
* keyboard accelerator checking:         msgfmt Invocation.
 
14097
* l10n:                                  Concepts.
 
14098
* language codes:                        Language Codes.
 
14099
* language selection:                    End Users.
 
14100
* language selection at runtime:         gettext grok.
 
14101
* large package:                         Ambiguities.
 
14102
* libiconv library:                      AM_ICONV.
 
14103
* libintl for C#:                        C#.
 
14104
* libintl for Java:                      Java.
 
14105
* libintl library:                       AM_GNU_GETTEXT.
 
14106
* librep Lisp:                           librep.
 
14107
* librep-format flag:                    PO Files.
 
14108
* LINGUAS file:                          po/LINGUAS.
 
14109
* link with libintl:                     Overview.
 
14110
* Linux <1>:                             Header Entry.
 
14111
* Linux <2>:                             Overview.
 
14112
* Linux:                                 Aspects.
 
14113
* Lisp:                                  Common Lisp.
 
14114
* lisp-format flag:                      PO Files.
 
14115
* list of translation teams, where to find: Header Entry.
 
14116
* locale facet, LC_ALL:                  Triggering.
 
14117
* locale facet, LC_COLLATE:              Triggering.
 
14118
* locale facet, LC_CTYPE <1>:            Triggering.
 
14119
* locale facet, LC_CTYPE:                Aspects.
 
14120
* locale facet, LC_MESSAGES <1>:         Triggering.
 
14121
* locale facet, LC_MESSAGES:             Aspects.
 
14122
* locale facet, LC_MONETARY <1>:         Triggering.
 
14123
* locale facet, LC_MONETARY:             Aspects.
 
14124
* locale facet, LC_NUMERIC <1>:          Triggering.
 
14125
* locale facet, LC_NUMERIC:              Aspects.
 
14126
* locale facet, LC_RESPONSES:            Triggering.
 
14127
* locale facet, LC_TIME <1>:             Triggering.
 
14128
* locale facet, LC_TIME:                 Aspects.
 
14129
* locale facets:                         Aspects.
 
14130
* locale program:                        Header Entry.
 
14131
* localization:                          Concepts.
 
14132
* lookup message translation <1>:        eval_gettext Invocation.
 
14133
* lookup message translation:            gettext Invocation.
 
14134
* lookup plural message translation <1>: eval_ngettext Invocation.
 
14135
* lookup plural message translation:     ngettext Invocation.
 
14136
* magic signature of MO files:           MO Files.
 
14137
* Makevars file:                         po/Makevars.
 
14138
* manipulating PO files:                 Manipulating.
 
14139
* marking Perl sources:                  Perl.
 
14140
* marking string initializers:           Special cases.
 
14141
* marking strings that require translation: Mark Keywords.
 
14142
* marking strings, preparations:         Preparing Strings.
 
14143
* marking translatable strings:          Overview.
 
14144
* menu entries:                          GUI program problems.
 
14145
* menu, keyboard accelerator support:    msgfmt Invocation.
 
14146
* merge PO files:                        msgcat Invocation.
 
14147
* merging two PO files:                  Manipulating.
 
14148
* message catalog files location:        Locating Catalogs.
 
14149
* messages:                              Aspects.
 
14150
* migration from earlier versions of gettext: Prerequisites.
 
14151
* mkinstalldirs file:                    mkinstalldirs.
 
14152
* mnemonics of menu entries:             msgfmt Invocation.
 
14153
* MO file's format:                      MO Files.
 
14154
* modify message attrributes:            msgattrib Invocation.
 
14155
* msgattrib program, usage:              msgattrib Invocation.
 
14156
* msgcat program, usage:                 msgcat Invocation.
 
14157
* msgcmp program, usage:                 msgcmp Invocation.
 
14158
* msgcomm program, usage:                msgcomm Invocation.
 
14159
* msgconv program, usage:                msgconv Invocation.
 
14160
* msgen program, usage:                  msgen Invocation.
 
14161
* msgexec program, usage:                msgexec Invocation.
 
14162
* msgfilter filter and catalog encoding: msgfilter Invocation.
 
14163
* msgfilter program, usage:              msgfilter Invocation.
 
14164
* msgfmt program, usage:                 msgfmt Invocation.
 
14165
* msggrep program, usage:                msggrep Invocation.
 
14166
* msgid:                                 PO Files.
 
14167
* msgid_plural:                          PO Files.
 
14168
* msginit program, usage:                msginit Invocation.
 
14169
* msgmerge program, usage:               msgmerge Invocation.
 
14170
* msgstr:                                PO Files.
 
14171
* msgunfmt program, usage:               msgunfmt Invocation.
 
14172
* msguniq program, usage:                msguniq Invocation.
 
14173
* multi-line strings:                    Normalizing.
 
14174
* N_, a convenience macro:               Comparison.
 
14175
* Native Language Support:               Concepts.
 
14176
* Natural Language Support:              Concepts.
 
14177
* newlines in PO files:                  PO Files.
 
14178
* ngettext:                              Plural forms.
 
14179
* ngettext program, usage:               ngettext Invocation.
 
14180
* NLS:                                   Concepts.
 
14181
* no-awk-format flag:                    PO Files.
 
14182
* no-c-format flag:                      PO Files.
 
14183
* no-c-format, and xgettext:             c-format Flag.
 
14184
* no-csharp-format flag:                 PO Files.
 
14185
* no-elisp-format flag:                  PO Files.
 
14186
* no-gcc-internal-format flag:           PO Files.
 
14187
* no-java-format flag:                   PO Files.
 
14188
* no-librep-format flag:                 PO Files.
 
14189
* no-lisp-format flag:                   PO Files.
 
14190
* no-objc-format flag:                   PO Files.
 
14191
* no-object-pascal-format flag:          PO Files.
 
14192
* no-perl-brace-format flag:             PO Files.
 
14193
* no-perl-format flag:                   PO Files.
 
14194
* no-php-format flag:                    PO Files.
 
14195
* no-python-format flag:                 PO Files.
 
14196
* no-qt-format flag:                     PO Files.
 
14197
* no-sh-format flag:                     PO Files.
 
14198
* no-smalltalk-format flag:              PO Files.
 
14199
* no-tcl-format flag:                    PO Files.
 
14200
* no-ycp-format flag:                    PO Files.
 
14201
* nplurals, in a PO file header:         Plural forms.
 
14202
* number format:                         Aspects.
 
14203
* objc-format flag:                      PO Files.
 
14204
* Object Pascal:                         Pascal.
 
14205
* object-pascal-format flag:             PO Files.
 
14206
* obsolete entries:                      Obsolete Entries.
 
14207
* optimization of gettext functions:     Optimized gettext.
 
14208
* orthography:                           Manipulating.
 
14209
* outdigits:                             c-format.
 
14210
* output to stdout, xgettext:            xgettext Invocation.
 
14211
* overview of gettext:                   Overview.
 
14212
* package and version declaration in configure.in: configure.in.
 
14213
* package build and installation options: Installers.
 
14214
* package maintainer's view of gettext:  Maintainers.
 
14215
* paragraphs:                            Preparing Strings.
 
14216
* Pascal:                                Pascal.
 
14217
* Perl:                                  Perl.
 
14218
* Perl default keywords:                 Default Keywords.
 
14219
* Perl invalid string interpolation:     Interpolation I.
 
14220
* Perl long lines:                       Long Lines.
 
14221
* Perl parentheses:                      Parentheses.
 
14222
* Perl pitfalls:                         Perl Pitfalls.
 
14223
* Perl quote-like expressions:           Quote-like Expressions.
 
14224
* Perl special keywords for hash-lookups: Special Keywords.
 
14225
* Perl valid string interpolation:       Interpolation II.
 
14226
* perl-brace-format flag:                PO Files.
 
14227
* perl-format flag:                      PO Files.
 
14228
* PHP:                                   PHP.
 
14229
* php-format flag:                       PO Files.
 
14230
* Pike:                                  Pike.
 
14231
* plural form formulas:                  Plural forms.
 
14232
* plural forms:                          Plural forms.
 
14233
* plural forms, in MO files:             MO Files.
 
14234
* plural forms, in PO files:             PO Files.
 
14235
* plural, in a PO file header:           Plural forms.
 
14236
* PO files' format:                      PO Files.
 
14237
* PO mode (Emacs) commands:              Main PO Commands.
 
14238
* PO template file:                      Template.
 
14239
* po_file_domains:                       libgettextpo.
 
14240
* po_file_free:                          libgettextpo.
 
14241
* po_file_read:                          libgettextpo.
 
14242
* po_message_iterator:                   libgettextpo.
 
14243
* po_message_iterator_free:              libgettextpo.
 
14244
* po_message_msgid:                      libgettextpo.
 
14245
* po_message_msgid_plural:               libgettextpo.
 
14246
* po_message_msgstr:                     libgettextpo.
 
14247
* po_message_msgstr_plural:              libgettextpo.
 
14248
* po_next_message:                       libgettextpo.
 
14249
* portability problems with sed:         msgfilter Invocation.
 
14250
* POTFILES.in file:                      po/POTFILES.in.
 
14251
* preparing programs for translation:    Sources.
 
14252
* preparing shell scripts for translation: Preparing Shell Scripts.
 
14253
* problems with catgets interface:       Problems with catgets.
 
14254
* programming languages:                 Language Implementors.
 
14255
* Python:                                Python.
 
14256
* python-format flag:                    PO Files.
 
14257
* Qt format strings:                     xgettext Invocation.
 
14258
* Qt mode, and msgfmt program:           msgfmt Invocation.
 
14259
* qt-format flag:                        PO Files.
 
14260
* quotation marks <1>:                   po/Makevars.
 
14261
* quotation marks:                       Header Entry.
 
14262
* quote characters, use in PO files:     Header Entry.
 
14263
* related reading:                       References.
 
14264
* RST:                                   RST.
 
14265
* scripting languages:                   Language Implementors.
 
14266
* search messages in a catalog:          msggrep Invocation.
 
14267
* selecting message language:            End Users.
 
14268
* sentences:                             Preparing Strings.
 
14269
* setting up gettext at build time:      Installers.
 
14270
* setting up gettext at run time:        End Users.
 
14271
* several domains:                       Ambiguities.
 
14272
* sex:                                   Introduction.
 
14273
* sgettext:                              GUI program problems.
 
14274
* sh-format flag:                        PO Files.
 
14275
* she, he, and they:                     Introduction.
 
14276
* shell format string:                   envsubst Invocation.
 
14277
* shell scripts:                         sh.
 
14278
* Smalltalk:                             Smalltalk.
 
14279
* smalltalk-format flag:                 PO Files.
 
14280
* sorting msgcat output:                 msgcat Invocation.
 
14281
* sorting msgmerge output:               msgmerge Invocation.
 
14282
* sorting msgunfmt output:               msgunfmt Invocation.
 
14283
* sorting output of xgettext:            xgettext Invocation.
 
14284
* specifying plural form in a PO file:   Plural forms.
 
14285
* standard output, and msgcat:           msgcat Invocation.
 
14286
* standard output, and msgmerge program: msgmerge Invocation.
 
14287
* string concatenation:                  Preparing Strings.
 
14288
* string normalization in entries:       Normalizing.
 
14289
* style:                                 Preparing Strings.
 
14290
* supported languages, xgettext:         xgettext Invocation.
 
14291
* Tcl:                                   Tcl.
 
14292
* Tcl mode, and msgfmt program:          msgfmt Invocation.
 
14293
* Tcl mode, and msgunfmt program:        msgunfmt Invocation.
 
14294
* tcl-format flag:                       PO Files.
 
14295
* template PO file:                      Overview.
 
14296
* testing .po files for equivalence:     xgettext Invocation.
 
14297
* Tk's scripting language:               Tcl.
 
14298
* translated entries:                    Translated Entries.
 
14299
* translating menu entries:              GUI program problems.
 
14300
* translation aspects:                   Aspects.
 
14301
* Translation Matrix:                    Matrix.
 
14302
* Translation Project:                   Why.
 
14303
* turning off NLS support:               lib/gettext.h.
 
14304
* tutorial of gettext usage:             Overview.
 
14305
* unify duplicate translations:          msguniq Invocation.
 
14306
* untranslated entries:                  Untranslated Entries.
 
14307
* update translations from a compendium: Using Compendia.
 
14308
* upgrading to new versions of gettext:  Prerequisites.
 
14309
* version control for backup files, msgmerge: msgmerge Invocation.
 
14310
* wxWindows library:                     wxWindows.
 
14311
* xargs, and output from msgexec:        msgexec Invocation.
 
14312
* xgettext program, usage:               xgettext Invocation.
 
14313
* xmodmap program, and typing quotation marks: Header Entry.
 
14314
* YaST2 scripting language:              YCP.
 
14315
* YCP:                                   YCP.
 
14316
* ycp-format flag:                       PO Files.
 
14317
 
 
14318
 
 
14319
 
 
14320
Tag Table:
 
14321
Node: Top2663
 
14322
Node: Introduction14898
 
14323
Node: Why16756
 
14324
Ref: Why-Footnote-119860
 
14325
Node: Concepts20016
 
14326
Node: Aspects23426
 
14327
Node: Files29262
 
14328
Node: Overview31160
 
14329
Node: Basics41949
 
14330
Node: Installation42776
 
14331
Node: PO Files44715
 
14332
Ref: PO Files-Footnote-154044
 
14333
Node: Main PO Commands54171
 
14334
Node: Entry Positioning59239
 
14335
Node: Normalizing64692
 
14336
Node: Sources69143
 
14337
Node: Triggering70837
 
14338
Node: Preparing Strings73864
 
14339
Node: Mark Keywords81561
 
14340
Node: Marking85113
 
14341
Node: c-format Flag92832
 
14342
Node: Special cases96740
 
14343
Node: Names99483
 
14344
Node: Libraries103076
 
14345
Node: Template106129
 
14346
Node: xgettext Invocation106846
 
14347
Node: Creating118320
 
14348
Node: msginit Invocation119198
 
14349
Node: Header Entry121756
 
14350
Node: Updating128753
 
14351
Node: msgmerge Invocation129508
 
14352
Node: Translated Entries134445
 
14353
Node: Fuzzy Entries135797
 
14354
Node: Untranslated Entries138963
 
14355
Node: Obsolete Entries140881
 
14356
Node: Modifying Translations144092
 
14357
Node: Modifying Comments152047
 
14358
Node: Subedit156458
 
14359
Node: C Sources Context160338
 
14360
Node: Auxiliary165446
 
14361
Node: Compendium168669
 
14362
Node: Creating Compendia169276
 
14363
Node: Using Compendia171706
 
14364
Node: Manipulating172585
 
14365
Node: msgcat Invocation176344
 
14366
Node: msgconv Invocation180514
 
14367
Node: msggrep Invocation183613
 
14368
Node: msgfilter Invocation188304
 
14369
Node: msguniq Invocation193091
 
14370
Node: msgcomm Invocation196900
 
14371
Node: msgcmp Invocation200865
 
14372
Node: msgattrib Invocation202421
 
14373
Node: msgen Invocation206924
 
14374
Node: msgexec Invocation210191
 
14375
Node: libgettextpo212586
 
14376
Node: Binaries217700
 
14377
Node: msgfmt Invocation218032
 
14378
Node: msgunfmt Invocation224884
 
14379
Node: MO Files228924
 
14380
Node: Users237012
 
14381
Node: Matrix238492
 
14382
Node: Installers239693
 
14383
Node: End Users240860
 
14384
Node: Programmers241505
 
14385
Node: catgets242675
 
14386
Node: Interface to catgets244075
 
14387
Node: Problems with catgets246067
 
14388
Node: gettext246965
 
14389
Node: Interface to gettext248461
 
14390
Node: Ambiguities250804
 
14391
Node: Locating Catalogs253494
 
14392
Ref: Locating Catalogs-Footnote-1254638
 
14393
Ref: Locating Catalogs-Footnote-2254863
 
14394
Node: Charset conversion255012
 
14395
Node: Plural forms257452
 
14396
Ref: Plural forms-Footnote-1268310
 
14397
Node: GUI program problems268402
 
14398
Node: Optimized gettext273503
 
14399
Node: Comparison274833
 
14400
Node: Using libintl.a279100
 
14401
Node: gettext grok279530
 
14402
Node: Temp Programmers282077
 
14403
Node: Temp Implementations282517
 
14404
Node: Temp catgets283880
 
14405
Node: Temp WSI285564
 
14406
Node: Temp Notes287549
 
14407
Node: Translators288035
 
14408
Node: Trans Intro 0288492
 
14409
Node: Trans Intro 1291138
 
14410
Node: Discussions292999
 
14411
Node: Organization296566
 
14412
Node: Central Coordination298544
 
14413
Node: National Teams299669
 
14414
Node: Sub-Cultures302179
 
14415
Node: Organizational Ideas303095
 
14416
Node: Mailing Lists304095
 
14417
Node: Information Flow305895
 
14418
Node: Prioritizing messages308055
 
14419
Node: Maintainers312316
 
14420
Node: Flat and Non-Flat314210
 
14421
Node: Prerequisites315690
 
14422
Node: gettextize Invocation319827
 
14423
Node: Adjusting Files326531
 
14424
Node: po/POTFILES.in328252
 
14425
Node: po/LINGUAS329494
 
14426
Node: po/Makevars331169
 
14427
Node: configure.in332760
 
14428
Node: config.guess334847
 
14429
Node: mkinstalldirs335961
 
14430
Node: aclocal336719
 
14431
Node: acconfig338485
 
14432
Node: config.h.in338968
 
14433
Node: Makefile340122
 
14434
Node: src/Makefile342700
 
14435
Node: lib/gettext.h345713
 
14436
Node: autoconf macros347943
 
14437
Node: AM_GNU_GETTEXT348567
 
14438
Node: AM_GNU_GETTEXT_VERSION352147
 
14439
Node: AM_PO_SUBDIRS352579
 
14440
Node: AM_ICONV353343
 
14441
Node: CVS Issues355536
 
14442
Node: Distributed CVS356087
 
14443
Node: Files under CVS357998
 
14444
Node: autopoint Invocation360550
 
14445
Node: Programming Languages362344
 
14446
Node: Language Implementors363162
 
14447
Node: Programmers for other Languages367941
 
14448
Node: Translators for other Languages368504
 
14449
Node: c-format369913
 
14450
Node: objc-format371613
 
14451
Node: sh-format371951
 
14452
Node: python-format372739
 
14453
Node: lisp-format373163
 
14454
Node: elisp-format373475
 
14455
Node: librep-format373951
 
14456
Node: smalltalk-format374340
 
14457
Node: java-format374826
 
14458
Node: csharp-format375258
 
14459
Node: awk-format375617
 
14460
Node: object-pascal-format375926
 
14461
Node: ycp-format376139
 
14462
Node: tcl-format376522
 
14463
Node: perl-format376801
 
14464
Node: php-format377530
 
14465
Node: gcc-internal-format377879
 
14466
Node: qt-format378905
 
14467
Node: Maintainers for other Languages379302
 
14468
Node: List of Programming Languages380527
 
14469
Node: C381749
 
14470
Node: sh383012
 
14471
Node: Preparing Shell Scripts384272
 
14472
Node: gettext.sh386670
 
14473
Node: gettext Invocation387199
 
14474
Node: ngettext Invocation388922
 
14475
Node: envsubst Invocation390478
 
14476
Node: eval_gettext Invocation391881
 
14477
Node: eval_ngettext Invocation392324
 
14478
Node: bash392820
 
14479
Node: Python394782
 
14480
Node: Common Lisp395977
 
14481
Node: clisp C396763
 
14482
Node: Emacs Lisp397464
 
14483
Node: librep398176
 
14484
Node: Smalltalk398900
 
14485
Node: Java399918
 
14486
Node: C#404921
 
14487
Node: gawk413323
 
14488
Node: Pascal414219
 
14489
Node: wxWindows415511
 
14490
Node: YCP416245
 
14491
Node: Tcl416968
 
14492
Node: Perl418362
 
14493
Node: General Problems421354
 
14494
Node: Default Keywords425012
 
14495
Node: Special Keywords425944
 
14496
Node: Quote-like Expressions427438
 
14497
Node: Interpolation I429703
 
14498
Node: Interpolation II433473
 
14499
Node: Parentheses435818
 
14500
Node: Long Lines437330
 
14501
Node: Perl Pitfalls439157
 
14502
Node: PHP443379
 
14503
Node: Pike444294
 
14504
Node: GCC-source444939
 
14505
Node: List of Data Formats445670
 
14506
Node: POT446126
 
14507
Node: RST446370
 
14508
Node: Glade446582
 
14509
Node: Conclusion446928
 
14510
Node: History447425
 
14511
Node: References451681
 
14512
Node: Language Codes453233
 
14513
Node: Country Codes457557
 
14514
Node: Program Index463292
 
14515
Node: Option Index464747
 
14516
Node: Variable Index498022
 
14517
Node: PO Mode Index499101
 
14518
Node: Autoconf Macro Index508459
 
14519
Node: Index508838
 
14520
 
 
14521
End Tag Table