1 This is gettext.info, produced by makeinfo version 4.13 from
4 INFO-DIR-SECTION GNU Gettext Utilities
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.
30 This file provides documentation for GNU `gettext' utilities. It
31 also serves as a reference for the free Translation Project.
33 Copyright (C) 1995-1998, 2001-2007 Free Software Foundation, Inc.
35 This manual is free documentation. It is dually licensed under the
36 GNU FDL and the GNU GPL. This means that you can redistribute this
37 manual under either of these two licenses, at your choice.
39 This manual is covered by the GNU FDL. Permission is granted to
40 copy, distribute and/or modify this document under the terms of the GNU
41 Free Documentation License (FDL), either version 1.2 of the License, or
42 (at your option) any later version published by the Free Software
43 Foundation (FSF); with no Invariant Sections, with no Front-Cover Text,
44 and with no Back-Cover Texts. A copy of the license is included in
47 This manual is covered by the GNU GPL. You can redistribute it
48 and/or modify it under the terms of the GNU General Public License
49 (GPL), either version 2 of the License, or (at your option) any later
50 version published by the Free Software Foundation (FSF). A copy of the
51 license is included in *note GNU GPL::.
54 File: gettext.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir)
56 GNU `gettext' utilities
57 ***********************
59 This manual documents the GNU gettext tools and the GNU libintl
60 library, version 0.18.1.
64 * Introduction:: Introduction
65 * Users:: The User's View
66 * PO Files:: The Format of PO Files
67 * Sources:: Preparing Program Sources
68 * Template:: Making the PO Template File
69 * Creating:: Creating a New PO File
70 * Updating:: Updating Existing PO Files
71 * Editing:: Editing PO Files
72 * Manipulating:: Manipulating PO Files
73 * Binaries:: Producing Binary MO Files
74 * Programmers:: The Programmer's View
75 * Translators:: The Translator's View
76 * Maintainers:: The Maintainer's View
77 * Installers:: The Installer's and Distributor's View
78 * Programming Languages:: Other Programming Languages
79 * Conclusion:: Concluding Remarks
81 * Language Codes:: ISO 639 language codes
82 * Country Codes:: ISO 3166 country codes
85 * Program Index:: Index of Programs
86 * Option Index:: Index of Command-Line Options
87 * Variable Index:: Index of Environment Variables
88 * PO Mode Index:: Index of Emacs PO Mode Commands
89 * Autoconf Macro Index:: Index of Autoconf Macros
90 * Index:: General Index
92 --- The Detailed Node Listing ---
96 * Why:: The Purpose of GNU `gettext'
97 * Concepts:: I18n, L10n, and Such
98 * Aspects:: Aspects in Native Language Support
99 * Files:: Files Conveying Translations
100 * Overview:: Overview of GNU `gettext'
104 * System Installation:: Questions During Operating System Installation
105 * Setting the GUI Locale:: How to Specify the Locale Used by GUI Programs
106 * Setting the POSIX Locale:: How to Specify the Locale According to POSIX
107 * Installing Localizations:: How to Install Additional Translations
109 Setting the POSIX Locale
111 * Locale Names:: How a Locale Specification Looks Like
112 * Locale Environment Variables:: Which Environment Variable Specfies What
113 * The LANGUAGE variable:: How to Specify a Priority List of Languages
115 Preparing Program Sources
117 * Importing:: Importing the `gettext' declaration
118 * Triggering:: Triggering `gettext' Operations
119 * Preparing Strings:: Preparing Translatable Strings
120 * Mark Keywords:: How Marks Appear in Sources
121 * Marking:: Marking Translatable Strings
122 * c-format Flag:: Telling something about the following string
123 * Special cases:: Special Cases of Translatable Strings
124 * Bug Report Address:: Letting Users Report Translation Bugs
125 * Names:: Marking Proper Names for Translation
126 * Libraries:: Preparing Library Sources
128 Making the PO Template File
130 * xgettext Invocation:: Invoking the `xgettext' Program
132 Creating a New PO File
134 * msginit Invocation:: Invoking the `msginit' Program
135 * Header Entry:: Filling in the Header Entry
137 Updating Existing PO Files
139 * msgmerge Invocation:: Invoking the `msgmerge' Program
143 * KBabel:: KDE's PO File Editor
144 * Gtranslator:: GNOME's PO File Editor
145 * PO Mode:: Emacs's PO File Editor
146 * Compendium:: Using Translation Compendia
148 Emacs's PO File Editor
150 * Installation:: Completing GNU `gettext' Installation
151 * Main PO Commands:: Main Commands
152 * Entry Positioning:: Entry Positioning
153 * Normalizing:: Normalizing Strings in Entries
154 * Translated Entries:: Translated Entries
155 * Fuzzy Entries:: Fuzzy Entries
156 * Untranslated Entries:: Untranslated Entries
157 * Obsolete Entries:: Obsolete Entries
158 * Modifying Translations:: Modifying Translations
159 * Modifying Comments:: Modifying Comments
160 * Subedit:: Mode for Editing Translations
161 * C Sources Context:: C Sources Context
162 * Auxiliary:: Consulting Auxiliary PO Files
164 Using Translation Compendia
166 * Creating Compendia:: Merging translations for later use
167 * Using Compendia:: Using older translations if they fit
169 Manipulating PO Files
171 * msgcat Invocation:: Invoking the `msgcat' Program
172 * msgconv Invocation:: Invoking the `msgconv' Program
173 * msggrep Invocation:: Invoking the `msggrep' Program
174 * msgfilter Invocation:: Invoking the `msgfilter' Program
175 * msguniq Invocation:: Invoking the `msguniq' Program
176 * msgcomm Invocation:: Invoking the `msgcomm' Program
177 * msgcmp Invocation:: Invoking the `msgcmp' Program
178 * msgattrib Invocation:: Invoking the `msgattrib' Program
179 * msgen Invocation:: Invoking the `msgen' Program
180 * msgexec Invocation:: Invoking the `msgexec' Program
181 * Colorizing:: Highlighting parts of PO files
182 * libgettextpo:: Writing your own programs that process PO files
184 Highlighting parts of PO files
186 * The --color option:: Triggering colorized output
187 * The TERM variable:: The environment variable `TERM'
188 * The --style option:: The `--style' option
189 * Style rules:: Style rules for PO files
190 * Customizing less:: Customizing `less' for viewing PO files
192 Producing Binary MO Files
194 * msgfmt Invocation:: Invoking the `msgfmt' Program
195 * msgunfmt Invocation:: Invoking the `msgunfmt' Program
196 * MO Files:: The Format of GNU MO Files
198 The Programmer's View
200 * catgets:: About `catgets'
201 * gettext:: About `gettext'
202 * Comparison:: Comparing the two interfaces
203 * Using libintl.a:: Using libintl.a in own programs
204 * gettext grok:: Being a `gettext' grok
205 * Temp Programmers:: Temporary Notes for the Programmers Chapter
209 * Interface to catgets:: The interface
210 * Problems with catgets:: Problems with the `catgets' interface?!
214 * Interface to gettext:: The interface
215 * Ambiguities:: Solving ambiguities
216 * Locating Catalogs:: Locating message catalog files
217 * Charset conversion:: How to request conversion to Unicode
218 * Contexts:: Solving ambiguities in GUI programs
219 * Plural forms:: Additional functions for handling plurals
220 * Optimized gettext:: Optimization of the *gettext functions
222 Temporary Notes for the Programmers Chapter
224 * Temp Implementations:: Temporary - Two Possible Implementations
225 * Temp catgets:: Temporary - About `catgets'
226 * Temp WSI:: Temporary - Why a single implementation
227 * Temp Notes:: Temporary - Notes
229 The Translator's View
231 * Trans Intro 0:: Introduction 0
232 * Trans Intro 1:: Introduction 1
233 * Discussions:: Discussions
234 * Organization:: Organization
235 * Information Flow:: Information Flow
236 * Translating plural forms:: How to fill in `msgstr[0]', `msgstr[1]'
237 * Prioritizing messages:: How to find which messages to translate first
241 * Central Coordination:: Central Coordination
242 * National Teams:: National Teams
243 * Mailing Lists:: Mailing Lists
247 * Sub-Cultures:: Sub-Cultures
248 * Organizational Ideas:: Organizational Ideas
250 The Maintainer's View
252 * Flat and Non-Flat:: Flat or Non-Flat Directory Structures
253 * Prerequisites:: Prerequisite Works
254 * gettextize Invocation:: Invoking the `gettextize' Program
255 * Adjusting Files:: Files You Must Create or Alter
256 * autoconf macros:: Autoconf macros for use in `configure.ac'
257 * CVS Issues:: Integrating with CVS
258 * Release Management:: Creating a Distribution Tarball
260 Files You Must Create or Alter
262 * po/POTFILES.in:: `POTFILES.in' in `po/'
263 * po/LINGUAS:: `LINGUAS' in `po/'
264 * po/Makevars:: `Makevars' in `po/'
265 * po/Rules-*:: Extending `Makefile' in `po/'
266 * configure.ac:: `configure.ac' at top level
267 * config.guess:: `config.guess', `config.sub' at top level
268 * mkinstalldirs:: `mkinstalldirs' at top level
269 * aclocal:: `aclocal.m4' at top level
270 * acconfig:: `acconfig.h' at top level
271 * config.h.in:: `config.h.in' at top level
272 * Makefile:: `Makefile.in' at top level
273 * src/Makefile:: `Makefile.in' in `src/'
274 * lib/gettext.h:: `gettext.h' in `lib/'
276 Autoconf macros for use in `configure.ac'
278 * AM_GNU_GETTEXT:: AM_GNU_GETTEXT in `gettext.m4'
279 * AM_GNU_GETTEXT_VERSION:: AM_GNU_GETTEXT_VERSION in `gettext.m4'
280 * AM_GNU_GETTEXT_NEED:: AM_GNU_GETTEXT_NEED in `gettext.m4'
281 * AM_GNU_GETTEXT_INTL_SUBDIR:: AM_GNU_GETTEXT_INTL_SUBDIR in `intldir.m4'
282 * AM_PO_SUBDIRS:: AM_PO_SUBDIRS in `po.m4'
283 * AM_ICONV:: AM_ICONV in `iconv.m4'
287 * Distributed CVS:: Avoiding version mismatch in distributed development
288 * Files under CVS:: Files to put under CVS version control
289 * autopoint Invocation:: Invoking the `autopoint' Program
291 Other Programming Languages
293 * Language Implementors:: The Language Implementor's View
294 * Programmers for other Languages:: The Programmer's View
295 * Translators for other Languages:: The Translator's View
296 * Maintainers for other Languages:: The Maintainer's View
297 * List of Programming Languages:: Individual Programming Languages
298 * List of Data Formats:: Internationalizable Data
300 The Translator's View
302 * c-format:: C Format Strings
303 * objc-format:: Objective C Format Strings
304 * sh-format:: Shell Format Strings
305 * python-format:: Python Format Strings
306 * lisp-format:: Lisp Format Strings
307 * elisp-format:: Emacs Lisp Format Strings
308 * librep-format:: librep Format Strings
309 * scheme-format:: Scheme Format Strings
310 * smalltalk-format:: Smalltalk Format Strings
311 * java-format:: Java Format Strings
312 * csharp-format:: C# Format Strings
313 * awk-format:: awk Format Strings
314 * object-pascal-format:: Object Pascal Format Strings
315 * ycp-format:: YCP Format Strings
316 * tcl-format:: Tcl Format Strings
317 * perl-format:: Perl Format Strings
318 * php-format:: PHP Format Strings
319 * gcc-internal-format:: GCC internal Format Strings
320 * gfc-internal-format:: GFC internal Format Strings
321 * qt-format:: Qt Format Strings
322 * qt-plural-format:: Qt Plural Format Strings
323 * kde-format:: KDE Format Strings
324 * boost-format:: Boost Format Strings
326 Individual Programming Languages
328 * C:: C, C++, Objective C
329 * sh:: sh - Shell Script
330 * bash:: bash - Bourne-Again Shell Script
332 * Common Lisp:: GNU clisp - Common Lisp
333 * clisp C:: GNU clisp C sources
334 * Emacs Lisp:: Emacs Lisp
336 * Scheme:: GNU guile - Scheme
337 * Smalltalk:: GNU Smalltalk
341 * Pascal:: Pascal - Free Pascal Compiler
342 * wxWidgets:: wxWidgets library
343 * YCP:: YCP - YaST2 scripting language
344 * Tcl:: Tcl - Tk's scripting language
346 * PHP:: PHP Hypertext Preprocessor
348 * GCC-source:: GNU Compiler Collection sources
352 * Preparing Shell Scripts:: Preparing Shell Scripts for Internationalization
353 * gettext.sh:: Contents of `gettext.sh'
354 * gettext Invocation:: Invoking the `gettext' program
355 * ngettext Invocation:: Invoking the `ngettext' program
356 * envsubst Invocation:: Invoking the `envsubst' program
357 * eval_gettext Invocation:: Invoking the `eval_gettext' function
358 * eval_ngettext Invocation:: Invoking the `eval_ngettext' function
362 * General Problems:: General Problems Parsing Perl Code
363 * Default Keywords:: Which Keywords Will xgettext Look For?
364 * Special Keywords:: How to Extract Hash Keys
365 * Quote-like Expressions:: What are Strings And Quote-like Expressions?
366 * Interpolation I:: Invalid String Interpolation
367 * Interpolation II:: Valid String Interpolation
368 * Parentheses:: When To Use Parentheses
369 * Long Lines:: How To Grok with Long Lines
370 * Perl Pitfalls:: Bugs, Pitfalls, and Things That Do Not Work
372 Internationalizable Data
374 * POT:: POT - Portable Object Template
375 * RST:: Resource String Table
376 * Glade:: Glade - GNOME user interface description
380 * History:: History of GNU `gettext'
381 * References:: Related Readings
385 * Usual Language Codes:: Two-letter ISO 639 language codes
386 * Rare Language Codes:: Three-letter ISO 639 language codes
390 * GNU GPL:: GNU General Public License
391 * GNU LGPL:: GNU Lesser General Public License
392 * GNU FDL:: GNU Free Documentation License
395 File: gettext.info, Node: Introduction, Next: Users, Prev: Top, Up: Top
400 This chapter explains the goals sought in the creation of GNU
401 `gettext' and the free Translation Project. Then, it explains a few
402 broad concepts around Native Language Support, and positions message
403 translation with regard to other aspects of national and cultural
404 variance, as they apply to programs. It also surveys those files used
405 to convey the translations. It explains how the various tools interact
406 in the initial generation of these files, and later, how the maintenance
407 cycle should usually operate.
409 In this manual, we use _he_ when speaking of the programmer or
410 maintainer, _she_ when speaking of the translator, and _they_ when
411 speaking of the installers or end users of the translated program.
412 This is only a convenience for clarifying the documentation. It is
413 _absolutely_ not meant to imply that some roles are more appropriate to
414 males or females. Besides, as you might guess, GNU `gettext' is meant
415 to be useful for people using computers, whatever their sex, race,
416 religion or nationality!
418 Please send suggestions and corrections to:
421 bug-gnu-gettext@gnu.org
423 Please include the manual's edition number and update date in your
428 * Why:: The Purpose of GNU `gettext'
429 * Concepts:: I18n, L10n, and Such
430 * Aspects:: Aspects in Native Language Support
431 * Files:: Files Conveying Translations
432 * Overview:: Overview of GNU `gettext'
435 File: gettext.info, Node: Why, Next: Concepts, Prev: Introduction, Up: Introduction
437 1.1 The Purpose of GNU `gettext'
438 ================================
440 Usually, programs are written and documented in English, and use
441 English at execution time to interact with users. This is true not
442 only of GNU software, but also of a great deal of proprietary and free
443 software. Using a common language is quite handy for communication
444 between developers, maintainers and users from all countries. On the
445 other hand, most people are less comfortable with English than with
446 their own native language, and would prefer to use their mother tongue
447 for day to day's work, as far as possible. Many would simply _love_ to
448 see their computer screen showing a lot less of English, and far more
449 of their own language.
451 However, to many people, this dream might appear so far fetched that
452 they may believe it is not even worth spending time thinking about it.
453 They have no confidence at all that the dream might ever become true.
454 Yet some have not lost hope, and have organized themselves. The
455 Translation Project is a formalization of this hope into a workable
456 structure, which has a good chance to get all of us nearer the
457 achievement of a truly multi-lingual set of programs.
459 GNU `gettext' is an important step for the Translation Project, as
460 it is an asset on which we may build many other steps. This package
461 offers to programmers, translators and even users, a well integrated
462 set of tools and documentation. Specifically, the GNU `gettext'
463 utilities are a set of tools that provides a framework within which
464 other free packages may produce multi-lingual messages. These tools
467 * A set of conventions about how programs should be written to
468 support message catalogs.
470 * A directory and file naming organization for the message catalogs
473 * A runtime library supporting the retrieval of translated messages.
475 * A few stand-alone programs to massage in various ways the sets of
476 translatable strings, or already translated strings.
478 * A library supporting the parsing and creation of files containing
481 * A special mode for Emacs(1) which helps preparing these sets and
482 bringing them up to date.
484 GNU `gettext' is designed to minimize the impact of
485 internationalization on program sources, keeping this impact as small
486 and hardly noticeable as possible. Internationalization has better
487 chances of succeeding if it is very light weighted, or at least, appear
488 to be so, when looking at program sources.
490 The Translation Project also uses the GNU `gettext' distribution as
491 a vehicle for documenting its structure and methods. This goes beyond
492 the strict technicalities of documenting the GNU `gettext' proper. By
493 so doing, translators will find in a single place, as far as possible,
494 all they need to know for properly doing their translating work. Also,
495 this supplemental documentation might also help programmers, and even
496 curious users, in understanding how GNU `gettext' is related to the
497 remainder of the Translation Project, and consequently, have a glimpse
498 at the _big picture_.
500 ---------- Footnotes ----------
502 (1) In this manual, all mentions of Emacs refers to either GNU Emacs
503 or to XEmacs, which people sometimes call FSF Emacs and Lucid Emacs,
507 File: gettext.info, Node: Concepts, Next: Aspects, Prev: Why, Up: Introduction
509 1.2 I18n, L10n, and Such
510 ========================
512 Two long words appear all the time when we discuss support of native
513 language in programs, and these words have a precise meaning, worth
514 being explained here, once and for all in this document. The words are
515 _internationalization_ and _localization_. Many people, tired of
516 writing these long words over and over again, took the habit of writing
517 "i18n" and "l10n" instead, quoting the first and last letter of each
518 word, and replacing the run of intermediate letters by a number merely
519 telling how many such letters there are. But in this manual, in the
520 sake of clarity, we will patiently write the names in full, each time...
522 By "internationalization", one refers to the operation by which a
523 program, or a set of programs turned into a package, is made aware of
524 and able to support multiple languages. This is a generalization
525 process, by which the programs are untied from calling only English
526 strings or other English specific habits, and connected to generic ways
527 of doing the same, instead. Program developers may use various
528 techniques to internationalize their programs. Some of these have been
529 standardized. GNU `gettext' offers one of these standards. *Note
532 By "localization", one means the operation by which, in a set of
533 programs already internationalized, one gives the program all needed
534 information so that it can adapt itself to handle its input and output
535 in a fashion which is correct for some native language and cultural
536 habits. This is a particularisation process, by which generic methods
537 already implemented in an internationalized program are used in
538 specific ways. The programming environment puts several functions to
539 the programmers disposal which allow this runtime configuration. The
540 formal description of specific set of cultural habits for some country,
541 together with all associated translations targeted to the same native
542 language, is called the "locale" for this language or country. Users
543 achieve localization of programs by setting proper values to special
544 environment variables, prior to executing those programs, identifying
545 which locale should be used.
547 In fact, locale message support is only one component of the cultural
548 data that makes up a particular locale. There are a whole host of
549 routines and functions provided to aid programmers in developing
550 internationalized software and which allow them to access the data
551 stored in a particular locale. When someone presently refers to a
552 particular locale, they are obviously referring to the data stored
553 within that particular locale. Similarly, if a programmer is referring
554 to "accessing the locale routines", they are referring to the complete
555 suite of routines that access all of the locale's information.
557 One uses the expression "Native Language Support", or merely NLS,
558 for speaking of the overall activity or feature encompassing both
559 internationalization and localization, allowing for multi-lingual
560 interactions in a program. In a nutshell, one could say that
561 internationalization is the operation by which further localizations
564 Also, very roughly said, when it comes to multi-lingual messages,
565 internationalization is usually taken care of by programmers, and
566 localization is usually taken care of by translators.
569 File: gettext.info, Node: Aspects, Next: Files, Prev: Concepts, Up: Introduction
571 1.3 Aspects in Native Language Support
572 ======================================
574 For a totally multi-lingual distribution, there are many things to
575 translate beyond output messages.
577 * As of today, GNU `gettext' offers a complete toolset for
578 translating messages output by C programs. Perl scripts and shell
579 scripts will also need to be translated. Even if there are today
580 some hooks by which this can be done, these hooks are not
581 integrated as well as they should be.
583 * Some programs, like `autoconf' or `bison', are able to produce
584 other programs (or scripts). Even if the generating programs
585 themselves are internationalized, the generated programs they
586 produce may need internationalization on their own, and this
587 indirect internationalization could be automated right from the
588 generating program. In fact, quite usually, generating and
589 generated programs could be internationalized independently, as
590 the effort needed is fairly orthogonal.
592 * A few programs include textual tables which might need translation
593 themselves, independently of the strings contained in the program
594 itself. For example, RFC 1345 gives an English description for
595 each character which the `recode' program is able to reconstruct
596 at execution. Since these descriptions are extracted from the RFC
597 by mechanical means, translating them properly would require a
598 prior translation of the RFC itself.
600 * Almost all programs accept options, which are often worded out so
601 to be descriptive for the English readers; one might want to
602 consider offering translated versions for program options as well.
604 * Many programs read, interpret, compile, or are somewhat driven by
605 input files which are texts containing keywords, identifiers, or
606 replies which are inherently translatable. For example, one may
607 want `gcc' to allow diacriticized characters in identifiers or use
608 translated keywords; `rm -i' might accept something else than `y'
609 or `n' for replies, etc. Even if the program will eventually make
610 most of its output in the foreign languages, one has to decide
611 whether the input syntax, option values, etc., are to be localized
614 * The manual accompanying a package, as well as all documentation
615 files in the distribution, could surely be translated, too.
616 Translating a manual, with the intent of later keeping up with
617 updates, is a major undertaking in itself, generally.
620 As we already stressed, translation is only one aspect of locales.
621 Other internationalization aspects are system services and are handled
622 in GNU `libc'. There are many attributes that are needed to define a
623 country's cultural conventions. These attributes include beside the
624 country's native language, the formatting of the date and time, the
625 representation of numbers, the symbols for currency, etc. These local
626 "rules" are termed the country's locale. The locale represents the
627 knowledge needed to support the country's native attributes.
629 There are a few major areas which may vary between countries and
630 hence, define what a locale must describe. The following list helps
631 putting multi-lingual messages into the proper context of other tasks
632 related to locales. See the GNU `libc' manual for details.
634 _Characters and Codesets_
635 The codeset most commonly used through out the USA and most English
636 speaking parts of the world is the ASCII codeset. However, there
637 are many characters needed by various locales that are not found
638 within this codeset. The 8-bit ISO 8859-1 code set has most of
639 the special characters needed to handle the major European
640 languages. However, in many cases, choosing ISO 8859-1 is
641 nevertheless not adequate: it doesn't even handle the major
642 European currency. Hence each locale will need to specify which
643 codeset they need to use and will need to have the appropriate
644 character handling routines to cope with the codeset.
647 The symbols used vary from country to country as does the position
648 used by the symbol. Software needs to be able to transparently
649 display currency figures in the native mode for each locale.
652 The format of date varies between locales. For example, Christmas
653 day in 1994 is written as 12/25/94 in the USA and as 25/12/94 in
654 Australia. Other countries might use ISO 8601 dates, etc.
656 Time of the day may be noted as HH:MM, HH.MM, or otherwise. Some
657 locales require time to be specified in 24-hour mode rather than
658 as AM or PM. Further, the nature and yearly extent of the
659 Daylight Saving correction vary widely between countries.
662 Numbers can be represented differently in different locales. For
663 example, the following numbers are all written correctly for their
671 Some programs could go further and use different unit systems, like
672 English units or Metric units, or even take into account variants
673 about how numbers are spelled in full.
676 The most obvious area is the language support within a locale.
677 This is where GNU `gettext' provides the means for developers and
678 users to easily change the language that the software uses to
679 communicate to the user.
682 These areas of cultural conventions are called _locale categories_.
683 It is an unfortunate term; _locale aspects_ or _locale feature
684 categories_ would be a better term, because each "locale category"
685 describes an area or task that requires localization. The concrete data
686 that describes the cultural conventions for such an area and for a
687 particular culture is also called a _locale category_. In this sense,
688 a locale is composed of several locale categories: the locale category
689 describing the codeset, the locale category describing the formatting
690 of numbers, the locale category containing the translated messages, and
693 Components of locale outside of message handling are standardized in
694 the ISO C standard and the POSIX:2001 standard (also known as the SUSV3
695 specification). GNU `libc' fully implements this, and most other
696 modern systems provide a more or less reasonable support for at least
697 some of the missing components.
700 File: gettext.info, Node: Files, Next: Overview, Prev: Aspects, Up: Introduction
702 1.4 Files Conveying Translations
703 ================================
705 The letters PO in `.po' files means Portable Object, to distinguish
706 it from `.mo' files, where MO stands for Machine Object. This
707 paradigm, as well as the PO file format, is inspired by the NLS
708 standard developed by Uniforum, and first implemented by Sun in their
711 PO files are meant to be read and edited by humans, and associate
712 each original, translatable string of a given package with its
713 translation in a particular target language. A single PO file is
714 dedicated to a single target language. If a package supports many
715 languages, there is one such PO file per language supported, and each
716 package has its own set of PO files. These PO files are best created by
717 the `xgettext' program, and later updated or refreshed through the
718 `msgmerge' program. Program `xgettext' extracts all marked messages
719 from a set of C files and initializes a PO file with empty
720 translations. Program `msgmerge' takes care of adjusting PO files
721 between releases of the corresponding sources, commenting obsolete
722 entries, initializing new ones, and updating all source line
723 references. Files ending with `.pot' are kind of base translation
724 files found in distributions, in PO file format.
726 MO files are meant to be read by programs, and are binary in nature.
727 A few systems already offer tools for creating and handling MO files as
728 part of the Native Language Support coming with the system, but the
729 format of these MO files is often different from system to system, and
730 non-portable. The tools already provided with these systems don't
731 support all the features of GNU `gettext'. Therefore GNU `gettext'
732 uses its own format for MO files. Files ending with `.gmo' are really
733 MO files, when it is known that these files use the GNU format.
736 File: gettext.info, Node: Overview, Prev: Files, Up: Introduction
738 1.5 Overview of GNU `gettext'
739 =============================
741 The following diagram summarizes the relation between the files
742 handled by GNU `gettext' and the tools acting on these files. It is
743 followed by somewhat detailed explanations, which you should read while
744 keeping an eye on the diagram. Having a clear understanding of these
745 interrelations will surely help programmers, translators and
748 Original C Sources ---> Preparation ---> Marked C Sources ---.
750 .---------<--- GNU gettext Library |
752 | `---------<--------------------+---------------'
754 | .-----<--- PACKAGE.pot <--- xgettext <---' .---<--- PO Compendium
757 | `---. +---> PO editor ---.
758 | +----> msgmerge ------> LANG.po ---->--------' |
761 | `-------------<---------------. |
762 | +--- New LANG.po <--------------------'
763 | .--- LANG.gmo <--- msgfmt <---'
765 | `---> install ---> /.../LANG/PACKAGE.mo ---.
766 | +---> "Hello world!"
767 `-------> install ---> /.../bin/PROGRAM -------'
769 As a programmer, the first step to bringing GNU `gettext' into your
770 package is identifying, right in the C sources, those strings which are
771 meant to be translatable, and those which are untranslatable. This
772 tedious job can be done a little more comfortably using emacs PO mode,
773 but you can use any means familiar to you for modifying your C sources.
774 Beside this some other simple, standard changes are needed to properly
775 initialize the translation library. *Note Sources::, for more
776 information about all this.
778 For newly written software the strings of course can and should be
779 marked while writing it. The `gettext' approach makes this very easy.
780 Simply put the following lines at the beginning of each file or in a
783 #define _(String) (String)
784 #define N_(String) String
785 #define textdomain(Domain)
786 #define bindtextdomain(Package, Directory)
788 Doing this allows you to prepare the sources for internationalization.
789 Later when you feel ready for the step to use the `gettext' library
790 simply replace these definitions by the following:
793 #define _(String) gettext (String)
794 #define gettext_noop(String) String
795 #define N_(String) gettext_noop (String)
797 and link against `libintl.a' or `libintl.so'. Note that on GNU
798 systems, you don't need to link with `libintl' because the `gettext'
799 library functions are already contained in GNU libc. That is all you
802 Once the C sources have been modified, the `xgettext' program is
803 used to find and extract all translatable strings, and create a PO
804 template file out of all these. This `PACKAGE.pot' file contains all
805 original program strings. It has sets of pointers to exactly where in
806 C sources each string is used. All translations are set to empty. The
807 letter `t' in `.pot' marks this as a Template PO file, not yet oriented
808 towards any particular language. *Note xgettext Invocation::, for more
809 details about how one calls the `xgettext' program. If you are
810 _really_ lazy, you might be interested at working a lot more right
811 away, and preparing the whole distribution setup (*note Maintainers::).
812 By doing so, you spare yourself typing the `xgettext' command, as `make'
813 should now generate the proper things automatically for you!
815 The first time through, there is no `LANG.po' yet, so the `msgmerge'
816 step may be skipped and replaced by a mere copy of `PACKAGE.pot' to
817 `LANG.po', where LANG represents the target language. See *note
818 Creating:: for details.
820 Then comes the initial translation of messages. Translation in
821 itself is a whole matter, still exclusively meant for humans, and whose
822 complexity far overwhelms the level of this manual. Nevertheless, a
823 few hints are given in some other chapter of this manual (*note
824 Translators::). You will also find there indications about how to
825 contact translating teams, or becoming part of them, for sharing your
826 translating concerns with others who target the same native language.
828 While adding the translated messages into the `LANG.po' PO file, if
829 you are not using one of the dedicated PO file editors (*note
830 Editing::), you are on your own for ensuring that your efforts fully
831 respect the PO file format, and quoting conventions (*note PO Files::).
832 This is surely not an impossible task, as this is the way many people
833 have handled PO files around 1995. On the other hand, by using a PO
834 file editor, most details of PO file format are taken care of for you,
835 but you have to acquire some familiarity with PO file editor itself.
837 If some common translations have already been saved into a compendium
838 PO file, translators may use PO mode for initializing untranslated
839 entries from the compendium, and also save selected translations into
840 the compendium, updating it (*note Compendium::). Compendium files are
841 meant to be exchanged between members of a given translation team.
843 Programs, or packages of programs, are dynamic in nature: users write
844 bug reports and suggestion for improvements, maintainers react by
845 modifying programs in various ways. The fact that a package has
846 already been internationalized should not make maintainers shy of
847 adding new strings, or modifying strings already translated. They just
848 do their job the best they can. For the Translation Project to work
849 smoothly, it is important that maintainers do not carry translation
850 concerns on their already loaded shoulders, and that translators be
851 kept as free as possible of programming concerns.
853 The only concern maintainers should have is carefully marking new
854 strings as translatable, when they should be, and do not otherwise
855 worry about them being translated, as this will come in proper time.
856 Consequently, when programs and their strings are adjusted in various
857 ways by maintainers, and for matters usually unrelated to translation,
858 `xgettext' would construct `PACKAGE.pot' files which are evolving over
859 time, so the translations carried by `LANG.po' are slowly fading out of
862 It is important for translators (and even maintainers) to understand
863 that package translation is a continuous process in the lifetime of a
864 package, and not something which is done once and for all at the start.
865 After an initial burst of translation activity for a given package,
866 interventions are needed once in a while, because here and there,
867 translated entries become obsolete, and new untranslated entries
868 appear, needing translation.
870 The `msgmerge' program has the purpose of refreshing an already
871 existing `LANG.po' file, by comparing it with a newer `PACKAGE.pot'
872 template file, extracted by `xgettext' out of recent C sources. The
873 refreshing operation adjusts all references to C source locations for
874 strings, since these strings move as programs are modified. Also,
875 `msgmerge' comments out as obsolete, in `LANG.po', those already
876 translated entries which are no longer used in the program sources
877 (*note Obsolete Entries::). It finally discovers new strings and
878 inserts them in the resulting PO file as untranslated entries (*note
879 Untranslated Entries::). *Note msgmerge Invocation::, for more
880 information about what `msgmerge' really does.
882 Whatever route or means taken, the goal is to obtain an updated
883 `LANG.po' file offering translations for all strings.
885 The temporal mobility, or fluidity of PO files, is an integral part
886 of the translation game, and should be well understood, and accepted.
887 People resisting it will have a hard time participating in the
888 Translation Project, or will give a hard time to other participants! In
889 particular, maintainers should relax and include all available official
890 PO files in their distributions, even if these have not recently been
891 updated, without exerting pressure on the translator teams to get the
892 job done. The pressure should rather come from the community of users
893 speaking a particular language, and maintainers should consider
894 themselves fairly relieved of any concern about the adequacy of
895 translation files. On the other hand, translators should reasonably
896 try updating the PO files they are responsible for, while the package
897 is undergoing pretest, prior to an official distribution.
899 Once the PO file is complete and dependable, the `msgfmt' program is
900 used for turning the PO file into a machine-oriented format, which may
901 yield efficient retrieval of translations by the programs of the
902 package, whenever needed at runtime (*note MO Files::). *Note msgfmt
903 Invocation::, for more information about all modes of execution for the
906 Finally, the modified and marked C sources are compiled and linked
907 with the GNU `gettext' library, usually through the operation of
908 `make', given a suitable `Makefile' exists for the project, and the
909 resulting executable is installed somewhere users will find it. The MO
910 files themselves should also be properly installed. Given the
911 appropriate environment variables are set (*note Setting the POSIX
912 Locale::), the program should localize itself automatically, whenever
915 The remainder of this manual has the purpose of explaining in depth
916 the various steps outlined above.
919 File: gettext.info, Node: Users, Next: PO Files, Prev: Introduction, Up: Top
924 Nowadays, when users log into a computer, they usually find that all
925 their programs show messages in their native language - at least for
926 users of languages with an active free software community, like French
927 or German; to a lesser extent for languages with a smaller
928 participation in free software and the GNU project, like Hindi and
931 How does this work? How can the user influence the language that is
932 used by the programs? This chapter will answer it.
936 * System Installation:: Questions During Operating System Installation
937 * Setting the GUI Locale:: How to Specify the Locale Used by GUI Programs
938 * Setting the POSIX Locale:: How to Specify the Locale According to POSIX
939 * Installing Localizations:: How to Install Additional Translations
942 File: gettext.info, Node: System Installation, Next: Setting the GUI Locale, Prev: Users, Up: Users
944 2.1 Operating System Installation
945 =================================
947 The default language is often already specified during operating
948 system installation. When the operating system is installed, the
949 installer typically asks for the language used for the installation
950 process and, separately, for the language to use in the installed
951 system. Some OS installers only ask for the language once.
953 This determines the system-wide default language for all users. But
954 the installers often give the possibility to install extra
955 localizations for additional languages. For example, the localizations
956 of KDE (the K Desktop Environment) and OpenOffice.org are often bundled
957 separately, as one installable package per language.
959 At this point it is good to consider the intended use of the
960 machine: If it is a machine designated for personal use, additional
961 localizations are probably not necessary. If, however, the machine is
962 in use in an organization or company that has international
963 relationships, one can consider the needs of guest users. If you have
964 a guest from abroad, for a week, what could be his preferred locales?
965 It may be worth installing these additional localizations ahead of
966 time, since they cost only a bit of disk space at this point.
968 The system-wide default language is the locale configuration that is
969 used when a new user account is created. But the user can have his own
970 locale configuration that is different from the one of the other users
971 of the same machine. He can specify it, typically after the first
972 login, as described in the next section.
975 File: gettext.info, Node: Setting the GUI Locale, Next: Setting the POSIX Locale, Prev: System Installation, Up: Users
977 2.2 Setting the Locale Used by GUI Programs
978 ===========================================
980 The immediately available programs in a user's desktop come from a
981 group of programs called a "desktop environment"; it usually includes
982 the window manager, a web browser, a text editor, and more. The most
983 common free desktop environments are KDE, GNOME, and Xfce.
985 The locale used by GUI programs of the desktop environment can be
986 specified in a configuration screen called "control center", "language
987 settings" or "country settings".
989 Individual GUI programs that are not part of the desktop environment
990 can have their locale specified either in a settings panel, or through
991 environment variables.
993 For some programs, it is possible to specify the locale through
994 environment variables, possibly even to a different locale than the
995 desktop's locale. This means, instead of starting a program through a
996 menu or from the file system, you can start it from the command-line,
997 after having set some environment variables. The environment variables
998 can be those specified in the next section (*note Setting the POSIX
999 Locale::); for some versions of KDE, however, the locale is specified
1000 through a variable `KDE_LANG', rather than `LANG' or `LC_ALL'.
1003 File: gettext.info, Node: Setting the POSIX Locale, Next: Installing Localizations, Prev: Setting the GUI Locale, Up: Users
1005 2.3 Setting the Locale through Environment Variables
1006 ====================================================
1008 As a user, if your language has been installed for this package, in
1009 the simplest case, you only have to set the `LANG' environment variable
1010 to the appropriate `LL_CC' combination. For example, let's suppose
1011 that you speak German and live in Germany. At the shell prompt, merely
1012 execute `setenv LANG de_DE' (in `csh'), `export LANG; LANG=de_DE' (in
1013 `sh') or `export LANG=de_DE' (in `bash'). This can be done from your
1014 `.login' or `.profile' file, once and for all.
1018 * Locale Names:: How a Locale Specification Looks Like
1019 * Locale Environment Variables:: Which Environment Variable Specfies What
1020 * The LANGUAGE variable:: How to Specify a Priority List of Languages
1023 File: gettext.info, Node: Locale Names, Next: Locale Environment Variables, Prev: Setting the POSIX Locale, Up: Setting the POSIX Locale
1028 A locale name usually has the form `LL_CC'. Here `LL' is an ISO 639
1029 two-letter language code, and `CC' is an ISO 3166 two-letter country
1030 code. For example, for German in Germany, LL is `de', and CC is `DE'.
1031 You find a list of the language codes in appendix *note Language
1032 Codes:: and a list of the country codes in appendix *note Country
1035 You might think that the country code specification is redundant.
1036 But in fact, some languages have dialects in different countries. For
1037 example, `de_AT' is used for Austria, and `pt_BR' for Brazil. The
1038 country code serves to distinguish the dialects.
1040 Many locale names have an extended syntax `LL_CC.ENCODING' that also
1041 specifies the character encoding. These are in use because between
1042 2000 and 2005, most users have switched to locales in UTF-8 encoding.
1043 For example, the German locale on glibc systems is nowadays
1044 `de_DE.UTF-8'. The older name `de_DE' still refers to the German
1045 locale as of 2000 that stores characters in ISO-8859-1 encoding - a
1046 text encoding that cannot even accomodate the Euro currency sign.
1048 Some locale names use `LL_CC.@VARIANT' instead of `LL_CC'. The
1049 `@VARIANT' can denote any kind of characteristics that is not already
1050 implied by the language LL and the country CC. It can denote a
1051 particular monetary unit. For example, on glibc systems, `de_DE@euro'
1052 denotes the locale that uses the Euro currency, in contrast to the
1053 older locale `de_DE' which implies the use of the currency before 2002.
1054 It can also denote a dialect of the language, or the script used to
1055 write text (for example, `sr_RS@latin' uses the Latin script, whereas
1056 `sr_RS' uses the Cyrillic script to write Serbian), or the orthography
1059 On other systems, some variations of this scheme are used, such as
1060 `LL'. You can get the list of locales supported by your system for
1061 your language by running the command `locale -a | grep '^LL''.
1063 There is also a special locale, called `C'. When it is used, it
1064 disables all localization: in this locale, all programs standardized by
1065 POSIX use English messages and an unspecified character encoding (often
1066 US-ASCII, but sometimes also ISO-8859-1 or UTF-8, depending on the
1070 File: gettext.info, Node: Locale Environment Variables, Next: The LANGUAGE variable, Prev: Locale Names, Up: Setting the POSIX Locale
1072 2.3.2 Locale Environment Variables
1073 ----------------------------------
1075 A locale is composed of several _locale categories_, see *note
1076 Aspects::. When a program looks up locale dependent values, it does
1077 this according to the following environment variables, in priority
1084 3. `LC_xxx', according to selected locale category: `LC_CTYPE',
1085 `LC_NUMERIC', `LC_TIME', `LC_COLLATE', `LC_MONETARY',
1090 Variables whose value is set but is empty are ignored in this lookup.
1092 `LANG' is the normal environment variable for specifying a locale.
1093 As a user, you normally set this variable (unless some of the other
1094 variables have already been set by the system, in `/etc/profile' or
1095 similar initialization files).
1097 `LC_CTYPE', `LC_NUMERIC', `LC_TIME', `LC_COLLATE', `LC_MONETARY',
1098 `LC_MESSAGES', and so on, are the environment variables meant to
1099 override `LANG' and affecting a single locale category only. For
1100 example, assume you are a Swedish user in Spain, and you want your
1101 programs to handle numbers and dates according to Spanish conventions,
1102 and only the messages should be in Swedish. Then you could create a
1103 locale named `sv_ES' or `sv_ES.UTF-8' by use of the `localedef'
1104 program. But it is simpler, and achieves the same effect, to set the
1105 `LANG' variable to `es_ES.UTF-8' and the `LC_MESSAGES' variable to
1106 `sv_SE.UTF-8'; these two locales come already preinstalled with the
1109 `LC_ALL' is an environment variable that overrides all of these. It
1110 is typically used in scripts that run particular programs. For example,
1111 `configure' scripts generated by GNU autoconf use `LC_ALL' to make sure
1112 that the configuration tests don't operate in locale dependent ways.
1114 Some systems, unfortunately, set `LC_ALL' in `/etc/profile' or in
1115 similar initialization files. As a user, you therefore have to unset
1116 this variable if you want to set `LANG' and optionally some of the other
1119 The `LANGUAGE' variable is described in the next subsection.
1122 File: gettext.info, Node: The LANGUAGE variable, Prev: Locale Environment Variables, Up: Setting the POSIX Locale
1124 2.3.3 Specifying a Priority List of Languages
1125 ---------------------------------------------
1127 Not all programs have translations for all languages. By default, an
1128 English message is shown in place of a nonexistent translation. If you
1129 understand other languages, you can set up a priority list of languages.
1130 This is done through a different environment variable, called
1131 `LANGUAGE'. GNU `gettext' gives preference to `LANGUAGE' over `LC_ALL'
1132 and `LANG' for the purpose of message handling, but you still need to
1133 have `LANG' (or `LC_ALL') set to the primary language; this is required
1134 by other parts of the system libraries. For example, some Swedish
1135 users who would rather read translations in German than English for
1136 when Swedish is not available, set `LANGUAGE' to `sv:de' while leaving
1139 Special advice for Norwegian users: The language code for Norwegian
1140 bokma*l changed from `no' to `nb' recently (in 2003). During the
1141 transition period, while some message catalogs for this language are
1142 installed under `nb' and some older ones under `no', it is recommended
1143 for Norwegian users to set `LANGUAGE' to `nb:no' so that both newer and
1144 older translations are used.
1146 In the `LANGUAGE' environment variable, but not in the other
1147 environment variables, `LL_CC' combinations can be abbreviated as `LL'
1148 to denote the language's main dialect. For example, `de' is equivalent
1149 to `de_DE' (German as spoken in Germany), and `pt' to `pt_PT'
1150 (Portuguese as spoken in Portugal) in this context.
1152 Note: The variable `LANGUAGE' is ignored if the locale is set to
1153 `C'. In other words, you have to first enable localization, by setting
1154 `LANG' (or `LC_ALL') to a value other than `C', before you can use a
1155 language priority list through the `LANGUAGE' variable.
1158 File: gettext.info, Node: Installing Localizations, Prev: Setting the POSIX Locale, Up: Users
1160 2.4 Installing Translations for Particular Programs
1161 ===================================================
1163 Languages are not equally well supported in all packages using GNU
1164 `gettext', and more translations are added over time. Usually, you use
1165 the translations that are shipped with the operating system or with
1166 particular packages that you install afterwards. But you can also
1167 install newer localizations directly. For doing this, you will need an
1168 understanding where each localization file is stored on the file system.
1170 For programs that participate in the Translation Project, you can
1171 start looking for translations here:
1172 `http://translationproject.org/team/index.html'. A snapshot of this
1173 information is also found in the `ABOUT-NLS' file that is shipped with
1176 For programs that are part of the KDE project, the starting point is:
1177 `http://i18n.kde.org/'.
1179 For programs that are part of the GNOME project, the starting point
1180 is: `http://www.gnome.org/i18n/'.
1182 For other programs, you may check whether the program's source code
1183 package contains some `LL.po' files; often they are kept together in a
1184 directory called `po/'. Each `LL.po' file contains the message
1185 translations for the language whose abbreviation of LL.
1188 File: gettext.info, Node: PO Files, Next: Sources, Prev: Users, Up: Top
1190 3 The Format of PO Files
1191 ************************
1193 The GNU `gettext' toolset helps programmers and translators at
1194 producing, updating and using translation files, mainly those PO files
1195 which are textual, editable files. This chapter explains the format of
1198 A PO file is made up of many entries, each entry holding the relation
1199 between an original untranslated string and its corresponding
1200 translation. All entries in a given PO file usually pertain to a
1201 single project, and all translations are expressed in a single target
1202 language. One PO file "entry" has the following schematic structure:
1205 # TRANSLATOR-COMMENTS
1206 #. EXTRACTED-COMMENTS
1209 #| msgid PREVIOUS-UNTRANSLATED-STRING
1210 msgid UNTRANSLATED-STRING
1211 msgstr TRANSLATED-STRING
1213 The general structure of a PO file should be well understood by the
1214 translator. When using PO mode, very little has to be known about the
1215 format details, as PO mode takes care of them for her.
1217 A simple entry can look like this:
1220 msgid "Unknown system error"
1221 msgstr "Error desconegut del sistema"
1223 Entries begin with some optional white space. Usually, when
1224 generated through GNU `gettext' tools, there is exactly one blank line
1225 between entries. Then comments follow, on lines all starting with the
1226 character `#'. There are two kinds of comments: those which have some
1227 white space immediately following the `#' - the TRANSLATOR COMMENTS -,
1228 which comments are created and maintained exclusively by the
1229 translator, and those which have some non-white character just after the
1230 `#' - the AUTOMATIC COMMENTS -, which comments are created and
1231 maintained automatically by GNU `gettext' tools. Comment lines
1232 starting with `#.' contain comments given by the programmer, directed
1233 at the translator; these comments are called EXTRACTED COMMENTS because
1234 the `xgettext' program extracts them from the program's source code.
1235 Comment lines starting with `#:' contain references to the program's
1236 source code. Comment lines starting with `#,' contain flags; more
1237 about these below. Comment lines starting with `#|' contain the
1238 previous untranslated string for which the translator gave a
1241 All comments, of either kind, are optional.
1243 After white space and comments, entries show two strings, namely
1244 first the untranslated string as it appears in the original program
1245 sources, and then, the translation of this string. The original string
1246 is introduced by the keyword `msgid', and the translation, by `msgstr'.
1247 The two strings, untranslated and translated, are quoted in various
1248 ways in the PO file, using `"' delimiters and `\' escapes, but the
1249 translator does not really have to pay attention to the precise quoting
1250 format, as PO mode fully takes care of quoting for her.
1252 The `msgid' strings, as well as automatic comments, are produced and
1253 managed by other GNU `gettext' tools, and PO mode does not provide
1254 means for the translator to alter these. The most she can do is merely
1255 deleting them, and only by deleting the whole entry. On the other
1256 hand, the `msgstr' string, as well as translator comments, are really
1257 meant for the translator, and PO mode gives her the full control she
1260 The comment lines beginning with `#,' are special because they are
1261 not completely ignored by the programs as comments generally are. The
1262 comma separated list of FLAGs is used by the `msgfmt' program to give
1263 the user some better diagnostic messages. Currently there are two
1264 forms of flags defined:
1267 This flag can be generated by the `msgmerge' program or it can be
1268 inserted by the translator herself. It shows that the `msgstr'
1269 string might not be a correct translation (anymore). Only the
1270 translator can judge if the translation requires further
1271 modification, or is acceptable as is. Once satisfied with the
1272 translation, she then removes this `fuzzy' attribute. The
1273 `msgmerge' program inserts this when it combined the `msgid' and
1274 `msgstr' entries after fuzzy search only. *Note Fuzzy Entries::.
1278 These flags should not be added by a human. Instead only the
1279 `xgettext' program adds them. In an automated PO file processing
1280 system as proposed here, the user's changes would be thrown away
1281 again as soon as the `xgettext' program generates a new template
1284 The `c-format' flag indicates that the untranslated string and the
1285 translation are supposed to be C format strings. The `no-c-format'
1286 flag indicates that they are not C format strings, even though the
1287 untranslated string happens to look like a C format string (with
1290 When the `c-format' flag is given for a string the `msgfmt'
1291 program does some more tests to check the validity of the
1292 translation. *Note msgfmt Invocation::, *note c-format Flag:: and
1297 Likewise for Objective C, see *note objc-format::.
1301 Likewise for Shell, see *note sh-format::.
1305 Likewise for Python, see *note python-format::.
1309 Likewise for Lisp, see *note lisp-format::.
1313 Likewise for Emacs Lisp, see *note elisp-format::.
1317 Likewise for librep, see *note librep-format::.
1321 Likewise for Scheme, see *note scheme-format::.
1324 `no-smalltalk-format'
1325 Likewise for Smalltalk, see *note smalltalk-format::.
1329 Likewise for Java, see *note java-format::.
1333 Likewise for C#, see *note csharp-format::.
1337 Likewise for awk, see *note awk-format::.
1339 `object-pascal-format'
1340 `no-object-pascal-format'
1341 Likewise for Object Pascal, see *note object-pascal-format::.
1345 Likewise for YCP, see *note ycp-format::.
1349 Likewise for Tcl, see *note tcl-format::.
1353 Likewise for Perl, see *note perl-format::.
1356 `no-perl-brace-format'
1357 Likewise for Perl brace, see *note perl-format::.
1361 Likewise for PHP, see *note php-format::.
1363 `gcc-internal-format'
1364 `no-gcc-internal-format'
1365 Likewise for the GCC sources, see *note gcc-internal-format::.
1367 `gfc-internal-format'
1368 `no-gfc-internal-format'
1369 Likewise for the GNU Fortran Compiler sources, see *note
1370 gfc-internal-format::.
1374 Likewise for Qt, see *note qt-format::.
1377 `no-qt-plural-format'
1378 Likewise for Qt plural forms, see *note qt-plural-format::.
1382 Likewise for KDE, see *note kde-format::.
1386 Likewise for Boost, see *note boost-format::.
1389 It is also possible to have entries with a context specifier. They
1393 # TRANSLATOR-COMMENTS
1394 #. EXTRACTED-COMMENTS
1397 #| msgctxt PREVIOUS-CONTEXT
1398 #| msgid PREVIOUS-UNTRANSLATED-STRING
1400 msgid UNTRANSLATED-STRING
1401 msgstr TRANSLATED-STRING
1403 The context serves to disambiguate messages with the same
1404 UNTRANSLATED-STRING. It is possible to have several entries with the
1405 same UNTRANSLATED-STRING in a PO file, provided that they each have a
1406 different CONTEXT. Note that an empty CONTEXT string and an absent
1407 `msgctxt' line do not mean the same thing.
1409 A different kind of entries is used for translations which involve
1413 # TRANSLATOR-COMMENTS
1414 #. EXTRACTED-COMMENTS
1417 #| msgid PREVIOUS-UNTRANSLATED-STRING-SINGULAR
1418 #| msgid_plural PREVIOUS-UNTRANSLATED-STRING-PLURAL
1419 msgid UNTRANSLATED-STRING-SINGULAR
1420 msgid_plural UNTRANSLATED-STRING-PLURAL
1421 msgstr[0] TRANSLATED-STRING-CASE-0
1423 msgstr[N] TRANSLATED-STRING-CASE-N
1425 Such an entry can look like this:
1427 #: src/msgcmp.c:338 src/po-lex.c:699
1429 msgid "found %d fatal error"
1430 msgid_plural "found %d fatal errors"
1431 msgstr[0] "s'ha trobat %d error fatal"
1432 msgstr[1] "s'han trobat %d errors fatals"
1434 Here also, a `msgctxt' context can be specified before `msgid', like
1437 Here, additional kinds of flags can be used:
1440 This flag is followed by a range of non-negative numbers, using
1441 the syntax `range: MINIMUM-VALUE..MAXIMUM-VALUE'. It designates
1442 the possible values that the numeric parameter of the message can
1443 take. In some languages, translators may produce slightly better
1444 translations if they know that the value can only take on values
1445 between 0 and 10, for example.
1447 The PREVIOUS-UNTRANSLATED-STRING is optionally inserted by the
1448 `msgmerge' program, at the same time when it marks a message fuzzy. It
1449 helps the translator to see which changes were done by the developers
1450 on the UNTRANSLATED-STRING.
1452 It happens that some lines, usually whitespace or comments, follow
1453 the very last entry of a PO file. Such lines are not part of any entry,
1454 and will be dropped when the PO file is processed by the tools, or may
1455 disturb some PO file editors.
1457 The remainder of this section may be safely skipped by those using a
1458 PO file editor, yet it may be interesting for everybody to have a better
1459 idea of the precise format of a PO file. On the other hand, those
1460 wishing to modify PO files by hand should carefully continue reading on.
1462 Each of UNTRANSLATED-STRING and TRANSLATED-STRING respects the C
1463 syntax for a character string, including the surrounding quotes and
1464 embedded backslashed escape sequences. When the time comes to write
1465 multi-line strings, one should not use escaped newlines. Instead, a
1466 closing quote should follow the last character on the line to be
1467 continued, and an opening quote should resume the string at the
1468 beginning of the following PO file line. For example:
1471 "Here is an example of how one might continue a very long string\n"
1472 "for the common case the string represents multi-line output.\n"
1474 In this example, the empty string is used on the first line, to allow
1475 better alignment of the `H' from the word `Here' over the `f' from the
1476 word `for'. In this example, the `msgid' keyword is followed by three
1477 strings, which are meant to be concatenated. Concatenating the empty
1478 string does not change the resulting overall string, but it is a way
1479 for us to comply with the necessity of `msgid' to be followed by a
1480 string on the same line, while keeping the multi-line presentation
1481 left-justified, as we find this to be a cleaner disposition. The empty
1482 string could have been omitted, but only if the string starting with
1483 `Here' was promoted on the first line, right after `msgid'.(1) It was
1484 not really necessary either to switch between the two last quoted
1485 strings immediately after the newline `\n', the switch could have
1486 occurred after _any_ other character, we just did it this way because
1489 One should carefully distinguish between end of lines marked as `\n'
1490 _inside_ quotes, which are part of the represented string, and end of
1491 lines in the PO file itself, outside string quotes, which have no
1492 incidence on the represented string.
1494 Outside strings, white lines and comments may be used freely.
1495 Comments start at the beginning of a line with `#' and extend until the
1496 end of the PO file line. Comments written by translators should have
1497 the initial `#' immediately followed by some white space. If the `#'
1498 is not immediately followed by white space, this comment is most likely
1499 generated and managed by specialized GNU tools, and might disappear or
1500 be replaced unexpectedly when the PO file is given to `msgmerge'.
1502 ---------- Footnotes ----------
1504 (1) This limitation is not imposed by GNU `gettext', but is for
1505 compatibility with the `msgfmt' implementation on Solaris.
1508 File: gettext.info, Node: Sources, Next: Template, Prev: PO Files, Up: Top
1510 4 Preparing Program Sources
1511 ***************************
1513 For the programmer, changes to the C source code fall into three
1514 categories. First, you have to make the localization functions known
1515 to all modules needing message translation. Second, you should
1516 properly trigger the operation of GNU `gettext' when the program
1517 initializes, usually from the `main' function. Last, you should
1518 identify, adjust and mark all constant strings in your program needing
1523 * Importing:: Importing the `gettext' declaration
1524 * Triggering:: Triggering `gettext' Operations
1525 * Preparing Strings:: Preparing Translatable Strings
1526 * Mark Keywords:: How Marks Appear in Sources
1527 * Marking:: Marking Translatable Strings
1528 * c-format Flag:: Telling something about the following string
1529 * Special cases:: Special Cases of Translatable Strings
1530 * Bug Report Address:: Letting Users Report Translation Bugs
1531 * Names:: Marking Proper Names for Translation
1532 * Libraries:: Preparing Library Sources
1535 File: gettext.info, Node: Importing, Next: Triggering, Prev: Sources, Up: Sources
1537 4.1 Importing the `gettext' declaration
1538 =======================================
1540 Presuming that your set of programs, or package, has been adjusted
1541 so all needed GNU `gettext' files are available, and your `Makefile'
1542 files are adjusted (*note Maintainers::), each C module having
1543 translated C strings should contain the line:
1545 #include <libintl.h>
1547 Similarly, each C module containing `printf()'/`fprintf()'/...
1548 calls with a format string that could be a translated C string (even if
1549 the C string comes from a different C module) should contain the line:
1551 #include <libintl.h>
1554 File: gettext.info, Node: Triggering, Next: Preparing Strings, Prev: Importing, Up: Sources
1556 4.2 Triggering `gettext' Operations
1557 ===================================
1559 The initialization of locale data should be done with more or less
1560 the same code in every program, as demonstrated below:
1563 main (int argc, char *argv[])
1566 setlocale (LC_ALL, "");
1567 bindtextdomain (PACKAGE, LOCALEDIR);
1568 textdomain (PACKAGE);
1572 PACKAGE and LOCALEDIR should be provided either by `config.h' or by
1573 the Makefile. For now consult the `gettext' or `hello' sources for
1576 The use of `LC_ALL' might not be appropriate for you. `LC_ALL'
1577 includes all locale categories and especially `LC_CTYPE'. This latter
1578 category is responsible for determining character classes with the
1579 `isalnum' etc. functions from `ctype.h' which could especially for
1580 programs, which process some kind of input language, be wrong. For
1581 example this would mean that a source code using the ç (c-cedilla
1582 character) is runnable in France but not in the U.S.
1584 Some systems also have problems with parsing numbers using the
1585 `scanf' functions if an other but the `LC_ALL' locale category is used.
1586 The standards say that additional formats but the one known in the
1587 `"C"' locale might be recognized. But some systems seem to reject
1588 numbers in the `"C"' locale format. In some situation, it might also
1589 be a problem with the notation itself which makes it impossible to
1590 recognize whether the number is in the `"C"' locale or the local
1591 format. This can happen if thousands separator characters are used.
1592 Some locales define this character according to the national
1593 conventions to `'.'' which is the same character used in the `"C"'
1594 locale to denote the decimal point.
1596 So it is sometimes necessary to replace the `LC_ALL' line in the
1597 code above by a sequence of `setlocale' lines
1601 setlocale (LC_CTYPE, "");
1602 setlocale (LC_MESSAGES, "");
1606 On all POSIX conformant systems the locale categories `LC_CTYPE',
1607 `LC_MESSAGES', `LC_COLLATE', `LC_MONETARY', `LC_NUMERIC', and `LC_TIME'
1608 are available. On some systems which are only ISO C compliant,
1609 `LC_MESSAGES' is missing, but a substitute for it is defined in GNU
1610 gettext's `<libintl.h>' and in GNU gnulib's `<locale.h>'.
1612 Note that changing the `LC_CTYPE' also affects the functions
1613 declared in the `<ctype.h>' standard header and some functions declared
1614 in the `<string.h>' and `<stdlib.h>' standard headers. If this is not
1615 desirable in your application (for example in a compiler's parser), you
1616 can use a set of substitute functions which hardwire the C locale, such
1617 as found in the modules `c-ctype', `c-strcase', `c-strcasestr',
1618 `c-strtod', `c-strtold' in the GNU gnulib source distribution.
1620 It is also possible to switch the locale forth and back between the
1621 environment dependent locale and the C locale, but this approach is
1622 normally avoided because a `setlocale' call is expensive, because it is
1623 tedious to determine the places where a locale switch is needed in a
1624 large program's source, and because switching a locale is not
1628 File: gettext.info, Node: Preparing Strings, Next: Mark Keywords, Prev: Triggering, Up: Sources
1630 4.3 Preparing Translatable Strings
1631 ==================================
1633 Before strings can be marked for translations, they sometimes need to
1634 be adjusted. Usually preparing a string for translation is done right
1635 before marking it, during the marking phase which is described in the
1636 next sections. What you have to keep in mind while doing that is the
1639 * Decent English style.
1643 * Split at paragraphs.
1645 * Use format strings instead of string concatenation.
1647 * Avoid unusual markup and unusual control characters.
1649 Let's look at some examples of these guidelines.
1651 Translatable strings should be in good English style. If slang
1652 language with abbreviations and shortcuts is used, often translators
1653 will not understand the message and will produce very inappropriate
1656 "%s: is parameter\n"
1658 This is nearly untranslatable: Is the displayed item _a_ parameter or
1663 The ambiguity in this message makes it unintelligible: Is the program
1664 attempting to set something on fire? Does it mean "The given object does
1665 not match the template"? Does it mean "The template does not fit for any
1668 In both cases, adding more words to the message will help both the
1669 translator and the English speaking user.
1671 Translatable strings should be entire sentences. It is often not
1672 possible to translate single verbs or adjectives in a substitutable way.
1674 printf ("File %s is %s protected", filename, rw ? "write" : "read");
1676 Most translators will not look at the source and will thus only see the
1677 string `"File %s is %s protected"', which is unintelligible. Change
1680 printf (rw ? "File %s is write protected" : "File %s is read protected",
1683 This way the translator will not only understand the message, she will
1684 also be able to find the appropriate grammatical construction. A French
1685 translator for example translates "write protected" like "protected
1688 Entire sentences are also important because in many languages, the
1689 declination of some word in a sentence depends on the gender or the
1690 number (singular/plural) of another part of the sentence. There are
1691 usually more interdependencies between words than in English. The
1692 consequence is that asking a translator to translate two half-sentences
1693 and then combining these two half-sentences through dumb string
1694 concatenation will not work, for many languages, even though it would
1695 work for English. That's why translators need to handle entire
1698 Often sentences don't fit into a single line. If a sentence is
1699 output using two subsequent `printf' statements, like this
1701 printf ("Locale charset \"%s\" is different from\n", lcharset);
1702 printf ("input file charset \"%s\".\n", fcharset);
1704 the translator would have to translate two half sentences, but nothing
1705 in the POT file would tell her that the two half sentences belong
1706 together. It is necessary to merge the two `printf' statements so that
1707 the translator can handle the entire sentence at once and decide at
1708 which place to insert a line break in the translation (if at all):
1710 printf ("Locale charset \"%s\" is different from\n\
1711 input file charset \"%s\".\n", lcharset, fcharset);
1713 You may now ask: how about two or more adjacent sentences? Like in
1716 puts ("Apollo 13 scenario: Stack overflow handling failed.");
1717 puts ("On the next stack overflow we will crash!!!");
1719 Should these two statements merged into a single one? I would recommend
1720 to merge them if the two sentences are related to each other, because
1721 then it makes it easier for the translator to understand and translate
1722 both. On the other hand, if one of the two messages is a stereotypic
1723 one, occurring in other places as well, you will do a favour to the
1724 translator by not merging the two. (Identical messages occurring in
1725 several places are combined by xgettext, so the translator has to
1726 handle them once only.)
1728 Translatable strings should be limited to one paragraph; don't let a
1729 single message be longer than ten lines. The reason is that when the
1730 translatable string changes, the translator is faced with the task of
1731 updating the entire translated string. Maybe only a single word will
1732 have changed in the English string, but the translator doesn't see that
1733 (with the current translation tools), therefore she has to proofread
1736 Many GNU programs have a `--help' output that extends over several
1737 screen pages. It is a courtesy towards the translators to split such a
1738 message into several ones of five to ten lines each. While doing that,
1739 you can also attempt to split the documented options into groups, such
1740 as the input options, the output options, and the informative output
1741 options. This will help every user to find the option he is looking
1744 Hardcoded string concatenation is sometimes used to construct English
1747 strcpy (s, "Replace ");
1748 strcat (s, object1);
1749 strcat (s, " with ");
1750 strcat (s, object2);
1753 In order to present to the translator only entire sentences, and also
1754 because in some languages the translator might want to swap the order
1755 of `object1' and `object2', it is necessary to change this to use a
1758 sprintf (s, "Replace %s with %s?", object1, object2);
1760 A similar case is compile time concatenation of strings. The ISO C
1761 99 include file `<inttypes.h>' contains a macro `PRId64' that can be
1762 used as a formatting directive for outputting an `int64_t' integer
1763 through `printf'. It expands to a constant string, usually "d" or "ld"
1764 or "lld" or something like this, depending on the platform. Assume you
1767 printf ("The amount is %0" PRId64 "\n", number);
1769 The `gettext' tools and library have special support for these
1770 `<inttypes.h>' macros. You can therefore simply write
1772 printf (gettext ("The amount is %0" PRId64 "\n"), number);
1774 The PO file will contain the string "The amount is %0<PRId64>\n". The
1775 translators will provide a translation containing "%0<PRId64>" as well,
1776 and at runtime the `gettext' function's result will contain the
1777 appropriate constant string, "d" or "ld" or "lld".
1779 This works only for the predefined `<inttypes.h>' macros. If you
1780 have defined your own similar macros, let's say `MYPRId64', that are
1781 not known to `xgettext', the solution for this problem is to change the
1785 sprintf (buf1, "%0" MYPRId64, number);
1786 printf (gettext ("The amount is %s\n"), buf1);
1788 This means, you put the platform dependent code in one statement,
1789 and the internationalization code in a different statement. Note that
1790 a buffer length of 100 is safe, because all available hardware integer
1791 types are limited to 128 bits, and to print a 128 bit integer one needs
1792 at most 54 characters, regardless whether in decimal, octal or
1795 All this applies to other programming languages as well. For
1796 example, in Java and C#, string concatenation is very frequently used,
1797 because it is a compiler built-in operator. Like in C, in Java, you
1800 System.out.println("Replace "+object1+" with "+object2+"?");
1802 into a statement involving a format string:
1805 MessageFormat.format("Replace {0} with {1}?",
1806 new Object[] { object1, object2 }));
1808 Similarly, in C#, you would change
1810 Console.WriteLine("Replace "+object1+" with "+object2+"?");
1812 into a statement involving a format string:
1815 String.Format("Replace {0} with {1}?", object1, object2));
1817 Unusual markup or control characters should not be used in
1818 translatable strings. Translators will likely not understand the
1819 particular meaning of the markup or control characters.
1821 For example, if you have a convention that `|' delimits the
1822 left-hand and right-hand part of some GUI elements, translators will
1823 often not understand it without specific comments. It might be better
1824 to have the translator translate the left-hand and right-hand part
1827 Another example is the `argp' convention to use a single `\v'
1828 (vertical tab) control character to delimit two sections inside a
1829 string. This is flawed. Some translators may convert it to a simple
1830 newline, some to blank lines. With some PO file editors it may not be
1831 easy to even enter a vertical tab control character. So, you cannot be
1832 sure that the translation will contain a `\v' character, at the
1833 corresponding position. The solution is, again, to let the translator
1834 translate two separate strings and combine at run-time the two
1835 translated strings with the `\v' required by the convention.
1837 HTML markup, however, is common enough that it's probably ok to use
1838 in translatable strings. But please bear in mind that the GNU gettext
1839 tools don't verify that the translations are well-formed HTML.
1842 File: gettext.info, Node: Mark Keywords, Next: Marking, Prev: Preparing Strings, Up: Sources
1844 4.4 How Marks Appear in Sources
1845 ===============================
1847 All strings requiring translation should be marked in the C sources.
1848 Marking is done in such a way that each translatable string appears to
1849 be the sole argument of some function or preprocessor macro. There are
1850 only a few such possible functions or macros meant for translation, and
1851 their names are said to be marking keywords. The marking is attached
1852 to strings themselves, rather than to what we do with them. This
1853 approach has more uses. A blatant example is an error message produced
1854 by formatting. The format string needs translation, as well as some
1855 strings inserted through some `%s' specification in the format, while
1856 the result from `sprintf' may have so many different instances that it
1857 is impractical to list them all in some `error_string_out()' routine,
1860 This marking operation has two goals. The first goal of marking is
1861 for triggering the retrieval of the translation, at run time. The
1862 keyword is possibly resolved into a routine able to dynamically return
1863 the proper translation, as far as possible or wanted, for the argument
1864 string. Most localizable strings are found in executable positions,
1865 that is, attached to variables or given as parameters to functions.
1866 But this is not universal usage, and some translatable strings appear
1867 in structured initializations. *Note Special cases::.
1869 The second goal of the marking operation is to help `xgettext' at
1870 properly extracting all translatable strings when it scans a set of
1871 program sources and produces PO file templates.
1873 The canonical keyword for marking translatable strings is `gettext',
1874 it gave its name to the whole GNU `gettext' package. For packages
1875 making only light use of the `gettext' keyword, macro or function, it
1876 is easily used _as is_. However, for packages using the `gettext'
1877 interface more heavily, it is usually more convenient to give the main
1878 keyword a shorter, less obtrusive name. Indeed, the keyword might
1879 appear on a lot of strings all over the package, and programmers
1880 usually do not want nor need their program sources to remind them
1881 forcefully, all the time, that they are internationalized. Further, a
1882 long keyword has the disadvantage of using more horizontal space,
1883 forcing more indentation work on sources for those trying to keep them
1884 within 79 or 80 columns.
1886 Many packages use `_' (a simple underline) as a keyword, and write
1887 `_("Translatable string")' instead of `gettext ("Translatable
1888 string")'. Further, the coding rule, from GNU standards, wanting that
1889 there is a space between the keyword and the opening parenthesis is
1890 relaxed, in practice, for this particular usage. So, the textual
1891 overhead per translatable string is reduced to only three characters:
1892 the underline and the two parentheses. However, even if GNU `gettext'
1893 uses this convention internally, it does not offer it officially. The
1894 real, genuine keyword is truly `gettext' indeed. It is fairly easy for
1895 those wanting to use `_' instead of `gettext' to declare:
1897 #include <libintl.h>
1898 #define _(String) gettext (String)
1900 instead of merely using `#include <libintl.h>'.
1902 The marking keywords `gettext' and `_' take the translatable string
1903 as sole argument. It is also possible to define marking functions that
1904 take it at another argument position. It is even possible to make the
1905 marked argument position depend on the total number of arguments of the
1906 function call; this is useful in C++. All this is achieved using
1907 `xgettext''s `--keyword' option. How to pass such an option to
1908 `xgettext', assuming that `gettextize' is used, is described in *note
1909 po/Makevars:: and *note AM_XGETTEXT_OPTION::.
1911 Note also that long strings can be split across lines, into multiple
1912 adjacent string tokens. Automatic string concatenation is performed at
1913 compile time according to ISO C and ISO C++; `xgettext' also supports
1916 Later on, the maintenance is relatively easy. If, as a programmer,
1917 you add or modify a string, you will have to ask yourself if the new or
1918 altered string requires translation, and include it within `_()' if you
1919 think it should be translated. For example, `"%s"' is an example of
1920 string _not_ requiring translation. But `"%s: %d"' _does_ require
1921 translation, because in French, unlike in English, it's customary to
1922 put a space before a colon.
1925 File: gettext.info, Node: Marking, Next: c-format Flag, Prev: Mark Keywords, Up: Sources
1927 4.5 Marking Translatable Strings
1928 ================================
1930 In PO mode, one set of features is meant more for the programmer than
1931 for the translator, and allows him to interactively mark which strings,
1932 in a set of program sources, are translatable, and which are not. Even
1933 if it is a fairly easy job for a programmer to find and mark such
1934 strings by other means, using any editor of his choice, PO mode makes
1935 this work more comfortable. Further, this gives translators who feel a
1936 little like programmers, or programmers who feel a little like
1937 translators, a tool letting them work at marking translatable strings
1938 in the program sources, while simultaneously producing a set of
1939 translation in some language, for the package being internationalized.
1941 The set of program sources, targeted by the PO mode commands describe
1942 here, should have an Emacs tags table constructed for your project,
1943 prior to using these PO file commands. This is easy to do. In any
1944 shell window, change the directory to the root of your project, then
1945 execute a command resembling:
1947 etags src/*.[hc] lib/*.[hc]
1949 presuming here you want to process all `.h' and `.c' files from the
1950 `src/' and `lib/' directories. This command will explore all said
1951 files and create a `TAGS' file in your root directory, somewhat
1952 summarizing the contents using a special file format Emacs can
1955 For packages following the GNU coding standards, there is a make
1956 goal `tags' or `TAGS' which constructs the tag files in all directories
1957 and for all files containing source code.
1959 Once your `TAGS' file is ready, the following commands assist the
1960 programmer at marking translatable strings in his set of sources. But
1961 these commands are necessarily driven from within a PO file window, and
1962 it is likely that you do not even have such a PO file yet. This is not
1963 a problem at all, as you may safely open a new, empty PO file, mainly
1964 for using these commands. This empty PO file will slowly fill in while
1965 you mark strings as translatable in your program sources.
1968 Search through program sources for a string which looks like a
1969 candidate for translation (`po-tags-search').
1972 Mark the last string found with `_()' (`po-mark-translatable').
1975 Mark the last string found with a keyword taken from a set of
1976 possible keywords. This command with a prefix allows some
1977 management of these keywords (`po-select-mark-and-mark').
1980 The `,' (`po-tags-search') command searches for the next occurrence
1981 of a string which looks like a possible candidate for translation, and
1982 displays the program source in another Emacs window, positioned in such
1983 a way that the string is near the top of this other window. If the
1984 string is too big to fit whole in this window, it is positioned so only
1985 its end is shown. In any case, the cursor is left in the PO file
1986 window. If the shown string would be better presented differently in
1987 different native languages, you may mark it using `M-,' or `M-.'.
1988 Otherwise, you might rather ignore it and skip to the next string by
1989 merely repeating the `,' command.
1991 A string is a good candidate for translation if it contains a
1992 sequence of three or more letters. A string containing at most two
1993 letters in a row will be considered as a candidate if it has more
1994 letters than non-letters. The command disregards strings containing no
1995 letters, or isolated letters only. It also disregards strings within
1996 comments, or strings already marked with some keyword PO mode knows
1999 If you have never told Emacs about some `TAGS' file to use, the
2000 command will request that you specify one from the minibuffer, the
2001 first time you use the command. You may later change your `TAGS' file
2002 by using the regular Emacs command `M-x visit-tags-table', which will
2003 ask you to name the precise `TAGS' file you want to use. *Note Tag
2004 Tables: (emacs)Tags.
2006 Each time you use the `,' command, the search resumes from where it
2007 was left by the previous search, and goes through all program sources,
2008 obeying the `TAGS' file, until all sources have been processed.
2009 However, by giving a prefix argument to the command (`C-u ,'), you may
2010 request that the search be restarted all over again from the first
2011 program source; but in this case, strings that you recently marked as
2012 translatable will be automatically skipped.
2014 Using this `,' command does not prevent using of other regular Emacs
2015 tags commands. For example, regular `tags-search' or
2016 `tags-query-replace' commands may be used without disrupting the
2017 independent `,' search sequence. However, as implemented, the
2018 _initial_ `,' command (or the `,' command is used with a prefix) might
2019 also reinitialize the regular Emacs tags searching to the first tags
2020 file, this reinitialization might be considered spurious.
2022 The `M-,' (`po-mark-translatable') command will mark the recently
2023 found string with the `_' keyword. The `M-.'
2024 (`po-select-mark-and-mark') command will request that you type one
2025 keyword from the minibuffer and use that keyword for marking the
2026 string. Both commands will automatically create a new PO file
2027 untranslated entry for the string being marked, and make it the current
2028 entry (making it easy for you to immediately proceed to its
2029 translation, if you feel like doing it right away). It is possible
2030 that the modifications made to the program source by `M-,' or `M-.'
2031 render some source line longer than 80 columns, forcing you to break
2032 and re-indent this line differently. You may use the `O' command from
2033 PO mode, or any other window changing command from Emacs, to break out
2034 into the program source window, and do any needed adjustments. You
2035 will have to use some regular Emacs command to return the cursor to the
2036 PO file window, if you want command `,' for the next string, say.
2038 The `M-.' command has a few built-in speedups, so you do not have to
2039 explicitly type all keywords all the time. The first such speedup is
2040 that you are presented with a _preferred_ keyword, which you may accept
2041 by merely typing `<RET>' at the prompt. The second speedup is that you
2042 may type any non-ambiguous prefix of the keyword you really mean, and
2043 the command will complete it automatically for you. This also means
2044 that PO mode has to _know_ all your possible keywords, and that it will
2045 not accept mistyped keywords.
2047 If you reply `?' to the keyword request, the command gives a list of
2048 all known keywords, from which you may choose. When the command is
2049 prefixed by an argument (`C-u M-.'), it inhibits updating any program
2050 source or PO file buffer, and does some simple keyword management
2051 instead. In this case, the command asks for a keyword, written in
2052 full, which becomes a new allowed keyword for later `M-.' commands.
2053 Moreover, this new keyword automatically becomes the _preferred_
2054 keyword for later commands. By typing an already known keyword in
2055 response to `C-u M-.', one merely changes the _preferred_ keyword and
2058 All keywords known for `M-.' are recognized by the `,' command when
2059 scanning for strings, and strings already marked by any of those known
2060 keywords are automatically skipped. If many PO files are opened
2061 simultaneously, each one has its own independent set of known keywords.
2062 There is no provision in PO mode, currently, for deleting a known
2063 keyword, you have to quit the file (maybe using `q') and reopen it
2064 afresh. When a PO file is newly brought up in an Emacs window, only
2065 `gettext' and `_' are known as keywords, and `gettext' is preferred for
2066 the `M-.' command. In fact, this is not useful to prefer `_', as this
2067 one is already built in the `M-,' command.
2070 File: gettext.info, Node: c-format Flag, Next: Special cases, Prev: Marking, Up: Sources
2072 4.6 Special Comments preceding Keywords
2073 =======================================
2075 In C programs strings are often used within calls of functions from
2076 the `printf' family. The special thing about these format strings is
2077 that they can contain format specifiers introduced with `%'. Assume we
2080 printf (gettext ("String `%s' has %d characters\n"), s, strlen (s));
2082 A possible German translation for the above string might be:
2084 "%d Zeichen lang ist die Zeichenkette `%s'"
2086 A C programmer, even if he cannot speak German, will recognize that
2087 there is something wrong here. The order of the two format specifiers
2088 is changed but of course the arguments in the `printf' don't have.
2089 This will most probably lead to problems because now the length of the
2090 string is regarded as the address.
2092 To prevent errors at runtime caused by translations the `msgfmt'
2093 tool can check statically whether the arguments in the original and the
2094 translation string match in type and number. If this is not the case
2095 and the `-c' option has been passed to `msgfmt', `msgfmt' will give an
2096 error and refuse to produce a MO file. Thus consequent use of `msgfmt
2097 -c' will catch the error, so that it cannot cause cause problems at
2100 If the word order in the above German translation would be correct one
2103 "%2$d Zeichen lang ist die Zeichenkette `%1$s'"
2105 The routines in `msgfmt' know about this special notation.
2107 Because not all strings in a program must be format strings it is not
2108 useful for `msgfmt' to test all the strings in the `.po' file. This
2109 might cause problems because the string might contain what looks like a
2110 format specifier, but the string is not used in `printf'.
2112 Therefore the `xgettext' adds a special tag to those messages it
2113 thinks might be a format string. There is no absolute rule for this,
2114 only a heuristic. In the `.po' file the entry is marked using the
2115 `c-format' flag in the `#,' comment line (*note PO Files::).
2117 The careful reader now might say that this again can cause problems.
2118 The heuristic might guess it wrong. This is true and therefore
2119 `xgettext' knows about a special kind of comment which lets the
2120 programmer take over the decision. If in the same line as or the
2121 immediately preceding line to the `gettext' keyword the `xgettext'
2122 program finds a comment containing the words `xgettext:c-format', it
2123 will mark the string in any case with the `c-format' flag. This kind
2124 of comment should be used when `xgettext' does not recognize the string
2125 as a format string but it really is one and it should be tested.
2126 Please note that when the comment is in the same line as the `gettext'
2127 keyword, it must be before the string to be translated.
2129 This situation happens quite often. The `printf' function is often
2130 called with strings which do not contain a format specifier. Of course
2131 one would normally use `fputs' but it does happen. In this case
2132 `xgettext' does not recognize this as a format string but what happens
2133 if the translation introduces a valid format specifier? The `printf'
2134 function will try to access one of the parameters but none exists
2135 because the original code does not pass any parameters.
2137 `xgettext' of course could make a wrong decision the other way
2138 round, i.e. a string marked as a format string actually is not a format
2139 string. In this case the `msgfmt' might give too many warnings and
2140 would prevent translating the `.po' file. The method to prevent this
2141 wrong decision is similar to the one used above, only the comment to
2142 use must contain the string `xgettext:no-c-format'.
2144 If a string is marked with `c-format' and this is not correct the
2145 user can find out who is responsible for the decision. See *note
2146 xgettext Invocation:: to see how the `--debug' option can be used for
2147 solving this problem.
2150 File: gettext.info, Node: Special cases, Next: Bug Report Address, Prev: c-format Flag, Up: Sources
2152 4.7 Special Cases of Translatable Strings
2153 =========================================
2155 The attentive reader might now point out that it is not always
2156 possible to mark translatable string with `gettext' or something like
2157 this. Consider the following case:
2160 static const char *messages[] = {
2161 "some very meaningful message",
2167 = index > 1 ? "a default message" : messages[index];
2173 While it is no problem to mark the string `"a default message"' it
2174 is not possible to mark the string initializers for `messages'. What
2175 is to be done? We have to fulfill two tasks. First we have to mark the
2176 strings so that the `xgettext' program (*note xgettext Invocation::)
2177 can find them, and second we have to translate the string at runtime
2178 before printing them.
2180 The first task can be fulfilled by creating a new keyword, which
2181 names a no-op. For the second we have to mark all access points to a
2182 string from the array. So one solution can look like this:
2184 #define gettext_noop(String) String
2187 static const char *messages[] = {
2188 gettext_noop ("some very meaningful message"),
2189 gettext_noop ("and another one")
2194 = index > 1 ? gettext ("a default message") : gettext (messages[index]);
2200 Please convince yourself that the string which is written by `fputs'
2201 is translated in any case. How to get `xgettext' know the additional
2202 keyword `gettext_noop' is explained in *note xgettext Invocation::.
2204 The above is of course not the only solution. You could also come
2205 along with the following one:
2207 #define gettext_noop(String) String
2210 static const char *messages[] = {
2211 gettext_noop ("some very meaningful message",
2212 gettext_noop ("and another one")
2217 = index > 1 ? gettext_noop ("a default message") : messages[index];
2219 fputs (gettext (string));
2223 But this has a drawback. The programmer has to take care that he
2224 uses `gettext_noop' for the string `"a default message"'. A use of
2225 `gettext' could have in rare cases unpredictable results.
2227 One advantage is that you need not make control flow analysis to make
2228 sure the output is really translated in any case. But this analysis is
2229 generally not very difficult. If it should be in any situation you can
2230 use this second method in this situation.
2233 File: gettext.info, Node: Bug Report Address, Next: Names, Prev: Special cases, Up: Sources
2235 4.8 Letting Users Report Translation Bugs
2236 =========================================
2238 Code sometimes has bugs, but translations sometimes have bugs too.
2239 The users need to be able to report them. Reporting translation bugs
2240 to the programmer or maintainer of a package is not very useful, since
2241 the maintainer must never change a translation, except on behalf of the
2242 translator. Hence the translation bugs must be reported to the
2245 Here is a way to organize this so that the maintainer does not need
2246 to forward translation bug reports, nor even keep a list of the
2247 addresses of the translators or their translation teams.
2249 Every program has a place where is shows the bug report address. For
2250 GNU programs, it is the code which handles the "-help" option,
2251 typically in a function called "usage". In this place, instruct the
2252 translator to add her own bug reporting address. For example, if that
2253 code has a statement
2255 printf (_("Report bugs to <%s>.\n"), PACKAGE_BUGREPORT);
2257 you can add some translator instructions like this:
2259 /* TRANSLATORS: The placeholder indicates the bug-reporting address
2260 for this package. Please add _another line_ saying
2261 "Report translation bugs to <...>\n" with the address for translation
2262 bugs (typically your translation team's web or email address). */
2263 printf (_("Report bugs to <%s>.\n"), PACKAGE_BUGREPORT);
2265 These will be extracted by `xgettext', leading to a .pot file that
2268 #. TRANSLATORS: The placeholder indicates the bug-reporting address
2269 #. for this package. Please add _another line_ saying
2270 #. "Report translation bugs to <...>\n" with the address for translation
2271 #. bugs (typically your translation team's web or email address).
2274 msgid "Report bugs to <%s>.\n"
2278 File: gettext.info, Node: Names, Next: Libraries, Prev: Bug Report Address, Up: Sources
2280 4.9 Marking Proper Names for Translation
2281 ========================================
2283 Should names of persons, cities, locations etc. be marked for
2284 translation or not? People who only know languages that can be written
2285 with Latin letters (English, Spanish, French, German, etc.) are tempted
2286 to say "no", because names usually do not change when transported
2287 between these languages. However, in general when translating from one
2288 script to another, names are translated too, usually phonetically or by
2289 transliteration. For example, Russian or Greek names are converted to
2290 the Latin alphabet when being translated to English, and English or
2291 French names are converted to the Katakana script when being translated
2292 to Japanese. This is necessary because the speakers of the target
2293 language in general cannot read the script the name is originally
2296 As a programmer, you should therefore make sure that names are marked
2297 for translation, with a special comment telling the translators that it
2298 is a proper name and how to pronounce it. In its simple form, it looks
2301 printf (_("Written by %s.\n"),
2302 /* TRANSLATORS: This is a proper name. See the gettext
2303 manual, section Names. Note this is actually a non-ASCII
2304 name: The first name is (with Unicode escapes)
2305 "Fran\u00e7ois" or (with HTML entities) "François".
2306 Pronunciation is like "fraa-swa pee-nar". */
2307 _("Francois Pinard"));
2309 The GNU gnulib library offers a module `propername'
2310 (`http://www.gnu.org/software/gnulib/MODULES.html#module=propername')
2311 which takes care to automatically append the original name, in
2312 parentheses, to the translated name. For names that cannot be written
2313 in ASCII, it also frees the translator from the task of entering the
2314 appropriate non-ASCII characters if no script change is needed. In
2315 this more comfortable form, it looks like this:
2317 printf (_("Written by %s and %s.\n"),
2318 proper_name ("Ulrich Drepper"),
2319 /* TRANSLATORS: This is a proper name. See the gettext
2320 manual, section Names. Note this is actually a non-ASCII
2321 name: The first name is (with Unicode escapes)
2322 "Fran\u00e7ois" or (with HTML entities) "François".
2323 Pronunciation is like "fraa-swa pee-nar". */
2324 proper_name_utf8 ("Francois Pinard", "Fran\303\247ois Pinard"));
2326 You can also write the original name directly in Unicode (rather than
2327 with Unicode escapes or HTML entities) and denote the pronunciation
2328 using the International Phonetic Alphabet (see
2329 `http://www.wikipedia.org/wiki/International_Phonetic_Alphabet').
2331 As a translator, you should use some care when translating names,
2332 because it is frustrating if people see their names mutilated or
2335 If your language uses the Latin script, all you need to do is to
2336 reproduce the name as perfectly as you can within the usual character
2337 set of your language. In this particular case, this means to provide a
2338 translation containing the c-cedilla character. If your language uses
2339 a different script and the people speaking it don't usually read Latin
2340 words, it means transliteration. If the programmer used the simple
2341 case, you should still give, in parentheses, the original writing of
2342 the name - for the sake of the people that do read the Latin script.
2343 If the programmer used the `propername' module mentioned above, you
2344 don't need to give the original writing of the name in parentheses,
2345 because the program will already do so. Here is an example, using
2346 Greek as the target script:
2348 #. This is a proper name. See the gettext
2349 #. manual, section Names. Note this is actually a non-ASCII
2350 #. name: The first name is (with Unicode escapes)
2351 #. "Fran\u00e7ois" or (with HTML entities) "François".
2352 #. Pronunciation is like "fraa-swa pee-nar".
2353 msgid "Francois Pinard"
2354 msgstr "\phi\rho\alpha\sigma\omicron\alpha \pi\iota\nu\alpha\rho"
2355 " (Francois Pinard)"
2357 Because translation of names is such a sensitive domain, it is a good
2358 idea to test your translation before submitting it.
2361 File: gettext.info, Node: Libraries, Prev: Names, Up: Sources
2363 4.10 Preparing Library Sources
2364 ==============================
2366 When you are preparing a library, not a program, for the use of
2367 `gettext', only a few details are different. Here we assume that the
2368 library has a translation domain and a POT file of its own. (If it
2369 uses the translation domain and POT file of the main program, then the
2370 previous sections apply without changes.)
2372 1. The library code doesn't call `setlocale (LC_ALL, "")'. It's the
2373 responsibility of the main program to set the locale. The
2374 library's documentation should mention this fact, so that
2375 developers of programs using the library are aware of it.
2377 2. The library code doesn't call `textdomain (PACKAGE)', because it
2378 would interfere with the text domain set by the main program.
2380 3. The initialization code for a program was
2382 setlocale (LC_ALL, "");
2383 bindtextdomain (PACKAGE, LOCALEDIR);
2384 textdomain (PACKAGE);
2386 For a library it is reduced to
2388 bindtextdomain (PACKAGE, LOCALEDIR);
2390 If your library's API doesn't already have an initialization
2391 function, you need to create one, containing at least the
2392 `bindtextdomain' invocation. However, you usually don't need to
2393 export and document this initialization function: It is sufficient
2394 that all entry points of the library call the initialization
2395 function if it hasn't been called before. The typical idiom used
2396 to achieve this is a static boolean variable that indicates
2397 whether the initialization function has been called. Like this:
2399 static bool libfoo_initialized;
2402 libfoo_initialize (void)
2404 bindtextdomain (PACKAGE, LOCALEDIR);
2405 libfoo_initialized = true;
2408 /* This function is part of the exported API. */
2412 /* Must ensure the initialization is performed. */
2413 if (!libfoo_initialized)
2414 libfoo_initialize ();
2418 /* This function is part of the exported API. The argument must be
2419 non-NULL and have been created through create_foo(). */
2421 foo_refcount (struct foo *argument)
2423 /* No need to invoke the initialization function here, because
2424 create_foo() must already have been called before. */
2428 4. The usual declaration of the `_' macro in each source file was
2430 #include <libintl.h>
2431 #define _(String) gettext (String)
2433 for a program. For a library, which has its own translation
2434 domain, it reads like this:
2436 #include <libintl.h>
2437 #define _(String) dgettext (PACKAGE, String)
2439 In other words, `dgettext' is used instead of `gettext'.
2440 Similarly, the `dngettext' function should be used in place of the
2441 `ngettext' function.
2444 File: gettext.info, Node: Template, Next: Creating, Prev: Sources, Up: Top
2446 5 Making the PO Template File
2447 *****************************
2449 After preparing the sources, the programmer creates a PO template
2450 file. This section explains how to use `xgettext' for this purpose.
2452 `xgettext' creates a file named `DOMAINNAME.po'. You should then
2453 rename it to `DOMAINNAME.pot'. (Why doesn't `xgettext' create it under
2454 the name `DOMAINNAME.pot' right away? The answer is: for historical
2455 reasons. When `xgettext' was specified, the distinction between a PO
2456 file and PO file template was fuzzy, and the suffix `.pot' wasn't in
2461 * xgettext Invocation:: Invoking the `xgettext' Program
2464 File: gettext.info, Node: xgettext Invocation, Prev: Template, Up: Template
2466 5.1 Invoking the `xgettext' Program
2467 ===================================
2469 xgettext [OPTION] [INPUTFILE] ...
2471 The `xgettext' program extracts translatable strings from given
2474 5.1.1 Input file location
2475 -------------------------
2482 Read the names of the input files from FILE instead of getting
2483 them from the command line.
2486 `--directory=DIRECTORY'
2487 Add DIRECTORY to the list of directories. Source files are
2488 searched relative to this list of directories. The resulting `.po'
2489 file will be written relative to the current directory, though.
2492 If INPUTFILE is `-', standard input is read.
2494 5.1.2 Output file location
2495 --------------------------
2498 `--default-domain=NAME'
2499 Use `NAME.po' for output (instead of `messages.po').
2503 Write output to specified file (instead of `NAME.po' or
2508 Output files will be placed in directory DIR.
2511 If the output FILE is `-' or `/dev/stdout', the output is written to
2514 5.1.3 Choice of input file language
2515 -----------------------------------
2519 Specifies the language of the input files. The supported languages
2520 are `C', `C++', `ObjectiveC', `PO', `Python', `Lisp', `EmacsLisp',
2521 `librep', `Scheme', `Smalltalk', `Java', `JavaProperties', `C#',
2522 `awk', `YCP', `Tcl', `Perl', `PHP', `GCC-source', `NXStringTable',
2527 This is a shorthand for `--language=C++'.
2530 By default the language is guessed depending on the input file name
2533 5.1.4 Input file interpretation
2534 -------------------------------
2537 Specifies the encoding of the input files. This option is needed
2538 only if some untranslated message strings or their corresponding
2539 comments contain non-ASCII characters. Note that Tcl and Glade
2540 input files are always assumed to be in UTF-8, regardless of this
2544 By default the input files are assumed to be in ASCII.
2546 5.1.5 Operation mode
2547 --------------------
2551 Join messages with existing file.
2554 `--exclude-file=FILE'
2555 Entries from FILE are not extracted. FILE should be a PO or POT
2559 `--add-comments[=TAG]'
2560 Place comment blocks starting with TAG and preceding keyword lines
2561 in the output file. Without a TAG, the option means to put _all_
2562 comment blocks preceding keyword lines in the output file.
2565 5.1.6 Language specific options
2566 -------------------------------
2570 Extract all strings.
2572 This option has an effect with most languages, namely C, C++,
2573 ObjectiveC, Shell, Python, Lisp, EmacsLisp, librep, Java, C#, awk,
2574 Tcl, Perl, PHP, GCC-source, Glade.
2577 `--keyword[=KEYWORDSPEC]'
2578 Specify KEYWORDSPEC as an additional keyword to be looked for.
2579 Without a KEYWORDSPEC, the option means to not use default
2582 If KEYWORDSPEC is a C identifier ID, `xgettext' looks for strings
2583 in the first argument of each call to the function or macro ID.
2584 If KEYWORDSPEC is of the form `ID:ARGNUM', `xgettext' looks for
2585 strings in the ARGNUMth argument of the call. If KEYWORDSPEC is
2586 of the form `ID:ARGNUM1,ARGNUM2', `xgettext' looks for strings in
2587 the ARGNUM1st argument and in the ARGNUM2nd argument of the call,
2588 and treats them as singular/plural variants for a message with
2589 plural handling. Also, if KEYWORDSPEC is of the form
2590 `ID:CONTEXTARGNUMc,ARGNUM' or `ID:ARGNUM,CONTEXTARGNUMc',
2591 `xgettext' treats strings in the CONTEXTARGNUMth argument as a
2592 context specifier. And, as a special-purpose support for GNOME,
2593 if KEYWORDSPEC is of the form `ID:ARGNUMg', `xgettext' recognizes
2594 the ARGNUMth argument as a string with context, using the GNOME
2595 `glib' syntax `"msgctxt|msgid"'.
2596 Furthermore, if KEYWORDSPEC is of the form `ID:...,TOTALNUMARGSt',
2597 `xgettext' recognizes this argument specification only if the
2598 number of actual arguments is equal to TOTALNUMARGS. This is
2599 useful for disambiguating overloaded function calls in C++.
2600 Finally, if KEYWORDSPEC is of the form `ID:ARGNUM...,"XCOMMENT"',
2601 `xgettext', when extracting a message from the specified argument
2602 strings, adds an extracted comment XCOMMENT to the message. Note
2603 that when used through a normal shell command line, the
2604 double-quotes around the XCOMMENT need to be escaped.
2606 This option has an effect with most languages, namely C, C++,
2607 ObjectiveC, Shell, Python, Lisp, EmacsLisp, librep, Java, C#, awk,
2608 Tcl, Perl, PHP, GCC-source, Glade.
2610 The default keyword specifications, which are always looked for if
2611 not explicitly disabled, are language dependent. They are:
2613 * For C, C++, and GCC-source: `gettext', `dgettext:2',
2614 `dcgettext:2', `ngettext:1,2', `dngettext:2,3',
2615 `dcngettext:2,3', `gettext_noop', and `pgettext:1c,2',
2616 `dpgettext:2c,3', `dcpgettext:2c,3', `npgettext:1c,2,3',
2617 `dnpgettext:2c,3,4', `dcnpgettext:2c,3,4'.
2619 * For Objective C: Like for C, and also `NSLocalizedString',
2620 `_', `NSLocalizedStaticString', `__'.
2622 * For Shell scripts: `gettext', `ngettext:1,2', `eval_gettext',
2623 `eval_ngettext:1,2'.
2625 * For Python: `gettext', `ugettext', `dgettext:2',
2626 `ngettext:1,2', `ungettext:1,2', `dngettext:2,3', `_'.
2628 * For Lisp: `gettext', `ngettext:1,2', `gettext-noop'.
2630 * For EmacsLisp: `_'.
2634 * For Scheme: `gettext', `ngettext:1,2', `gettext-noop'.
2636 * For Java: `GettextResource.gettext:2',
2637 `GettextResource.ngettext:2,3',
2638 `GettextResource.pgettext:2c,3',
2639 `GettextResource.npgettext:2c,3,4', `gettext', `ngettext:1,2',
2640 `pgettext:1c,2', `npgettext:1c,2,3', `getString'.
2642 * For C#: `GetString', `GetPluralString:1,2',
2643 `GetParticularString:1c,2',
2644 `GetParticularPluralString:1c,2,3'.
2646 * For awk: `dcgettext', `dcngettext:1,2'.
2648 * For Tcl: `::msgcat::mc'.
2650 * For Perl: `gettext', `%gettext', `$gettext', `dgettext:2',
2651 `dcgettext:2', `ngettext:1,2', `dngettext:2,3',
2652 `dcngettext:2,3', `gettext_noop'.
2654 * For PHP: `_', `gettext', `dgettext:2', `dcgettext:2',
2655 `ngettext:1,2', `dngettext:2,3', `dcngettext:2,3'.
2657 * For Glade 1: `label', `title', `text', `format', `copyright',
2658 `comments', `preview_text', `tooltip'.
2660 To disable the default keyword specifications, the option `-k' or
2661 `--keyword' or `--keyword=', without a KEYWORDSPEC, can be used.
2663 `--flag=WORD:ARG:FLAG'
2664 Specifies additional flags for strings occurring as part of the
2665 ARGth argument of the function WORD. The possible flags are the
2666 possible format string indicators, such as `c-format', and their
2667 negations, such as `no-c-format', possibly prefixed with `pass-'.
2668 The meaning of `--flag=FUNCTION:ARG:LANG-format' is that in
2669 language LANG, the specified FUNCTION expects as ARGth argument a
2670 format string. (For those of you familiar with GCC function
2671 attributes, `--flag=FUNCTION:ARG:c-format' is roughly equivalent
2672 to the declaration `__attribute__ ((__format__ (__printf__, ARG,
2673 ...)))' attached to FUNCTION in a C source file.) For example, if
2674 you use the `error' function from GNU libc, you can specify its
2675 behaviour through `--flag=error:3:c-format'. The effect of this
2676 specification is that `xgettext' will mark as format strings all
2677 `gettext' invocations that occur as ARGth argument of FUNCTION.
2678 This is useful when such strings contain no format string
2679 directives: together with the checks done by `msgfmt -c' it will
2680 ensure that translators cannot accidentally use format string
2681 directives that would lead to a crash at runtime.
2682 The meaning of `--flag=FUNCTION:ARG:pass-LANG-format' is that in
2683 language LANG, if the FUNCTION call occurs in a position that must
2684 yield a format string, then its ARGth argument must yield a format
2685 string of the same type as well. (If you know GCC function
2686 attributes, the `--flag=FUNCTION:ARG:pass-c-format' option is
2687 roughly equivalent to the declaration `__attribute__
2688 ((__format_arg__ (ARG)))' attached to FUNCTION in a C source file.)
2689 For example, if you use the `_' shortcut for the `gettext'
2690 function, you should use `--flag=_:1:pass-c-format'. The effect
2691 of this specification is that `xgettext' will propagate a format
2692 string requirement for a `_("string")' call to its first argument,
2693 the literal `"string"', and thus mark it as a format string. This
2694 is useful when such strings contain no format string directives:
2695 together with the checks done by `msgfmt -c' it will ensure that
2696 translators cannot accidentally use format string directives that
2697 would lead to a crash at runtime.
2698 This option has an effect with most languages, namely C, C++,
2699 ObjectiveC, Shell, Python, Lisp, EmacsLisp, librep, Scheme, Java,
2700 C#, awk, YCP, Tcl, Perl, PHP, GCC-source.
2704 Understand ANSI C trigraphs for input.
2705 This option has an effect only with the languages C, C++,
2709 Recognize Qt format strings.
2710 This option has an effect only with the language C++.
2713 Recognize KDE 4 format strings.
2714 This option has an effect only with the language C++.
2717 Recognize Boost format strings.
2718 This option has an effect only with the language C++.
2721 Use the flags `c-format' and `possible-c-format' to show who was
2722 responsible for marking a message as a format string. The latter
2723 form is used if the `xgettext' program decided, the format form is
2724 used if the programmer prescribed it.
2726 By default only the `c-format' form is used. The translator should
2727 not have to care about these details.
2730 This implementation of `xgettext' is able to process a few awkward
2731 cases, like strings in preprocessor macros, ANSI concatenation of
2732 adjacent strings, and escaped end of lines for continued strings.
2734 5.1.7 Output details
2735 --------------------
2739 Specify whether or when to use colors and other text attributes.
2740 See *note The --color option:: for details.
2742 `--style=STYLE_FILE'
2743 Specify the CSS style rule file to use for `--color'. See *note
2744 The --style option:: for details.
2747 Always write an output file even if no message is defined.
2751 Write the .po file using indented style.
2754 Do not write `#: FILENAME:LINE' lines. Note that using this
2755 option makes it harder for technically skilled translators to
2756 understand each message's context.
2760 Generate `#: FILENAME:LINE' lines (default).
2763 Write out a strict Uniforum conforming PO file. Note that this
2764 Uniforum format should be avoided because it doesn't support the
2767 `--properties-output'
2768 Write out a Java ResourceBundle in Java `.properties' syntax. Note
2769 that this file format doesn't support plural forms and silently
2770 drops obsolete messages.
2772 `--stringtable-output'
2773 Write out a NeXTstep/GNUstep localized resource file in `.strings'
2774 syntax. Note that this file format doesn't support plural forms.
2778 Set the output page width. Long strings in the output files will
2779 be split across multiple lines in order to ensure that each line's
2780 width (= number of screen columns) is less or equal to the given
2784 Do not break long message lines. Message lines whose width
2785 exceeds the output page width will not be split into several
2786 lines. Only file reference lines which are wider than the output
2787 page width will be split.
2791 Generate sorted output. Note that using this option makes it much
2792 harder for the translator to understand each message's context.
2796 Sort output by file location.
2799 Don't write header with `msgid ""' entry.
2801 This is useful for testing purposes because it eliminates a source
2802 of variance for generated `.gmo' files. With `--omit-header', two
2803 invocations of `xgettext' on the same files with the same options
2804 at different times are guaranteed to produce the same results.
2806 Note that using this option will lead to an error if the resulting
2807 file would not entirely be in ASCII.
2809 `--copyright-holder=STRING'
2810 Set the copyright holder in the output. STRING should be the
2811 copyright holder of the surrounding package. (Note that the msgstr
2812 strings, extracted from the package's sources, belong to the
2813 copyright holder of the package.) Translators are expected to
2814 transfer or disclaim the copyright for their translations, so that
2815 package maintainers can distribute them without legal risk. If
2816 STRING is empty, the output files are marked as being in the
2817 public domain; in this case, the translators are expected to
2818 disclaim their copyright, again so that package maintainers can
2819 distribute them without legal risk.
2821 The default value for STRING is the Free Software Foundation, Inc.,
2822 simply because `xgettext' was first used in the GNU project.
2825 Omit FSF copyright in output. This option is equivalent to
2826 `--copyright-holder='''. It can be useful for packages outside
2827 the GNU project that want their translations to be in the public
2830 `--package-name=PACKAGE'
2831 Set the package name in the header of the output.
2833 `--package-version=VERSION'
2834 Set the package version in the header of the output. This option
2835 has an effect only if the `--package-name' option is also used.
2837 `--msgid-bugs-address=EMAIL@ADDRESS'
2838 Set the reporting address for msgid bugs. This is the email
2839 address or URL to which the translators shall report bugs in the
2840 untranslated strings:
2842 - Strings which are not entire sentences, see the maintainer
2843 guidelines in *note Preparing Strings::.
2845 - Strings which use unclear terms or require additional context
2848 - Strings which make invalid assumptions about notation of
2849 date, time or money.
2851 - Pluralisation problems.
2853 - Incorrect English spelling.
2855 - Incorrect formatting.
2857 It can be your email address, or a mailing list address where
2858 translators can write to without being subscribed, or the URL of a
2859 web page through which the translators can contact you.
2861 The default value is empty, which means that translators will be
2862 clueless! Don't forget to specify this option.
2865 `--msgstr-prefix[=STRING]'
2866 Use STRING (or "" if not specified) as prefix for msgstr values.
2869 `--msgstr-suffix[=STRING]'
2870 Use STRING (or "" if not specified) as suffix for msgstr values.
2873 5.1.8 Informative output
2874 ------------------------
2878 Display this help and exit.
2882 Output version information and exit.
2886 File: gettext.info, Node: Creating, Next: Updating, Prev: Template, Up: Top
2888 6 Creating a New PO File
2889 ************************
2891 When starting a new translation, the translator creates a file called
2892 `LANG.po', as a copy of the `PACKAGE.pot' template file with
2893 modifications in the initial comments (at the beginning of the file)
2894 and in the header entry (the first entry, near the beginning of the
2897 The easiest way to do so is by use of the `msginit' program. For
2900 $ cd PACKAGE-VERSION
2904 The alternative way is to do the copy and modifications by hand. To
2905 do so, the translator copies `PACKAGE.pot' to `LANG.po'. Then she
2906 modifies the initial comments and the header entry of this file.
2910 * msginit Invocation:: Invoking the `msginit' Program
2911 * Header Entry:: Filling in the Header Entry
2914 File: gettext.info, Node: msginit Invocation, Next: Header Entry, Prev: Creating, Up: Creating
2916 6.1 Invoking the `msginit' Program
2917 ==================================
2921 The `msginit' program creates a new PO file, initializing the meta
2922 information with values from the user's environment.
2924 6.1.1 Input file location
2925 -------------------------
2932 If no INPUTFILE is given, the current directory is searched for the
2933 POT file. If it is `-', standard input is read.
2935 6.1.2 Output file location
2936 --------------------------
2939 `--output-file=FILE'
2940 Write output to specified PO file.
2943 If no output file is given, it depends on the `--locale' option or
2944 the user's locale setting. If it is `-', the results are written to
2947 6.1.3 Input file syntax
2948 -----------------------
2951 `--properties-input'
2952 Assume the input file is a Java ResourceBundle in Java
2953 `.properties' syntax, not in PO file syntax.
2955 `--stringtable-input'
2956 Assume the input file is a NeXTstep/GNUstep localized resource
2957 file in `.strings' syntax, not in PO file syntax.
2960 6.1.4 Output details
2961 --------------------
2965 Set target locale. LL should be a language code, and CC should be
2966 a country code. The command `locale -a' can be used to output a
2967 list of all installed locales. The default is the user's locale
2971 Declares that the PO file will not have a human translator and is
2972 instead automatically generated.
2976 Specify whether or when to use colors and other text attributes.
2977 See *note The --color option:: for details.
2979 `--style=STYLE_FILE'
2980 Specify the CSS style rule file to use for `--color'. See *note
2981 The --style option:: for details.
2984 `--properties-output'
2985 Write out a Java ResourceBundle in Java `.properties' syntax. Note
2986 that this file format doesn't support plural forms and silently
2987 drops obsolete messages.
2989 `--stringtable-output'
2990 Write out a NeXTstep/GNUstep localized resource file in `.strings'
2991 syntax. Note that this file format doesn't support plural forms.
2995 Set the output page width. Long strings in the output files will
2996 be split across multiple lines in order to ensure that each line's
2997 width (= number of screen columns) is less or equal to the given
3001 Do not break long message lines. Message lines whose width
3002 exceeds the output page width will not be split into several
3003 lines. Only file reference lines which are wider than the output
3004 page width will be split.
3007 6.1.5 Informative output
3008 ------------------------
3012 Display this help and exit.
3016 Output version information and exit.
3020 File: gettext.info, Node: Header Entry, Prev: msginit Invocation, Up: Creating
3022 6.2 Filling in the Header Entry
3023 ===============================
3025 The initial comments "SOME DESCRIPTIVE TITLE", "YEAR" and "FIRST
3026 AUTHOR <EMAIL@ADDRESS>, YEAR" ought to be replaced by sensible
3027 information. This can be done in any text editor; if Emacs is used and
3028 it switched to PO mode automatically (because it has recognized the
3029 file's suffix), you can disable it by typing `M-x fundamental-mode'.
3031 Modifying the header entry can already be done using PO mode: in
3032 Emacs, type `M-x po-mode RET' and then `RET' again to start editing the
3033 entry. You should fill in the following fields.
3036 This is the name and version of the package. Fill it in if it has
3037 not already been filled in by `xgettext'.
3039 Report-Msgid-Bugs-To
3040 This has already been filled in by `xgettext'. It contains an
3041 email address or URL where you can report bugs in the untranslated
3044 - Strings which are not entire sentences, see the maintainer
3045 guidelines in *note Preparing Strings::.
3047 - Strings which use unclear terms or require additional context
3050 - Strings which make invalid assumptions about notation of
3051 date, time or money.
3053 - Pluralisation problems.
3055 - Incorrect English spelling.
3057 - Incorrect formatting.
3060 This has already been filled in by `xgettext'.
3063 You don't need to fill this in. It will be filled by the PO file
3064 editor when you save the file.
3067 Fill in your name and email address (without double quotes).
3070 Fill in the English name of the language, and the email address or
3071 homepage URL of the language team you are part of.
3073 Before starting a translation, it is a good idea to get in touch
3074 with your translation team, not only to make sure you don't do
3075 duplicated work, but also to coordinate difficult linguistic
3078 In the Free Translation Project, each translation team has its own
3079 mailing list. The up-to-date list of teams can be found at the
3080 Free Translation Project's homepage,
3081 `http://translationproject.org/', in the "Teams" area.
3084 Fill in the language code of the language. This can be in one of
3087 - `LL', an ISO 639 two-letter language code (lowercase). See
3088 *note Language Codes:: for the list of codes.
3090 - `LL_CC', where `LL' is an ISO 639 two-letter language code
3091 (lowercase) and `CC' is an ISO 3166 two-letter country code
3092 (uppercase). The country code specification is not redundant:
3093 Some languages have dialects in different countries. For
3094 example, `de_AT' is used for Austria, and `pt_BR' for Brazil.
3095 The country code serves to distinguish the dialects. See
3096 *note Language Codes:: and *note Country Codes:: for the
3099 - `LL_CC@VARIANT', where `LL' is an ISO 639 two-letter language
3100 code (lowercase), `CC' is an ISO 3166 two-letter country code
3101 (uppercase), and `VARIANT' is a variant designator. The
3102 variant designator (lowercase) can be a script designator,
3103 such as `latin' or `cyrillic'.
3105 The naming convention `LL_CC' is also the way locales are named on
3106 systems based on GNU libc. But there are three important
3109 * In this PO file field, but not in locale names, `LL_CC'
3110 combinations denoting a language's main dialect are
3111 abbreviated as `LL'. For example, `de' is equivalent to
3112 `de_DE' (German as spoken in Germany), and `pt' to `pt_PT'
3113 (Portuguese as spoken in Portugal) in this context.
3115 * In this PO file field, suffixes like `.ENCODING' are not used.
3117 * In this PO file field, variant designators that are not
3118 relevant to message translation, such as `@euro', are not
3121 So, if your locale name is `de_DE.UTF-8', the language
3122 specification in PO files is just `de'.
3125 Replace `CHARSET' with the character encoding used for your
3126 language, in your locale, or UTF-8. This field is needed for
3127 correct operation of the `msgmerge' and `msgfmt' programs, as well
3128 as for users whose locale's character encoding differs from yours
3129 (see *note Charset conversion::).
3131 You get the character encoding of your locale by running the shell
3132 command `locale charmap'. If the result is `C' or
3133 `ANSI_X3.4-1968', which is equivalent to `ASCII' (= `US-ASCII'),
3134 it means that your locale is not correctly configured. In this
3135 case, ask your translation team which charset to use. `ASCII' is
3136 not usable for any language except Latin.
3138 Because the PO files must be portable to operating systems with
3139 less advanced internationalization facilities, the character
3140 encodings that can be used are limited to those supported by both
3141 GNU `libc' and GNU `libiconv'. These are: `ASCII', `ISO-8859-1',
3142 `ISO-8859-2', `ISO-8859-3', `ISO-8859-4', `ISO-8859-5',
3143 `ISO-8859-6', `ISO-8859-7', `ISO-8859-8', `ISO-8859-9',
3144 `ISO-8859-13', `ISO-8859-14', `ISO-8859-15', `KOI8-R', `KOI8-U',
3145 `KOI8-T', `CP850', `CP866', `CP874', `CP932', `CP949', `CP950',
3146 `CP1250', `CP1251', `CP1252', `CP1253', `CP1254', `CP1255',
3147 `CP1256', `CP1257', `GB2312', `EUC-JP', `EUC-KR', `EUC-TW',
3148 `BIG5', `BIG5-HKSCS', `GBK', `GB18030', `SHIFT_JIS', `JOHAB',
3149 `TIS-620', `VISCII', `GEORGIAN-PS', `UTF-8'.
3151 In the GNU system, the following encodings are frequently used for
3152 the corresponding languages.
3154 * `ISO-8859-1' for Afrikaans, Albanian, Basque, Breton,
3155 Catalan, Cornish, Danish, Dutch, English, Estonian, Faroese,
3156 Finnish, French, Galician, German, Greenlandic, Icelandic,
3157 Indonesian, Irish, Italian, Malay, Manx, Norwegian, Occitan,
3158 Portuguese, Spanish, Swedish, Tagalog, Uzbek, Walloon,
3160 * `ISO-8859-2' for Bosnian, Croatian, Czech, Hungarian, Polish,
3161 Romanian, Serbian, Slovak, Slovenian,
3163 * `ISO-8859-3' for Maltese,
3165 * `ISO-8859-5' for Macedonian, Serbian,
3167 * `ISO-8859-6' for Arabic,
3169 * `ISO-8859-7' for Greek,
3171 * `ISO-8859-8' for Hebrew,
3173 * `ISO-8859-9' for Turkish,
3175 * `ISO-8859-13' for Latvian, Lithuanian, Maori,
3177 * `ISO-8859-14' for Welsh,
3179 * `ISO-8859-15' for Basque, Catalan, Dutch, English, Finnish,
3180 French, Galician, German, Irish, Italian, Portuguese,
3181 Spanish, Swedish, Walloon,
3183 * `KOI8-R' for Russian,
3185 * `KOI8-U' for Ukrainian,
3187 * `KOI8-T' for Tajik,
3189 * `CP1251' for Bulgarian, Belarusian,
3191 * `GB2312', `GBK', `GB18030' for simplified writing of Chinese,
3193 * `BIG5', `BIG5-HKSCS' for traditional writing of Chinese,
3195 * `EUC-JP' for Japanese,
3197 * `EUC-KR' for Korean,
3199 * `TIS-620' for Thai,
3201 * `GEORGIAN-PS' for Georgian,
3203 * `UTF-8' for any language, including those listed above.
3205 When single quote characters or double quote characters are used in
3206 translations for your language, and your locale's encoding is one
3207 of the ISO-8859-* charsets, it is best if you create your PO files
3208 in UTF-8 encoding, instead of your locale's encoding. This is
3209 because in UTF-8 the real quote characters can be represented
3210 (single quote characters: U+2018, U+2019, double quote characters:
3211 U+201C, U+201D), whereas none of ISO-8859-* charsets has them all.
3212 Users in UTF-8 locales will see the real quote characters, whereas
3213 users in ISO-8859-* locales will see the vertical apostrophe and
3214 the vertical double quote instead (because that's what the
3215 character set conversion will transliterate them to).
3217 To enter such quote characters under X11, you can change your
3218 keyboard mapping using the `xmodmap' program. The X11 names of
3219 the quote characters are "leftsinglequotemark",
3220 "rightsinglequotemark", "leftdoublequotemark",
3221 "rightdoublequotemark", "singlelowquotemark", "doublelowquotemark".
3223 Note that only recent versions of GNU Emacs support the UTF-8
3224 encoding: Emacs 20 with Mule-UCS, and Emacs 21. As of January
3225 2001, XEmacs doesn't support the UTF-8 encoding.
3227 The character encoding name can be written in either upper or
3228 lower case. Usually upper case is preferred.
3230 Content-Transfer-Encoding
3234 This field is optional. It is only needed if the PO file has
3235 plural forms. You can find them by searching for the
3236 `msgid_plural' keyword. The format of the plural forms field is
3237 described in *note Plural forms:: and *note Translating plural
3241 File: gettext.info, Node: Updating, Next: Editing, Prev: Creating, Up: Top
3243 7 Updating Existing PO Files
3244 ****************************
3248 * msgmerge Invocation:: Invoking the `msgmerge' Program
3251 File: gettext.info, Node: msgmerge Invocation, Prev: Updating, Up: Updating
3253 7.1 Invoking the `msgmerge' Program
3254 ===================================
3256 msgmerge [OPTION] DEF.po REF.pot
3258 The `msgmerge' program merges two Uniforum style .po files together.
3259 The DEF.po file is an existing PO file with translations which will be
3260 taken over to the newly created file as long as they still match;
3261 comments will be preserved, but extracted comments and file positions
3262 will be discarded. The REF.pot file is the last created PO file with
3263 up-to-date source references but old translations, or a PO Template file
3264 (generally created by `xgettext'); any translations or comments in the
3265 file will be discarded, however dot comments and file positions will be
3266 preserved. Where an exact match cannot be found, fuzzy matching is
3267 used to produce better results.
3269 7.1.1 Input file location
3270 -------------------------
3273 Translations referring to old sources.
3276 References to the new sources.
3279 `--directory=DIRECTORY'
3280 Add DIRECTORY to the list of directories. Source files are
3281 searched relative to this list of directories. The resulting `.po'
3282 file will be written relative to the current directory, though.
3286 Specify an additional library of message translations. *Note
3287 Compendium::. This option may be specified more than once.
3290 7.1.2 Operation mode
3291 --------------------
3295 Update DEF.po. Do nothing if DEF.po is already up to date.
3298 7.1.3 Output file location
3299 --------------------------
3302 `--output-file=FILE'
3303 Write output to specified file.
3306 The results are written to standard output if no output file is
3307 specified or if it is `-'.
3309 7.1.4 Output file location in update mode
3310 -----------------------------------------
3312 The result is written back to DEF.po.
3315 Make a backup of DEF.po
3318 Override the usual backup suffix.
3321 The version control method may be selected via the `--backup' option
3322 or through the `VERSION_CONTROL' environment variable. Here are the
3327 Never make backups (even if `--backup' is given).
3331 Make numbered backups.
3335 Make numbered backups if numbered backups for this file already
3336 exist, otherwise make simple backups.
3340 Always make simple backups.
3343 The backup suffix is `~', unless set with `--suffix' or the
3344 `SIMPLE_BACKUP_SUFFIX' environment variable.
3346 7.1.5 Operation modifiers
3347 -------------------------
3351 Apply REF.pot to each of the domains in DEF.po.
3354 `--no-fuzzy-matching'
3355 Do not use fuzzy matching when an exact match is not found. This
3356 may speed up the operation considerably.
3359 Keep the previous msgids of translated messages, marked with `#|',
3360 when adding the fuzzy marker to such messages.
3362 7.1.6 Input file syntax
3363 -----------------------
3366 `--properties-input'
3367 Assume the input files are Java ResourceBundles in Java
3368 `.properties' syntax, not in PO file syntax.
3370 `--stringtable-input'
3371 Assume the input files are NeXTstep/GNUstep localized resource
3372 files in `.strings' syntax, not in PO file syntax.
3375 7.1.7 Output details
3376 --------------------
3378 `--lang=CATALOGNAME'
3379 Specify the `Language' field to be used in the header entry. See
3380 *note Header Entry:: for the meaning of this field. Note: The
3381 `Language-Team' and `Plural-Forms' fields are left unchanged. If
3382 this option is not specified, the `Language' field is inferred, as
3383 best as possible, from the `Language-Team' field.
3387 Specify whether or when to use colors and other text attributes.
3388 See *note The --color option:: for details.
3390 `--style=STYLE_FILE'
3391 Specify the CSS style rule file to use for `--color'. See *note
3392 The --style option:: for details.
3395 Always write an output file even if it contains no message.
3399 Write the .po file using indented style.
3402 Do not write `#: FILENAME:LINE' lines.
3405 Generate `#: FILENAME:LINE' lines (default).
3408 Write out a strict Uniforum conforming PO file. Note that this
3409 Uniforum format should be avoided because it doesn't support the
3413 `--properties-output'
3414 Write out a Java ResourceBundle in Java `.properties' syntax. Note
3415 that this file format doesn't support plural forms and silently
3416 drops obsolete messages.
3418 `--stringtable-output'
3419 Write out a NeXTstep/GNUstep localized resource file in `.strings'
3420 syntax. Note that this file format doesn't support plural forms.
3424 Set the output page width. Long strings in the output files will
3425 be split across multiple lines in order to ensure that each line's
3426 width (= number of screen columns) is less or equal to the given
3430 Do not break long message lines. Message lines whose width
3431 exceeds the output page width will not be split into several
3432 lines. Only file reference lines which are wider than the output
3433 page width will be split.
3437 Generate sorted output. Note that using this option makes it much
3438 harder for the translator to understand each message's context.
3442 Sort output by file location.
3445 7.1.8 Informative output
3446 ------------------------
3450 Display this help and exit.
3454 Output version information and exit.
3458 Increase verbosity level.
3463 Suppress progress indicators.
3467 File: gettext.info, Node: Editing, Next: Manipulating, Prev: Updating, Up: Top
3474 * KBabel:: KDE's PO File Editor
3475 * Gtranslator:: GNOME's PO File Editor
3476 * PO Mode:: Emacs's PO File Editor
3477 * Compendium:: Using Translation Compendia
3480 File: gettext.info, Node: KBabel, Next: Gtranslator, Prev: Editing, Up: Editing
3482 8.1 KDE's PO File Editor
3483 ========================
3486 File: gettext.info, Node: Gtranslator, Next: PO Mode, Prev: KBabel, Up: Editing
3488 8.2 GNOME's PO File Editor
3489 ==========================
3492 File: gettext.info, Node: PO Mode, Next: Compendium, Prev: Gtranslator, Up: Editing
3494 8.3 Emacs's PO File Editor
3495 ==========================
3497 For those of you being the lucky users of Emacs, PO mode has been
3498 specifically created for providing a cozy environment for editing or
3499 modifying PO files. While editing a PO file, PO mode allows for the
3500 easy browsing of auxiliary and compendium PO files, as well as for
3501 following references into the set of C program sources from which PO
3502 files have been derived. It has a few special features, among which
3503 are the interactive marking of program strings as translatable, and the
3504 validation of PO files with easy repositioning to PO file lines showing
3507 For the beginning, besides main PO mode commands (*note Main PO
3508 Commands::), you should know how to move between entries (*note Entry
3509 Positioning::), and how to handle untranslated entries (*note
3510 Untranslated Entries::).
3514 * Installation:: Completing GNU `gettext' Installation
3515 * Main PO Commands:: Main Commands
3516 * Entry Positioning:: Entry Positioning
3517 * Normalizing:: Normalizing Strings in Entries
3518 * Translated Entries:: Translated Entries
3519 * Fuzzy Entries:: Fuzzy Entries
3520 * Untranslated Entries:: Untranslated Entries
3521 * Obsolete Entries:: Obsolete Entries
3522 * Modifying Translations:: Modifying Translations
3523 * Modifying Comments:: Modifying Comments
3524 * Subedit:: Mode for Editing Translations
3525 * C Sources Context:: C Sources Context
3526 * Auxiliary:: Consulting Auxiliary PO Files
3529 File: gettext.info, Node: Installation, Next: Main PO Commands, Prev: PO Mode, Up: PO Mode
3531 8.3.1 Completing GNU `gettext' Installation
3532 -------------------------------------------
3534 Once you have received, unpacked, configured and compiled the GNU
3535 `gettext' distribution, the `make install' command puts in place the
3536 programs `xgettext', `msgfmt', `gettext', and `msgmerge', as well as
3537 their available message catalogs. To top off a comfortable
3538 installation, you might also want to make the PO mode available to your
3541 During the installation of the PO mode, you might want to modify your
3542 file `.emacs', once and for all, so it contains a few lines looking
3545 (setq auto-mode-alist
3546 (cons '("\\.po\\'\\|\\.po\\." . po-mode) auto-mode-alist))
3547 (autoload 'po-mode "po-mode" "Major mode for translators to edit PO files" t)
3549 Later, whenever you edit some `.po' file, or any file having the
3550 string `.po.' within its name, Emacs loads `po-mode.elc' (or
3551 `po-mode.el') as needed, and automatically activates PO mode commands
3552 for the associated buffer. The string _PO_ appears in the mode line
3553 for any buffer for which PO mode is active. Many PO files may be
3554 active at once in a single Emacs session.
3556 If you are using Emacs version 20 or newer, and have already
3557 installed the appropriate international fonts on your system, you may
3558 also tell Emacs how to determine automatically the coding system of
3559 every PO file. This will often (but not always) cause the necessary
3560 fonts to be loaded and used for displaying the translations on your
3561 Emacs screen. For this to happen, add the lines:
3563 (modify-coding-system-alist 'file "\\.po\\'\\|\\.po\\."
3564 'po-find-file-coding-system)
3565 (autoload 'po-find-file-coding-system "po-mode")
3567 to your `.emacs' file. If, with this, you still see boxes instead of
3568 international characters, try a different font set (via Shift Mouse
3572 File: gettext.info, Node: Main PO Commands, Next: Entry Positioning, Prev: Installation, Up: PO Mode
3574 8.3.2 Main PO mode Commands
3575 ---------------------------
3577 After setting up Emacs with something similar to the lines in *note
3578 Installation::, PO mode is activated for a window when Emacs finds a PO
3579 file in that window. This puts the window read-only and establishes a
3580 po-mode-map, which is a genuine Emacs mode, in a way that is not derived
3581 from text mode in any way. Functions found on `po-mode-hook', if any,
3584 When PO mode is active in a window, the letters `PO' appear in the
3585 mode line for that window. The mode line also displays how many
3586 entries of each kind are held in the PO file. For example, the string
3587 `132t+3f+10u+2o' would tell the translator that the PO mode contains
3588 132 translated entries (*note Translated Entries::, 3 fuzzy entries
3589 (*note Fuzzy Entries::), 10 untranslated entries (*note Untranslated
3590 Entries::) and 2 obsolete entries (*note Obsolete Entries::).
3591 Zero-coefficients items are not shown. So, in this example, if the
3592 fuzzy entries were unfuzzied, the untranslated entries were translated
3593 and the obsolete entries were deleted, the mode line would merely
3594 display `145t' for the counters.
3596 The main PO commands are those which do not fit into the other
3597 categories of subsequent sections. These allow for quitting PO mode or
3598 for managing windows in special ways.
3601 Undo last modification to the PO file (`po-undo').
3604 Quit processing and save the PO file (`po-quit').
3607 Quit processing, possibly after confirmation
3608 (`po-confirm-and-quit').
3611 Temporary leave the PO file window (`po-other-window').
3615 Show help about PO mode (`po-help').
3618 Give some PO file statistics (`po-statistics').
3621 Batch validate the format of the whole PO file (`po-validate').
3624 The command `_' (`po-undo') interfaces to the Emacs _undo_ facility.
3625 *Note Undoing Changes: (emacs)Undo. Each time `_' is typed,
3626 modifications which the translator did to the PO file are undone a
3627 little more. For the purpose of undoing, each PO mode command is
3628 atomic. This is especially true for the `<RET>' command: the whole
3629 edition made by using a single use of this command is undone at once,
3630 even if the edition itself implied several actions. However, while in
3631 the editing window, one can undo the edition work quite parsimoniously.
3633 The commands `Q' (`po-quit') and `q' (`po-confirm-and-quit') are
3634 used when the translator is done with the PO file. The former is a bit
3635 less verbose than the latter. If the file has been modified, it is
3636 saved to disk first. In both cases, and prior to all this, the
3637 commands check if any untranslated messages remain in the PO file and,
3638 if so, the translator is asked if she really wants to leave off working
3639 with this PO file. This is the preferred way of getting rid of an
3640 Emacs PO file buffer. Merely killing it through the usual command
3641 `C-x k' (`kill-buffer') is not the tidiest way to proceed.
3643 The command `0' (`po-other-window') is another, softer way, to leave
3644 PO mode, temporarily. It just moves the cursor to some other Emacs
3645 window, and pops one if necessary. For example, if the translator just
3646 got PO mode to show some source context in some other, she might
3647 discover some apparent bug in the program source that needs correction.
3648 This command allows the translator to change sex, become a programmer,
3649 and have the cursor right into the window containing the program she
3650 (or rather _he_) wants to modify. By later getting the cursor back in
3651 the PO file window, or by asking Emacs to edit this file once again, PO
3652 mode is then recovered.
3654 The command `h' (`po-help') displays a summary of all available PO
3655 mode commands. The translator should then type any character to resume
3656 normal PO mode operations. The command `?' has the same effect as `h'.
3658 The command `=' (`po-statistics') computes the total number of
3659 entries in the PO file, the ordinal of the current entry (counted from
3660 1), the number of untranslated entries, the number of obsolete entries,
3661 and displays all these numbers.
3663 The command `V' (`po-validate') launches `msgfmt' in checking and
3664 verbose mode over the current PO file. This command first offers to
3665 save the current PO file on disk. The `msgfmt' tool, from GNU
3666 `gettext', has the purpose of creating a MO file out of a PO file, and
3667 PO mode uses the features of this program for checking the overall
3668 format of a PO file, as well as all individual entries.
3670 The program `msgfmt' runs asynchronously with Emacs, so the
3671 translator regains control immediately while her PO file is being
3672 studied. Error output is collected in the Emacs `*compilation*' buffer,
3673 displayed in another window. The regular Emacs command `C-x`'
3674 (`next-error'), as well as other usual compile commands, allow the
3675 translator to reposition quickly to the offending parts of the PO file.
3676 Once the cursor is on the line in error, the translator may decide on
3677 any PO mode action which would help correcting the error.
3680 File: gettext.info, Node: Entry Positioning, Next: Normalizing, Prev: Main PO Commands, Up: PO Mode
3682 8.3.3 Entry Positioning
3683 -----------------------
3685 The cursor in a PO file window is almost always part of an entry.
3686 The only exceptions are the special case when the cursor is after the
3687 last entry in the file, or when the PO file is empty. The entry where
3688 the cursor is found to be is said to be the current entry. Many PO
3689 mode commands operate on the current entry, so moving the cursor does
3690 more than allowing the translator to browse the PO file, this also
3691 selects on which entry commands operate.
3693 Some PO mode commands alter the position of the cursor in a
3694 specialized way. A few of those special purpose positioning are
3695 described here, the others are described in following sections (for a
3696 complete list try `C-h m'):
3699 Redisplay the current entry (`po-current-entry').
3702 Select the entry after the current one (`po-next-entry').
3705 Select the entry before the current one (`po-previous-entry').
3708 Select the first entry in the PO file (`po-first-entry').
3711 Select the last entry in the PO file (`po-last-entry').
3714 Record the location of the current entry for later use
3715 (`po-push-location').
3718 Return to a previously saved entry location (`po-pop-location').
3721 Exchange the current entry location with the previously saved one
3722 (`po-exchange-location').
3725 Any Emacs command able to reposition the cursor may be used to
3726 select the current entry in PO mode, including commands which move by
3727 characters, lines, paragraphs, screens or pages, and search commands.
3728 However, there is a kind of standard way to display the current entry
3729 in PO mode, which usual Emacs commands moving the cursor do not
3730 especially try to enforce. The command `.' (`po-current-entry') has
3731 the sole purpose of redisplaying the current entry properly, after the
3732 current entry has been changed by means external to PO mode, or the
3733 Emacs screen otherwise altered.
3735 It is yet to be decided if PO mode helps the translator, or otherwise
3736 irritates her, by forcing a rigid window disposition while she is doing
3737 her work. We originally had quite precise ideas about how windows
3738 should behave, but on the other hand, anyone used to Emacs is often
3739 happy to keep full control. Maybe a fixed window disposition might be
3740 offered as a PO mode option that the translator might activate or
3741 deactivate at will, so it could be offered on an experimental basis.
3742 If nobody feels a real need for using it, or a compulsion for writing
3743 it, we should drop this whole idea. The incentive for doing it should
3744 come from translators rather than programmers, as opinions from an
3745 experienced translator are surely more worth to me than opinions from
3746 programmers _thinking_ about how _others_ should do translation.
3748 The commands `n' (`po-next-entry') and `p' (`po-previous-entry')
3749 move the cursor the entry following, or preceding, the current one. If
3750 `n' is given while the cursor is on the last entry of the PO file, or
3751 if `p' is given while the cursor is on the first entry, no move is done.
3753 The commands `<' (`po-first-entry') and `>' (`po-last-entry') move
3754 the cursor to the first entry, or last entry, of the PO file. When the
3755 cursor is located past the last entry in a PO file, most PO mode
3756 commands will return an error saying `After last entry'. Moreover, the
3757 commands `<' and `>' have the special property of being able to work
3758 even when the cursor is not into some PO file entry, and one may use
3759 them for nicely correcting this situation. But even these commands
3760 will fail on a truly empty PO file. There are development plans for
3761 the PO mode for it to interactively fill an empty PO file from sources.
3764 The translator may decide, before working at the translation of a
3765 particular entry, that she needs to browse the remainder of the PO
3766 file, maybe for finding the terminology or phraseology used in related
3767 entries. She can of course use the standard Emacs idioms for saving
3768 the current cursor location in some register, and use that register for
3769 getting back, or else, use the location ring.
3771 PO mode offers another approach, by which cursor locations may be
3772 saved onto a special stack. The command `m' (`po-push-location')
3773 merely adds the location of current entry to the stack, pushing the
3774 already saved locations under the new one. The command `r'
3775 (`po-pop-location') consumes the top stack element and repositions the
3776 cursor to the entry associated with that top element. This position is
3777 then lost, for the next `r' will move the cursor to the previously
3778 saved location, and so on until no locations remain on the stack.
3780 If the translator wants the position to be kept on the location
3781 stack, maybe for taking a look at the entry associated with the top
3782 element, then go elsewhere with the intent of getting back later, she
3783 ought to use `m' immediately after `r'.
3785 The command `x' (`po-exchange-location') simultaneously repositions
3786 the cursor to the entry associated with the top element of the stack of
3787 saved locations, and replaces that top element with the location of the
3788 current entry before the move. Consequently, repeating the `x' command
3789 toggles alternatively between two entries. For achieving this, the
3790 translator will position the cursor on the first entry, use `m', then
3791 position to the second entry, and merely use `x' for making the switch.
3794 File: gettext.info, Node: Normalizing, Next: Translated Entries, Prev: Entry Positioning, Up: PO Mode
3796 8.3.4 Normalizing Strings in Entries
3797 ------------------------------------
3799 There are many different ways for encoding a particular string into a
3800 PO file entry, because there are so many different ways to split and
3801 quote multi-line strings, and even, to represent special characters by
3802 backslashed escaped sequences. Some features of PO mode rely on the
3803 ability for PO mode to scan an already existing PO file for a
3804 particular string encoded into the `msgid' field of some entry. Even
3805 if PO mode has internally all the built-in machinery for implementing
3806 this recognition easily, doing it fast is technically difficult. To
3807 facilitate a solution to this efficiency problem, we decided on a
3808 canonical representation for strings.
3810 A conventional representation of strings in a PO file is currently
3811 under discussion, and PO mode experiments with a canonical
3812 representation. Having both `xgettext' and PO mode converging towards
3813 a uniform way of representing equivalent strings would be useful, as
3814 the internal normalization needed by PO mode could be automatically
3815 satisfied when using `xgettext' from GNU `gettext'. An explicit PO
3816 mode normalization should then be only necessary for PO files imported
3817 from elsewhere, or for when the convention itself evolves.
3819 So, for achieving normalization of at least the strings of a given
3820 PO file needing a canonical representation, the following PO mode
3821 command is available:
3824 Tidy the whole PO file by making entries more uniform.
3827 The special command `M-x po-normalize', which has no associated
3828 keys, revises all entries, ensuring that strings of both original and
3829 translated entries use uniform internal quoting in the PO file. It
3830 also removes any crumb after the last entry. This command may be
3831 useful for PO files freshly imported from elsewhere, or if we ever
3832 improve on the canonical quoting format we use. This canonical format
3833 is not only meant for getting cleaner PO files, but also for greatly
3834 speeding up `msgid' string lookup for some other PO mode commands.
3836 `M-x po-normalize' presently makes three passes over the entries.
3837 The first implements heuristics for converting PO files for GNU
3838 `gettext' 0.6 and earlier, in which `msgid' and `msgstr' fields were
3839 using K&R style C string syntax for multi-line strings. These
3840 heuristics may fail for comments not related to obsolete entries and
3841 ending with a backslash; they also depend on subsequent passes for
3842 finalizing the proper commenting of continued lines for obsolete
3843 entries. This first pass might disappear once all oldish PO files
3844 would have been adjusted. The second and third pass normalize all
3845 `msgid' and `msgstr' strings respectively. They also clean out those
3846 trailing backslashes used by XView's `msgfmt' for continued lines.
3848 Having such an explicit normalizing command allows for importing PO
3849 files from other sources, but also eases the evolution of the current
3850 convention, evolution driven mostly by aesthetic concerns, as of now.
3851 It is easy to make suggested adjustments at a later time, as the
3852 normalizing command and eventually, other GNU `gettext' tools should
3853 greatly automate conformance. A description of the canonical string
3854 format is given below, for the particular benefit of those not having
3855 Emacs handy, and who would nevertheless want to handcraft their PO
3858 Right now, in PO mode, strings are single line or multi-line. A
3859 string goes multi-line if and only if it has _embedded_ newlines, that
3860 is, if it matches `[^\n]\n+[^\n]'. So, we would have:
3862 msgstr "\n\nHello, world!\n\n\n"
3864 but, replacing the space by a newline, this becomes:
3874 We are deliberately using a caricatural example, here, to make the
3875 point clearer. Usually, multi-lines are not that bad looking. It is
3876 probable that we will implement the following suggestion. We might
3877 lump together all initial newlines into the empty string, and also all
3878 newlines introducing empty lines (that is, for N > 1, the N-1'th last
3879 newlines would go together on a separate string), so making the
3880 previous example appear:
3887 There are a few yet undecided little points about string
3888 normalization, to be documented in this manual, once these questions
3892 File: gettext.info, Node: Translated Entries, Next: Fuzzy Entries, Prev: Normalizing, Up: PO Mode
3894 8.3.5 Translated Entries
3895 ------------------------
3897 Each PO file entry for which the `msgstr' field has been filled with
3898 a translation, and which is not marked as fuzzy (*note Fuzzy Entries::),
3899 is said to be a "translated" entry. Only translated entries will later
3900 be compiled by GNU `msgfmt' and become usable in programs. Other entry
3901 types will be excluded; translation will not occur for them.
3903 Some commands are more specifically related to translated entry
3907 Find the next translated entry (`po-next-translated-entry').
3910 Find the previous translated entry
3911 (`po-previous-translated-entry').
3914 The commands `t' (`po-next-translated-entry') and `T'
3915 (`po-previous-translated-entry') move forwards or backwards, chasing
3916 for an translated entry. If none is found, the search is extended and
3917 wraps around in the PO file buffer.
3919 Translated entries usually result from the translator having edited
3920 in a translation for them, *note Modifying Translations::. However, if
3921 the variable `po-auto-fuzzy-on-edit' is not `nil', the entry having
3922 received a new translation first becomes a fuzzy entry, which ought to
3923 be later unfuzzied before becoming an official, genuine translated
3924 entry. *Note Fuzzy Entries::.
3927 File: gettext.info, Node: Fuzzy Entries, Next: Untranslated Entries, Prev: Translated Entries, Up: PO Mode
3932 Each PO file entry may have a set of "attributes", which are
3933 qualities given a name and explicitly associated with the translation,
3934 using a special system comment. One of these attributes has the name
3935 `fuzzy', and entries having this attribute are said to have a fuzzy
3936 translation. They are called fuzzy entries, for short.
3938 Fuzzy entries, even if they account for translated entries for most
3939 other purposes, usually call for revision by the translator. Those may
3940 be produced by applying the program `msgmerge' to update an older
3941 translated PO files according to a new PO template file, when this tool
3942 hypothesises that some new `msgid' has been modified only slightly out
3943 of an older one, and chooses to pair what it thinks to be the old
3944 translation for the new modified entry. The slight alteration in the
3945 original string (the `msgid' string) should often be reflected in the
3946 translated string, and this requires the intervention of the
3947 translator. For this reason, `msgmerge' might mark some entries as
3950 Also, the translator may decide herself to mark an entry as fuzzy
3951 for her own convenience, when she wants to remember that the entry has
3952 to be later revisited. So, some commands are more specifically related
3953 to fuzzy entry processing.
3956 Find the next fuzzy entry (`po-next-fuzzy-entry').
3959 Find the previous fuzzy entry (`po-previous-fuzzy-entry').
3962 Remove the fuzzy attribute of the current entry (`po-unfuzzy').
3965 The commands `f' (`po-next-fuzzy-entry') and `F'
3966 (`po-previous-fuzzy-entry') move forwards or backwards, chasing for a
3967 fuzzy entry. If none is found, the search is extended and wraps around
3968 in the PO file buffer.
3970 The command `<TAB>' (`po-unfuzzy') removes the fuzzy attribute
3971 associated with an entry, usually leaving it translated. Further, if
3972 the variable `po-auto-select-on-unfuzzy' has not the `nil' value, the
3973 `<TAB>' command will automatically chase for another interesting entry
3974 to work on. The initial value of `po-auto-select-on-unfuzzy' is `nil'.
3976 The initial value of `po-auto-fuzzy-on-edit' is `nil'. However, if
3977 the variable `po-auto-fuzzy-on-edit' is set to `t', any entry edited
3978 through the `<RET>' command is marked fuzzy, as a way to ensure some
3979 kind of double check, later. In this case, the usual paradigm is that
3980 an entry becomes fuzzy (if not already) whenever the translator
3981 modifies it. If she is satisfied with the translation, she then uses
3982 `<TAB>' to pick another entry to work on, clearing the fuzzy attribute
3983 on the same blow. If she is not satisfied yet, she merely uses `<SPC>'
3984 to chase another entry, leaving the entry fuzzy.
3986 The translator may also use the `<DEL>' command
3987 (`po-fade-out-entry') over any translated entry to mark it as being
3988 fuzzy, when she wants to easily leave a trace she wants to later return
3989 working at this entry.
3991 Also, when time comes to quit working on a PO file buffer with the
3992 `q' command, the translator is asked for confirmation, if fuzzy string
3996 File: gettext.info, Node: Untranslated Entries, Next: Obsolete Entries, Prev: Fuzzy Entries, Up: PO Mode
3998 8.3.7 Untranslated Entries
3999 --------------------------
4001 When `xgettext' originally creates a PO file, unless told otherwise,
4002 it initializes the `msgid' field with the untranslated string, and
4003 leaves the `msgstr' string to be empty. Such entries, having an empty
4004 translation, are said to be "untranslated" entries. Later, when the
4005 programmer slightly modifies some string right in the program, this
4006 change is later reflected in the PO file by the appearance of a new
4007 untranslated entry for the modified string.
4009 The usual commands moving from entry to entry consider untranslated
4010 entries on the same level as active entries. Untranslated entries are
4011 easily recognizable by the fact they end with `msgstr ""'.
4013 The work of the translator might be (quite naively) seen as the
4014 process of seeking for an untranslated entry, editing a translation for
4015 it, and repeating these actions until no untranslated entries remain.
4016 Some commands are more specifically related to untranslated entry
4020 Find the next untranslated entry (`po-next-untranslated-entry').
4023 Find the previous untranslated entry
4024 (`po-previous-untransted-entry').
4027 Turn the current entry into an untranslated one (`po-kill-msgstr').
4030 The commands `u' (`po-next-untranslated-entry') and `U'
4031 (`po-previous-untransted-entry') move forwards or backwards, chasing
4032 for an untranslated entry. If none is found, the search is extended
4033 and wraps around in the PO file buffer.
4035 An entry can be turned back into an untranslated entry by merely
4036 emptying its translation, using the command `k' (`po-kill-msgstr').
4037 *Note Modifying Translations::.
4039 Also, when time comes to quit working on a PO file buffer with the
4040 `q' command, the translator is asked for confirmation, if some
4041 untranslated string still exists.
4044 File: gettext.info, Node: Obsolete Entries, Next: Modifying Translations, Prev: Untranslated Entries, Up: PO Mode
4046 8.3.8 Obsolete Entries
4047 ----------------------
4049 By "obsolete" PO file entries, we mean those entries which are
4050 commented out, usually by `msgmerge' when it found that the translation
4051 is not needed anymore by the package being localized.
4053 The usual commands moving from entry to entry consider obsolete
4054 entries on the same level as active entries. Obsolete entries are
4055 easily recognizable by the fact that all their lines start with `#',
4056 even those lines containing `msgid' or `msgstr'.
4058 Commands exist for emptying the translation or reinitializing it to
4059 the original untranslated string. Commands interfacing with the kill
4060 ring may force some previously saved text into the translation. The
4061 user may interactively edit the translation. All these commands may
4062 apply to obsolete entries, carefully leaving the entry obsolete after
4065 Moreover, some commands are more specifically related to obsolete
4069 Find the next obsolete entry (`po-next-obsolete-entry').
4072 Find the previous obsolete entry (`po-previous-obsolete-entry').
4075 Make an active entry obsolete, or zap out an obsolete entry
4076 (`po-fade-out-entry').
4079 The commands `o' (`po-next-obsolete-entry') and `O'
4080 (`po-previous-obsolete-entry') move forwards or backwards, chasing for
4081 an obsolete entry. If none is found, the search is extended and wraps
4082 around in the PO file buffer.
4084 PO mode does not provide ways for un-commenting an obsolete entry
4085 and making it active, because this would reintroduce an original
4086 untranslated string which does not correspond to any marked string in
4087 the program sources. This goes with the philosophy of never
4088 introducing useless `msgid' values.
4090 However, it is possible to comment out an active entry, so making it
4091 obsolete. GNU `gettext' utilities will later react to the
4092 disappearance of a translation by using the untranslated string. The
4093 command `<DEL>' (`po-fade-out-entry') pushes the current entry a little
4094 further towards annihilation. If the entry is active (it is a
4095 translated entry), then it is first made fuzzy. If it is already fuzzy,
4096 then the entry is merely commented out, with confirmation. If the entry
4097 is already obsolete, then it is completely deleted from the PO file.
4098 It is easy to recycle the translation so deleted into some other PO file
4099 entry, usually one which is untranslated. *Note Modifying
4102 Here is a quite interesting problem to solve for later development of
4103 PO mode, for those nights you are not sleepy. The idea would be that
4104 PO mode might become bright enough, one of these days, to make good
4105 guesses at retrieving the most probable candidate, among all obsolete
4106 entries, for initializing the translation of a newly appeared string.
4107 I think it might be a quite hard problem to do this algorithmically, as
4108 we have to develop good and efficient measures of string similarity.
4109 Right now, PO mode completely lets the decision to the translator, when
4110 the time comes to find the adequate obsolete translation, it merely
4111 tries to provide handy tools for helping her to do so.
4114 File: gettext.info, Node: Modifying Translations, Next: Modifying Comments, Prev: Obsolete Entries, Up: PO Mode
4116 8.3.9 Modifying Translations
4117 ----------------------------
4119 PO mode prevents direct modification of the PO file, by the usual
4120 means Emacs gives for altering a buffer's contents. By doing so, it
4121 pretends helping the translator to avoid little clerical errors about
4122 the overall file format, or the proper quoting of strings, as those
4123 errors would be easily made. Other kinds of errors are still possible,
4124 but some may be caught and diagnosed by the batch validation process,
4125 which the translator may always trigger by the `V' command. For all
4126 other errors, the translator has to rely on her own judgment, and also
4127 on the linguistic reports submitted to her by the users of the
4128 translated package, having the same mother tongue.
4130 When the time comes to create a translation, correct an error
4131 diagnosed mechanically or reported by a user, the translators have to
4132 resort to using the following commands for modifying the translations.
4135 Interactively edit the translation (`po-edit-msgstr').
4139 Reinitialize the translation with the original, untranslated string
4140 (`po-msgid-to-msgstr').
4143 Save the translation on the kill ring, and delete it
4147 Save the translation on the kill ring, without deleting it
4148 (`po-kill-ring-save-msgstr').
4151 Replace the translation, taking the new from the kill ring
4155 The command `<RET>' (`po-edit-msgstr') opens a new Emacs window
4156 meant to edit in a new translation, or to modify an already existing
4157 translation. The new window contains a copy of the translation taken
4158 from the current PO file entry, all ready for edition, expunged of all
4159 quoting marks, fully modifiable and with the complete extent of Emacs
4160 modifying commands. When the translator is done with her
4161 modifications, she may use `C-c C-c' to close the subedit window with
4162 the automatically requoted results, or `C-c C-k' to abort her
4163 modifications. *Note Subedit::, for more information.
4165 The command `<LFD>' (`po-msgid-to-msgstr') initializes, or
4166 reinitializes the translation with the original string. This command is
4167 normally used when the translator wants to redo a fresh translation of
4168 the original string, disregarding any previous work.
4170 It is possible to arrange so, whenever editing an untranslated
4171 entry, the `<LFD>' command be automatically executed. If you set
4172 `po-auto-edit-with-msgid' to `t', the translation gets initialised with
4173 the original string, in case none exists already. The default value
4174 for `po-auto-edit-with-msgid' is `nil'.
4176 In fact, whether it is best to start a translation with an empty
4177 string, or rather with a copy of the original string, is a matter of
4178 taste or habit. Sometimes, the source language and the target language
4179 are so different that is simply best to start writing on an empty page.
4180 At other times, the source and target languages are so close that it
4181 would be a waste to retype a number of words already being written in
4182 the original string. A translator may also like having the original
4183 string right under her eyes, as she will progressively overwrite the
4184 original text with the translation, even if this requires some extra
4185 editing work to get rid of the original.
4187 The command `k' (`po-kill-msgstr') merely empties the translation
4188 string, so turning the entry into an untranslated one. But while doing
4189 so, its previous contents is put apart in a special place, known as the
4190 kill ring. The command `w' (`po-kill-ring-save-msgstr') has also the
4191 effect of taking a copy of the translation onto the kill ring, but it
4192 otherwise leaves the entry alone, and does _not_ remove the translation
4193 from the entry. Both commands use exactly the Emacs kill ring, which
4194 is shared between buffers, and which is well known already to Emacs
4197 The translator may use `k' or `w' many times in the course of her
4198 work, as the kill ring may hold several saved translations. From the
4199 kill ring, strings may later be reinserted in various Emacs buffers.
4200 In particular, the kill ring may be used for moving translation strings
4201 between different entries of a single PO file buffer, or if the
4202 translator is handling many such buffers at once, even between PO files.
4204 To facilitate exchanges with buffers which are not in PO mode, the
4205 translation string put on the kill ring by the `k' command is fully
4206 unquoted before being saved: external quotes are removed, multi-line
4207 strings are concatenated, and backslash escaped sequences are turned
4208 into their corresponding characters. In the special case of obsolete
4209 entries, the translation is also uncommented prior to saving.
4211 The command `y' (`po-yank-msgstr') completely replaces the
4212 translation of the current entry by a string taken from the kill ring.
4213 Following Emacs terminology, we then say that the replacement string is
4214 "yanked" into the PO file buffer. *Note Yanking: (emacs)Yanking. The
4215 first time `y' is used, the translation receives the value of the most
4216 recent addition to the kill ring. If `y' is typed once again,
4217 immediately, without intervening keystrokes, the translation just
4218 inserted is taken away and replaced by the second most recent addition
4219 to the kill ring. By repeating `y' many times in a row, the translator
4220 may travel along the kill ring for saved strings, until she finds the
4221 string she really wanted.
4223 When a string is yanked into a PO file entry, it is fully and
4224 automatically requoted for complying with the format PO files should
4225 have. Further, if the entry is obsolete, PO mode then appropriately
4226 push the inserted string inside comments. Once again, translators
4227 should not burden themselves with quoting considerations besides, of
4228 course, the necessity of the translated string itself respective to the
4231 Note that `k' or `w' are not the only commands pushing strings on
4232 the kill ring, as almost any PO mode command replacing translation
4233 strings (or the translator comments) automatically saves the old string
4234 on the kill ring. The main exceptions to this general rule are the
4235 yanking commands themselves.
4237 To better illustrate the operation of killing and yanking, let's use
4238 an actual example, taken from a common situation. When the programmer
4239 slightly modifies some string right in the program, his change is later
4240 reflected in the PO file by the appearance of a new untranslated entry
4241 for the modified string, and the fact that the entry translating the
4242 original or unmodified string becomes obsolete. In many cases, the
4243 translator might spare herself some work by retrieving the unmodified
4244 translation from the obsolete entry, then initializing the untranslated
4245 entry `msgstr' field with this retrieved translation. Once this done,
4246 the obsolete entry is not wanted anymore, and may be safely deleted.
4248 When the translator finds an untranslated entry and suspects that a
4249 slight variant of the translation exists, she immediately uses `m' to
4250 mark the current entry location, then starts chasing obsolete entries
4251 with `o', hoping to find some translation corresponding to the
4252 unmodified string. Once found, she uses the `<DEL>' command for
4253 deleting the obsolete entry, knowing that `<DEL>' also _kills_ the
4254 translation, that is, pushes the translation on the kill ring. Then,
4255 `r' returns to the initial untranslated entry, and `y' then _yanks_ the
4256 saved translation right into the `msgstr' field. The translator is
4257 then free to use `<RET>' for fine tuning the translation contents, and
4258 maybe to later use `u', then `m' again, for going on with the next
4259 untranslated string.
4261 When some sequence of keys has to be typed over and over again, the
4262 translator may find it useful to become better acquainted with the Emacs
4263 capability of learning these sequences and playing them back under
4264 request. *Note Keyboard Macros: (emacs)Keyboard Macros.
4267 File: gettext.info, Node: Modifying Comments, Next: Subedit, Prev: Modifying Translations, Up: PO Mode
4269 8.3.10 Modifying Comments
4270 -------------------------
4272 Any translation work done seriously will raise many linguistic
4273 difficulties, for which decisions have to be made, and the choices
4274 further documented. These documents may be saved within the PO file in
4275 form of translator comments, which the translator is free to create,
4276 delete, or modify at will. These comments may be useful to herself
4277 when she returns to this PO file after a while.
4279 Comments not having whitespace after the initial `#', for example,
4280 those beginning with `#.' or `#:', are _not_ translator comments, they
4281 are exclusively created by other `gettext' tools. So, the commands
4282 below will never alter such system added comments, they are not meant
4283 for the translator to modify. *Note PO Files::.
4285 The following commands are somewhat similar to those modifying
4286 translations, so the general indications given for those apply here.
4287 *Note Modifying Translations::.
4290 Interactively edit the translator comments (`po-edit-comment').
4293 Save the translator comments on the kill ring, and delete it
4294 (`po-kill-comment').
4297 Save the translator comments on the kill ring, without deleting it
4298 (`po-kill-ring-save-comment').
4301 Replace the translator comments, taking the new from the kill ring
4302 (`po-yank-comment').
4305 These commands parallel PO mode commands for modifying the
4306 translation strings, and behave much the same way as they do, except
4307 that they handle this part of PO file comments meant for translator
4308 usage, rather than the translation strings. So, if the descriptions
4309 given below are slightly succinct, it is because the full details have
4310 already been given. *Note Modifying Translations::.
4312 The command `#' (`po-edit-comment') opens a new Emacs window
4313 containing a copy of the translator comments on the current PO file
4314 entry. If there are no such comments, PO mode understands that the
4315 translator wants to add a comment to the entry, and she is presented
4316 with an empty screen. Comment marks (`#') and the space following them
4317 are automatically removed before edition, and reinstated after. For
4318 translator comments pertaining to obsolete entries, the uncommenting
4319 and recommenting operations are done twice. Once in the editing
4320 window, the keys `C-c C-c' allow the translator to tell she is finished
4321 with editing the comment. *Note Subedit::, for further details.
4323 Functions found on `po-subedit-mode-hook', if any, are executed after
4324 the string has been inserted in the edit buffer.
4326 The command `K' (`po-kill-comment') gets rid of all translator
4327 comments, while saving those comments on the kill ring. The command
4328 `W' (`po-kill-ring-save-comment') takes a copy of the translator
4329 comments on the kill ring, but leaves them undisturbed in the current
4330 entry. The command `Y' (`po-yank-comment') completely replaces the
4331 translator comments by a string taken at the front of the kill ring.
4332 When this command is immediately repeated, the comments just inserted
4333 are withdrawn, and replaced by other strings taken along the kill ring.
4335 On the kill ring, all strings have the same nature. There is no
4336 distinction between _translation_ strings and _translator comments_
4337 strings. So, for example, let's presume the translator has just
4338 finished editing a translation, and wants to create a new translator
4339 comment to document why the previous translation was not good, just to
4340 remember what was the problem. Foreseeing that she will do that in her
4341 documentation, the translator may want to quote the previous
4342 translation in her translator comments. To do so, she may initialize
4343 the translator comments with the previous translation, still at the
4344 head of the kill ring. Because editing already pushed the previous
4345 translation on the kill ring, she merely has to type `M-w' prior to
4346 `#', and the previous translation will be right there, all ready for
4347 being introduced by some explanatory text.
4349 On the other hand, presume there are some translator comments already
4350 and that the translator wants to add to those comments, instead of
4351 wholly replacing them. Then, she should edit the comment right away
4352 with `#'. Once inside the editing window, she can use the regular
4353 Emacs commands `C-y' (`yank') and `M-y' (`yank-pop') to get the
4354 previous translation where she likes.
4357 File: gettext.info, Node: Subedit, Next: C Sources Context, Prev: Modifying Comments, Up: PO Mode
4359 8.3.11 Details of Sub Edition
4360 -----------------------------
4362 The PO subedit minor mode has a few peculiarities worth being
4363 described in fuller detail. It installs a few commands over the usual
4364 editing set of Emacs, which are described below.
4367 Complete edition (`po-subedit-exit').
4370 Abort edition (`po-subedit-abort').
4373 Consult auxiliary PO files (`po-subedit-cycle-auxiliary').
4376 The window's contents represents a translation for a given message,
4377 or a translator comment. The translator may modify this window to her
4378 heart's content. Once this is done, the command `C-c C-c'
4379 (`po-subedit-exit') may be used to return the edited translation into
4380 the PO file, replacing the original translation, even if it moved out of
4381 sight or if buffers were switched.
4383 If the translator becomes unsatisfied with her translation or
4384 comment, to the extent she prefers keeping what was existent prior to
4385 the `<RET>' or `#' command, she may use the command `C-c C-k'
4386 (`po-subedit-abort') to merely get rid of edition, while preserving the
4387 original translation or comment. Another way would be for her to exit
4388 normally with `C-c C-c', then type `U' once for undoing the whole
4389 effect of last edition.
4391 The command `C-c C-a' (`po-subedit-cycle-auxiliary') allows for
4392 glancing through translations already achieved in other languages,
4393 directly while editing the current translation. This may be quite
4394 convenient when the translator is fluent at many languages, but of
4395 course, only makes sense when such completed auxiliary PO files are
4396 already available to her (*note Auxiliary::).
4398 Functions found on `po-subedit-mode-hook', if any, are executed after
4399 the string has been inserted in the edit buffer.
4401 While editing her translation, the translator should pay attention
4402 to not inserting unwanted `<RET>' (newline) characters at the end of
4403 the translated string if those are not meant to be there, or to removing
4404 such characters when they are required. Since these characters are not
4405 visible in the editing buffer, they are easily introduced by mistake.
4406 To help her, `<RET>' automatically puts the character `<' at the end of
4407 the string being edited, but this `<' is not really part of the string.
4408 On exiting the editing window with `C-c C-c', PO mode automatically
4409 removes such `<' and all whitespace added after it. If the translator
4410 adds characters after the terminating `<', it looses its delimiting
4411 property and integrally becomes part of the string. If she removes the
4412 delimiting `<', then the edited string is taken _as is_, with all
4413 trailing newlines, even if invisible. Also, if the translated string
4414 ought to end itself with a genuine `<', then the delimiting `<' may not
4415 be removed; so the string should appear, in the editing window, as
4416 ending with two `<' in a row.
4418 When a translation (or a comment) is being edited, the translator
4419 may move the cursor back into the PO file buffer and freely move to
4420 other entries, browsing at will. If, with an edition pending, the
4421 translator wanders in the PO file buffer, she may decide to start
4422 modifying another entry. Each entry being edited has its own subedit
4423 buffer. It is possible to simultaneously edit the translation _and_
4424 the comment of a single entry, or to edit entries in different PO
4425 files, all at once. Typing `<RET>' on a field already being edited
4426 merely resumes that particular edit. Yet, the translator should better
4427 be comfortable at handling many Emacs windows!
4429 Pending subedits may be completed or aborted in any order, regardless
4430 of how or when they were started. When many subedits are pending and
4431 the translator asks for quitting the PO file (with the `q' command),
4432 subedits are automatically resumed one at a time, so she may decide for
4436 File: gettext.info, Node: C Sources Context, Next: Auxiliary, Prev: Subedit, Up: PO Mode
4438 8.3.12 C Sources Context
4439 ------------------------
4441 PO mode is particularly powerful when used with PO files created
4442 through GNU `gettext' utilities, as those utilities insert special
4443 comments in the PO files they generate. Some of these special comments
4444 relate the PO file entry to exactly where the untranslated string
4445 appears in the program sources.
4447 When the translator gets to an untranslated entry, she is fairly
4448 often faced with an original string which is not as informative as it
4449 normally should be, being succinct, cryptic, or otherwise ambiguous.
4450 Before choosing how to translate the string, she needs to understand
4451 better what the string really means and how tight the translation has
4452 to be. Most of the time, when problems arise, the only way left to make
4453 her judgment is looking at the true program sources from where this
4454 string originated, searching for surrounding comments the programmer
4455 might have put in there, and looking around for helping clues of _any_
4458 Surely, when looking at program sources, the translator will receive
4459 more help if she is a fluent programmer. However, even if she is not
4460 versed in programming and feels a little lost in C code, the translator
4461 should not be shy at taking a look, once in a while. It is most
4462 probable that she will still be able to find some of the hints she
4463 needs. She will learn quickly to not feel uncomfortable in program
4464 code, paying more attention to programmer's comments, variable and
4465 function names (if he dared choosing them well), and overall
4466 organization, than to the program code itself.
4468 The following commands are meant to help the translator at getting
4469 program source context for a PO file entry.
4472 Resume the display of a program source context, or cycle through
4473 them (`po-cycle-source-reference').
4476 Display of a program source context selected by menu
4477 (`po-select-source-reference').
4480 Add a directory to the search path for source files
4481 (`po-consider-source-path').
4484 Delete a directory from the search path for source files
4485 (`po-ignore-source-path').
4488 The commands `s' (`po-cycle-source-reference') and `M-s'
4489 (`po-select-source-reference') both open another window displaying some
4490 source program file, and already positioned in such a way that it shows
4491 an actual use of the string to be translated. By doing so, the command
4492 gives source program context for the string. But if the entry has no
4493 source context references, or if all references are unresolved along
4494 the search path for program sources, then the command diagnoses this as
4497 Even if `s' (or `M-s') opens a new window, the cursor stays in the
4498 PO file window. If the translator really wants to get into the program
4499 source window, she ought to do it explicitly, maybe by using command
4502 When `s' is typed for the first time, or for a PO file entry which
4503 is different of the last one used for getting source context, then the
4504 command reacts by giving the first context available for this entry, if
4505 any. If some context has already been recently displayed for the
4506 current PO file entry, and the translator wandered off to do other
4507 things, typing `s' again will merely resume, in another window, the
4508 context last displayed. In particular, if the translator moved the
4509 cursor away from the context in the source file, the command will bring
4510 the cursor back to the context. By using `s' many times in a row, with
4511 no other commands intervening, PO mode will cycle to the next available
4512 contexts for this particular entry, getting back to the first context
4513 once the last has been shown.
4515 The command `M-s' behaves differently. Instead of cycling through
4516 references, it lets the translator choose a particular reference among
4517 many, and displays that reference. It is best used with completion, if
4518 the translator types `<TAB>' immediately after `M-s', in response to
4519 the question, she will be offered a menu of all possible references, as
4520 a reminder of which are the acceptable answers. This command is useful
4521 only where there are really many contexts available for a single string
4524 Program source files are usually found relative to where the PO file
4525 stands. As a special provision, when this fails, the file is also
4526 looked for, but relative to the directory immediately above it. Those
4527 two cases take proper care of most PO files. However, it might happen
4528 that a PO file has been moved, or is edited in a different place than
4529 its normal location. When this happens, the translator should tell PO
4530 mode in which directory normally sits the genuine PO file. Many such
4531 directories may be specified, and all together, they constitute what is
4532 called the "search path" for program sources. The command `S'
4533 (`po-consider-source-path') is used to interactively enter a new
4534 directory at the front of the search path, and the command `M-S'
4535 (`po-ignore-source-path') is used to select, with completion, one of
4536 the directories she does not want anymore on the search path.
4539 File: gettext.info, Node: Auxiliary, Prev: C Sources Context, Up: PO Mode
4541 8.3.13 Consulting Auxiliary PO Files
4542 ------------------------------------
4544 PO mode is able to help the knowledgeable translator, being fluent in
4545 many languages, at taking advantage of translations already achieved in
4546 other languages she just happens to know. It provides these other
4547 language translations as additional context for her own work. Moreover,
4548 it has features to ease the production of translations for many
4549 languages at once, for translators preferring to work in this way.
4551 An "auxiliary" PO file is an existing PO file meant for the same
4552 package the translator is working on, but targeted to a different mother
4553 tongue language. Commands exist for declaring and handling auxiliary
4554 PO files, and also for showing contexts for the entry under work.
4556 Here are the auxiliary file commands available in PO mode.
4559 Seek auxiliary files for another translation for the same entry
4560 (`po-cycle-auxiliary').
4563 Switch to a particular auxiliary file (`po-select-auxiliary').
4566 Declare this PO file as an auxiliary file
4567 (`po-consider-as-auxiliary').
4570 Remove this PO file from the list of auxiliary files
4571 (`po-ignore-as-auxiliary').
4574 Command `A' (`po-consider-as-auxiliary') adds the current PO file to
4575 the list of auxiliary files, while command `M-A'
4576 (`po-ignore-as-auxiliary' just removes it.
4578 The command `a' (`po-cycle-auxiliary') seeks all auxiliary PO files,
4579 round-robin, searching for a translated entry in some other language
4580 having an `msgid' field identical as the one for the current entry.
4581 The found PO file, if any, takes the place of the current PO file in
4582 the display (its window gets on top). Before doing so, the current PO
4583 file is also made into an auxiliary file, if not already. So, `a' in
4584 this newly displayed PO file will seek another PO file, and so on, so
4585 repeating `a' will eventually yield back the original PO file.
4587 The command `C-c C-a' (`po-select-auxiliary') asks the translator
4588 for her choice of a particular auxiliary file, with completion, and
4589 then switches to that selected PO file. The command also checks if the
4590 selected file has an `msgid' field identical as the one for the current
4591 entry, and if yes, this entry becomes current. Otherwise, the cursor
4592 of the selected file is left undisturbed.
4594 For all this to work fully, auxiliary PO files will have to be
4595 normalized, in that way that `msgid' fields should be written _exactly_
4596 the same way. It is possible to write `msgid' fields in various ways
4597 for representing the same string, different writing would break the
4598 proper behaviour of the auxiliary file commands of PO mode. This is not
4599 expected to be much a problem in practice, as most existing PO files
4600 have their `msgid' entries written by the same GNU `gettext' tools.
4602 However, PO files initially created by PO mode itself, while marking
4603 strings in source files, are normalised differently. So are PO files
4604 resulting of the `M-x normalize' command. Until these discrepancies
4605 between PO mode and other GNU `gettext' tools get fully resolved, the
4606 translator should stay aware of normalisation issues.
4609 File: gettext.info, Node: Compendium, Prev: PO Mode, Up: Editing
4611 8.4 Using Translation Compendia
4612 ===============================
4614 A "compendium" is a special PO file containing a set of translations
4615 recurring in many different packages. The translator can use gettext
4616 tools to build a new compendium, to add entries to her compendium, and
4617 to initialize untranslated entries, or to update already translated
4618 entries, from translations kept in the compendium.
4622 * Creating Compendia:: Merging translations for later use
4623 * Using Compendia:: Using older translations if they fit
4626 File: gettext.info, Node: Creating Compendia, Next: Using Compendia, Prev: Compendium, Up: Compendium
4628 8.4.1 Creating Compendia
4629 ------------------------
4631 Basically every PO file consisting of translated entries only can be
4632 declared as a valid compendium. Often the translator wants to have
4633 special compendia; let's consider two cases: `concatenating PO files'
4634 and `extracting a message subset from a PO file'.
4636 8.4.1.1 Concatenate PO Files
4637 ............................
4639 To concatenate several valid PO files into one compendium file you
4640 can use `msgcomm' or `msgcat' (the latter preferred):
4642 msgcat -o compendium.po file1.po file2.po
4644 By default, `msgcat' will accumulate divergent translations for the
4645 same string. Those occurrences will be marked as `fuzzy' and highly
4646 visible decorated; calling `msgcat' on `file1.po':
4650 msgid "Report bugs to <%s>.\n"
4651 msgstr "Comunicar `bugs' a <%s>.\n"
4657 msgid "Report bugs to <%s>.\n"
4658 msgstr "Comunicar \"bugs\" a <%s>.\n"
4662 #: src/hello.c:200 src/bye.c:100
4664 msgid "Report bugs to <%s>.\n"
4666 "#-#-#-#-# file1.po #-#-#-#-#\n"
4667 "Comunicar `bugs' a <%s>.\n"
4668 "#-#-#-#-# file2.po #-#-#-#-#\n"
4669 "Comunicar \"bugs\" a <%s>.\n"
4671 The translator will have to resolve this "conflict" manually; she has
4672 to decide whether the first or the second version is appropriate (or
4673 provide a new translation), to delete the "marker lines", and finally
4674 to remove the `fuzzy' mark.
4676 If the translator knows in advance the first found translation of a
4677 message is always the best translation she can make use to the
4678 `--use-first' switch:
4680 msgcat --use-first -o compendium.po file1.po file2.po
4682 A good compendium file must not contain `fuzzy' or untranslated
4683 entries. If input files are "dirty" you must preprocess the input
4684 files or postprocess the result using `msgattrib --translated
4687 8.4.1.2 Extract a Message Subset from a PO File
4688 ...............................................
4690 Nobody wants to translate the same messages again and again; thus you
4691 may wish to have a compendium file containing `getopt.c' messages.
4693 To extract a message subset (e.g., all `getopt.c' messages) from an
4694 existing PO file into one compendium file you can use `msggrep':
4696 msggrep --location src/getopt.c -o compendium.po file.po
4699 File: gettext.info, Node: Using Compendia, Prev: Creating Compendia, Up: Compendium
4701 8.4.2 Using Compendia
4702 ---------------------
4704 You can use a compendium file to initialize a translation from
4705 scratch or to update an already existing translation.
4707 8.4.2.1 Initialize a New Translation File
4708 .........................................
4710 Since a PO file with translations does not exist the translator can
4711 merely use `/dev/null' to fake the "old" translation file.
4713 msgmerge --compendium compendium.po -o file.po /dev/null file.pot
4715 8.4.2.2 Update an Existing Translation File
4716 ...........................................
4718 Concatenate the compendium file(s) and the existing PO, merge the
4719 result with the POT file and remove the obsolete entries (optional,
4720 here done using `sed'):
4722 msgcat --use-first -o update.po compendium1.po compendium2.po file.po
4723 msgmerge update.po file.pot | msgattrib --no-obsolete > file.po
4726 File: gettext.info, Node: Manipulating, Next: Binaries, Prev: Editing, Up: Top
4728 9 Manipulating PO Files
4729 ***********************
4731 Sometimes it is necessary to manipulate PO files in a way that is
4732 better performed automatically than by hand. GNU `gettext' includes a
4733 complete set of tools for this purpose.
4735 When merging two packages into a single package, the resulting POT
4736 file will be the concatenation of the two packages' POT files. Thus the
4737 maintainer must concatenate the two existing package translations into
4738 a single translation catalog, for each language. This is best performed
4739 using `msgcat'. It is then the translators' duty to deal with any
4740 possible conflicts that arose during the merge.
4742 When a translator takes over the translation job from another
4743 translator, but she uses a different character encoding in her locale,
4744 she will convert the catalog to her character encoding. This is best
4745 done through the `msgconv' program.
4747 When a maintainer takes a source file with tagged messages from
4748 another package, he should also take the existing translations for this
4749 source file (and not let the translators do the same job twice). One
4750 way to do this is through `msggrep', another is to create a POT file for
4751 that source file and use `msgmerge'.
4753 When a translator wants to adjust some translation catalog for a
4754 special dialect or orthography -- for example, German as written in
4755 Switzerland versus German as written in Germany -- she needs to apply
4756 some text processing to every message in the catalog. The tool for
4757 doing this is `msgfilter'.
4759 Another use of `msgfilter' is to produce approximately the POT file
4760 for which a given PO file was made. This can be done through a filter
4761 command like `msgfilter sed -e d | sed -e '/^# /d''. Note that the
4762 original POT file may have had different comments and different plural
4763 message counts, that's why it's better to use the original POT file if
4766 When a translator wants to check her translations, for example
4767 according to orthography rules or using a non-interactive spell
4768 checker, she can do so using the `msgexec' program.
4770 When third party tools create PO or POT files, sometimes duplicates
4771 cannot be avoided. But the GNU `gettext' tools give an error when they
4772 encounter duplicate msgids in the same file and in the same domain. To
4773 merge duplicates, the `msguniq' program can be used.
4775 `msgcomm' is a more general tool for keeping or throwing away
4776 duplicates, occurring in different files.
4778 `msgcmp' can be used to check whether a translation catalog is
4779 completely translated.
4781 `msgattrib' can be used to select and extract only the fuzzy or
4782 untranslated messages of a translation catalog.
4784 `msgen' is useful as a first step for preparing English translation
4785 catalogs. It copies each message's msgid to its msgstr.
4787 Finally, for those applications where all these various programs are
4788 not sufficient, a library `libgettextpo' is provided that can be used to
4789 write other specialized programs that process PO files.
4793 * msgcat Invocation:: Invoking the `msgcat' Program
4794 * msgconv Invocation:: Invoking the `msgconv' Program
4795 * msggrep Invocation:: Invoking the `msggrep' Program
4796 * msgfilter Invocation:: Invoking the `msgfilter' Program
4797 * msguniq Invocation:: Invoking the `msguniq' Program
4798 * msgcomm Invocation:: Invoking the `msgcomm' Program
4799 * msgcmp Invocation:: Invoking the `msgcmp' Program
4800 * msgattrib Invocation:: Invoking the `msgattrib' Program
4801 * msgen Invocation:: Invoking the `msgen' Program
4802 * msgexec Invocation:: Invoking the `msgexec' Program
4803 * Colorizing:: Highlighting parts of PO files
4804 * libgettextpo:: Writing your own programs that process PO files
4807 File: gettext.info, Node: msgcat Invocation, Next: msgconv Invocation, Prev: Manipulating, Up: Manipulating
4809 9.1 Invoking the `msgcat' Program
4810 =================================
4812 msgcat [OPTION] [INPUTFILE]...
4814 The `msgcat' program concatenates and merges the specified PO files.
4815 It finds messages which are common to two or more of the specified PO
4816 files. By using the `--more-than' option, greater commonality may be
4817 requested before messages are printed. Conversely, the `--less-than'
4818 option may be used to specify less commonality before messages are
4819 printed (i.e. `--less-than=2' will only print the unique messages).
4820 Translations, comments and extract comments will be cumulated, except
4821 that if `--use-first' is specified, they will be taken from the first
4822 PO file to define them. File positions from all PO files will be
4825 9.1.1 Input file location
4826 -------------------------
4833 Read the names of the input files from FILE instead of getting
4834 them from the command line.
4837 `--directory=DIRECTORY'
4838 Add DIRECTORY to the list of directories. Source files are
4839 searched relative to this list of directories. The resulting `.po'
4840 file will be written relative to the current directory, though.
4843 If INPUTFILE is `-', standard input is read.
4845 9.1.2 Output file location
4846 --------------------------
4849 `--output-file=FILE'
4850 Write output to specified file.
4853 The results are written to standard output if no output file is
4854 specified or if it is `-'.
4856 9.1.3 Message selection
4857 -----------------------
4860 `--less-than=NUMBER'
4861 Print messages with less than NUMBER definitions, defaults to
4862 infinite if not set.
4865 `--more-than=NUMBER'
4866 Print messages with more than NUMBER definitions, defaults to 0 if
4871 Shorthand for `--less-than=2'. Requests that only unique messages
4875 9.1.4 Input file syntax
4876 -----------------------
4879 `--properties-input'
4880 Assume the input files are Java ResourceBundles in Java
4881 `.properties' syntax, not in PO file syntax.
4883 `--stringtable-input'
4884 Assume the input files are NeXTstep/GNUstep localized resource
4885 files in `.strings' syntax, not in PO file syntax.
4888 9.1.5 Output details
4889 --------------------
4893 Specify encoding for output.
4896 Use first available translation for each message. Don't merge
4897 several translations into one.
4899 `--lang=CATALOGNAME'
4900 Specify the `Language' field to be used in the header entry. See
4901 *note Header Entry:: for the meaning of this field. Note: The
4902 `Language-Team' and `Plural-Forms' fields are left unchanged.
4906 Specify whether or when to use colors and other text attributes.
4907 See *note The --color option:: for details.
4909 `--style=STYLE_FILE'
4910 Specify the CSS style rule file to use for `--color'. See *note
4911 The --style option:: for details.
4914 Always write an output file even if it contains no message.
4918 Write the .po file using indented style.
4921 Do not write `#: FILENAME:LINE' lines.
4925 Generate `#: FILENAME:LINE' lines (default).
4928 Write out a strict Uniforum conforming PO file. Note that this
4929 Uniforum format should be avoided because it doesn't support the
4933 `--properties-output'
4934 Write out a Java ResourceBundle in Java `.properties' syntax. Note
4935 that this file format doesn't support plural forms and silently
4936 drops obsolete messages.
4938 `--stringtable-output'
4939 Write out a NeXTstep/GNUstep localized resource file in `.strings'
4940 syntax. Note that this file format doesn't support plural forms.
4944 Set the output page width. Long strings in the output files will
4945 be split across multiple lines in order to ensure that each line's
4946 width (= number of screen columns) is less or equal to the given
4950 Do not break long message lines. Message lines whose width
4951 exceeds the output page width will not be split into several
4952 lines. Only file reference lines which are wider than the output
4953 page width will be split.
4957 Generate sorted output. Note that using this option makes it much
4958 harder for the translator to understand each message's context.
4962 Sort output by file location.
4965 9.1.6 Informative output
4966 ------------------------
4970 Display this help and exit.
4974 Output version information and exit.
4978 File: gettext.info, Node: msgconv Invocation, Next: msggrep Invocation, Prev: msgcat Invocation, Up: Manipulating
4980 9.2 Invoking the `msgconv' Program
4981 ==================================
4983 msgconv [OPTION] [INPUTFILE]
4985 The `msgconv' program converts a translation catalog to a different
4988 9.2.1 Input file location
4989 -------------------------
4995 `--directory=DIRECTORY'
4996 Add DIRECTORY to the list of directories. Source files are
4997 searched relative to this list of directories. The resulting `.po'
4998 file will be written relative to the current directory, though.
5001 If no INPUTFILE is given or if it is `-', standard input is read.
5003 9.2.2 Output file location
5004 --------------------------
5007 `--output-file=FILE'
5008 Write output to specified file.
5011 The results are written to standard output if no output file is
5012 specified or if it is `-'.
5014 9.2.3 Conversion target
5015 -----------------------
5019 Specify encoding for output.
5022 The default encoding is the current locale's encoding.
5024 9.2.4 Input file syntax
5025 -----------------------
5028 `--properties-input'
5029 Assume the input file is a Java ResourceBundle in Java
5030 `.properties' syntax, not in PO file syntax.
5032 `--stringtable-input'
5033 Assume the input file is a NeXTstep/GNUstep localized resource
5034 file in `.strings' syntax, not in PO file syntax.
5037 9.2.5 Output details
5038 --------------------
5042 Specify whether or when to use colors and other text attributes.
5043 See *note The --color option:: for details.
5045 `--style=STYLE_FILE'
5046 Specify the CSS style rule file to use for `--color'. See *note
5047 The --style option:: for details.
5050 Always write an output file even if it contains no message.
5054 Write the .po file using indented style.
5057 Do not write `#: FILENAME:LINE' lines.
5060 Generate `#: FILENAME:LINE' lines (default).
5063 Write out a strict Uniforum conforming PO file. Note that this
5064 Uniforum format should be avoided because it doesn't support the
5068 `--properties-output'
5069 Write out a Java ResourceBundle in Java `.properties' syntax. Note
5070 that this file format doesn't support plural forms and silently
5071 drops obsolete messages.
5073 `--stringtable-output'
5074 Write out a NeXTstep/GNUstep localized resource file in `.strings'
5075 syntax. Note that this file format doesn't support plural forms.
5079 Set the output page width. Long strings in the output files will
5080 be split across multiple lines in order to ensure that each line's
5081 width (= number of screen columns) is less or equal to the given
5085 Do not break long message lines. Message lines whose width
5086 exceeds the output page width will not be split into several
5087 lines. Only file reference lines which are wider than the output
5088 page width will be split.
5092 Generate sorted output. Note that using this option makes it much
5093 harder for the translator to understand each message's context.
5097 Sort output by file location.
5100 9.2.6 Informative output
5101 ------------------------
5105 Display this help and exit.
5109 Output version information and exit.
5113 File: gettext.info, Node: msggrep Invocation, Next: msgfilter Invocation, Prev: msgconv Invocation, Up: Manipulating
5115 9.3 Invoking the `msggrep' Program
5116 ==================================
5118 msggrep [OPTION] [INPUTFILE]
5120 The `msggrep' program extracts all messages of a translation catalog
5121 that match a given pattern or belong to some given source files.
5123 9.3.1 Input file location
5124 -------------------------
5130 `--directory=DIRECTORY'
5131 Add DIRECTORY to the list of directories. Source files are
5132 searched relative to this list of directories. The resulting `.po'
5133 file will be written relative to the current directory, though.
5136 If no INPUTFILE is given or if it is `-', standard input is read.
5138 9.3.2 Output file location
5139 --------------------------
5142 `--output-file=FILE'
5143 Write output to specified file.
5146 The results are written to standard output if no output file is
5147 specified or if it is `-'.
5149 9.3.3 Message selection
5150 -----------------------
5152 [-N SOURCEFILE]... [-M DOMAINNAME]...
5153 [-J MSGCTXT-PATTERN] [-K MSGID-PATTERN] [-T MSGSTR-PATTERN]
5154 [-C COMMENT-PATTERN]
5156 A message is selected if
5157 * it comes from one of the specified source files,
5159 * or if it comes from one of the specified domains,
5161 * or if `-J' is given and its context (msgctxt) matches
5164 * or if `-K' is given and its key (msgid or msgid_plural) matches
5167 * or if `-T' is given and its translation (msgstr) matches
5170 * or if `-C' is given and the translator's comment matches
5173 When more than one selection criterion is specified, the set of
5174 selected messages is the union of the selected messages of each
5177 MSGCTXT-PATTERN or MSGID-PATTERN or MSGSTR-PATTERN syntax:
5178 [-E | -F] [-e PATTERN | -f FILE]...
5179 PATTERNs are basic regular expressions by default, or extended
5180 regular expressions if -E is given, or fixed strings if -F is given.
5183 `--location=SOURCEFILE'
5184 Select messages extracted from SOURCEFILE. SOURCEFILE can be
5185 either a literal file name or a wildcard pattern.
5188 `--domain=DOMAINNAME'
5189 Select messages belonging to domain DOMAINNAME.
5193 Start of patterns for the msgctxt.
5197 Start of patterns for the msgid.
5201 Start of patterns for the msgstr.
5205 Start of patterns for the translator's comment.
5208 `--extracted-comment'
5209 Start of patterns for the extracted comments.
5213 Specify that PATTERN is an extended regular expression.
5217 Specify that PATTERN is a set of newline-separated strings.
5221 Use PATTERN as a regular expression.
5225 Obtain PATTERN from FILE.
5229 Ignore case distinctions.
5233 Output only the messages that do not match any selection
5234 criterion, instead of the messages that match a selection
5238 9.3.4 Input file syntax
5239 -----------------------
5242 `--properties-input'
5243 Assume the input file is a Java ResourceBundle in Java
5244 `.properties' syntax, not in PO file syntax.
5246 `--stringtable-input'
5247 Assume the input file is a NeXTstep/GNUstep localized resource
5248 file in `.strings' syntax, not in PO file syntax.
5251 9.3.5 Output details
5252 --------------------
5256 Specify whether or when to use colors and other text attributes.
5257 See *note The --color option:: for details.
5259 `--style=STYLE_FILE'
5260 Specify the CSS style rule file to use for `--color'. See *note
5261 The --style option:: for details.
5264 Always write an output file even if it contains no message.
5267 Write the .po file using indented style.
5270 Do not write `#: FILENAME:LINE' lines.
5273 Generate `#: FILENAME:LINE' lines (default).
5276 Write out a strict Uniforum conforming PO file. Note that this
5277 Uniforum format should be avoided because it doesn't support the
5281 `--properties-output'
5282 Write out a Java ResourceBundle in Java `.properties' syntax. Note
5283 that this file format doesn't support plural forms and silently
5284 drops obsolete messages.
5286 `--stringtable-output'
5287 Write out a NeXTstep/GNUstep localized resource file in `.strings'
5288 syntax. Note that this file format doesn't support plural forms.
5292 Set the output page width. Long strings in the output files will
5293 be split across multiple lines in order to ensure that each line's
5294 width (= number of screen columns) is less or equal to the given
5298 Do not break long message lines. Message lines whose width
5299 exceeds the output page width will not be split into several
5300 lines. Only file reference lines which are wider than the output
5301 page width will be split.
5304 Generate sorted output. Note that using this option makes it much
5305 harder for the translator to understand each message's context.
5308 Sort output by file location.
5311 9.3.6 Informative output
5312 ------------------------
5316 Display this help and exit.
5320 Output version information and exit.
5326 To extract the messages that come from the source files
5327 `gnulib-lib/error.c' and `gnulib-lib/getopt.c':
5329 msggrep -N gnulib-lib/error.c -N gnulib-lib/getopt.c input.po
5331 To extract the messages that contain the string "Please specify" in
5332 the original string:
5334 msggrep --msgid -F -e 'Please specify' input.po
5336 To extract the messages that have a context specifier of either
5337 "Menu>File" or "Menu>Edit" or a submenu of them:
5339 msggrep --msgctxt -E -e '^Menu>(File|Edit)' input.po
5341 To extract the messages whose translation contains one of the
5342 strings in the file `wordlist.txt':
5344 msggrep --msgstr -F -f wordlist.txt input.po
5347 File: gettext.info, Node: msgfilter Invocation, Next: msguniq Invocation, Prev: msggrep Invocation, Up: Manipulating
5349 9.4 Invoking the `msgfilter' Program
5350 ====================================
5352 msgfilter [OPTION] FILTER [FILTER-OPTION]
5354 The `msgfilter' program applies a filter to all translations of a
5355 translation catalog.
5357 During each FILTER invocation, the environment variable
5358 `MSGFILTER_MSGID' is bound to the message's msgid, and the environment
5359 variable `MSGFILTER_LOCATION' is bound to the location in the PO file
5360 of the message. If the message has a context, the environment variable
5361 `MSGFILTER_MSGCTXT' is bound to the message's msgctxt, otherwise it is
5364 9.4.1 Input file location
5365 -------------------------
5372 `--directory=DIRECTORY'
5373 Add DIRECTORY to the list of directories. Source files are
5374 searched relative to this list of directories. The resulting `.po'
5375 file will be written relative to the current directory, though.
5378 If no INPUTFILE is given or if it is `-', standard input is read.
5380 9.4.2 Output file location
5381 --------------------------
5384 `--output-file=FILE'
5385 Write output to specified file.
5388 The results are written to standard output if no output file is
5389 specified or if it is `-'.
5394 The FILTER can be any program that reads a translation from standard
5395 input and writes a modified translation to standard output. A
5396 frequently used filter is `sed'. A few particular built-in filters are
5399 Note: If the filter is not a built-in filter, you have to care about
5400 encodings: It is your responsibility to ensure that the FILTER can cope
5401 with input encoded in the translation catalog's encoding. If the
5402 FILTER wants input in a particular encoding, you can in a first step
5403 convert the translation catalog to that encoding using the `msgconv'
5404 program, before invoking `msgfilter'. If the FILTER wants input in the
5405 locale's encoding, but you want to avoid the locale's encoding, then
5406 you can first convert the translation catalog to UTF-8 using the
5407 `msgconv' program and then make `msgfilter' work in an UTF-8 locale, by
5408 using the `LC_ALL' environment variable.
5410 Note: Most translations in a translation catalog don't end with a
5411 newline character. For this reason, it is important that the FILTER
5412 recognizes its last input line even if it ends without a newline, and
5413 that it doesn't add an undesired trailing newline at the end. The `sed'
5414 program on some platforms is known to ignore the last line of input if
5415 it is not terminated with a newline. You can use GNU `sed' instead; it
5416 does not have this limitation.
5418 9.4.4 Useful FILTER-OPTIONs when the FILTER is `sed'
5419 ----------------------------------------------------
5422 `--expression=SCRIPT'
5423 Add SCRIPT to the commands to be executed.
5427 Add the contents of SCRIPTFILE to the commands to be executed.
5432 Suppress automatic printing of pattern space.
5435 9.4.5 Built-in FILTERs
5436 ----------------------
5438 The filter `recode-sr-latin' is recognized as a built-in filter.
5439 The command `recode-sr-latin' converts Serbian text, written in the
5440 Cyrillic script, to the Latin script. The command `msgfilter
5441 recode-sr-latin' applies this conversion to the translations of a PO
5442 file. Thus, it can be used to convert an `sr.po' file to an
5445 The use of built-in filters is not sensitive to the current locale's
5446 encoding. Moreover, when used with a built-in filter, `msgfilter' can
5447 automatically convert the message catalog to the UTF-8 encoding when
5450 9.4.6 Input file syntax
5451 -----------------------
5454 `--properties-input'
5455 Assume the input file is a Java ResourceBundle in Java
5456 `.properties' syntax, not in PO file syntax.
5458 `--stringtable-input'
5459 Assume the input file is a NeXTstep/GNUstep localized resource
5460 file in `.strings' syntax, not in PO file syntax.
5463 9.4.7 Output details
5464 --------------------
5468 Specify whether or when to use colors and other text attributes.
5469 See *note The --color option:: for details.
5471 `--style=STYLE_FILE'
5472 Specify the CSS style rule file to use for `--color'. See *note
5473 The --style option:: for details.
5476 Always write an output file even if it contains no message.
5479 Write the .po file using indented style.
5482 Keep the header entry, i.e. the message with `msgid ""',
5483 unmodified, instead of filtering it. By default, the header entry
5484 is subject to filtering like any other message.
5487 Do not write `#: FILENAME:LINE' lines.
5490 Generate `#: FILENAME:LINE' lines (default).
5493 Write out a strict Uniforum conforming PO file. Note that this
5494 Uniforum format should be avoided because it doesn't support the
5498 `--properties-output'
5499 Write out a Java ResourceBundle in Java `.properties' syntax. Note
5500 that this file format doesn't support plural forms and silently
5501 drops obsolete messages.
5503 `--stringtable-output'
5504 Write out a NeXTstep/GNUstep localized resource file in `.strings'
5505 syntax. Note that this file format doesn't support plural forms.
5509 Set the output page width. Long strings in the output files will
5510 be split across multiple lines in order to ensure that each line's
5511 width (= number of screen columns) is less or equal to the given
5515 Do not break long message lines. Message lines whose width
5516 exceeds the output page width will not be split into several
5517 lines. Only file reference lines which are wider than the output
5518 page width will be split.
5522 Generate sorted output. Note that using this option makes it much
5523 harder for the translator to understand each message's context.
5527 Sort output by file location.
5530 9.4.8 Informative output
5531 ------------------------
5535 Display this help and exit.
5539 Output version information and exit.
5545 To convert German translations to Swiss orthography (in an UTF-8
5548 msgconv -t UTF-8 de.po | msgfilter sed -e 's/ß/ss/g'
5550 To convert Serbian translations in Cyrillic script to Latin script:
5552 msgfilter recode-sr-latin < sr.po
5555 File: gettext.info, Node: msguniq Invocation, Next: msgcomm Invocation, Prev: msgfilter Invocation, Up: Manipulating
5557 9.5 Invoking the `msguniq' Program
5558 ==================================
5560 msguniq [OPTION] [INPUTFILE]
5562 The `msguniq' program unifies duplicate translations in a translation
5563 catalog. It finds duplicate translations of the same message ID. Such
5564 duplicates are invalid input for other programs like `msgfmt',
5565 `msgmerge' or `msgcat'. By default, duplicates are merged together.
5566 When using the `--repeated' option, only duplicates are output, and all
5567 other messages are discarded. Comments and extracted comments will be
5568 cumulated, except that if `--use-first' is specified, they will be
5569 taken from the first translation. File positions will be cumulated.
5570 When using the `--unique' option, duplicates are discarded.
5572 9.5.1 Input file location
5573 -------------------------
5579 `--directory=DIRECTORY'
5580 Add DIRECTORY to the list of directories. Source files are
5581 searched relative to this list of directories. The resulting `.po'
5582 file will be written relative to the current directory, though.
5585 If no INPUTFILE is given or if it is `-', standard input is read.
5587 9.5.2 Output file location
5588 --------------------------
5591 `--output-file=FILE'
5592 Write output to specified file.
5595 The results are written to standard output if no output file is
5596 specified or if it is `-'.
5598 9.5.3 Message selection
5599 -----------------------
5603 Print only duplicates.
5607 Print only unique messages, discard duplicates.
5610 9.5.4 Input file syntax
5611 -----------------------
5614 `--properties-input'
5615 Assume the input file is a Java ResourceBundle in Java
5616 `.properties' syntax, not in PO file syntax.
5618 `--stringtable-input'
5619 Assume the input file is a NeXTstep/GNUstep localized resource
5620 file in `.strings' syntax, not in PO file syntax.
5623 9.5.5 Output details
5624 --------------------
5628 Specify encoding for output.
5631 Use first available translation for each message. Don't merge
5632 several translations into one.
5636 Specify whether or when to use colors and other text attributes.
5637 See *note The --color option:: for details.
5639 `--style=STYLE_FILE'
5640 Specify the CSS style rule file to use for `--color'. See *note
5641 The --style option:: for details.
5644 Always write an output file even if it contains no message.
5648 Write the .po file using indented style.
5651 Do not write `#: FILENAME:LINE' lines.
5655 Generate `#: FILENAME:LINE' lines (default).
5658 Write out a strict Uniforum conforming PO file. Note that this
5659 Uniforum format should be avoided because it doesn't support the
5663 `--properties-output'
5664 Write out a Java ResourceBundle in Java `.properties' syntax. Note
5665 that this file format doesn't support plural forms and silently
5666 drops obsolete messages.
5668 `--stringtable-output'
5669 Write out a NeXTstep/GNUstep localized resource file in `.strings'
5670 syntax. Note that this file format doesn't support plural forms.
5674 Set the output page width. Long strings in the output files will
5675 be split across multiple lines in order to ensure that each line's
5676 width (= number of screen columns) is less or equal to the given
5680 Do not break long message lines. Message lines whose width
5681 exceeds the output page width will not be split into several
5682 lines. Only file reference lines which are wider than the output
5683 page width will be split.
5687 Generate sorted output. Note that using this option makes it much
5688 harder for the translator to understand each message's context.
5692 Sort output by file location.
5695 9.5.6 Informative output
5696 ------------------------
5700 Display this help and exit.
5704 Output version information and exit.
5708 File: gettext.info, Node: msgcomm Invocation, Next: msgcmp Invocation, Prev: msguniq Invocation, Up: Manipulating
5710 9.6 Invoking the `msgcomm' Program
5711 ==================================
5713 msgcomm [OPTION] [INPUTFILE]...
5715 The `msgcomm' program finds messages which are common to two or more
5716 of the specified PO files. By using the `--more-than' option, greater
5717 commonality may be requested before messages are printed. Conversely,
5718 the `--less-than' option may be used to specify less commonality before
5719 messages are printed (i.e. `--less-than=2' will only print the unique
5720 messages). Translations, comments and extract comments will be
5721 preserved, but only from the first PO file to define them. File
5722 positions from all PO files will be cumulated.
5724 9.6.1 Input file location
5725 -------------------------
5732 Read the names of the input files from FILE instead of getting
5733 them from the command line.
5736 `--directory=DIRECTORY'
5737 Add DIRECTORY to the list of directories. Source files are
5738 searched relative to this list of directories. The resulting `.po'
5739 file will be written relative to the current directory, though.
5742 If INPUTFILE is `-', standard input is read.
5744 9.6.2 Output file location
5745 --------------------------
5748 `--output-file=FILE'
5749 Write output to specified file.
5752 The results are written to standard output if no output file is
5753 specified or if it is `-'.
5755 9.6.3 Message selection
5756 -----------------------
5759 `--less-than=NUMBER'
5760 Print messages with less than NUMBER definitions, defaults to
5761 infinite if not set.
5764 `--more-than=NUMBER'
5765 Print messages with more than NUMBER definitions, defaults to 1 if
5770 Shorthand for `--less-than=2'. Requests that only unique messages
5774 9.6.4 Input file syntax
5775 -----------------------
5778 `--properties-input'
5779 Assume the input files are Java ResourceBundles in Java
5780 `.properties' syntax, not in PO file syntax.
5782 `--stringtable-input'
5783 Assume the input files are NeXTstep/GNUstep localized resource
5784 files in `.strings' syntax, not in PO file syntax.
5787 9.6.5 Output details
5788 --------------------
5792 Specify whether or when to use colors and other text attributes.
5793 See *note The --color option:: for details.
5795 `--style=STYLE_FILE'
5796 Specify the CSS style rule file to use for `--color'. See *note
5797 The --style option:: for details.
5800 Always write an output file even if it contains no message.
5804 Write the .po file using indented style.
5807 Do not write `#: FILENAME:LINE' lines.
5811 Generate `#: FILENAME:LINE' lines (default).
5814 Write out a strict Uniforum conforming PO file. Note that this
5815 Uniforum format should be avoided because it doesn't support the
5819 `--properties-output'
5820 Write out a Java ResourceBundle in Java `.properties' syntax. Note
5821 that this file format doesn't support plural forms and silently
5822 drops obsolete messages.
5824 `--stringtable-output'
5825 Write out a NeXTstep/GNUstep localized resource file in `.strings'
5826 syntax. Note that this file format doesn't support plural forms.
5830 Set the output page width. Long strings in the output files will
5831 be split across multiple lines in order to ensure that each line's
5832 width (= number of screen columns) is less or equal to the given
5836 Do not break long message lines. Message lines whose width
5837 exceeds the output page width will not be split into several
5838 lines. Only file reference lines which are wider than the output
5839 page width will be split.
5843 Generate sorted output. Note that using this option makes it much
5844 harder for the translator to understand each message's context.
5848 Sort output by file location.
5851 Don't write header with `msgid ""' entry.
5854 9.6.6 Informative output
5855 ------------------------
5859 Display this help and exit.
5863 Output version information and exit.
5867 File: gettext.info, Node: msgcmp Invocation, Next: msgattrib Invocation, Prev: msgcomm Invocation, Up: Manipulating
5869 9.7 Invoking the `msgcmp' Program
5870 =================================
5872 msgcmp [OPTION] DEF.po REF.pot
5874 The `msgcmp' program compares two Uniforum style .po files to check
5875 that both contain the same set of msgid strings. The DEF.po file is an
5876 existing PO file with the translations. The REF.pot file is the last
5877 created PO file, or a PO Template file (generally created by
5878 `xgettext'). This is useful for checking that you have translated each
5879 and every message in your program. Where an exact match cannot be
5880 found, fuzzy matching is used to produce better diagnostics.
5882 9.7.1 Input file location
5883 -------------------------
5889 References to the sources.
5892 `--directory=DIRECTORY'
5893 Add DIRECTORY to the list of directories. Source files are
5894 searched relative to this list of directories.
5897 9.7.2 Operation modifiers
5898 -------------------------
5902 Apply REF.pot to each of the domains in DEF.po.
5905 `--no-fuzzy-matching'
5906 Do not use fuzzy matching when an exact match is not found. This
5907 may speed up the operation considerably.
5910 Consider fuzzy messages in the DEF.po file like translated
5911 messages. Note that using this option is usually wrong, because
5912 fuzzy messages are exactly those which have not been validated by
5915 `--use-untranslated'
5916 Consider untranslated messages in the DEF.po file like translated
5917 messages. Note that using this option is usually wrong.
5920 9.7.3 Input file syntax
5921 -----------------------
5924 `--properties-input'
5925 Assume the input files are Java ResourceBundles in Java
5926 `.properties' syntax, not in PO file syntax.
5928 `--stringtable-input'
5929 Assume the input files are NeXTstep/GNUstep localized resource
5930 files in `.strings' syntax, not in PO file syntax.
5933 9.7.4 Informative output
5934 ------------------------
5938 Display this help and exit.
5942 Output version information and exit.
5946 File: gettext.info, Node: msgattrib Invocation, Next: msgen Invocation, Prev: msgcmp Invocation, Up: Manipulating
5948 9.8 Invoking the `msgattrib' Program
5949 ====================================
5951 msgattrib [OPTION] [INPUTFILE]
5953 The `msgattrib' program filters the messages of a translation catalog
5954 according to their attributes, and manipulates the attributes.
5956 9.8.1 Input file location
5957 -------------------------
5963 `--directory=DIRECTORY'
5964 Add DIRECTORY to the list of directories. Source files are
5965 searched relative to this list of directories. The resulting `.po'
5966 file will be written relative to the current directory, though.
5969 If no INPUTFILE is given or if it is `-', standard input is read.
5971 9.8.2 Output file location
5972 --------------------------
5975 `--output-file=FILE'
5976 Write output to specified file.
5979 The results are written to standard output if no output file is
5980 specified or if it is `-'.
5982 9.8.3 Message selection
5983 -----------------------
5986 Keep translated messages, remove untranslated messages.
5989 Keep untranslated messages, remove translated messages.
5992 Remove `fuzzy' marked messages.
5995 Keep `fuzzy' marked messages, remove all other messages.
5998 Remove obsolete #~ messages.
6001 Keep obsolete #~ messages, remove all other messages.
6004 9.8.4 Attribute manipulation
6005 ----------------------------
6007 Attributes are modified after the message selection/removal has been
6008 performed. If the `--only-file' or `--ignore-file' option is
6009 specified, the attribute modification is applied only to those messages
6010 that are listed in the ONLY-FILE and not listed in the IGNORE-FILE.
6013 Set all messages `fuzzy'.
6016 Set all messages non-`fuzzy'.
6019 Set all messages obsolete.
6022 Set all messages non-obsolete.
6025 Remove the "previous msgid" (`#|') comments from all messages.
6028 Limit the attribute changes to entries that are listed in FILE.
6029 FILE should be a PO or POT file.
6031 `--ignore-file=FILE'
6032 Limit the attribute changes to entries that are not listed in FILE.
6033 FILE should be a PO or POT file.
6036 Synonym for `--only-fuzzy --clear-fuzzy': It keeps only the fuzzy
6037 messages and removes their `fuzzy' mark.
6040 Synonym for `--only-obsolete --clear-obsolete': It keeps only the
6041 obsolete messages and makes them non-obsolete.
6044 9.8.5 Input file syntax
6045 -----------------------
6048 `--properties-input'
6049 Assume the input file is a Java ResourceBundle in Java
6050 `.properties' syntax, not in PO file syntax.
6052 `--stringtable-input'
6053 Assume the input file is a NeXTstep/GNUstep localized resource
6054 file in `.strings' syntax, not in PO file syntax.
6057 9.8.6 Output details
6058 --------------------
6062 Specify whether or when to use colors and other text attributes.
6063 See *note The --color option:: for details.
6065 `--style=STYLE_FILE'
6066 Specify the CSS style rule file to use for `--color'. See *note
6067 The --style option:: for details.
6070 Always write an output file even if it contains no message.
6074 Write the .po file using indented style.
6077 Do not write `#: FILENAME:LINE' lines.
6081 Generate `#: FILENAME:LINE' lines (default).
6084 Write out a strict Uniforum conforming PO file. Note that this
6085 Uniforum format should be avoided because it doesn't support the
6089 `--properties-output'
6090 Write out a Java ResourceBundle in Java `.properties' syntax. Note
6091 that this file format doesn't support plural forms and silently
6092 drops obsolete messages.
6094 `--stringtable-output'
6095 Write out a NeXTstep/GNUstep localized resource file in `.strings'
6096 syntax. Note that this file format doesn't support plural forms.
6100 Set the output page width. Long strings in the output files will
6101 be split across multiple lines in order to ensure that each line's
6102 width (= number of screen columns) is less or equal to the given
6106 Do not break long message lines. Message lines whose width
6107 exceeds the output page width will not be split into several
6108 lines. Only file reference lines which are wider than the output
6109 page width will be split.
6113 Generate sorted output. Note that using this option makes it much
6114 harder for the translator to understand each message's context.
6118 Sort output by file location.
6121 9.8.7 Informative output
6122 ------------------------
6126 Display this help and exit.
6130 Output version information and exit.
6134 File: gettext.info, Node: msgen Invocation, Next: msgexec Invocation, Prev: msgattrib Invocation, Up: Manipulating
6136 9.9 Invoking the `msgen' Program
6137 ================================
6139 msgen [OPTION] INPUTFILE
6141 The `msgen' program creates an English translation catalog. The
6142 input file is the last created English PO file, or a PO Template file
6143 (generally created by xgettext). Untranslated entries are assigned a
6144 translation that is identical to the msgid.
6146 Note: `msginit --no-translator --locale=en' performs a very similar
6147 task. The main difference is that `msginit' cares specially about the
6148 header entry, whereas `msgen' doesn't.
6150 9.9.1 Input file location
6151 -------------------------
6154 Input PO or POT file.
6157 `--directory=DIRECTORY'
6158 Add DIRECTORY to the list of directories. Source files are
6159 searched relative to this list of directories. The resulting `.po'
6160 file will be written relative to the current directory, though.
6163 If INPUTFILE is `-', standard input is read.
6165 9.9.2 Output file location
6166 --------------------------
6169 `--output-file=FILE'
6170 Write output to specified file.
6173 The results are written to standard output if no output file is
6174 specified or if it is `-'.
6176 9.9.3 Input file syntax
6177 -----------------------
6180 `--properties-input'
6181 Assume the input file is a Java ResourceBundle in Java
6182 `.properties' syntax, not in PO file syntax.
6184 `--stringtable-input'
6185 Assume the input file is a NeXTstep/GNUstep localized resource
6186 file in `.strings' syntax, not in PO file syntax.
6189 9.9.4 Output details
6190 --------------------
6192 `--lang=CATALOGNAME'
6193 Specify the `Language' field to be used in the header entry. See
6194 *note Header Entry:: for the meaning of this field. Note: The
6195 `Language-Team' and `Plural-Forms' fields are not set by this
6200 Specify whether or when to use colors and other text attributes.
6201 See *note The --color option:: for details.
6203 `--style=STYLE_FILE'
6204 Specify the CSS style rule file to use for `--color'. See *note
6205 The --style option:: for details.
6208 Always write an output file even if it contains no message.
6212 Write the .po file using indented style.
6215 Do not write `#: FILENAME:LINE' lines.
6218 Generate `#: FILENAME:LINE' lines (default).
6221 Write out a strict Uniforum conforming PO file. Note that this
6222 Uniforum format should be avoided because it doesn't support the
6226 `--properties-output'
6227 Write out a Java ResourceBundle in Java `.properties' syntax. Note
6228 that this file format doesn't support plural forms and silently
6229 drops obsolete messages.
6231 `--stringtable-output'
6232 Write out a NeXTstep/GNUstep localized resource file in `.strings'
6233 syntax. Note that this file format doesn't support plural forms.
6237 Set the output page width. Long strings in the output files will
6238 be split across multiple lines in order to ensure that each line's
6239 width (= number of screen columns) is less or equal to the given
6243 Do not break long message lines. Message lines whose width
6244 exceeds the output page width will not be split into several
6245 lines. Only file reference lines which are wider than the output
6246 page width will be split.
6250 Generate sorted output. Note that using this option makes it much
6251 harder for the translator to understand each message's context.
6255 Sort output by file location.
6258 9.9.5 Informative output
6259 ------------------------
6263 Display this help and exit.
6267 Output version information and exit.
6271 File: gettext.info, Node: msgexec Invocation, Next: Colorizing, Prev: msgen Invocation, Up: Manipulating
6273 9.10 Invoking the `msgexec' Program
6274 ===================================
6276 msgexec [OPTION] COMMAND [COMMAND-OPTION]
6278 The `msgexec' program applies a command to all translations of a
6279 translation catalog. The COMMAND can be any program that reads a
6280 translation from standard input. It is invoked once for each
6281 translation. Its output becomes msgexec's output. `msgexec''s return
6282 code is the maximum return code across all invocations.
6284 A special builtin command called `0' outputs the translation,
6285 followed by a null byte. The output of `msgexec 0' is suitable as
6286 input for `xargs -0'.
6288 During each COMMAND invocation, the environment variable
6289 `MSGEXEC_MSGID' is bound to the message's msgid, and the environment
6290 variable `MSGEXEC_LOCATION' is bound to the location in the PO file of
6291 the message. If the message has a context, the environment variable
6292 `MSGEXEC_MSGCTXT' is bound to the message's msgctxt, otherwise it is
6295 Note: It is your responsibility to ensure that the COMMAND can cope
6296 with input encoded in the translation catalog's encoding. If the
6297 COMMAND wants input in a particular encoding, you can in a first step
6298 convert the translation catalog to that encoding using the `msgconv'
6299 program, before invoking `msgexec'. If the COMMAND wants input in the
6300 locale's encoding, but you want to avoid the locale's encoding, then
6301 you can first convert the translation catalog to UTF-8 using the
6302 `msgconv' program and then make `msgexec' work in an UTF-8 locale, by
6303 using the `LC_ALL' environment variable.
6305 9.10.1 Input file location
6306 --------------------------
6313 `--directory=DIRECTORY'
6314 Add DIRECTORY to the list of directories. Source files are
6315 searched relative to this list of directories. The resulting `.po'
6316 file will be written relative to the current directory, though.
6319 If no INPUTFILE is given or if it is `-', standard input is read.
6321 9.10.2 Input file syntax
6322 ------------------------
6325 `--properties-input'
6326 Assume the input file is a Java ResourceBundle in Java
6327 `.properties' syntax, not in PO file syntax.
6329 `--stringtable-input'
6330 Assume the input file is a NeXTstep/GNUstep localized resource
6331 file in `.strings' syntax, not in PO file syntax.
6334 9.10.3 Informative output
6335 -------------------------
6339 Display this help and exit.
6343 Output version information and exit.
6347 File: gettext.info, Node: Colorizing, Next: libgettextpo, Prev: msgexec Invocation, Up: Manipulating
6349 9.11 Highlighting parts of PO files
6350 ===================================
6352 Translators are usually only interested in seeing the untranslated
6353 and fuzzy messages of a PO file. Also, when a message is set fuzzy
6354 because the msgid changed, they want to see the differences between the
6355 previous msgid and the current one (especially if the msgid is long and
6356 only few words in it have changed). Finally, it's always welcome to
6357 highlight the different sections of a message in a PO file (comments,
6358 msgid, msgstr, etc.).
6360 Such highlighting is possible through the `msgcat' options `--color'
6365 * The --color option:: Triggering colorized output
6366 * The TERM variable:: The environment variable `TERM'
6367 * The --style option:: The `--style' option
6368 * Style rules:: Style rules for PO files
6369 * Customizing less:: Customizing `less' for viewing PO files
6372 File: gettext.info, Node: The --color option, Next: The TERM variable, Up: Colorizing
6374 9.11.1 The `--color' option
6375 ---------------------------
6377 The `--color=WHEN' option specifies under which conditions colorized
6378 output should be generated. The WHEN part can be one of the following:
6382 The output will be colorized.
6386 The output will not be colorized.
6390 The output will be colorized if the output device is a tty, i.e.
6391 when the output goes directly to a text screen or terminal
6395 The output will be colorized and be in HTML format.
6397 `--color' is equivalent to `--color=yes'. The default is
6400 Thus, a command like `msgcat vi.po' will produce colorized output
6401 when called by itself in a command window. Whereas in a pipe, such as
6402 `msgcat vi.po | less -R', it will not produce colorized output. To get
6403 colorized output in this situation nevertheless, use the command
6404 `msgcat --color vi.po | less -R'.
6406 The `--color=html' option will produce output that can be viewed in
6407 a browser. This can be useful, for example, for Indic languages,
6408 because the renderic of Indic scripts in browser is usually better than
6409 in terminal emulators.
6411 Note that the output produced with the `--color' option is _not_ a
6412 valid PO file in itself. It contains additional terminal-specific
6413 escape sequences or HTML tags. A PO file reader will give a syntax
6414 error when confronted with such content. Except for the `--color=html'
6415 case, you therefore normally don't need to save output produced with the
6416 `--color' option in a file.
6419 File: gettext.info, Node: The TERM variable, Next: The --style option, Prev: The --color option, Up: Colorizing
6421 9.11.2 The environment variable `TERM'
6422 --------------------------------------
6424 The environment variable `TERM' contains a identifier for the text
6425 window's capabilities. You can get a detailed list of these
6426 cababilities by using the `infocmp' command, using `man 5 terminfo' as a
6429 When producing text with embedded color directives, `msgcat' looks
6430 at the `TERM' variable. Text windows today typically support at least
6431 8 colors. Often, however, the text window supports 16 or more colors,
6432 even though the `TERM' variable is set to a identifier denoting only 8
6433 supported colors. It can be worth setting the `TERM' variable to a
6434 different value in these cases:
6437 `xterm' is in most cases built with support for 16 colors. It can
6438 also be built with support for 88 or 256 colors (but not both).
6439 You can try to set `TERM' to either `xterm-16color',
6440 `xterm-88color', or `xterm-256color'.
6443 `rxvt' is often built with support for 16 colors. You can try to
6444 set `TERM' to `rxvt-16color'.
6447 `konsole' too is often built with support for 16 colors. You can
6448 try to set `TERM' to `konsole-16color' or `xterm-16color'.
6450 After setting `TERM', you can verify it by invoking `msgcat
6451 --color=test' and seeing whether the output looks like a reasonable
6455 File: gettext.info, Node: The --style option, Next: Style rules, Prev: The TERM variable, Up: Colorizing
6457 9.11.3 The `--style' option
6458 ---------------------------
6460 The `--style=STYLE_FILE' option specifies the style file to use when
6461 colorizing. It has an effect only when the `--color' option is
6464 If the `--style' option is not specified, the environment variable
6465 `PO_STYLE' is considered. It is meant to point to the user's preferred
6468 The default style file is
6469 `$prefix/share/gettext/styles/po-default.css', where `$prefix' is the
6470 installation location.
6472 A few style files are predefined:
6474 This style imitates the look used by vim 7.
6477 This style imitates the look used by GNU Emacs 21 and 22 in an X11
6480 `po-emacs-xterm.css'
6481 `po-emacs-xterm16.css'
6482 `po-emacs-xterm256.css'
6483 This style imitates the look used by GNU Emacs 22 in a terminal of
6484 type `xterm' (8 colors) or `xterm-16color' (16 colors) or
6485 `xterm-256color' (256 colors), respectively.
6487 You can use these styles without specifying a directory. They are
6488 actually located in `$prefix/share/gettext/styles/', where `$prefix' is
6489 the installation location.
6491 You can also design your own styles. This is described in the next
6495 File: gettext.info, Node: Style rules, Next: Customizing less, Prev: The --style option, Up: Colorizing
6497 9.11.4 Style rules for PO files
6498 -------------------------------
6500 The same style file can be used for styling of a PO file, for
6501 terminal output and for HTML output. It is written in CSS (Cascading
6502 Style Sheet) syntax. See `http://www.w3.org/TR/css2/cover.html' for a
6503 formal definition of CSS. Many HTML authoring tutorials also contain
6504 explanations of CSS.
6506 In the case of HTML output, the style file is embedded in the HTML
6507 output. In the case of text output, the style file is interpreted by
6508 the `msgcat' program. This means, in particular, that when `@import'
6509 is used with relative file names, the file names are
6511 - relative to the resulting HTML file, in the case of HTML output,
6513 - relative to the style sheet containing the `@import', in the case
6514 of text output. (Actually, `@import's are not yet supported in
6515 this case, due to a limitation in `libcroco'.)
6517 CSS rules are built up from selectors and declarations. The
6518 declarations specify graphical properties; the selectors specify
6519 specify when they apply.
6521 In PO files, the following simple selectors (based on "CSS classes",
6522 see the CSS2 spec, section 5.8.3) are supported.
6524 * Selectors that apply to entire messages:
6527 This matches the header entry of a PO file.
6530 This matches a translated message.
6533 This matches an untranslated message (i.e. a message with
6537 This matches a fuzzy message (i.e. a message which has a
6538 translation that needs review by the translator).
6541 This matches an obsolete message (i.e. a message that was
6542 translated but is not needed by the current POT file any
6545 * Selectors that apply to parts of a message in PO syntax. Recall
6546 the general structure of a message in PO syntax:
6549 # TRANSLATOR-COMMENTS
6550 #. EXTRACTED-COMMENTS
6553 #| msgid PREVIOUS-UNTRANSLATED-STRING
6554 msgid UNTRANSLATED-STRING
6555 msgstr TRANSLATED-STRING
6558 This matches all comments (translator comments, extracted
6559 comments, source file reference comments, flag comments,
6560 previous message comments, as well as the entire obsolete
6563 `.translator-comment'
6564 This matches the translator comments.
6566 `.extracted-comment'
6567 This matches the extracted comments, i.e. the comments placed
6568 by the programmer at the attention of the translator.
6570 `.reference-comment'
6571 This matches the source file reference comments (entire
6575 This matches the individual source file references inside the
6576 source file reference comment lines.
6579 This matches the flag comment lines (entire lines).
6582 This matches the individual flags inside flag comment lines.
6585 This matches the `fuzzy' flag inside flag comment lines.
6588 This matches the comments containing the previous
6589 untranslated string (entire lines).
6592 This matches the previous untranslated string including the
6593 string delimiters, the associated keywords (`msgid' etc.) and
6594 the spaces between them.
6597 This matches the untranslated string including the string
6598 delimiters, the associated keywords (`msgid' etc.) and the
6599 spaces between them.
6602 This matches the translated string including the string
6603 delimiters, the associated keywords (`msgstr' etc.) and the
6604 spaces between them.
6607 This matches the keywords (`msgid', `msgstr', etc.).
6610 This matches strings, including the string delimiters (double
6613 * Selectors that apply to parts of strings:
6616 This matches the entire contents of a string (excluding the
6617 string delimiters, i.e. the double quotes).
6620 This matches an escape sequence (starting with a backslash).
6623 This matches a format string directive (starting with a `%'
6624 sign in the case of most programming languages, with a `{' in
6625 the case of `java-format' and `csharp-format', with a `~' in
6626 the case of `lisp-format' and `scheme-format', or with `$' in
6627 the case of `sh-format').
6629 `.invalid-format-directive'
6630 This matches an invalid format string directive.
6633 In an untranslated string, this matches a part of the string
6634 that was not present in the previous untranslated string.
6635 (Not yet implemented in this release.)
6638 In an untranslated string or in a previous untranslated
6639 string, this matches a part of the string that is changed or
6640 replaced. (Not yet implemented in this release.)
6643 In a previous untranslated string, this matches a part of the
6644 string that is not present in the current untranslated
6645 string. (Not yet implemented in this release.)
6647 These selectors can be combined to hierarchical selectors. For
6650 .msgstr .invalid-format-directive { color: red; }
6652 will highlight the invalid format directives in the translated strings.
6654 In text mode, pseudo-classes (CSS2 spec, section 5.11) and
6655 pseudo-elements (CSS2 spec, section 5.12) are not supported.
6657 The declarations in HTML mode are not limited; any graphical
6658 attribute supported by the browsers can be used.
6660 The declarations in text mode are limited to the following
6661 properties. Other properties will be silently ignored.
6663 `color' (CSS2 spec, section 14.1)
6664 `background-color' (CSS2 spec, section 14.2.1)
6665 These properties is supported. Colors will be adjusted to match
6666 the terminal's capabilities. Note that many terminals support
6669 `font-weight' (CSS2 spec, section 15.2.3)
6670 This property is supported, but most terminals can only render two
6671 different weights: `normal' and `bold'. Values >= 600 are
6674 `font-style' (CSS2 spec, section 15.2.3)
6675 This property is supported. The values `italic' and `oblique' are
6676 rendered the same way.
6678 `text-decoration' (CSS2 spec, section 16.3.1)
6679 This property is supported, limited to the values `none' and
6683 File: gettext.info, Node: Customizing less, Prev: Style rules, Up: Colorizing
6685 9.11.5 Customizing `less' for viewing PO files
6686 ----------------------------------------------
6688 The `less' program is a popular text file browser for use in a text
6689 screen or terminal emulator. It also supports text with embedded escape
6690 sequences for colors and text decorations.
6692 You can use `less' to view a PO file like this (assuming an UTF-8
6695 msgcat --to-code=UTF-8 --color xyz.po | less -R
6697 You can simplify this to this simple command:
6701 after these three preparations:
6703 1. Add the options `-R' and `-f' to the `LESS' environment variable.
6705 $ LESS="$LESS -R -f"
6708 2. If your system does not already have the `lessopen.sh' and
6709 `lessclose.sh' scripts, create them and set the `LESSOPEN' and
6710 `LESSCLOSE' environment variables, as indicated in the manual page
6713 3. Add to `lessopen.sh' a piece of script that recognizes PO files
6714 through their file extension and invokes `msgcat' on them,
6715 producing a temporary file. Like this:
6719 tmpfile=`mktemp "${TMPDIR-/tmp}/less.XXXXXX"`
6720 msgcat --to-code=UTF-8 --color "$1" > "$tmpfile"
6727 File: gettext.info, Node: libgettextpo, Prev: Colorizing, Up: Manipulating
6729 9.12 Writing your own programs that process PO files
6730 ====================================================
6732 For the tasks for which a combination of `msgattrib', `msgcat' etc.
6733 is not sufficient, a set of C functions is provided in a library, to
6734 make it possible to process PO files in your own programs. When you
6735 use this library, you don't need to write routines to parse the PO
6736 file; instead, you retrieve a pointer in memory to each of messages
6737 contained in the PO file. Functions for writing PO files are not
6738 provided at this time.
6740 The functions are declared in the header file `<gettext-po.h>', and
6741 are defined in a library called `libgettextpo'.
6743 -- Data Type: po_file_t
6744 This is a pointer type that refers to the contents of a PO file,
6745 after it has been read into memory.
6747 -- Data Type: po_message_iterator_t
6748 This is a pointer type that refers to an iterator that produces a
6749 sequence of messages.
6751 -- Data Type: po_message_t
6752 This is a pointer type that refers to a message of a PO file,
6753 including its translation.
6755 -- Function: po_file_t po_file_read (const char *FILENAME)
6756 The `po_file_read' function reads a PO file into memory. The file
6757 name is given as argument. The return value is a handle to the PO
6758 file's contents, valid until `po_file_free' is called on it. In
6759 case of error, the return value is `NULL', and `errno' is set.
6761 -- Function: void po_file_free (po_file_t FILE)
6762 The `po_file_free' function frees a PO file's contents from memory,
6763 including all messages that are only implicitly accessible through
6766 -- Function: const char * const * po_file_domains (po_file_t FILE)
6767 The `po_file_domains' function returns the domains for which the
6768 given PO file has messages. The return value is a `NULL'
6769 terminated array which is valid as long as the FILE handle is
6770 valid. For PO files which contain no `domain' directive, the
6771 return value contains only one domain, namely the default domain
6774 -- Function: po_message_iterator_t po_message_iterator (po_file_t
6775 FILE, const char *DOMAIN)
6776 The `po_message_iterator' returns an iterator that will produce the
6777 messages of FILE that belong to the given DOMAIN. If DOMAIN is
6778 `NULL', the default domain is used instead. To list the messages,
6779 use the function `po_next_message' repeatedly.
6781 -- Function: void po_message_iterator_free (po_message_iterator_t
6783 The `po_message_iterator_free' function frees an iterator
6784 previously allocated through the `po_message_iterator' function.
6786 -- Function: po_message_t po_next_message (po_message_iterator_t
6788 The `po_next_message' function returns the next message from
6789 ITERATOR and advances the iterator. It returns `NULL' when the
6790 iterator has reached the end of its message list.
6792 The following functions returns details of a `po_message_t'. Recall
6793 that the results are valid as long as the FILE handle is valid.
6795 -- Function: const char * po_message_msgid (po_message_t MESSAGE)
6796 The `po_message_msgid' function returns the `msgid' (untranslated
6797 English string) of a message. This is guaranteed to be non-`NULL'.
6799 -- Function: const char * po_message_msgid_plural (po_message_t
6801 The `po_message_msgid_plural' function returns the `msgid_plural'
6802 (untranslated English plural string) of a message with plurals, or
6803 `NULL' for a message without plural.
6805 -- Function: const char * po_message_msgstr (po_message_t MESSAGE)
6806 The `po_message_msgstr' function returns the `msgstr' (translation)
6807 of a message. For an untranslated message, the return value is an
6810 -- Function: const char * po_message_msgstr_plural (po_message_t
6812 The `po_message_msgstr_plural' function returns the
6813 `msgstr[INDEX]' of a message with plurals, or `NULL' when the
6814 INDEX is out of range or for a message without plural.
6816 Here is an example code how these functions can be used.
6818 const char *filename = ...;
6819 po_file_t file = po_file_read (filename);
6822 error (EXIT_FAILURE, errno, "couldn't open the PO file %s", filename);
6824 const char * const *domains = po_file_domains (file);
6825 const char * const *domainp;
6827 for (domainp = domains; *domainp; domainp++)
6829 const char *domain = *domainp;
6830 po_message_iterator_t iterator = po_message_iterator (file, domain);
6834 po_message_t *message = po_next_message (iterator);
6836 if (message == NULL)
6839 const char *msgid = po_message_msgid (message);
6840 const char *msgstr = po_message_msgstr (message);
6845 po_message_iterator_free (iterator);
6848 po_file_free (file);
6851 File: gettext.info, Node: Binaries, Next: Programmers, Prev: Manipulating, Up: Top
6853 10 Producing Binary MO Files
6854 ****************************
6858 * msgfmt Invocation:: Invoking the `msgfmt' Program
6859 * msgunfmt Invocation:: Invoking the `msgunfmt' Program
6860 * MO Files:: The Format of GNU MO Files
6863 File: gettext.info, Node: msgfmt Invocation, Next: msgunfmt Invocation, Prev: Binaries, Up: Binaries
6865 10.1 Invoking the `msgfmt' Program
6866 ==================================
6868 msgfmt [OPTION] FILENAME.po ...
6870 The `msgfmt' programs generates a binary message catalog from a
6871 textual translation description.
6873 10.1.1 Input file location
6874 --------------------------
6879 `--directory=DIRECTORY'
6880 Add DIRECTORY to the list of directories. Source files are
6881 searched relative to this list of directories. The resulting `.po'
6882 file will be written relative to the current directory, though.
6885 If an input file is `-', standard input is read.
6887 10.1.2 Operation mode
6888 ---------------------
6892 Java mode: generate a Java `ResourceBundle' class.
6895 Like -java, and assume Java2 (JDK 1.2 or higher).
6898 C# mode: generate a .NET .dll file containing a subclass of
6899 `GettextResourceSet'.
6901 `--csharp-resources'
6902 C# resources mode: generate a .NET `.resources' file.
6905 Tcl mode: generate a tcl/msgcat `.msg' file.
6908 Qt mode: generate a Qt `.qm' file.
6911 10.1.3 Output file location
6912 ---------------------------
6915 `--output-file=FILE'
6916 Write output to specified file.
6919 Direct the program to work strictly following the Uniforum/Sun
6920 implementation. Currently this only affects the naming of the
6921 output file. If this option is not given the name of the output
6922 file is the same as the domain name. If the strict Uniforum mode
6923 is enabled the suffix `.mo' is added to the file name if it is not
6926 We find this behaviour of Sun's implementation rather silly and so
6927 by default this mode is _not_ selected.
6930 If the output FILE is `-', output is written to standard output.
6932 10.1.4 Output file location in Java mode
6933 ----------------------------------------
6936 `--resource=RESOURCE'
6937 Specify the resource name.
6941 Specify the locale name, either a language specification of the
6942 form LL or a combined language and country specification of the
6946 Specify the base directory of classes directory hierarchy.
6949 The class name is determined by appending the locale name to the
6950 resource name, separated with an underscore. The `-d' option is
6951 mandatory. The class is written under the specified directory.
6953 10.1.5 Output file location in C# mode
6954 --------------------------------------
6957 `--resource=RESOURCE'
6958 Specify the resource name.
6962 Specify the locale name, either a language specification of the
6963 form LL or a combined language and country specification of the
6967 Specify the base directory for locale dependent `.dll' files.
6970 The `-l' and `-d' options are mandatory. The `.dll' file is written
6971 in a subdirectory of the specified directory whose name depends on the
6974 10.1.6 Output file location in Tcl mode
6975 ---------------------------------------
6979 Specify the locale name, either a language specification of the
6980 form LL or a combined language and country specification of the
6984 Specify the base directory of `.msg' message catalogs.
6987 The `-l' and `-d' options are mandatory. The `.msg' file is written
6988 in the specified directory.
6990 10.1.7 Input file syntax
6991 ------------------------
6994 `--properties-input'
6995 Assume the input files are Java ResourceBundles in Java
6996 `.properties' syntax, not in PO file syntax.
6998 `--stringtable-input'
6999 Assume the input files are NeXTstep/GNUstep localized resource
7000 files in `.strings' syntax, not in PO file syntax.
7003 10.1.8 Input file interpretation
7004 --------------------------------
7008 Perform all the checks implied by `--check-format',
7009 `--check-header', `--check-domain'.
7012 Check language dependent format strings.
7014 If the string represents a format string used in a `printf'-like
7015 function both strings should have the same number of `%' format
7016 specifiers, with matching types. If the flag `c-format' or
7017 `possible-c-format' appears in the special comment <#,> for this
7018 entry a check is performed. For example, the check will diagnose
7019 using `%.*s' against `%s', or `%d' against `%s', or `%d' against
7020 `%x'. It can even handle positional parameters.
7022 Normally the `xgettext' program automatically decides whether a
7023 string is a format string or not. This algorithm is not perfect,
7024 though. It might regard a string as a format string though it is
7025 not used in a `printf'-like function and so `msgfmt' might report
7026 errors where there are none.
7028 To solve this problem the programmer can dictate the decision to
7029 the `xgettext' program (*note c-format::). The translator should
7030 not consider removing the flag from the <#,> line. This "fix"
7031 would be reversed again as soon as `msgmerge' is called the next
7035 Verify presence and contents of the header entry. *Note Header
7036 Entry::, for a description of the various fields in the header
7040 Check for conflicts between domain directives and the
7041 `--output-file' option
7044 `--check-compatibility'
7045 Check that GNU msgfmt behaves like X/Open msgfmt. This will give
7046 an error when attempting to use the GNU extensions.
7048 `--check-accelerators[=CHAR]'
7049 Check presence of keyboard accelerators for menu items. This is
7050 based on the convention used in some GUIs that a keyboard
7051 accelerator in a menu item string is designated by an immediately
7052 preceding `&' character. Sometimes a keyboard accelerator is also
7053 called "keyboard mnemonic". This check verifies that if the
7054 untranslated string has exactly one `&' character, the translated
7055 string has exactly one `&' as well. If this option is given with
7056 a CHAR argument, this CHAR should be a non-alphanumeric character
7057 and is used as keyboard accelerator mark instead of `&'.
7061 Use fuzzy entries in output. Note that using this option is
7062 usually wrong, because fuzzy messages are exactly those which have
7063 not been validated by a human translator.
7066 10.1.9 Output details
7067 ---------------------
7070 `--alignment=NUMBER'
7071 Align strings to NUMBER bytes (default: 1).
7074 Don't include a hash table in the binary file. Lookup will be
7075 more expensive at run time (binary search instead of hash table
7079 10.1.10 Informative output
7080 --------------------------
7084 Display this help and exit.
7088 Output version information and exit.
7091 Print statistics about translations. When the option `--verbose'
7092 is used in combination with `--statistics', the input file name is
7093 printed in front of the statistics line.
7097 Increase verbosity level.
7101 File: gettext.info, Node: msgunfmt Invocation, Next: MO Files, Prev: msgfmt Invocation, Up: Binaries
7103 10.2 Invoking the `msgunfmt' Program
7104 ====================================
7106 msgunfmt [OPTION] [FILE]...
7108 The `msgunfmt' program converts a binary message catalog to a
7109 Uniforum style .po file.
7111 10.2.1 Operation mode
7112 ---------------------
7116 Java mode: input is a Java `ResourceBundle' class.
7119 C# mode: input is a .NET .dll file containing a subclass of
7120 `GettextResourceSet'.
7122 `--csharp-resources'
7123 C# resources mode: input is a .NET `.resources' file.
7126 Tcl mode: input is a tcl/msgcat `.msg' file.
7129 10.2.2 Input file location
7130 --------------------------
7136 If no input FILE is given or if it is `-', standard input is read.
7138 10.2.3 Input file location in Java mode
7139 ---------------------------------------
7142 `--resource=RESOURCE'
7143 Specify the resource name.
7147 Specify the locale name, either a language specification of the
7148 form LL or a combined language and country specification of the
7152 The class name is determined by appending the locale name to the
7153 resource name, separated with an underscore. The class is located
7154 using the `CLASSPATH'.
7156 10.2.4 Input file location in C# mode
7157 -------------------------------------
7160 `--resource=RESOURCE'
7161 Specify the resource name.
7165 Specify the locale name, either a language specification of the
7166 form LL or a combined language and country specification of the
7170 Specify the base directory for locale dependent `.dll' files.
7173 The `-l' and `-d' options are mandatory. The `.msg' file is located
7174 in a subdirectory of the specified directory whose name depends on the
7177 10.2.5 Input file location in Tcl mode
7178 --------------------------------------
7182 Specify the locale name, either a language specification of the
7183 form LL or a combined language and country specification of the
7187 Specify the base directory of `.msg' message catalogs.
7190 The `-l' and `-d' options are mandatory. The `.msg' file is located
7191 in the specified directory.
7193 10.2.6 Output file location
7194 ---------------------------
7197 `--output-file=FILE'
7198 Write output to specified file.
7201 The results are written to standard output if no output file is
7202 specified or if it is `-'.
7204 10.2.7 Output details
7205 ---------------------
7209 Specify whether or when to use colors and other text attributes.
7210 See *note The --color option:: for details.
7212 `--style=STYLE_FILE'
7213 Specify the CSS style rule file to use for `--color'. See *note
7214 The --style option:: for details.
7217 Always write an output file even if it contains no message.
7221 Write the .po file using indented style.
7224 Write out a strict Uniforum conforming PO file. Note that this
7225 Uniforum format should be avoided because it doesn't support the
7229 `--properties-output'
7230 Write out a Java ResourceBundle in Java `.properties' syntax. Note
7231 that this file format doesn't support plural forms and silently
7232 drops obsolete messages.
7234 `--stringtable-output'
7235 Write out a NeXTstep/GNUstep localized resource file in `.strings'
7236 syntax. Note that this file format doesn't support plural forms.
7240 Set the output page width. Long strings in the output files will
7241 be split across multiple lines in order to ensure that each line's
7242 width (= number of screen columns) is less or equal to the given
7246 Do not break long message lines. Message lines whose width
7247 exceeds the output page width will not be split into several
7248 lines. Only file reference lines which are wider than the output
7249 page width will be split.
7253 Generate sorted output. Note that using this option makes it much
7254 harder for the translator to understand each message's context.
7257 10.2.8 Informative output
7258 -------------------------
7262 Display this help and exit.
7266 Output version information and exit.
7270 Increase verbosity level.
7274 File: gettext.info, Node: MO Files, Prev: msgunfmt Invocation, Up: Binaries
7276 10.3 The Format of GNU MO Files
7277 ===============================
7279 The format of the generated MO files is best described by a picture,
7280 which appears below.
7282 The first two words serve the identification of the file. The magic
7283 number will always signal GNU MO files. The number is stored in the
7284 byte order of the generating machine, so the magic number really is two
7285 numbers: `0x950412de' and `0xde120495'.
7287 The second word describes the current revision of the file format,
7288 composed of a major and a minor revision number. The revision numbers
7289 ensure that the readers of MO files can distinguish new formats from
7290 old ones and handle their contents, as far as possible. For now the
7291 major revision is 0 or 1, and the minor revision is also 0 or 1. More
7292 revisions might be added in the future. A program seeing an unexpected
7293 major revision number should stop reading the MO file entirely; whereas
7294 an unexpected minor revision number means that the file can be read but
7295 will not reveal its full contents, when parsed by a program that
7296 supports only smaller minor revision numbers.
7298 The version is kept separate from the magic number, instead of using
7299 different magic numbers for different formats, mainly because
7300 `/etc/magic' is not updated often.
7302 Follow a number of pointers to later tables in the file, allowing
7303 for the extension of the prefix part of MO files without having to
7304 recompile programs reading them. This might become useful for later
7305 inserting a few flag bits, indication about the charset used, new
7306 tables, or other things.
7308 Then, at offset O and offset T in the picture, two tables of string
7309 descriptors can be found. In both tables, each string descriptor uses
7310 two 32 bits integers, one for the string length, another for the offset
7311 of the string in the MO file, counting in bytes from the start of the
7312 file. The first table contains descriptors for the original strings,
7313 and is sorted so the original strings are in increasing lexicographical
7314 order. The second table contains descriptors for the translated
7315 strings, and is parallel to the first table: to find the corresponding
7316 translation one has to access the array slot in the second array with
7319 Having the original strings sorted enables the use of simple binary
7320 search, for when the MO file does not contain an hashing table, or for
7321 when it is not practical to use the hashing table provided in the MO
7322 file. This also has another advantage, as the empty string in a PO
7323 file GNU `gettext' is usually _translated_ into some system information
7324 attached to that particular MO file, and the empty string necessarily
7325 becomes the first in both the original and translated tables, making
7326 the system information very easy to find.
7328 The size S of the hash table can be zero. In this case, the hash
7329 table itself is not contained in the MO file. Some people might prefer
7330 this because a precomputed hashing table takes disk space, and does not
7331 win _that_ much speed. The hash table contains indices to the sorted
7332 array of strings in the MO file. Conflict resolution is done by double
7333 hashing. The precise hashing algorithm used is fairly dependent on GNU
7334 `gettext' code, and is not documented here.
7336 As for the strings themselves, they follow the hash file, and each
7337 is terminated with a <NUL>, and this <NUL> is not counted in the length
7338 which appears in the string descriptor. The `msgfmt' program has an
7339 option selecting the alignment for MO file strings. With this option,
7340 each string is separately aligned so it starts at an offset which is a
7341 multiple of the alignment value. On some RISC machines, a correct
7342 alignment will speed things up.
7344 Contexts are stored by storing the concatenation of the context, a
7345 <EOT> byte, and the original string, instead of the original string.
7347 Plural forms are stored by letting the plural of the original string
7348 follow the singular of the original string, separated through a <NUL>
7349 byte. The length which appears in the string descriptor includes both.
7350 However, only the singular of the original string takes part in the
7351 hash table lookup. The plural variants of the translation are all
7352 stored consecutively, separated through a <NUL> byte. Here also, the
7353 length in the string descriptor includes all of them.
7355 Nothing prevents a MO file from having embedded <NUL>s in strings.
7356 However, the program interface currently used already presumes that
7357 strings are <NUL> terminated, so embedded <NUL>s are somewhat useless.
7358 But the MO file format is general enough so other interfaces would be
7359 later possible, if for example, we ever want to implement wide
7360 characters right in MO files, where <NUL> bytes may accidentally
7361 appear. (No, we don't want to have wide characters in MO files. They
7362 would make the file unnecessarily large, and the `wchar_t' type being
7363 platform dependent, MO files would be platform dependent as well.)
7365 This particular issue has been strongly debated in the GNU `gettext'
7366 development forum, and it is expectable that MO file format will evolve
7367 or change over time. It is even possible that many formats may later
7368 be supported concurrently. But surely, we have to start somewhere, and
7369 the MO file format described here is a good start. Nothing is cast in
7370 concrete, and the format may later evolve fairly easily, so we should
7371 feel comfortable with the current approach.
7374 +------------------------------------------+
7375 0 | magic number = 0x950412de |
7377 4 | file format revision = 0 |
7379 8 | number of strings | == N
7381 12 | offset of table with original strings | == O
7383 16 | offset of table with translation strings | == T
7385 20 | size of hashing table | == S
7387 24 | offset of hashing table | == H
7390 . (possibly more entries later) .
7393 O | length & offset 0th string ----------------.
7394 O + 8 | length & offset 1st string ------------------.
7396 O + ((N-1)*8)| length & offset (N-1)th string | | |
7398 T | length & offset 0th translation ---------------.
7399 T + 8 | length & offset 1st translation -----------------.
7401 T + ((N-1)*8)| length & offset (N-1)th translation | | | | |
7403 H | start hash table | | | | |
7405 H + S * 4 | end hash table | | | | |
7407 | NUL terminated 0th string <----------------' | | |
7409 | NUL terminated 1st string <------------------' | |
7413 | NUL terminated 0th translation <---------------' |
7415 | NUL terminated 1st translation <-----------------'
7419 +------------------------------------------+
7422 File: gettext.info, Node: Programmers, Next: Translators, Prev: Binaries, Up: Top
7424 11 The Programmer's View
7425 ************************
7427 One aim of the current message catalog implementation provided by
7428 GNU `gettext' was to use the system's message catalog handling, if the
7429 installer wishes to do so. So we perhaps should first take a look at
7430 the solutions we know about. The people in the POSIX committee did not
7431 manage to agree on one of the semi-official standards which we'll
7432 describe below. In fact they couldn't agree on anything, so they
7433 decided only to include an example of an interface. The major Unix
7434 vendors are split in the usage of the two most important
7435 specifications: X/Open's catgets vs. Uniforum's gettext interface.
7436 We'll describe them both and later explain our solution of this dilemma.
7440 * catgets:: About `catgets'
7441 * gettext:: About `gettext'
7442 * Comparison:: Comparing the two interfaces
7443 * Using libintl.a:: Using libintl.a in own programs
7444 * gettext grok:: Being a `gettext' grok
7445 * Temp Programmers:: Temporary Notes for the Programmers Chapter
7448 File: gettext.info, Node: catgets, Next: gettext, Prev: Programmers, Up: Programmers
7450 11.1 About `catgets'
7451 ====================
7453 The `catgets' implementation is defined in the X/Open Portability
7454 Guide, Volume 3, XSI Supplementary Definitions, Chapter 5. But the
7455 process of creating this standard seemed to be too slow for some of the
7456 Unix vendors so they created their implementations on preliminary
7457 versions of the standard. Of course this leads again to problems while
7458 writing platform independent programs: even the usage of `catgets' does
7459 not guarantee a unique interface.
7461 Another, personal comment on this that only a bunch of committee
7462 members could have made this interface. They never really tried to
7463 program using this interface. It is a fast, memory-saving
7464 implementation, an user can happily live with it. But programmers hate
7465 it (at least I and some others do...)
7467 But we must not forget one point: after all the trouble with
7468 transferring the rights on Unix(tm) they at last came to X/Open, the
7469 very same who published this specification. This leads me to making
7470 the prediction that this interface will be in future Unix standards
7471 (e.g. Spec1170) and therefore part of all Unix implementation
7472 (implementations, which are _allowed_ to wear this name).
7476 * Interface to catgets:: The interface
7477 * Problems with catgets:: Problems with the `catgets' interface?!
7480 File: gettext.info, Node: Interface to catgets, Next: Problems with catgets, Prev: catgets, Up: catgets
7482 11.1.1 The Interface
7483 --------------------
7485 The interface to the `catgets' implementation consists of three
7486 functions which correspond to those used in file access: `catopen' to
7487 open the catalog for using, `catgets' for accessing the message tables,
7488 and `catclose' for closing after work is done. Prototypes for the
7489 functions and the needed definitions are in the `<nl_types.h>' header
7492 `catopen' is used like in this:
7494 nl_catd catd = catopen ("catalog_name", 0);
7496 The function takes as the argument the name of the catalog. This
7497 usual refers to the name of the program or the package. The second
7498 parameter is not further specified in the standard. I don't even know
7499 whether it is implemented consistently among various systems. So the
7500 common advice is to use `0' as the value. The return value is a handle
7501 to the message catalog, equivalent to handles to file returned by
7504 This handle is of course used in the `catgets' function which can be
7507 char *translation = catgets (catd, set_no, msg_id, "original string");
7509 The first parameter is this catalog descriptor. The second parameter
7510 specifies the set of messages in this catalog, in which the message
7511 described by `msg_id' is obtained. `catgets' therefore uses a
7512 three-stage addressing:
7514 catalog name => set number => message ID => translation
7516 The fourth argument is not used to address the translation. It is
7517 given as a default value in case when one of the addressing stages
7518 fail. One important thing to remember is that although the return type
7519 of catgets is `char *' the resulting string _must not_ be changed. It
7520 should better be `const char *', but the standard is published in 1988,
7521 one year before ANSI C.
7523 The last of these functions is used and behaves as expected:
7527 After this no `catgets' call using the descriptor is legal anymore.
7530 File: gettext.info, Node: Problems with catgets, Prev: Interface to catgets, Up: catgets
7532 11.1.2 Problems with the `catgets' Interface?!
7533 ----------------------------------------------
7535 Now that this description seemed to be really easy -- where are the
7536 problems we speak of? In fact the interface could be used in a
7537 reasonable way, but constructing the message catalogs is a pain. The
7538 reason for this lies in the third argument of `catgets': the unique
7539 message ID. This has to be a numeric value for all messages in a single
7540 set. Perhaps you could imagine the problems keeping such a list while
7541 changing the source code. Add a new message here, remove one there. Of
7542 course there have been developed a lot of tools helping to organize this
7543 chaos but one as the other fails in one aspect or the other. We don't
7544 want to say that the other approach has no problems but they are far
7545 more easy to manage.
7548 File: gettext.info, Node: gettext, Next: Comparison, Prev: catgets, Up: Programmers
7550 11.2 About `gettext'
7551 ====================
7553 The definition of the `gettext' interface comes from a Uniforum
7554 proposal. It was submitted there by Sun, who had implemented the
7555 `gettext' function in SunOS 4, around 1990. Nowadays, the `gettext'
7556 interface is specified by the OpenI18N standard.
7558 The main point about this solution is that it does not follow the
7559 method of normal file handling (open-use-close) and that it does not
7560 burden the programmer with so many tasks, especially the unique key
7561 handling. Of course here also a unique key is needed, but this key is
7562 the message itself (how long or short it is). See *note Comparison::
7563 for a more detailed comparison of the two methods.
7565 The following section contains a rather detailed description of the
7566 interface. We make it that detailed because this is the interface we
7567 chose for the GNU `gettext' Library. Programmers interested in using
7568 this library will be interested in this description.
7572 * Interface to gettext:: The interface
7573 * Ambiguities:: Solving ambiguities
7574 * Locating Catalogs:: Locating message catalog files
7575 * Charset conversion:: How to request conversion to Unicode
7576 * Contexts:: Solving ambiguities in GUI programs
7577 * Plural forms:: Additional functions for handling plurals
7578 * Optimized gettext:: Optimization of the *gettext functions
7581 File: gettext.info, Node: Interface to gettext, Next: Ambiguities, Prev: gettext, Up: gettext
7583 11.2.1 The Interface
7584 --------------------
7586 The minimal functionality an interface must have is a) to select a
7587 domain the strings are coming from (a single domain for all programs is
7588 not reasonable because its construction and maintenance is difficult,
7589 perhaps impossible) and b) to access a string in a selected domain.
7591 This is principally the description of the `gettext' interface. It
7592 has a global domain which unqualified usages reference. Of course this
7593 domain is selectable by the user.
7595 char *textdomain (const char *domain_name);
7597 This provides the possibility to change or query the current status
7598 of the current global domain of the `LC_MESSAGE' category. The
7599 argument is a null-terminated string, whose characters must be legal in
7600 the use in filenames. If the DOMAIN_NAME argument is `NULL', the
7601 function returns the current value. If no value has been set before,
7602 the name of the default domain is returned: _messages_. Please note
7603 that although the return value of `textdomain' is of type `char *' no
7604 changing is allowed. It is also important to know that no checks of
7605 the availability are made. If the name is not available you will see
7606 this by the fact that no translations are provided.
7608 To use a domain set by `textdomain' the function
7610 char *gettext (const char *msgid);
7612 is to be used. This is the simplest reasonable form one can imagine.
7613 The translation of the string MSGID is returned if it is available in
7614 the current domain. If it is not available, the argument itself is
7615 returned. If the argument is `NULL' the result is undefined.
7617 One thing which should come into mind is that no explicit dependency
7618 to the used domain is given. The current value of the domain is used.
7619 If this changes between two executions of the same `gettext' call in
7620 the program, both calls reference a different message catalog.
7622 For the easiest case, which is normally used in internationalized
7623 packages, once at the beginning of execution a call to `textdomain' is
7624 issued, setting the domain to a unique name, normally the package name.
7625 In the following code all strings which have to be translated are
7626 filtered through the gettext function. That's all, the package speaks
7630 File: gettext.info, Node: Ambiguities, Next: Locating Catalogs, Prev: Interface to gettext, Up: gettext
7632 11.2.2 Solving Ambiguities
7633 --------------------------
7635 While this single name domain works well for most applications there
7636 might be the need to get translations from more than one domain. Of
7637 course one could switch between different domains with calls to
7638 `textdomain', but this is really not convenient nor is it fast. A
7639 possible situation could be one case subject to discussion during this
7640 writing: all error messages of functions in the set of common used
7641 functions should go into a separate domain `error'. By this mean we
7642 would only need to translate them once. Another case are messages from
7643 a library, as these _have_ to be independent of the current domain set
7646 For this reasons there are two more functions to retrieve strings:
7648 char *dgettext (const char *domain_name, const char *msgid);
7649 char *dcgettext (const char *domain_name, const char *msgid,
7652 Both take an additional argument at the first place, which
7653 corresponds to the argument of `textdomain'. The third argument of
7654 `dcgettext' allows to use another locale category but `LC_MESSAGES'.
7655 But I really don't know where this can be useful. If the DOMAIN_NAME
7656 is `NULL' or CATEGORY has an value beside the known ones, the result is
7657 undefined. It should also be noted that this function is not part of
7658 the second known implementation of this function family, the one found
7661 A second ambiguity can arise by the fact, that perhaps more than one
7662 domain has the same name. This can be solved by specifying where the
7663 needed message catalog files can be found.
7665 char *bindtextdomain (const char *domain_name,
7666 const char *dir_name);
7668 Calling this function binds the given domain to a file in the
7669 specified directory (how this file is determined follows below).
7670 Especially a file in the systems default place is not favored against
7671 the specified file anymore (as it would be by solely using
7672 `textdomain'). A `NULL' pointer for the DIR_NAME parameter returns the
7673 binding associated with DOMAIN_NAME. If DOMAIN_NAME itself is `NULL'
7674 nothing happens and a `NULL' pointer is returned. Here again as for
7675 all the other functions is true that none of the return value must be
7678 It is important to remember that relative path names for the
7679 DIR_NAME parameter can be trouble. Since the path is always computed
7680 relative to the current directory different results will be achieved
7681 when the program executes a `chdir' command. Relative paths should
7682 always be avoided to avoid dependencies and unreliabilities.
7685 File: gettext.info, Node: Locating Catalogs, Next: Charset conversion, Prev: Ambiguities, Up: gettext
7687 11.2.3 Locating Message Catalog Files
7688 -------------------------------------
7690 Because many different languages for many different packages have to
7691 be stored we need some way to add these information to file message
7692 catalog files. The way usually used in Unix environments is have this
7693 encoding in the file name. This is also done here. The directory name
7694 given in `bindtextdomain's second argument (or the default directory),
7695 followed by the name of the locale, the locale category, and the domain
7696 name are concatenated:
7698 DIR_NAME/LOCALE/LC_CATEGORY/DOMAIN_NAME.mo
7700 The default value for DIR_NAME is system specific. For the GNU
7701 library, and for packages adhering to its conventions, it's:
7702 /usr/local/share/locale
7704 LOCALE is the name of the locale category which is designated by
7705 `LC_CATEGORY'. For `gettext' and `dgettext' this `LC_CATEGORY' is
7706 always `LC_MESSAGES'.(1) The name of the locale category is determined
7707 through `setlocale (LC_CATEGORY, NULL)'. (2) When using the function
7708 `dcgettext', you can specify the locale category through the third
7711 ---------- Footnotes ----------
7713 (1) Some system, e.g. mingw, don't have `LC_MESSAGES'. Here we use
7714 a more or less arbitrary value for it, namely 1729, the smallest
7715 positive integer which can be represented in two different ways as the
7718 (2) When the system does not support `setlocale' its behavior in
7719 setting the locale values is simulated by looking at the environment
7723 File: gettext.info, Node: Charset conversion, Next: Contexts, Prev: Locating Catalogs, Up: gettext
7725 11.2.4 How to specify the output character set `gettext' uses
7726 -------------------------------------------------------------
7728 `gettext' not only looks up a translation in a message catalog. It
7729 also converts the translation on the fly to the desired output character
7730 set. This is useful if the user is working in a different character set
7731 than the translator who created the message catalog, because it avoids
7732 distributing variants of message catalogs which differ only in the
7735 The output character set is, by default, the value of `nl_langinfo
7736 (CODESET)', which depends on the `LC_CTYPE' part of the current locale.
7737 But programs which store strings in a locale independent way (e.g.
7738 UTF-8) can request that `gettext' and related functions return the
7739 translations in that encoding, by use of the `bind_textdomain_codeset'
7742 Note that the MSGID argument to `gettext' is not subject to
7743 character set conversion. Also, when `gettext' does not find a
7744 translation for MSGID, it returns MSGID unchanged - independently of
7745 the current output character set. It is therefore recommended that all
7746 MSGIDs be US-ASCII strings.
7748 -- Function: char * bind_textdomain_codeset (const char *DOMAINNAME,
7749 const char *CODESET)
7750 The `bind_textdomain_codeset' function can be used to specify the
7751 output character set for message catalogs for domain DOMAINNAME.
7752 The CODESET argument must be a valid codeset name which can be used
7753 for the `iconv_open' function, or a null pointer.
7755 If the CODESET parameter is the null pointer,
7756 `bind_textdomain_codeset' returns the currently selected codeset
7757 for the domain with the name DOMAINNAME. It returns `NULL' if no
7758 codeset has yet been selected.
7760 The `bind_textdomain_codeset' function can be used several times.
7761 If used multiple times with the same DOMAINNAME argument, the
7762 later call overrides the settings made by the earlier one.
7764 The `bind_textdomain_codeset' function returns a pointer to a
7765 string containing the name of the selected codeset. The string is
7766 allocated internally in the function and must not be changed by the
7767 user. If the system went out of core during the execution of
7768 `bind_textdomain_codeset', the return value is `NULL' and the
7769 global variable ERRNO is set accordingly.
7772 File: gettext.info, Node: Contexts, Next: Plural forms, Prev: Charset conversion, Up: gettext
7774 11.2.5 Using contexts for solving ambiguities
7775 ---------------------------------------------
7777 One place where the `gettext' functions, if used normally, have big
7778 problems is within programs with graphical user interfaces (GUIs). The
7779 problem is that many of the strings which have to be translated are very
7780 short. They have to appear in pull-down menus which restricts the
7781 length. But strings which are not containing entire sentences or at
7782 least large fragments of a sentence may appear in more than one
7783 situation in the program but might have different translations. This is
7784 especially true for the one-word strings which are frequently used in
7787 As a consequence many people say that the `gettext' approach is
7788 wrong and instead `catgets' should be used which indeed does not have
7789 this problem. But there is a very simple and powerful method to handle
7790 this kind of problems with the `gettext' functions.
7792 Contexts can be added to strings to be translated. A context
7793 dependent translation lookup is when a translation for a given string
7794 is searched, that is limited to a given context. The translation for
7795 the same string in a different context can be different. The different
7796 translations of the same string in different contexts can be stored in
7797 the in the same MO file, and can be edited by the translator in the
7800 The `gettext.h' include file contains the lookup macros for strings
7801 with contexts. They are implemented as thin macros and inline functions
7802 over the functions from `<libintl.h>'.
7804 const char *pgettext (const char *msgctxt, const char *msgid);
7806 In a call of this macro, MSGCTXT and MSGID must be string literals.
7807 The macro returns the translation of MSGID, restricted to the context
7810 The MSGCTXT string is visible in the PO file to the translator. You
7811 should try to make it somehow canonical and never changing. Because
7812 every time you change an MSGCTXT, the translator will have to review
7813 the translation of MSGID.
7815 Finding a canonical MSGCTXT string that doesn't change over time can
7816 be hard. But you shouldn't use the file name or class name containing
7817 the `pgettext' call - because it is a common development task to rename
7818 a file or a class, and it shouldn't cause translator work. Also you
7819 shouldn't use a comment in the form of a complete English sentence as
7820 MSGCTXT - because orthography or grammar changes are often applied to
7821 such sentences, and again, it shouldn't force the translator to do a
7824 The `p' in `pgettext' stands for "particular": `pgettext' fetches a
7825 particular translation of the MSGID.
7827 const char *dpgettext (const char *domain_name,
7828 const char *msgctxt, const char *msgid);
7829 const char *dcpgettext (const char *domain_name,
7830 const char *msgctxt, const char *msgid,
7833 These are generalizations of `pgettext'. They behave similarly to
7834 `dgettext' and `dcgettext', respectively. The DOMAIN_NAME argument
7835 defines the translation domain. The CATEGORY argument allows to use
7836 another locale category than `LC_MESSAGES'.
7838 As as example consider the following fictional situation. A GUI
7839 program has a menu bar with the following entries:
7841 +------------+------------+--------------------------------------+
7842 | File | Printer | |
7843 +------------+------------+--------------------------------------+
7846 +----------+ | Connect |
7849 To have the strings `File', `Printer', `Open', `New', `Select', and
7850 `Connect' translated there has to be at some point in the code a call
7851 to a function of the `gettext' family. But in two places the string
7852 passed into the function would be `Open'. The translations might not
7853 be the same and therefore we are in the dilemma described above.
7855 What distinguishes the two places is the menu path from the menu
7856 root to the particular menu entries:
7864 Menu|Printer|Connect
7866 The context is thus the menu path without its last part. So, the
7867 calls look like this:
7869 pgettext ("Menu|", "File")
7870 pgettext ("Menu|", "Printer")
7871 pgettext ("Menu|File|", "Open")
7872 pgettext ("Menu|File|", "New")
7873 pgettext ("Menu|Printer|", "Select")
7874 pgettext ("Menu|Printer|", "Open")
7875 pgettext ("Menu|Printer|", "Connect")
7877 Whether or not to use the `|' character at the end of the context is
7880 For more complex cases, where the MSGCTXT or MSGID are not string
7881 literals, more general macros are available:
7883 const char *pgettext_expr (const char *msgctxt, const char *msgid);
7884 const char *dpgettext_expr (const char *domain_name,
7885 const char *msgctxt, const char *msgid);
7886 const char *dcpgettext_expr (const char *domain_name,
7887 const char *msgctxt, const char *msgid,
7890 Here MSGCTXT and MSGID can be arbitrary string-valued expressions.
7891 These macros are more general. But in the case that both argument
7892 expressions are string literals, the macros without the `_expr' suffix
7896 File: gettext.info, Node: Plural forms, Next: Optimized gettext, Prev: Contexts, Up: gettext
7898 11.2.6 Additional functions for plural forms
7899 --------------------------------------------
7901 The functions of the `gettext' family described so far (and all the
7902 `catgets' functions as well) have one problem in the real world which
7903 have been neglected completely in all existing approaches. What is
7904 meant here is the handling of plural forms.
7906 Looking through Unix source code before the time anybody thought
7907 about internationalization (and, sadly, even afterwards) one can often
7908 find code similar to the following:
7910 printf ("%d file%s deleted", n, n == 1 ? "" : "s");
7912 After the first complaints from people internationalizing the code
7913 people either completely avoided formulations like this or used strings
7914 like `"file(s)"'. Both look unnatural and should be avoided. First
7915 tries to solve the problem correctly looked like this:
7918 printf ("%d file deleted", n);
7920 printf ("%d files deleted", n);
7922 But this does not solve the problem. It helps languages where the
7923 plural form of a noun is not simply constructed by adding an `s' but
7924 that is all. Once again people fell into the trap of believing the
7925 rules their language is using are universal. But the handling of plural
7926 forms differs widely between the language families. For example, Rafal
7927 Maszkowski `<rzm@mat.uni.torun.pl>' reports:
7929 In Polish we use e.g. plik (file) this way:
7935 and so on (o' means 8859-2 oacute which should be rather okreska,
7936 similar to aogonek).
7938 There are two things which can differ between languages (and even
7939 inside language families);
7941 * The form how plural forms are built differs. This is a problem
7942 with languages which have many irregularities. German, for
7943 instance, is a drastic case. Though English and German are part
7944 of the same language family (Germanic), the almost regular forming
7945 of plural noun forms (appending an `s') is hardly found in German.
7947 * The number of plural forms differ. This is somewhat surprising for
7948 those who only have experiences with Romanic and Germanic languages
7949 since here the number is the same (there are two).
7951 But other language families have only one form or many forms. More
7952 information on this in an extra section.
7954 The consequence of this is that application writers should not try to
7955 solve the problem in their code. This would be localization since it is
7956 only usable for certain, hardcoded language environments. Instead the
7957 extended `gettext' interface should be used.
7959 These extra functions are taking instead of the one key string two
7960 strings and a numerical argument. The idea behind this is that using
7961 the numerical argument and the first string as a key, the implementation
7962 can select using rules specified by the translator the right plural
7963 form. The two string arguments then will be used to provide a return
7964 value in case no message catalog is found (similar to the normal
7965 `gettext' behavior). In this case the rules for Germanic language is
7966 used and it is assumed that the first string argument is the singular
7967 form, the second the plural form.
7969 This has the consequence that programs without language catalogs can
7970 display the correct strings only if the program itself is written using
7971 a Germanic language. This is a limitation but since the GNU C library
7972 (as well as the GNU `gettext' package) are written as part of the GNU
7973 package and the coding standards for the GNU project require program
7974 being written in English, this solution nevertheless fulfills its
7977 -- Function: char * ngettext (const char *MSGID1, const char *MSGID2,
7978 unsigned long int N)
7979 The `ngettext' function is similar to the `gettext' function as it
7980 finds the message catalogs in the same way. But it takes two
7981 extra arguments. The MSGID1 parameter must contain the singular
7982 form of the string to be converted. It is also used as the key
7983 for the search in the catalog. The MSGID2 parameter is the plural
7984 form. The parameter N is used to determine the plural form. If no
7985 message catalog is found MSGID1 is returned if `n == 1', otherwise
7988 An example for the use of this function is:
7990 printf (ngettext ("%d file removed", "%d files removed", n), n);
7992 Please note that the numeric value N has to be passed to the
7993 `printf' function as well. It is not sufficient to pass it only to
7996 In the English singular case, the number - always 1 - can be
7997 replaced with "one":
7999 printf (ngettext ("One file removed", "%d files removed", n), n);
8001 This works because the `printf' function discards excess arguments
8002 that are not consumed by the format string.
8004 If this function is meant to yield a format string that takes two
8005 or more arguments, you can not use it like this:
8007 printf (ngettext ("%d file removed from directory %s",
8008 "%d files removed from directory %s",
8012 because in many languages the translators want to replace the `%d'
8013 with an explicit word in the singular case, just like "one" in
8014 English, and C format strings cannot consume the second argument
8015 but skip the first argument. Instead, you have to reorder the
8016 arguments so that `n' comes last:
8018 printf (ngettext ("%$2d file removed from directory %$1s",
8019 "%$2d files removed from directory %$1s",
8023 See *note c-format:: for details about this argument reordering
8026 When you know that the value of `n' is within a given range, you
8027 can specify it as a comment directed to the `xgettext' tool. This
8028 information may help translators to use more adequate
8029 translations. Like this:
8031 if (days > 7 && days < 14)
8032 /* xgettext: range: 1..6 */
8033 printf (ngettext ("one week and one day", "one week and %d days",
8037 It is also possible to use this function when the strings don't
8038 contain a cardinal number:
8040 puts (ngettext ("Delete the selected file?",
8041 "Delete the selected files?",
8044 In this case the number N is only used to choose the plural form.
8046 -- Function: char * dngettext (const char *DOMAIN, const char *MSGID1,
8047 const char *MSGID2, unsigned long int N)
8048 The `dngettext' is similar to the `dgettext' function in the way
8049 the message catalog is selected. The difference is that it takes
8050 two extra parameter to provide the correct plural form. These two
8051 parameters are handled in the same way `ngettext' handles them.
8053 -- Function: char * dcngettext (const char *DOMAIN, const char
8054 *MSGID1, const char *MSGID2, unsigned long int N, int
8056 The `dcngettext' is similar to the `dcgettext' function in the way
8057 the message catalog is selected. The difference is that it takes
8058 two extra parameter to provide the correct plural form. These two
8059 parameters are handled in the same way `ngettext' handles them.
8061 Now, how do these functions solve the problem of the plural forms?
8062 Without the input of linguists (which was not available) it was not
8063 possible to determine whether there are only a few different forms in
8064 which plural forms are formed or whether the number can increase with
8065 every new supported language.
8067 Therefore the solution implemented is to allow the translator to
8068 specify the rules of how to select the plural form. Since the formula
8069 varies with every language this is the only viable solution except for
8070 hardcoding the information in the code (which still would require the
8071 possibility of extensions to not prevent the use of new languages).
8073 The information about the plural form selection has to be stored in
8074 the header entry of the PO file (the one with the empty `msgid' string).
8075 The plural form information looks like this:
8077 Plural-Forms: nplurals=2; plural=n == 1 ? 0 : 1;
8079 The `nplurals' value must be a decimal number which specifies how
8080 many different plural forms exist for this language. The string
8081 following `plural' is an expression which is using the C language
8082 syntax. Exceptions are that no negative numbers are allowed, numbers
8083 must be decimal, and the only variable allowed is `n'. Spaces are
8084 allowed in the expression, but backslash-newlines are not; in the
8085 examples below the backslash-newlines are present for formatting
8086 purposes only. This expression will be evaluated whenever one of the
8087 functions `ngettext', `dngettext', or `dcngettext' is called. The
8088 numeric value passed to these functions is then substituted for all uses
8089 of the variable `n' in the expression. The resulting value then must
8090 be greater or equal to zero and smaller than the value given as the
8091 value of `nplurals'.
8093 The following rules are known at this point. The language with families
8094 are listed. But this does not necessarily mean the information can be
8095 generalized for the whole family (as can be easily seen in the table
8099 Some languages only require one single form. There is no
8100 distinction between the singular and plural form. An appropriate
8101 header entry would look like this:
8103 Plural-Forms: nplurals=1; plural=0;
8105 Languages with this property include:
8108 Japanese, Vietnamese, Korean
8110 Two forms, singular used for one only
8111 This is the form used in most existing programs since it is what
8112 English is using. A header entry would look like this:
8114 Plural-Forms: nplurals=2; plural=n != 1;
8116 (Note: this uses the feature of C expressions that boolean
8117 expressions have to value zero or one.)
8119 Languages with this property include:
8122 English, German, Dutch, Swedish, Danish, Norwegian, Faroese
8125 Spanish, Portuguese, Italian, Bulgarian
8139 Other languages using the same header entry are:
8144 Turkic/Altaic family
8147 Hungarian does not appear to have a plural if you look at
8148 sentences involving cardinal numbers. For example, "1 apple" is
8149 "1 alma", and "123 apples" is "123 alma". But when the number is
8150 not explicit, the distinction between singular and plural exists:
8151 "the apple" is "az alma", and "the apples" is "az almák". Since
8152 `ngettext' has to support both types of sentences, it is
8153 classified here, under "two forms".
8155 The same holds for Turkish: "1 apple" is "1 elma", and "123
8156 apples" is "123 elma". But when the number is omitted, the
8157 distinction between singular and plural exists: "the apple" is
8158 "elma", and "the apples" is "elmalar".
8160 Two forms, singular used for zero and one
8161 Exceptional case in the language family. The header entry would
8164 Plural-Forms: nplurals=2; plural=n>1;
8166 Languages with this property include:
8169 Brazilian Portuguese, French
8171 Three forms, special case for zero
8172 The header entry would be:
8174 Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n != 0 ? 1 : 2;
8176 Languages with this property include:
8181 Three forms, special cases for one and two
8182 The header entry would be:
8184 Plural-Forms: nplurals=3; plural=n==1 ? 0 : n==2 ? 1 : 2;
8186 Languages with this property include:
8191 Three forms, special case for numbers ending in 00 or [2-9][0-9]
8192 The header entry would be:
8194 Plural-Forms: nplurals=3; \
8195 plural=n==1 ? 0 : (n==0 || (n%100 > 0 && n%100 < 20)) ? 1 : 2;
8197 Languages with this property include:
8202 Three forms, special case for numbers ending in 1[2-9]
8203 The header entry would look like this:
8205 Plural-Forms: nplurals=3; \
8206 plural=n%10==1 && n%100!=11 ? 0 : \
8207 n%10>=2 && (n%100<10 || n%100>=20) ? 1 : 2;
8209 Languages with this property include:
8214 Three forms, special cases for numbers ending in 1 and 2, 3, 4, except those ending in 1[1-4]
8215 The header entry would look like this:
8217 Plural-Forms: nplurals=3; \
8218 plural=n%10==1 && n%100!=11 ? 0 : \
8219 n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;
8221 Languages with this property include:
8224 Russian, Ukrainian, Serbian, Croatian
8226 Three forms, special cases for 1 and 2, 3, 4
8227 The header entry would look like this:
8229 Plural-Forms: nplurals=3; \
8230 plural=(n==1) ? 0 : (n>=2 && n<=4) ? 1 : 2;
8232 Languages with this property include:
8237 Three forms, special case for one and some numbers ending in 2, 3, or 4
8238 The header entry would look like this:
8240 Plural-Forms: nplurals=3; \
8242 n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;
8244 Languages with this property include:
8249 Four forms, special case for one and all numbers ending in 02, 03, or 04
8250 The header entry would look like this:
8252 Plural-Forms: nplurals=4; \
8253 plural=n%100==1 ? 0 : n%100==2 ? 1 : n%100==3 || n%100==4 ? 2 : 3;
8255 Languages with this property include:
8260 You might now ask, `ngettext' handles only numbers N of type
8261 `unsigned long'. What about larger integer types? What about negative
8262 numbers? What about floating-point numbers?
8264 About larger integer types, such as `uintmax_t' or `unsigned long
8265 long': they can be handled by reducing the value to a range that fits
8266 in an `unsigned long'. Simply casting the value to `unsigned long'
8267 would not do the right thing, since it would treat `ULONG_MAX + 1' like
8268 zero, `ULONG_MAX + 2' like singular, and the like. Here you can
8269 exploit the fact that all mentioned plural form formulas eventually
8270 become periodic, with a period that is a divisor of 100 (or 1000 or
8271 1000000). So, when you reduce a large value to another one in the
8272 range [1000000, 1999999] that ends in the same 6 decimal digits, you
8273 can assume that it will lead to the same plural form selection. This
8276 #include <inttypes.h>
8277 uintmax_t nbytes = ...;
8278 printf (ngettext ("The file has %"PRIuMAX" byte.",
8279 "The file has %"PRIuMAX" bytes.",
8281 ? (nbytes % 1000000) + 1000000
8285 Negative and floating-point values usually represent physical
8286 entities for which singular and plural don't clearly apply. In such
8287 cases, there is no need to use `ngettext'; a simple `gettext' call with
8288 a form suitable for all values will do. For example:
8290 printf (gettext ("Time elapsed: %.3f seconds"),
8291 num_milliseconds * 0.001);
8293 Even if NUM_MILLISECONDS happens to be a multiple of 1000, the output
8294 Time elapsed: 1.000 seconds
8295 is acceptable in English, and similarly for other languages.
8297 The translators' perspective regarding plural forms is explained in
8298 *note Translating plural forms::.
8300 ---------- Footnotes ----------
8302 (1) Additions are welcome. Send appropriate information to
8303 <bug-gnu-gettext@gnu.org> and <bug-glibc-manual@gnu.org>.
8306 File: gettext.info, Node: Optimized gettext, Prev: Plural forms, Up: gettext
8308 11.2.7 Optimization of the *gettext functions
8309 ---------------------------------------------
8311 At this point of the discussion we should talk about an advantage of
8312 the GNU `gettext' implementation. Some readers might have pointed out
8313 that an internationalized program might have a poor performance if some
8314 string has to be translated in an inner loop. While this is unavoidable
8315 when the string varies from one run of the loop to the other it is
8316 simply a waste of time when the string is always the same. Take the
8322 puts (gettext ("Hello world"));
8326 When the locale selection does not change between two runs the resulting
8327 string is always the same. One way to use this is:
8330 str = gettext ("Hello world");
8337 But this solution is not usable in all situation (e.g. when the locale
8338 selection changes) nor does it lead to legible code.
8340 For this reason, GNU `gettext' caches previous translation results.
8341 When the same translation is requested twice, with no new message
8342 catalogs being loaded in between, `gettext' will, the second time, find
8343 the result through a single cache lookup.
8346 File: gettext.info, Node: Comparison, Next: Using libintl.a, Prev: gettext, Up: Programmers
8348 11.3 Comparing the Two Interfaces
8349 =================================
8351 The following discussion is perhaps a little bit colored. As said
8352 above we implemented GNU `gettext' following the Uniforum proposal and
8353 this surely has its reasons. But it should show how we came to this
8356 First we take a look at the developing process. When we write an
8357 application using NLS provided by `gettext' we proceed as always. Only
8358 when we come to a string which might be seen by the users and thus has
8359 to be translated we use `gettext("...")' instead of `"..."'. At the
8360 beginning of each source file (or in a central header file) we define
8362 #define gettext(String) (String)
8364 Even this definition can be avoided when the system supports the
8365 `gettext' function in its C library. When we compile this code the
8366 result is the same as if no NLS code is used. When you take a look at
8367 the GNU `gettext' code you will see that we use `_("...")' instead of
8368 `gettext("...")'. This reduces the number of additional characters per
8369 translatable string to _3_ (in words: three).
8371 When now a production version of the program is needed we simply
8372 replace the definition
8374 #define _(String) (String)
8378 #include <libintl.h>
8379 #define _(String) gettext (String)
8381 Additionally we run the program `xgettext' on all source code file
8382 which contain translatable strings and that's it: we have a running
8383 program which does not depend on translations to be available, but which
8384 can use any that becomes available.
8386 The same procedure can be done for the `gettext_noop' invocations
8387 (*note Special cases::). One usually defines `gettext_noop' as a no-op
8388 macro. So you should consider the following code for your project:
8390 #define gettext_noop(String) String
8391 #define N_(String) gettext_noop (String)
8393 `N_' is a short form similar to `_'. The `Makefile' in the `po/'
8394 directory of GNU `gettext' knows by default both of the mentioned short
8395 forms so you are invited to follow this proposal for your own ease.
8397 Now to `catgets'. The main problem is the work for the programmer.
8398 Every time he comes to a translatable string he has to define a number
8399 (or a symbolic constant) which has also be defined in the message
8400 catalog file. He also has to take care for duplicate entries,
8401 duplicate message IDs etc. If he wants to have the same quality in the
8402 message catalog as the GNU `gettext' program provides he also has to
8403 put the descriptive comments for the strings and the location in all
8404 source code files in the message catalog. This is nearly a Mission:
8407 But there are also some points people might call advantages speaking
8408 for `catgets'. If you have a single word in a string and this string
8409 is used in different contexts it is likely that in one or the other
8410 language the word has different translations. Example:
8412 printf ("%s: %d", gettext ("number"), number_of_errors)
8414 printf ("you should see %d %s", number_count,
8415 number_count == 1 ? gettext ("number") : gettext ("numbers"))
8417 Here we have to translate two times the string `"number"'. Even if
8418 you do not speak a language beside English it might be possible to
8419 recognize that the two words have a different meaning. In German the
8420 first appearance has to be translated to `"Anzahl"' and the second to
8423 Now you can say that this example is really esoteric. And you are
8424 right! This is exactly how we felt about this problem and decide that
8425 it does not weight that much. The solution for the above problem could
8428 printf ("%s %d", gettext ("number:"), number_of_errors)
8430 printf (number_count == 1 ? gettext ("you should see %d number")
8431 : gettext ("you should see %d numbers"),
8434 We believe that we can solve all conflicts with this method. If it
8435 is difficult one can also consider changing one of the conflicting
8436 string a little bit. But it is not impossible to overcome.
8438 `catgets' allows same original entry to have different translations,
8439 but `gettext' has another, scalable approach for solving ambiguities of
8440 this kind: *Note Ambiguities::.
8443 File: gettext.info, Node: Using libintl.a, Next: gettext grok, Prev: Comparison, Up: Programmers
8445 11.4 Using libintl.a in own programs
8446 ====================================
8448 Starting with version 0.9.4 the library `libintl.h' should be
8449 self-contained. I.e., you can use it in your own programs without
8450 providing additional functions. The `Makefile' will put the header and
8451 the library in directories selected using the `$(prefix)'.
8454 File: gettext.info, Node: gettext grok, Next: Temp Programmers, Prev: Using libintl.a, Up: Programmers
8456 11.5 Being a `gettext' grok
8457 ===========================
8459 * NOTE: * This documentation section is outdated and needs to be
8462 To fully exploit the functionality of the GNU `gettext' library it
8463 is surely helpful to read the source code. But for those who don't want
8464 to spend that much time in reading the (sometimes complicated) code here
8467 * Changing the language at runtime
8469 For interactive programs it might be useful to offer a selection
8470 of the used language at runtime. To understand how to do this one
8471 need to know how the used language is determined while executing
8472 the `gettext' function. The method which is presented here only
8473 works correctly with the GNU implementation of the `gettext'
8476 In the function `dcgettext' at every call the current setting of
8477 the highest priority environment variable is determined and used.
8478 Highest priority means here the following list with decreasing
8485 3. `LC_xxx', according to selected locale category
8489 Afterwards the path is constructed using the found value and the
8490 translation file is loaded if available.
8492 What happens now when the value for, say, `LANGUAGE' changes?
8493 According to the process explained above the new value of this
8494 variable is found as soon as the `dcgettext' function is called.
8495 But this also means the (perhaps) different message catalog file
8496 is loaded. In other words: the used language is changed.
8498 But there is one little hook. The code for gcc-2.7.0 and up
8499 provides some optimization. This optimization normally prevents
8500 the calling of the `dcgettext' function as long as no new catalog
8501 is loaded. But if `dcgettext' is not called the program also
8502 cannot find the `LANGUAGE' variable be changed (*note Optimized
8503 gettext::). A solution for this is very easy. Include the
8504 following code in the language switching function.
8506 /* Change language. */
8507 setenv ("LANGUAGE", "fr", 1);
8509 /* Make change known. */
8511 extern int _nl_msg_cat_cntr;
8515 The variable `_nl_msg_cat_cntr' is defined in `loadmsgcat.c'. You
8516 don't need to know what this is for. But it can be used to detect
8517 whether a `gettext' implementation is GNU gettext and not non-GNU
8518 system's native gettext implementation.
8522 File: gettext.info, Node: Temp Programmers, Prev: gettext grok, Up: Programmers
8524 11.6 Temporary Notes for the Programmers Chapter
8525 ================================================
8527 * NOTE: * This documentation section is outdated and needs to be
8532 * Temp Implementations:: Temporary - Two Possible Implementations
8533 * Temp catgets:: Temporary - About `catgets'
8534 * Temp WSI:: Temporary - Why a single implementation
8535 * Temp Notes:: Temporary - Notes
8538 File: gettext.info, Node: Temp Implementations, Next: Temp catgets, Prev: Temp Programmers, Up: Temp Programmers
8540 11.6.1 Temporary - Two Possible Implementations
8541 -----------------------------------------------
8543 There are two competing methods for language independent messages:
8544 the X/Open `catgets' method, and the Uniforum `gettext' method. The
8545 `catgets' method indexes messages by integers; the `gettext' method
8546 indexes them by their English translations. The `catgets' method has
8547 been around longer and is supported by more vendors. The `gettext'
8548 method is supported by Sun, and it has been heard that the COSE
8549 multi-vendor initiative is supporting it. Neither method is a POSIX
8550 standard; the POSIX.1 committee had a lot of disagreement in this area.
8552 Neither one is in the POSIX standard. There was much disagreement
8553 in the POSIX.1 committee about using the `gettext' routines vs.
8554 `catgets' (XPG). In the end the committee couldn't agree on anything,
8555 so no messaging system was included as part of the standard. I believe
8556 the informative annex of the standard includes the XPG3 messaging
8557 interfaces, "...as an example of a messaging system that has been
8560 They were very careful not to say anywhere that you should use one
8561 set of interfaces over the other. For more on this topic please see
8562 the Programming for Internationalization FAQ.
8565 File: gettext.info, Node: Temp catgets, Next: Temp WSI, Prev: Temp Implementations, Up: Temp Programmers
8567 11.6.2 Temporary - About `catgets'
8568 ----------------------------------
8570 There have been a few discussions of late on the use of `catgets' as
8571 a base. I think it important to present both sides of the argument and
8572 hence am opting to play devil's advocate for a little bit.
8574 I'll not deny the fact that `catgets' could have been designed a lot
8575 better. It currently has quite a number of limitations and these have
8576 already been pointed out.
8578 However there is a great deal to be said for consistency and
8579 standardization. A common recurring problem when writing Unix software
8580 is the myriad portability problems across Unix platforms. It seems as
8581 if every Unix vendor had a look at the operating system and found parts
8582 they could improve upon. Undoubtedly, these modifications are probably
8583 innovative and solve real problems. However, software developers have
8584 a hard time keeping up with all these changes across so many platforms.
8586 And this has prompted the Unix vendors to begin to standardize their
8587 systems. Hence the impetus for Spec1170. Every major Unix vendor has
8588 committed to supporting this standard and every Unix software developer
8589 waits with glee the day they can write software to this standard and
8590 simply recompile (without having to use autoconf) across different
8593 As I understand it, Spec1170 is roughly based upon version 4 of the
8594 X/Open Portability Guidelines (XPG4). Because `catgets' and friends
8595 are defined in XPG4, I'm led to believe that `catgets' is a part of
8596 Spec1170 and hence will become a standardized component of all Unix
8600 File: gettext.info, Node: Temp WSI, Next: Temp Notes, Prev: Temp catgets, Up: Temp Programmers
8602 11.6.3 Temporary - Why a single implementation
8603 ----------------------------------------------
8605 Now it seems kind of wasteful to me to have two different systems
8606 installed for accessing message catalogs. If we do want to remedy
8607 `catgets' deficiencies why don't we try to expand `catgets' (in a
8608 compatible manner) rather than implement an entirely new system.
8609 Otherwise, we'll end up with two message catalog access systems
8610 installed with an operating system - one set of routines for packages
8611 using GNU `gettext' for their internationalization, and another set of
8612 routines (catgets) for all other software. Bloated?
8614 Supposing another catalog access system is implemented. Which do we
8615 recommend? At least for Linux, we need to attract as many software
8616 developers as possible. Hence we need to make it as easy for them to
8617 port their software as possible. Which means supporting `catgets'. We
8618 will be implementing the `libintl' code within our `libc', but does
8619 this mean we also have to incorporate another message catalog access
8620 scheme within our `libc' as well? And what about people who are going
8621 to be using the `libintl' + non-`catgets' routines. When they port
8622 their software to other platforms, they're now going to have to include
8623 the front-end (`libintl') code plus the back-end code (the non-`catgets'
8624 access routines) with their software instead of just including the
8625 `libintl' code with their software.
8627 Message catalog support is however only the tip of the iceberg.
8628 What about the data for the other locale categories? They also have a
8629 number of deficiencies. Are we going to abandon them as well and
8630 develop another duplicate set of routines (should `libintl' expand
8631 beyond message catalog support)?
8633 Like many parts of Unix that can be improved upon, we're stuck with
8634 balancing compatibility with the past with useful improvements and
8635 innovations for the future.
8638 File: gettext.info, Node: Temp Notes, Prev: Temp WSI, Up: Temp Programmers
8640 11.6.4 Temporary - Notes
8641 ------------------------
8643 X/Open agreed very late on the standard form so that many
8644 implementations differ from the final form. Both of my system (old
8645 Linux catgets and Ultrix-4) have a strange variation.
8647 OK. After incorporating the last changes I have to spend some time
8648 on making the GNU/Linux `libc' `gettext' functions. So in future
8649 Solaris is not the only system having `gettext'.
8652 File: gettext.info, Node: Translators, Next: Maintainers, Prev: Programmers, Up: Top
8654 12 The Translator's View
8655 ************************
8659 * Trans Intro 0:: Introduction 0
8660 * Trans Intro 1:: Introduction 1
8661 * Discussions:: Discussions
8662 * Organization:: Organization
8663 * Information Flow:: Information Flow
8664 * Translating plural forms:: How to fill in `msgstr[0]', `msgstr[1]'
8665 * Prioritizing messages:: How to find which messages to translate first
8668 File: gettext.info, Node: Trans Intro 0, Next: Trans Intro 1, Prev: Translators, Up: Translators
8673 * NOTE: * This documentation section is outdated and needs to be
8676 Free software is going international! The Translation Project is a
8677 way to get maintainers, translators and users all together, so free
8678 software will gradually become able to speak many native languages.
8680 The GNU `gettext' tool set contains _everything_ maintainers need
8681 for internationalizing their packages for messages. It also contains
8682 quite useful tools for helping translators at localizing messages to
8683 their native language, once a package has already been
8686 To achieve the Translation Project, we need many interested people
8687 who like their own language and write it well, and who are also able to
8688 synergize with other translators speaking the same language. If you'd
8689 like to volunteer to _work_ at translating messages, please send mail
8690 to your translating team.
8692 Each team has its own mailing list, courtesy of Linux International.
8693 You may reach your translating team at the address `LL@li.org',
8694 replacing LL by the two-letter ISO 639 code for your language.
8695 Language codes are _not_ the same as country codes given in ISO 3166.
8696 The following translating teams exist:
8698 Chinese `zh', Czech `cs', Danish `da', Dutch `nl', Esperanto `eo',
8699 Finnish `fi', French `fr', Irish `ga', German `de', Greek `el',
8700 Italian `it', Japanese `ja', Indonesian `in', Norwegian `no',
8701 Polish `pl', Portuguese `pt', Russian `ru', Spanish `es', Swedish
8702 `sv' and Turkish `tr'.
8704 For example, you may reach the Chinese translating team by writing to
8705 `zh@li.org'. When you become a member of the translating team for your
8706 own language, you may subscribe to its list. For example, Swedish
8707 people can send a message to `sv-request@li.org', having this message
8712 Keep in mind that team members should be interested in _working_ at
8713 translations, or at solving translational difficulties, rather than
8714 merely lurking around. If your team does not exist yet and you want to
8715 start one, please write to `coordinator@translationproject.org'; you
8716 will then reach the coordinator for all translator teams.
8718 A handful of GNU packages have already been adapted and provided
8719 with message translations for several languages. Translation teams
8720 have begun to organize, using these packages as a starting point. But
8721 there are many more packages and many languages for which we have no
8722 volunteer translators. If you would like to volunteer to work at
8723 translating messages, please send mail to
8724 `coordinator@translationproject.org' indicating what language(s) you
8728 File: gettext.info, Node: Trans Intro 1, Next: Discussions, Prev: Trans Intro 0, Up: Translators
8733 * NOTE: * This documentation section is outdated and needs to be
8736 This is now official, GNU is going international! Here is the
8737 announcement submitted for the January 1995 GNU Bulletin:
8739 A handful of GNU packages have already been adapted and provided
8740 with message translations for several languages. Translation
8741 teams have begun to organize, using these packages as a starting
8742 point. But there are many more packages and many languages for
8743 which we have no volunteer translators. If you'd like to
8744 volunteer to work at translating messages, please send mail to
8745 `coordinator@translationproject.org' indicating what language(s)
8748 This document should answer many questions for those who are curious
8749 about the process or would like to contribute. Please at least skim
8750 over it, hoping to cut down a little of the high volume of e-mail
8751 generated by this collective effort towards internationalization of
8754 Most free programming which is widely shared is done in English, and
8755 currently, English is used as the main communicating language between
8756 national communities collaborating to free software. This very document
8757 is written in English. This will not change in the foreseeable future.
8759 However, there is a strong appetite from national communities for
8760 having more software able to write using national language and habits,
8761 and there is an on-going effort to modify free software in such a way
8762 that it becomes able to do so. The experiments driven so far raised an
8763 enthusiastic response from pretesters, so we believe that
8764 internationalization of free software is dedicated to succeed.
8766 For suggestion clarifications, additions or corrections to this
8767 document, please e-mail to `coordinator@translationproject.org'.
8770 File: gettext.info, Node: Discussions, Next: Organization, Prev: Trans Intro 1, Up: Translators
8775 * NOTE: * This documentation section is outdated and needs to be
8778 Facing this internationalization effort, a few users expressed their
8779 concerns. Some of these doubts are presented and discussed, here.
8783 Some languages are not spoken by a very large number of people, so
8784 people speaking them sometimes consider that there may not be all
8785 that much demand such versions of free software packages.
8786 Moreover, many people being _into computers_, in some countries,
8787 generally seem to prefer English versions of their software.
8789 On the other end, people might enjoy their own language a lot, and
8790 be very motivated at providing to themselves the pleasure of
8791 having their beloved free software speaking their mother tongue.
8792 They do themselves a personal favor, and do not pay that much
8793 attention to the number of people benefiting of their work.
8797 Other users are shy to push forward their own language, seeing in
8798 this some kind of misplaced propaganda. Someone thought there
8799 must be some users of the language over the networks pestering
8800 other people with it.
8802 But any spoken language is worth localization, because there are
8803 people behind the language for whom the language is important and
8804 dear to their hearts.
8808 The biggest problem is to find the right translations so that
8809 everybody can understand the messages. Translations are usually a
8810 little odd. Some people get used to English, to the extent they
8811 may find translations into their own language "rather pushy,
8812 obnoxious and sometimes even hilarious." As a French speaking
8813 man, I have the experience of those instruction manuals for goods,
8814 so poorly translated in French in Korea or Taiwan...
8816 The fact is that we sometimes have to create a kind of national
8817 computer culture, and this is not easy without the collaboration of
8818 many people liking their mother tongue. This is why translations
8819 are better achieved by people knowing and loving their own
8820 language, and ready to work together at improving the results they
8823 * Dependencies over the GPL or LGPL
8825 Some people wonder if using GNU `gettext' necessarily brings their
8826 package under the protective wing of the GNU General Public
8827 License or the GNU Library General Public License, when they do
8828 not want to make their program free, or want other kinds of
8829 freedom. The simplest answer is "normally not".
8831 The `gettext-runtime' part of GNU `gettext', i.e. the contents of
8832 `libintl', is covered by the GNU Library General Public License.
8833 The `gettext-tools' part of GNU `gettext', i.e. the rest of the
8834 GNU `gettext' package, is covered by the GNU General Public
8837 The mere marking of localizable strings in a package, or
8838 conditional inclusion of a few lines for initialization, is not
8839 really including GPL'ed or LGPL'ed code. However, since the
8840 localization routines in `libintl' are under the LGPL, the LGPL
8841 needs to be considered. It gives the right to distribute the
8842 complete unmodified source of `libintl' even with non-free
8843 programs. It also gives the right to use `libintl' as a shared
8844 library, even for non-free programs. But it gives the right to
8845 use `libintl' as a static library or to incorporate `libintl' into
8846 another library only to free software.
8850 File: gettext.info, Node: Organization, Next: Information Flow, Prev: Discussions, Up: Translators
8855 * NOTE: * This documentation section is outdated and needs to be
8858 On a larger scale, the true solution would be to organize some kind
8859 of fairly precise set up in which volunteers could participate. I gave
8860 some thought to this idea lately, and realize there will be some touchy
8861 points. I thought of writing to Richard Stallman to launch such a
8862 project, but feel it might be good to shake out the ideas between
8863 ourselves first. Most probably that Linux International has some
8864 experience in the field already, or would like to orchestrate the
8865 volunteer work, maybe. Food for thought, in any case!
8867 I guess we have to setup something early, somehow, that will help
8868 many possible contributors of the same language to interlock and avoid
8869 work duplication, and further be put in contact for solving together
8870 problems particular to their tongue (in most languages, there are many
8871 difficulties peculiar to translating technical English). My Swedish
8872 contributor acknowledged these difficulties, and I'm well aware of them
8875 This is surely not a technical issue, but we should manage so the
8876 effort of locale contributors be maximally useful, despite the national
8877 team layer interface between contributors and maintainers.
8879 The Translation Project needs some setup for coordinating language
8880 coordinators. Localizing evolving programs will surely become a
8881 permanent and continuous activity in the free software community, once
8882 well started. The setup should be minimally completed and tested
8883 before GNU `gettext' becomes an official reality. The e-mail address
8884 `coordinator@translationproject.org' has been set up for receiving
8885 offers from volunteers and general e-mail on these topics. This address
8886 reaches the Translation Project coordinator.
8890 * Central Coordination:: Central Coordination
8891 * National Teams:: National Teams
8892 * Mailing Lists:: Mailing Lists
8895 File: gettext.info, Node: Central Coordination, Next: National Teams, Prev: Organization, Up: Organization
8897 12.4.1 Central Coordination
8898 ---------------------------
8900 I also think GNU will need sooner than it thinks, that someone set up
8901 a way to organize and coordinate these groups. Some kind of group of
8902 groups. My opinion is that it would be good that GNU delegates this
8903 task to a small group of collaborating volunteers, shortly. Perhaps in
8904 `gnu.announce' a list of this national committee's can be published.
8906 My role as coordinator would simply be to refer to Ulrich any German
8907 speaking volunteer interested to localization of free software
8908 packages, and maybe helping national groups to initially organize,
8909 while maintaining national registries for until national groups are
8910 ready to take over. In fact, the coordinator should ease volunteers to
8911 get in contact with one another for creating national teams, which
8912 should then select one coordinator per language, or country
8913 (regionalized language). If well done, the coordination should be
8914 useful without being an overwhelming task, the time to put delegations
8918 File: gettext.info, Node: National Teams, Next: Mailing Lists, Prev: Central Coordination, Up: Organization
8920 12.4.2 National Teams
8921 ---------------------
8923 I suggest we look for volunteer coordinators/editors for individual
8924 languages. These people will scan contributions of translation files
8925 for various programs, for their own languages, and will ensure high and
8926 uniform standards of diction.
8928 From my current experience with other people in these days, those who
8929 provide localizations are very enthusiastic about the process, and are
8930 more interested in the localization process than in the program they
8931 localize, and want to do many programs, not just one. This seems to
8932 confirm that having a coordinator/editor for each language is a good
8935 We need to choose someone who is good at writing clear and concise
8936 prose in the language in question. That is hard--we can't check it
8937 ourselves. So we need to ask a few people to judge each others'
8938 writing and select the one who is best.
8940 I announce my prerelease to a few dozen people, and you would not
8941 believe all the discussions it generated already. I shudder to think
8942 what will happen when this will be launched, for true, officially,
8943 world wide. Who am I to arbitrate between two Czekolsovak users
8944 contradicting each other, for example?
8946 I assume that your German is not much better than my French so that
8947 I would not be able to judge about these formulations. What I would
8948 suggest is that for each language there is a group for people who
8949 maintain the PO files and judge about changes. I suspect there will be
8950 cultural differences between how such groups of people will behave.
8951 Some will have relaxed ways, reach consensus easily, and have anyone of
8952 the group relate to the maintainers, while others will fight to death,
8953 organize heavy administrations up to national standards, and use strict
8956 The German team is putting out a good example. Right now, they are
8957 maybe half a dozen people revising translations of each other and
8958 discussing the linguistic issues. I do not even have all the names.
8959 Ulrich Drepper is taking care of coordinating the German team. He
8960 subscribed to all my pretest lists, so I do not even have to warn him
8961 specifically of incoming releases.
8963 I'm sure, that is a good idea to get teams for each language working
8964 on translations. That will make the translations better and more
8969 * Sub-Cultures:: Sub-Cultures
8970 * Organizational Ideas:: Organizational Ideas
8973 File: gettext.info, Node: Sub-Cultures, Next: Organizational Ideas, Prev: National Teams, Up: National Teams
8975 12.4.2.1 Sub-Cultures
8976 .....................
8978 Taking French for example, there are a few sub-cultures around
8979 computers which developed diverging vocabularies. Picking volunteers
8980 here and there without addressing this problem in an organized way,
8981 soon in the project, might produce a distasteful mix of
8982 internationalized programs, and possibly trigger endless quarrels among
8983 those who really care.
8985 Keeping some kind of unity in the way French localization of
8986 internationalized programs is achieved is a difficult (and delicate)
8987 job. Knowing the latin character of French people (:-), if we take this
8988 the wrong way, we could end up nowhere, or spoil a lot of energies.
8989 Maybe we should begin to address this problem seriously _before_ GNU
8990 `gettext' become officially published. And I suspect that this means
8994 File: gettext.info, Node: Organizational Ideas, Prev: Sub-Cultures, Up: National Teams
8996 12.4.2.2 Organizational Ideas
8997 .............................
8999 I expect the next big changes after the official release. Please
9000 note that I use the German translation of the short GPL message. We
9001 need to set a few good examples before the localization goes out for
9002 true in the free software community. Here are a few points to discuss:
9004 * Each group should have one FTP server (at least one master).
9006 * The files on the server should reflect the latest version (of
9007 course!) and it should also contain a RCS directory with the
9008 corresponding archives (I don't have this now).
9010 * There should also be a ChangeLog file (this is more useful than the
9011 RCS archive but can be generated automatically from the later by
9014 * A "core group" should judge about questionable changes (for now
9015 this group consists solely by me but I ask some others
9016 occasionally; this also seems to work).
9020 File: gettext.info, Node: Mailing Lists, Prev: National Teams, Up: Organization
9022 12.4.3 Mailing Lists
9023 --------------------
9025 If we get any inquiries about GNU `gettext', send them on to:
9027 `coordinator@translationproject.org'
9029 The `*-pretest' lists are quite useful to me, maybe the idea could
9030 be generalized to many GNU, and non-GNU packages. But each maintainer
9033 François, we have a mechanism in place here at `gnu.ai.mit.edu' to
9034 track teams, support mailing lists for them and log members. We have a
9035 slight preference that you use it. If this is OK with you, I can get
9038 Things are changing! A few years ago, when Daniel Fekete and I
9039 asked for a mailing list for GNU localization, nested at the FSF, we
9040 were politely invited to organize it anywhere else, and so did we. For
9041 communicating with my pretesters, I later made a handful of mailing
9042 lists located at iro.umontreal.ca and administrated by `majordomo'.
9043 These lists have been _very_ dependable so far...
9045 I suspect that the German team will organize itself a mailing list
9046 located in Germany, and so forth for other countries. But before they
9047 organize for true, it could surely be useful to offer mailing lists
9048 located at the FSF to each national team. So yes, please explain me
9049 how I should proceed to create and handle them.
9051 We should create temporary mailing lists, one per country, to help
9052 people organize. Temporary, because once regrouped and structured, it
9053 would be fair the volunteers from country bring back _their_ list in
9054 there and manage it as they want. My feeling is that, in the long run,
9055 each team should run its own list, from within their country. There
9056 also should be some central list to which all teams could subscribe as
9057 they see fit, as long as each team is represented in it.
9060 File: gettext.info, Node: Information Flow, Next: Translating plural forms, Prev: Organization, Up: Translators
9062 12.5 Information Flow
9063 =====================
9065 * NOTE: * This documentation section is outdated and needs to be
9068 There will surely be some discussion about this messages after the
9069 packages are finally released. If people now send you some proposals
9070 for better messages, how do you proceed? Jim, please note that right
9071 now, as I put forward nearly a dozen of localizable programs, I receive
9072 both the translations and the coordination concerns about them.
9074 If I put one of my things to pretest, Ulrich receives the
9075 announcement and passes it on to the German team, who make last minute
9076 revisions. Then he submits the translation files to me _as the
9077 maintainer_. For free packages I do not maintain, I would not even
9078 hear about it. This scheme could be made to work for the whole
9079 Translation Project, I think. For security reasons, maybe Ulrich
9080 (national coordinators, in fact) should update central registry kept at
9081 the Translation Project (Jim, me, or Len's recruits) once in a while.
9083 In December/January, I was aggressively ready to internationalize
9084 all of GNU, giving myself the duty of one small GNU package per week or
9085 so, taking many weeks or months for bigger packages. But it does not
9086 work this way. I first did all the things I'm responsible for. I've
9087 nothing against some missionary work on other maintainers, but I'm also
9088 loosing a lot of energy over it--same debates over again.
9090 And when the first localized packages are released we'll get a lot of
9091 responses about ugly translations :-). Surely, and we need to have
9092 beforehand a fairly good idea about how to handle the information flow
9093 between the national teams and the package maintainers.
9095 Please start saving somewhere a quick history of each PO file. I
9096 know for sure that the file format will change, allowing for comments.
9097 It would be nice that each file has a kind of log, and references for
9098 those who want to submit comments or gripes, or otherwise contribute.
9099 I sent a proposal for a fast and flexible format, but it is not
9100 receiving acceptance yet by the GNU deciders. I'll tell you when I
9101 have more information about this.
9104 File: gettext.info, Node: Translating plural forms, Next: Prioritizing messages, Prev: Information Flow, Up: Translators
9106 12.6 Translating plural forms
9107 =============================
9109 Suppose you are translating a PO file, and it contains an entry like
9113 msgid "One file removed"
9114 msgid_plural "%d files removed"
9118 What does this mean? How do you fill it in?
9120 Such an entry denotes a message with plural forms, that is, a
9121 message where the text depends on a cardinal number. The general form
9122 of the message, in English, is the `msgid_plural' line. The `msgid'
9123 line is the English singular form, that is, the form for when the
9124 number is equal to 1. More details about plural forms are explained in
9125 *note Plural forms::.
9127 The first thing you need to look at is the `Plural-Forms' line in the
9128 header entry of the PO file. It contains the number of plural forms
9129 and a formula. If the PO file does not yet have such a line, you have
9130 to add it. It only depends on the language into which you are
9131 translating. You can get this info by using the `msginit' command (see
9132 *note Creating::) - it contains a database of known plural formulas -
9133 or by asking other members of your translation team.
9135 Suppose the line looks as follows:
9137 "Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n%10>=2 && n"
9138 "%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;\n"
9140 It's logically one line; recall that the PO file formatting is
9141 allowed to break long lines so that each physical line fits in 80
9144 The value of `nplurals' here tells you that there are three plural
9145 forms. The first thing you need to do is to ensure that the entry
9146 contains an `msgstr' line for each of the forms:
9149 msgid "One file removed"
9150 msgid_plural "%d files removed"
9155 Then translate the `msgid_plural' line and fill it in into each
9159 msgid "One file removed"
9160 msgid_plural "%d files removed"
9161 msgstr[0] "%d slika uklonjenih"
9162 msgstr[1] "%d slika uklonjenih"
9163 msgstr[2] "%d slika uklonjenih"
9165 Now you can refine the translation so that it matches the plural
9166 form. According to the formula above, `msgstr[0]' is used when the
9167 number ends in 1 but does not end in 11; `msgstr[1]' is used when the
9168 number ends in 2, 3, 4, but not in 12, 13, 14; and `msgstr[2]' is used
9169 in all other cases. With this knowledge, you can refine the
9173 msgid "One file removed"
9174 msgid_plural "%d files removed"
9175 msgstr[0] "%d slika je uklonjena"
9176 msgstr[1] "%d datoteke uklonjenih"
9177 msgstr[2] "%d slika uklonjenih"
9179 You noticed that in the English singular form (`msgid') the number
9180 placeholder could be omitted and replaced by the numeral word "one".
9181 Can you do this in your translation as well?
9183 msgstr[0] "jednom datotekom je uklonjen"
9185 Well, it depends on whether `msgstr[0]' applies only to the number 1,
9186 or to other numbers as well. If, according to the plural formula,
9187 `msgstr[0]' applies only to `n == 1', then you can use the specialized
9188 translation without the number placeholder. In our case, however,
9189 `msgstr[0]' also applies to the numbers 21, 31, 41, etc., and therefore
9190 you cannot omit the placeholder.
9193 File: gettext.info, Node: Prioritizing messages, Prev: Translating plural forms, Up: Translators
9195 12.7 Prioritizing messages: How to determine which messages to translate first
9196 ==============================================================================
9198 A translator sometimes has only a limited amount of time per week to
9199 spend on a package, and some packages have quite large message catalogs
9200 (over 1000 messages). Therefore she wishes to translate the messages
9201 first that are the most visible to the user, or that occur most
9202 frequently. This section describes how to determine these "most
9203 urgent" messages. It also applies to determine the "next most urgent"
9204 messages after the message catalog has already been partially
9207 In a first step, she uses the programs like a user would do. While
9208 she does this, the GNU `gettext' library logs into a file the not yet
9209 translated messages for which a translation was requested from the
9212 In a second step, she uses the PO mode to translate precisely this
9215 Here a more details. The GNU `libintl' library (but not the
9216 corresponding functions in GNU `libc') supports an environment variable
9217 `GETTEXT_LOG_UNTRANSLATED'. The GNU `libintl' library will log into
9218 this file the messages for which `gettext()' and related functions
9219 couldn't find the translation. If the file doesn't exist, it will be
9220 created as needed. On systems with GNU `libc' a shared library
9221 `preloadable_libintl.so' is provided that can be used with the ELF
9222 `LD_PRELOAD' mechanism.
9224 So, in the first step, the translator uses these commands on systems
9227 $ LD_PRELOAD=/usr/local/lib/preloadable_libintl.so
9229 $ GETTEXT_LOG_UNTRANSLATED=$HOME/gettextlogused
9230 $ export GETTEXT_LOG_UNTRANSLATED
9232 and these commands on other systems:
9234 $ GETTEXT_LOG_UNTRANSLATED=$HOME/gettextlogused
9235 $ export GETTEXT_LOG_UNTRANSLATED
9237 Then she uses and peruses the programs. (It is a good and
9238 recommended practice to use the programs for which you provide
9239 translations: it gives you the needed context.) When done, she removes
9240 the environment variables:
9243 $ unset GETTEXT_LOG_UNTRANSLATED
9245 The second step starts with removing duplicates:
9247 $ msguniq $HOME/gettextlogused > missing.po
9249 The result is a PO file, but needs some preprocessing before a PO
9250 file editor can be used with it. First, it is a multi-domain PO file,
9251 containing messages from many translation domains. Second, it lacks
9252 all translator comments and source references. Here is how to get a
9253 list of the affected translation domains:
9255 $ sed -n -e 's,^domain "\(.*\)"$,\1,p' < missing.po | sort | uniq
9257 Then the translator can handle the domains one by one. For
9258 simplicity, let's use environment variables to denote the language,
9259 domain and source package.
9261 $ lang=nl # your language
9262 $ domain=coreutils # the name of the domain to be handled
9263 $ package=/usr/src/gnu/coreutils-4.5.4 # the package where it comes from
9265 She takes the latest copy of `$lang.po' from the Translation Project,
9266 or from the package (in most cases, `$package/po/$lang.po'), or creates
9267 a fresh one if she's the first translator (see *note Creating::). She
9268 then uses the following commands to mark the not urgent messages as
9269 "obsolete". (This doesn't mean that these messages - translated and
9270 untranslated ones - will go away. It simply means that the PO file
9271 editor will ignore them in the following editing session.)
9273 $ msggrep --domain=$domain missing.po | grep -v '^domain' \
9274 > $domain-missing.po
9275 $ msgattrib --set-obsolete --ignore-file $domain-missing.po $domain.$lang.po \
9276 > $domain.$lang-urgent.po
9278 The she translates `$domain.$lang-urgent.po' by use of a PO file
9279 editor (*note Editing::). (FIXME: I don't know whether `KBabel' and
9280 `gtranslator' also preserve obsolete messages, as they should.)
9281 Finally she restores the not urgent messages (with their earlier
9282 translations, for those which were already translated) through this
9285 $ msgmerge --no-fuzzy-matching $domain.$lang-urgent.po $package/po/$domain.pot \
9288 Then she can submit `$domain.$lang.po' and proceed to the next
9292 File: gettext.info, Node: Maintainers, Next: Installers, Prev: Translators, Up: Top
9294 13 The Maintainer's View
9295 ************************
9297 The maintainer of a package has many responsibilities. One of them
9298 is ensuring that the package will install easily on many platforms, and
9299 that the magic we described earlier (*note Users::) will work for
9300 installers and end users.
9302 Of course, there are many possible ways by which GNU `gettext' might
9303 be integrated in a distribution, and this chapter does not cover them
9304 in all generality. Instead, it details one possible approach which is
9305 especially adequate for many free software distributions following GNU
9306 standards, or even better, Gnits standards, because GNU `gettext' is
9307 purposely for helping the internationalization of the whole GNU
9308 project, and as many other good free packages as possible. So, the
9309 maintainer's view presented here presumes that the package already has
9310 a `configure.ac' file and uses GNU Autoconf.
9312 Nevertheless, GNU `gettext' may surely be useful for free packages
9313 not following GNU standards and conventions, but the maintainers of such
9314 packages might have to show imagination and initiative in organizing
9315 their distributions so `gettext' work for them in all situations.
9316 There are surely many, out there.
9318 Even if `gettext' methods are now stabilizing, slight adjustments
9319 might be needed between successive `gettext' versions, so you should
9320 ideally revise this chapter in subsequent releases, looking for changes.
9324 * Flat and Non-Flat:: Flat or Non-Flat Directory Structures
9325 * Prerequisites:: Prerequisite Works
9326 * gettextize Invocation:: Invoking the `gettextize' Program
9327 * Adjusting Files:: Files You Must Create or Alter
9328 * autoconf macros:: Autoconf macros for use in `configure.ac'
9329 * CVS Issues:: Integrating with CVS
9330 * Release Management:: Creating a Distribution Tarball
9333 File: gettext.info, Node: Flat and Non-Flat, Next: Prerequisites, Prev: Maintainers, Up: Maintainers
9335 13.1 Flat or Non-Flat Directory Structures
9336 ==========================================
9338 Some free software packages are distributed as `tar' files which
9339 unpack in a single directory, these are said to be "flat" distributions.
9340 Other free software packages have a one level hierarchy of
9341 subdirectories, using for example a subdirectory named `doc/' for the
9342 Texinfo manual and man pages, another called `lib/' for holding
9343 functions meant to replace or complement C libraries, and a
9344 subdirectory `src/' for holding the proper sources for the package.
9345 These other distributions are said to be "non-flat".
9347 We cannot say much about flat distributions. A flat directory
9348 structure has the disadvantage of increasing the difficulty of updating
9349 to a new version of GNU `gettext'. Also, if you have many PO files,
9350 this could somewhat pollute your single directory. Also, GNU
9351 `gettext''s libintl sources consist of C sources, shell scripts, `sed'
9352 scripts and complicated Makefile rules, which don't fit well into an
9353 existing flat structure. For these reasons, we recommend to use
9354 non-flat approach in this case as well.
9356 Maybe because GNU `gettext' itself has a non-flat structure, we have
9357 more experience with this approach, and this is what will be described
9358 in the remaining of this chapter. Some maintainers might use this as
9359 an opportunity to unflatten their package structure.
9362 File: gettext.info, Node: Prerequisites, Next: gettextize Invocation, Prev: Flat and Non-Flat, Up: Maintainers
9364 13.2 Prerequisite Works
9365 =======================
9367 There are some works which are required for using GNU `gettext' in
9368 one of your package. These works have some kind of generality that
9369 escape the point by point descriptions used in the remainder of this
9370 chapter. So, we describe them here.
9372 * Before attempting to use `gettextize' you should install some
9373 other packages first. Ensure that recent versions of GNU `m4',
9374 GNU Autoconf and GNU `gettext' are already installed at your site,
9375 and if not, proceed to do this first. If you get to install these
9376 things, beware that GNU `m4' must be fully installed before GNU
9377 Autoconf is even _configured_.
9379 To further ease the task of a package maintainer the `automake'
9380 package was designed and implemented. GNU `gettext' now uses this
9381 tool and the `Makefile's in the `intl/' and `po/' therefore know
9382 about all the goals necessary for using `automake' and `libintl'
9385 Those four packages are only needed by you, as a maintainer; the
9386 installers of your own package and end users do not really need
9387 any of GNU `m4', GNU Autoconf, GNU `gettext', or GNU `automake'
9388 for successfully installing and running your package, with messages
9389 properly translated. But this is not completely true if you
9390 provide internationalized shell scripts within your own package:
9391 GNU `gettext' shall then be installed at the user site if the end
9392 users want to see the translation of shell script messages.
9394 * Your package should use Autoconf and have a `configure.ac' or
9395 `configure.in' file. If it does not, you have to learn how. The
9396 Autoconf documentation is quite well written, it is a good idea
9397 that you print it and get familiar with it.
9399 * Your C sources should have already been modified according to
9400 instructions given earlier in this manual. *Note Sources::.
9402 * Your `po/' directory should receive all PO files submitted to you
9403 by the translator teams, each having `LL.po' as a name. This is
9404 not usually easy to get translation work done before your package
9405 gets internationalized and available! Since the cycle has to
9406 start somewhere, the easiest for the maintainer is to start with
9407 absolutely no PO files, and wait until various translator teams
9408 get interested in your package, and submit PO files.
9411 It is worth adding here a few words about how the maintainer should
9412 ideally behave with PO files submissions. As a maintainer, your role is
9413 to authenticate the origin of the submission as being the representative
9414 of the appropriate translating teams of the Translation Project (forward
9415 the submission to `coordinator@translationproject.org' in case of
9416 doubt), to ensure that the PO file format is not severely broken and
9417 does not prevent successful installation, and for the rest, to merely
9418 put these PO files in `po/' for distribution.
9420 As a maintainer, you do not have to take on your shoulders the
9421 responsibility of checking if the translations are adequate or
9422 complete, and should avoid diving into linguistic matters. Translation
9423 teams drive themselves and are fully responsible of their linguistic
9424 choices for the Translation Project. Keep in mind that translator
9425 teams are _not_ driven by maintainers. You can help by carefully
9426 redirecting all communications and reports from users about linguistic
9427 matters to the appropriate translation team, or explain users how to
9428 reach or join their team. The simplest might be to send them the
9431 Maintainers should _never ever_ apply PO file bug reports
9432 themselves, short-cutting translation teams. If some translator has
9433 difficulty to get some of her points through her team, it should not be
9434 an option for her to directly negotiate translations with maintainers.
9435 Teams ought to settle their problems themselves, if any. If you, as a
9436 maintainer, ever think there is a real problem with a team, please
9437 never try to _solve_ a team's problem on your own.
9440 File: gettext.info, Node: gettextize Invocation, Next: Adjusting Files, Prev: Prerequisites, Up: Maintainers
9442 13.3 Invoking the `gettextize' Program
9443 ======================================
9445 The `gettextize' program is an interactive tool that helps the
9446 maintainer of a package internationalized through GNU `gettext'. It is
9447 used for two purposes:
9449 * As a wizard, when a package is modified to use GNU `gettext' for
9452 * As a migration tool, for upgrading the GNU `gettext' support in a
9453 package from a previous to a newer version of GNU `gettext'.
9455 This program performs the following tasks:
9457 * It copies into the package some files that are consistently and
9458 identically needed in every package internationalized through GNU
9461 * It performs as many of the tasks mentioned in the next section
9462 *note Adjusting Files:: as can be performed automatically.
9464 * It removes obsolete files and idioms used for previous GNU
9465 `gettext' versions to the form recommended for the current GNU
9468 * It prints a summary of the tasks that ought to be done manually
9469 and could not be done automatically by `gettextize'.
9471 It can be invoked as follows:
9473 gettextize [ OPTION... ] [ DIRECTORY ]
9475 and accepts the following options:
9479 Force replacement of files which already exist.
9482 Install the libintl sources in a subdirectory named `intl/'. This
9483 libintl will be used to provide internationalization on systems
9484 that don't have GNU libintl installed. If this option is omitted,
9485 the call to `AM_GNU_GETTEXT' in `configure.ac' should read:
9486 `AM_GNU_GETTEXT([external])', and internationalization will not be
9487 enabled on systems lacking GNU gettext.
9490 Specify a directory containing PO files. Such a directory
9491 contains the translations into various languages of a particular
9492 POT file. This option can be specified multiple times, once for
9493 each translation domain. If it is not specified, the directory
9494 named `po/' is updated.
9497 Don't update or create ChangeLog files. By default, `gettextize'
9498 logs all changes (file additions, modifications and removals) in a
9499 file called `ChangeLog' in each affected directory.
9502 Make symbolic links instead of copying the needed files. This can
9503 be useful to save a few kilobytes of disk space, but it requires
9504 extra effort to create self-contained tarballs, it may disturb
9505 some mechanism the maintainer applies to the sources, and it is
9506 likely to introduce bugs when a newer version of `gettext' is
9507 installed on the system.
9511 Print modifications but don't perform them. All actions that
9512 `gettextize' would normally execute are inhibited and instead only
9513 listed on standard output.
9516 Display this help and exit.
9519 Output version information and exit.
9522 If DIRECTORY is given, this is the top level directory of a package
9523 to prepare for using GNU `gettext'. If not given, it is assumed that
9524 the current directory is the top level directory of such a package.
9526 The program `gettextize' provides the following files. However, no
9527 existing file will be replaced unless the option `--force' (`-f') is
9530 1. The `ABOUT-NLS' file is copied in the main directory of your
9531 package, the one being at the top level. This file gives the main
9532 indications about how to install and use the Native Language
9533 Support features of your program. You might elect to use a more
9534 recent copy of this `ABOUT-NLS' file than the one provided through
9535 `gettextize', if you have one handy. You may also fetch a more
9536 recent copy of file `ABOUT-NLS' from Translation Project sites,
9537 and from most GNU archive sites.
9539 2. A `po/' directory is created for eventually holding all
9540 translation files, but initially only containing the file
9541 `po/Makefile.in.in' from the GNU `gettext' distribution (beware
9542 the double `.in' in the file name) and a few auxiliary files. If
9543 the `po/' directory already exists, it will be preserved along
9544 with the files it contains, and only `Makefile.in.in' and the
9545 auxiliary files will be overwritten.
9547 If `--po-dir' has been specified, this holds for every directory
9548 specified through `--po-dir', instead of `po/'.
9550 3. Only if `--intl' has been specified: A `intl/' directory is
9551 created and filled with most of the files originally in the
9552 `intl/' directory of the GNU `gettext' distribution. Also, if
9553 option `--force' (`-f') is given, the `intl/' directory is emptied
9556 4. The file `config.rpath' is copied into the directory containing
9557 configuration support files. It is needed by the `AM_GNU_GETTEXT'
9560 5. Only if the project is using GNU `automake': A set of `autoconf'
9561 macro files is copied into the package's `autoconf' macro
9562 repository, usually in a directory called `m4/'.
9564 If your site support symbolic links, `gettextize' will not actually
9565 copy the files into your package, but establish symbolic links instead.
9566 This avoids duplicating the disk space needed in all packages. Merely
9567 using the `-h' option while creating the `tar' archive of your
9568 distribution will resolve each link by an actual copy in the
9569 distribution archive. So, to insist, you really should use `-h' option
9570 with `tar' within your `dist' goal of your main `Makefile.in'.
9572 Furthermore, `gettextize' will update all `Makefile.am' files in
9573 each affected directory, as well as the top level `configure.ac' or
9574 `configure.in' file.
9576 It is interesting to understand that most new files for supporting
9577 GNU `gettext' facilities in one package go in `intl/', `po/' and `m4/'
9578 subdirectories. One distinction between `intl/' and the two other
9579 directories is that `intl/' is meant to be completely identical in all
9580 packages using GNU `gettext', while the other directories will mostly
9581 contain package dependent files.
9583 The `gettextize' program makes backup files for all files it
9584 replaces or changes, and also write ChangeLog entries about these
9585 changes. This way, the careful maintainer can check after running
9586 `gettextize' whether its changes are acceptable to him, and possibly
9587 adjust them. An exception to this rule is the `intl/' directory, which
9588 is added or replaced or removed as a whole.
9590 It is important to understand that `gettextize' can not do the
9591 entire job of adapting a package for using GNU `gettext'. The amount
9592 of remaining work depends on whether the package uses GNU `automake' or
9593 not. But in any case, the maintainer should still read the section
9594 *note Adjusting Files:: after invoking `gettextize'.
9596 In particular, if after using `gettexize', you get an error
9597 `AC_COMPILE_IFELSE was called before AC_GNU_SOURCE' or `AC_RUN_IFELSE
9598 was called before AC_GNU_SOURCE', you can fix it by modifying
9599 `configure.ac', as described in *note configure.ac::.
9601 It is also important to understand that `gettextize' is not part of
9602 the GNU build system, in the sense that it should not be invoked
9603 automatically, and not be invoked by someone who doesn't assume the
9604 responsibilities of a package maintainer. For the latter purpose, a
9605 separate tool is provided, see *note autopoint Invocation::.
9608 File: gettext.info, Node: Adjusting Files, Next: autoconf macros, Prev: gettextize Invocation, Up: Maintainers
9610 13.4 Files You Must Create or Alter
9611 ===================================
9613 Besides files which are automatically added through `gettextize',
9614 there are many files needing revision for properly interacting with GNU
9615 `gettext'. If you are closely following GNU standards for Makefile
9616 engineering and auto-configuration, the adaptations should be easier to
9617 achieve. Here is a point by point description of the changes needed in
9620 So, here comes a list of files, each one followed by a description of
9621 all alterations it needs. Many examples are taken out from the GNU
9622 `gettext' 0.18.1 distribution itself, or from the GNU `hello'
9623 distribution (`http://www.franken.de/users/gnu/ke/hello' or
9624 `http://www.gnu.franken.de/ke/hello/') You may indeed refer to the
9625 source code of the GNU `gettext' and GNU `hello' packages, as they are
9626 intended to be good examples for using GNU gettext functionality.
9630 * po/POTFILES.in:: `POTFILES.in' in `po/'
9631 * po/LINGUAS:: `LINGUAS' in `po/'
9632 * po/Makevars:: `Makevars' in `po/'
9633 * po/Rules-*:: Extending `Makefile' in `po/'
9634 * configure.ac:: `configure.ac' at top level
9635 * config.guess:: `config.guess', `config.sub' at top level
9636 * mkinstalldirs:: `mkinstalldirs' at top level
9637 * aclocal:: `aclocal.m4' at top level
9638 * acconfig:: `acconfig.h' at top level
9639 * config.h.in:: `config.h.in' at top level
9640 * Makefile:: `Makefile.in' at top level
9641 * src/Makefile:: `Makefile.in' in `src/'
9642 * lib/gettext.h:: `gettext.h' in `lib/'
9645 File: gettext.info, Node: po/POTFILES.in, Next: po/LINGUAS, Prev: Adjusting Files, Up: Adjusting Files
9647 13.4.1 `POTFILES.in' in `po/'
9648 -----------------------------
9650 The `po/' directory should receive a file named `POTFILES.in'. This
9651 file tells which files, among all program sources, have marked strings
9652 needing translation. Here is an example of such a file:
9654 # List of source files containing translatable strings.
9655 # Copyright (C) 1995 Free Software Foundation, Inc.
9657 # Common library files
9662 # Package source files
9667 Hash-marked comments and white lines are ignored. All other lines list
9668 those source files containing strings marked for translation (*note
9669 Mark Keywords::), in a notation relative to the top level of your whole
9670 distribution, rather than the location of the `POTFILES.in' file itself.
9672 When a C file is automatically generated by a tool, like `flex' or
9673 `bison', that doesn't introduce translatable strings by itself, it is
9674 recommended to list in `po/POTFILES.in' the real source file (ending in
9675 `.l' in the case of `flex', or in `.y' in the case of `bison'), not the
9679 File: gettext.info, Node: po/LINGUAS, Next: po/Makevars, Prev: po/POTFILES.in, Up: Adjusting Files
9681 13.4.2 `LINGUAS' in `po/'
9682 -------------------------
9684 The `po/' directory should also receive a file named `LINGUAS'.
9685 This file contains the list of available translations. It is a
9686 whitespace separated list. Hash-marked comments and white lines are
9687 ignored. Here is an example file:
9689 # Set of available languages.
9692 This example means that German and French PO files are available, so
9693 that these languages are currently supported by your package. If you
9694 want to further restrict, at installation time, the set of installed
9695 languages, this should not be done by modifying the `LINGUAS' file, but
9696 rather by using the `LINGUAS' environment variable (*note Installers::).
9698 It is recommended that you add the "languages" `en@quot' and
9699 `en@boldquot' to the `LINGUAS' file. `en@quot' is a variant of English
9700 message catalogs (`en') which uses real quotation marks instead of the
9701 ugly looking asymmetric ASCII substitutes ``' and `''. `en@boldquot'
9702 is a variant of `en@quot' that additionally outputs quoted pieces of
9703 text in a bold font, when used in a terminal emulator which supports
9704 the VT100 escape sequences (such as `xterm' or the Linux console, but
9705 not Emacs in `M-x shell' mode).
9707 These extra message catalogs `en@quot' and `en@boldquot' are
9708 constructed automatically, not by translators; to support them, you
9709 need the files `Rules-quot', `quot.sed', `boldquot.sed',
9710 `en@quot.header', `en@boldquot.header', `insert-header.sin' in the
9711 `po/' directory. You can copy them from GNU gettext's `po/' directory;
9712 they are also installed by running `gettextize'.
9715 File: gettext.info, Node: po/Makevars, Next: po/Rules-*, Prev: po/LINGUAS, Up: Adjusting Files
9717 13.4.3 `Makevars' in `po/'
9718 --------------------------
9720 The `po/' directory also has a file named `Makevars'. It contains
9721 variables that are specific to your project. `po/Makevars' gets
9722 inserted into the `po/Makefile' when the latter is created. The
9723 variables thus take effect when the POT file is created or updated, and
9724 when the message catalogs get installed.
9726 The first three variables can be left unmodified if your package has
9727 a single message domain and, accordingly, a single `po/' directory.
9728 Only packages which have multiple `po/' directories at different
9729 locations need to adjust the three first variables defined in
9732 As an alternative to the `XGETTEXT_OPTIONS' variables, it is also
9733 possible to specify `xgettext' options through the `AM_XGETTEXT_OPTION'
9734 autoconf macro. See *note AM_XGETTEXT_OPTION::.
9737 File: gettext.info, Node: po/Rules-*, Next: configure.ac, Prev: po/Makevars, Up: Adjusting Files
9739 13.4.4 Extending `Makefile' in `po/'
9740 ------------------------------------
9742 All files called `Rules-*' in the `po/' directory get appended to
9743 the `po/Makefile' when it is created. They present an opportunity to
9744 add rules for special PO files to the Makefile, without needing to mess
9745 with `po/Makefile.in.in'.
9747 GNU gettext comes with a `Rules-quot' file, containing rules for
9748 building catalogs `en@quot.po' and `en@boldquot.po'. The effect of
9749 `en@quot.po' is that people who set their `LANGUAGE' environment
9750 variable to `en@quot' will get messages with proper looking symmetric
9751 Unicode quotation marks instead of abusing the ASCII grave accent and
9752 the ASCII apostrophe for indicating quotations. To enable this
9753 catalog, simply add `en@quot' to the `po/LINGUAS' file. The effect of
9754 `en@boldquot.po' is that people who set `LANGUAGE' to `en@boldquot'
9755 will get not only proper quotation marks, but also the quoted text will
9756 be shown in a bold font on terminals and consoles. This catalog is
9757 useful only for command-line programs, not GUI programs. To enable it,
9758 similarly add `en@boldquot' to the `po/LINGUAS' file.
9760 Similarly, you can create rules for building message catalogs for the
9761 `sr@latin' locale - Serbian written with the Latin alphabet - from
9762 those for the `sr' locale - Serbian written with Cyrillic letters. See
9763 *note msgfilter Invocation::.
9766 File: gettext.info, Node: configure.ac, Next: config.guess, Prev: po/Rules-*, Up: Adjusting Files
9768 13.4.5 `configure.ac' at top level
9769 ----------------------------------
9771 `configure.ac' or `configure.in' - this is the source from which
9772 `autoconf' generates the `configure' script.
9774 1. Declare the package and version.
9776 This is done by a set of lines like these:
9780 AC_DEFINE_UNQUOTED(PACKAGE, "$PACKAGE")
9781 AC_DEFINE_UNQUOTED(VERSION, "$VERSION")
9785 or, if you are using GNU `automake', by a line like this:
9787 AM_INIT_AUTOMAKE(gettext, 0.18.1)
9789 Of course, you replace `gettext' with the name of your package,
9790 and `0.18.1' by its version numbers, exactly as they should appear
9791 in the packaged `tar' file name of your distribution
9792 (`gettext-0.18.1.tar.gz', here).
9794 2. Check for internationalization support.
9796 Here is the main `m4' macro for triggering internationalization
9797 support. Just add this line to `configure.ac':
9801 This call is purposely simple, even if it generates a lot of
9802 configure time checking and actions.
9804 If you have suppressed the `intl/' subdirectory by calling
9805 `gettextize' without `--intl' option, this call should read
9807 AM_GNU_GETTEXT([external])
9809 3. Have output files created.
9811 The `AC_OUTPUT' directive, at the end of your `configure.ac' file,
9812 needs to be modified in two ways:
9814 AC_OUTPUT([EXISTING CONFIGURATION FILES intl/Makefile po/Makefile.in],
9815 [EXISTING ADDITIONAL ACTIONS])
9817 The modification to the first argument to `AC_OUTPUT' asks for
9818 substitution in the `intl/' and `po/' directories. Note the `.in'
9819 suffix used for `po/' only. This is because the distributed file
9820 is really `po/Makefile.in.in'.
9822 If you have suppressed the `intl/' subdirectory by calling
9823 `gettextize' without `--intl' option, then you don't need to add
9824 `intl/Makefile' to the `AC_OUTPUT' line.
9827 If, after doing the recommended modifications, a command like
9828 `aclocal -I m4' or `autoconf' or `autoreconf' fails with a trace
9831 configure.ac:44: warning: AC_COMPILE_IFELSE was called before AC_GNU_SOURCE
9832 ../../lib/autoconf/specific.m4:335: AC_GNU_SOURCE is expanded from...
9833 m4/lock.m4:224: gl_LOCK is expanded from...
9834 m4/gettext.m4:571: gt_INTL_SUBDIR_CORE is expanded from...
9835 m4/gettext.m4:472: AM_INTL_SUBDIR is expanded from...
9836 m4/gettext.m4:347: AM_GNU_GETTEXT is expanded from...
9837 configure.ac:44: the top level
9838 configure.ac:44: warning: AC_RUN_IFELSE was called before AC_GNU_SOURCE
9840 you need to add an explicit invocation of `AC_GNU_SOURCE' in the
9841 `configure.ac' file - after `AC_PROG_CC' but before `AM_GNU_GETTEXT',
9842 most likely very close to the `AC_PROG_CC' invocation. This is
9843 necessary because of ordering restrictions imposed by GNU autoconf.
9846 File: gettext.info, Node: config.guess, Next: mkinstalldirs, Prev: configure.ac, Up: Adjusting Files
9848 13.4.6 `config.guess', `config.sub' at top level
9849 ------------------------------------------------
9851 If you haven't suppressed the `intl/' subdirectory, you need to add
9852 the GNU `config.guess' and `config.sub' files to your distribution.
9853 They are needed because the `intl/' directory has platform dependent
9854 support for determining the locale's character encoding and therefore
9855 needs to identify the platform.
9857 You can obtain the newest version of `config.guess' and `config.sub'
9858 from the CVS of the `config' project at `http://savannah.gnu.org/'. The
9859 commands to fetch them are
9860 $ wget 'http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/config/config/config.guess'
9861 $ wget 'http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/config/config/config.sub'
9862 Less recent versions are also contained in the GNU `automake' and
9863 GNU `libtool' packages.
9865 Normally, `config.guess' and `config.sub' are put at the top level
9866 of a distribution. But it is also possible to put them in a
9867 subdirectory, altogether with other configuration support files like
9868 `install-sh', `ltconfig', `ltmain.sh' or `missing'. All you need to
9869 do, other than moving the files, is to add the following line to your
9872 AC_CONFIG_AUX_DIR([SUBDIR])
9875 File: gettext.info, Node: mkinstalldirs, Next: aclocal, Prev: config.guess, Up: Adjusting Files
9877 13.4.7 `mkinstalldirs' at top level
9878 -----------------------------------
9880 With earlier versions of GNU gettext, you needed to add the GNU
9881 `mkinstalldirs' script to your distribution. This is not needed any
9882 more. You can remove it if you not also using an automake version
9883 older than automake 1.9.
9886 File: gettext.info, Node: aclocal, Next: acconfig, Prev: mkinstalldirs, Up: Adjusting Files
9888 13.4.8 `aclocal.m4' at top level
9889 --------------------------------
9891 If you do not have an `aclocal.m4' file in your distribution, the
9892 simplest is to concatenate the files `codeset.m4', `fcntl-o.m4',
9893 `gettext.m4', `glibc2.m4', `glibc21.m4', `iconv.m4', `intdiv0.m4',
9894 `intl.m4', `intldir.m4', `intlmacosx.m4', `intmax.m4', `inttypes_h.m4',
9895 `inttypes-pri.m4', `lcmessage.m4', `lib-ld.m4', `lib-link.m4',
9896 `lib-prefix.m4', `lock.m4', `longlong.m4', `nls.m4', `po.m4',
9897 `printf-posix.m4', `progtest.m4', `size_max.m4', `stdint_h.m4',
9898 `threadlib.m4', `uintmax_t.m4', `visibility.m4', `wchar_t.m4',
9899 `wint_t.m4', `xsize.m4' from GNU `gettext''s `m4/' directory into a
9900 single file. If you have suppressed the `intl/' directory, only
9901 `gettext.m4', `iconv.m4', `lib-ld.m4', `lib-link.m4', `lib-prefix.m4',
9902 `nls.m4', `po.m4', `progtest.m4' need to be concatenated.
9904 If you are not using GNU `automake' 1.8 or newer, you will need to
9905 add a file `mkdirp.m4' from a newer automake distribution to the list
9908 If you already have an `aclocal.m4' file, then you will have to
9909 merge the said macro files into your `aclocal.m4'. Note that if you
9910 are upgrading from a previous release of GNU `gettext', you should most
9911 probably _replace_ the macros (`AM_GNU_GETTEXT', etc.), as they usually
9912 change a little from one release of GNU `gettext' to the next. Their
9913 contents may vary as we get more experience with strange systems out
9916 If you are using GNU `automake' 1.5 or newer, it is enough to put
9917 these macro files into a subdirectory named `m4/' and add the line
9919 ACLOCAL_AMFLAGS = -I m4
9921 to your top level `Makefile.am'.
9923 These macros check for the internationalization support functions
9924 and related informations. Hopefully, once stabilized, these macros
9925 might be integrated in the standard Autoconf set, because this piece of
9926 `m4' code will be the same for all projects using GNU `gettext'.
9929 File: gettext.info, Node: acconfig, Next: config.h.in, Prev: aclocal, Up: Adjusting Files
9931 13.4.9 `acconfig.h' at top level
9932 --------------------------------
9934 Earlier GNU `gettext' releases required to put definitions for
9935 `ENABLE_NLS', `HAVE_GETTEXT' and `HAVE_LC_MESSAGES', `HAVE_STPCPY',
9936 `PACKAGE' and `VERSION' into an `acconfig.h' file. This is not needed
9937 any more; you can remove them from your `acconfig.h' file unless your
9938 package uses them independently from the `intl/' directory.
9941 File: gettext.info, Node: config.h.in, Next: Makefile, Prev: acconfig, Up: Adjusting Files
9943 13.4.10 `config.h.in' at top level
9944 ----------------------------------
9946 The include file template that holds the C macros to be defined by
9947 `configure' is usually called `config.h.in' and may be maintained
9948 either manually or automatically.
9950 If `gettextize' has created an `intl/' directory, this file must be
9951 called `config.h.in' and must be at the top level. If, however, you
9952 have suppressed the `intl/' directory by calling `gettextize' without
9953 `--intl' option, then you can choose the name of this file and its
9956 If it is maintained automatically, by use of the `autoheader'
9957 program, you need to do nothing about it. This is the case in
9958 particular if you are using GNU `automake'.
9960 If it is maintained manually, and if `gettextize' has created an
9961 `intl/' directory, you should switch to using `autoheader'. The list
9962 of C macros to be added for the sake of the `intl/' directory is just
9963 too long to be maintained manually; it also changes between different
9964 versions of GNU `gettext'.
9966 If it is maintained manually, and if on the other hand you have
9967 suppressed the `intl/' directory by calling `gettextize' without
9968 `--intl' option, then you can get away by adding the following lines to
9971 /* Define to 1 if translation of program messages to the user's
9972 native language is requested. */
9976 File: gettext.info, Node: Makefile, Next: src/Makefile, Prev: config.h.in, Up: Adjusting Files
9978 13.4.11 `Makefile.in' at top level
9979 ----------------------------------
9981 Here are a few modifications you need to make to your main, top-level
9984 1. Add the following lines near the beginning of your `Makefile.in',
9985 so the `dist:' goal will work properly (as explained further down):
9990 2. Add file `ABOUT-NLS' to the `DISTFILES' definition, so the file
9993 3. Wherever you process subdirectories in your `Makefile.in', be sure
9994 you also process the subdirectories `intl' and `po'. Special
9995 rules in the `Makefiles' take care for the case where no
9996 internationalization is wanted.
9998 If you are using Makefiles, either generated by automake, or
9999 hand-written so they carefully follow the GNU coding standards,
10000 the effected goals for which the new subdirectories must be
10001 handled include `installdirs', `install', `uninstall', `clean',
10004 Here is an example of a canonical order of processing. In this
10005 example, we also define `SUBDIRS' in `Makefile.in' for it to be
10006 further used in the `dist:' goal.
10008 SUBDIRS = doc intl lib src po
10010 Note that you must arrange for `make' to descend into the `intl'
10011 directory before descending into other directories containing code
10012 which make use of the `libintl.h' header file. For this reason,
10013 here we mention `intl' before `lib' and `src'.
10015 4. A delicate point is the `dist:' goal, as both `intl/Makefile' and
10016 `po/Makefile' will later assume that the proper directory has been
10017 set up from the main `Makefile'. Here is an example at what the
10018 `dist:' goal might look like:
10020 distdir = $(PACKAGE)-$(VERSION)
10024 chmod 777 $(distdir)
10025 for file in $(DISTFILES); do \
10026 ln $$file $(distdir) 2>/dev/null || cp -p $$file $(distdir); \
10028 for subdir in $(SUBDIRS); do \
10029 mkdir $(distdir)/$$subdir || exit 1; \
10030 chmod 777 $(distdir)/$$subdir; \
10031 (cd $$subdir && $(MAKE) $@) || exit 1; \
10033 tar chozf $(distdir).tar.gz $(distdir)
10037 Note that if you are using GNU `automake', `Makefile.in' is
10038 automatically generated from `Makefile.am', and all needed changes to
10039 `Makefile.am' are already made by running `gettextize'.
10042 File: gettext.info, Node: src/Makefile, Next: lib/gettext.h, Prev: Makefile, Up: Adjusting Files
10044 13.4.12 `Makefile.in' in `src/'
10045 -------------------------------
10047 Some of the modifications made in the main `Makefile.in' will also
10048 be needed in the `Makefile.in' from your package sources, which we
10049 assume here to be in the `src/' subdirectory. Here are all the
10050 modifications needed in `src/Makefile.in':
10052 1. In view of the `dist:' goal, you should have these lines near the
10053 beginning of `src/Makefile.in':
10055 PACKAGE = @PACKAGE@
10056 VERSION = @VERSION@
10058 2. If not done already, you should guarantee that `top_srcdir' gets
10059 defined. This will serve for `cpp' include files. Just add the
10062 top_srcdir = @top_srcdir@
10064 3. You might also want to define `subdir' as `src', later allowing
10065 for almost uniform `dist:' goals in all your `Makefile.in'. At
10066 list, the `dist:' goal below assume that you used:
10070 4. The `main' function of your program will normally call
10071 `bindtextdomain' (see *note Triggering::), like this:
10073 bindtextdomain (PACKAGE, LOCALEDIR);
10074 textdomain (PACKAGE);
10076 To make LOCALEDIR known to the program, add the following lines to
10077 `Makefile.in' if you are using Autoconf version 2.60 or newer:
10079 datadir = @datadir@
10080 datarootdir= @datarootdir@
10081 localedir = @localedir@
10082 DEFS = -DLOCALEDIR=\"$(localedir)\" @DEFS@
10084 or these lines if your version of Autoconf is older than 2.60:
10086 datadir = @datadir@
10087 localedir = $(datadir)/locale
10088 DEFS = -DLOCALEDIR=\"$(localedir)\" @DEFS@
10090 Note that `@datadir@' defaults to `$(prefix)/share', thus
10091 `$(localedir)' defaults to `$(prefix)/share/locale'.
10093 5. You should ensure that the final linking will use `@LIBINTL@' or
10094 `@LTLIBINTL@' as a library. `@LIBINTL@' is for use without
10095 `libtool', `@LTLIBINTL@' is for use with `libtool'. An easy way
10096 to achieve this is to manage that it gets into `LIBS', like this:
10098 LIBS = @LIBINTL@ @LIBS@
10100 In most packages internationalized with GNU `gettext', one will
10101 find a directory `lib/' in which a library containing some helper
10102 functions will be build. (You need at least the few functions
10103 which the GNU `gettext' Library itself needs.) However some of
10104 the functions in the `lib/' also give messages to the user which
10105 of course should be translated, too. Taking care of this, the
10106 support library (say `libsupport.a') should be placed before
10107 `@LIBINTL@' and `@LIBS@' in the above example. So one has to
10110 LIBS = ../lib/libsupport.a @LIBINTL@ @LIBS@
10112 6. You should also ensure that directory `intl/' will be searched for
10113 C preprocessor include files in all circumstances. So, you have to
10114 manage so both `-I../intl' and `-I$(top_srcdir)/intl' will be
10115 given to the C compiler.
10117 7. Your `dist:' goal has to conform with others. Here is a
10118 reasonable definition for it:
10120 distdir = ../$(PACKAGE)-$(VERSION)/$(subdir)
10121 dist: Makefile $(DISTFILES)
10122 for file in $(DISTFILES); do \
10123 ln $$file $(distdir) 2>/dev/null || cp -p $$file $(distdir) || exit 1; \
10127 Note that if you are using GNU `automake', `Makefile.in' is
10128 automatically generated from `Makefile.am', and the first three changes
10129 and the last change are not necessary. The remaining needed
10130 `Makefile.am' modifications are the following:
10132 1. To make LOCALEDIR known to the program, add the following to
10135 <module>_CPPFLAGS = -DLOCALEDIR=\"$(localedir)\"
10137 for each specific module or compilation unit, or
10139 AM_CPPFLAGS = -DLOCALEDIR=\"$(localedir)\"
10141 for all modules and compilation units together. Furthermore, if
10142 you are using an Autoconf version older then 2.60, add this line
10143 to define `localedir':
10145 localedir = $(datadir)/locale
10147 2. To ensure that the final linking will use `@LIBINTL@' or
10148 `@LTLIBINTL@' as a library, add the following to `Makefile.am':
10150 <program>_LDADD = @LIBINTL@
10152 for each specific program, or
10156 for all programs together. Remember that when you use `libtool'
10157 to link a program, you need to use @LTLIBINTL@ instead of @LIBINTL@
10160 3. If you have an `intl/' directory, whose contents is created by
10161 `gettextize', then to ensure that it will be searched for C
10162 preprocessor include files in all circumstances, add something like
10163 this to `Makefile.am':
10165 AM_CPPFLAGS = -I../intl -I$(top_srcdir)/intl
10169 File: gettext.info, Node: lib/gettext.h, Prev: src/Makefile, Up: Adjusting Files
10171 13.4.13 `gettext.h' in `lib/'
10172 -----------------------------
10174 Internationalization of packages, as provided by GNU `gettext', is
10175 optional. It can be turned off in two situations:
10177 * When the installer has specified `./configure --disable-nls'. This
10178 can be useful when small binaries are more important than
10179 features, for example when building utilities for boot diskettes.
10180 It can also be useful in order to get some specific C compiler
10181 warnings about code quality with some older versions of GCC (older
10184 * When the package does not include the `intl/' subdirectory, and the
10185 libintl.h header (with its associated libintl library, if any) is
10186 not already installed on the system, it is preferable that the
10187 package builds without internationalization support, rather than
10188 to give a compilation error.
10190 A C preprocessor macro can be used to detect these two cases.
10191 Usually, when `libintl.h' was found and not explicitly disabled, the
10192 `ENABLE_NLS' macro will be defined to 1 in the autoconf generated
10193 configuration file (usually called `config.h'). In the two negative
10194 situations, however, this macro will not be defined, thus it will
10195 evaluate to 0 in C preprocessor expressions.
10197 `gettext.h' is a convenience header file for conditional use of
10198 `<libintl.h>', depending on the `ENABLE_NLS' macro. If `ENABLE_NLS' is
10199 set, it includes `<libintl.h>'; otherwise it defines no-op substitutes
10200 for the libintl.h functions. We recommend the use of `"gettext.h"'
10201 over direct use of `<libintl.h>', so that portability to older systems
10202 is guaranteed and installers can turn off internationalization if they
10203 want to. In the C code, you will then write
10205 #include "gettext.h"
10209 #include <libintl.h>
10211 The location of `gettext.h' is usually in a directory containing
10212 auxiliary include files. In many GNU packages, there is a directory
10213 `lib/' containing helper functions; `gettext.h' fits there. In other
10214 packages, it can go into the `src' directory.
10216 Do not install the `gettext.h' file in public locations. Every
10217 package that needs it should contain a copy of it on its own.
10220 File: gettext.info, Node: autoconf macros, Next: CVS Issues, Prev: Adjusting Files, Up: Maintainers
10222 13.5 Autoconf macros for use in `configure.ac'
10223 ==============================================
10225 GNU `gettext' installs macros for use in a package's `configure.ac'
10226 or `configure.in'. *Note Introduction: (autoconf)Top. The primary
10227 macro is, of course, `AM_GNU_GETTEXT'.
10231 * AM_GNU_GETTEXT:: AM_GNU_GETTEXT in `gettext.m4'
10232 * AM_GNU_GETTEXT_VERSION:: AM_GNU_GETTEXT_VERSION in `gettext.m4'
10233 * AM_GNU_GETTEXT_NEED:: AM_GNU_GETTEXT_NEED in `gettext.m4'
10234 * AM_GNU_GETTEXT_INTL_SUBDIR:: AM_GNU_GETTEXT_INTL_SUBDIR in `intldir.m4'
10235 * AM_PO_SUBDIRS:: AM_PO_SUBDIRS in `po.m4'
10236 * AM_XGETTEXT_OPTION:: AM_XGETTEXT_OPTION in `po.m4'
10237 * AM_ICONV:: AM_ICONV in `iconv.m4'
10240 File: gettext.info, Node: AM_GNU_GETTEXT, Next: AM_GNU_GETTEXT_VERSION, Prev: autoconf macros, Up: autoconf macros
10242 13.5.1 AM_GNU_GETTEXT in `gettext.m4'
10243 -------------------------------------
10245 The `AM_GNU_GETTEXT' macro tests for the presence of the GNU gettext
10246 function family in either the C library or a separate `libintl' library
10247 (shared or static libraries are both supported) or in the package's
10248 `intl/' directory. It also invokes `AM_PO_SUBDIRS', thus preparing the
10249 `po/' directories of the package for building.
10251 `AM_GNU_GETTEXT' accepts up to three optional arguments. The general
10254 AM_GNU_GETTEXT([INTLSYMBOL], [NEEDSYMBOL], [INTLDIR])
10256 INTLSYMBOL can be `external' or `no-libtool'. The default (if it is
10257 not specified or empty) is `no-libtool'. INTLSYMBOL should be
10258 `external' for packages with no `intl/' directory. For packages with
10259 an `intl/' directory, you can either use an INTLSYMBOL equal to
10260 `no-libtool', or you can use `external' and override by using the macro
10261 `AM_GNU_GETTEXT_INTL_SUBDIR' elsewhere. The two ways to specify the
10262 existence of an `intl/' directory are equivalent. At build time, a
10263 static library `$(top_builddir)/intl/libintl.a' will then be created.
10265 If NEEDSYMBOL is specified and is `need-ngettext', then GNU gettext
10266 implementations (in libc or libintl) without the `ngettext()' function
10267 will be ignored. If NEEDSYMBOL is specified and is
10268 `need-formatstring-macros', then GNU gettext implementations that don't
10269 support the ISO C 99 `<inttypes.h>' formatstring macros will be ignored.
10270 Only one NEEDSYMBOL can be specified. These requirements can also be
10271 specified by using the macro `AM_GNU_GETTEXT_NEED' elsewhere. To
10272 specify more than one requirement, just specify the strongest one among
10273 them, or invoke the `AM_GNU_GETTEXT_NEED' macro several times. The
10274 hierarchy among the various alternatives is as follows:
10275 `need-formatstring-macros' implies `need-ngettext'.
10277 INTLDIR is used to find the intl libraries. If empty, the value
10278 `$(top_builddir)/intl/' is used.
10280 The `AM_GNU_GETTEXT' macro determines whether GNU gettext is
10281 available and should be used. If so, it sets the `USE_NLS' variable to
10282 `yes'; it defines `ENABLE_NLS' to 1 in the autoconf generated
10283 configuration file (usually called `config.h'); it sets the variables
10284 `LIBINTL' and `LTLIBINTL' to the linker options for use in a Makefile
10285 (`LIBINTL' for use without libtool, `LTLIBINTL' for use with libtool);
10286 it adds an `-I' option to `CPPFLAGS' if necessary. In the negative
10287 case, it sets `USE_NLS' to `no'; it sets `LIBINTL' and `LTLIBINTL' to
10288 empty and doesn't change `CPPFLAGS'.
10290 The complexities that `AM_GNU_GETTEXT' deals with are the following:
10292 * Some operating systems have `gettext' in the C library, for example
10293 glibc. Some have it in a separate library `libintl'. GNU
10294 `libintl' might have been installed as part of the GNU `gettext'
10297 * GNU `libintl', if installed, is not necessarily already in the
10298 search path (`CPPFLAGS' for the include file search path,
10299 `LDFLAGS' for the library search path).
10301 * Except for glibc, the operating system's native `gettext' cannot
10302 exploit the GNU mo files, doesn't have the necessary locale
10303 dependency features, and cannot convert messages from the
10304 catalog's text encoding to the user's locale encoding.
10306 * GNU `libintl', if installed, is not necessarily already in the run
10307 time library search path. To avoid the need for setting an
10308 environment variable like `LD_LIBRARY_PATH', the macro adds the
10309 appropriate run time search path options to the `LIBINTL' and
10310 `LTLIBINTL' variables. This works on most systems, but not on
10311 some operating systems with limited shared library support, like
10314 * GNU `libintl' relies on POSIX/XSI `iconv'. The macro checks for
10315 linker options needed to use iconv and appends them to the
10316 `LIBINTL' and `LTLIBINTL' variables.
10319 File: gettext.info, Node: AM_GNU_GETTEXT_VERSION, Next: AM_GNU_GETTEXT_NEED, Prev: AM_GNU_GETTEXT, Up: autoconf macros
10321 13.5.2 AM_GNU_GETTEXT_VERSION in `gettext.m4'
10322 ---------------------------------------------
10324 The `AM_GNU_GETTEXT_VERSION' macro declares the version number of
10325 the GNU gettext infrastructure that is used by the package.
10327 The use of this macro is optional; only the `autopoint' program makes
10328 use of it (*note CVS Issues::).
10331 File: gettext.info, Node: AM_GNU_GETTEXT_NEED, Next: AM_GNU_GETTEXT_INTL_SUBDIR, Prev: AM_GNU_GETTEXT_VERSION, Up: autoconf macros
10333 13.5.3 AM_GNU_GETTEXT_NEED in `gettext.m4'
10334 ------------------------------------------
10336 The `AM_GNU_GETTEXT_NEED' macro declares a constraint regarding the
10337 GNU gettext implementation. The syntax is
10339 AM_GNU_GETTEXT_NEED([NEEDSYMBOL])
10341 If NEEDSYMBOL is `need-ngettext', then GNU gettext implementations
10342 (in libc or libintl) without the `ngettext()' function will be ignored.
10343 If NEEDSYMBOL is `need-formatstring-macros', then GNU gettext
10344 implementations that don't support the ISO C 99 `<inttypes.h>'
10345 formatstring macros will be ignored.
10347 The optional second argument of `AM_GNU_GETTEXT' is also taken into
10350 The `AM_GNU_GETTEXT_NEED' invocations can occur before or after the
10351 `AM_GNU_GETTEXT' invocation; the order doesn't matter.
10354 File: gettext.info, Node: AM_GNU_GETTEXT_INTL_SUBDIR, Next: AM_PO_SUBDIRS, Prev: AM_GNU_GETTEXT_NEED, Up: autoconf macros
10356 13.5.4 AM_GNU_GETTEXT_INTL_SUBDIR in `intldir.m4'
10357 -------------------------------------------------
10359 The `AM_GNU_GETTEXT_INTL_SUBDIR' macro specifies that the
10360 `AM_GNU_GETTEXT' macro, although invoked with the first argument
10361 `external', should also prepare for building the `intl/' subdirectory.
10363 The `AM_GNU_GETTEXT_INTL_SUBDIR' invocation can occur before or after
10364 the `AM_GNU_GETTEXT' invocation; the order doesn't matter.
10366 The use of this macro requires GNU automake 1.10 or newer and GNU
10367 autoconf 2.61 or newer.
10370 File: gettext.info, Node: AM_PO_SUBDIRS, Next: AM_XGETTEXT_OPTION, Prev: AM_GNU_GETTEXT_INTL_SUBDIR, Up: autoconf macros
10372 13.5.5 AM_PO_SUBDIRS in `po.m4'
10373 -------------------------------
10375 The `AM_PO_SUBDIRS' macro prepares the `po/' directories of the
10376 package for building. This macro should be used in internationalized
10377 programs written in other programming languages than C, C++, Objective
10378 C, for example `sh', `Python', `Lisp'. See *note Programming
10379 Languages:: for a list of programming languages that support
10380 localization through PO files.
10382 The `AM_PO_SUBDIRS' macro determines whether internationalization
10383 should be used. If so, it sets the `USE_NLS' variable to `yes',
10384 otherwise to `no'. It also determines the right values for Makefile
10385 variables in each `po/' directory.
10388 File: gettext.info, Node: AM_XGETTEXT_OPTION, Next: AM_ICONV, Prev: AM_PO_SUBDIRS, Up: autoconf macros
10390 13.5.6 AM_XGETTEXT_OPTION in `po.m4'
10391 ------------------------------------
10393 The `AM_XGETTEXT_OPTION' macro registers a command-line option to be
10394 used in the invocations of `xgettext' in the `po/' directories of the
10397 For example, if you have a source file that defines a function
10398 `error_at_line' whose fifth argument is a format string, you can use
10399 AM_XGETTEXT_OPTION([--flag=error_at_line:5:c-format])
10400 to instruct `xgettext' to mark all translatable strings in `gettext'
10401 invocations that occur as fifth argument to this function as `c-format'.
10403 See *note xgettext Invocation:: for the list of options that
10404 `xgettext' accepts.
10406 The use of this macro is an alternative to the use of the
10407 `XGETTEXT_OPTIONS' variable in `po/Makevars'.
10410 File: gettext.info, Node: AM_ICONV, Prev: AM_XGETTEXT_OPTION, Up: autoconf macros
10412 13.5.7 AM_ICONV in `iconv.m4'
10413 -----------------------------
10415 The `AM_ICONV' macro tests for the presence of the POSIX/XSI `iconv'
10416 function family in either the C library or a separate `libiconv'
10417 library. If found, it sets the `am_cv_func_iconv' variable to `yes';
10418 it defines `HAVE_ICONV' to 1 in the autoconf generated configuration
10419 file (usually called `config.h'); it defines `ICONV_CONST' to `const'
10420 or to empty, depending on whether the second argument of `iconv()' is
10421 of type `const char **' or `char **'; it sets the variables `LIBICONV'
10422 and `LTLIBICONV' to the linker options for use in a Makefile
10423 (`LIBICONV' for use without libtool, `LTLIBICONV' for use with
10424 libtool); it adds an `-I' option to `CPPFLAGS' if necessary. If not
10425 found, it sets `LIBICONV' and `LTLIBICONV' to empty and doesn't change
10428 The complexities that `AM_ICONV' deals with are the following:
10430 * Some operating systems have `iconv' in the C library, for example
10431 glibc. Some have it in a separate library `libiconv', for example
10432 OSF/1 or FreeBSD. Regardless of the operating system, GNU
10433 `libiconv' might have been installed. In that case, it should be
10434 used instead of the operating system's native `iconv'.
10436 * GNU `libiconv', if installed, is not necessarily already in the
10437 search path (`CPPFLAGS' for the include file search path,
10438 `LDFLAGS' for the library search path).
10440 * GNU `libiconv' is binary incompatible with some operating system's
10441 native `iconv', for example on FreeBSD. Use of an `iconv.h' and
10442 `libiconv.so' that don't fit together would produce program
10445 * GNU `libiconv', if installed, is not necessarily already in the
10446 run time library search path. To avoid the need for setting an
10447 environment variable like `LD_LIBRARY_PATH', the macro adds the
10448 appropriate run time search path options to the `LIBICONV'
10449 variable. This works on most systems, but not on some operating
10450 systems with limited shared library support, like SCO.
10452 `iconv.m4' is distributed with the GNU gettext package because
10453 `gettext.m4' relies on it.
10456 File: gettext.info, Node: CVS Issues, Next: Release Management, Prev: autoconf macros, Up: Maintainers
10458 13.6 Integrating with CVS
10459 =========================
10461 Many projects use CVS for distributed development, version control
10462 and source backup. This section gives some advice how to manage the
10463 uses of `cvs', `gettextize', `autopoint' and `autoconf'.
10467 * Distributed CVS:: Avoiding version mismatch in distributed development
10468 * Files under CVS:: Files to put under CVS version control
10469 * autopoint Invocation:: Invoking the `autopoint' Program
10472 File: gettext.info, Node: Distributed CVS, Next: Files under CVS, Prev: CVS Issues, Up: CVS Issues
10474 13.6.1 Avoiding version mismatch in distributed development
10475 -----------------------------------------------------------
10477 In a project development with multiple developers, using CVS, there
10478 should be a single developer who occasionally - when there is desire to
10479 upgrade to a new `gettext' version - runs `gettextize' and performs the
10480 changes listed in *note Adjusting Files::, and then commits his changes
10483 It is highly recommended that all developers on a project use the
10484 same version of GNU `gettext' in the package. In other words, if a
10485 developer runs `gettextize', he should go the whole way, make the
10486 necessary remaining changes and commit his changes to the CVS.
10487 Otherwise the following damages will likely occur:
10489 * Apparent version mismatch between developers. Since some `gettext'
10490 specific portions in `configure.ac', `configure.in' and
10491 `Makefile.am', `Makefile.in' files depend on the `gettext'
10492 version, the use of infrastructure files belonging to different
10493 `gettext' versions can easily lead to build errors.
10495 * Hidden version mismatch. Such version mismatch can also lead to
10496 malfunctioning of the package, that may be undiscovered by the
10497 developers. The worst case of hidden version mismatch is that
10498 internationalization of the package doesn't work at all.
10500 * Release risks. All developers implicitly perform constant testing
10501 on a package. This is important in the days and weeks before a
10502 release. If the guy who makes the release tar files uses a
10503 different version of GNU `gettext' than the other developers, the
10504 distribution will be less well tested than if all had been using
10505 the same `gettext' version. For example, it is possible that a
10506 platform specific bug goes undiscovered due to this constellation.
10509 File: gettext.info, Node: Files under CVS, Next: autopoint Invocation, Prev: Distributed CVS, Up: CVS Issues
10511 13.6.2 Files to put under CVS version control
10512 ---------------------------------------------
10514 There are basically three ways to deal with generated files in the
10515 context of a CVS repository, such as `configure' generated from
10516 `configure.ac', `PARSER.c' generated from `PARSER.y', or
10517 `po/Makefile.in.in' autoinstalled by `gettextize' or `autopoint'.
10519 1. All generated files are always committed into the repository.
10521 2. All generated files are committed into the repository occasionally,
10522 for example each time a release is made.
10524 3. Generated files are never committed into the repository.
10526 Each of these three approaches has different advantages and
10529 1. The advantage is that anyone can check out the CVS at any moment
10530 and gets a working build. The drawbacks are: 1a. It requires
10531 some frequent "cvs commit" actions by the maintainers. 1b. The
10532 repository grows in size quite fast.
10534 2. The advantage is that anyone can check out the CVS, and the usual
10535 "./configure; make" will work. The drawbacks are: 2a. The one who
10536 checks out the repository needs tools like GNU `automake', GNU
10537 `autoconf', GNU `m4' installed in his PATH; sometimes he even
10538 needs particular versions of them. 2b. When a release is made and
10539 a commit is made on the generated files, the other developers get
10540 conflicts on the generated files after doing "cvs update".
10541 Although these conflicts are easy to resolve, they are annoying.
10543 3. The advantage is less work for the maintainers. The drawback is
10544 that anyone who checks out the CVS not only needs tools like GNU
10545 `automake', GNU `autoconf', GNU `m4' installed in his PATH, but
10546 also that he needs to perform a package specific pre-build step
10547 before being able to "./configure; make".
10549 For the first and second approach, all files modified or brought in
10550 by the occasional `gettextize' invocation and update should be
10551 committed into the CVS.
10553 For the third approach, the maintainer can omit from the CVS
10554 repository all the files that `gettextize' mentions as "copy".
10555 Instead, he adds to the `configure.ac' or `configure.in' a line of the
10558 AM_GNU_GETTEXT_VERSION(0.18.1)
10560 and adds to the package's pre-build script an invocation of
10561 `autopoint'. For everyone who checks out the CVS, this `autopoint'
10562 invocation will copy into the right place the `gettext' infrastructure
10563 files that have been omitted from the CVS.
10565 The version number used as argument to `AM_GNU_GETTEXT_VERSION' is
10566 the version of the `gettext' infrastructure that the package wants to
10567 use. It is also the minimum version number of the `autopoint' program.
10568 So, if you write `AM_GNU_GETTEXT_VERSION(0.11.5)' then the developers
10569 can have any version >= 0.11.5 installed; the package will work with
10570 the 0.11.5 infrastructure in all developers' builds. When the
10571 maintainer then runs gettextize from, say, version 0.12.1 on the
10572 package, the occurrence of `AM_GNU_GETTEXT_VERSION(0.11.5)' will be
10573 changed into `AM_GNU_GETTEXT_VERSION(0.12.1)', and all other developers
10574 that use the CVS will henceforth need to have GNU `gettext' 0.12.1 or
10578 File: gettext.info, Node: autopoint Invocation, Prev: Files under CVS, Up: CVS Issues
10580 13.6.3 Invoking the `autopoint' Program
10581 ---------------------------------------
10583 autopoint [OPTION]...
10585 The `autopoint' program copies standard gettext infrastructure files
10586 into a source package. It extracts from a macro call of the form
10587 `AM_GNU_GETTEXT_VERSION(VERSION)', found in the package's
10588 `configure.in' or `configure.ac' file, the gettext version used by the
10589 package, and copies the infrastructure files belonging to this version
10597 Force overwriting of files that already exist.
10601 Print modifications but don't perform them. All file copying
10602 actions that `autopoint' would normally execute are inhibited and
10603 instead only listed on standard output.
10606 13.6.3.2 Informative output
10607 ...........................
10610 Display this help and exit.
10613 Output version information and exit.
10616 `autopoint' supports the GNU `gettext' versions from 0.10.35 to the
10617 current one, 0.18.1. In order to apply `autopoint' to a package using
10618 a `gettext' version newer than 0.18.1, you need to install this same
10619 version of GNU `gettext' at least.
10621 In packages using GNU `automake', an invocation of `autopoint'
10622 should be followed by invocations of `aclocal' and then `autoconf' and
10623 `autoheader'. The reason is that `autopoint' installs some autoconf
10624 macro files, which are used by `aclocal' to create `aclocal.m4', and
10625 the latter is used by `autoconf' to create the package's `configure'
10626 script and by `autoheader' to create the package's `config.h.in'
10627 include file template.
10629 The name `autopoint' is an abbreviation of `auto-po-intl-m4'; the
10630 tool copies or updates mostly files in the `po', `intl', `m4'
10634 File: gettext.info, Node: Release Management, Prev: CVS Issues, Up: Maintainers
10636 13.7 Creating a Distribution Tarball
10637 ====================================
10639 In projects that use GNU `automake', the usual commands for creating
10640 a distribution tarball, `make dist' or `make distcheck', automatically
10641 update the PO files as needed.
10643 If GNU `automake' is not used, the maintainer needs to perform this
10644 update before making a release:
10647 $ (cd po; make update-po)
10651 File: gettext.info, Node: Installers, Next: Programming Languages, Prev: Maintainers, Up: Top
10653 14 The Installer's and Distributor's View
10654 *****************************************
10656 By default, packages fully using GNU `gettext', internally, are
10657 installed in such a way that they to allow translation of messages. At
10658 _configuration_ time, those packages should automatically detect
10659 whether the underlying host system already provides the GNU `gettext'
10660 functions. If not, the GNU `gettext' library should be automatically
10661 prepared and used. Installers may use special options at configuration
10662 time for changing this behavior. The command `./configure
10663 --with-included-gettext' bypasses system `gettext' to use the included
10664 GNU `gettext' instead, while `./configure --disable-nls' produces
10665 programs totally unable to translate messages.
10667 Internationalized packages have usually many `LL.po' files. Unless
10668 translations are disabled, all those available are installed together
10669 with the package. However, the environment variable `LINGUAS' may be
10670 set, prior to configuration, to limit the installed set. `LINGUAS'
10671 should then contain a space separated list of two-letter codes, stating
10672 which languages are allowed.
10675 File: gettext.info, Node: Programming Languages, Next: Conclusion, Prev: Installers, Up: Top
10677 15 Other Programming Languages
10678 ******************************
10680 While the presentation of `gettext' focuses mostly on C and
10681 implicitly applies to C++ as well, its scope is far broader than that:
10682 Many programming languages, scripting languages and other textual data
10683 like GUI resources or package descriptions can make use of the gettext
10688 * Language Implementors:: The Language Implementor's View
10689 * Programmers for other Languages:: The Programmer's View
10690 * Translators for other Languages:: The Translator's View
10691 * Maintainers for other Languages:: The Maintainer's View
10692 * List of Programming Languages:: Individual Programming Languages
10693 * List of Data Formats:: Internationalizable Data
10696 File: gettext.info, Node: Language Implementors, Next: Programmers for other Languages, Prev: Programming Languages, Up: Programming Languages
10698 15.1 The Language Implementor's View
10699 ====================================
10701 All programming and scripting languages that have the notion of
10702 strings are eligible to supporting `gettext'. Supporting `gettext'
10703 means the following:
10705 1. You should add to the language a syntax for translatable strings.
10706 In principle, a function call of `gettext' would do, but a
10707 shorthand syntax helps keeping the legibility of internationalized
10708 programs. For example, in C we use the syntax `_("string")', and
10709 in GNU awk we use the shorthand `_"string"'.
10711 2. You should arrange that evaluation of such a translatable string at
10712 runtime calls the `gettext' function, or performs equivalent
10715 3. Similarly, you should make the functions `ngettext', `dcgettext',
10716 `dcngettext' available from within the language. These functions
10717 are less often used, but are nevertheless necessary for particular
10718 purposes: `ngettext' for correct plural handling, and `dcgettext'
10719 and `dcngettext' for obeying other locale-related environment
10720 variables than `LC_MESSAGES', such as `LC_TIME' or `LC_MONETARY'.
10721 For these latter functions, you need to make the `LC_*' constants,
10722 available in the C header `<locale.h>', referenceable from within
10723 the language, usually either as enumeration values or as strings.
10725 4. You should allow the programmer to designate a message domain,
10726 either by making the `textdomain' function available from within
10727 the language, or by introducing a magic variable called
10728 `TEXTDOMAIN'. Similarly, you should allow the programmer to
10729 designate where to search for message catalogs, by providing
10730 access to the `bindtextdomain' function.
10732 5. You should either perform a `setlocale (LC_ALL, "")' call during
10733 the startup of your language runtime, or allow the programmer to
10734 do so. Remember that gettext will act as a no-op if the
10735 `LC_MESSAGES' and `LC_CTYPE' locale categories are not both set.
10737 6. A programmer should have a way to extract translatable strings
10738 from a program into a PO file. The GNU `xgettext' program is being
10739 extended to support very different programming languages. Please
10740 contact the GNU `gettext' maintainers to help them doing this. If
10741 the string extractor is best integrated into your language's
10742 parser, GNU `xgettext' can function as a front end to your string
10745 7. The language's library should have a string formatting facility
10746 where the arguments of a format string are denoted by a positional
10747 number or a name. This is needed because for some languages and
10748 some messages with more than one substitutable argument, the
10749 translation will need to output the substituted arguments in
10750 different order. *Note c-format Flag::.
10752 8. If the language has more than one implementation, and not all of
10753 the implementations use `gettext', but the programs should be
10754 portable across implementations, you should provide a no-i18n
10755 emulation, that makes the other implementations accept programs
10756 written for yours, without actually translating the strings.
10758 9. To help the programmer in the task of marking translatable strings,
10759 which is sometimes performed using the Emacs PO mode (*note
10760 Marking::), you are welcome to contact the GNU `gettext'
10761 maintainers, so they can add support for your language to
10764 On the implementation side, three approaches are possible, with
10765 different effects on portability and copyright:
10767 * You may integrate the GNU `gettext''s `intl/' directory in your
10768 package, as described in *note Maintainers::. This allows you to
10769 have internationalization on all kinds of platforms. Note that
10770 when you then distribute your package, it legally falls under the
10771 GNU General Public License, and the GNU project will be glad about
10772 your contribution to the Free Software pool.
10774 * You may link against GNU `gettext' functions if they are found in
10775 the C library. For example, an autoconf test for `gettext()' and
10776 `ngettext()' will detect this situation. For the moment, this test
10777 will succeed on GNU systems and not on other platforms. No severe
10778 copyright restrictions apply.
10780 * You may emulate or reimplement the GNU `gettext' functionality.
10781 This has the advantage of full portability and no copyright
10782 restrictions, but also the drawback that you have to reimplement
10783 the GNU `gettext' features (such as the `LANGUAGE' environment
10784 variable, the locale aliases database, the automatic charset
10785 conversion, and plural handling).
10788 File: gettext.info, Node: Programmers for other Languages, Next: Translators for other Languages, Prev: Language Implementors, Up: Programming Languages
10790 15.2 The Programmer's View
10791 ==========================
10793 For the programmer, the general procedure is the same as for the C
10794 language. The Emacs PO mode marking supports other languages, and the
10795 GNU `xgettext' string extractor recognizes other languages based on the
10796 file extension or a command-line option. In some languages,
10797 `setlocale' is not needed because it is already performed by the
10798 underlying language runtime.
10801 File: gettext.info, Node: Translators for other Languages, Next: Maintainers for other Languages, Prev: Programmers for other Languages, Up: Programming Languages
10803 15.3 The Translator's View
10804 ==========================
10806 The translator works exactly as in the C language case. The only
10807 difference is that when translating format strings, she has to be aware
10808 of the language's particular syntax for positional arguments in format
10813 * c-format:: C Format Strings
10814 * objc-format:: Objective C Format Strings
10815 * sh-format:: Shell Format Strings
10816 * python-format:: Python Format Strings
10817 * lisp-format:: Lisp Format Strings
10818 * elisp-format:: Emacs Lisp Format Strings
10819 * librep-format:: librep Format Strings
10820 * scheme-format:: Scheme Format Strings
10821 * smalltalk-format:: Smalltalk Format Strings
10822 * java-format:: Java Format Strings
10823 * csharp-format:: C# Format Strings
10824 * awk-format:: awk Format Strings
10825 * object-pascal-format:: Object Pascal Format Strings
10826 * ycp-format:: YCP Format Strings
10827 * tcl-format:: Tcl Format Strings
10828 * perl-format:: Perl Format Strings
10829 * php-format:: PHP Format Strings
10830 * gcc-internal-format:: GCC internal Format Strings
10831 * gfc-internal-format:: GFC internal Format Strings
10832 * qt-format:: Qt Format Strings
10833 * qt-plural-format:: Qt Plural Format Strings
10834 * kde-format:: KDE Format Strings
10835 * boost-format:: Boost Format Strings
10838 File: gettext.info, Node: c-format, Next: objc-format, Prev: Translators for other Languages, Up: Translators for other Languages
10840 15.3.1 C Format Strings
10841 -----------------------
10843 C format strings are described in POSIX (IEEE P1003.1 2001), section
10845 `http://www.opengroup.org/onlinepubs/007904975/functions/fprintf.html'.
10846 See also the fprintf() manual page,
10847 `http://www.linuxvalley.it/encyclopedia/ldp/manpage/man3/printf.3.php',
10848 `http://informatik.fh-wuerzburg.de/student/i510/man/printf.html'.
10850 Although format strings with positions that reorder arguments, such
10853 "Only %2$d bytes free on '%1$s'."
10855 which is semantically equivalent to
10857 "'%s' has only %d bytes free."
10859 are a POSIX/XSI feature and not specified by ISO C 99, translators can
10860 rely on this reordering ability: On the few platforms where `printf()',
10861 `fprintf()' etc. don't support this feature natively, `libintl.a' or
10862 `libintl.so' provides replacement functions, and GNU `<libintl.h>'
10863 activates these replacement functions automatically.
10865 As a special feature for Farsi (Persian) and maybe Arabic,
10866 translators can insert an `I' flag into numeric format directives. For
10867 example, the translation of `"%d"' can be `"%Id"'. The effect of this
10868 flag, on systems with GNU `libc', is that in the output, the ASCII
10869 digits are replaced with the `outdigits' defined in the `LC_CTYPE'
10870 locale category. On other systems, the `gettext' function removes this
10871 flag, so that it has no effect.
10873 Note that the programmer should _not_ put this flag into the
10874 untranslated string. (Putting the `I' format directive flag into an
10875 MSGID string would lead to undefined behaviour on platforms without
10876 glibc when NLS is disabled.)
10879 File: gettext.info, Node: objc-format, Next: sh-format, Prev: c-format, Up: Translators for other Languages
10881 15.3.2 Objective C Format Strings
10882 ---------------------------------
10884 Objective C format strings are like C format strings. They support
10885 an additional format directive: "%@", which when executed consumes an
10886 argument of type `Object *'.
10889 File: gettext.info, Node: sh-format, Next: python-format, Prev: objc-format, Up: Translators for other Languages
10891 15.3.3 Shell Format Strings
10892 ---------------------------
10894 Shell format strings, as supported by GNU gettext and the `envsubst'
10895 program, are strings with references to shell variables in the form
10896 `$VARIABLE' or `${VARIABLE}'. References of the form
10897 `${VARIABLE-DEFAULT}', `${VARIABLE:-DEFAULT}', `${VARIABLE=DEFAULT}',
10898 `${VARIABLE:=DEFAULT}', `${VARIABLE+REPLACEMENT}',
10899 `${VARIABLE:+REPLACEMENT}', `${VARIABLE?IGNORED}',
10900 `${VARIABLE:?IGNORED}', that would be valid inside shell scripts, are
10901 not supported. The VARIABLE names must consist solely of alphanumeric
10902 or underscore ASCII characters, not start with a digit and be nonempty;
10903 otherwise such a variable reference is ignored.
10906 File: gettext.info, Node: python-format, Next: lisp-format, Prev: sh-format, Up: Translators for other Languages
10908 15.3.4 Python Format Strings
10909 ----------------------------
10911 Python format strings are described in Python Library reference /
10912 2. Built-in Types, Exceptions and Functions / 2.2. Built-in Types /
10913 2.2.6. Sequence Types / 2.2.6.2. String Formatting Operations.
10914 `http://www.python.org/doc/2.2.1/lib/typesseq-strings.html'.
10917 File: gettext.info, Node: lisp-format, Next: elisp-format, Prev: python-format, Up: Translators for other Languages
10919 15.3.5 Lisp Format Strings
10920 --------------------------
10922 Lisp format strings are described in the Common Lisp HyperSpec,
10923 chapter 22.3 Formatted Output,
10924 `http://www.lisp.org/HyperSpec/Body/sec_22-3.html'.
10927 File: gettext.info, Node: elisp-format, Next: librep-format, Prev: lisp-format, Up: Translators for other Languages
10929 15.3.6 Emacs Lisp Format Strings
10930 --------------------------------
10932 Emacs Lisp format strings are documented in the Emacs Lisp reference,
10933 section Formatting Strings,
10934 `http://www.gnu.org/manual/elisp-manual-21-2.8/html_chapter/elisp_4.html#SEC75'.
10935 Note that as of version 21, XEmacs supports numbered argument
10936 specifications in format strings while FSF Emacs doesn't.
10939 File: gettext.info, Node: librep-format, Next: scheme-format, Prev: elisp-format, Up: Translators for other Languages
10941 15.3.7 librep Format Strings
10942 ----------------------------
10944 librep format strings are documented in the librep manual, section
10946 `http://librep.sourceforge.net/librep-manual.html#Formatted%20Output',
10947 `http://www.gwinnup.org/research/docs/librep.html#SEC122'.
10950 File: gettext.info, Node: scheme-format, Next: smalltalk-format, Prev: librep-format, Up: Translators for other Languages
10952 15.3.8 Scheme Format Strings
10953 ----------------------------
10955 Scheme format strings are documented in the SLIB manual, section
10956 Format Specification.
10959 File: gettext.info, Node: smalltalk-format, Next: java-format, Prev: scheme-format, Up: Translators for other Languages
10961 15.3.9 Smalltalk Format Strings
10962 -------------------------------
10964 Smalltalk format strings are described in the GNU Smalltalk
10965 documentation, class `CharArray', methods `bindWith:' and
10966 `bindWithArguments:'.
10967 `http://www.gnu.org/software/smalltalk/gst-manual/gst_68.html#SEC238'.
10968 In summary, a directive starts with `%' and is followed by `%' or a
10969 nonzero digit (`1' to `9').
10972 File: gettext.info, Node: java-format, Next: csharp-format, Prev: smalltalk-format, Up: Translators for other Languages
10974 15.3.10 Java Format Strings
10975 ---------------------------
10977 Java format strings are described in the JDK documentation for class
10978 `java.text.MessageFormat',
10979 `http://java.sun.com/j2se/1.4/docs/api/java/text/MessageFormat.html'.
10980 See also the ICU documentation
10981 `http://oss.software.ibm.com/icu/apiref/classMessageFormat.html'.
10984 File: gettext.info, Node: csharp-format, Next: awk-format, Prev: java-format, Up: Translators for other Languages
10986 15.3.11 C# Format Strings
10987 -------------------------
10989 C# format strings are described in the .NET documentation for class
10990 `System.String' and in
10991 `http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpConFormattingOverview.asp'.
10994 File: gettext.info, Node: awk-format, Next: object-pascal-format, Prev: csharp-format, Up: Translators for other Languages
10996 15.3.12 awk Format Strings
10997 --------------------------
10999 awk format strings are described in the gawk documentation, section
11000 Printf, `http://www.gnu.org/manual/gawk/html_node/Printf.html#Printf'.
11003 File: gettext.info, Node: object-pascal-format, Next: ycp-format, Prev: awk-format, Up: Translators for other Languages
11005 15.3.13 Object Pascal Format Strings
11006 ------------------------------------
11008 Object Pascal format strings are described in the documentation of
11009 the Free Pascal runtime library, section Format,
11010 `http://www.freepascal.org/docs-html/rtl/sysutils/format.html'.
11013 File: gettext.info, Node: ycp-format, Next: tcl-format, Prev: object-pascal-format, Up: Translators for other Languages
11015 15.3.14 YCP Format Strings
11016 --------------------------
11018 YCP sformat strings are described in the libycp documentation
11019 `file:/usr/share/doc/packages/libycp/YCP-builtins.html'. In summary, a
11020 directive starts with `%' and is followed by `%' or a nonzero digit
11024 File: gettext.info, Node: tcl-format, Next: perl-format, Prev: ycp-format, Up: Translators for other Languages
11026 15.3.15 Tcl Format Strings
11027 --------------------------
11029 Tcl format strings are described in the `format.n' manual page,
11030 `http://www.scriptics.com/man/tcl8.3/TclCmd/format.htm'.
11033 File: gettext.info, Node: perl-format, Next: php-format, Prev: tcl-format, Up: Translators for other Languages
11035 15.3.16 Perl Format Strings
11036 ---------------------------
11038 There are two kinds format strings in Perl: those acceptable to the
11039 Perl built-in function `printf', labelled as `perl-format', and those
11040 acceptable to the `libintl-perl' function `__x', labelled as
11041 `perl-brace-format'.
11043 Perl `printf' format strings are described in the `sprintf' section
11046 Perl brace format strings are described in the
11047 `Locale::TextDomain(3pm)' manual page of the CPAN package libintl-perl.
11048 In brief, Perl format uses placeholders put between braces (`{' and
11049 `}'). The placeholder must have the syntax of simple identifiers.
11052 File: gettext.info, Node: php-format, Next: gcc-internal-format, Prev: perl-format, Up: Translators for other Languages
11054 15.3.17 PHP Format Strings
11055 --------------------------
11057 PHP format strings are described in the documentation of the PHP
11058 function `sprintf', in `phpdoc/manual/function.sprintf.html' or
11059 `http://www.php.net/manual/en/function.sprintf.php'.
11062 File: gettext.info, Node: gcc-internal-format, Next: gfc-internal-format, Prev: php-format, Up: Translators for other Languages
11064 15.3.18 GCC internal Format Strings
11065 -----------------------------------
11067 These format strings are used inside the GCC sources. In such a
11068 format string, a directive starts with `%', is optionally followed by a
11069 size specifier `l', an optional flag `+', another optional flag `#',
11070 and is finished by a specifier: `%' denotes a literal percent sign, `c'
11071 denotes a character, `s' denotes a string, `i' and `d' denote an
11072 integer, `o', `u', `x' denote an unsigned integer, `.*s' denotes a
11073 string preceded by a width specification, `H' denotes a `location_t *'
11074 pointer, `D' denotes a general declaration, `F' denotes a function
11075 declaration, `T' denotes a type, `A' denotes a function argument, `C'
11076 denotes a tree code, `E' denotes an expression, `L' denotes a
11077 programming language, `O' denotes a binary operator, `P' denotes a
11078 function parameter, `Q' denotes an assignment operator, `V' denotes a
11079 const/volatile qualifier.
11082 File: gettext.info, Node: gfc-internal-format, Next: qt-format, Prev: gcc-internal-format, Up: Translators for other Languages
11084 15.3.19 GFC internal Format Strings
11085 -----------------------------------
11087 These format strings are used inside the GNU Fortran Compiler
11088 sources, that is, the Fortran frontend in the GCC sources. In such a
11089 format string, a directive starts with `%' and is finished by a
11090 specifier: `%' denotes a literal percent sign, `C' denotes the current
11091 source location, `L' denotes a source location, `c' denotes a
11092 character, `s' denotes a string, `i' and `d' denote an integer, `u'
11093 denotes an unsigned integer. `i', `d', and `u' may be preceded by a
11094 size specifier `l'.
11097 File: gettext.info, Node: qt-format, Next: qt-plural-format, Prev: gfc-internal-format, Up: Translators for other Languages
11099 15.3.20 Qt Format Strings
11100 -------------------------
11102 Qt format strings are described in the documentation of the QString
11103 class `file:/usr/lib/qt-4.3.0/doc/html/qstring.html'. In summary, a
11104 directive consists of a `%' followed by a digit. The same directive
11105 cannot occur more than once in a format string.
11108 File: gettext.info, Node: qt-plural-format, Next: kde-format, Prev: qt-format, Up: Translators for other Languages
11110 15.3.21 Qt Format Strings
11111 -------------------------
11113 Qt format strings are described in the documentation of the
11114 QObject::tr method `file:/usr/lib/qt-4.3.0/doc/html/qobject.html'. In
11115 summary, the only allowed directive is `%n'.
11118 File: gettext.info, Node: kde-format, Next: boost-format, Prev: qt-plural-format, Up: Translators for other Languages
11120 15.3.22 KDE Format Strings
11121 --------------------------
11123 KDE 4 format strings are defined as follows: A directive consists of
11124 a `%' followed by a non-zero decimal number. If a `%n' occurs in a
11125 format strings, all of `%1', ..., `%(n-1)' must occur as well, except
11126 possibly one of them.
11129 File: gettext.info, Node: boost-format, Prev: kde-format, Up: Translators for other Languages
11131 15.3.23 Boost Format Strings
11132 ----------------------------
11134 Boost format strings are described in the documentation of the
11135 `boost::format' class, at
11136 `http://www.boost.org/libs/format/doc/format.html'. In summary, a
11137 directive has either the same syntax as in a C format string, such as
11138 `%1$+5d', or may be surrounded by vertical bars, such as `%|1$+5d|' or
11139 `%|1$+5|', or consists of just an argument number between percent
11140 signs, such as `%1%'.
11143 File: gettext.info, Node: Maintainers for other Languages, Next: List of Programming Languages, Prev: Translators for other Languages, Up: Programming Languages
11145 15.4 The Maintainer's View
11146 ==========================
11148 For the maintainer, the general procedure differs from the C language
11151 * For those languages that don't use GNU gettext, the `intl/'
11152 directory is not needed and can be omitted. This means that the
11153 maintainer calls the `gettextize' program without the `--intl'
11154 option, and that he invokes the `AM_GNU_GETTEXT' autoconf macro via
11155 `AM_GNU_GETTEXT([external])'.
11157 * If only a single programming language is used, the
11158 `XGETTEXT_OPTIONS' variable in `po/Makevars' (*note po/Makevars::)
11159 should be adjusted to match the `xgettext' options for that
11160 particular programming language. If the package uses more than
11161 one programming language with `gettext' support, it becomes
11162 necessary to change the POT file construction rule in
11163 `po/Makefile.in.in'. It is recommended to make one `xgettext'
11164 invocation per programming language, each with the options
11165 appropriate for that language, and to combine the resulting files
11169 File: gettext.info, Node: List of Programming Languages, Next: List of Data Formats, Prev: Maintainers for other Languages, Up: Programming Languages
11171 15.5 Individual Programming Languages
11172 =====================================
11176 * C:: C, C++, Objective C
11177 * sh:: sh - Shell Script
11178 * bash:: bash - Bourne-Again Shell Script
11180 * Common Lisp:: GNU clisp - Common Lisp
11181 * clisp C:: GNU clisp C sources
11182 * Emacs Lisp:: Emacs Lisp
11184 * Scheme:: GNU guile - Scheme
11185 * Smalltalk:: GNU Smalltalk
11189 * Pascal:: Pascal - Free Pascal Compiler
11190 * wxWidgets:: wxWidgets library
11191 * YCP:: YCP - YaST2 scripting language
11192 * Tcl:: Tcl - Tk's scripting language
11194 * PHP:: PHP Hypertext Preprocessor
11196 * GCC-source:: GNU Compiler Collection sources
11199 File: gettext.info, Node: C, Next: sh, Prev: List of Programming Languages, Up: List of Programming Languages
11201 15.5.1 C, C++, Objective C
11202 --------------------------
11205 gcc, gpp, gobjc, glibc, gettext
11209 For C++: `C', `c++', `cc', `cxx', `cpp', `hpp'.
11210 For Objective C: `m'.
11218 gettext/ngettext functions
11219 `gettext', `dgettext', `dcgettext', `ngettext', `dngettext',
11223 `textdomain' function
11226 `bindtextdomain' function
11229 Programmer must call `setlocale (LC_ALL, "")'
11232 `#include <libintl.h>'
11233 `#include <locale.h>'
11234 `#define _(string) gettext (string)'
11236 Use or emulate GNU gettext
11242 Formatting with positions
11243 `fprintf "%2$d %1$d"'
11244 In C++: `autosprintf "%2$d %1$d"' (*note Introduction:
11248 autoconf (gettext.m4) and #if ENABLE_NLS
11253 The following examples are available in the `examples' directory:
11254 `hello-c', `hello-c-gnome', `hello-c++', `hello-c++-qt',
11255 `hello-c++-kde', `hello-c++-gnome', `hello-c++-wxwidgets',
11256 `hello-objc', `hello-objc-gnustep', `hello-objc-gnome'.
11259 File: gettext.info, Node: sh, Next: bash, Prev: C, Up: List of Programming Languages
11261 15.5.2 sh - Shell Script
11262 ------------------------
11271 `"abc"', `'abc'', `abc'
11274 `"`gettext \"abc\"`"'
11276 gettext/ngettext functions
11277 `gettext', `ngettext' programs
11278 `eval_gettext', `eval_ngettext' shell functions
11281 environment variable `TEXTDOMAIN'
11284 environment variable `TEXTDOMAINDIR'
11292 Use or emulate GNU gettext
11298 Formatting with positions
11307 An example is available in the `examples' directory: `hello-sh'.
11311 * Preparing Shell Scripts:: Preparing Shell Scripts for Internationalization
11312 * gettext.sh:: Contents of `gettext.sh'
11313 * gettext Invocation:: Invoking the `gettext' program
11314 * ngettext Invocation:: Invoking the `ngettext' program
11315 * envsubst Invocation:: Invoking the `envsubst' program
11316 * eval_gettext Invocation:: Invoking the `eval_gettext' function
11317 * eval_ngettext Invocation:: Invoking the `eval_ngettext' function
11320 File: gettext.info, Node: Preparing Shell Scripts, Next: gettext.sh, Prev: sh, Up: sh
11322 15.5.2.1 Preparing Shell Scripts for Internationalization
11323 .........................................................
11325 Preparing a shell script for internationalization is conceptually
11326 similar to the steps described in *note Sources::. The concrete steps
11327 for shell scripts are as follows.
11333 near the top of the script. `gettext.sh' is a shell function
11334 library that provides the functions `eval_gettext' (see *note
11335 eval_gettext Invocation::) and `eval_ngettext' (see *note
11336 eval_ngettext Invocation::). You have to ensure that `gettext.sh'
11337 can be found in the `PATH'.
11339 2. Set and export the `TEXTDOMAIN' and `TEXTDOMAINDIR' environment
11340 variables. Usually `TEXTDOMAIN' is the package or program name,
11341 and `TEXTDOMAINDIR' is the absolute pathname corresponding to
11342 `$prefix/share/locale', where `$prefix' is the installation
11345 TEXTDOMAIN=@PACKAGE@
11347 TEXTDOMAINDIR=@LOCALEDIR@
11348 export TEXTDOMAINDIR
11350 3. Prepare the strings for translation, as described in *note
11351 Preparing Strings::.
11353 4. Simplify translatable strings so that they don't contain command
11354 substitution (`"`...`"' or `"$(...)"'), variable access with
11355 defaulting (like `${VARIABLE-DEFAULT}'), access to positional
11356 arguments (like `$0', `$1', ...) or highly volatile shell
11357 variables (like `$?'). This can always be done through simple
11358 local code restructuring. For example,
11360 echo "Usage: $0 [OPTION] FILE..."
11365 echo "Usage: $program_name [OPTION] FILE..."
11369 echo "Remaining files: `ls | wc -l`"
11373 filecount="`ls | wc -l`"
11374 echo "Remaining files: $filecount"
11376 5. For each translatable string, change the output command `echo' or
11377 `$echo' to `gettext' (if the string contains no references to
11378 shell variables) or to `eval_gettext' (if it refers to shell
11379 variables), followed by a no-argument `echo' command (to account
11380 for the terminating newline). Similarly, for cases with plural
11381 handling, replace a conditional `echo' command with an invocation
11382 of `ngettext' or `eval_ngettext', followed by a no-argument `echo'
11385 When doing this, you also need to add an extra backslash before
11386 the dollar sign in references to shell variables, so that the
11387 `eval_gettext' function receives the translatable string before
11388 the variable values are substituted into it. For example,
11390 echo "Remaining files: $filecount"
11394 eval_gettext "Remaining files: \$filecount"; echo
11396 If the output command is not `echo', you can make it use `echo'
11397 nevertheless, through the use of backquotes. However, note that
11398 inside backquotes, backslashes must be doubled to be effective
11399 (because the backquoting eats one level of backslashes). For
11400 example, assuming that `error' is a shell function that signals an
11403 error "file not found: $filename"
11405 is first transformed into
11407 error "`echo \"file not found: \$filename\"`"
11411 error "`eval_gettext \"file not found: \\\$filename\"`"
11414 File: gettext.info, Node: gettext.sh, Next: gettext Invocation, Prev: Preparing Shell Scripts, Up: sh
11416 15.5.2.2 Contents of `gettext.sh'
11417 .................................
11419 `gettext.sh', contained in the run-time package of GNU gettext,
11420 provides the following:
11422 * $echo The variable `echo' is set to a command that outputs its
11423 first argument and a newline, without interpreting backslashes in
11424 the argument string.
11426 * eval_gettext See *note eval_gettext Invocation::.
11428 * eval_ngettext See *note eval_ngettext Invocation::.
11431 File: gettext.info, Node: gettext Invocation, Next: ngettext Invocation, Prev: gettext.sh, Up: sh
11433 15.5.2.3 Invoking the `gettext' program
11434 .......................................
11436 gettext [OPTION] [[TEXTDOMAIN] MSGID]
11437 gettext [OPTION] -s [MSGID]...
11439 The `gettext' program displays the native language translation of a
11445 `--domain=TEXTDOMAIN'
11446 Retrieve translated messages from TEXTDOMAIN. Usually a TEXTDOMAIN
11447 corresponds to a package, a program, or a module of a program.
11450 Enable expansion of some escape sequences. This option is for
11451 compatibility with the `echo' program or shell built-in. The
11452 escape sequences `\a', `\b', `\c', `\f', `\n', `\r', `\t', `\v',
11453 `\\', and `\' followed by one to three octal digits, are
11454 interpreted like the System V `echo' program did.
11457 This option is only for compatibility with the `echo' program or
11458 shell built-in. It has no effect.
11462 Display this help and exit.
11465 Suppress trailing newline. By default, `gettext' adds a newline to
11470 Output version information and exit.
11472 `[TEXTDOMAIN] MSGID'
11473 Retrieve translated message corresponding to MSGID from TEXTDOMAIN.
11476 If the TEXTDOMAIN parameter is not given, the domain is determined
11477 from the environment variable `TEXTDOMAIN'. If the message catalog is
11478 not found in the regular directory, another location can be specified
11479 with the environment variable `TEXTDOMAINDIR'.
11481 When used with the `-s' option the program behaves like the `echo'
11482 command. But it does not simply copy its arguments to stdout. Instead
11483 those messages found in the selected catalog are translated.
11485 Note: `xgettext' supports only the one-argument form of the
11486 `gettext' invocation, where no options are present and the TEXTDOMAIN
11487 is implicit, from the environment.
11490 File: gettext.info, Node: ngettext Invocation, Next: envsubst Invocation, Prev: gettext Invocation, Up: sh
11492 15.5.2.4 Invoking the `ngettext' program
11493 ........................................
11495 ngettext [OPTION] [TEXTDOMAIN] MSGID MSGID-PLURAL COUNT
11497 The `ngettext' program displays the native language translation of a
11498 textual message whose grammatical form depends on a number.
11503 `--domain=TEXTDOMAIN'
11504 Retrieve translated messages from TEXTDOMAIN. Usually a TEXTDOMAIN
11505 corresponds to a package, a program, or a module of a program.
11508 Enable expansion of some escape sequences. This option is for
11509 compatibility with the `gettext' program. The escape sequences
11510 `\a', `\b', `\c', `\f', `\n', `\r', `\t', `\v', `\\', and `\'
11511 followed by one to three octal digits, are interpreted like the
11512 System V `echo' program did.
11515 This option is only for compatibility with the `gettext' program.
11520 Display this help and exit.
11524 Output version information and exit.
11527 Retrieve translated message from TEXTDOMAIN.
11529 `MSGID MSGID-PLURAL'
11530 Translate MSGID (English singular) / MSGID-PLURAL (English plural).
11533 Choose singular/plural form based on this value.
11536 If the TEXTDOMAIN parameter is not given, the domain is determined
11537 from the environment variable `TEXTDOMAIN'. If the message catalog is
11538 not found in the regular directory, another location can be specified
11539 with the environment variable `TEXTDOMAINDIR'.
11541 Note: `xgettext' supports only the three-arguments form of the
11542 `ngettext' invocation, where no options are present and the TEXTDOMAIN
11543 is implicit, from the environment.
11546 File: gettext.info, Node: envsubst Invocation, Next: eval_gettext Invocation, Prev: ngettext Invocation, Up: sh
11548 15.5.2.5 Invoking the `envsubst' program
11549 ........................................
11551 envsubst [OPTION] [SHELL-FORMAT]
11553 The `envsubst' program substitutes the values of environment
11560 Output the variables occurring in SHELL-FORMAT.
11563 *Informative output*
11567 Display this help and exit.
11571 Output version information and exit.
11574 In normal operation mode, standard input is copied to standard
11575 output, with references to environment variables of the form
11576 `$VARIABLE' or `${VARIABLE}' being replaced with the corresponding
11577 values. If a SHELL-FORMAT is given, only those environment variables
11578 that are referenced in SHELL-FORMAT are substituted; otherwise all
11579 environment variables references occurring in standard input are
11582 These substitutions are a subset of the substitutions that a shell
11583 performs on unquoted and double-quoted strings. Other kinds of
11584 substitutions done by a shell, such as `${VARIABLE-DEFAULT}' or
11585 `$(COMMAND-LIST)' or ``COMMAND-LIST`', are not performed by the
11586 `envsubst' program, due to security reasons.
11588 When `--variables' is used, standard input is ignored, and the output
11589 consists of the environment variables that are referenced in
11590 SHELL-FORMAT, one per line.
11593 File: gettext.info, Node: eval_gettext Invocation, Next: eval_ngettext Invocation, Prev: envsubst Invocation, Up: sh
11595 15.5.2.6 Invoking the `eval_gettext' function
11596 .............................................
11600 This function outputs the native language translation of a textual
11601 message, performing dollar-substitution on the result. Note that only
11602 shell variables mentioned in MSGID will be dollar-substituted in the
11606 File: gettext.info, Node: eval_ngettext Invocation, Prev: eval_gettext Invocation, Up: sh
11608 15.5.2.7 Invoking the `eval_ngettext' function
11609 ..............................................
11611 eval_ngettext MSGID MSGID-PLURAL COUNT
11613 This function outputs the native language translation of a textual
11614 message whose grammatical form depends on a number, performing
11615 dollar-substitution on the result. Note that only shell variables
11616 mentioned in MSGID or MSGID-PLURAL will be dollar-substituted in the
11620 File: gettext.info, Node: bash, Next: Python, Prev: sh, Up: List of Programming Languages
11622 15.5.3 bash - Bourne-Again Shell Script
11623 ---------------------------------------
11625 GNU `bash' 2.0 or newer has a special shorthand for translating a
11626 string and substituting variable values in it: `$"msgid"'. But the use
11627 of this construct is *discouraged*, due to the security holes it opens
11628 and due to its portability problems.
11630 The security holes of `$"..."' come from the fact that after looking
11631 up the translation of the string, `bash' processes it like it processes
11632 any double-quoted string: dollar and backquote processing, like `eval'
11635 1. In a locale whose encoding is one of BIG5, BIG5-HKSCS, GBK,
11636 GB18030, SHIFT_JIS, JOHAB, some double-byte characters have a
11637 second byte whose value is `0x60'. For example, the byte sequence
11638 `\xe0\x60' is a single character in these locales. Many versions
11639 of `bash' (all versions up to bash-2.05, and newer versions on
11640 platforms without `mbsrtowcs()' function) don't know about
11641 character boundaries and see a backquote character where there is
11642 only a particular Chinese character. Thus it can start executing
11643 part of the translation as a command list. This situation can
11644 occur even without the translator being aware of it: if the
11645 translator provides translations in the UTF-8 encoding, it is the
11646 `gettext()' function which will, during its conversion from the
11647 translator's encoding to the user's locale's encoding, produce the
11648 dangerous `\x60' bytes.
11650 2. A translator could - voluntarily or inadvertently - use backquotes
11651 `"`...`"' or dollar-parentheses `"$(...)"' in her translations.
11652 The enclosed strings would be executed as command lists by the
11655 The portability problem is that `bash' must be built with
11656 internationalization support; this is normally not the case on systems
11657 that don't have the `gettext()' function in libc.
11660 File: gettext.info, Node: Python, Next: Common Lisp, Prev: bash, Up: List of Programming Languages
11672 `'abc'', `u'abc'', `r'abc'', `ur'abc'',
11673 `"abc"', `u"abc"', `r"abc"', `ur"abc"',
11674 `'''abc'''', `u'''abc'''', `r'''abc'''', `ur'''abc'''',
11675 `"""abc"""', `u"""abc"""', `r"""abc"""', `ur"""abc"""'
11680 gettext/ngettext functions
11681 `gettext.gettext', `gettext.dgettext', `gettext.ngettext',
11682 `gettext.dngettext', also `ugettext', `ungettext'
11685 `gettext.textdomain' function, or `gettext.install(DOMAIN)'
11689 `gettext.bindtextdomain' function, or
11690 `gettext.install(DOMAIN,LOCALEDIR)' function
11693 not used by the gettext emulation
11698 Use or emulate GNU gettext
11704 Formatting with positions
11705 `'...%(ident)d...' % { 'ident': value }'
11713 An example is available in the `examples' directory: `hello-python'.
11715 A note about format strings: Python supports format strings with
11716 unnamed arguments, such as `'...%d...'', and format strings with named
11717 arguments, such as `'...%(ident)d...''. The latter are preferable for
11718 internationalized programs, for two reasons:
11720 * When a format string takes more than one argument, the translator
11721 can provide a translation that uses the arguments in a different
11722 order, if the format string uses named arguments. For example,
11723 the translator can reformulate
11724 "'%(volume)s' has only %(freespace)d bytes free."
11726 "Only %(freespace)d bytes free on '%(volume)s'."
11727 Additionally, the identifiers also provide some context to the
11730 * In the context of plural forms, the format string used for the
11731 singular form does not use the numeric argument in many languages.
11732 Even in English, one prefers to write `"one hour"' instead of `"1
11733 hour"'. Omitting individual arguments from format strings like
11734 this is only possible with the named argument syntax. (With
11735 unnamed arguments, Python - unlike C - verifies that the format
11736 string uses all supplied arguments.)
11739 File: gettext.info, Node: Common Lisp, Next: clisp C, Prev: Python, Up: List of Programming Languages
11741 15.5.5 GNU clisp - Common Lisp
11742 ------------------------------
11745 clisp 2.28 or newer
11754 `(_ "abc")', `(ENGLISH "abc")'
11756 gettext/ngettext functions
11757 `i18n:gettext', `i18n:ngettext'
11763 `i18n:textdomaindir'
11771 Use or emulate GNU gettext
11775 `xgettext -k_ -kENGLISH'
11777 Formatting with positions
11778 `format "~1@*~D ~0@*~D"'
11781 On platforms without gettext, no translation.
11786 An example is available in the `examples' directory: `hello-clisp'.
11789 File: gettext.info, Node: clisp C, Next: Emacs Lisp, Prev: Common Lisp, Up: List of Programming Languages
11791 15.5.6 GNU clisp C sources
11792 --------------------------
11804 `ENGLISH ? "abc" : ""'
11808 gettext/ngettext functions
11809 `clgettext', `clgettextl'
11821 `#include "lispbibl.c"'
11823 Use or emulate GNU gettext
11829 Formatting with positions
11830 `fprintf "%2$d %1$d"'
11833 On platforms without gettext, no translation.
11839 File: gettext.info, Node: Emacs Lisp, Next: librep, Prev: clisp C, Up: List of Programming Languages
11856 gettext/ngettext functions
11857 `gettext', `dgettext' (xemacs only)
11860 `domain' special form (xemacs only)
11863 `bind-text-domain' function (xemacs only)
11871 Use or emulate GNU gettext
11877 Formatting with positions
11878 `format "%2$d %1$d"'
11881 Only XEmacs. Without `I18N3' defined at build time, no
11888 File: gettext.info, Node: librep, Next: Scheme, Prev: Emacs Lisp, Up: List of Programming Languages
11894 librep 0.15.3 or newer
11905 gettext/ngettext functions
11909 `textdomain' function
11912 `bindtextdomain' function
11918 `(require 'rep.i18n.gettext)'
11920 Use or emulate GNU gettext
11926 Formatting with positions
11927 `format "%2$d %1$d"'
11930 On platforms without gettext, no translation.
11935 An example is available in the `examples' directory: `hello-librep'.
11938 File: gettext.info, Node: Scheme, Next: Smalltalk, Prev: librep, Up: List of Programming Languages
11940 15.5.9 GNU guile - Scheme
11941 -------------------------
11955 gettext/ngettext functions
11956 `gettext', `ngettext'
11965 `(catch #t (lambda () (setlocale LC_ALL "")) (lambda args #f))'
11968 `(use-modules (ice-9 format))'
11970 Use or emulate GNU gettext
11976 Formatting with positions
11980 On platforms without gettext, no translation.
11985 An example is available in the `examples' directory: `hello-guile'.
11988 File: gettext.info, Node: Smalltalk, Next: Java, Prev: Scheme, Up: List of Programming Languages
11990 15.5.10 GNU Smalltalk
11991 ---------------------
12005 gettext/ngettext functions
12006 `LcMessagesDomain>>#at:', `LcMessagesDomain>>#at:plural:with:'
12009 `LcMessages>>#domain:localeDirectory:' (returns a
12010 `LcMessagesDomain' object).
12011 Example: `I18N Locale default messages domain: 'gettext'
12012 localeDirectory: /usr/local/share/locale''
12015 `LcMessages>>#domain:localeDirectory:', see above.
12018 Automatic if you use `I18N Locale default'.
12021 `PackageLoader fileInPackage: 'I18N'!'
12023 Use or emulate GNU gettext
12029 Formatting with positions
12030 `'%1 %2' bindWith: 'Hello' with: 'world''
12038 An example is available in the `examples' directory:
12042 File: gettext.info, Node: Java, Next: C#, Prev: Smalltalk, Up: List of Programming Languages
12059 gettext/ngettext functions
12060 `GettextResource.gettext', `GettextResource.ngettext',
12061 `GettextResource.pgettext', `GettextResource.npgettext'
12064 --, use `ResourceBundle.getResource' instead
12067 --, use CLASSPATH instead
12075 Use or emulate GNU gettext
12076 --, uses a Java specific message catalog format
12081 Formatting with positions
12082 `MessageFormat.format "{1,number} {0,number}"'
12090 Before marking strings as internationalizable, uses of the string
12091 concatenation operator need to be converted to `MessageFormat'
12092 applications. For example, `"file "+filename+" not found"' becomes
12093 `MessageFormat.format("file {0} not found", new Object[] { filename })'.
12094 Only after this is done, can the strings be marked and extracted.
12096 GNU gettext uses the native Java internationalization mechanism,
12097 namely `ResourceBundle's. There are two formats of `ResourceBundle's:
12098 `.properties' files and `.class' files. The `.properties' format is a
12099 text file which the translators can directly edit, like PO files, but
12100 which doesn't support plural forms. Whereas the `.class' format is
12101 compiled from `.java' source code and can support plural forms
12102 (provided it is accessed through an appropriate API, see below).
12104 To convert a PO file to a `.properties' file, the `msgcat' program
12105 can be used with the option `--properties-output'. To convert a
12106 `.properties' file back to a PO file, the `msgcat' program can be used
12107 with the option `--properties-input'. All the tools that manipulate PO
12108 files can work with `.properties' files as well, if given the
12109 `--properties-input' and/or `--properties-output' option.
12111 To convert a PO file to a ResourceBundle class, the `msgfmt' program
12112 can be used with the option `--java' or `--java2'. To convert a
12113 ResourceBundle back to a PO file, the `msgunfmt' program can be used
12114 with the option `--java'.
12116 Two different programmatic APIs can be used to access
12117 ResourceBundles. Note that both APIs work with all kinds of
12118 ResourceBundles, whether GNU gettext generated classes, or other
12119 `.class' or `.properties' files.
12121 1. The `java.util.ResourceBundle' API.
12123 In particular, its `getString' function returns a string
12124 translation. Note that a missing translation yields a
12125 `MissingResourceException'.
12127 This has the advantage of being the standard API. And it does not
12128 require any additional libraries, only the `msgcat' generated
12129 `.properties' files or the `msgfmt' generated `.class' files. But
12130 it cannot do plural handling, even if the resource was generated
12131 by `msgfmt' from a PO file with plural handling.
12133 2. The `gnu.gettext.GettextResource' API.
12135 Reference documentation in Javadoc 1.1 style format is in the
12136 javadoc2 directory (javadoc2/index.html).
12138 Its `gettext' function returns a string translation. Note that
12139 when a translation is missing, the MSGID argument is returned
12142 This has the advantage of having the `ngettext' function for plural
12143 handling and the `pgettext' and `npgettext' for strings constraint
12144 to a particular context.
12146 To use this API, one needs the `libintl.jar' file which is part of
12147 the GNU gettext package and distributed under the LGPL.
12149 Four examples, using the second API, are available in the `examples'
12150 directory: `hello-java', `hello-java-awt', `hello-java-swing',
12151 `hello-java-qtjambi'.
12153 Now, to make use of the API and define a shorthand for `getString',
12154 there are three idioms that you can choose from:
12156 * (This one assumes Java 1.5 or newer.) In a unique class of your
12157 project, say `Util', define a static variable holding the
12158 `ResourceBundle' instance and the shorthand:
12160 private static ResourceBundle myResources =
12161 ResourceBundle.getBundle("domain-name");
12162 public static String _(String s) {
12163 return myResources.getString(s);
12166 All classes containing internationalized strings then contain
12168 import static Util._;
12170 and the shorthand is used like this:
12172 System.out.println(_("Operation completed."));
12174 * In a unique class of your project, say `Util', define a static
12175 variable holding the `ResourceBundle' instance:
12177 public static ResourceBundle myResources =
12178 ResourceBundle.getBundle("domain-name");
12180 All classes containing internationalized strings then contain
12182 private static ResourceBundle res = Util.myResources;
12183 private static String _(String s) { return res.getString(s); }
12185 and the shorthand is used like this:
12187 System.out.println(_("Operation completed."));
12189 * You add a class with a very short name, say `S', containing just
12190 the definition of the resource bundle and of the shorthand:
12193 public static ResourceBundle myResources =
12194 ResourceBundle.getBundle("domain-name");
12195 public static String _(String s) {
12196 return myResources.getString(s);
12200 and the shorthand is used like this:
12202 System.out.println(S._("Operation completed."));
12204 Which of the three idioms you choose, will depend on whether your
12205 project requires portability to Java versions prior to Java 1.5 and, if
12206 so, whether copying two lines of codes into every class is more
12207 acceptable in your project than a class with a single-letter name.
12210 File: gettext.info, Node: C#, Next: gawk, Prev: Java, Up: List of Programming Languages
12216 pnet, pnetlib 0.6.2 or newer, or mono 0.29 or newer
12227 gettext/ngettext functions
12228 `GettextResourceManager.GetString',
12229 `GettextResourceManager.GetPluralString'
12230 `GettextResourceManager.GetParticularString'
12231 `GettextResourceManager.GetParticularPluralString'
12234 `new GettextResourceManager(domain)'
12237 --, compiled message catalogs are located in subdirectories of the
12238 directory containing the executable
12246 Use or emulate GNU gettext
12247 --, uses a C# specific message catalog format
12252 Formatting with positions
12253 `String.Format "{1} {0}"'
12261 Before marking strings as internationalizable, uses of the string
12262 concatenation operator need to be converted to `String.Format'
12263 invocations. For example, `"file "+filename+" not found"' becomes
12264 `String.Format("file {0} not found", filename)'. Only after this is
12265 done, can the strings be marked and extracted.
12267 GNU gettext uses the native C#/.NET internationalization mechanism,
12268 namely the classes `ResourceManager' and `ResourceSet'. Applications
12269 use the `ResourceManager' methods to retrieve the native language
12270 translation of strings. An instance of `ResourceSet' is the in-memory
12271 representation of a message catalog file. The `ResourceManager' loads
12272 and accesses `ResourceSet' instances as needed to look up the
12275 There are two formats of `ResourceSet's that can be directly loaded
12276 by the C# runtime: `.resources' files and `.dll' files.
12278 * The `.resources' format is a binary file usually generated through
12279 the `resgen' or `monoresgen' utility, but which doesn't support
12280 plural forms. `.resources' files can also be embedded in .NET
12281 `.exe' files. This only affects whether a file system access is
12282 performed to load the message catalog; it doesn't affect the
12283 contents of the message catalog.
12285 * On the other hand, the `.dll' format is a binary file that is
12286 compiled from `.cs' source code and can support plural forms
12287 (provided it is accessed through the GNU gettext API, see below).
12289 Note that these .NET `.dll' and `.exe' files are not tied to a
12290 particular platform; their file format and GNU gettext for C# can be
12291 used on any platform.
12293 To convert a PO file to a `.resources' file, the `msgfmt' program
12294 can be used with the option `--csharp-resources'. To convert a
12295 `.resources' file back to a PO file, the `msgunfmt' program can be used
12296 with the option `--csharp-resources'. You can also, in some cases, use
12297 the `resgen' program (from the `pnet' package) or the `monoresgen'
12298 program (from the `mono'/`mcs' package). These programs can also
12299 convert a `.resources' file back to a PO file. But beware: as of this
12300 writing (January 2004), the `monoresgen' converter is quite buggy and
12301 the `resgen' converter ignores the encoding of the PO files.
12303 To convert a PO file to a `.dll' file, the `msgfmt' program can be
12304 used with the option `--csharp'. The result will be a `.dll' file
12305 containing a subclass of `GettextResourceSet', which itself is a
12306 subclass of `ResourceSet'. To convert a `.dll' file containing a
12307 `GettextResourceSet' subclass back to a PO file, the `msgunfmt' program
12308 can be used with the option `--csharp'.
12310 The advantages of the `.dll' format over the `.resources' format are:
12312 1. Freedom to localize: Users can add their own translations to an
12313 application after it has been built and distributed. Whereas when
12314 the programmer uses a `ResourceManager' constructor provided by
12315 the system, the set of `.resources' files for an application must
12316 be specified when the application is built and cannot be extended
12319 2. Plural handling: A message catalog in `.dll' format supports the
12320 plural handling function `GetPluralString'. Whereas `.resources'
12321 files can only contain data and only support lookups that depend
12322 on a single string.
12324 3. Context handling: A message catalog in `.dll' format supports the
12325 query-with-context functions `GetParticularString' and
12326 `GetParticularPluralString'. Whereas `.resources' files can only
12327 contain data and only support lookups that depend on a single
12330 4. The `GettextResourceManager' that loads the message catalogs in
12331 `.dll' format also provides for inheritance on a per-message basis.
12332 For example, in Austrian (`de_AT') locale, translations from the
12333 German (`de') message catalog will be used for messages not found
12334 in the Austrian message catalog. This has the consequence that
12335 the Austrian translators need only translate those few messages
12336 for which the translation into Austrian differs from the German
12337 one. Whereas when working with `.resources' files, each message
12338 catalog must provide the translations of all messages by itself.
12340 5. The `GettextResourceManager' that loads the message catalogs in
12341 `.dll' format also provides for a fallback: The English MSGID is
12342 returned when no translation can be found. Whereas when working
12343 with `.resources' files, a language-neutral `.resources' file must
12344 explicitly be provided as a fallback.
12346 On the side of the programmatic APIs, the programmer can use either
12347 the standard `ResourceManager' API and the GNU `GettextResourceManager'
12348 API. The latter is an extension of the former, because
12349 `GettextResourceManager' is a subclass of `ResourceManager'.
12351 1. The `System.Resources.ResourceManager' API.
12353 This API works with resources in `.resources' format.
12355 The creation of the `ResourceManager' is done through
12356 new ResourceManager(domainname, Assembly.GetExecutingAssembly())
12357 The `GetString' function returns a string's translation. Note
12358 that this function returns null when a translation is missing
12359 (i.e. not even found in the fallback resource file).
12361 2. The `GNU.Gettext.GettextResourceManager' API.
12363 This API works with resources in `.dll' format.
12365 Reference documentation is in the csharpdoc directory
12366 (csharpdoc/index.html).
12368 The creation of the `ResourceManager' is done through
12369 new GettextResourceManager(domainname)
12371 The `GetString' function returns a string's translation. Note
12372 that when a translation is missing, the MSGID argument is returned
12375 The `GetPluralString' function returns a string translation with
12376 plural handling, like the `ngettext' function in C.
12378 The `GetParticularString' function returns a string's translation,
12379 specific to a particular context, like the `pgettext' function in
12380 C. Note that when a translation is missing, the MSGID argument is
12381 returned unchanged.
12383 The `GetParticularPluralString' function returns a string
12384 translation, specific to a particular context, with plural
12385 handling, like the `npgettext' function in C.
12387 To use this API, one needs the `GNU.Gettext.dll' file which is
12388 part of the GNU gettext package and distributed under the LGPL.
12390 You can also mix both approaches: use the
12391 `GNU.Gettext.GettextResourceManager' constructor, but otherwise use
12392 only the `ResourceManager' type and only the `GetString' method. This
12393 is appropriate when you want to profit from the tools for PO files, but
12394 don't want to change an existing source code that uses
12395 `ResourceManager' and don't (yet) need the `GetPluralString' method.
12397 Two examples, using the second API, are available in the `examples'
12398 directory: `hello-csharp', `hello-csharp-forms'.
12400 Now, to make use of the API and define a shorthand for `GetString',
12401 there are two idioms that you can choose from:
12403 * In a unique class of your project, say `Util', define a static
12404 variable holding the `ResourceManager' instance:
12406 public static GettextResourceManager MyResourceManager =
12407 new GettextResourceManager("domain-name");
12409 All classes containing internationalized strings then contain
12411 private static GettextResourceManager Res = Util.MyResourceManager;
12412 private static String _(String s) { return Res.GetString(s); }
12414 and the shorthand is used like this:
12416 Console.WriteLine(_("Operation completed."));
12418 * You add a class with a very short name, say `S', containing just
12419 the definition of the resource manager and of the shorthand:
12422 public static GettextResourceManager MyResourceManager =
12423 new GettextResourceManager("domain-name");
12424 public static String _(String s) {
12425 return MyResourceManager.GetString(s);
12429 and the shorthand is used like this:
12431 Console.WriteLine(S._("Operation completed."));
12433 Which of the two idioms you choose, will depend on whether copying
12434 two lines of codes into every class is more acceptable in your project
12435 than a class with a single-letter name.
12438 File: gettext.info, Node: gawk, Next: Pascal, Prev: C#, Up: List of Programming Languages
12455 gettext/ngettext functions
12456 `dcgettext', missing `dcngettext' in gawk-3.1.0
12459 `TEXTDOMAIN' variable
12462 `bindtextdomain' function
12465 automatic, but missing `setlocale (LC_MESSAGES, "")' in gawk-3.1.0
12470 Use or emulate GNU gettext
12476 Formatting with positions
12477 `printf "%2$d %1$d"' (GNU awk only)
12480 On platforms without gettext, no translation. On non-GNU awks,
12481 you must define `dcgettext', `dcngettext' and `bindtextdomain'
12487 An example is available in the `examples' directory: `hello-gawk'.
12490 File: gettext.info, Node: Pascal, Next: wxWidgets, Prev: gawk, Up: List of Programming Languages
12492 15.5.14 Pascal - Free Pascal Compiler
12493 -------------------------------------
12507 gettext/ngettext functions
12508 --, use `ResourceString' data type instead
12511 --, use `TranslateResourceStrings' function instead
12514 --, use `TranslateResourceStrings' function instead
12517 automatic, but uses only LANG, not LC_MESSAGES or LC_ALL
12520 `{$mode delphi}' or `{$mode objfpc}'
12523 Use or emulate GNU gettext
12527 `ppc386' followed by `xgettext' or `rstconv'
12529 Formatting with positions
12531 `format "%1:d %0:d"'
12539 The Pascal compiler has special support for the `ResourceString' data
12540 type. It generates a `.rst' file. This is then converted to a `.pot'
12541 file by use of `xgettext' or `rstconv'. At runtime, a `.mo' file
12542 corresponding to translations of this `.pot' file can be loaded using
12543 the `TranslateResourceStrings' function in the `gettext' unit.
12545 An example is available in the `examples' directory: `hello-pascal'.
12548 File: gettext.info, Node: wxWidgets, Next: YCP, Prev: Pascal, Up: List of Programming Languages
12550 15.5.15 wxWidgets library
12551 -------------------------
12565 gettext/ngettext functions
12566 `wxLocale::GetString', `wxGetTranslation'
12569 `wxLocale::AddCatalog'
12572 `wxLocale::AddCatalogLookupPathPrefix'
12575 `wxLocale::Init', `wxSetLocale'
12578 `#include <wx/intl.h>'
12580 Use or emulate GNU gettext
12581 emulate, see `include/wx/intl.h' and `src/common/intl.cpp'
12586 Formatting with positions
12587 wxString::Format supports positions if and only if the system has
12588 `wprintf()', `vswprintf()' functions and they support positions
12589 according to POSIX.
12598 File: gettext.info, Node: YCP, Next: Tcl, Prev: wxWidgets, Up: List of Programming Languages
12600 15.5.16 YCP - YaST2 scripting language
12601 --------------------------------------
12604 libycp, libycp-devel, yast2-core, yast2-core-devel
12615 gettext/ngettext functions
12616 `_()' with 1 or 3 arguments
12619 `textdomain' statement
12630 Use or emulate GNU gettext
12636 Formatting with positions
12645 An example is available in the `examples' directory: `hello-ycp'.
12648 File: gettext.info, Node: Tcl, Next: Perl, Prev: YCP, Up: List of Programming Languages
12650 15.5.17 Tcl - Tk's scripting language
12651 -------------------------------------
12665 gettext/ngettext functions
12672 --, use `::msgcat::mcload' instead
12675 automatic, uses LANG, but ignores LC_MESSAGES and LC_ALL
12678 `package require msgcat'
12679 `proc _ {s} {return [::msgcat::mc $s]}'
12681 Use or emulate GNU gettext
12682 --, uses a Tcl specific message catalog format
12687 Formatting with positions
12688 `format "%2\$d %1\$d"'
12696 Two examples are available in the `examples' directory: `hello-tcl',
12699 Before marking strings as internationalizable, substitutions of
12700 variables into the string need to be converted to `format'
12701 applications. For example, `"file $filename not found"' becomes
12702 `[format "file %s not found" $filename]'. Only after this is done, can
12703 the strings be marked and extracted. After marking, this example
12704 becomes `[format [_ "file %s not found"] $filename]' or `[msgcat::mc
12705 "file %s not found" $filename]'. Note that the `msgcat::mc' function
12706 implicitly calls `format' when more than one argument is given.
12709 File: gettext.info, Node: Perl, Next: PHP, Prev: Tcl, Up: List of Programming Languages
12718 `pl', `PL', `pm', `cgi'
12733 * `/pattern match/'
12735 * `?pattern match?'
12737 * `s/substitution/operators/'
12739 * `$tied_hash{"message"}'
12741 * `$tied_hash_reference->{"message"}'
12743 * etc., issue the command `man perlsyn' for details
12747 `__' (double underscore)
12749 gettext/ngettext functions
12750 `gettext', `dgettext', `dcgettext', `ngettext', `dngettext',
12754 `textdomain' function
12757 `bindtextdomain' function
12759 bind_textdomain_codeset
12760 `bind_textdomain_codeset' function
12763 Use `setlocale (LC_ALL, "");'
12767 `use Locale::TextDomain;' (included in the package libintl-perl
12768 which is available on the Comprehensive Perl Archive Network CPAN,
12769 http://www.cpan.org/).
12771 Use or emulate GNU gettext
12772 platform dependent: gettext_pp emulates, gettext_xs uses GNU
12776 `xgettext -k__ -k\$__ -k%__ -k__x -k__n:1,2 -k__nx:1,2 -k__xn:1,2
12779 Formatting with positions
12780 Both kinds of format strings support formatting with positions.
12781 `printf "%2\$d %1\$d", ...' (requires Perl 5.8.0 or newer)
12782 `__expand("[new] replaces [old]", old => $oldvalue, new =>
12786 The `libintl-perl' package is platform independent but is not part
12787 of the Perl core. The programmer is responsible for providing a
12788 dummy implementation of the required functions if the package is
12789 not installed on the target system.
12795 Included in `libintl-perl', available on CPAN
12796 (http://www.cpan.org/).
12799 An example is available in the `examples' directory: `hello-perl'.
12801 The `xgettext' parser backend for Perl differs significantly from
12802 the parser backends for other programming languages, just as Perl
12803 itself differs significantly from other programming languages. The
12804 Perl parser backend offers many more string marking facilities than the
12805 other backends but it also has some Perl specific limitations, the
12806 worst probably being its imperfectness.
12810 * General Problems:: General Problems Parsing Perl Code
12811 * Default Keywords:: Which Keywords Will xgettext Look For?
12812 * Special Keywords:: How to Extract Hash Keys
12813 * Quote-like Expressions:: What are Strings And Quote-like Expressions?
12814 * Interpolation I:: Invalid String Interpolation
12815 * Interpolation II:: Valid String Interpolation
12816 * Parentheses:: When To Use Parentheses
12817 * Long Lines:: How To Grok with Long Lines
12818 * Perl Pitfalls:: Bugs, Pitfalls, and Things That Do Not Work
12821 File: gettext.info, Node: General Problems, Next: Default Keywords, Up: Perl
12823 15.5.18.1 General Problems Parsing Perl Code
12824 ............................................
12826 It is often heard that only Perl can parse Perl. This is not true.
12827 Perl cannot be _parsed_ at all, it can only be _executed_. Perl has
12828 various built-in ambiguities that can only be resolved at runtime.
12830 The following example may illustrate one common problem:
12832 print gettext "Hello World!";
12834 Although this example looks like a bullet-proof case of a function
12835 invocation, it is not:
12837 open gettext, ">testfile" or die;
12838 print gettext "Hello world!"
12840 In this context, the string `gettext' looks more like a file handle.
12841 But not necessarily:
12843 use Locale::Messages qw (:libintl_h);
12844 open gettext ">testfile" or die;
12845 print gettext "Hello world!";
12847 Now, the file is probably syntactically incorrect, provided that the
12848 module `Locale::Messages' found first in the Perl include path exports a
12849 function `gettext'. But what if the module `Locale::Messages' really
12852 use vars qw (*gettext);
12856 In this case, the string `gettext' will be interpreted as a file
12857 handle again, and the above example will create a file `testfile' and
12858 write the string "Hello world!" into it. Even advanced control flow
12859 analysis will not really help:
12866 print gettext "Hello world!";
12868 If the module `Sane' exports a function `gettext' that does what we
12869 expect, and the module `InSane' opens a file for writing and associates
12870 the _handle_ `gettext' with this output stream, we are clueless again
12871 about what will happen at runtime. It is completely unpredictable.
12872 The truth is that Perl has so many ways to fill its symbol table at
12873 runtime that it is impossible to interpret a particular piece of code
12874 without executing it.
12876 Of course, `xgettext' will not execute your Perl sources while
12877 scanning for translatable strings, but rather use heuristics in order
12878 to guess what you meant.
12880 Another problem is the ambiguity of the slash and the question mark.
12881 Their interpretation depends on the context:
12884 print "OK\n" if /foobar/;
12889 # Another pattern match.
12890 print "OK\n" if ?foobar?;
12893 print $x ? "foo" : "bar";
12895 The slash may either act as the division operator or introduce a
12896 pattern match, whereas the question mark may act as the ternary
12897 conditional operator or as a pattern match, too. Other programming
12898 languages like `awk' present similar problems, but the consequences of a
12899 misinterpretation are particularly nasty with Perl sources. In `awk'
12900 for instance, a statement can never exceed one line and the parser can
12901 recover from a parsing error at the next newline and interpret the rest
12902 of the input stream correctly. Perl is different, as a pattern match
12903 is terminated by the next appearance of the delimiter (the slash or the
12904 question mark) in the input stream, regardless of the semantic context.
12905 If a slash is really a division sign but mis-interpreted as a pattern
12906 match, the rest of the input file is most probably parsed incorrectly.
12908 There are certain cases, where the ambiguity cannot be resolved at
12911 $x = wantarray ? 1 : 0;
12913 The Perl built-in function `wantarray' does not accept any arguments.
12914 The Perl parser therefore knows that the question mark does not start a
12915 regular expression but is the ternary conditional operator.
12918 $x = wantarrays ? 1 : 0;
12920 Now the situation is different. The function `wantarrays' takes a
12921 variable number of arguments (like any non-prototyped Perl function).
12922 The question mark is now the delimiter of a pattern match, and hence
12923 the piece of code does not compile.
12925 sub wantarrays() {}
12926 $x = wantarrays ? 1 : 0;
12928 Now the function is prototyped, Perl knows that it does not accept
12929 any arguments, and the question mark is therefore interpreted as the
12930 ternaray operator again. But that unfortunately outsmarts `xgettext'.
12932 The Perl parser in `xgettext' cannot know whether a function has a
12933 prototype and what that prototype would look like. It therefore makes
12934 an educated guess. If a function is known to be a Perl built-in and
12935 this function does not accept any arguments, a following question mark
12936 or slash is treated as an operator, otherwise as the delimiter of a
12937 following regular expression. The Perl built-ins that do not accept
12938 arguments are `wantarray', `fork', `time', `times', `getlogin',
12939 `getppid', `getpwent', `getgrent', `gethostent', `getnetent',
12940 `getprotoent', `getservent', `setpwent', `setgrent', `endpwent',
12941 `endgrent', `endhostent', `endnetent', `endprotoent', and `endservent'.
12943 If you find that `xgettext' fails to extract strings from portions
12944 of your sources, you should therefore look out for slashes and/or
12945 question marks preceding these sections. You may have come across a
12946 bug in `xgettext''s Perl parser (and of course you should report that
12947 bug). In the meantime you should consider to reformulate your code in
12948 a manner less challenging to `xgettext'.
12950 In particular, if the parser is too dumb to see that a function does
12951 not accept arguments, use parentheses:
12953 $x = somefunc() ? 1 : 0;
12954 $y = (somefunc) ? 1 : 0;
12956 In fact the Perl parser itself has similar problems and warns you
12957 about such constructs.
12960 File: gettext.info, Node: Default Keywords, Next: Special Keywords, Prev: General Problems, Up: Perl
12962 15.5.18.2 Which keywords will xgettext look for?
12963 ................................................
12965 Unless you instruct `xgettext' otherwise by invoking it with one of
12966 the options `--keyword' or `-k', it will recognize the following
12967 keywords in your Perl sources:
12977 The first (singular) and the second (plural) argument will be
12982 The first (singular) and the second (plural) argument will be
12987 The first (singular) and the second (plural) argument will be
12994 The keys of lookups into the hash `%gettext' will be extracted.
12998 The keys of lookups into the hash reference `$gettext' will be
13003 File: gettext.info, Node: Special Keywords, Next: Quote-like Expressions, Prev: Default Keywords, Up: Perl
13005 15.5.18.3 How to Extract Hash Keys
13006 ..................................
13008 Translating messages at runtime is normally performed by looking up
13009 the original string in the translation database and returning the
13010 translated version. The "natural" Perl implementation is a hash
13011 lookup, and, of course, `xgettext' supports such practice.
13013 print __"Hello world!";
13014 print $__{"Hello world!"};
13015 print $__->{"Hello world!"};
13016 print $$__{"Hello world!"};
13018 The above four lines all do the same thing. The Perl module
13019 `Locale::TextDomain' exports by default a hash `%__' that is tied to
13020 the function `__()'. It also exports a reference `$__' to `%__'.
13022 If an argument to the `xgettext' option `--keyword', resp. `-k'
13023 starts with a percent sign, the rest of the keyword is interpreted as
13024 the name of a hash. If it starts with a dollar sign, the rest of the
13025 keyword is interpreted as a reference to a hash.
13027 Note that you can omit the quotation marks (single or double) around
13028 the hash key (almost) whenever Perl itself allows it:
13030 print $gettext{Error};
13032 The exact rule is: You can omit the surrounding quotes, when the hash
13033 key is a valid C (!) identifier, i.e. when it starts with an underscore
13034 or an ASCII letter and is followed by an arbitrary number of
13035 underscores, ASCII letters or digits. Other Unicode characters are
13036 _not_ allowed, regardless of the `use utf8' pragma.
13039 File: gettext.info, Node: Quote-like Expressions, Next: Interpolation I, Prev: Special Keywords, Up: Perl
13041 15.5.18.4 What are Strings And Quote-like Expressions?
13042 ......................................................
13044 Perl offers a plethora of different string constructs. Those that
13045 can be used either as arguments to functions or inside braces for hash
13046 lookups are generally supported by `xgettext'.
13048 * *double-quoted strings*
13049 print gettext "Hello World!";
13051 * *single-quoted strings*
13052 print gettext 'Hello World!';
13054 * *the operator qq*
13055 print gettext qq |Hello World!|;
13056 print gettext qq <E-mail: <guido\@imperia.net>>;
13058 The operator `qq' is fully supported. You can use arbitrary
13059 delimiters, including the four bracketing delimiters (round, angle,
13060 square, curly) that nest.
13063 print gettext q |Hello World!|;
13064 print gettext q <E-mail: <guido@imperia.net>>;
13066 The operator `q' is fully supported. You can use arbitrary
13067 delimiters, including the four bracketing delimiters (round, angle,
13068 square, curly) that nest.
13070 * *the operator qx*
13071 print gettext qx ;LANGUAGE=C /bin/date;
13072 print gettext qx [/usr/bin/ls | grep '^[A-Z]*'];
13074 The operator `qx' is fully supported. You can use arbitrary
13075 delimiters, including the four bracketing delimiters (round, angle,
13076 square, curly) that nest.
13078 The example is actually a useless use of `gettext'. It will
13079 invoke the `gettext' function on the output of the command
13080 specified with the `qx' operator. The feature was included in
13081 order to make the interface consistent (the parser will extract
13082 all strings and quote-like expressions).
13085 print gettext <<'EOF';
13086 program not found in $PATH
13089 print ngettext <<EOF, <<"EOF";
13092 several files deleted
13095 Here-documents are recognized. If the delimiter is enclosed in
13096 single quotes, the string is not interpolated. If it is enclosed
13097 in double quotes or has no quotes at all, the string is
13100 Delimiters that start with a digit are not supported!
13104 File: gettext.info, Node: Interpolation I, Next: Interpolation II, Prev: Quote-like Expressions, Up: Perl
13106 15.5.18.5 Invalid Uses Of String Interpolation
13107 ..............................................
13109 Perl is capable of interpolating variables into strings. This offers
13110 some nice features in localized programs but can also lead to problems.
13112 A common error is a construct like the following:
13114 print gettext "This is the program $0!\n";
13116 Perl will interpolate at runtime the value of the variable `$0' into
13117 the argument of the `gettext()' function. Hence, this argument is not
13118 a string constant but a variable argument (`$0' is a global variable
13119 that holds the name of the Perl script being executed). The
13120 interpolation is performed by Perl before the string argument is passed
13121 to `gettext()' and will therefore depend on the name of the script
13122 which can only be determined at runtime. Consequently, it is almost
13123 impossible that a translation can be looked up at runtime (except if,
13124 by accident, the interpolated string is found in the message catalog).
13126 The `xgettext' program will therefore terminate parsing with a fatal
13127 error if it encounters a variable inside of an extracted string. In
13128 general, this will happen for all kinds of string interpolations that
13129 cannot be safely performed at compile time. If you absolutely know
13130 what you are doing, you can always circumvent this behavior:
13132 my $know_what_i_am_doing = "This is program $0!\n";
13133 print gettext $know_what_i_am_doing;
13135 Since the parser only recognizes strings and quote-like expressions,
13136 but not variables or other terms, the above construct will be accepted.
13137 You will have to find another way, however, to let your original string
13138 make it into your message catalog.
13140 If invoked with the option `--extract-all', resp. `-a', variable
13141 interpolation will be accepted. Rationale: You will generally use this
13142 option in order to prepare your sources for internationalization.
13144 Please see the manual page `man perlop' for details of strings and
13145 quote-like expressions that are subject to interpolation and those that
13146 are not. Safe interpolations (that will not lead to a fatal error) are:
13148 * the escape sequences `\t' (tab, HT, TAB), `\n' (newline, NL), `\r'
13149 (return, CR), `\f' (form feed, FF), `\b' (backspace, BS), `\a'
13150 (alarm, bell, BEL), and `\e' (escape, ESC).
13152 * octal chars, like `\033'
13153 Note that octal escapes in the range of 400-777 are translated
13154 into a UTF-8 representation, regardless of the presence of the
13157 * hex chars, like `\x1b'
13159 * wide hex chars, like `\x{263a}'
13160 Note that this escape is translated into a UTF-8 representation,
13161 regardless of the presence of the `use utf8' pragma.
13163 * control chars, like `\c[' (CTRL-[)
13165 * named Unicode chars, like `\N{LATIN CAPITAL LETTER C WITH CEDILLA}'
13166 Note that this escape is translated into a UTF-8 representation,
13167 regardless of the presence of the `use utf8' pragma.
13169 The following escapes are considered partially safe:
13171 * `\l' lowercase next char
13173 * `\u' uppercase next char
13175 * `\L' lowercase till \E
13177 * `\U' uppercase till \E
13179 * `\E' end case modification
13181 * `\Q' quote non-word characters till \E
13184 These escapes are only considered safe if the string consists of
13185 ASCII characters only. Translation of characters outside the range
13186 defined by ASCII is locale-dependent and can actually only be performed
13187 at runtime; `xgettext' doesn't do these locale-dependent translations
13188 at extraction time.
13190 Except for the modifier `\Q', these translations, albeit valid, are
13191 generally useless and only obfuscate your sources. If a translation
13192 can be safely performed at compile time you can just as well write what
13196 File: gettext.info, Node: Interpolation II, Next: Parentheses, Prev: Interpolation I, Up: Perl
13198 15.5.18.6 Valid Uses Of String Interpolation
13199 ............................................
13201 Perl is often used to generate sources for other programming
13202 languages or arbitrary file formats. Web applications that output HTML
13203 code make a prominent example for such usage.
13205 You will often come across situations where you want to intersperse
13206 code written in the target (programming) language with translatable
13207 messages, like in the following HTML example:
13209 print gettext <<EOF;
13210 <h1>My Homepage</h1>
13211 <script language="JavaScript"><!--
13212 for (i = 0; i < 100; ++i) {
13213 alert ("Thank you so much for visiting my homepage!");
13218 The parser will extract the entire here document, and it will appear
13219 entirely in the resulting PO file, including the JavaScript snippet
13220 embedded in the HTML code. If you exaggerate with constructs like the
13221 above, you will run the risk that the translators of your package will
13222 look out for a less challenging project. You should consider an
13223 alternative expression here:
13226 <h1>$gettext{"My Homepage"}</h1>
13227 <script language="JavaScript"><!--
13228 for (i = 0; i < 100; ++i) {
13229 alert ("$gettext{'Thank you so much for visiting my homepage!'}");
13234 Only the translatable portions of the code will be extracted here,
13235 and the resulting PO file will begrudgingly improve in terms of
13238 You can interpolate hash lookups in all strings or quote-like
13239 expressions that are subject to interpolation (see the manual page `man
13240 perlop' for details). Double interpolation is invalid, however:
13242 # TRANSLATORS: Replace "the earth" with the name of your planet.
13243 print gettext qq{Welcome to $gettext->{"the earth"}};
13245 The `qq'-quoted string is recognized as an argument to `xgettext' in
13246 the first place, and checked for invalid variable interpolation. The
13247 dollar sign of hash-dereferencing will therefore terminate the parser
13248 with an "invalid interpolation" error.
13250 It is valid to interpolate hash lookups in regular expressions:
13252 if ($var =~ /$gettext{"the earth"}/) {
13253 print gettext "Match!\n";
13255 s/$gettext{"U. S. A."}/$gettext{"U. S. A."} $gettext{"(dial +0)"}/g;
13258 File: gettext.info, Node: Parentheses, Next: Long Lines, Prev: Interpolation II, Up: Perl
13260 15.5.18.7 When To Use Parentheses
13261 .................................
13263 In Perl, parentheses around function arguments are mostly optional.
13264 `xgettext' will always assume that all recognized keywords (except for
13265 hashes and hash references) are names of properly prototyped functions,
13266 and will (hopefully) only require parentheses where Perl itself
13267 requires them. All constructs in the following example are therefore
13270 print gettext ("Hello World!\n");
13271 print gettext "Hello World!\n";
13272 print dgettext ($package => "Hello World!\n");
13273 print dgettext $package, "Hello World!\n";
13275 # The "fat comma" => turns the left-hand side argument into a
13276 # single-quoted string!
13277 print dgettext smellovision => "Hello World!\n";
13279 # The following assignment only works with prototyped functions.
13280 # Otherwise, the functions will act as "greedy" list operators and
13281 # eat up all following arguments.
13282 my $anonymous_hash = {
13283 planet => gettext "earth",
13284 cakes => ngettext "one cake", "several cakes", $n,
13287 # The same without fat comma:
13289 'planet', gettext "earth",
13290 'cakes', ngettext "one cake", "several cakes", $n,
13294 # Parentheses are only significant for the first argument.
13295 print dngettext 'package', ("one cake", "several cakes", $n), $discarded;
13298 File: gettext.info, Node: Long Lines, Next: Perl Pitfalls, Prev: Parentheses, Up: Perl
13300 15.5.18.8 How To Grok with Long Lines
13301 .....................................
13303 The necessity of long messages can often lead to a cumbersome or
13304 unreadable coding style. Perl has several options that may prevent you
13305 from writing unreadable code, and `xgettext' does its best to do
13306 likewise. This is where the dot operator (the string concatenation
13307 operator) may come in handy:
13309 print gettext ("This is a very long"
13310 . " message that is still"
13311 . " readable, because"
13312 . " it is split into"
13313 . " multiple lines.\n");
13315 Perl is smart enough to concatenate these constant string fragments
13316 into one long string at compile time, and so is `xgettext'. You will
13317 only find one long message in the resulting POT file.
13319 Note that the future Perl 6 will probably use the underscore (`_')
13320 as the string concatenation operator, and the dot (`.') for
13321 dereferencing. This new syntax is not yet supported by `xgettext'.
13323 If embedded newline characters are not an issue, or even desired, you
13324 may also insert newline characters inside quoted strings wherever you
13327 print gettext ("<em>In HTML output
13328 embedded newlines are generally no
13329 problem, since adjacent whitespace
13330 is always rendered into a single
13331 space character.</em>");
13333 You may also consider to use here documents:
13335 print gettext <<EOF;
13337 embedded newlines are generally no
13338 problem, since adjacent whitespace
13339 is always rendered into a single
13340 space character.</em>
13343 Please do not forget that the line breaks are real, i.e. they
13344 translate into newline characters that will consequently show up in the
13345 resulting POT file.
13348 File: gettext.info, Node: Perl Pitfalls, Prev: Long Lines, Up: Perl
13350 15.5.18.9 Bugs, Pitfalls, And Things That Do Not Work
13351 .....................................................
13353 The foregoing sections should have proven that `xgettext' is quite
13354 smart in extracting translatable strings from Perl sources. Yet, some
13355 more or less exotic constructs that could be expected to work, actually
13358 One of the more relevant limitations can be found in the
13359 implementation of variable interpolation inside quoted strings. Only
13360 simple hash lookups can be used there:
13363 $gettext{"The dot operator"
13366 Likewise, you cannot @{[ gettext ("interpolate function calls") ]}
13367 inside quoted strings or quote-like expressions.
13370 This is valid Perl code and will actually trigger invocations of the
13371 `gettext' function at runtime. Yet, the Perl parser in `xgettext' will
13372 fail to recognize the strings. A less obvious example can be found in
13373 the interpolation of regular expressions:
13375 s/<!--START_OF_WEEK-->/gettext ("Sunday")/e;
13377 The modifier `e' will cause the substitution to be interpreted as an
13378 evaluable statement. Consequently, at runtime the function `gettext()'
13379 is called, but again, the parser fails to extract the string "Sunday".
13380 Use a temporary variable as a simple workaround if you really happen to
13383 my $sunday = gettext "Sunday";
13384 s/<!--START_OF_WEEK-->/$sunday/;
13386 Hash slices would also be handy but are not recognized:
13388 my @weekdays = @gettext{'Sunday', 'Monday', 'Tuesday', 'Wednesday',
13389 'Thursday', 'Friday', 'Saturday'};
13391 @weekdays = @gettext{qw (Sunday Monday Tuesday Wednesday Thursday
13392 Friday Saturday) };
13394 This is perfectly valid usage of the tied hash `%gettext' but the
13395 strings are not recognized and therefore will not be extracted.
13397 Another caveat of the current version is its rudimentary support for
13398 non-ASCII characters in identifiers. You may encounter serious
13399 problems if you use identifiers with characters outside the range of
13400 'A'-'Z', 'a'-'z', '0'-'9' and the underscore '_'.
13402 Maybe some of these missing features will be implemented in future
13403 versions, but since you can always make do without them at minimal
13404 effort, these todos have very low priority.
13406 A nasty problem are brace format strings that already contain braces
13407 as part of the normal text, for example the usage strings typically
13408 encountered in programs:
13410 die "usage: $0 {OPTIONS} FILENAME...\n";
13412 If you want to internationalize this code with Perl brace format
13413 strings, you will run into a problem:
13415 die __x ("usage: {program} {OPTIONS} FILENAME...\n", program => $0);
13417 Whereas `{program}' is a placeholder, `{OPTIONS}' is not and should
13418 probably be translated. Yet, there is no way to teach the Perl parser
13419 in `xgettext' to recognize the first one, and leave the other one alone.
13421 There are two possible work-arounds for this problem. If you are
13422 sure that your program will run under Perl 5.8.0 or newer (these Perl
13423 versions handle positional parameters in `printf()') or if you are sure
13424 that the translator will not have to reorder the arguments in her
13425 translation - for example if you have only one brace placeholder in
13426 your string, or if it describes a syntax, like in this one -, you can
13427 mark the string as `no-perl-brace-format' and use `printf()':
13429 # xgettext: no-perl-brace-format
13430 die sprintf ("usage: %s {OPTIONS} FILENAME...\n", $0);
13432 If you want to use the more portable Perl brace format, you will
13433 have to do put placeholders in place of the literal braces:
13435 die __x ("usage: {program} {[}OPTIONS{]} FILENAME...\n",
13436 program => $0, '[' => '{', ']' => '}');
13438 Perl brace format strings know no escaping mechanism. No matter how
13439 this escaping mechanism looked like, it would either give the
13440 programmer a hard time, make translating Perl brace format strings
13441 heavy-going, or result in a performance penalty at runtime, when the
13442 format directives get executed. Most of the time you will happily get
13443 along with `printf()' for this special case.
13446 File: gettext.info, Node: PHP, Next: Pike, Prev: Perl, Up: List of Programming Languages
13448 15.5.19 PHP Hypertext Preprocessor
13449 ----------------------------------
13452 mod_php4, mod_php4-core, phpdoc
13455 `php', `php3', `php4'
13463 gettext/ngettext functions
13464 `gettext', `dgettext', `dcgettext'; starting with PHP 4.2.0 also
13465 `ngettext', `dngettext', `dcngettext'
13468 `textdomain' function
13471 `bindtextdomain' function
13474 Programmer must call `setlocale (LC_ALL, "")'
13479 Use or emulate GNU gettext
13485 Formatting with positions
13486 `printf "%2\$d %1\$d"'
13489 On platforms without gettext, the functions are not available.
13494 An example is available in the `examples' directory: `hello-php'.
13497 File: gettext.info, Node: Pike, Next: GCC-source, Prev: PHP, Up: List of Programming Languages
13514 gettext/ngettext functions
13515 `gettext', `dgettext', `dcgettext'
13518 `textdomain' function
13521 `bindtextdomain' function
13524 `setlocale' function
13527 `import Locale.Gettext;'
13529 Use or emulate GNU gettext
13535 Formatting with positions
13539 On platforms without gettext, the functions are not available.
13545 File: gettext.info, Node: GCC-source, Prev: Pike, Up: List of Programming Languages
13547 15.5.21 GNU Compiler Collection sources
13548 ---------------------------------------
13562 gettext/ngettext functions
13563 `gettext', `dgettext', `dcgettext', `ngettext', `dngettext',
13567 `textdomain' function
13570 `bindtextdomain' function
13573 Programmer must call `setlocale (LC_ALL, "")'
13576 `#include "intl.h"'
13578 Use or emulate GNU gettext
13584 Formatting with positions
13588 Uses autoconf macros
13594 File: gettext.info, Node: List of Data Formats, Prev: List of Programming Languages, Up: Programming Languages
13596 15.6 Internationalizable Data
13597 =============================
13599 Here is a list of other data formats which can be internationalized
13604 * POT:: POT - Portable Object Template
13605 * RST:: Resource String Table
13606 * Glade:: Glade - GNOME user interface description
13609 File: gettext.info, Node: POT, Next: RST, Prev: List of Data Formats, Up: List of Data Formats
13611 15.6.1 POT - Portable Object Template
13612 -------------------------------------
13624 File: gettext.info, Node: RST, Next: Glade, Prev: POT, Up: List of Data Formats
13626 15.6.2 Resource String Table
13627 ----------------------------
13636 `xgettext', `rstconv'
13639 File: gettext.info, Node: Glade, Prev: RST, Up: List of Data Formats
13641 15.6.3 Glade - GNOME user interface description
13642 -----------------------------------------------
13645 glade, libglade, glade2, libglade2, intltool
13651 `xgettext', `libglade-xgettext', `xml-i18n-extract',
13655 File: gettext.info, Node: Conclusion, Next: Language Codes, Prev: Programming Languages, Up: Top
13657 16 Concluding Remarks
13658 *********************
13660 We would like to conclude this GNU `gettext' manual by presenting an
13661 history of the Translation Project so far. We finally give a few
13662 pointers for those who want to do further research or readings about
13663 Native Language Support matters.
13667 * History:: History of GNU `gettext'
13668 * References:: Related Readings
13671 File: gettext.info, Node: History, Next: References, Prev: Conclusion, Up: Conclusion
13673 16.1 History of GNU `gettext'
13674 =============================
13676 Internationalization concerns and algorithms have been informally
13677 and casually discussed for years in GNU, sometimes around GNU `libc',
13678 maybe around the incoming `Hurd', or otherwise (nobody clearly
13679 remembers). And even then, when the work started for real, this was
13680 somewhat independently of these previous discussions.
13682 This all began in July 1994, when Patrick D'Cruze had the idea and
13683 initiative of internationalizing version 3.9.2 of GNU `fileutils'. He
13684 then asked Jim Meyering, the maintainer, how to get those changes
13685 folded into an official release. That first draft was full of
13686 `#ifdef's and somewhat disconcerting, and Jim wanted to find nicer
13687 ways. Patrick and Jim shared some tries and experimentations in this
13688 area. Then, feeling that this might eventually have a deeper impact on
13689 GNU, Jim wanted to know what standards were, and contacted Richard
13690 Stallman, who very quickly and verbally described an overall design for
13691 what was meant to become `glocale', at that time.
13693 Jim implemented `glocale' and got a lot of exhausting feedback from
13694 Patrick and Richard, of course, but also from Mitchum DSouza (who wrote
13695 a `catgets'-like package), Roland McGrath, maybe David MacKenzie,
13696 François Pinard, and Paul Eggert, all pushing and pulling in various
13697 directions, not always compatible, to the extent that after a couple of
13698 test releases, `glocale' was torn apart. In particular, Paul Eggert -
13699 always keeping an eye on developments in Solaris - advocated the use of
13700 the `gettext' API over `glocale''s `catgets'-based API.
13702 While Jim took some distance and time and became dad for a second
13703 time, Roland wanted to get GNU `libc' internationalized, and got Ulrich
13704 Drepper involved in that project. Instead of starting from `glocale',
13705 Ulrich rewrote something from scratch, but more conforming to the set
13706 of guidelines who emerged out of the `glocale' effort. Then, Ulrich
13707 got people from the previous forum to involve themselves into this new
13708 project, and the switch from `glocale' to what was first named
13709 `msgutils', renamed `nlsutils', and later `gettext', became officially
13710 accepted by Richard in May 1995 or so.
13712 Let's summarize by saying that Ulrich Drepper wrote GNU `gettext' in
13713 April 1995. The first official release of the package, including PO
13714 mode, occurred in July 1995, and was numbered 0.7. Other people
13715 contributed to the effort by providing a discussion forum around
13716 Ulrich, writing little pieces of code, or testing. These are quoted in
13717 the `THANKS' file which comes with the GNU `gettext' distribution.
13719 While this was being done, François adapted half a dozen of GNU
13720 packages to `glocale' first, then later to `gettext', putting them in
13721 pretest, so providing along the way an effective user environment for
13722 fine tuning the evolving tools. He also took the responsibility of
13723 organizing and coordinating the Translation Project. After nearly a
13724 year of informal exchanges between people from many countries,
13725 translator teams started to exist in May 1995, through the creation and
13726 support by Patrick D'Cruze of twenty unmoderated mailing lists for that
13727 many native languages, and two moderated lists: one for reaching all
13728 teams at once, the other for reaching all willing maintainers of
13729 internationalized free software packages.
13731 François also wrote PO mode in June 1995 with the collaboration of
13732 Greg McGary, as a kind of contribution to Ulrich's package. He also
13733 gave a hand with the GNU `gettext' Texinfo manual.
13735 In 1997, Ulrich Drepper released the GNU libc 2.0, which included the
13736 `gettext', `textdomain' and `bindtextdomain' functions.
13738 In 2000, Ulrich Drepper added plural form handling (the `ngettext'
13739 function) to GNU libc. Later, in 2001, he released GNU libc 2.2.x,
13740 which is the first free C library with full internationalization
13743 Ulrich being quite busy in his role of General Maintainer of GNU
13744 libc, he handed over the GNU `gettext' maintenance to Bruno Haible in
13745 2000. Bruno added the plural form handling to the tools as well, added
13746 support for UTF-8 and CJK locales, and wrote a few new tools for
13747 manipulating PO files.
13750 File: gettext.info, Node: References, Prev: History, Up: Conclusion
13752 16.2 Related Readings
13753 =====================
13755 * NOTE: * This documentation section is outdated and needs to be
13758 Eugene H. Dorr (`dorre@well.com') maintains an interesting
13759 bibliography on internationalization matters, called
13760 `Internationalization Reference List', which is available as:
13761 ftp://ftp.ora.com/pub/examples/nutshell/ujip/doc/i18n-books.txt
13763 Michael Gschwind (`mike@vlsivie.tuwien.ac.at') maintains a
13764 Frequently Asked Questions (FAQ) list, entitled `Programming for
13765 Internationalisation'. This FAQ discusses writing programs which can
13766 handle different language conventions, character sets, etc.; and is
13767 applicable to all character set encodings, with particular emphasis on
13768 ISO 8859-1. It is regularly published in Usenet groups
13769 `comp.unix.questions', `comp.std.internat',
13770 `comp.software.international', `comp.lang.c', `comp.windows.x',
13771 `comp.std.c', `comp.answers' and `news.answers'. The home location of
13773 ftp://ftp.vlsivie.tuwien.ac.at/pub/8bit/ISO-programming
13775 Patrick D'Cruze (`pdcruze@li.org') wrote a tutorial about NLS
13776 matters, and Jochen Hein (`Hein@student.tu-clausthal.de') took over the
13777 responsibility of maintaining it. It may be found as:
13778 ftp://sunsite.unc.edu/pub/Linux/utils/nls/catalogs/Incoming/...
13779 ...locale-tutorial-0.8.txt.gz
13780 This site is mirrored in:
13781 ftp://ftp.ibp.fr/pub/linux/sunsite/
13783 A French version of the same tutorial should be findable at:
13784 ftp://ftp.ibp.fr/pub/linux/french/docs/
13785 together with French translations of many Linux-related documents.
13788 File: gettext.info, Node: Language Codes, Next: Country Codes, Prev: Conclusion, Up: Top
13790 Appendix A Language Codes
13791 *************************
13793 The ISO 639 standard defines two-letter codes for many languages, and
13794 three-letter codes for more rarely used languages. All abbreviations
13795 for languages used in the Translation Project should come from this
13800 * Usual Language Codes:: Two-letter ISO 639 language codes
13801 * Rare Language Codes:: Three-letter ISO 639 language codes
13804 File: gettext.info, Node: Usual Language Codes, Next: Rare Language Codes, Prev: Language Codes, Up: Language Codes
13806 A.1 Usual Language Codes
13807 ========================
13809 For the commonly used languages, the ISO 639-1 standard defines
13981 Hebrew (formerly iw).
13993 Haitian; Haitian Creole.
14008 Indonesian (formerly in).
14011 Interlingue; Occidental.
14050 Kuanyama; Kwanyama.
14056 Kalaallisut; Greenlandic.
14059 Central Khmer; Cambodian.
14089 Letzeburgesch; Luxembourgish.
14095 Limburgish; Limburger; Limburgan.
14179 Occitan; Provençal.
14242 Sinhala; Sinhalese.
14269 Sesotho; Sotho, Southern.
14353 Yiddish (formerly ji).
14368 File: gettext.info, Node: Rare Language Codes, Prev: Usual Language Codes, Up: Language Codes
14370 A.2 Rare Language Codes
14371 =======================
14373 For rarely used languages, the ISO 639-2 standard defines
14374 three-letter codes. Here is the current list, reduced to only living
14375 languages with at least one million of speakers.
14417 Filipino; Pilipino.
14426 Swiss German; Alemannic; Alsatian.
14459 Luo (Kenya and Tanzania).
14495 Pedi; Sepedi; Northern Sotho.
14507 Pampanga; Kapampangan.
14558 File: gettext.info, Node: Country Codes, Next: Licenses, Prev: Language Codes, Up: Top
14560 Appendix B Country Codes
14561 ************************
14563 The ISO 3166 standard defines two character codes for many countries
14564 and territories. All abbreviations for countries used in the
14565 Translation Project should come from this standard.
14571 United Arab Emirates.
14577 Antigua and Barbuda.
14589 Netherlands Antilles.
14619 Bosnia and Herzegovina.
14679 Cocos (Keeling) Islands.
14685 Central African Republic.
14742 Dominican Republic.
14790 Britain (United Kingdom).
14829 South Georgia and the South Sandwich Islands.
14847 Heard Island and McDonald Islands.
14877 British Indian Ocean Territory.
14919 St Kitts and Nevis.
15003 Northern Mariana Islands.
15096 St Pierre and Miquelon.
15159 Svalbard and Jan Mayen.
15180 Sao Tome and Principe.
15192 Turks and Caicos Islands.
15198 French Southern and Antarctic Lands.
15228 Trinidad and Tobago.
15246 US minor outlying islands.
15261 St Vincent and the Grenadines.
15267 Virgin Islands (UK).
15270 Virgin Islands (US).
15300 File: gettext.info, Node: Licenses, Next: Program Index, Prev: Country Codes, Up: Top
15302 Appendix C Licenses
15303 *******************
15305 The files of this package are covered by the licenses indicated in
15306 each particular file or directory. Here is a summary:
15308 * The `libintl' and `libasprintf' libraries are covered by the GNU
15309 Library General Public License (LGPL). A copy of the license is
15310 included in *note GNU LGPL::.
15312 * The executable programs of this package and the `libgettextpo'
15313 library are covered by the GNU General Public License (GPL). A
15314 copy of the license is included in *note GNU GPL::.
15316 * This manual is free documentation. It is dually licensed under the
15317 GNU FDL and the GNU GPL. This means that you can redistribute this
15318 manual under either of these two licenses, at your choice.
15319 This manual is covered by the GNU FDL. Permission is granted to
15320 copy, distribute and/or modify this document under the terms of the
15321 GNU Free Documentation License (FDL), either version 1.2 of the
15322 License, or (at your option) any later version published by the
15323 Free Software Foundation (FSF); with no Invariant Sections, with no
15324 Front-Cover Text, and with no Back-Cover Texts. A copy of the
15325 license is included in *note GNU FDL::.
15326 This manual is covered by the GNU GPL. You can redistribute it
15327 and/or modify it under the terms of the GNU General Public License
15328 (GPL), either version 2 of the License, or (at your option) any
15329 later version published by the Free Software Foundation (FSF). A
15330 copy of the license is included in *note GNU GPL::.
15334 * GNU GPL:: GNU General Public License
15335 * GNU LGPL:: GNU Lesser General Public License
15336 * GNU FDL:: GNU Free Documentation License
15339 File: gettext.info, Node: GNU GPL, Next: GNU LGPL, Up: Licenses
15341 C.1 GNU GENERAL PUBLIC LICENSE
15342 ==============================
15344 Version 2, June 1991
15346 Copyright (C) 1989, 1991 Free Software Foundation, Inc.
15347 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
15349 Everyone is permitted to copy and distribute verbatim copies
15350 of this license document, but changing it is not allowed.
15355 The licenses for most software are designed to take away your
15356 freedom to share and change it. By contrast, the GNU General Public
15357 License is intended to guarantee your freedom to share and change free
15358 software--to make sure the software is free for all its users. This
15359 General Public License applies to most of the Free Software
15360 Foundation's software and to any other program whose authors commit to
15361 using it. (Some other Free Software Foundation software is covered by
15362 the GNU Library General Public License instead.) You can apply it to
15363 your programs, too.
15365 When we speak of free software, we are referring to freedom, not
15366 price. Our General Public Licenses are designed to make sure that you
15367 have the freedom to distribute copies of free software (and charge for
15368 this service if you wish), that you receive source code or can get it
15369 if you want it, that you can change the software or use pieces of it in
15370 new free programs; and that you know you can do these things.
15372 To protect your rights, we need to make restrictions that forbid
15373 anyone to deny you these rights or to ask you to surrender the rights.
15374 These restrictions translate to certain responsibilities for you if you
15375 distribute copies of the software, or if you modify it.
15377 For example, if you distribute copies of such a program, whether
15378 gratis or for a fee, you must give the recipients all the rights that
15379 you have. You must make sure that they, too, receive or can get the
15380 source code. And you must show them these terms so they know their
15383 We protect your rights with two steps: (1) copyright the software,
15384 and (2) offer you this license which gives you legal permission to copy,
15385 distribute and/or modify the software.
15387 Also, for each author's protection and ours, we want to make certain
15388 that everyone understands that there is no warranty for this free
15389 software. If the software is modified by someone else and passed on, we
15390 want its recipients to know that what they have is not the original, so
15391 that any problems introduced by others will not reflect on the original
15392 authors' reputations.
15394 Finally, any free program is threatened constantly by software
15395 patents. We wish to avoid the danger that redistributors of a free
15396 program will individually obtain patent licenses, in effect making the
15397 program proprietary. To prevent this, we have made it clear that any
15398 patent must be licensed for everyone's free use or not licensed at all.
15400 The precise terms and conditions for copying, distribution and
15401 modification follow.
15403 TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
15405 0. This License applies to any program or other work which contains a
15406 notice placed by the copyright holder saying it may be distributed
15407 under the terms of this General Public License. The "Program",
15408 below, refers to any such program or work, and a "work based on
15409 the Program" means either the Program or any derivative work under
15410 copyright law: that is to say, a work containing the Program or a
15411 portion of it, either verbatim or with modifications and/or
15412 translated into another language. (Hereinafter, translation is
15413 included without limitation in the term "modification".) Each
15414 licensee is addressed as "you".
15416 Activities other than copying, distribution and modification are
15417 not covered by this License; they are outside its scope. The act
15418 of running the Program is not restricted, and the output from the
15419 Program is covered only if its contents constitute a work based on
15420 the Program (independent of having been made by running the
15421 Program). Whether that is true depends on what the Program does.
15423 1. You may copy and distribute verbatim copies of the Program's
15424 source code as you receive it, in any medium, provided that you
15425 conspicuously and appropriately publish on each copy an appropriate
15426 copyright notice and disclaimer of warranty; keep intact all the
15427 notices that refer to this License and to the absence of any
15428 warranty; and give any other recipients of the Program a copy of
15429 this License along with the Program.
15431 You may charge a fee for the physical act of transferring a copy,
15432 and you may at your option offer warranty protection in exchange
15435 2. You may modify your copy or copies of the Program or any portion
15436 of it, thus forming a work based on the Program, and copy and
15437 distribute such modifications or work under the terms of Section 1
15438 above, provided that you also meet all of these conditions:
15440 a. You must cause the modified files to carry prominent notices
15441 stating that you changed the files and the date of any change.
15443 b. You must cause any work that you distribute or publish, that
15444 in whole or in part contains or is derived from the Program
15445 or any part thereof, to be licensed as a whole at no charge
15446 to all third parties under the terms of this License.
15448 c. If the modified program normally reads commands interactively
15449 when run, you must cause it, when started running for such
15450 interactive use in the most ordinary way, to print or display
15451 an announcement including an appropriate copyright notice and
15452 a notice that there is no warranty (or else, saying that you
15453 provide a warranty) and that users may redistribute the
15454 program under these conditions, and telling the user how to
15455 view a copy of this License. (Exception: if the Program
15456 itself is interactive but does not normally print such an
15457 announcement, your work based on the Program is not required
15458 to print an announcement.)
15460 These requirements apply to the modified work as a whole. If
15461 identifiable sections of that work are not derived from the
15462 Program, and can be reasonably considered independent and separate
15463 works in themselves, then this License, and its terms, do not
15464 apply to those sections when you distribute them as separate
15465 works. But when you distribute the same sections as part of a
15466 whole which is a work based on the Program, the distribution of
15467 the whole must be on the terms of this License, whose permissions
15468 for other licensees extend to the entire whole, and thus to each
15469 and every part regardless of who wrote it.
15471 Thus, it is not the intent of this section to claim rights or
15472 contest your rights to work written entirely by you; rather, the
15473 intent is to exercise the right to control the distribution of
15474 derivative or collective works based on the Program.
15476 In addition, mere aggregation of another work not based on the
15477 Program with the Program (or with a work based on the Program) on
15478 a volume of a storage or distribution medium does not bring the
15479 other work under the scope of this License.
15481 3. You may copy and distribute the Program (or a work based on it,
15482 under Section 2) in object code or executable form under the terms
15483 of Sections 1 and 2 above provided that you also do one of the
15486 a. Accompany it with the complete corresponding machine-readable
15487 source code, which must be distributed under the terms of
15488 Sections 1 and 2 above on a medium customarily used for
15489 software interchange; or,
15491 b. Accompany it with a written offer, valid for at least three
15492 years, to give any third party, for a charge no more than your
15493 cost of physically performing source distribution, a complete
15494 machine-readable copy of the corresponding source code, to be
15495 distributed under the terms of Sections 1 and 2 above on a
15496 medium customarily used for software interchange; or,
15498 c. Accompany it with the information you received as to the offer
15499 to distribute corresponding source code. (This alternative is
15500 allowed only for noncommercial distribution and only if you
15501 received the program in object code or executable form with
15502 such an offer, in accord with Subsection b above.)
15504 The source code for a work means the preferred form of the work for
15505 making modifications to it. For an executable work, complete
15506 source code means all the source code for all modules it contains,
15507 plus any associated interface definition files, plus the scripts
15508 used to control compilation and installation of the executable.
15509 However, as a special exception, the source code distributed need
15510 not include anything that is normally distributed (in either
15511 source or binary form) with the major components (compiler,
15512 kernel, and so on) of the operating system on which the executable
15513 runs, unless that component itself accompanies the executable.
15515 If distribution of executable or object code is made by offering
15516 access to copy from a designated place, then offering equivalent
15517 access to copy the source code from the same place counts as
15518 distribution of the source code, even though third parties are not
15519 compelled to copy the source along with the object code.
15521 4. You may not copy, modify, sublicense, or distribute the Program
15522 except as expressly provided under this License. Any attempt
15523 otherwise to copy, modify, sublicense or distribute the Program is
15524 void, and will automatically terminate your rights under this
15525 License. However, parties who have received copies, or rights,
15526 from you under this License will not have their licenses
15527 terminated so long as such parties remain in full compliance.
15529 5. You are not required to accept this License, since you have not
15530 signed it. However, nothing else grants you permission to modify
15531 or distribute the Program or its derivative works. These actions
15532 are prohibited by law if you do not accept this License.
15533 Therefore, by modifying or distributing the Program (or any work
15534 based on the Program), you indicate your acceptance of this
15535 License to do so, and all its terms and conditions for copying,
15536 distributing or modifying the Program or works based on it.
15538 6. Each time you redistribute the Program (or any work based on the
15539 Program), the recipient automatically receives a license from the
15540 original licensor to copy, distribute or modify the Program
15541 subject to these terms and conditions. You may not impose any
15542 further restrictions on the recipients' exercise of the rights
15543 granted herein. You are not responsible for enforcing compliance
15544 by third parties to this License.
15546 7. If, as a consequence of a court judgment or allegation of patent
15547 infringement or for any other reason (not limited to patent
15548 issues), conditions are imposed on you (whether by court order,
15549 agreement or otherwise) that contradict the conditions of this
15550 License, they do not excuse you from the conditions of this
15551 License. If you cannot distribute so as to satisfy simultaneously
15552 your obligations under this License and any other pertinent
15553 obligations, then as a consequence you may not distribute the
15554 Program at all. For example, if a patent license would not permit
15555 royalty-free redistribution of the Program by all those who
15556 receive copies directly or indirectly through you, then the only
15557 way you could satisfy both it and this License would be to refrain
15558 entirely from distribution of the Program.
15560 If any portion of this section is held invalid or unenforceable
15561 under any particular circumstance, the balance of the section is
15562 intended to apply and the section as a whole is intended to apply
15563 in other circumstances.
15565 It is not the purpose of this section to induce you to infringe any
15566 patents or other property right claims or to contest validity of
15567 any such claims; this section has the sole purpose of protecting
15568 the integrity of the free software distribution system, which is
15569 implemented by public license practices. Many people have made
15570 generous contributions to the wide range of software distributed
15571 through that system in reliance on consistent application of that
15572 system; it is up to the author/donor to decide if he or she is
15573 willing to distribute software through any other system and a
15574 licensee cannot impose that choice.
15576 This section is intended to make thoroughly clear what is believed
15577 to be a consequence of the rest of this License.
15579 8. If the distribution and/or use of the Program is restricted in
15580 certain countries either by patents or by copyrighted interfaces,
15581 the original copyright holder who places the Program under this
15582 License may add an explicit geographical distribution limitation
15583 excluding those countries, so that distribution is permitted only
15584 in or among countries not thus excluded. In such case, this
15585 License incorporates the limitation as if written in the body of
15588 9. The Free Software Foundation may publish revised and/or new
15589 versions of the General Public License from time to time. Such
15590 new versions will be similar in spirit to the present version, but
15591 may differ in detail to address new problems or concerns.
15593 Each version is given a distinguishing version number. If the
15594 Program specifies a version number of this License which applies
15595 to it and "any later version", you have the option of following
15596 the terms and conditions either of that version or of any later
15597 version published by the Free Software Foundation. If the Program
15598 does not specify a version number of this License, you may choose
15599 any version ever published by the Free Software Foundation.
15601 10. If you wish to incorporate parts of the Program into other free
15602 programs whose distribution conditions are different, write to the
15603 author to ask for permission. For software which is copyrighted
15604 by the Free Software Foundation, write to the Free Software
15605 Foundation; we sometimes make exceptions for this. Our decision
15606 will be guided by the two goals of preserving the free status of
15607 all derivatives of our free software and of promoting the sharing
15608 and reuse of software generally.
15612 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO
15613 WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE
15614 LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
15615 HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT
15616 WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT
15617 NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
15618 FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE
15619 QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
15620 PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
15621 SERVICING, REPAIR OR CORRECTION.
15623 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
15624 WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
15625 MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE
15626 LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
15627 INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
15628 INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
15629 DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU
15630 OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY
15631 OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
15632 ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
15634 END OF TERMS AND CONDITIONS
15636 Appendix: How to Apply These Terms to Your New Programs
15637 -------------------------------------------------------
15639 If you develop a new program, and you want it to be of the greatest
15640 possible use to the public, the best way to achieve this is to make it
15641 free software which everyone can redistribute and change under these
15644 To do so, attach the following notices to the program. It is safest
15645 to attach them to the start of each source file to most effectively
15646 convey the exclusion of warranty; and each file should have at least
15647 the "copyright" line and a pointer to where the full notice is found.
15649 ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES.
15650 Copyright (C) YYYY NAME OF AUTHOR
15652 This program is free software; you can redistribute it and/or modify
15653 it under the terms of the GNU General Public License as published by
15654 the Free Software Foundation; either version 2 of the License, or
15655 (at your option) any later version.
15657 This program is distributed in the hope that it will be useful,
15658 but WITHOUT ANY WARRANTY; without even the implied warranty of
15659 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15660 GNU General Public License for more details.
15662 You should have received a copy of the GNU General Public License
15663 along with this program; if not, write to the Free Software
15664 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
15666 Also add information on how to contact you by electronic and paper
15669 If the program is interactive, make it output a short notice like
15670 this when it starts in an interactive mode:
15672 Gnomovision version 69, Copyright (C) 19YY NAME OF AUTHOR
15673 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
15674 This is free software, and you are welcome to redistribute it
15675 under certain conditions; type `show c' for details.
15677 The hypothetical commands `show w' and `show c' should show the
15678 appropriate parts of the General Public License. Of course, the
15679 commands you use may be called something other than `show w' and `show
15680 c'; they could even be mouse-clicks or menu items--whatever suits your
15683 You should also get your employer (if you work as a programmer) or
15684 your school, if any, to sign a "copyright disclaimer" for the program,
15685 if necessary. Here is a sample; alter the names:
15687 Yoyodyne, Inc., hereby disclaims all copyright interest in the program
15688 `Gnomovision' (which makes passes at compilers) written by James Hacker.
15690 SIGNATURE OF TY COON, 1 April 1989
15691 Ty Coon, President of Vice
15693 This General Public License does not permit incorporating your
15694 program into proprietary programs. If your program is a subroutine
15695 library, you may consider it more useful to permit linking proprietary
15696 applications with the library. If this is what you want to do, use the
15697 GNU Library General Public License instead of this License.
15700 File: gettext.info, Node: GNU LGPL, Next: GNU FDL, Prev: GNU GPL, Up: Licenses
15702 C.2 GNU LESSER GENERAL PUBLIC LICENSE
15703 =====================================
15705 Version 2.1, February 1999
15707 Copyright (C) 1991, 1999 Free Software Foundation, Inc.
15708 51 Franklin St - Fifth Floor, Boston, MA 02110-1301, USA
15710 Everyone is permitted to copy and distribute verbatim copies
15711 of this license document, but changing it is not allowed.
15713 [This is the first released version of the Lesser GPL. It also counts
15714 as the successor of the GNU Library Public License, version 2, hence the
15715 version number 2.1.]
15720 The licenses for most software are designed to take away your
15721 freedom to share and change it. By contrast, the GNU General Public
15722 Licenses are intended to guarantee your freedom to share and change
15723 free software--to make sure the software is free for all its users.
15725 This license, the Lesser General Public License, applies to some
15726 specially designated software--typically libraries--of the Free
15727 Software Foundation and other authors who decide to use it. You can use
15728 it too, but we suggest you first think carefully about whether this
15729 license or the ordinary General Public License is the better strategy to
15730 use in any particular case, based on the explanations below.
15732 When we speak of free software, we are referring to freedom of use,
15733 not price. Our General Public Licenses are designed to make sure that
15734 you have the freedom to distribute copies of free software (and charge
15735 for this service if you wish); that you receive source code or can get
15736 it if you want it; that you can change the software and use pieces of it
15737 in new free programs; and that you are informed that you can do these
15740 To protect your rights, we need to make restrictions that forbid
15741 distributors to deny you these rights or to ask you to surrender these
15742 rights. These restrictions translate to certain responsibilities for
15743 you if you distribute copies of the library or if you modify it.
15745 For example, if you distribute copies of the library, whether gratis
15746 or for a fee, you must give the recipients all the rights that we gave
15747 you. You must make sure that they, too, receive or can get the source
15748 code. If you link other code with the library, you must provide
15749 complete object files to the recipients, so that they can relink them
15750 with the library after making changes to the library and recompiling
15751 it. And you must show them these terms so they know their rights.
15753 We protect your rights with a two-step method: (1) we copyright the
15754 library, and (2) we offer you this license, which gives you legal
15755 permission to copy, distribute and/or modify the library.
15757 To protect each distributor, we want to make it very clear that
15758 there is no warranty for the free library. Also, if the library is
15759 modified by someone else and passed on, the recipients should know that
15760 what they have is not the original version, so that the original
15761 author's reputation will not be affected by problems that might be
15762 introduced by others.
15764 Finally, software patents pose a constant threat to the existence of
15765 any free program. We wish to make sure that a company cannot
15766 effectively restrict the users of a free program by obtaining a
15767 restrictive license from a patent holder. Therefore, we insist that
15768 any patent license obtained for a version of the library must be
15769 consistent with the full freedom of use specified in this license.
15771 Most GNU software, including some libraries, is covered by the
15772 ordinary GNU General Public License. This license, the GNU Lesser
15773 General Public License, applies to certain designated libraries, and is
15774 quite different from the ordinary General Public License. We use this
15775 license for certain libraries in order to permit linking those
15776 libraries into non-free programs.
15778 When a program is linked with a library, whether statically or using
15779 a shared library, the combination of the two is legally speaking a
15780 combined work, a derivative of the original library. The ordinary
15781 General Public License therefore permits such linking only if the
15782 entire combination fits its criteria of freedom. The Lesser General
15783 Public License permits more lax criteria for linking other code with
15786 We call this license the "Lesser" General Public License because it
15787 does _Less_ to protect the user's freedom than the ordinary General
15788 Public License. It also provides other free software developers Less
15789 of an advantage over competing non-free programs. These disadvantages
15790 are the reason we use the ordinary General Public License for many
15791 libraries. However, the Lesser license provides advantages in certain
15792 special circumstances.
15794 For example, on rare occasions, there may be a special need to
15795 encourage the widest possible use of a certain library, so that it
15796 becomes a de-facto standard. To achieve this, non-free programs must be
15797 allowed to use the library. A more frequent case is that a free
15798 library does the same job as widely used non-free libraries. In this
15799 case, there is little to gain by limiting the free library to free
15800 software only, so we use the Lesser General Public License.
15802 In other cases, permission to use a particular library in non-free
15803 programs enables a greater number of people to use a large body of free
15804 software. For example, permission to use the GNU C Library in non-free
15805 programs enables many more people to use the whole GNU operating
15806 system, as well as its variant, the GNU/Linux operating system.
15808 Although the Lesser General Public License is Less protective of the
15809 users' freedom, it does ensure that the user of a program that is
15810 linked with the Library has the freedom and the wherewithal to run that
15811 program using a modified version of the Library.
15813 The precise terms and conditions for copying, distribution and
15814 modification follow. Pay close attention to the difference between a
15815 "work based on the library" and a "work that uses the library". The
15816 former contains code derived from the library, whereas the latter must
15817 be combined with the library in order to run.
15819 GNU LESSER GENERAL PUBLIC LICENSE
15821 TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
15823 0. This License Agreement applies to any software library or other
15824 program which contains a notice placed by the copyright holder or
15825 other authorized party saying it may be distributed under the
15826 terms of this Lesser General Public License (also called "this
15827 License"). Each licensee is addressed as "you".
15829 A "library" means a collection of software functions and/or data
15830 prepared so as to be conveniently linked with application programs
15831 (which use some of those functions and data) to form executables.
15833 The "Library", below, refers to any such software library or work
15834 which has been distributed under these terms. A "work based on the
15835 Library" means either the Library or any derivative work under
15836 copyright law: that is to say, a work containing the Library or a
15837 portion of it, either verbatim or with modifications and/or
15838 translated straightforwardly into another language. (Hereinafter,
15839 translation is included without limitation in the term
15842 "Source code" for a work means the preferred form of the work for
15843 making modifications to it. For a library, complete source code
15844 means all the source code for all modules it contains, plus any
15845 associated interface definition files, plus the scripts used to
15846 control compilation and installation of the library.
15848 Activities other than copying, distribution and modification are
15849 not covered by this License; they are outside its scope. The act
15850 of running a program using the Library is not restricted, and
15851 output from such a program is covered only if its contents
15852 constitute a work based on the Library (independent of the use of
15853 the Library in a tool for writing it). Whether that is true
15854 depends on what the Library does and what the program that uses
15857 1. You may copy and distribute verbatim copies of the Library's
15858 complete source code as you receive it, in any medium, provided
15859 that you conspicuously and appropriately publish on each copy an
15860 appropriate copyright notice and disclaimer of warranty; keep
15861 intact all the notices that refer to this License and to the
15862 absence of any warranty; and distribute a copy of this License
15863 along with the Library.
15865 You may charge a fee for the physical act of transferring a copy,
15866 and you may at your option offer warranty protection in exchange
15869 2. You may modify your copy or copies of the Library or any portion
15870 of it, thus forming a work based on the Library, and copy and
15871 distribute such modifications or work under the terms of Section 1
15872 above, provided that you also meet all of these conditions:
15874 a. The modified work must itself be a software library.
15876 b. You must cause the files modified to carry prominent notices
15877 stating that you changed the files and the date of any change.
15879 c. You must cause the whole of the work to be licensed at no
15880 charge to all third parties under the terms of this License.
15882 d. If a facility in the modified Library refers to a function or
15883 a table of data to be supplied by an application program that
15884 uses the facility, other than as an argument passed when the
15885 facility is invoked, then you must make a good faith effort
15886 to ensure that, in the event an application does not supply
15887 such function or table, the facility still operates, and
15888 performs whatever part of its purpose remains meaningful.
15890 (For example, a function in a library to compute square roots
15891 has a purpose that is entirely well-defined independent of the
15892 application. Therefore, Subsection 2d requires that any
15893 application-supplied function or table used by this function
15894 must be optional: if the application does not supply it, the
15895 square root function must still compute square roots.)
15897 These requirements apply to the modified work as a whole. If
15898 identifiable sections of that work are not derived from the
15899 Library, and can be reasonably considered independent and separate
15900 works in themselves, then this License, and its terms, do not
15901 apply to those sections when you distribute them as separate
15902 works. But when you distribute the same sections as part of a
15903 whole which is a work based on the Library, the distribution of
15904 the whole must be on the terms of this License, whose permissions
15905 for other licensees extend to the entire whole, and thus to each
15906 and every part regardless of who wrote it.
15908 Thus, it is not the intent of this section to claim rights or
15909 contest your rights to work written entirely by you; rather, the
15910 intent is to exercise the right to control the distribution of
15911 derivative or collective works based on the Library.
15913 In addition, mere aggregation of another work not based on the
15914 Library with the Library (or with a work based on the Library) on
15915 a volume of a storage or distribution medium does not bring the
15916 other work under the scope of this License.
15918 3. You may opt to apply the terms of the ordinary GNU General Public
15919 License instead of this License to a given copy of the Library.
15920 To do this, you must alter all the notices that refer to this
15921 License, so that they refer to the ordinary GNU General Public
15922 License, version 2, instead of to this License. (If a newer
15923 version than version 2 of the ordinary GNU General Public License
15924 has appeared, then you can specify that version instead if you
15925 wish.) Do not make any other change in these notices.
15927 Once this change is made in a given copy, it is irreversible for
15928 that copy, so the ordinary GNU General Public License applies to
15929 all subsequent copies and derivative works made from that copy.
15931 This option is useful when you wish to copy part of the code of
15932 the Library into a program that is not a library.
15934 4. You may copy and distribute the Library (or a portion or
15935 derivative of it, under Section 2) in object code or executable
15936 form under the terms of Sections 1 and 2 above provided that you
15937 accompany it with the complete corresponding machine-readable
15938 source code, which must be distributed under the terms of Sections
15939 1 and 2 above on a medium customarily used for software
15942 If distribution of object code is made by offering access to copy
15943 from a designated place, then offering equivalent access to copy
15944 the source code from the same place satisfies the requirement to
15945 distribute the source code, even though third parties are not
15946 compelled to copy the source along with the object code.
15948 5. A program that contains no derivative of any portion of the
15949 Library, but is designed to work with the Library by being
15950 compiled or linked with it, is called a "work that uses the
15951 Library". Such a work, in isolation, is not a derivative work of
15952 the Library, and therefore falls outside the scope of this License.
15954 However, linking a "work that uses the Library" with the Library
15955 creates an executable that is a derivative of the Library (because
15956 it contains portions of the Library), rather than a "work that
15957 uses the library". The executable is therefore covered by this
15958 License. Section 6 states terms for distribution of such
15961 When a "work that uses the Library" uses material from a header
15962 file that is part of the Library, the object code for the work may
15963 be a derivative work of the Library even though the source code is
15964 not. Whether this is true is especially significant if the work
15965 can be linked without the Library, or if the work is itself a
15966 library. The threshold for this to be true is not precisely
15969 If such an object file uses only numerical parameters, data
15970 structure layouts and accessors, and small macros and small inline
15971 functions (ten lines or less in length), then the use of the object
15972 file is unrestricted, regardless of whether it is legally a
15973 derivative work. (Executables containing this object code plus
15974 portions of the Library will still fall under Section 6.)
15976 Otherwise, if the work is a derivative of the Library, you may
15977 distribute the object code for the work under the terms of Section
15978 6. Any executables containing that work also fall under Section 6,
15979 whether or not they are linked directly with the Library itself.
15981 6. As an exception to the Sections above, you may also combine or
15982 link a "work that uses the Library" with the Library to produce a
15983 work containing portions of the Library, and distribute that work
15984 under terms of your choice, provided that the terms permit
15985 modification of the work for the customer's own use and reverse
15986 engineering for debugging such modifications.
15988 You must give prominent notice with each copy of the work that the
15989 Library is used in it and that the Library and its use are covered
15990 by this License. You must supply a copy of this License. If the
15991 work during execution displays copyright notices, you must include
15992 the copyright notice for the Library among them, as well as a
15993 reference directing the user to the copy of this License. Also,
15994 you must do one of these things:
15996 a. Accompany the work with the complete corresponding
15997 machine-readable source code for the Library including
15998 whatever changes were used in the work (which must be
15999 distributed under Sections 1 and 2 above); and, if the work
16000 is an executable linked with the Library, with the complete
16001 machine-readable "work that uses the Library", as object code
16002 and/or source code, so that the user can modify the Library
16003 and then relink to produce a modified executable containing
16004 the modified Library. (It is understood that the user who
16005 changes the contents of definitions files in the Library will
16006 not necessarily be able to recompile the application to use
16007 the modified definitions.)
16009 b. Use a suitable shared library mechanism for linking with the
16010 Library. A suitable mechanism is one that (1) uses at run
16011 time a copy of the library already present on the user's
16012 computer system, rather than copying library functions into
16013 the executable, and (2) will operate properly with a modified
16014 version of the library, if the user installs one, as long as
16015 the modified version is interface-compatible with the version
16016 that the work was made with.
16018 c. Accompany the work with a written offer, valid for at least
16019 three years, to give the same user the materials specified in
16020 Subsection 6a, above, for a charge no more than the cost of
16021 performing this distribution.
16023 d. If distribution of the work is made by offering access to copy
16024 from a designated place, offer equivalent access to copy the
16025 above specified materials from the same place.
16027 e. Verify that the user has already received a copy of these
16028 materials or that you have already sent this user a copy.
16030 For an executable, the required form of the "work that uses the
16031 Library" must include any data and utility programs needed for
16032 reproducing the executable from it. However, as a special
16033 exception, the materials to be distributed need not include
16034 anything that is normally distributed (in either source or binary
16035 form) with the major components (compiler, kernel, and so on) of
16036 the operating system on which the executable runs, unless that
16037 component itself accompanies the executable.
16039 It may happen that this requirement contradicts the license
16040 restrictions of other proprietary libraries that do not normally
16041 accompany the operating system. Such a contradiction means you
16042 cannot use both them and the Library together in an executable
16043 that you distribute.
16045 7. You may place library facilities that are a work based on the
16046 Library side-by-side in a single library together with other
16047 library facilities not covered by this License, and distribute
16048 such a combined library, provided that the separate distribution
16049 of the work based on the Library and of the other library
16050 facilities is otherwise permitted, and provided that you do these
16053 a. Accompany the combined library with a copy of the same work
16054 based on the Library, uncombined with any other library
16055 facilities. This must be distributed under the terms of the
16058 b. Give prominent notice with the combined library of the fact
16059 that part of it is a work based on the Library, and explaining
16060 where to find the accompanying uncombined form of the same
16063 8. You may not copy, modify, sublicense, link with, or distribute the
16064 Library except as expressly provided under this License. Any
16065 attempt otherwise to copy, modify, sublicense, link with, or
16066 distribute the Library is void, and will automatically terminate
16067 your rights under this License. However, parties who have
16068 received copies, or rights, from you under this License will not
16069 have their licenses terminated so long as such parties remain in
16072 9. You are not required to accept this License, since you have not
16073 signed it. However, nothing else grants you permission to modify
16074 or distribute the Library or its derivative works. These actions
16075 are prohibited by law if you do not accept this License.
16076 Therefore, by modifying or distributing the Library (or any work
16077 based on the Library), you indicate your acceptance of this
16078 License to do so, and all its terms and conditions for copying,
16079 distributing or modifying the Library or works based on it.
16081 10. Each time you redistribute the Library (or any work based on the
16082 Library), the recipient automatically receives a license from the
16083 original licensor to copy, distribute, link with or modify the
16084 Library subject to these terms and conditions. You may not impose
16085 any further restrictions on the recipients' exercise of the rights
16086 granted herein. You are not responsible for enforcing compliance
16087 by third parties with this License.
16089 11. If, as a consequence of a court judgment or allegation of patent
16090 infringement or for any other reason (not limited to patent
16091 issues), conditions are imposed on you (whether by court order,
16092 agreement or otherwise) that contradict the conditions of this
16093 License, they do not excuse you from the conditions of this
16094 License. If you cannot distribute so as to satisfy simultaneously
16095 your obligations under this License and any other pertinent
16096 obligations, then as a consequence you may not distribute the
16097 Library at all. For example, if a patent license would not permit
16098 royalty-free redistribution of the Library by all those who
16099 receive copies directly or indirectly through you, then the only
16100 way you could satisfy both it and this License would be to refrain
16101 entirely from distribution of the Library.
16103 If any portion of this section is held invalid or unenforceable
16104 under any particular circumstance, the balance of the section is
16105 intended to apply, and the section as a whole is intended to apply
16106 in other circumstances.
16108 It is not the purpose of this section to induce you to infringe any
16109 patents or other property right claims or to contest validity of
16110 any such claims; this section has the sole purpose of protecting
16111 the integrity of the free software distribution system which is
16112 implemented by public license practices. Many people have made
16113 generous contributions to the wide range of software distributed
16114 through that system in reliance on consistent application of that
16115 system; it is up to the author/donor to decide if he or she is
16116 willing to distribute software through any other system and a
16117 licensee cannot impose that choice.
16119 This section is intended to make thoroughly clear what is believed
16120 to be a consequence of the rest of this License.
16122 12. If the distribution and/or use of the Library is restricted in
16123 certain countries either by patents or by copyrighted interfaces,
16124 the original copyright holder who places the Library under this
16125 License may add an explicit geographical distribution limitation
16126 excluding those countries, so that distribution is permitted only
16127 in or among countries not thus excluded. In such case, this
16128 License incorporates the limitation as if written in the body of
16131 13. The Free Software Foundation may publish revised and/or new
16132 versions of the Lesser General Public License from time to time.
16133 Such new versions will be similar in spirit to the present version,
16134 but may differ in detail to address new problems or concerns.
16136 Each version is given a distinguishing version number. If the
16137 Library specifies a version number of this License which applies
16138 to it and "any later version", you have the option of following
16139 the terms and conditions either of that version or of any later
16140 version published by the Free Software Foundation. If the Library
16141 does not specify a license version number, you may choose any
16142 version ever published by the Free Software Foundation.
16144 14. If you wish to incorporate parts of the Library into other free
16145 programs whose distribution conditions are incompatible with these,
16146 write to the author to ask for permission. For software which is
16147 copyrighted by the Free Software Foundation, write to the Free
16148 Software Foundation; we sometimes make exceptions for this. Our
16149 decision will be guided by the two goals of preserving the free
16150 status of all derivatives of our free software and of promoting
16151 the sharing and reuse of software generally.
16155 15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
16156 WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE
16157 LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
16158 HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT
16159 WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT
16160 NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
16161 FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE
16162 QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH YOU. SHOULD THE
16163 LIBRARY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
16164 SERVICING, REPAIR OR CORRECTION.
16166 16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
16167 WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
16168 MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE
16169 LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
16170 INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
16171 INABILITY TO USE THE LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF
16172 DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU
16173 OR THIRD PARTIES OR A FAILURE OF THE LIBRARY TO OPERATE WITH ANY
16174 OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
16175 ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
16177 END OF TERMS AND CONDITIONS
16179 How to Apply These Terms to Your New Libraries
16180 ----------------------------------------------
16182 If you develop a new library, and you want it to be of the greatest
16183 possible use to the public, we recommend making it free software that
16184 everyone can redistribute and change. You can do so by permitting
16185 redistribution under these terms (or, alternatively, under the terms of
16186 the ordinary General Public License).
16188 To apply these terms, attach the following notices to the library.
16189 It is safest to attach them to the start of each source file to most
16190 effectively convey the exclusion of warranty; and each file should have
16191 at least the "copyright" line and a pointer to where the full notice is
16194 ONE LINE TO GIVE THE LIBRARY'S NAME AND AN IDEA OF WHAT IT DOES.
16195 Copyright (C) YEAR NAME OF AUTHOR
16197 This library is free software; you can redistribute it and/or modify it
16198 under the terms of the GNU Lesser General Public License as published by
16199 the Free Software Foundation; either version 2.1 of the License, or (at
16200 your option) any later version.
16202 This library is distributed in the hope that it will be useful, but
16203 WITHOUT ANY WARRANTY; without even the implied warranty of
16204 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16205 Lesser General Public License for more details.
16207 You should have received a copy of the GNU Lesser General Public
16208 License along with this library; if not, write to the Free Software
16209 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
16212 Also add information on how to contact you by electronic and paper
16215 You should also get your employer (if you work as a programmer) or
16216 your school, if any, to sign a "copyright disclaimer" for the library,
16217 if necessary. Here is a sample; alter the names:
16219 Yoyodyne, Inc., hereby disclaims all copyright interest in the library
16220 `Frob' (a library for tweaking knobs) written by James Random Hacker.
16222 SIGNATURE OF TY COON, 1 April 1990
16223 Ty Coon, President of Vice
16225 That's all there is to it!
16228 File: gettext.info, Node: GNU FDL, Prev: GNU LGPL, Up: Licenses
16230 C.3 GNU Free Documentation License
16231 ==================================
16233 Version 1.2, November 2002
16235 Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
16236 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
16238 Everyone is permitted to copy and distribute verbatim copies
16239 of this license document, but changing it is not allowed.
16243 The purpose of this License is to make a manual, textbook, or other
16244 functional and useful document "free" in the sense of freedom: to
16245 assure everyone the effective freedom to copy and redistribute it,
16246 with or without modifying it, either commercially or
16247 noncommercially. Secondarily, this License preserves for the
16248 author and publisher a way to get credit for their work, while not
16249 being considered responsible for modifications made by others.
16251 This License is a kind of "copyleft", which means that derivative
16252 works of the document must themselves be free in the same sense.
16253 It complements the GNU General Public License, which is a copyleft
16254 license designed for free software.
16256 We have designed this License in order to use it for manuals for
16257 free software, because free software needs free documentation: a
16258 free program should come with manuals providing the same freedoms
16259 that the software does. But this License is not limited to
16260 software manuals; it can be used for any textual work, regardless
16261 of subject matter or whether it is published as a printed book.
16262 We recommend this License principally for works whose purpose is
16263 instruction or reference.
16265 1. APPLICABILITY AND DEFINITIONS
16267 This License applies to any manual or other work, in any medium,
16268 that contains a notice placed by the copyright holder saying it
16269 can be distributed under the terms of this License. Such a notice
16270 grants a world-wide, royalty-free license, unlimited in duration,
16271 to use that work under the conditions stated herein. The
16272 "Document", below, refers to any such manual or work. Any member
16273 of the public is a licensee, and is addressed as "you". You
16274 accept the license if you copy, modify or distribute the work in a
16275 way requiring permission under copyright law.
16277 A "Modified Version" of the Document means any work containing the
16278 Document or a portion of it, either copied verbatim, or with
16279 modifications and/or translated into another language.
16281 A "Secondary Section" is a named appendix or a front-matter section
16282 of the Document that deals exclusively with the relationship of the
16283 publishers or authors of the Document to the Document's overall
16284 subject (or to related matters) and contains nothing that could
16285 fall directly within that overall subject. (Thus, if the Document
16286 is in part a textbook of mathematics, a Secondary Section may not
16287 explain any mathematics.) The relationship could be a matter of
16288 historical connection with the subject or with related matters, or
16289 of legal, commercial, philosophical, ethical or political position
16292 The "Invariant Sections" are certain Secondary Sections whose
16293 titles are designated, as being those of Invariant Sections, in
16294 the notice that says that the Document is released under this
16295 License. If a section does not fit the above definition of
16296 Secondary then it is not allowed to be designated as Invariant.
16297 The Document may contain zero Invariant Sections. If the Document
16298 does not identify any Invariant Sections then there are none.
16300 The "Cover Texts" are certain short passages of text that are
16301 listed, as Front-Cover Texts or Back-Cover Texts, in the notice
16302 that says that the Document is released under this License. A
16303 Front-Cover Text may be at most 5 words, and a Back-Cover Text may
16304 be at most 25 words.
16306 A "Transparent" copy of the Document means a machine-readable copy,
16307 represented in a format whose specification is available to the
16308 general public, that is suitable for revising the document
16309 straightforwardly with generic text editors or (for images
16310 composed of pixels) generic paint programs or (for drawings) some
16311 widely available drawing editor, and that is suitable for input to
16312 text formatters or for automatic translation to a variety of
16313 formats suitable for input to text formatters. A copy made in an
16314 otherwise Transparent file format whose markup, or absence of
16315 markup, has been arranged to thwart or discourage subsequent
16316 modification by readers is not Transparent. An image format is
16317 not Transparent if used for any substantial amount of text. A
16318 copy that is not "Transparent" is called "Opaque".
16320 Examples of suitable formats for Transparent copies include plain
16321 ASCII without markup, Texinfo input format, LaTeX input format,
16322 SGML or XML using a publicly available DTD, and
16323 standard-conforming simple HTML, PostScript or PDF designed for
16324 human modification. Examples of transparent image formats include
16325 PNG, XCF and JPG. Opaque formats include proprietary formats that
16326 can be read and edited only by proprietary word processors, SGML or
16327 XML for which the DTD and/or processing tools are not generally
16328 available, and the machine-generated HTML, PostScript or PDF
16329 produced by some word processors for output purposes only.
16331 The "Title Page" means, for a printed book, the title page itself,
16332 plus such following pages as are needed to hold, legibly, the
16333 material this License requires to appear in the title page. For
16334 works in formats which do not have any title page as such, "Title
16335 Page" means the text near the most prominent appearance of the
16336 work's title, preceding the beginning of the body of the text.
16338 A section "Entitled XYZ" means a named subunit of the Document
16339 whose title either is precisely XYZ or contains XYZ in parentheses
16340 following text that translates XYZ in another language. (Here XYZ
16341 stands for a specific section name mentioned below, such as
16342 "Acknowledgements", "Dedications", "Endorsements", or "History".)
16343 To "Preserve the Title" of such a section when you modify the
16344 Document means that it remains a section "Entitled XYZ" according
16345 to this definition.
16347 The Document may include Warranty Disclaimers next to the notice
16348 which states that this License applies to the Document. These
16349 Warranty Disclaimers are considered to be included by reference in
16350 this License, but only as regards disclaiming warranties: any other
16351 implication that these Warranty Disclaimers may have is void and
16352 has no effect on the meaning of this License.
16354 2. VERBATIM COPYING
16356 You may copy and distribute the Document in any medium, either
16357 commercially or noncommercially, provided that this License, the
16358 copyright notices, and the license notice saying this License
16359 applies to the Document are reproduced in all copies, and that you
16360 add no other conditions whatsoever to those of this License. You
16361 may not use technical measures to obstruct or control the reading
16362 or further copying of the copies you make or distribute. However,
16363 you may accept compensation in exchange for copies. If you
16364 distribute a large enough number of copies you must also follow
16365 the conditions in section 3.
16367 You may also lend copies, under the same conditions stated above,
16368 and you may publicly display copies.
16370 3. COPYING IN QUANTITY
16372 If you publish printed copies (or copies in media that commonly
16373 have printed covers) of the Document, numbering more than 100, and
16374 the Document's license notice requires Cover Texts, you must
16375 enclose the copies in covers that carry, clearly and legibly, all
16376 these Cover Texts: Front-Cover Texts on the front cover, and
16377 Back-Cover Texts on the back cover. Both covers must also clearly
16378 and legibly identify you as the publisher of these copies. The
16379 front cover must present the full title with all words of the
16380 title equally prominent and visible. You may add other material
16381 on the covers in addition. Copying with changes limited to the
16382 covers, as long as they preserve the title of the Document and
16383 satisfy these conditions, can be treated as verbatim copying in
16386 If the required texts for either cover are too voluminous to fit
16387 legibly, you should put the first ones listed (as many as fit
16388 reasonably) on the actual cover, and continue the rest onto
16391 If you publish or distribute Opaque copies of the Document
16392 numbering more than 100, you must either include a
16393 machine-readable Transparent copy along with each Opaque copy, or
16394 state in or with each Opaque copy a computer-network location from
16395 which the general network-using public has access to download
16396 using public-standard network protocols a complete Transparent
16397 copy of the Document, free of added material. If you use the
16398 latter option, you must take reasonably prudent steps, when you
16399 begin distribution of Opaque copies in quantity, to ensure that
16400 this Transparent copy will remain thus accessible at the stated
16401 location until at least one year after the last time you
16402 distribute an Opaque copy (directly or through your agents or
16403 retailers) of that edition to the public.
16405 It is requested, but not required, that you contact the authors of
16406 the Document well before redistributing any large number of
16407 copies, to give them a chance to provide you with an updated
16408 version of the Document.
16412 You may copy and distribute a Modified Version of the Document
16413 under the conditions of sections 2 and 3 above, provided that you
16414 release the Modified Version under precisely this License, with
16415 the Modified Version filling the role of the Document, thus
16416 licensing distribution and modification of the Modified Version to
16417 whoever possesses a copy of it. In addition, you must do these
16418 things in the Modified Version:
16420 A. Use in the Title Page (and on the covers, if any) a title
16421 distinct from that of the Document, and from those of
16422 previous versions (which should, if there were any, be listed
16423 in the History section of the Document). You may use the
16424 same title as a previous version if the original publisher of
16425 that version gives permission.
16427 B. List on the Title Page, as authors, one or more persons or
16428 entities responsible for authorship of the modifications in
16429 the Modified Version, together with at least five of the
16430 principal authors of the Document (all of its principal
16431 authors, if it has fewer than five), unless they release you
16432 from this requirement.
16434 C. State on the Title page the name of the publisher of the
16435 Modified Version, as the publisher.
16437 D. Preserve all the copyright notices of the Document.
16439 E. Add an appropriate copyright notice for your modifications
16440 adjacent to the other copyright notices.
16442 F. Include, immediately after the copyright notices, a license
16443 notice giving the public permission to use the Modified
16444 Version under the terms of this License, in the form shown in
16445 the Addendum below.
16447 G. Preserve in that license notice the full lists of Invariant
16448 Sections and required Cover Texts given in the Document's
16451 H. Include an unaltered copy of this License.
16453 I. Preserve the section Entitled "History", Preserve its Title,
16454 and add to it an item stating at least the title, year, new
16455 authors, and publisher of the Modified Version as given on
16456 the Title Page. If there is no section Entitled "History" in
16457 the Document, create one stating the title, year, authors,
16458 and publisher of the Document as given on its Title Page,
16459 then add an item describing the Modified Version as stated in
16460 the previous sentence.
16462 J. Preserve the network location, if any, given in the Document
16463 for public access to a Transparent copy of the Document, and
16464 likewise the network locations given in the Document for
16465 previous versions it was based on. These may be placed in
16466 the "History" section. You may omit a network location for a
16467 work that was published at least four years before the
16468 Document itself, or if the original publisher of the version
16469 it refers to gives permission.
16471 K. For any section Entitled "Acknowledgements" or "Dedications",
16472 Preserve the Title of the section, and preserve in the
16473 section all the substance and tone of each of the contributor
16474 acknowledgements and/or dedications given therein.
16476 L. Preserve all the Invariant Sections of the Document,
16477 unaltered in their text and in their titles. Section numbers
16478 or the equivalent are not considered part of the section
16481 M. Delete any section Entitled "Endorsements". Such a section
16482 may not be included in the Modified Version.
16484 N. Do not retitle any existing section to be Entitled
16485 "Endorsements" or to conflict in title with any Invariant
16488 O. Preserve any Warranty Disclaimers.
16490 If the Modified Version includes new front-matter sections or
16491 appendices that qualify as Secondary Sections and contain no
16492 material copied from the Document, you may at your option
16493 designate some or all of these sections as invariant. To do this,
16494 add their titles to the list of Invariant Sections in the Modified
16495 Version's license notice. These titles must be distinct from any
16496 other section titles.
16498 You may add a section Entitled "Endorsements", provided it contains
16499 nothing but endorsements of your Modified Version by various
16500 parties--for example, statements of peer review or that the text
16501 has been approved by an organization as the authoritative
16502 definition of a standard.
16504 You may add a passage of up to five words as a Front-Cover Text,
16505 and a passage of up to 25 words as a Back-Cover Text, to the end
16506 of the list of Cover Texts in the Modified Version. Only one
16507 passage of Front-Cover Text and one of Back-Cover Text may be
16508 added by (or through arrangements made by) any one entity. If the
16509 Document already includes a cover text for the same cover,
16510 previously added by you or by arrangement made by the same entity
16511 you are acting on behalf of, you may not add another; but you may
16512 replace the old one, on explicit permission from the previous
16513 publisher that added the old one.
16515 The author(s) and publisher(s) of the Document do not by this
16516 License give permission to use their names for publicity for or to
16517 assert or imply endorsement of any Modified Version.
16519 5. COMBINING DOCUMENTS
16521 You may combine the Document with other documents released under
16522 this License, under the terms defined in section 4 above for
16523 modified versions, provided that you include in the combination
16524 all of the Invariant Sections of all of the original documents,
16525 unmodified, and list them all as Invariant Sections of your
16526 combined work in its license notice, and that you preserve all
16527 their Warranty Disclaimers.
16529 The combined work need only contain one copy of this License, and
16530 multiple identical Invariant Sections may be replaced with a single
16531 copy. If there are multiple Invariant Sections with the same name
16532 but different contents, make the title of each such section unique
16533 by adding at the end of it, in parentheses, the name of the
16534 original author or publisher of that section if known, or else a
16535 unique number. Make the same adjustment to the section titles in
16536 the list of Invariant Sections in the license notice of the
16539 In the combination, you must combine any sections Entitled
16540 "History" in the various original documents, forming one section
16541 Entitled "History"; likewise combine any sections Entitled
16542 "Acknowledgements", and any sections Entitled "Dedications". You
16543 must delete all sections Entitled "Endorsements."
16545 6. COLLECTIONS OF DOCUMENTS
16547 You may make a collection consisting of the Document and other
16548 documents released under this License, and replace the individual
16549 copies of this License in the various documents with a single copy
16550 that is included in the collection, provided that you follow the
16551 rules of this License for verbatim copying of each of the
16552 documents in all other respects.
16554 You may extract a single document from such a collection, and
16555 distribute it individually under this License, provided you insert
16556 a copy of this License into the extracted document, and follow
16557 this License in all other respects regarding verbatim copying of
16560 7. AGGREGATION WITH INDEPENDENT WORKS
16562 A compilation of the Document or its derivatives with other
16563 separate and independent documents or works, in or on a volume of
16564 a storage or distribution medium, is called an "aggregate" if the
16565 copyright resulting from the compilation is not used to limit the
16566 legal rights of the compilation's users beyond what the individual
16567 works permit. When the Document is included in an aggregate, this
16568 License does not apply to the other works in the aggregate which
16569 are not themselves derivative works of the Document.
16571 If the Cover Text requirement of section 3 is applicable to these
16572 copies of the Document, then if the Document is less than one half
16573 of the entire aggregate, the Document's Cover Texts may be placed
16574 on covers that bracket the Document within the aggregate, or the
16575 electronic equivalent of covers if the Document is in electronic
16576 form. Otherwise they must appear on printed covers that bracket
16577 the whole aggregate.
16581 Translation is considered a kind of modification, so you may
16582 distribute translations of the Document under the terms of section
16583 4. Replacing Invariant Sections with translations requires special
16584 permission from their copyright holders, but you may include
16585 translations of some or all Invariant Sections in addition to the
16586 original versions of these Invariant Sections. You may include a
16587 translation of this License, and all the license notices in the
16588 Document, and any Warranty Disclaimers, provided that you also
16589 include the original English version of this License and the
16590 original versions of those notices and disclaimers. In case of a
16591 disagreement between the translation and the original version of
16592 this License or a notice or disclaimer, the original version will
16595 If a section in the Document is Entitled "Acknowledgements",
16596 "Dedications", or "History", the requirement (section 4) to
16597 Preserve its Title (section 1) will typically require changing the
16602 You may not copy, modify, sublicense, or distribute the Document
16603 except as expressly provided for under this License. Any other
16604 attempt to copy, modify, sublicense or distribute the Document is
16605 void, and will automatically terminate your rights under this
16606 License. However, parties who have received copies, or rights,
16607 from you under this License will not have their licenses
16608 terminated so long as such parties remain in full compliance.
16610 10. FUTURE REVISIONS OF THIS LICENSE
16612 The Free Software Foundation may publish new, revised versions of
16613 the GNU Free Documentation License from time to time. Such new
16614 versions will be similar in spirit to the present version, but may
16615 differ in detail to address new problems or concerns. See
16616 `http://www.gnu.org/copyleft/'.
16618 Each version of the License is given a distinguishing version
16619 number. If the Document specifies that a particular numbered
16620 version of this License "or any later version" applies to it, you
16621 have the option of following the terms and conditions either of
16622 that specified version or of any later version that has been
16623 published (not as a draft) by the Free Software Foundation. If
16624 the Document does not specify a version number of this License,
16625 you may choose any version ever published (not as a draft) by the
16626 Free Software Foundation.
16628 ADDENDUM: How to use this License for your documents
16629 ----------------------------------------------------
16631 To use this License in a document you have written, include a copy of
16632 the License in the document and put the following copyright and license
16633 notices just after the title page:
16635 Copyright (C) YEAR YOUR NAME.
16636 Permission is granted to copy, distribute and/or modify this document
16637 under the terms of the GNU Free Documentation License, Version 1.2
16638 or any later version published by the Free Software Foundation;
16639 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
16640 Texts. A copy of the license is included in the section entitled ``GNU
16641 Free Documentation License''.
16643 If you have Invariant Sections, Front-Cover Texts and Back-Cover
16644 Texts, replace the "with...Texts." line with this:
16646 with the Invariant Sections being LIST THEIR TITLES, with
16647 the Front-Cover Texts being LIST, and with the Back-Cover Texts
16650 If you have Invariant Sections without Cover Texts, or some other
16651 combination of the three, merge those two alternatives to suit the
16654 If your document contains nontrivial examples of program code, we
16655 recommend releasing these examples in parallel under your choice of
16656 free software license, such as the GNU General Public License, to
16657 permit their use in free software.
16660 File: gettext.info, Node: Program Index, Next: Option Index, Prev: Licenses, Up: Top
16668 * autopoint: autopoint Invocation. (line 6)
16669 * envsubst: envsubst Invocation. (line 6)
16670 * gettext <1>: gettext Invocation. (line 6)
16671 * gettext: sh. (line 19)
16672 * gettextize: gettextize Invocation.
16674 * msgattrib: msgattrib Invocation. (line 6)
16675 * msgcat: msgcat Invocation. (line 6)
16676 * msgcmp: msgcmp Invocation. (line 6)
16677 * msgcomm: msgcomm Invocation. (line 6)
16678 * msgconv: msgconv Invocation. (line 6)
16679 * msgen: msgen Invocation. (line 6)
16680 * msgexec: msgexec Invocation. (line 6)
16681 * msgfilter: msgfilter Invocation. (line 6)
16682 * msgfmt: msgfmt Invocation. (line 6)
16683 * msggrep: msggrep Invocation. (line 6)
16684 * msginit: msginit Invocation. (line 6)
16685 * msgmerge: msgmerge Invocation. (line 6)
16686 * msgunfmt: msgunfmt Invocation. (line 6)
16687 * msguniq: msguniq Invocation. (line 6)
16688 * ngettext <1>: ngettext Invocation. (line 6)
16689 * ngettext: sh. (line 19)
16690 * recode-sr-latin: msgfilter Invocation. (line 92)
16691 * xgettext: xgettext Invocation. (line 6)
16694 File: gettext.info, Node: Option Index, Next: Variable Index, Prev: Program Index, Up: Top
16702 * --add-comments, xgettext option: xgettext Invocation. (line 97)
16703 * --add-location, msgattrib option: msgattrib Invocation.
16705 * --add-location, msgcat option: msgcat Invocation. (line 119)
16706 * --add-location, msgcomm option: msgcomm Invocation. (line 104)
16707 * --add-location, msgconv option: msgconv Invocation. (line 83)
16708 * --add-location, msgen option: msgen Invocation. (line 85)
16709 * --add-location, msgfilter option: msgfilter Invocation.
16711 * --add-location, msggrep option: msggrep Invocation. (line 161)
16712 * --add-location, msgmerge option: msgmerge Invocation. (line 155)
16713 * --add-location, msguniq option: msguniq Invocation. (line 101)
16714 * --add-location, xgettext option: xgettext Invocation. (line 297)
16715 * --alignment, msgfmt option: msgfmt Invocation. (line 209)
16716 * --backup, msgmerge option: msgmerge Invocation. (line 65)
16717 * --boost, xgettext option: xgettext Invocation. (line 254)
16718 * --c++, xgettext option: xgettext Invocation. (line 64)
16719 * --check, msgfmt option: msgfmt Invocation. (line 146)
16720 * --check-accelerators, msgfmt option: msgfmt Invocation. (line 187)
16721 * --check-compatibility, msgfmt option: msgfmt Invocation. (line 183)
16722 * --check-domain, msgfmt option: msgfmt Invocation. (line 178)
16723 * --check-format, msgfmt option: msgfmt Invocation. (line 150)
16724 * --check-header, msgfmt option: msgfmt Invocation. (line 173)
16725 * --clear-fuzzy, msgattrib option: msgattrib Invocation.
16727 * --clear-obsolete, msgattrib option: msgattrib Invocation.
16729 * --clear-previous, msgattrib option: msgattrib Invocation.
16731 * --color, msgattrib option: msgattrib Invocation.
16733 * --color, msgcat option <1>: The --color option. (line 6)
16734 * --color, msgcat option: msgcat Invocation. (line 100)
16735 * --color, msgcomm option: msgcomm Invocation. (line 85)
16736 * --color, msgconv option: msgconv Invocation. (line 65)
16737 * --color, msgen option: msgen Invocation. (line 67)
16738 * --color, msgfilter option: msgfilter Invocation.
16740 * --color, msggrep option: msggrep Invocation. (line 144)
16741 * --color, msginit option: msginit Invocation. (line 63)
16742 * --color, msgmerge option: msgmerge Invocation. (line 137)
16743 * --color, msgunfmt option: msgunfmt Invocation. (line 109)
16744 * --color, msguniq option: msguniq Invocation. (line 82)
16745 * --color, xgettext option: xgettext Invocation. (line 276)
16746 * --comment, msggrep option: msggrep Invocation. (line 93)
16747 * --compendium, msgmerge option: msgmerge Invocation. (line 36)
16748 * --copyright-holder, xgettext option: xgettext Invocation. (line 347)
16749 * --csharp, msgfmt option: msgfmt Invocation. (line 36)
16750 * --csharp, msgunfmt option: msgunfmt Invocation. (line 19)
16751 * --csharp-resources, msgfmt option: msgfmt Invocation. (line 40)
16752 * --csharp-resources, msgunfmt option: msgunfmt Invocation. (line 23)
16753 * --debug, xgettext option: xgettext Invocation. (line 258)
16754 * --default-domain, xgettext option: xgettext Invocation. (line 36)
16755 * --directory, msgattrib option: msgattrib Invocation.
16757 * --directory, msgcat option: msgcat Invocation. (line 32)
16758 * --directory, msgcmp option: msgcmp Invocation. (line 27)
16759 * --directory, msgcomm option: msgcomm Invocation. (line 30)
16760 * --directory, msgconv option: msgconv Invocation. (line 19)
16761 * --directory, msgen option: msgen Invocation. (line 25)
16762 * --directory, msgexec option: msgexec Invocation. (line 44)
16763 * --directory, msgfilter option: msgfilter Invocation.
16765 * --directory, msgfmt option: msgfmt Invocation. (line 18)
16766 * --directory, msggrep option: msggrep Invocation. (line 19)
16767 * --directory, msgmerge option: msgmerge Invocation. (line 30)
16768 * --directory, msguniq option: msguniq Invocation. (line 26)
16769 * --directory, xgettext option: xgettext Invocation. (line 24)
16770 * --domain, gettext option: gettext Invocation. (line 16)
16771 * --domain, msggrep option: msggrep Invocation. (line 77)
16772 * --domain, ngettext option: ngettext Invocation. (line 15)
16773 * --dry-run, autopoint option: autopoint Invocation.
16775 * --dry-run, gettextize option: gettextize Invocation.
16777 * --exclude-file, xgettext option: xgettext Invocation. (line 92)
16778 * --expression, msgfilter option: msgfilter Invocation.
16780 * --extended-regexp, msggrep option: msggrep Invocation. (line 101)
16781 * --extract-all, xgettext option: xgettext Invocation. (line 107)
16782 * --extracted-comment, msggrep option: msggrep Invocation. (line 97)
16783 * --file, msgfilter option: msgfilter Invocation.
16785 * --file, msggrep option: msggrep Invocation. (line 113)
16786 * --files-from, msgcat option: msgcat Invocation. (line 27)
16787 * --files-from, msgcomm option: msgcomm Invocation. (line 25)
16788 * --files-from, xgettext option: xgettext Invocation. (line 19)
16789 * --fixed-strings, msggrep option: msggrep Invocation. (line 105)
16790 * --flag, xgettext option: xgettext Invocation. (line 201)
16791 * --force, autopoint option: autopoint Invocation.
16793 * --force, gettextize option: gettextize Invocation.
16795 * --force-po, msgattrib option: msgattrib Invocation.
16797 * --force-po, msgcat option: msgcat Invocation. (line 108)
16798 * --force-po, msgcomm option: msgcomm Invocation. (line 93)
16799 * --force-po, msgconv option: msgconv Invocation. (line 73)
16800 * --force-po, msgen option: msgen Invocation. (line 75)
16801 * --force-po, msgfilter option: msgfilter Invocation.
16803 * --force-po, msggrep option: msggrep Invocation. (line 152)
16804 * --force-po, msgmerge option: msgmerge Invocation. (line 145)
16805 * --force-po, msgunfmt option: msgunfmt Invocation. (line 117)
16806 * --force-po, msguniq option: msguniq Invocation. (line 90)
16807 * --force-po, xgettext option: xgettext Invocation. (line 284)
16808 * --foreign-user, xgettext option: xgettext Invocation. (line 362)
16809 * --from-code, xgettext option: xgettext Invocation. (line 74)
16810 * --fuzzy, msgattrib option: msgattrib Invocation.
16812 * --help, autopoint option: autopoint Invocation.
16814 * --help, envsubst option: envsubst Invocation. (line 22)
16815 * --help, gettext option: gettext Invocation. (line 32)
16816 * --help, gettextize option: gettextize Invocation.
16818 * --help, msgattrib option: msgattrib Invocation.
16820 * --help, msgcat option: msgcat Invocation. (line 164)
16821 * --help, msgcmp option: msgcmp Invocation. (line 72)
16822 * --help, msgcomm option: msgcomm Invocation. (line 152)
16823 * --help, msgconv option: msgconv Invocation. (line 128)
16824 * --help, msgen option: msgen Invocation. (line 130)
16825 * --help, msgexec option: msgexec Invocation. (line 69)
16826 * --help, msgfilter option: msgfilter Invocation.
16828 * --help, msgfmt option: msgfmt Invocation. (line 222)
16829 * --help, msggrep option: msggrep Invocation. (line 204)
16830 * --help, msginit option: msginit Invocation. (line 99)
16831 * --help, msgmerge option: msgmerge Invocation. (line 200)
16832 * --help, msgunfmt option: msgunfmt Invocation. (line 162)
16833 * --help, msguniq option: msguniq Invocation. (line 146)
16834 * --help, ngettext option: ngettext Invocation. (line 31)
16835 * --help, xgettext option: xgettext Invocation. (line 415)
16836 * --ignore-case, msggrep option: msggrep Invocation. (line 117)
16837 * --ignore-file, msgattrib option: msgattrib Invocation.
16839 * --indent, msgattrib option: msgattrib Invocation.
16841 * --indent, msgcat option: msgcat Invocation. (line 112)
16842 * --indent, msgcomm option: msgcomm Invocation. (line 97)
16843 * --indent, msgconv option: msgconv Invocation. (line 77)
16844 * --indent, msgen option: msgen Invocation. (line 79)
16845 * --indent, msgfilter option: msgfilter Invocation.
16847 * --indent, msggrep option: msggrep Invocation. (line 155)
16848 * --indent, msgmerge option: msgmerge Invocation. (line 149)
16849 * --indent, msgunfmt option: msgunfmt Invocation. (line 121)
16850 * --indent, msguniq option: msguniq Invocation. (line 94)
16851 * --indent, xgettext option: xgettext Invocation. (line 288)
16852 * --input, msgexec option: msgexec Invocation. (line 40)
16853 * --input, msgfilter option: msgfilter Invocation.
16855 * --input, msginit option: msginit Invocation. (line 16)
16856 * --intl, gettextize option: gettextize Invocation.
16858 * --invert-match, msggrep option: msggrep Invocation. (line 121)
16859 * --java, msgfmt option: msgfmt Invocation. (line 30)
16860 * --java, msgunfmt option: msgunfmt Invocation. (line 16)
16861 * --java2, msgfmt option: msgfmt Invocation. (line 33)
16862 * --join-existing, xgettext option: xgettext Invocation. (line 88)
16863 * --kde, xgettext option: xgettext Invocation. (line 250)
16864 * --keep-header, msgfilter option: msgfilter Invocation.
16866 * --keyword, xgettext option: xgettext Invocation. (line 115)
16867 * --lang, msgcat option <1>: msgen Invocation. (line 60)
16868 * --lang, msgcat option <2>: msgcat Invocation. (line 94)
16869 * --lang, msgcat option: msgmerge Invocation. (line 129)
16870 * --language, xgettext option: xgettext Invocation. (line 56)
16871 * --less-than, msgcat option: msgcat Invocation. (line 55)
16872 * --less-than, msgcomm option: msgcomm Invocation. (line 53)
16873 * --locale, msgfmt option: msgfmt Invocation. (line 79)
16874 * --locale, msginit option: msginit Invocation. (line 52)
16875 * --locale, msgunfmt option: msgunfmt Invocation. (line 47)
16876 * --location, msggrep option: msggrep Invocation. (line 72)
16877 * --more-than, msgcat option: msgcat Invocation. (line 60)
16878 * --more-than, msgcomm option: msgcomm Invocation. (line 58)
16879 * --msgctxt, msggrep option: msggrep Invocation. (line 81)
16880 * --msgid, msggrep option: msggrep Invocation. (line 85)
16881 * --msgid-bugs-address, xgettext option: xgettext Invocation. (line 375)
16882 * --msgstr, msggrep option: msggrep Invocation. (line 89)
16883 * --msgstr-prefix, xgettext option: xgettext Invocation. (line 403)
16884 * --msgstr-suffix, xgettext option: xgettext Invocation. (line 407)
16885 * --multi-domain, msgcmp option: msgcmp Invocation. (line 36)
16886 * --multi-domain, msgmerge option: msgmerge Invocation. (line 101)
16887 * --no-changelog, gettextize option: gettextize Invocation.
16889 * --no-fuzzy, msgattrib option: msgattrib Invocation.
16891 * --no-fuzzy-matching, msgcmp option: msgcmp Invocation. (line 40)
16892 * --no-fuzzy-matching, msgmerge option: msgmerge Invocation. (line 105)
16893 * --no-hash, msgfmt option: msgfmt Invocation. (line 212)
16894 * --no-location, msgattrib option: msgattrib Invocation.
16896 * --no-location, msgcat option: msgcat Invocation. (line 115)
16897 * --no-location, msgcomm option: msgcomm Invocation. (line 100)
16898 * --no-location, msgconv option: msgconv Invocation. (line 80)
16899 * --no-location, msgen option: msgen Invocation. (line 82)
16900 * --no-location, msgfilter option: msgfilter Invocation.
16902 * --no-location, msggrep option: msggrep Invocation. (line 158)
16903 * --no-location, msgmerge option: msgmerge Invocation. (line 152)
16904 * --no-location, msguniq option: msguniq Invocation. (line 97)
16905 * --no-location, xgettext option: xgettext Invocation. (line 291)
16906 * --no-obsolete, msgattrib option: msgattrib Invocation.
16908 * --no-translator, msginit option: msginit Invocation. (line 58)
16909 * --no-wrap, msgattrib option: msgattrib Invocation.
16911 * --no-wrap, msgcat option: msgcat Invocation. (line 144)
16912 * --no-wrap, msgcomm option: msgcomm Invocation. (line 129)
16913 * --no-wrap, msgconv option: msgconv Invocation. (line 108)
16914 * --no-wrap, msgen option: msgen Invocation. (line 110)
16915 * --no-wrap, msgfilter option: msgfilter Invocation.
16917 * --no-wrap, msggrep option: msggrep Invocation. (line 186)
16918 * --no-wrap, msginit option: msginit Invocation. (line 88)
16919 * --no-wrap, msgmerge option: msgmerge Invocation. (line 180)
16920 * --no-wrap, msgunfmt option: msgunfmt Invocation. (line 146)
16921 * --no-wrap, msguniq option: msguniq Invocation. (line 126)
16922 * --no-wrap, xgettext option: xgettext Invocation. (line 321)
16923 * --obsolete, msgattrib option: msgattrib Invocation.
16925 * --omit-header, msgcomm option: msgcomm Invocation. (line 144)
16926 * --omit-header, xgettext option: xgettext Invocation. (line 336)
16927 * --only-file, msgattrib option: msgattrib Invocation.
16929 * --only-fuzzy, msgattrib option: msgattrib Invocation.
16931 * --only-obsolete, msgattrib option: msgattrib Invocation.
16933 * --output, xgettext option: xgettext Invocation. (line 40)
16934 * --output-dir, xgettext option: xgettext Invocation. (line 45)
16935 * --output-file, msgattrib option: msgattrib Invocation.
16937 * --output-file, msgcat option: msgcat Invocation. (line 44)
16938 * --output-file, msgcomm option: msgcomm Invocation. (line 42)
16939 * --output-file, msgconv option: msgconv Invocation. (line 31)
16940 * --output-file, msgen option: msgen Invocation. (line 37)
16941 * --output-file, msgfilter option: msgfilter Invocation.
16943 * --output-file, msgfmt option: msgfmt Invocation. (line 54)
16944 * --output-file, msggrep option: msggrep Invocation. (line 31)
16945 * --output-file, msginit option: msginit Invocation. (line 27)
16946 * --output-file, msgmerge option: msgmerge Invocation. (line 53)
16947 * --output-file, msgunfmt option: msgunfmt Invocation. (line 98)
16948 * --output-file, msguniq option: msguniq Invocation. (line 38)
16949 * --package-name, xgettext option: xgettext Invocation. (line 368)
16950 * --package-version, xgettext option: xgettext Invocation. (line 371)
16951 * --po-dir, gettextize option: gettextize Invocation.
16953 * --previous, msgmerge option: msgmerge Invocation. (line 109)
16954 * --properties-input, msgattrib option: msgattrib Invocation.
16956 * --properties-input, msgcat option: msgcat Invocation. (line 74)
16957 * --properties-input, msgcmp option: msgcmp Invocation. (line 59)
16958 * --properties-input, msgcomm option: msgcomm Invocation. (line 72)
16959 * --properties-input, msgconv option: msgconv Invocation. (line 52)
16960 * --properties-input, msgen option: msgen Invocation. (line 48)
16961 * --properties-input, msgexec option: msgexec Invocation. (line 56)
16962 * --properties-input, msgfilter option: msgfilter Invocation.
16964 * --properties-input, msgfmt option: msgfmt Invocation. (line 133)
16965 * --properties-input, msggrep option: msggrep Invocation. (line 131)
16966 * --properties-input, msginit option: msginit Invocation. (line 39)
16967 * --properties-input, msgmerge option: msgmerge Invocation. (line 117)
16968 * --properties-input, msguniq option: msguniq Invocation. (line 61)
16969 * --properties-output, msgattrib option: msgattrib Invocation.
16971 * --properties-output, msgcat option: msgcat Invocation. (line 128)
16972 * --properties-output, msgcomm option: msgcomm Invocation. (line 113)
16973 * --properties-output, msgconv option: msgconv Invocation. (line 92)
16974 * --properties-output, msgen option: msgen Invocation. (line 94)
16975 * --properties-output, msgfilter option: msgfilter Invocation.
16977 * --properties-output, msggrep option: msggrep Invocation. (line 170)
16978 * --properties-output, msginit option: msginit Invocation. (line 72)
16979 * --properties-output, msgmerge option: msgmerge Invocation. (line 164)
16980 * --properties-output, msgunfmt option: msgunfmt Invocation. (line 130)
16981 * --properties-output, msguniq option: msguniq Invocation. (line 110)
16982 * --properties-output, xgettext option: xgettext Invocation. (line 305)
16983 * --qt, msgfmt option: msgfmt Invocation. (line 46)
16984 * --qt, xgettext option: xgettext Invocation. (line 246)
16985 * --quiet, msgfilter option: msgfilter Invocation.
16987 * --quiet, msgmerge option: msgmerge Invocation. (line 213)
16988 * --regexp=, msggrep option: msggrep Invocation. (line 109)
16989 * --repeated, msguniq option: msguniq Invocation. (line 49)
16990 * --resource, msgfmt option: msgfmt Invocation. (line 75)
16991 * --resource, msgunfmt option: msgunfmt Invocation. (line 43)
16992 * --set-fuzzy, msgattrib option: msgattrib Invocation.
16994 * --set-obsolete, msgattrib option: msgattrib Invocation.
16996 * --silent, msgfilter option: msgfilter Invocation.
16998 * --silent, msgmerge option: msgmerge Invocation. (line 213)
16999 * --sort-by-file, msgattrib option: msgattrib Invocation.
17001 * --sort-by-file, msgcat option: msgcat Invocation. (line 156)
17002 * --sort-by-file, msgcomm option: msgcomm Invocation. (line 141)
17003 * --sort-by-file, msgconv option: msgconv Invocation. (line 120)
17004 * --sort-by-file, msgen option: msgen Invocation. (line 122)
17005 * --sort-by-file, msgfilter option: msgfilter Invocation.
17007 * --sort-by-file, msggrep option: msggrep Invocation. (line 196)
17008 * --sort-by-file, msgmerge option: msgmerge Invocation. (line 192)
17009 * --sort-by-file, msguniq option: msguniq Invocation. (line 138)
17010 * --sort-by-file, xgettext option: xgettext Invocation. (line 333)
17011 * --sort-output, msgattrib option: msgattrib Invocation.
17013 * --sort-output, msgcat option: msgcat Invocation. (line 151)
17014 * --sort-output, msgcomm option: msgcomm Invocation. (line 136)
17015 * --sort-output, msgconv option: msgconv Invocation. (line 115)
17016 * --sort-output, msgen option: msgen Invocation. (line 117)
17017 * --sort-output, msgfilter option: msgfilter Invocation.
17019 * --sort-output, msggrep option: msggrep Invocation. (line 192)
17020 * --sort-output, msgmerge option: msgmerge Invocation. (line 187)
17021 * --sort-output, msgunfmt option: msgunfmt Invocation. (line 153)
17022 * --sort-output, msguniq option: msguniq Invocation. (line 133)
17023 * --sort-output, xgettext option: xgettext Invocation. (line 328)
17024 * --statistics, msgfmt option: msgfmt Invocation. (line 229)
17025 * --strict, msgattrib option: msgattrib Invocation.
17027 * --strict, msgcat option: msgcat Invocation. (line 122)
17028 * --strict, msgcomm option: msgcomm Invocation. (line 107)
17029 * --strict, msgconv option: msgconv Invocation. (line 86)
17030 * --strict, msgen option: msgen Invocation. (line 88)
17031 * --strict, msgfilter option: msgfilter Invocation.
17033 * --strict, msgfmt option: msgfmt Invocation. (line 57)
17034 * --strict, msggrep option: msggrep Invocation. (line 164)
17035 * --strict, msgmerge option: msgmerge Invocation. (line 158)
17036 * --strict, msgunfmt option: msgunfmt Invocation. (line 124)
17037 * --strict, msguniq option: msguniq Invocation. (line 104)
17038 * --strict, xgettext option: xgettext Invocation. (line 300)
17039 * --stringtable-input, msgattrib option: msgattrib Invocation.
17041 * --stringtable-input, msgcat option: msgcat Invocation. (line 78)
17042 * --stringtable-input, msgcmp option: msgcmp Invocation. (line 63)
17043 * --stringtable-input, msgcomm option: msgcomm Invocation. (line 76)
17044 * --stringtable-input, msgen option: msgen Invocation. (line 52)
17045 * --stringtable-input, msgexec option: msgexec Invocation. (line 60)
17046 * --stringtable-input, msgfilter option: msgfilter Invocation.
17048 * --stringtable-input, msgfmt option: msgfmt Invocation. (line 137)
17049 * --stringtable-input, msggrep option: msggrep Invocation. (line 135)
17050 * --stringtable-input, msginit option: msginit Invocation. (line 43)
17051 * --stringtable-input, msgmerge option: msgmerge Invocation. (line 121)
17052 * --stringtable-input, msgonv option: msgconv Invocation. (line 56)
17053 * --stringtable-input, msguniq option: msguniq Invocation. (line 65)
17054 * --stringtable-output, msgattrib option: msgattrib Invocation.
17056 * --stringtable-output, msgcat option: msgcat Invocation. (line 133)
17057 * --stringtable-output, msgcomm option: msgcomm Invocation. (line 118)
17058 * --stringtable-output, msgconv option: msgconv Invocation. (line 97)
17059 * --stringtable-output, msgen option: msgen Invocation. (line 99)
17060 * --stringtable-output, msgfilter option: msgfilter Invocation.
17062 * --stringtable-output, msggrep option: msggrep Invocation. (line 175)
17063 * --stringtable-output, msginit option: msginit Invocation. (line 77)
17064 * --stringtable-output, msgmerge option: msgmerge Invocation. (line 169)
17065 * --stringtable-output, msgunfmt option: msgunfmt Invocation. (line 135)
17066 * --stringtable-output, msguniq option: msguniq Invocation. (line 115)
17067 * --stringtable-output, xgettext option: xgettext Invocation. (line 310)
17068 * --style, msgattrib option: msgattrib Invocation.
17070 * --style, msgcat option <1>: The --style option. (line 6)
17071 * --style, msgcat option: msgcat Invocation. (line 104)
17072 * --style, msgcomm option: msgcomm Invocation. (line 89)
17073 * --style, msgconv option: msgconv Invocation. (line 69)
17074 * --style, msgen option: msgen Invocation. (line 71)
17075 * --style, msgfilter option: msgfilter Invocation.
17077 * --style, msggrep option: msggrep Invocation. (line 148)
17078 * --style, msginit option: msginit Invocation. (line 67)
17079 * --style, msgmerge option: msgmerge Invocation. (line 141)
17080 * --style, msgunfmt option: msgunfmt Invocation. (line 113)
17081 * --style, msguniq option: msguniq Invocation. (line 86)
17082 * --style, xgettext option: xgettext Invocation. (line 280)
17083 * --suffix, msgmerge option: msgmerge Invocation. (line 68)
17084 * --symlink, gettextize option: gettextize Invocation.
17086 * --tcl, msgfmt option: msgfmt Invocation. (line 43)
17087 * --tcl, msgunfmt option: msgunfmt Invocation. (line 26)
17088 * --to-code, msgcat option: msgcat Invocation. (line 87)
17089 * --to-code, msgconv option: msgconv Invocation. (line 42)
17090 * --to-code, msguniq option: msguniq Invocation. (line 74)
17091 * --translated, msgattrib option: msgattrib Invocation.
17093 * --trigraphs, xgettext option: xgettext Invocation. (line 241)
17094 * --unique, msgcat option: msgcat Invocation. (line 65)
17095 * --unique, msgcomm option: msgcomm Invocation. (line 63)
17096 * --unique, msguniq option: msguniq Invocation. (line 53)
17097 * --untranslated, msgattrib option: msgattrib Invocation.
17099 * --update, msgmerge option: msgmerge Invocation. (line 45)
17100 * --use-first, msgcat option: msgcat Invocation. (line 90)
17101 * --use-first, msguniq option: msguniq Invocation. (line 77)
17102 * --use-fuzzy, msgcmp option: msgcmp Invocation. (line 44)
17103 * --use-fuzzy, msgfmt option: msgfmt Invocation. (line 199)
17104 * --use-untranslated, msgcmp option: msgcmp Invocation. (line 50)
17105 * --variables, envsubst option: envsubst Invocation. (line 15)
17106 * --verbose, msgfmt option: msgfmt Invocation. (line 235)
17107 * --verbose, msgmerge option: msgmerge Invocation. (line 208)
17108 * --verbose, msgunfmt option: msgunfmt Invocation. (line 170)
17109 * --version, autopoint option: autopoint Invocation.
17111 * --version, envsubst option: envsubst Invocation. (line 26)
17112 * --version, gettext option: gettext Invocation. (line 40)
17113 * --version, gettextize option: gettextize Invocation.
17115 * --version, msgattrib option: msgattrib Invocation.
17117 * --version, msgcat option: msgcat Invocation. (line 168)
17118 * --version, msgcmp option: msgcmp Invocation. (line 76)
17119 * --version, msgcomm option: msgcomm Invocation. (line 156)
17120 * --version, msgconv option: msgconv Invocation. (line 132)
17121 * --version, msgen option: msgen Invocation. (line 134)
17122 * --version, msgexec option: msgexec Invocation. (line 73)
17123 * --version, msgfilter option: msgfilter Invocation.
17125 * --version, msgfmt option: msgfmt Invocation. (line 226)
17126 * --version, msggrep option: msggrep Invocation. (line 208)
17127 * --version, msginit option: msginit Invocation. (line 103)
17128 * --version, msgmerge option: msgmerge Invocation. (line 204)
17129 * --version, msgunfmt option: msgunfmt Invocation. (line 166)
17130 * --version, msguniq option: msguniq Invocation. (line 150)
17131 * --version, ngettext option: ngettext Invocation. (line 35)
17132 * --version, xgettext option: xgettext Invocation. (line 419)
17133 * --width, msgattrib option: msgattrib Invocation.
17135 * --width, msgcat option: msgcat Invocation. (line 138)
17136 * --width, msgcomm option: msgcomm Invocation. (line 123)
17137 * --width, msgconv option: msgconv Invocation. (line 102)
17138 * --width, msgen option: msgen Invocation. (line 104)
17139 * --width, msgfilter option: msgfilter Invocation.
17141 * --width, msggrep option: msggrep Invocation. (line 180)
17142 * --width, msginit option: msginit Invocation. (line 82)
17143 * --width, msgmerge option: msgmerge Invocation. (line 174)
17144 * --width, msgunfmt option: msgunfmt Invocation. (line 140)
17145 * --width, msguniq option: msguniq Invocation. (line 120)
17146 * --width, xgettext option: xgettext Invocation. (line 315)
17147 * -<, msgcat option: msgcat Invocation. (line 55)
17148 * -<, msgcomm option: msgcomm Invocation. (line 53)
17149 * ->, msgcat option: msgcat Invocation. (line 60)
17150 * ->, msgcomm option: msgcomm Invocation. (line 58)
17151 * -a, msgfmt option: msgfmt Invocation. (line 209)
17152 * -a, xgettext option: xgettext Invocation. (line 107)
17153 * -C, msgfmt option: msgfmt Invocation. (line 183)
17154 * -c, msgfmt option: msgfmt Invocation. (line 146)
17155 * -C, msggrep option: msggrep Invocation. (line 93)
17156 * -C, msgmerge option: msgmerge Invocation. (line 36)
17157 * -c, xgettext option: xgettext Invocation. (line 97)
17158 * -C, xgettext option: xgettext Invocation. (line 64)
17159 * -d, autopoint option: autopoint Invocation.
17161 * -d, gettext option: gettext Invocation. (line 16)
17162 * -d, gettextize option: gettextize Invocation.
17164 * -D, msgattrib option: msgattrib Invocation.
17166 * -D, msgcat option: msgcat Invocation. (line 32)
17167 * -D, msgcmp option: msgcmp Invocation. (line 27)
17168 * -D, msgcomm option: msgcomm Invocation. (line 30)
17169 * -D, msgconv option: msgconv Invocation. (line 19)
17170 * -D, msgen option: msgen Invocation. (line 25)
17171 * -D, msgexec option: msgexec Invocation. (line 44)
17172 * -D, msgfilter option: msgfilter Invocation.
17174 * -d, msgfmt option: msgfmt Invocation. (line 84)
17175 * -D, msgfmt option: msgfmt Invocation. (line 18)
17176 * -D, msggrep option: msggrep Invocation. (line 19)
17177 * -D, msgmerge option: msgmerge Invocation. (line 30)
17178 * -d, msgunfmt option: msgunfmt Invocation. (line 70)
17179 * -d, msguniq option: msguniq Invocation. (line 49)
17180 * -D, msguniq option: msguniq Invocation. (line 26)
17181 * -d, ngettext option: ngettext Invocation. (line 15)
17182 * -d, xgettext option: xgettext Invocation. (line 36)
17183 * -D, xgettext option: xgettext Invocation. (line 24)
17184 * -E, gettext option: gettext Invocation. (line 27)
17185 * -e, gettext option: gettext Invocation. (line 20)
17186 * -e, msgfilter option: msgfilter Invocation.
17188 * -e, msggrep option: msggrep Invocation. (line 109)
17189 * -E, msggrep option: msggrep Invocation. (line 101)
17190 * -E, ngettext option: ngettext Invocation. (line 26)
17191 * -e, ngettext option: ngettext Invocation. (line 19)
17192 * -f, autopoint option: autopoint Invocation.
17194 * -f, gettextize option: gettextize Invocation.
17196 * -F, msgattrib option: msgattrib Invocation.
17198 * -F, msgcat option: msgcat Invocation. (line 156)
17199 * -f, msgcat option: msgcat Invocation. (line 27)
17200 * -F, msgcomm option: msgcomm Invocation. (line 141)
17201 * -f, msgcomm option: msgcomm Invocation. (line 25)
17202 * -F, msgconv option: msgconv Invocation. (line 120)
17203 * -F, msgen option: msgen Invocation. (line 122)
17204 * -F, msgfilter option: msgfilter Invocation.
17206 * -f, msgfilter option: msgfilter Invocation.
17208 * -f, msgfmt option: msgfmt Invocation. (line 199)
17209 * -f, msggrep option: msggrep Invocation. (line 113)
17210 * -F, msggrep option: msggrep Invocation. (line 105)
17211 * -F, msgmerge option: msgmerge Invocation. (line 192)
17212 * -F, msguniq option: msguniq Invocation. (line 138)
17213 * -F, xgettext option: xgettext Invocation. (line 333)
17214 * -f, xgettext option: xgettext Invocation. (line 19)
17215 * -h, envsubst option: envsubst Invocation. (line 22)
17216 * -h, gettext option: gettext Invocation. (line 32)
17217 * -h, msgattrib option: msgattrib Invocation.
17219 * -h, msgcat option: msgcat Invocation. (line 164)
17220 * -h, msgcmp option: msgcmp Invocation. (line 72)
17221 * -h, msgcomm option: msgcomm Invocation. (line 152)
17222 * -h, msgconv option: msgconv Invocation. (line 128)
17223 * -h, msgen option: msgen Invocation. (line 130)
17224 * -h, msgexec option: msgexec Invocation. (line 69)
17225 * -h, msgfilter option: msgfilter Invocation.
17227 * -h, msgfmt option: msgfmt Invocation. (line 222)
17228 * -h, msggrep option: msggrep Invocation. (line 204)
17229 * -h, msginit option: msginit Invocation. (line 99)
17230 * -h, msgmerge option: msgmerge Invocation. (line 200)
17231 * -h, msgunfmt option: msgunfmt Invocation. (line 162)
17232 * -h, msguniq option: msguniq Invocation. (line 146)
17233 * -h, ngettext option: ngettext Invocation. (line 31)
17234 * -h, xgettext option: xgettext Invocation. (line 415)
17235 * -i, msgattrib option: msgattrib Invocation.
17237 * -i, msgcat option: msgcat Invocation. (line 112)
17238 * -i, msgcomm option: msgcomm Invocation. (line 97)
17239 * -i, msgconv option: msgconv Invocation. (line 77)
17240 * -i, msgen option: msgen Invocation. (line 79)
17241 * -i, msgexec option: msgexec Invocation. (line 40)
17242 * -i, msgfilter option: msgfilter Invocation.
17244 * -i, msggrep option: msggrep Invocation. (line 117)
17245 * -i, msginit option: msginit Invocation. (line 16)
17246 * -i, msgmerge option: msgmerge Invocation. (line 149)
17247 * -i, msgunfmt option: msgunfmt Invocation. (line 121)
17248 * -i, msguniq option: msguniq Invocation. (line 94)
17249 * -i, xgettext option: xgettext Invocation. (line 288)
17250 * -j, msgfmt option: msgfmt Invocation. (line 30)
17251 * -J, msggrep option: msggrep Invocation. (line 81)
17252 * -j, msgunfmt option: msgunfmt Invocation. (line 16)
17253 * -j, xgettext option: xgettext Invocation. (line 88)
17254 * -K, msggrep option: msggrep Invocation. (line 85)
17255 * -k, xgettext option: xgettext Invocation. (line 115)
17256 * -l, msgfmt option: msgfmt Invocation. (line 79)
17257 * -l, msginit option: msginit Invocation. (line 52)
17258 * -l, msgunfmt option: msgunfmt Invocation. (line 47)
17259 * -L, xgettext option: xgettext Invocation. (line 56)
17260 * -m, msgcmp option: msgcmp Invocation. (line 36)
17261 * -M, msggrep option: msggrep Invocation. (line 77)
17262 * -m, msgmerge option: msgmerge Invocation. (line 101)
17263 * -M, xgettext option: xgettext Invocation. (line 407)
17264 * -m, xgettext option: xgettext Invocation. (line 403)
17265 * -n, gettext option: gettext Invocation. (line 35)
17266 * -n, msgattrib option: msgattrib Invocation.
17268 * -n, msgcat option: msgcat Invocation. (line 119)
17269 * -N, msgcmp option: msgcmp Invocation. (line 40)
17270 * -n, msgcomm option: msgcomm Invocation. (line 104)
17271 * -n, msgfilter option: msgfilter Invocation.
17273 * -N, msggrep option: msggrep Invocation. (line 72)
17274 * -N, msgmerge option: msgmerge Invocation. (line 105)
17275 * -n, msguniq option: msguniq Invocation. (line 101)
17276 * -n, xgettext option: xgettext Invocation. (line 297)
17277 * -o, msgattrib option: msgattrib Invocation.
17279 * -o, msgcat option: msgcat Invocation. (line 44)
17280 * -o, msgcomm option: msgcomm Invocation. (line 42)
17281 * -o, msgconv option: msgconv Invocation. (line 31)
17282 * -o, msgen option: msgen Invocation. (line 37)
17283 * -o, msgfilter option: msgfilter Invocation.
17285 * -o, msgfmt option: msgfmt Invocation. (line 54)
17286 * -o, msggrep option: msggrep Invocation. (line 31)
17287 * -o, msginit option: msginit Invocation. (line 27)
17288 * -o, msgmerge option: msgmerge Invocation. (line 53)
17289 * -o, msgunfmt option: msgunfmt Invocation. (line 98)
17290 * -o, msguniq option: msguniq Invocation. (line 38)
17291 * -o, xgettext option: xgettext Invocation. (line 40)
17292 * -p, msgattrib option: msgattrib Invocation.
17294 * -P, msgattrib option: msgattrib Invocation.
17296 * -p, msgcat option: msgcat Invocation. (line 128)
17297 * -P, msgcat option: msgcat Invocation. (line 74)
17298 * -P, msgcmp option: msgcmp Invocation. (line 59)
17299 * -p, msgcomm option: msgcomm Invocation. (line 113)
17300 * -P, msgcomm option: msgcomm Invocation. (line 72)
17301 * -p, msgconv option: msgconv Invocation. (line 92)
17302 * -P, msgconv option: msgconv Invocation. (line 52)
17303 * -p, msgen option: msgen Invocation. (line 94)
17304 * -P, msgen option: msgen Invocation. (line 48)
17305 * -P, msgexec option: msgexec Invocation. (line 56)
17306 * -p, msgfilter option: msgfilter Invocation.
17308 * -P, msgfilter option: msgfilter Invocation.
17310 * -P, msgfmt option: msgfmt Invocation. (line 133)
17311 * -p, msggrep option: msggrep Invocation. (line 170)
17312 * -P, msggrep option: msggrep Invocation. (line 131)
17313 * -p, msginit option: msginit Invocation. (line 72)
17314 * -P, msginit option: msginit Invocation. (line 39)
17315 * -p, msgmerge option: msgmerge Invocation. (line 164)
17316 * -P, msgmerge option: msgmerge Invocation. (line 117)
17317 * -p, msgunfmt option: msgunfmt Invocation. (line 130)
17318 * -p, msguniq option: msguniq Invocation. (line 110)
17319 * -P, msguniq option: msguniq Invocation. (line 61)
17320 * -p, xgettext option: xgettext Invocation. (line 45)
17321 * -q, msgmerge option: msgmerge Invocation. (line 213)
17322 * -r, msgfmt option: msgfmt Invocation. (line 75)
17323 * -r, msgunfmt option: msgunfmt Invocation. (line 43)
17324 * -s, msgattrib option: msgattrib Invocation.
17326 * -s, msgcat option: msgcat Invocation. (line 151)
17327 * -s, msgcomm option: msgcomm Invocation. (line 136)
17328 * -s, msgconv option: msgconv Invocation. (line 115)
17329 * -s, msgen option: msgen Invocation. (line 117)
17330 * -s, msgfilter option: msgfilter Invocation.
17332 * -s, msgmerge option: msgmerge Invocation. (line 187)
17333 * -s, msgunfmt option: msgunfmt Invocation. (line 153)
17334 * -s, msguniq option: msguniq Invocation. (line 133)
17335 * -s, xgettext option: xgettext Invocation. (line 328)
17336 * -t, msgcat option: msgcat Invocation. (line 87)
17337 * -t, msgconv option: msgconv Invocation. (line 42)
17338 * -T, msggrep option: msggrep Invocation. (line 89)
17339 * -t, msguniq option: msguniq Invocation. (line 74)
17340 * -T, xgettext option: xgettext Invocation. (line 241)
17341 * -u, msgcat option: msgcat Invocation. (line 65)
17342 * -u, msgcomm option: msgcomm Invocation. (line 63)
17343 * -U, msgmerge option: msgmerge Invocation. (line 45)
17344 * -u, msguniq option: msguniq Invocation. (line 53)
17345 * -V, envsubst option: envsubst Invocation. (line 26)
17346 * -v, envsubst option: envsubst Invocation. (line 15)
17347 * -V, gettext option: gettext Invocation. (line 40)
17348 * -V, msgattrib option: msgattrib Invocation.
17350 * -V, msgcat option: msgcat Invocation. (line 168)
17351 * -V, msgcmp option: msgcmp Invocation. (line 76)
17352 * -V, msgcomm option: msgcomm Invocation. (line 156)
17353 * -V, msgconv option: msgconv Invocation. (line 132)
17354 * -V, msgen option: msgen Invocation. (line 134)
17355 * -V, msgexec option: msgexec Invocation. (line 73)
17356 * -V, msgfilter option: msgfilter Invocation.
17358 * -v, msgfmt option: msgfmt Invocation. (line 235)
17359 * -V, msgfmt option: msgfmt Invocation. (line 226)
17360 * -V, msggrep option: msggrep Invocation. (line 208)
17361 * -v, msggrep option: msggrep Invocation. (line 121)
17362 * -V, msginit option: msginit Invocation. (line 103)
17363 * -v, msgmerge option: msgmerge Invocation. (line 208)
17364 * -V, msgmerge option: msgmerge Invocation. (line 204)
17365 * -v, msgunfmt option: msgunfmt Invocation. (line 170)
17366 * -V, msgunfmt option: msgunfmt Invocation. (line 166)
17367 * -V, msguniq option: msguniq Invocation. (line 150)
17368 * -V, ngettext option: ngettext Invocation. (line 35)
17369 * -V, xgettext option: xgettext Invocation. (line 419)
17370 * -w, msgattrib option: msgattrib Invocation.
17372 * -w, msgcat option: msgcat Invocation. (line 138)
17373 * -w, msgcomm option: msgcomm Invocation. (line 123)
17374 * -w, msgconv option: msgconv Invocation. (line 102)
17375 * -w, msgen option: msgen Invocation. (line 104)
17376 * -w, msgfilter option: msgfilter Invocation.
17378 * -w, msggrep option: msggrep Invocation. (line 180)
17379 * -w, msginit option: msginit Invocation. (line 82)
17380 * -w, msgmerge option: msgmerge Invocation. (line 174)
17381 * -w, msgunfmt option: msgunfmt Invocation. (line 140)
17382 * -w, msguniq option: msguniq Invocation. (line 120)
17383 * -w, xgettext option: xgettext Invocation. (line 315)
17384 * -X, msggrep option: msggrep Invocation. (line 97)
17385 * -x, xgettext option: xgettext Invocation. (line 92)
17388 File: gettext.info, Node: Variable Index, Next: PO Mode Index, Prev: Option Index, Up: Top
17396 * GETTEXT_LOG_UNTRANSLATED, environment variable: Prioritizing messages.
17398 * LANG, environment variable <1>: gettext grok. (line 32)
17399 * LANG, environment variable: Locale Environment Variables.
17401 * LANGUAGE, environment variable <1>: po/Rules-*. (line 11)
17402 * LANGUAGE, environment variable <2>: gettext grok. (line 28)
17403 * LANGUAGE, environment variable: Locale Environment Variables.
17405 * LC_ALL, environment variable <1>: gettext grok. (line 28)
17406 * LC_ALL, environment variable: Locale Environment Variables.
17408 * LC_COLLATE, environment variable <1>: gettext grok. (line 30)
17409 * LC_COLLATE, environment variable: Locale Environment Variables.
17411 * LC_CTYPE, environment variable <1>: gettext grok. (line 30)
17412 * LC_CTYPE, environment variable: Locale Environment Variables.
17414 * LC_MESSAGES, environment variable <1>: gettext grok. (line 30)
17415 * LC_MESSAGES, environment variable: Locale Environment Variables.
17417 * LC_MONETARY, environment variable <1>: gettext grok. (line 30)
17418 * LC_MONETARY, environment variable: Locale Environment Variables.
17420 * LC_NUMERIC, environment variable <1>: gettext grok. (line 30)
17421 * LC_NUMERIC, environment variable: Locale Environment Variables.
17423 * LC_TIME, environment variable <1>: gettext grok. (line 30)
17424 * LC_TIME, environment variable: Locale Environment Variables.
17426 * LINGUAS, environment variable: Installers. (line 17)
17427 * MSGEXEC_LOCATION, environment variable: msgexec Invocation. (line 18)
17428 * MSGEXEC_MSGCTXT, environment variable: msgexec Invocation. (line 18)
17429 * MSGEXEC_MSGID, environment variable: msgexec Invocation. (line 18)
17430 * MSGFILTER_LOCATION, environment variable: msgfilter Invocation.
17432 * MSGFILTER_MSGCTXT, environment variable: msgfilter Invocation.
17434 * MSGFILTER_MSGID, environment variable: msgfilter Invocation. (line 11)
17435 * PO_STYLE, environment variable: The --style option. (line 10)
17436 * TERM, environment variable: The TERM variable. (line 6)
17437 * TEXTDOMAIN, environment variable: sh. (line 23)
17438 * TEXTDOMAINDIR, environment variable: sh. (line 26)
17441 File: gettext.info, Node: PO Mode Index, Next: Autoconf Macro Index, Prev: Variable Index, Up: Top
17449 * #, PO Mode command: Modifying Comments. (line 24)
17450 * ,, PO Mode command: Marking. (line 44)
17451 * ., PO Mode command: Entry Positioning. (line 20)
17452 * .emacs customizations: Installation. (line 13)
17453 * 0, PO Mode command: Main PO Commands. (line 40)
17454 * <, PO Mode command: Entry Positioning. (line 29)
17455 * =, PO Mode command: Main PO Commands. (line 47)
17456 * >, PO Mode command: Entry Positioning. (line 32)
17457 * ?, PO Mode command: Main PO Commands. (line 44)
17458 * _, PO Mode command: Main PO Commands. (line 30)
17459 * a, PO Mode command: Auxiliary. (line 40)
17460 * A, PO Mode command: Auxiliary. (line 28)
17461 * a, PO Mode command: Auxiliary. (line 21)
17462 * auxiliary PO file: Auxiliary. (line 13)
17463 * C-c C-a, PO Mode command <1>: Auxiliary. (line 25)
17464 * C-c C-a, PO Mode command: Subedit. (line 17)
17465 * C-c C-c, PO Mode command: Subedit. (line 11)
17466 * C-c C-k, PO Mode command: Subedit. (line 14)
17467 * C-j, PO Mode command: Modifying Translations.
17469 * commands: Main PO Commands. (line 6)
17470 * comment out PO file entry: Obsolete Entries. (line 47)
17471 * consulting program sources: C Sources Context. (line 6)
17472 * consulting translations to other languages: Auxiliary. (line 6)
17473 * current entry of a PO file: Entry Positioning. (line 6)
17474 * cut and paste for translated strings: Modifying Translations.
17476 * DEL, PO Mode command <1>: Obsolete Entries. (line 32)
17477 * DEL, PO Mode command: Fuzzy Entries. (line 60)
17478 * editing comments: Modifying Comments. (line 6)
17479 * editing multiple entries: Subedit. (line 62)
17480 * editing translations: Modifying Translations.
17482 * etags, using for marking strings: Marking. (line 17)
17483 * exiting PO subedit: Subedit. (line 20)
17484 * F, PO Mode command: Fuzzy Entries. (line 39)
17485 * f, PO Mode command: Fuzzy Entries. (line 39)
17486 * F, PO Mode command: Fuzzy Entries. (line 33)
17487 * f, PO Mode command: Fuzzy Entries. (line 30)
17488 * find source fragment for a PO file entry: C Sources Context.
17490 * h, PO Mode command: Main PO Commands. (line 44)
17491 * installing PO mode: Installation. (line 13)
17492 * K, PO Mode command: Modifying Comments. (line 27)
17493 * k, PO Mode command <1>: Modifying Translations.
17495 * k, PO Mode command: Untranslated Entries.
17497 * LFD, PO Mode command: Modifying Translations.
17499 * looking at the source to aid translation: C Sources Context.
17501 * m, PO Mode command: Entry Positioning. (line 35)
17502 * M-,, PO Mode command: Marking. (line 48)
17503 * M-., PO Mode command: Marking. (line 51)
17504 * M-A, PO Mode command: Auxiliary. (line 32)
17505 * M-S, PO Mode command: C Sources Context. (line 89)
17506 * M-s, PO Mode command: C Sources Context. (line 53)
17507 * M-S, PO Mode command: C Sources Context. (line 49)
17508 * M-s, PO Mode command: C Sources Context. (line 41)
17509 * marking strings for translation: Marking. (line 6)
17510 * moving by fuzzy entries: Fuzzy Entries. (line 24)
17511 * moving by obsolete entries: Obsolete Entries. (line 22)
17512 * moving by translated entries: Translated Entries. (line 12)
17513 * moving by untranslated entries: Untranslated Entries.
17515 * moving through a PO file: Entry Positioning. (line 14)
17516 * n, PO Mode command: Entry Positioning. (line 23)
17517 * next-error, stepping through PO file validation results: Main PO Commands.
17519 * normalize, PO Mode command: Auxiliary. (line 64)
17520 * O, PO Mode command: Obsolete Entries. (line 36)
17521 * o, PO Mode command: Obsolete Entries. (line 36)
17522 * O, PO Mode command: Obsolete Entries. (line 29)
17523 * o, PO Mode command: Obsolete Entries. (line 26)
17524 * obsolete active entry: Obsolete Entries. (line 47)
17525 * p, PO Mode command: Entry Positioning. (line 26)
17526 * pending subedits: Subedit. (line 73)
17527 * po-auto-edit-with-msgid, PO Mode variable: Modifying Translations.
17529 * po-auto-fuzzy-on-edit, PO Mode variable: Translated Entries.
17531 * po-auto-select-on-unfuzzy, PO Mode variable: Fuzzy Entries. (line 44)
17532 * po-confirm-and-quit, PO Mode command: Main PO Commands. (line 62)
17533 * po-consider-as-auxiliary, PO Mode command: Auxiliary. (line 36)
17534 * po-consider-source-path, PO Mode command: C Sources Context.
17536 * po-current-entry, PO Mode command: Entry Positioning. (line 46)
17537 * po-cycle-auxiliary, PO Mode command: Auxiliary. (line 40)
17538 * po-cycle-source-reference, PO Mode command: C Sources Context.
17540 * po-edit-comment, PO Mode command: Modifying Comments. (line 46)
17541 * po-edit-msgstr, PO Mode command: Modifying Translations.
17543 * po-exchange-location, PO Mode command: Entry Positioning. (line 106)
17544 * po-fade-out-entry, PO Mode command <1>: Obsolete Entries. (line 47)
17545 * po-fade-out-entry, PO Mode command: Fuzzy Entries. (line 60)
17546 * po-first-entry, PO Mode command: Entry Positioning. (line 74)
17547 * po-help, PO Mode command: Main PO Commands. (line 83)
17548 * po-ignore-as-auxiliary, PO Mode command: Auxiliary. (line 36)
17549 * po-ignore-source-path, PO Mode command: C Sources Context. (line 89)
17550 * po-kill-comment, PO Mode command: Modifying Comments. (line 60)
17551 * po-kill-msgstr, PO Mode command <1>: Modifying Translations.
17553 * po-kill-msgstr, PO Mode command: Untranslated Entries.
17555 * po-kill-ring-save-comment, PO Mode command: Modifying Comments.
17557 * po-kill-ring-save-msgstr, PO Mode command: Modifying Translations.
17559 * po-last-entry, PO Mode command: Entry Positioning. (line 74)
17560 * po-mark-translatable, PO Mode command: Marking. (line 98)
17561 * po-msgid-to-msgstr, PO Mode command: Modifying Translations.
17563 * po-next-entry, PO Mode command: Entry Positioning. (line 69)
17564 * po-next-fuzzy-entry, PO Mode command: Fuzzy Entries. (line 39)
17565 * po-next-obsolete-entry, PO Mode command: Obsolete Entries. (line 36)
17566 * po-next-translated-entry, PO Mode command: Translated Entries.
17568 * po-next-untranslated-entry, PO Mode command: Untranslated Entries.
17570 * po-normalize, PO Mode command: Normalizing. (line 31)
17571 * po-other-window, PO Mode command: Main PO Commands. (line 72)
17572 * po-pop-location, PO Mode command: Entry Positioning. (line 92)
17573 * po-previous-entry, PO Mode command: Entry Positioning. (line 69)
17574 * po-previous-fuzzy-entry, PO Mode command: Fuzzy Entries. (line 39)
17575 * po-previous-obsolete-entry, PO Mode command: Obsolete Entries.
17577 * po-previous-translated-entry, PO Mode command: Translated Entries.
17579 * po-previous-untransted-entry, PO Mode command: Untranslated Entries.
17581 * po-push-location, PO Mode command: Entry Positioning. (line 92)
17582 * po-quit, PO Mode command: Main PO Commands. (line 62)
17583 * po-select-auxiliary, PO Mode command: Auxiliary. (line 49)
17584 * po-select-mark-and-mark, PO Mode command: Marking. (line 98)
17585 * po-select-source-reference, PO Mode command: C Sources Context.
17587 * po-statistics, PO Mode command: Main PO Commands. (line 87)
17588 * po-subedit-abort, PO Mode command: Subedit. (line 27)
17589 * po-subedit-cycle-auxiliary, PO Mode command: Subedit. (line 35)
17590 * po-subedit-exit, PO Mode command: Subedit. (line 20)
17591 * po-subedit-mode-hook, PO Mode variable: Modifying Comments. (line 57)
17592 * po-tags-search, PO Mode command: Marking. (line 56)
17593 * po-undo, PO Mode command: Main PO Commands. (line 53)
17594 * po-unfuzzy, PO Mode command: Fuzzy Entries. (line 44)
17595 * po-validate, PO Mode command: Main PO Commands. (line 92)
17596 * po-yank-comment, PO Mode command: Modifying Comments. (line 60)
17597 * po-yank-msgstr, PO Mode command: Modifying Translations.
17599 * q, PO Mode command: Main PO Commands. (line 62)
17600 * Q, PO Mode command: Main PO Commands. (line 62)
17601 * q, PO Mode command: Main PO Commands. (line 36)
17602 * Q, PO Mode command: Main PO Commands. (line 33)
17603 * r, PO Mode command: Entry Positioning. (line 39)
17604 * RET, PO Mode command: Modifying Translations.
17606 * S, PO Mode command: C Sources Context. (line 89)
17607 * s, PO Mode command: C Sources Context. (line 53)
17608 * S, PO Mode command: C Sources Context. (line 45)
17609 * s, PO Mode command: C Sources Context. (line 37)
17610 * starting a string translation: Modifying Translations.
17612 * string normalization in entries: Normalizing. (line 30)
17613 * subedit minor mode: Subedit. (line 6)
17614 * T, PO Mode command: Translated Entries. (line 23)
17615 * t, PO Mode command: Translated Entries. (line 23)
17616 * T, PO Mode command: Translated Entries. (line 19)
17617 * t, PO Mode command: Translated Entries. (line 16)
17618 * TAB, PO Mode command: Fuzzy Entries. (line 36)
17619 * TAGS, and marking translatable strings: Marking. (line 31)
17620 * U, PO Mode command: Untranslated Entries.
17622 * u, PO Mode command: Untranslated Entries.
17624 * U, PO Mode command: Untranslated Entries.
17626 * u, PO Mode command: Untranslated Entries.
17628 * use the source, Luke: C Sources Context. (line 6)
17629 * using obsolete translations to make new entries: Modifying Translations.
17631 * using translation compendia: Compendium. (line 6)
17632 * V, PO Mode command: Main PO Commands. (line 50)
17633 * W, PO Mode command: Modifying Comments. (line 31)
17634 * w, PO Mode command: Modifying Translations.
17636 * x, PO Mode command: Entry Positioning. (line 42)
17637 * Y, PO Mode command: Modifying Comments. (line 35)
17638 * y, PO Mode command: Modifying Translations.
17642 File: gettext.info, Node: Autoconf Macro Index, Next: Index, Prev: PO Mode Index, Up: Top
17644 Autoconf Macro Index
17645 ********************
17650 * AM_GNU_GETTEXT: AM_GNU_GETTEXT. (line 6)
17651 * AM_GNU_GETTEXT_INTL_SUBDIR: AM_GNU_GETTEXT_INTL_SUBDIR.
17653 * AM_GNU_GETTEXT_NEED: AM_GNU_GETTEXT_NEED. (line 6)
17654 * AM_GNU_GETTEXT_VERSION: AM_GNU_GETTEXT_VERSION.
17656 * AM_ICONV: AM_ICONV. (line 6)
17657 * AM_PO_SUBDIRS: AM_PO_SUBDIRS. (line 6)
17658 * AM_XGETTEXT_OPTION: AM_XGETTEXT_OPTION. (line 6)
17661 File: gettext.info, Node: Index, Prev: Autoconf Macro Index, Up: Top
17669 * _, a macro to mark strings for translation: Mark Keywords. (line 45)
17670 * _nl_msg_cat_cntr: gettext grok. (line 62)
17671 * ABOUT-NLS file: Installing Localizations.
17673 * acconfig.h file: acconfig. (line 6)
17674 * accumulating translations: Creating Compendia. (line 14)
17675 * aclocal.m4 file: aclocal. (line 6)
17676 * adding keywords, xgettext: xgettext Invocation. (line 119)
17677 * ambiguities: Preparing Strings. (line 41)
17678 * apply a filter to translations: msgfilter Invocation.
17680 * apply command to all translations in a catalog: msgexec Invocation.
17682 * Arabic digits: c-format. (line 28)
17683 * attribute manipulation: msgattrib Invocation.
17685 * attribute, fuzzy: Fuzzy Entries. (line 6)
17686 * attributes of a PO file entry: Fuzzy Entries. (line 6)
17687 * attributes, manipulating: Manipulating. (line 56)
17688 * autoconf macros for gettext: autoconf macros. (line 6)
17689 * autopoint program, usage: autopoint Invocation.
17691 * auxiliary PO file: Auxiliary. (line 13)
17692 * available translations: Installing Localizations.
17694 * awk: gawk. (line 6)
17695 * awk-format flag: PO Files. (line 149)
17696 * backup old file, and msgmerge program: msgmerge Invocation. (line 65)
17697 * bash: bash. (line 6)
17698 * bibliography: References. (line 6)
17699 * big picture: Overview. (line 6)
17700 * bind_textdomain_codeset: Charset conversion. (line 28)
17701 * Boost format strings: xgettext Invocation. (line 254)
17702 * boost-format flag: PO Files. (line 198)
17703 * bug report address: Introduction. (line 24)
17704 * C and C-like languages: C. (line 6)
17705 * C trigraphs: xgettext Invocation. (line 241)
17707 * C# mode, and msgfmt program: msgfmt Invocation. (line 36)
17708 * C# mode, and msgunfmt program: msgunfmt Invocation. (line 19)
17709 * C# resources mode, and msgfmt program: msgfmt Invocation. (line 40)
17710 * C# resources mode, and msgunfmt program: msgunfmt Invocation.
17712 * C#, string concatenation: Preparing Strings. (line 168)
17713 * c-format flag: PO Files. (line 90)
17714 * c-format, and xgettext: c-format Flag. (line 48)
17715 * catalog encoding and msgexec output: msgexec Invocation. (line 25)
17716 * catclose, a catgets function: Interface to catgets.
17718 * catgets, a catgets function: Interface to catgets.
17720 * catgets, X/Open specification: catgets. (line 6)
17721 * catopen, a catgets function: Interface to catgets.
17723 * character encoding: Aspects. (line 67)
17724 * charset conversion at runtime: Charset conversion. (line 6)
17725 * charset of PO files: Header Entry. (line 106)
17726 * check format strings: msgfmt Invocation. (line 150)
17727 * checking of translations: Manipulating. (line 41)
17728 * clisp: Common Lisp. (line 6)
17729 * clisp C sources: clisp C. (line 6)
17730 * codeset: Aspects. (line 67)
17731 * comments in PO files: PO Files. (line 307)
17732 * comments, automatic: PO Files. (line 36)
17733 * comments, extracted: PO Files. (line 36)
17734 * comments, translator: PO Files. (line 36)
17735 * Common Lisp: Common Lisp. (line 6)
17736 * compare PO files: msgcmp Invocation. (line 8)
17737 * comparison of interfaces: Comparison. (line 6)
17738 * compatibility with X/Open msgfmt: msgfmt Invocation. (line 183)
17739 * compendium: Compendium. (line 6)
17740 * compendium, creating: Creating Compendia. (line 6)
17741 * concatenate PO files: msgcat Invocation. (line 8)
17742 * concatenating PO files into a compendium: Creating Compendia.
17744 * concatenation of strings: Preparing Strings. (line 117)
17745 * config.h.in file: config.h.in. (line 6)
17746 * context: Contexts. (line 6)
17747 * context, argument specification in xgettext: xgettext Invocation.
17749 * context, in MO files: MO Files. (line 71)
17750 * context, in PO files: PO Files. (line 202)
17751 * control characters: Preparing Strings. (line 190)
17752 * convert binary message catalog into PO file: msgunfmt Invocation.
17754 * convert translations to a different encoding: msgconv Invocation.
17756 * converting a package to use gettext: Prerequisites. (line 6)
17757 * country codes: Country Codes. (line 6)
17758 * create new PO file: msginit Invocation. (line 8)
17759 * creating a new PO file: Creating. (line 6)
17760 * creating compendia: Creating Compendia. (line 6)
17761 * csharp-format flag: PO Files. (line 145)
17762 * currency symbols: Aspects. (line 79)
17763 * date format: Aspects. (line 84)
17764 * dcngettext: Plural forms. (line 161)
17765 * dcpgettext: Contexts. (line 56)
17766 * dcpgettext_expr: Contexts. (line 112)
17767 * debugging messages marked as format strings: xgettext Invocation.
17769 * dialect: Manipulating. (line 28)
17770 * disabling NLS: lib/gettext.h. (line 6)
17771 * distribution tarball: Release Management. (line 6)
17772 * dngettext: Plural forms. (line 153)
17773 * dollar substitution: envsubst Invocation. (line 8)
17774 * domain ambiguities: Ambiguities. (line 6)
17775 * dpgettext: Contexts. (line 56)
17776 * dpgettext_expr: Contexts. (line 112)
17777 * duplicate elimination: Manipulating. (line 45)
17778 * duplicate removal: msguniq Invocation. (line 8)
17779 * editing comments in PO files: Modifying Comments. (line 6)
17780 * Editing PO Files: Editing. (line 6)
17781 * editing translations: Modifying Translations.
17783 * elisp-format flag: PO Files. (line 125)
17784 * Emacs Lisp: Emacs Lisp. (line 6)
17785 * Emacs PO Mode: PO Mode. (line 6)
17786 * encoding: Aspects. (line 67)
17787 * encoding conversion: Manipulating. (line 17)
17788 * encoding conversion at runtime: Charset conversion. (line 6)
17789 * encoding for your language: Header Entry. (line 135)
17790 * encoding list: Header Entry. (line 119)
17791 * encoding of PO files: Header Entry. (line 106)
17792 * environment variables: envsubst Invocation. (line 8)
17793 * envsubst program, usage: envsubst Invocation. (line 6)
17794 * eval_gettext function, usage: eval_gettext Invocation.
17796 * eval_ngettext function, usage: eval_ngettext Invocation.
17798 * evolution of packages: Overview. (line 127)
17799 * extracting parts of a PO file into a compendium: Creating Compendia.
17801 * FDL, GNU Free Documentation License: GNU FDL. (line 6)
17802 * file format, .mo: MO Files. (line 6)
17803 * file format, .po: PO Files. (line 6)
17804 * files, .po and .mo: Files. (line 6)
17805 * files, .pot: Overview. (line 67)
17806 * filter messages according to attributes: msgattrib Invocation.
17808 * find common messages: msgcomm Invocation. (line 8)
17809 * force use of fuzzy entries: msgfmt Invocation. (line 199)
17810 * format strings: c-format Flag. (line 6)
17811 * Free Pascal: Pascal. (line 6)
17812 * function attribute, __format__: xgettext Invocation. (line 205)
17813 * function attribute, __format_arg__: xgettext Invocation. (line 219)
17814 * fuzzy entries: Fuzzy Entries. (line 6)
17815 * fuzzy flag: PO Files. (line 80)
17816 * gawk: gawk. (line 6)
17817 * gcc-internal-format flag: PO Files. (line 177)
17818 * GCC-source: GCC-source. (line 6)
17819 * generate binary message catalog from PO file: msgfmt Invocation.
17821 * generate translation catalog in English: msgen Invocation. (line 8)
17822 * gettext files: Adjusting Files. (line 6)
17823 * gettext installation: Installation. (line 6)
17824 * gettext interface: Interface to gettext.
17826 * gettext program, usage: gettext Invocation. (line 6)
17827 * gettext vs catgets: Comparison. (line 6)
17828 * gettext, a programmer's view: gettext. (line 6)
17829 * gettext.h file: lib/gettext.h. (line 6)
17830 * gettextize program, usage: gettextize Invocation.
17832 * gfc-internal-format flag: PO Files. (line 181)
17833 * GNOME PO file editor: Gtranslator. (line 6)
17834 * GPL, GNU General Public License: GNU GPL. (line 6)
17835 * GUI programs: Contexts. (line 6)
17836 * guile: Scheme. (line 6)
17837 * hash table, inside MO files: MO Files. (line 55)
17838 * he, she, and they: Introduction. (line 15)
17839 * header entry of a PO file: Header Entry. (line 6)
17840 * help option: Preparing Strings. (line 109)
17841 * history of GNU gettext: History. (line 6)
17842 * i18n: Concepts. (line 6)
17843 * importing PO files: Normalizing. (line 55)
17844 * include file libintl.h <1>: lib/gettext.h. (line 29)
17845 * include file libintl.h <2>: Comparison. (line 33)
17846 * include file libintl.h <3>: Importing. (line 11)
17847 * include file libintl.h: Overview. (line 57)
17848 * initialization: Triggering. (line 6)
17849 * initialize new PO file: msginit Invocation. (line 8)
17850 * initialize translations from a compendium: Using Compendia. (line 12)
17851 * installing gettext: Installation. (line 6)
17852 * interface to catgets: Interface to catgets.
17854 * internationalization: Concepts. (line 16)
17855 * inttypes.h: Preparing Strings. (line 133)
17856 * ISO 3166: Country Codes. (line 6)
17857 * ISO 639: Language Codes. (line 6)
17858 * Java: Java. (line 6)
17859 * Java mode, and msgfmt program: msgfmt Invocation. (line 30)
17860 * Java mode, and msgunfmt program: msgunfmt Invocation. (line 16)
17861 * Java, string concatenation: Preparing Strings. (line 168)
17862 * java-format flag: PO Files. (line 141)
17863 * KDE format strings: xgettext Invocation. (line 250)
17864 * KDE PO file editor: KBabel. (line 6)
17865 * kde-format flag: PO Files. (line 194)
17866 * keyboard accelerator checking: msgfmt Invocation. (line 187)
17867 * l10n: Concepts. (line 6)
17868 * language codes: Language Codes. (line 6)
17869 * language selection: Locale Environment Variables.
17871 * language selection at runtime: gettext grok. (line 14)
17872 * large package: Ambiguities. (line 6)
17873 * LGPL, GNU Lesser General Public License: GNU LGPL. (line 6)
17874 * libiconv library: AM_ICONV. (line 21)
17875 * libintl for C#: C#. (line 178)
17876 * libintl for Java: Java. (line 105)
17877 * libintl library: AM_GNU_GETTEXT. (line 53)
17878 * librep Lisp: librep. (line 6)
17879 * librep-format flag: PO Files. (line 129)
17880 * License, GNU FDL: GNU FDL. (line 6)
17881 * License, GNU GPL: GNU GPL. (line 6)
17882 * License, GNU LGPL: GNU LGPL. (line 6)
17883 * Licenses: Licenses. (line 6)
17884 * LINGUAS file: po/LINGUAS. (line 6)
17885 * link with libintl: Overview. (line 62)
17886 * Linux <1>: Header Entry. (line 132)
17887 * Linux <2>: Overview. (line 62)
17888 * Linux: Aspects. (line 125)
17889 * Lisp: Common Lisp. (line 6)
17890 * lisp-format flag: PO Files. (line 121)
17891 * list of translation teams, where to find: Header Entry. (line 59)
17892 * locale categories: Aspects. (line 61)
17893 * locale category, LC_ALL: Triggering. (line 23)
17894 * locale category, LC_COLLATE: Triggering. (line 53)
17895 * locale category, LC_CTYPE <1>: Triggering. (line 23)
17896 * locale category, LC_CTYPE: Aspects. (line 67)
17897 * locale category, LC_MESSAGES <1>: Triggering. (line 53)
17898 * locale category, LC_MESSAGES: Aspects. (line 108)
17899 * locale category, LC_MONETARY <1>: Triggering. (line 53)
17900 * locale category, LC_MONETARY: Aspects. (line 79)
17901 * locale category, LC_NUMERIC <1>: Triggering. (line 53)
17902 * locale category, LC_NUMERIC: Aspects. (line 94)
17903 * locale category, LC_RESPONSES: Triggering. (line 53)
17904 * locale category, LC_TIME <1>: Triggering. (line 53)
17905 * locale category, LC_TIME: Aspects. (line 84)
17906 * locale program: Header Entry. (line 112)
17907 * localization: Concepts. (line 26)
17908 * lookup message translation <1>: eval_gettext Invocation.
17910 * lookup message translation: gettext Invocation. (line 9)
17911 * lookup plural message translation <1>: eval_ngettext Invocation.
17913 * lookup plural message translation: ngettext Invocation. (line 8)
17914 * magic signature of MO files: MO Files. (line 9)
17915 * Makefile.in.in extensions: po/Rules-*. (line 6)
17916 * Makevars file: po/Makevars. (line 6)
17917 * manipulating PO files: Manipulating. (line 6)
17918 * marking Perl sources: Perl. (line 93)
17919 * marking string initializers: Special cases. (line 6)
17920 * marking strings that require translation: Mark Keywords. (line 6)
17921 * marking strings, preparations: Preparing Strings. (line 6)
17922 * marking translatable strings: Overview. (line 34)
17923 * markup: Preparing Strings. (line 190)
17924 * menu entries: Contexts. (line 6)
17925 * menu, keyboard accelerator support: msgfmt Invocation. (line 187)
17926 * merge PO files: msgcat Invocation. (line 8)
17927 * merging two PO files: Manipulating. (line 10)
17928 * message catalog files location: Locating Catalogs. (line 6)
17929 * messages: Aspects. (line 108)
17930 * migration from earlier versions of gettext: Prerequisites. (line 6)
17931 * mkinstalldirs file: mkinstalldirs. (line 6)
17932 * mnemonics of menu entries: msgfmt Invocation. (line 187)
17933 * MO file's format: MO Files. (line 6)
17934 * modify message attributes: msgattrib Invocation.
17936 * msgattrib program, usage: msgattrib Invocation.
17938 * msgcat program, usage: msgcat Invocation. (line 6)
17939 * msgcmp program, usage: msgcmp Invocation. (line 6)
17940 * msgcomm program, usage: msgcomm Invocation. (line 6)
17941 * msgconv program, usage: msgconv Invocation. (line 6)
17942 * msgctxt: PO Files. (line 202)
17943 * msgen program, usage: msgen Invocation. (line 6)
17944 * msgexec program, usage: msgexec Invocation. (line 6)
17945 * msgfilter filter and catalog encoding: msgfilter Invocation.
17947 * msgfilter program, usage: msgfilter Invocation.
17949 * msgfmt program, usage: msgfmt Invocation. (line 6)
17950 * msggrep program, usage: msggrep Invocation. (line 6)
17951 * msgid: PO Files. (line 56)
17952 * msgid_plural: PO Files. (line 222)
17953 * msginit program, usage: msginit Invocation. (line 6)
17954 * msgmerge program, usage: msgmerge Invocation. (line 6)
17955 * msgstr: PO Files. (line 56)
17956 * msgunfmt program, usage: msgunfmt Invocation. (line 6)
17957 * msguniq program, usage: msguniq Invocation. (line 6)
17958 * multi-line strings: Normalizing. (line 65)
17959 * N_, a convenience macro: Comparison. (line 41)
17960 * Native Language Support: Concepts. (line 51)
17961 * Natural Language Support: Concepts. (line 51)
17962 * newlines in PO files: PO Files. (line 302)
17963 * ngettext: Plural forms. (line 84)
17964 * ngettext program, usage: ngettext Invocation. (line 6)
17965 * NLS: Concepts. (line 51)
17966 * no-awk-format flag: PO Files. (line 150)
17967 * no-boost-format flag: PO Files. (line 199)
17968 * no-c-format flag: PO Files. (line 91)
17969 * no-c-format, and xgettext: c-format Flag. (line 48)
17970 * no-csharp-format flag: PO Files. (line 146)
17971 * no-elisp-format flag: PO Files. (line 126)
17972 * no-gcc-internal-format flag: PO Files. (line 178)
17973 * no-gfc-internal-format flag: PO Files. (line 182)
17974 * no-java-format flag: PO Files. (line 142)
17975 * no-kde-format flag: PO Files. (line 195)
17976 * no-librep-format flag: PO Files. (line 130)
17977 * no-lisp-format flag: PO Files. (line 122)
17978 * no-objc-format flag: PO Files. (line 110)
17979 * no-object-pascal-format flag: PO Files. (line 154)
17980 * no-perl-brace-format flag: PO Files. (line 170)
17981 * no-perl-format flag: PO Files. (line 166)
17982 * no-php-format flag: PO Files. (line 174)
17983 * no-python-format flag: PO Files. (line 118)
17984 * no-qt-format flag: PO Files. (line 187)
17985 * no-qt-plural-format flag: PO Files. (line 191)
17986 * no-scheme-format flag: PO Files. (line 134)
17987 * no-sh-format flag: PO Files. (line 114)
17988 * no-smalltalk-format flag: PO Files. (line 138)
17989 * no-tcl-format flag: PO Files. (line 162)
17990 * no-ycp-format flag: PO Files. (line 158)
17991 * nplurals, in a PO file header: Plural forms. (line 178)
17992 * number format: Aspects. (line 94)
17993 * objc-format flag: PO Files. (line 109)
17994 * Object Pascal: Pascal. (line 6)
17995 * object-pascal-format flag: PO Files. (line 153)
17996 * obsolete entries: Obsolete Entries. (line 6)
17997 * optimization of gettext functions: Optimized gettext. (line 6)
17998 * orthography: Manipulating. (line 28)
17999 * outdigits: c-format. (line 28)
18000 * output to stdout, xgettext: xgettext Invocation. (line 48)
18001 * overview of gettext: Overview. (line 6)
18002 * package and version declaration in configure.ac: configure.ac.
18004 * package build and installation options: Installers. (line 6)
18005 * package distributor's view of gettext: Installers. (line 6)
18006 * package installer's view of gettext: Installers. (line 6)
18007 * package maintainer's view of gettext: Maintainers. (line 6)
18008 * paragraphs: Preparing Strings. (line 101)
18009 * Pascal: Pascal. (line 6)
18010 * Perl: Perl. (line 6)
18011 * Perl default keywords: Default Keywords. (line 6)
18012 * Perl invalid string interpolation: Interpolation I. (line 6)
18013 * Perl long lines: Long Lines. (line 6)
18014 * Perl parentheses: Parentheses. (line 6)
18015 * Perl pitfalls: Perl Pitfalls. (line 6)
18016 * Perl quote-like expressions: Quote-like Expressions.
18018 * Perl special keywords for hash-lookups: Special Keywords. (line 6)
18019 * Perl valid string interpolation: Interpolation II. (line 6)
18020 * perl-brace-format flag: PO Files. (line 169)
18021 * perl-format flag: PO Files. (line 165)
18022 * pgettext: Contexts. (line 33)
18023 * pgettext_expr: Contexts. (line 112)
18024 * PHP: PHP. (line 6)
18025 * php-format flag: PO Files. (line 173)
18026 * Pike: Pike. (line 6)
18027 * plural form formulas: Plural forms. (line 198)
18028 * plural forms: Plural forms. (line 6)
18029 * plural forms, in MO files: MO Files. (line 74)
18030 * plural forms, in PO files: PO Files. (line 222)
18031 * plural forms, translating: Translating plural forms.
18033 * plural, in a PO file header: Plural forms. (line 178)
18034 * PO files' format: PO Files. (line 6)
18035 * PO mode (Emacs) commands: Main PO Commands. (line 6)
18036 * PO template file: Template. (line 6)
18037 * po_file_domains: libgettextpo. (line 41)
18038 * po_file_free: libgettextpo. (line 36)
18039 * po_file_read: libgettextpo. (line 30)
18040 * po_message_iterator: libgettextpo. (line 50)
18041 * po_message_iterator_free: libgettextpo. (line 57)
18042 * po_message_msgid: libgettextpo. (line 70)
18043 * po_message_msgid_plural: libgettextpo. (line 75)
18044 * po_message_msgstr: libgettextpo. (line 80)
18045 * po_message_msgstr_plural: libgettextpo. (line 86)
18046 * po_next_message: libgettextpo. (line 62)
18047 * portability problems with sed: msgfilter Invocation.
18049 * POTFILES.in file: po/POTFILES.in. (line 6)
18050 * preparing programs for translation: Sources. (line 6)
18051 * preparing shell scripts for translation: Preparing Shell Scripts.
18053 * problems with catgets interface: Problems with catgets.
18055 * programming languages: Language Implementors.
18057 * Python: Python. (line 6)
18058 * python-format flag: PO Files. (line 117)
18059 * Qt format strings: xgettext Invocation. (line 246)
18060 * Qt mode, and msgfmt program: msgfmt Invocation. (line 46)
18061 * qt-format flag: PO Files. (line 186)
18062 * qt-plural-format flag: PO Files. (line 190)
18063 * quotation marks <1>: po/Rules-*. (line 11)
18064 * quotation marks: Header Entry. (line 186)
18065 * quote characters, use in PO files: Header Entry. (line 186)
18066 * range: flag: PO Files. (line 253)
18067 * recode-sr-latin program: msgfilter Invocation.
18069 * related reading: References. (line 6)
18070 * release: Release Management. (line 6)
18071 * RST: RST. (line 6)
18072 * Scheme: Scheme. (line 6)
18073 * scheme-format flag: PO Files. (line 133)
18074 * scripting languages: Language Implementors.
18076 * search messages in a catalog: msggrep Invocation. (line 8)
18077 * selecting message language: Locale Environment Variables.
18079 * sentences: Preparing Strings. (line 44)
18080 * setting up gettext at build time: Installers. (line 6)
18081 * setting up gettext at run time: Locale Environment Variables.
18083 * several domains: Ambiguities. (line 6)
18084 * sex: Introduction. (line 15)
18085 * sh-format flag: PO Files. (line 113)
18086 * she, he, and they: Introduction. (line 15)
18087 * shell format string: envsubst Invocation. (line 8)
18088 * shell scripts: sh. (line 6)
18089 * Smalltalk: Smalltalk. (line 6)
18090 * smalltalk-format flag: PO Files. (line 137)
18091 * sorting msgcat output: msgcat Invocation. (line 151)
18092 * sorting msgmerge output: msgmerge Invocation. (line 187)
18093 * sorting msgunfmt output: msgunfmt Invocation. (line 153)
18094 * sorting output of xgettext: xgettext Invocation. (line 328)
18095 * specifying plural form in a PO file: Plural forms. (line 178)
18096 * standard output, and msgcat: msgcat Invocation. (line 47)
18097 * standard output, and msgmerge program: msgmerge Invocation. (line 56)
18098 * string concatenation: Preparing Strings. (line 117)
18099 * string normalization in entries: Normalizing. (line 6)
18100 * style: Preparing Strings. (line 24)
18101 * supported languages, xgettext: xgettext Invocation. (line 56)
18102 * Tcl: Tcl. (line 6)
18103 * Tcl mode, and msgfmt program: msgfmt Invocation. (line 43)
18104 * Tcl mode, and msgunfmt program: msgunfmt Invocation. (line 26)
18105 * tcl-format flag: PO Files. (line 161)
18106 * template PO file: Overview. (line 67)
18107 * testing .po files for equivalence: xgettext Invocation. (line 338)
18108 * Tk's scripting language: Tcl. (line 6)
18109 * translated entries: Translated Entries. (line 6)
18110 * translating menu entries: Contexts. (line 6)
18111 * translation aspects: Aspects. (line 6)
18112 * Translation Matrix: Installing Localizations.
18114 * Translation Project: Why. (line 17)
18115 * turning off NLS support: lib/gettext.h. (line 6)
18116 * tutorial of gettext usage: Overview. (line 6)
18117 * unify duplicate translations: msguniq Invocation. (line 8)
18118 * untranslated entries: Untranslated Entries.
18120 * update translations from a compendium: Using Compendia. (line 20)
18121 * upgrading to new versions of gettext: Prerequisites. (line 6)
18122 * version control for backup files, msgmerge: msgmerge Invocation.
18124 * wxWidgets library: wxWidgets. (line 6)
18125 * xargs, and output from msgexec: msgexec Invocation. (line 14)
18126 * xgettext program, usage: xgettext Invocation. (line 6)
18127 * xmodmap program, and typing quotation marks: Header Entry. (line 198)
18128 * YaST2 scripting language: YCP. (line 6)
18129 * YCP: YCP. (line 6)
18130 * ycp-format flag: PO Files. (line 157)
18136 Node: Introduction
\7f17401
18138 Ref: Why-Footnote-1
\7f22238
18139 Node: Concepts
\7f22394
18140 Node: Aspects
\7f25815
18141 Node: Files
\7f32349
18142 Node: Overview
\7f34258
18143 Node: Users
\7f44194
18144 Node: System Installation
\7f45105
18145 Node: Setting the GUI Locale
\7f46797
18146 Node: Setting the POSIX Locale
\7f48173
18147 Node: Locale Names
\7f49112
18148 Node: Locale Environment Variables
\7f51517
18149 Node: The LANGUAGE variable
\7f53730
18150 Node: Installing Localizations
\7f55630
18151 Node: PO Files
\7f56985
18152 Ref: PO Files-Footnote-1
\7f69122
18153 Node: Sources
\7f69249
18154 Node: Importing
\7f70475
18155 Node: Triggering
\7f71158
18156 Node: Preparing Strings
\7f74358
18157 Node: Mark Keywords
\7f83401
18158 Node: Marking
\7f87861
18159 Node: c-format Flag
\7f95591
18160 Node: Special cases
\7f99510
18161 Node: Bug Report Address
\7f102253
18162 Node: Names
\7f104218
18163 Node: Libraries
\7f108503
18164 Node: Template
\7f111540
18165 Node: xgettext Invocation
\7f112265
18166 Node: Creating
\7f127823
18167 Node: msginit Invocation
\7f128708
18168 Node: Header Entry
\7f131610
18169 Node: Updating
\7f140573
18170 Node: msgmerge Invocation
\7f140788
18171 Node: Editing
\7f146578
18172 Node: KBabel
\7f146936
18173 Node: Gtranslator
\7f147074
18174 Node: PO Mode
\7f147216
18175 Node: Installation
\7f148870
18176 Node: Main PO Commands
\7f150834
18177 Node: Entry Positioning
\7f155922
18178 Node: Normalizing
\7f161390
18179 Node: Translated Entries
\7f165884
18180 Node: Fuzzy Entries
\7f167242
18181 Node: Untranslated Entries
\7f170423
18182 Node: Obsolete Entries
\7f172355
18183 Node: Modifying Translations
\7f175580
18184 Node: Modifying Comments
\7f183549
18185 Node: Subedit
\7f187976
18186 Node: C Sources Context
\7f191872
18187 Node: Auxiliary
\7f196996
18188 Node: Compendium
\7f200212
18189 Node: Creating Compendia
\7f200827
18190 Node: Using Compendia
\7f203311
18191 Node: Manipulating
\7f204251
18192 Node: msgcat Invocation
\7f208079
18193 Node: msgconv Invocation
\7f212833
18194 Node: msggrep Invocation
\7f216288
18195 Node: msgfilter Invocation
\7f222446
18196 Node: msguniq Invocation
\7f228985
18197 Node: msgcomm Invocation
\7f233150
18198 Node: msgcmp Invocation
\7f237471
18199 Node: msgattrib Invocation
\7f239628
18200 Node: msgen Invocation
\7f244589
18201 Node: msgexec Invocation
\7f248441
18202 Node: Colorizing
\7f251020
18203 Node: The --color option
\7f252049
18204 Node: The TERM variable
\7f253681
18205 Node: The --style option
\7f255133
18206 Node: Style rules
\7f256441
18207 Node: Customizing less
\7f263183
18208 Node: libgettextpo
\7f264586
18209 Node: Binaries
\7f269702
18210 Node: msgfmt Invocation
\7f270046
18211 Node: msgunfmt Invocation
\7f277198
18212 Node: MO Files
\7f281636
18213 Node: Programmers
\7f290214
18214 Node: catgets
\7f291396
18215 Node: Interface to catgets
\7f292810
18216 Node: Problems with catgets
\7f294819
18217 Node: gettext
\7f295734
18218 Node: Interface to gettext
\7f297237
18219 Node: Ambiguities
\7f299567
18220 Node: Locating Catalogs
\7f302282
18221 Ref: Locating Catalogs-Footnote-1
\7f303512
18222 Ref: Locating Catalogs-Footnote-2
\7f303738
18223 Node: Charset conversion
\7f303887
18224 Node: Contexts
\7f306341
18225 Node: Plural forms
\7f311847
18226 Ref: Plural forms-Footnote-1
\7f327784
18227 Node: Optimized gettext
\7f327906
18228 Node: Comparison
\7f329245
18229 Node: Using libintl.a
\7f333515
18230 Node: gettext grok
\7f333958
18231 Node: Temp Programmers
\7f336599
18232 Node: Temp Implementations
\7f337127
18233 Node: Temp catgets
\7f338507
18234 Node: Temp WSI
\7f340208
18235 Node: Temp Notes
\7f342210
18236 Node: Translators
\7f342713
18237 Node: Trans Intro 0
\7f343248
18238 Node: Trans Intro 1
\7f345997
18239 Node: Discussions
\7f347961
18240 Node: Organization
\7f351619
18241 Node: Central Coordination
\7f353695
18242 Node: National Teams
\7f354838
18243 Node: Sub-Cultures
\7f357365
18244 Node: Organizational Ideas
\7f358302
18245 Node: Mailing Lists
\7f359323
18246 Node: Information Flow
\7f361146
18247 Node: Translating plural forms
\7f363400
18248 Node: Prioritizing messages
\7f366769
18249 Node: Maintainers
\7f371076
18250 Node: Flat and Non-Flat
\7f373032
18251 Node: Prerequisites
\7f374525
18252 Node: gettextize Invocation
\7f378682
18253 Node: Adjusting Files
\7f386091
18254 Node: po/POTFILES.in
\7f387880
18255 Node: po/LINGUAS
\7f389129
18256 Node: po/Makevars
\7f390821
18257 Node: po/Rules-*
\7f391763
18258 Node: configure.ac
\7f393234
18259 Node: config.guess
\7f396256
18260 Node: mkinstalldirs
\7f397611
18261 Node: aclocal
\7f398016
18262 Node: acconfig
\7f400030
18263 Node: config.h.in
\7f400530
18264 Node: Makefile
\7f401998
18265 Node: src/Makefile
\7f404595
18266 Node: lib/gettext.h
\7f409316
18267 Node: autoconf macros
\7f411564
18268 Node: AM_GNU_GETTEXT
\7f412406
18269 Node: AM_GNU_GETTEXT_VERSION
\7f416371
18270 Node: AM_GNU_GETTEXT_NEED
\7f416826
18271 Node: AM_GNU_GETTEXT_INTL_SUBDIR
\7f417719
18272 Node: AM_PO_SUBDIRS
\7f418374
18273 Node: AM_XGETTEXT_OPTION
\7f419169
18274 Node: AM_ICONV
\7f420039
18275 Node: CVS Issues
\7f422254
18276 Node: Distributed CVS
\7f422845
18277 Node: Files under CVS
\7f424773
18278 Node: autopoint Invocation
\7f428049
18279 Node: Release Management
\7f429893
18280 Node: Installers
\7f430406
18281 Node: Programming Languages
\7f431633
18282 Node: Language Implementors
\7f432459
18283 Node: Programmers for other Languages
\7f437287
18284 Node: Translators for other Languages
\7f437871
18285 Node: c-format
\7f439568
18286 Node: objc-format
\7f441287
18287 Node: sh-format
\7f441642
18288 Node: python-format
\7f442447
18289 Node: lisp-format
\7f442888
18290 Node: elisp-format
\7f443217
18291 Node: librep-format
\7f443710
18292 Node: scheme-format
\7f444113
18293 Node: smalltalk-format
\7f444392
18294 Node: java-format
\7f444895
18295 Node: csharp-format
\7f445346
18296 Node: awk-format
\7f445724
18297 Node: object-pascal-format
\7f446052
18298 Node: ycp-format
\7f446438
18299 Node: tcl-format
\7f446840
18300 Node: perl-format
\7f447138
18301 Node: php-format
\7f447886
18302 Node: gcc-internal-format
\7f448254
18303 Node: gfc-internal-format
\7f449309
18304 Node: qt-format
\7f450006
18305 Node: qt-plural-format
\7f450447
18306 Node: kde-format
\7f450802
18307 Node: boost-format
\7f451215
18308 Node: Maintainers for other Languages
\7f451763
18309 Node: List of Programming Languages
\7f453001
18312 Node: Preparing Shell Scripts
\7f456858
18313 Node: gettext.sh
\7f460250
18314 Node: gettext Invocation
\7f460800
18315 Node: ngettext Invocation
\7f462724
18316 Node: envsubst Invocation
\7f464485
18317 Node: eval_gettext Invocation
\7f465906
18318 Node: eval_ngettext Invocation
\7f466367
18319 Node: bash
\7f466881
18320 Node: Python
\7f468860
18321 Node: Common Lisp
\7f471183
18322 Node: clisp C
\7f471983
18323 Node: Emacs Lisp
\7f472698
18324 Node: librep
\7f473424
18325 Node: Scheme
\7f474159
18326 Node: Smalltalk
\7f474943
18327 Node: Java
\7f475977
18329 Node: gawk
\7f490999
18330 Node: Pascal
\7f491911
18331 Node: wxWidgets
\7f493219
18334 Node: Perl
\7f496275
18335 Node: General Problems
\7f499283
18336 Node: Default Keywords
\7f504771
18337 Node: Special Keywords
\7f505726
18338 Node: Quote-like Expressions
\7f507242
18339 Node: Interpolation I
\7f509520
18340 Node: Interpolation II
\7f513313
18341 Node: Parentheses
\7f515681
18342 Node: Long Lines
\7f517202
18343 Node: Perl Pitfalls
\7f519050
18345 Node: Pike
\7f524226
18346 Node: GCC-source
\7f524887
18347 Node: List of Data Formats
\7f525634
18350 Node: Glade
\7f526587
18351 Node: Conclusion
\7f526947
18352 Node: History
\7f527453
18353 Node: References
\7f531723
18354 Node: Language Codes
\7f533370
18355 Node: Usual Language Codes
\7f533885
18356 Node: Rare Language Codes
\7f538247
18357 Node: Country Codes
\7f539916
18358 Node: Licenses
\7f545805
18359 Node: GNU GPL
\7f547650
18360 Node: GNU LGPL
\7f566833
18361 Node: GNU FDL
\7f594972
18362 Node: Program Index
\7f617361
18363 Node: Option Index
\7f619247
18364 Node: Variable Index
\7f668348
18365 Node: PO Mode Index
\7f671605
18366 Node: Autoconf Macro Index
\7f685441
18367 Node: Index
\7f686248