1 This is gettext.info, produced by makeinfo version 5.2 from
4 Copyright (C) 1995-1998, 2001-2015 Free Software Foundation, Inc.
6 This manual is free documentation. It is dually licensed under the
7 GNU FDL and the GNU GPL. This means that you can redistribute this
8 manual under either of these two licenses, at your choice.
10 This manual is covered by the GNU FDL. Permission is granted to copy,
11 distribute and/or modify this document under the terms of the GNU Free
12 Documentation License (FDL), either version 1.2 of the License, or (at
13 your option) any later version published by the Free Software Foundation
14 (FSF); with no Invariant Sections, with no Front-Cover Text, and with no
15 Back-Cover Texts. A copy of the license is included in *note GNU FDL::.
17 This manual is covered by the GNU GPL. You can redistribute it and/or
18 modify it under the terms of the GNU General Public License (GPL),
19 either version 2 of the License, or (at your option) any later version
20 published by the Free Software Foundation (FSF). A copy of the license
21 is included in *note GNU GPL::.
22 INFO-DIR-SECTION GNU Gettext Utilities
24 * gettext: (gettext). GNU gettext utilities.
25 * autopoint: (gettext)autopoint Invocation. Copy gettext infrastructure.
26 * envsubst: (gettext)envsubst Invocation. Expand environment variables.
27 * gettextize: (gettext)gettextize Invocation. Prepare a package for gettext.
28 * msgattrib: (gettext)msgattrib Invocation. Select part of a PO file.
29 * msgcat: (gettext)msgcat Invocation. Combine several PO files.
30 * msgcmp: (gettext)msgcmp Invocation. Compare a PO file and template.
31 * msgcomm: (gettext)msgcomm Invocation. Match two PO files.
32 * msgconv: (gettext)msgconv Invocation. Convert PO file to encoding.
33 * msgen: (gettext)msgen Invocation. Create an English PO file.
34 * msgexec: (gettext)msgexec Invocation. Process a PO file.
35 * msgfilter: (gettext)msgfilter Invocation. Pipe a PO file through a filter.
36 * msgfmt: (gettext)msgfmt Invocation. Make MO files out of PO files.
37 * msggrep: (gettext)msggrep Invocation. Select part of a PO file.
38 * msginit: (gettext)msginit Invocation. Create a fresh PO file.
39 * msgmerge: (gettext)msgmerge Invocation. Update a PO file from template.
40 * msgunfmt: (gettext)msgunfmt Invocation. Uncompile MO file into PO file.
41 * msguniq: (gettext)msguniq Invocation. Unify duplicates for PO file.
42 * ngettext: (gettext)ngettext Invocation. Translate a message with plural.
43 * xgettext: (gettext)xgettext Invocation. Extract strings into a PO file.
44 * ISO639: (gettext)Language Codes. ISO 639 language codes.
45 * ISO3166: (gettext)Country Codes. ISO 3166 country codes.
48 This file provides documentation for GNU ‘gettext’ utilities. It
49 also serves as a reference for the free Translation Project.
52 File: gettext.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir)
54 GNU ‘gettext’ utilities
55 ***********************
57 This manual documents the GNU gettext tools and the GNU libintl
58 library, version 0.19.7.
62 * Introduction:: Introduction
63 * Users:: The User’s View
64 * PO Files:: The Format of PO Files
65 * Sources:: Preparing Program Sources
66 * Template:: Making the PO Template File
67 * Creating:: Creating a New PO File
68 * Updating:: Updating Existing PO Files
69 * Editing:: Editing PO Files
70 * Manipulating:: Manipulating PO Files
71 * Binaries:: Producing Binary MO Files
72 * Programmers:: The Programmer’s View
73 * Translators:: The Translator’s View
74 * Maintainers:: The Maintainer’s View
75 * Installers:: The Installer’s and Distributor’s View
76 * Programming Languages:: Other Programming Languages
77 * Conclusion:: Concluding Remarks
79 * Language Codes:: ISO 639 language codes
80 * Country Codes:: ISO 3166 country codes
83 * Program Index:: Index of Programs
84 * Option Index:: Index of Command-Line Options
85 * Variable Index:: Index of Environment Variables
86 * PO Mode Index:: Index of Emacs PO Mode Commands
87 * Autoconf Macro Index:: Index of Autoconf Macros
88 * Index:: General Index
90 — The Detailed Node Listing —
94 * Why:: The Purpose of GNU ‘gettext’
95 * Concepts:: I18n, L10n, and Such
96 * Aspects:: Aspects in Native Language Support
97 * Files:: Files Conveying Translations
98 * Overview:: Overview of GNU ‘gettext’
102 * System Installation:: Questions During Operating System Installation
103 * Setting the GUI Locale:: How to Specify the Locale Used by GUI Programs
104 * Setting the POSIX Locale:: How to Specify the Locale According to POSIX
105 * Installing Localizations:: How to Install Additional Translations
107 Setting the Locale through Environment Variables
109 * Locale Names:: How a Locale Specification Looks Like
110 * Locale Environment Variables:: Which Environment Variable Specfies What
111 * The LANGUAGE variable:: How to Specify a Priority List of Languages
113 Preparing Program Sources
115 * Importing:: Importing the ‘gettext’ declaration
116 * Triggering:: Triggering ‘gettext’ Operations
117 * Preparing Strings:: Preparing Translatable Strings
118 * Mark Keywords:: How Marks Appear in Sources
119 * Marking:: Marking Translatable Strings
120 * c-format Flag:: Telling something about the following string
121 * Special cases:: Special Cases of Translatable Strings
122 * Bug Report Address:: Letting Users Report Translation Bugs
123 * Names:: Marking Proper Names for Translation
124 * Libraries:: Preparing Library Sources
126 Making the PO Template File
128 * xgettext Invocation:: Invoking the ‘xgettext’ Program
130 Creating a New PO File
132 * msginit Invocation:: Invoking the ‘msginit’ Program
133 * Header Entry:: Filling in the Header Entry
135 Updating Existing PO Files
137 * msgmerge Invocation:: Invoking the ‘msgmerge’ Program
141 * KBabel:: KDE’s PO File Editor
142 * Gtranslator:: GNOME’s PO File Editor
143 * PO Mode:: Emacs’s PO File Editor
144 * Compendium:: Using Translation Compendia
146 Emacs’s PO File Editor
148 * Installation:: Completing GNU ‘gettext’ Installation
149 * Main PO Commands:: Main Commands
150 * Entry Positioning:: Entry Positioning
151 * Normalizing:: Normalizing Strings in Entries
152 * Translated Entries:: Translated Entries
153 * Fuzzy Entries:: Fuzzy Entries
154 * Untranslated Entries:: Untranslated Entries
155 * Obsolete Entries:: Obsolete Entries
156 * Modifying Translations:: Modifying Translations
157 * Modifying Comments:: Modifying Comments
158 * Subedit:: Mode for Editing Translations
159 * C Sources Context:: C Sources Context
160 * Auxiliary:: Consulting Auxiliary PO Files
162 Using Translation Compendia
164 * Creating Compendia:: Merging translations for later use
165 * Using Compendia:: Using older translations if they fit
167 Manipulating PO Files
169 * msgcat Invocation:: Invoking the ‘msgcat’ Program
170 * msgconv Invocation:: Invoking the ‘msgconv’ Program
171 * msggrep Invocation:: Invoking the ‘msggrep’ Program
172 * msgfilter Invocation:: Invoking the ‘msgfilter’ Program
173 * msguniq Invocation:: Invoking the ‘msguniq’ Program
174 * msgcomm Invocation:: Invoking the ‘msgcomm’ Program
175 * msgcmp Invocation:: Invoking the ‘msgcmp’ Program
176 * msgattrib Invocation:: Invoking the ‘msgattrib’ Program
177 * msgen Invocation:: Invoking the ‘msgen’ Program
178 * msgexec Invocation:: Invoking the ‘msgexec’ Program
179 * Colorizing:: Highlighting parts of PO files
180 * libgettextpo:: Writing your own programs that process PO files
182 Highlighting parts of PO files
184 * The --color option:: Triggering colorized output
185 * The TERM variable:: The environment variable ‘TERM’
186 * The --style option:: The ‘--style’ option
187 * Style rules:: Style rules for PO files
188 * Customizing less:: Customizing ‘less’ for viewing PO files
190 Producing Binary MO Files
192 * msgfmt Invocation:: Invoking the ‘msgfmt’ Program
193 * msgunfmt Invocation:: Invoking the ‘msgunfmt’ Program
194 * MO Files:: The Format of GNU MO Files
196 The Programmer’s View
198 * catgets:: About ‘catgets’
199 * gettext:: About ‘gettext’
200 * Comparison:: Comparing the two interfaces
201 * Using libintl.a:: Using libintl.a in own programs
202 * gettext grok:: Being a ‘gettext’ grok
203 * Temp Programmers:: Temporary Notes for the Programmers Chapter
207 * Interface to catgets:: The interface
208 * Problems with catgets:: Problems with the ‘catgets’ interface?!
212 * Interface to gettext:: The interface
213 * Ambiguities:: Solving ambiguities
214 * Locating Catalogs:: Locating message catalog files
215 * Charset conversion:: How to request conversion to Unicode
216 * Contexts:: Solving ambiguities in GUI programs
217 * Plural forms:: Additional functions for handling plurals
218 * Optimized gettext:: Optimization of the *gettext functions
220 Temporary Notes for the Programmers Chapter
222 * Temp Implementations:: Temporary - Two Possible Implementations
223 * Temp catgets:: Temporary - About ‘catgets’
224 * Temp WSI:: Temporary - Why a single implementation
225 * Temp Notes:: Temporary - Notes
227 The Translator’s View
229 * Trans Intro 0:: Introduction 0
230 * Trans Intro 1:: Introduction 1
231 * Discussions:: Discussions
232 * Organization:: Organization
233 * Information Flow:: Information Flow
234 * Translating plural forms:: How to fill in ‘msgstr[0]’, ‘msgstr[1]’
235 * Prioritizing messages:: How to find which messages to translate first
239 * Central Coordination:: Central Coordination
240 * National Teams:: National Teams
241 * Mailing Lists:: Mailing Lists
245 * Sub-Cultures:: Sub-Cultures
246 * Organizational Ideas:: Organizational Ideas
248 The Maintainer’s View
250 * Flat and Non-Flat:: Flat or Non-Flat Directory Structures
251 * Prerequisites:: Prerequisite Works
252 * gettextize Invocation:: Invoking the ‘gettextize’ Program
253 * Adjusting Files:: Files You Must Create or Alter
254 * autoconf macros:: Autoconf macros for use in ‘configure.ac’
255 * Version Control Issues::
256 * Release Management:: Creating a Distribution Tarball
258 Files You Must Create or Alter
260 * po/POTFILES.in:: ‘POTFILES.in’ in ‘po/’
261 * po/LINGUAS:: ‘LINGUAS’ in ‘po/’
262 * po/Makevars:: ‘Makevars’ in ‘po/’
263 * po/Rules-*:: Extending ‘Makefile’ in ‘po/’
264 * configure.ac:: ‘configure.ac’ at top level
265 * config.guess:: ‘config.guess’, ‘config.sub’ at top level
266 * mkinstalldirs:: ‘mkinstalldirs’ at top level
267 * aclocal:: ‘aclocal.m4’ at top level
268 * acconfig:: ‘acconfig.h’ at top level
269 * config.h.in:: ‘config.h.in’ at top level
270 * Makefile:: ‘Makefile.in’ at top level
271 * src/Makefile:: ‘Makefile.in’ in ‘src/’
272 * lib/gettext.h:: ‘gettext.h’ in ‘lib/’
274 Autoconf macros for use in ‘configure.ac’
276 * AM_GNU_GETTEXT:: AM_GNU_GETTEXT in ‘gettext.m4’
277 * AM_GNU_GETTEXT_VERSION:: AM_GNU_GETTEXT_VERSION in ‘gettext.m4’
278 * AM_GNU_GETTEXT_NEED:: AM_GNU_GETTEXT_NEED in ‘gettext.m4’
279 * AM_GNU_GETTEXT_INTL_SUBDIR:: AM_GNU_GETTEXT_INTL_SUBDIR in ‘intldir.m4’
280 * AM_PO_SUBDIRS:: AM_PO_SUBDIRS in ‘po.m4’
281 * AM_XGETTEXT_OPTION:: AM_XGETTEXT_OPTION in ‘po.m4’
282 * AM_ICONV:: AM_ICONV in ‘iconv.m4’
284 Integrating with Version Control Systems
286 * Distributed Development:: Avoiding version mismatch in distributed development
287 * Files under Version Control:: Files to put under version control
288 * Translations under Version Control:: Put PO Files under 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
325 * lua-format:: Lua Format Strings
326 * javascript-format:: JavaScript Format Strings
328 Individual Programming Languages
330 * C:: C, C++, Objective C
331 * sh:: sh - Shell Script
332 * bash:: bash - Bourne-Again Shell Script
334 * Common Lisp:: GNU clisp - Common Lisp
335 * clisp C:: GNU clisp C sources
336 * Emacs Lisp:: Emacs Lisp
338 * Scheme:: GNU guile - Scheme
339 * Smalltalk:: GNU Smalltalk
343 * Pascal:: Pascal - Free Pascal Compiler
344 * wxWidgets:: wxWidgets library
345 * YCP:: YCP - YaST2 scripting language
346 * Tcl:: Tcl - Tk’s scripting language
348 * PHP:: PHP Hypertext Preprocessor
350 * GCC-source:: GNU Compiler Collection sources
352 * JavaScript:: JavaScript
357 * Preparing Shell Scripts:: Preparing Shell Scripts for Internationalization
358 * gettext.sh:: Contents of ‘gettext.sh’
359 * gettext Invocation:: Invoking the ‘gettext’ program
360 * ngettext Invocation:: Invoking the ‘ngettext’ program
361 * envsubst Invocation:: Invoking the ‘envsubst’ program
362 * eval_gettext Invocation:: Invoking the ‘eval_gettext’ function
363 * eval_ngettext Invocation:: Invoking the ‘eval_ngettext’ function
367 * General Problems:: General Problems Parsing Perl Code
368 * Default Keywords:: Which Keywords Will xgettext Look For?
369 * Special Keywords:: How to Extract Hash Keys
370 * Quote-like Expressions:: What are Strings And Quote-like Expressions?
371 * Interpolation I:: Invalid String Interpolation
372 * Interpolation II:: Valid String Interpolation
373 * Parentheses:: When To Use Parentheses
374 * Long Lines:: How To Grok with Long Lines
375 * Perl Pitfalls:: Bugs, Pitfalls, and Things That Do Not Work
377 Internationalizable Data
379 * POT:: POT - Portable Object Template
380 * RST:: Resource String Table
381 * Glade:: Glade - GNOME user interface description
382 * GSettings:: GSettings - GNOME user configuration schema
383 * AppData:: AppData - freedesktop.org application description
384 * Preparing ITS Rules:: Preparing Rules for XML Internationalization
388 * History:: History of GNU ‘gettext’
389 * References:: Related Readings
393 * Usual Language Codes:: Two-letter ISO 639 language codes
394 * Rare Language Codes:: Three-letter ISO 639 language codes
398 * GNU GPL:: GNU General Public License
399 * GNU LGPL:: GNU Lesser General Public License
400 * GNU FDL:: GNU Free Documentation License
404 File: gettext.info, Node: Introduction, Next: Users, Prev: Top, Up: Top
409 This chapter explains the goals sought in the creation of GNU
410 ‘gettext’ and the free Translation Project. Then, it explains a few
411 broad concepts around Native Language Support, and positions message
412 translation with regard to other aspects of national and cultural
413 variance, as they apply to programs. It also surveys those files used
414 to convey the translations. It explains how the various tools interact
415 in the initial generation of these files, and later, how the maintenance
416 cycle should usually operate.
418 In this manual, we use _he_ when speaking of the programmer or
419 maintainer, _she_ when speaking of the translator, and _they_ when
420 speaking of the installers or end users of the translated program. This
421 is only a convenience for clarifying the documentation. It is
422 _absolutely_ not meant to imply that some roles are more appropriate to
423 males or females. Besides, as you might guess, GNU ‘gettext’ is meant
424 to be useful for people using computers, whatever their sex, race,
425 religion or nationality!
427 Please send suggestions and corrections to:
430 bug-gnu-gettext@gnu.org
432 Please include the manual’s edition number and update date in your
437 * Why:: The Purpose of GNU ‘gettext’
438 * Concepts:: I18n, L10n, and Such
439 * Aspects:: Aspects in Native Language Support
440 * Files:: Files Conveying Translations
441 * Overview:: Overview of GNU ‘gettext’
444 File: gettext.info, Node: Why, Next: Concepts, Prev: Introduction, Up: Introduction
446 1.1 The Purpose of GNU ‘gettext’
447 ================================
449 Usually, programs are written and documented in English, and use
450 English at execution time to interact with users. This is true not only
451 of GNU software, but also of a great deal of proprietary and free
452 software. Using a common language is quite handy for communication
453 between developers, maintainers and users from all countries. On the
454 other hand, most people are less comfortable with English than with
455 their own native language, and would prefer to use their mother tongue
456 for day to day’s work, as far as possible. Many would simply _love_ to
457 see their computer screen showing a lot less of English, and far more of
460 However, to many people, this dream might appear so far fetched that
461 they may believe it is not even worth spending time thinking about it.
462 They have no confidence at all that the dream might ever become true.
463 Yet some have not lost hope, and have organized themselves. The
464 Translation Project is a formalization of this hope into a workable
465 structure, which has a good chance to get all of us nearer the
466 achievement of a truly multi-lingual set of programs.
468 GNU ‘gettext’ is an important step for the Translation Project, as it
469 is an asset on which we may build many other steps. This package offers
470 to programmers, translators and even users, a well integrated set of
471 tools and documentation. Specifically, the GNU ‘gettext’ utilities are
472 a set of tools that provides a framework within which other free
473 packages may produce multi-lingual messages. These tools include
475 • A set of conventions about how programs should be written to
476 support message catalogs.
478 • A directory and file naming organization for the message catalogs
481 • A runtime library supporting the retrieval of translated messages.
483 • A few stand-alone programs to massage in various ways the sets of
484 translatable strings, or already translated strings.
486 • A library supporting the parsing and creation of files containing
489 • A special mode for Emacs(1) which helps preparing these sets and
490 bringing them up to date.
492 GNU ‘gettext’ is designed to minimize the impact of
493 internationalization on program sources, keeping this impact as small
494 and hardly noticeable as possible. Internationalization has better
495 chances of succeeding if it is very light weighted, or at least, appear
496 to be so, when looking at program sources.
498 The Translation Project also uses the GNU ‘gettext’ distribution as a
499 vehicle for documenting its structure and methods. This goes beyond the
500 strict technicalities of documenting the GNU ‘gettext’ proper. By so
501 doing, translators will find in a single place, as far as possible, all
502 they need to know for properly doing their translating work. Also, this
503 supplemental documentation might also help programmers, and even curious
504 users, in understanding how GNU ‘gettext’ is related to the remainder of
505 the Translation Project, and consequently, have a glimpse at the _big
508 ---------- Footnotes ----------
510 (1) In this manual, all mentions of Emacs refers to either GNU Emacs
511 or to XEmacs, which people sometimes call FSF Emacs and Lucid Emacs,
515 File: gettext.info, Node: Concepts, Next: Aspects, Prev: Why, Up: Introduction
517 1.2 I18n, L10n, and Such
518 ========================
520 Two long words appear all the time when we discuss support of native
521 language in programs, and these words have a precise meaning, worth
522 being explained here, once and for all in this document. The words are
523 _internationalization_ and _localization_. Many people, tired of
524 writing these long words over and over again, took the habit of writing
525 "i18n" and "l10n" instead, quoting the first and last letter of each
526 word, and replacing the run of intermediate letters by a number merely
527 telling how many such letters there are. But in this manual, in the
528 sake of clarity, we will patiently write the names in full, each time…
530 By "internationalization", one refers to the operation by which a
531 program, or a set of programs turned into a package, is made aware of
532 and able to support multiple languages. This is a generalization
533 process, by which the programs are untied from calling only English
534 strings or other English specific habits, and connected to generic ways
535 of doing the same, instead. Program developers may use various
536 techniques to internationalize their programs. Some of these have been
537 standardized. GNU ‘gettext’ offers one of these standards. *Note
540 By "localization", one means the operation by which, in a set of
541 programs already internationalized, one gives the program all needed
542 information so that it can adapt itself to handle its input and output
543 in a fashion which is correct for some native language and cultural
544 habits. This is a particularisation process, by which generic methods
545 already implemented in an internationalized program are used in specific
546 ways. The programming environment puts several functions to the
547 programmers disposal which allow this runtime configuration. The formal
548 description of specific set of cultural habits for some country,
549 together with all associated translations targeted to the same native
550 language, is called the "locale" for this language or country. Users
551 achieve localization of programs by setting proper values to special
552 environment variables, prior to executing those programs, identifying
553 which locale should be used.
555 In fact, locale message support is only one component of the cultural
556 data that makes up a particular locale. There are a whole host of
557 routines and functions provided to aid programmers in developing
558 internationalized software and which allow them to access the data
559 stored in a particular locale. When someone presently refers to a
560 particular locale, they are obviously referring to the data stored
561 within that particular locale. Similarly, if a programmer is referring
562 to “accessing the locale routines”, they are referring to the complete
563 suite of routines that access all of the locale’s information.
565 One uses the expression "Native Language Support", or merely NLS, for
566 speaking of the overall activity or feature encompassing both
567 internationalization and localization, allowing for multi-lingual
568 interactions in a program. In a nutshell, one could say that
569 internationalization is the operation by which further localizations are
572 Also, very roughly said, when it comes to multi-lingual messages,
573 internationalization is usually taken care of by programmers, and
574 localization is usually taken care of by translators.
577 File: gettext.info, Node: Aspects, Next: Files, Prev: Concepts, Up: Introduction
579 1.3 Aspects in Native Language Support
580 ======================================
582 For a totally multi-lingual distribution, there are many things to
583 translate beyond output messages.
585 • As of today, GNU ‘gettext’ offers a complete toolset for
586 translating messages output by C programs. Perl scripts and shell
587 scripts will also need to be translated. Even if there are today
588 some hooks by which this can be done, these hooks are not
589 integrated as well as they should be.
591 • Some programs, like ‘autoconf’ or ‘bison’, are able to produce
592 other programs (or scripts). Even if the generating programs
593 themselves are internationalized, the generated programs they
594 produce may need internationalization on their own, and this
595 indirect internationalization could be automated right from the
596 generating program. In fact, quite usually, generating and
597 generated programs could be internationalized independently, as the
598 effort needed is fairly orthogonal.
600 • A few programs include textual tables which might need translation
601 themselves, independently of the strings contained in the program
602 itself. For example, RFC 1345 gives an English description for
603 each character which the ‘recode’ program is able to reconstruct at
604 execution. Since these descriptions are extracted from the RFC by
605 mechanical means, translating them properly would require a prior
606 translation of the RFC itself.
608 • Almost all programs accept options, which are often worded out so
609 to be descriptive for the English readers; one might want to
610 consider offering translated versions for program options as well.
612 • Many programs read, interpret, compile, or are somewhat driven by
613 input files which are texts containing keywords, identifiers, or
614 replies which are inherently translatable. For example, one may
615 want ‘gcc’ to allow diacriticized characters in identifiers or use
616 translated keywords; ‘rm -i’ might accept something else than ‘y’
617 or ‘n’ for replies, etc. Even if the program will eventually make
618 most of its output in the foreign languages, one has to decide
619 whether the input syntax, option values, etc., are to be localized
622 • The manual accompanying a package, as well as all documentation
623 files in the distribution, could surely be translated, too.
624 Translating a manual, with the intent of later keeping up with
625 updates, is a major undertaking in itself, generally.
627 As we already stressed, translation is only one aspect of locales.
628 Other internationalization aspects are system services and are handled
629 in GNU ‘libc’. There are many attributes that are needed to define a
630 country’s cultural conventions. These attributes include beside the
631 country’s native language, the formatting of the date and time, the
632 representation of numbers, the symbols for currency, etc. These local
633 "rules" are termed the country’s locale. The locale represents the
634 knowledge needed to support the country’s native attributes.
636 There are a few major areas which may vary between countries and
637 hence, define what a locale must describe. The following list helps
638 putting multi-lingual messages into the proper context of other tasks
639 related to locales. See the GNU ‘libc’ manual for details.
641 _Characters and Codesets_
643 The codeset most commonly used through out the USA and most English
644 speaking parts of the world is the ASCII codeset. However, there
645 are many characters needed by various locales that are not found
646 within this codeset. The 8-bit ISO 8859-1 code set has most of the
647 special characters needed to handle the major European languages.
648 However, in many cases, choosing ISO 8859-1 is nevertheless not
649 adequate: it doesn’t even handle the major European currency.
650 Hence each locale will need to specify which codeset they need to
651 use and will need to have the appropriate character handling
652 routines to cope with the codeset.
656 The symbols used vary from country to country as does the position
657 used by the symbol. Software needs to be able to transparently
658 display currency figures in the native mode for each locale.
662 The format of date varies between locales. For example, Christmas
663 day in 1994 is written as 12/25/94 in the USA and as 25/12/94 in
664 Australia. Other countries might use ISO 8601 dates, etc.
666 Time of the day may be noted as HH:MM, HH.MM, or otherwise. Some
667 locales require time to be specified in 24-hour mode rather than as
668 AM or PM. Further, the nature and yearly extent of the Daylight
669 Saving correction vary widely between countries.
673 Numbers can be represented differently in different locales. For
674 example, the following numbers are all written correctly for their
682 Some programs could go further and use different unit systems, like
683 English units or Metric units, or even take into account variants
684 about how numbers are spelled in full.
688 The most obvious area is the language support within a locale.
689 This is where GNU ‘gettext’ provides the means for developers and
690 users to easily change the language that the software uses to
691 communicate to the user.
693 These areas of cultural conventions are called _locale categories_.
694 It is an unfortunate term; _locale aspects_ or _locale feature
695 categories_ would be a better term, because each “locale category”
696 describes an area or task that requires localization. The concrete data
697 that describes the cultural conventions for such an area and for a
698 particular culture is also called a _locale category_. In this sense, a
699 locale is composed of several locale categories: the locale category
700 describing the codeset, the locale category describing the formatting of
701 numbers, the locale category containing the translated messages, and so
704 Components of locale outside of message handling are standardized in
705 the ISO C standard and the POSIX:2001 standard (also known as the SUSV3
706 specification). GNU ‘libc’ fully implements this, and most other modern
707 systems provide a more or less reasonable support for at least some of
708 the missing components.
711 File: gettext.info, Node: Files, Next: Overview, Prev: Aspects, Up: Introduction
713 1.4 Files Conveying Translations
714 ================================
716 The letters PO in ‘.po’ files means Portable Object, to distinguish
717 it from ‘.mo’ files, where MO stands for Machine Object. This paradigm,
718 as well as the PO file format, is inspired by the NLS standard developed
719 by Uniforum, and first implemented by Sun in their Solaris system.
721 PO files are meant to be read and edited by humans, and associate
722 each original, translatable string of a given package with its
723 translation in a particular target language. A single PO file is
724 dedicated to a single target language. If a package supports many
725 languages, there is one such PO file per language supported, and each
726 package has its own set of PO files. These PO files are best created by
727 the ‘xgettext’ program, and later updated or refreshed through the
728 ‘msgmerge’ program. Program ‘xgettext’ extracts all marked messages
729 from a set of C files and initializes a PO file with empty translations.
730 Program ‘msgmerge’ takes care of adjusting PO files between releases of
731 the corresponding sources, commenting obsolete entries, initializing new
732 ones, and updating all source line references. Files ending with ‘.pot’
733 are kind of base translation files found in distributions, in PO file
736 MO files are meant to be read by programs, and are binary in nature.
737 A few systems already offer tools for creating and handling MO files as
738 part of the Native Language Support coming with the system, but the
739 format of these MO files is often different from system to system, and
740 non-portable. The tools already provided with these systems don’t
741 support all the features of GNU ‘gettext’. Therefore GNU ‘gettext’ uses
742 its own format for MO files. Files ending with ‘.gmo’ are really MO
743 files, when it is known that these files use the GNU format.
746 File: gettext.info, Node: Overview, Prev: Files, Up: Introduction
748 1.5 Overview of GNU ‘gettext’
749 =============================
751 The following diagram summarizes the relation between the files
752 handled by GNU ‘gettext’ and the tools acting on these files. It is
753 followed by somewhat detailed explanations, which you should read while
754 keeping an eye on the diagram. Having a clear understanding of these
755 interrelations will surely help programmers, translators and
758 Original C Sources ---> Preparation ---> Marked C Sources ---.
760 .---------<--- GNU gettext Library |
762 | `---------<--------------------+---------------'
764 | .-----<--- PACKAGE.pot <--- xgettext <---' .---<--- PO Compendium
767 | `---. +---> PO editor ---.
768 | +----> msgmerge ------> LANG.po ---->--------' |
771 | `-------------<---------------. |
772 | +--- New LANG.po <--------------------'
773 | .--- LANG.gmo <--- msgfmt <---'
775 | `---> install ---> /.../LANG/PACKAGE.mo ---.
776 | +---> "Hello world!"
777 `-------> install ---> /.../bin/PROGRAM -------'
779 As a programmer, the first step to bringing GNU ‘gettext’ into your
780 package is identifying, right in the C sources, those strings which are
781 meant to be translatable, and those which are untranslatable. This
782 tedious job can be done a little more comfortably using emacs PO mode,
783 but you can use any means familiar to you for modifying your C sources.
784 Beside this some other simple, standard changes are needed to properly
785 initialize the translation library. *Note Sources::, for more
786 information about all this.
788 For newly written software the strings of course can and should be
789 marked while writing it. The ‘gettext’ approach makes this very easy.
790 Simply put the following lines at the beginning of each file or in a
793 #define _(String) (String)
794 #define N_(String) String
795 #define textdomain(Domain)
796 #define bindtextdomain(Package, Directory)
798 Doing this allows you to prepare the sources for internationalization.
799 Later when you feel ready for the step to use the ‘gettext’ library
800 simply replace these definitions by the following:
803 #define _(String) gettext (String)
804 #define gettext_noop(String) String
805 #define N_(String) gettext_noop (String)
807 and link against ‘libintl.a’ or ‘libintl.so’. Note that on GNU systems,
808 you don’t need to link with ‘libintl’ because the ‘gettext’ library
809 functions are already contained in GNU libc. That is all you have to
812 Once the C sources have been modified, the ‘xgettext’ program is used
813 to find and extract all translatable strings, and create a PO template
814 file out of all these. This ‘PACKAGE.pot’ file contains all original
815 program strings. It has sets of pointers to exactly where in C sources
816 each string is used. All translations are set to empty. The letter ‘t’
817 in ‘.pot’ marks this as a Template PO file, not yet oriented towards any
818 particular language. *Note xgettext Invocation::, for more details
819 about how one calls the ‘xgettext’ program. If you are _really_ lazy,
820 you might be interested at working a lot more right away, and preparing
821 the whole distribution setup (*note Maintainers::). By doing so, you
822 spare yourself typing the ‘xgettext’ command, as ‘make’ should now
823 generate the proper things automatically for you!
825 The first time through, there is no ‘LANG.po’ yet, so the ‘msgmerge’
826 step may be skipped and replaced by a mere copy of ‘PACKAGE.pot’ to
827 ‘LANG.po’, where LANG represents the target language. See *note
828 Creating:: for details.
830 Then comes the initial translation of messages. Translation in
831 itself is a whole matter, still exclusively meant for humans, and whose
832 complexity far overwhelms the level of this manual. Nevertheless, a few
833 hints are given in some other chapter of this manual (*note
834 Translators::). You will also find there indications about how to
835 contact translating teams, or becoming part of them, for sharing your
836 translating concerns with others who target the same native language.
838 While adding the translated messages into the ‘LANG.po’ PO file, if
839 you are not using one of the dedicated PO file editors (*note
840 Editing::), you are on your own for ensuring that your efforts fully
841 respect the PO file format, and quoting conventions (*note PO Files::).
842 This is surely not an impossible task, as this is the way many people
843 have handled PO files around 1995. On the other hand, by using a PO
844 file editor, most details of PO file format are taken care of for you,
845 but you have to acquire some familiarity with PO file editor itself.
847 If some common translations have already been saved into a compendium
848 PO file, translators may use PO mode for initializing untranslated
849 entries from the compendium, and also save selected translations into
850 the compendium, updating it (*note Compendium::). Compendium files are
851 meant to be exchanged between members of a given translation team.
853 Programs, or packages of programs, are dynamic in nature: users write
854 bug reports and suggestion for improvements, maintainers react by
855 modifying programs in various ways. The fact that a package has already
856 been internationalized should not make maintainers shy of adding new
857 strings, or modifying strings already translated. They just do their
858 job the best they can. For the Translation Project to work smoothly, it
859 is important that maintainers do not carry translation concerns on their
860 already loaded shoulders, and that translators be kept as free as
861 possible of programming concerns.
863 The only concern maintainers should have is carefully marking new
864 strings as translatable, when they should be, and do not otherwise worry
865 about them being translated, as this will come in proper time.
866 Consequently, when programs and their strings are adjusted in various
867 ways by maintainers, and for matters usually unrelated to translation,
868 ‘xgettext’ would construct ‘PACKAGE.pot’ files which are evolving over
869 time, so the translations carried by ‘LANG.po’ are slowly fading out of
872 It is important for translators (and even maintainers) to understand
873 that package translation is a continuous process in the lifetime of a
874 package, and not something which is done once and for all at the start.
875 After an initial burst of translation activity for a given package,
876 interventions are needed once in a while, because here and there,
877 translated entries become obsolete, and new untranslated entries appear,
880 The ‘msgmerge’ program has the purpose of refreshing an already
881 existing ‘LANG.po’ file, by comparing it with a newer ‘PACKAGE.pot’
882 template file, extracted by ‘xgettext’ out of recent C sources. The
883 refreshing operation adjusts all references to C source locations for
884 strings, since these strings move as programs are modified. Also,
885 ‘msgmerge’ comments out as obsolete, in ‘LANG.po’, those already
886 translated entries which are no longer used in the program sources
887 (*note Obsolete Entries::). It finally discovers new strings and
888 inserts them in the resulting PO file as untranslated entries (*note
889 Untranslated Entries::). *Note msgmerge Invocation::, for more
890 information about what ‘msgmerge’ really does.
892 Whatever route or means taken, the goal is to obtain an updated
893 ‘LANG.po’ file offering translations for all strings.
895 The temporal mobility, or fluidity of PO files, is an integral part
896 of the translation game, and should be well understood, and accepted.
897 People resisting it will have a hard time participating in the
898 Translation Project, or will give a hard time to other participants! In
899 particular, maintainers should relax and include all available official
900 PO files in their distributions, even if these have not recently been
901 updated, without exerting pressure on the translator teams to get the
902 job done. The pressure should rather come from the community of users
903 speaking a particular language, and maintainers should consider
904 themselves fairly relieved of any concern about the adequacy of
905 translation files. On the other hand, translators should reasonably try
906 updating the PO files they are responsible for, while the package is
907 undergoing pretest, prior to an official distribution.
909 Once the PO file is complete and dependable, the ‘msgfmt’ program is
910 used for turning the PO file into a machine-oriented format, which may
911 yield efficient retrieval of translations by the programs of the
912 package, whenever needed at runtime (*note MO Files::). *Note msgfmt
913 Invocation::, for more information about all modes of execution for the
916 Finally, the modified and marked C sources are compiled and linked
917 with the GNU ‘gettext’ library, usually through the operation of ‘make’,
918 given a suitable ‘Makefile’ exists for the project, and the resulting
919 executable is installed somewhere users will find it. The MO files
920 themselves should also be properly installed. Given the appropriate
921 environment variables are set (*note Setting the POSIX Locale::), the
922 program should localize itself automatically, whenever it executes.
924 The remainder of this manual has the purpose of explaining in depth
925 the various steps outlined above.
928 File: gettext.info, Node: Users, Next: PO Files, Prev: Introduction, Up: Top
933 Nowadays, when users log into a computer, they usually find that all
934 their programs show messages in their native language – at least for
935 users of languages with an active free software community, like French
936 or German; to a lesser extent for languages with a smaller participation
937 in free software and the GNU project, like Hindi and Filipino.
939 How does this work? How can the user influence the language that is
940 used by the programs? This chapter will answer it.
944 * System Installation:: Questions During Operating System Installation
945 * Setting the GUI Locale:: How to Specify the Locale Used by GUI Programs
946 * Setting the POSIX Locale:: How to Specify the Locale According to POSIX
947 * Installing Localizations:: How to Install Additional Translations
950 File: gettext.info, Node: System Installation, Next: Setting the GUI Locale, Prev: Users, Up: Users
952 2.1 Operating System Installation
953 =================================
955 The default language is often already specified during operating
956 system installation. When the operating system is installed, the
957 installer typically asks for the language used for the installation
958 process and, separately, for the language to use in the installed
959 system. Some OS installers only ask for the language once.
961 This determines the system-wide default language for all users. But
962 the installers often give the possibility to install extra localizations
963 for additional languages. For example, the localizations of KDE (the K
964 Desktop Environment) and OpenOffice.org are often bundled separately, as
965 one installable package per language.
967 At this point it is good to consider the intended use of the machine:
968 If it is a machine designated for personal use, additional localizations
969 are probably not necessary. If, however, the machine is in use in an
970 organization or company that has international relationships, one can
971 consider the needs of guest users. If you have a guest from abroad, for
972 a week, what could be his preferred locales? It may be worth installing
973 these additional localizations ahead of time, since they cost only a bit
974 of disk space at this point.
976 The system-wide default language is the locale configuration that is
977 used when a new user account is created. But the user can have his own
978 locale configuration that is different from the one of the other users
979 of the same machine. He can specify it, typically after the first
980 login, as described in the next section.
983 File: gettext.info, Node: Setting the GUI Locale, Next: Setting the POSIX Locale, Prev: System Installation, Up: Users
985 2.2 Setting the Locale Used by GUI Programs
986 ===========================================
988 The immediately available programs in a user’s desktop come from a
989 group of programs called a “desktop environment”; it usually includes
990 the window manager, a web browser, a text editor, and more. The most
991 common free desktop environments are KDE, GNOME, and Xfce.
993 The locale used by GUI programs of the desktop environment can be
994 specified in a configuration screen called “control center”, “language
995 settings” or “country settings”.
997 Individual GUI programs that are not part of the desktop environment
998 can have their locale specified either in a settings panel, or through
999 environment variables.
1001 For some programs, it is possible to specify the locale through
1002 environment variables, possibly even to a different locale than the
1003 desktop’s locale. This means, instead of starting a program through a
1004 menu or from the file system, you can start it from the command-line,
1005 after having set some environment variables. The environment variables
1006 can be those specified in the next section (*note Setting the POSIX
1007 Locale::); for some versions of KDE, however, the locale is specified
1008 through a variable ‘KDE_LANG’, rather than ‘LANG’ or ‘LC_ALL’.
1011 File: gettext.info, Node: Setting the POSIX Locale, Next: Installing Localizations, Prev: Setting the GUI Locale, Up: Users
1013 2.3 Setting the Locale through Environment Variables
1014 ====================================================
1016 As a user, if your language has been installed for this package, in
1017 the simplest case, you only have to set the ‘LANG’ environment variable
1018 to the appropriate ‘LL_CC’ combination. For example, let’s suppose that
1019 you speak German and live in Germany. At the shell prompt, merely
1020 execute ‘setenv LANG de_DE’ (in ‘csh’), ‘export LANG; LANG=de_DE’ (in
1021 ‘sh’) or ‘export LANG=de_DE’ (in ‘bash’). This can be done from your
1022 ‘.login’ or ‘.profile’ file, once and for all.
1026 * Locale Names:: How a Locale Specification Looks Like
1027 * Locale Environment Variables:: Which Environment Variable Specfies What
1028 * The LANGUAGE variable:: How to Specify a Priority List of Languages
1031 File: gettext.info, Node: Locale Names, Next: Locale Environment Variables, Prev: Setting the POSIX Locale, Up: Setting the POSIX Locale
1036 A locale name usually has the form ‘LL_CC’. Here ‘LL’ is an ISO 639
1037 two-letter language code, and ‘CC’ is an ISO 3166 two-letter country
1038 code. For example, for German in Germany, LL is ‘de’, and CC is ‘DE’.
1039 You find a list of the language codes in appendix *note Language Codes::
1040 and a list of the country codes in appendix *note Country Codes::.
1042 You might think that the country code specification is redundant.
1043 But in fact, some languages have dialects in different countries. For
1044 example, ‘de_AT’ is used for Austria, and ‘pt_BR’ for Brazil. The
1045 country code serves to distinguish the dialects.
1047 Many locale names have an extended syntax ‘LL_CC.ENCODING’ that also
1048 specifies the character encoding. These are in use because between 2000
1049 and 2005, most users have switched to locales in UTF-8 encoding. For
1050 example, the German locale on glibc systems is nowadays ‘de_DE.UTF-8’.
1051 The older name ‘de_DE’ still refers to the German locale as of 2000 that
1052 stores characters in ISO-8859-1 encoding – a text encoding that cannot
1053 even accommodate the Euro currency sign.
1055 Some locale names use ‘LL_CC.@VARIANT’ instead of ‘LL_CC’. The
1056 ‘@VARIANT’ can denote any kind of characteristics that is not already
1057 implied by the language LL and the country CC. It can denote a
1058 particular monetary unit. For example, on glibc systems, ‘de_DE@euro’
1059 denotes the locale that uses the Euro currency, in contrast to the older
1060 locale ‘de_DE’ which implies the use of the currency before 2002. It
1061 can also denote a dialect of the language, or the script used to write
1062 text (for example, ‘sr_RS@latin’ uses the Latin script, whereas ‘sr_RS’
1063 uses the Cyrillic script to write Serbian), or the orthography rules, or
1066 On other systems, some variations of this scheme are used, such as
1067 ‘LL’. You can get the list of locales supported by your system for your
1068 language by running the command ‘locale -a | grep '^LL'’.
1070 There is also a special locale, called ‘C’. When it is used, it
1071 disables all localization: in this locale, all programs standardized by
1072 POSIX use English messages and an unspecified character encoding (often
1073 US-ASCII, but sometimes also ISO-8859-1 or UTF-8, depending on the
1077 File: gettext.info, Node: Locale Environment Variables, Next: The LANGUAGE variable, Prev: Locale Names, Up: Setting the POSIX Locale
1079 2.3.2 Locale Environment Variables
1080 ----------------------------------
1082 A locale is composed of several _locale categories_, see *note
1083 Aspects::. When a program looks up locale dependent values, it does
1084 this according to the following environment variables, in priority
1089 3. ‘LC_xxx’, according to selected locale category: ‘LC_CTYPE’,
1090 ‘LC_NUMERIC’, ‘LC_TIME’, ‘LC_COLLATE’, ‘LC_MONETARY’,
1094 Variables whose value is set but is empty are ignored in this lookup.
1096 ‘LANG’ is the normal environment variable for specifying a locale.
1097 As a user, you normally set this variable (unless some of the other
1098 variables have already been set by the system, in ‘/etc/profile’ or
1099 similar initialization files).
1101 ‘LC_CTYPE’, ‘LC_NUMERIC’, ‘LC_TIME’, ‘LC_COLLATE’, ‘LC_MONETARY’,
1102 ‘LC_MESSAGES’, and so on, are the environment variables meant to
1103 override ‘LANG’ and affecting a single locale category only. For
1104 example, assume you are a Swedish user in Spain, and you want your
1105 programs to handle numbers and dates according to Spanish conventions,
1106 and only the messages should be in Swedish. Then you could create a
1107 locale named ‘sv_ES’ or ‘sv_ES.UTF-8’ by use of the ‘localedef’ program.
1108 But it is simpler, and achieves the same effect, to set the ‘LANG’
1109 variable to ‘es_ES.UTF-8’ and the ‘LC_MESSAGES’ variable to
1110 ‘sv_SE.UTF-8’; these two locales come already preinstalled with the
1113 ‘LC_ALL’ is an environment variable that overrides all of these. It
1114 is typically used in scripts that run particular programs. For example,
1115 ‘configure’ scripts generated by GNU autoconf use ‘LC_ALL’ to make sure
1116 that the configuration tests don’t operate in locale dependent ways.
1118 Some systems, unfortunately, set ‘LC_ALL’ in ‘/etc/profile’ or in
1119 similar initialization files. As a user, you therefore have to unset
1120 this variable if you want to set ‘LANG’ and optionally some of the other
1123 The ‘LANGUAGE’ variable is described in the next subsection.
1126 File: gettext.info, Node: The LANGUAGE variable, Prev: Locale Environment Variables, Up: Setting the POSIX Locale
1128 2.3.3 Specifying a Priority List of Languages
1129 ---------------------------------------------
1131 Not all programs have translations for all languages. By default, an
1132 English message is shown in place of a nonexistent translation. If you
1133 understand other languages, you can set up a priority list of languages.
1134 This is done through a different environment variable, called
1135 ‘LANGUAGE’. GNU ‘gettext’ gives preference to ‘LANGUAGE’ over ‘LC_ALL’
1136 and ‘LANG’ for the purpose of message handling, but you still need to
1137 have ‘LANG’ (or ‘LC_ALL’) set to the primary language; this is required
1138 by other parts of the system libraries. For example, some Swedish users
1139 who would rather read translations in German than English for when
1140 Swedish is not available, set ‘LANGUAGE’ to ‘sv:de’ while leaving ‘LANG’
1143 Special advice for Norwegian users: The language code for Norwegian
1144 bokmål changed from ‘no’ to ‘nb’ recently (in 2003). During the
1145 transition period, while some message catalogs for this language are
1146 installed under ‘nb’ and some older ones under ‘no’, it is recommended
1147 for Norwegian users to set ‘LANGUAGE’ to ‘nb:no’ so that both newer and
1148 older translations are used.
1150 In the ‘LANGUAGE’ environment variable, but not in the other
1151 environment variables, ‘LL_CC’ combinations can be abbreviated as ‘LL’
1152 to denote the language’s main dialect. For example, ‘de’ is equivalent
1153 to ‘de_DE’ (German as spoken in Germany), and ‘pt’ to ‘pt_PT’
1154 (Portuguese as spoken in Portugal) in this context.
1156 Note: The variable ‘LANGUAGE’ is ignored if the locale is set to ‘C’.
1157 In other words, you have to first enable localization, by setting ‘LANG’
1158 (or ‘LC_ALL’) to a value other than ‘C’, before you can use a language
1159 priority list through the ‘LANGUAGE’ variable.
1162 File: gettext.info, Node: Installing Localizations, Prev: Setting the POSIX Locale, Up: Users
1164 2.4 Installing Translations for Particular Programs
1165 ===================================================
1167 Languages are not equally well supported in all packages using GNU
1168 ‘gettext’, and more translations are added over time. Usually, you use
1169 the translations that are shipped with the operating system or with
1170 particular packages that you install afterwards. But you can also
1171 install newer localizations directly. For doing this, you will need an
1172 understanding where each localization file is stored on the file system.
1174 For programs that participate in the Translation Project, you can
1175 start looking for translations here:
1176 <http://translationproject.org/team/index.html>. A snapshot of this
1177 information is also found in the ‘ABOUT-NLS’ file that is shipped with
1180 For programs that are part of the KDE project, the starting point is:
1181 <http://i18n.kde.org/>.
1183 For programs that are part of the GNOME project, the starting point
1184 is: <http://www.gnome.org/i18n/>.
1186 For other programs, you may check whether the program’s source code
1187 package contains some ‘LL.po’ files; often they are kept together in a
1188 directory called ‘po/’. Each ‘LL.po’ file contains the message
1189 translations for the language whose abbreviation of LL.
1192 File: gettext.info, Node: PO Files, Next: Sources, Prev: Users, Up: Top
1194 3 The Format of PO Files
1195 ************************
1197 The GNU ‘gettext’ toolset helps programmers and translators at
1198 producing, updating and using translation files, mainly those PO files
1199 which are textual, editable files. This chapter explains the format of
1202 A PO file is made up of many entries, each entry holding the relation
1203 between an original untranslated string and its corresponding
1204 translation. All entries in a given PO file usually pertain to a single
1205 project, and all translations are expressed in a single target language.
1206 One PO file "entry" has the following schematic structure:
1209 # TRANSLATOR-COMMENTS
1210 #. EXTRACTED-COMMENTS
1213 #| msgid PREVIOUS-UNTRANSLATED-STRING
1214 msgid UNTRANSLATED-STRING
1215 msgstr TRANSLATED-STRING
1217 The general structure of a PO file should be well understood by the
1218 translator. When using PO mode, very little has to be known about the
1219 format details, as PO mode takes care of them for her.
1221 A simple entry can look like this:
1224 msgid "Unknown system error"
1225 msgstr "Error desconegut del sistema"
1227 Entries begin with some optional white space. Usually, when
1228 generated through GNU ‘gettext’ tools, there is exactly one blank line
1229 between entries. Then comments follow, on lines all starting with the
1230 character ‘#’. There are two kinds of comments: those which have some
1231 white space immediately following the ‘#’ - the TRANSLATOR COMMENTS -,
1232 which comments are created and maintained exclusively by the translator,
1233 and those which have some non-white character just after the ‘#’ - the
1234 AUTOMATIC COMMENTS -, which comments are created and maintained
1235 automatically by GNU ‘gettext’ tools. Comment lines starting with ‘#.’
1236 contain comments given by the programmer, directed at the translator;
1237 these comments are called EXTRACTED COMMENTS because the ‘xgettext’
1238 program extracts them from the program’s source code. Comment lines
1239 starting with ‘#:’ contain references to the program’s source code.
1240 Comment lines starting with ‘#,’ contain flags; more about these below.
1241 Comment lines starting with ‘#|’ contain the previous untranslated
1242 string for which the translator gave a translation.
1244 All comments, of either kind, are optional.
1246 After white space and comments, entries show two strings, namely
1247 first the untranslated string as it appears in the original program
1248 sources, and then, the translation of this string. The original string
1249 is introduced by the keyword ‘msgid’, and the translation, by ‘msgstr’.
1250 The two strings, untranslated and translated, are quoted in various ways
1251 in the PO file, using ‘"’ delimiters and ‘\’ escapes, but the translator
1252 does not really have to pay attention to the precise quoting format, as
1253 PO mode fully takes care of quoting for her.
1255 The ‘msgid’ strings, as well as automatic comments, are produced and
1256 managed by other GNU ‘gettext’ tools, and PO mode does not provide means
1257 for the translator to alter these. The most she can do is merely
1258 deleting them, and only by deleting the whole entry. On the other hand,
1259 the ‘msgstr’ string, as well as translator comments, are really meant
1260 for the translator, and PO mode gives her the full control she needs.
1262 The comment lines beginning with ‘#,’ are special because they are
1263 not completely ignored by the programs as comments generally are. The
1264 comma separated list of FLAGs is used by the ‘msgfmt’ program to give
1265 the user some better diagnostic messages. Currently there are two forms
1269 This flag can be generated by the ‘msgmerge’ program or it can be
1270 inserted by the translator herself. It shows that the ‘msgstr’
1271 string might not be a correct translation (anymore). Only the
1272 translator can judge if the translation requires further
1273 modification, or is acceptable as is. Once satisfied with the
1274 translation, she then removes this ‘fuzzy’ attribute. The
1275 ‘msgmerge’ program inserts this when it combined the ‘msgid’ and
1276 ‘msgstr’ entries after fuzzy search only. *Note Fuzzy Entries::.
1280 These flags should not be added by a human. Instead only the
1281 ‘xgettext’ program adds them. In an automated PO file processing
1282 system as proposed here, the user’s changes would be thrown away
1283 again as soon as the ‘xgettext’ program generates a new template
1286 The ‘c-format’ flag indicates that the untranslated string and the
1287 translation are supposed to be C format strings. The ‘no-c-format’
1288 flag indicates that they are not C format strings, even though the
1289 untranslated string happens to look like a C format string (with
1292 When the ‘c-format’ flag is given for a string the ‘msgfmt’ program
1293 does some more tests to check the validity of the translation.
1294 *Note msgfmt Invocation::, *note c-format Flag:: and *note
1299 Likewise for Objective C, see *note objc-format::.
1303 Likewise for Shell, see *note sh-format::.
1307 Likewise for Python, see *note python-format::.
1309 ‘python-brace-format’
1310 ‘no-python-brace-format’
1311 Likewise for Python brace, see *note python-format::.
1315 Likewise for Lisp, see *note lisp-format::.
1319 Likewise for Emacs Lisp, see *note elisp-format::.
1323 Likewise for librep, see *note librep-format::.
1327 Likewise for Scheme, see *note scheme-format::.
1330 ‘no-smalltalk-format’
1331 Likewise for Smalltalk, see *note smalltalk-format::.
1335 Likewise for Java, see *note java-format::.
1339 Likewise for C#, see *note csharp-format::.
1343 Likewise for awk, see *note awk-format::.
1345 ‘object-pascal-format’
1346 ‘no-object-pascal-format’
1347 Likewise for Object Pascal, see *note object-pascal-format::.
1351 Likewise for YCP, see *note ycp-format::.
1355 Likewise for Tcl, see *note tcl-format::.
1359 Likewise for Perl, see *note perl-format::.
1362 ‘no-perl-brace-format’
1363 Likewise for Perl brace, see *note perl-format::.
1367 Likewise for PHP, see *note php-format::.
1369 ‘gcc-internal-format’
1370 ‘no-gcc-internal-format’
1371 Likewise for the GCC sources, see *note gcc-internal-format::.
1373 ‘gfc-internal-format’
1374 ‘no-gfc-internal-format’
1375 Likewise for the GNU Fortran Compiler sources, see *note
1376 gfc-internal-format::.
1380 Likewise for Qt, see *note qt-format::.
1383 ‘no-qt-plural-format’
1384 Likewise for Qt plural forms, see *note qt-plural-format::.
1388 Likewise for KDE, see *note kde-format::.
1392 Likewise for Boost, see *note boost-format::.
1396 Likewise for Lua, see *note lua-format::.
1399 ‘no-javascript-format’
1400 Likewise for JavaScript, see *note javascript-format::.
1402 It is also possible to have entries with a context specifier. They
1406 # TRANSLATOR-COMMENTS
1407 #. EXTRACTED-COMMENTS
1410 #| msgctxt PREVIOUS-CONTEXT
1411 #| msgid PREVIOUS-UNTRANSLATED-STRING
1413 msgid UNTRANSLATED-STRING
1414 msgstr TRANSLATED-STRING
1416 The context serves to disambiguate messages with the same
1417 UNTRANSLATED-STRING. It is possible to have several entries with the
1418 same UNTRANSLATED-STRING in a PO file, provided that they each have a
1419 different CONTEXT. Note that an empty CONTEXT string and an absent
1420 ‘msgctxt’ line do not mean the same thing.
1422 A different kind of entries is used for translations which involve
1426 # TRANSLATOR-COMMENTS
1427 #. EXTRACTED-COMMENTS
1430 #| msgid PREVIOUS-UNTRANSLATED-STRING-SINGULAR
1431 #| msgid_plural PREVIOUS-UNTRANSLATED-STRING-PLURAL
1432 msgid UNTRANSLATED-STRING-SINGULAR
1433 msgid_plural UNTRANSLATED-STRING-PLURAL
1434 msgstr[0] TRANSLATED-STRING-CASE-0
1436 msgstr[N] TRANSLATED-STRING-CASE-N
1438 Such an entry can look like this:
1440 #: src/msgcmp.c:338 src/po-lex.c:699
1442 msgid "found %d fatal error"
1443 msgid_plural "found %d fatal errors"
1444 msgstr[0] "s'ha trobat %d error fatal"
1445 msgstr[1] "s'han trobat %d errors fatals"
1447 Here also, a ‘msgctxt’ context can be specified before ‘msgid’, like
1450 Here, additional kinds of flags can be used:
1453 This flag is followed by a range of non-negative numbers, using the
1454 syntax ‘range: MINIMUM-VALUE..MAXIMUM-VALUE’. It designates the
1455 possible values that the numeric parameter of the message can take.
1456 In some languages, translators may produce slightly better
1457 translations if they know that the value can only take on values
1458 between 0 and 10, for example.
1460 The PREVIOUS-UNTRANSLATED-STRING is optionally inserted by the
1461 ‘msgmerge’ program, at the same time when it marks a message fuzzy. It
1462 helps the translator to see which changes were done by the developers on
1463 the UNTRANSLATED-STRING.
1465 It happens that some lines, usually whitespace or comments, follow
1466 the very last entry of a PO file. Such lines are not part of any entry,
1467 and will be dropped when the PO file is processed by the tools, or may
1468 disturb some PO file editors.
1470 The remainder of this section may be safely skipped by those using a
1471 PO file editor, yet it may be interesting for everybody to have a better
1472 idea of the precise format of a PO file. On the other hand, those
1473 wishing to modify PO files by hand should carefully continue reading on.
1475 An empty UNTRANSLATED-STRING is reserved to contain the header entry
1476 with the meta information (*note Header Entry::). This header entry
1477 should be the first entry of the file. The empty UNTRANSLATED-STRING is
1478 reserved for this purpose and must not be used anywhere else.
1480 Each of UNTRANSLATED-STRING and TRANSLATED-STRING respects the C
1481 syntax for a character string, including the surrounding quotes and
1482 embedded backslashed escape sequences. When the time comes to write
1483 multi-line strings, one should not use escaped newlines. Instead, a
1484 closing quote should follow the last character on the line to be
1485 continued, and an opening quote should resume the string at the
1486 beginning of the following PO file line. For example:
1489 "Here is an example of how one might continue a very long string\n"
1490 "for the common case the string represents multi-line output.\n"
1492 In this example, the empty string is used on the first line, to allow
1493 better alignment of the ‘H’ from the word ‘Here’ over the ‘f’ from the
1494 word ‘for’. In this example, the ‘msgid’ keyword is followed by three
1495 strings, which are meant to be concatenated. Concatenating the empty
1496 string does not change the resulting overall string, but it is a way for
1497 us to comply with the necessity of ‘msgid’ to be followed by a string on
1498 the same line, while keeping the multi-line presentation left-justified,
1499 as we find this to be a cleaner disposition. The empty string could
1500 have been omitted, but only if the string starting with ‘Here’ was
1501 promoted on the first line, right after ‘msgid’.(1) It was not really
1502 necessary either to switch between the two last quoted strings
1503 immediately after the newline ‘\n’, the switch could have occurred after
1504 _any_ other character, we just did it this way because it is neater.
1506 One should carefully distinguish between end of lines marked as ‘\n’
1507 _inside_ quotes, which are part of the represented string, and end of
1508 lines in the PO file itself, outside string quotes, which have no
1509 incidence on the represented string.
1511 Outside strings, white lines and comments may be used freely.
1512 Comments start at the beginning of a line with ‘#’ and extend until the
1513 end of the PO file line. Comments written by translators should have
1514 the initial ‘#’ immediately followed by some white space. If the ‘#’ is
1515 not immediately followed by white space, this comment is most likely
1516 generated and managed by specialized GNU tools, and might disappear or
1517 be replaced unexpectedly when the PO file is given to ‘msgmerge’.
1519 ---------- Footnotes ----------
1521 (1) This limitation is not imposed by GNU ‘gettext’, but is for
1522 compatibility with the ‘msgfmt’ implementation on Solaris.
1525 File: gettext.info, Node: Sources, Next: Template, Prev: PO Files, Up: Top
1527 4 Preparing Program Sources
1528 ***************************
1530 For the programmer, changes to the C source code fall into three
1531 categories. First, you have to make the localization functions known to
1532 all modules needing message translation. Second, you should properly
1533 trigger the operation of GNU ‘gettext’ when the program initializes,
1534 usually from the ‘main’ function. Last, you should identify, adjust and
1535 mark all constant strings in your program needing translation.
1539 * Importing:: Importing the ‘gettext’ declaration
1540 * Triggering:: Triggering ‘gettext’ Operations
1541 * Preparing Strings:: Preparing Translatable Strings
1542 * Mark Keywords:: How Marks Appear in Sources
1543 * Marking:: Marking Translatable Strings
1544 * c-format Flag:: Telling something about the following string
1545 * Special cases:: Special Cases of Translatable Strings
1546 * Bug Report Address:: Letting Users Report Translation Bugs
1547 * Names:: Marking Proper Names for Translation
1548 * Libraries:: Preparing Library Sources
1551 File: gettext.info, Node: Importing, Next: Triggering, Prev: Sources, Up: Sources
1553 4.1 Importing the ‘gettext’ declaration
1554 =======================================
1556 Presuming that your set of programs, or package, has been adjusted so
1557 all needed GNU ‘gettext’ files are available, and your ‘Makefile’ files
1558 are adjusted (*note Maintainers::), each C module having translated C
1559 strings should contain the line:
1561 #include <libintl.h>
1563 Similarly, each C module containing ‘printf()’/‘fprintf()’/... calls
1564 with a format string that could be a translated C string (even if the C
1565 string comes from a different C module) should contain the line:
1567 #include <libintl.h>
1570 File: gettext.info, Node: Triggering, Next: Preparing Strings, Prev: Importing, Up: Sources
1572 4.2 Triggering ‘gettext’ Operations
1573 ===================================
1575 The initialization of locale data should be done with more or less
1576 the same code in every program, as demonstrated below:
1579 main (int argc, char *argv[])
1582 setlocale (LC_ALL, "");
1583 bindtextdomain (PACKAGE, LOCALEDIR);
1584 textdomain (PACKAGE);
1588 PACKAGE and LOCALEDIR should be provided either by ‘config.h’ or by
1589 the Makefile. For now consult the ‘gettext’ or ‘hello’ sources for more
1592 The use of ‘LC_ALL’ might not be appropriate for you. ‘LC_ALL’
1593 includes all locale categories and especially ‘LC_CTYPE’. This latter
1594 category is responsible for determining character classes with the
1595 ‘isalnum’ etc. functions from ‘ctype.h’ which could especially for
1596 programs, which process some kind of input language, be wrong. For
1597 example this would mean that a source code using the ç (c-cedilla
1598 character) is runnable in France but not in the U.S.
1600 Some systems also have problems with parsing numbers using the
1601 ‘scanf’ functions if an other but the ‘LC_ALL’ locale category is used.
1602 The standards say that additional formats but the one known in the ‘"C"’
1603 locale might be recognized. But some systems seem to reject numbers in
1604 the ‘"C"’ locale format. In some situation, it might also be a problem
1605 with the notation itself which makes it impossible to recognize whether
1606 the number is in the ‘"C"’ locale or the local format. This can happen
1607 if thousands separator characters are used. Some locales define this
1608 character according to the national conventions to ‘'.'’ which is the
1609 same character used in the ‘"C"’ locale to denote the decimal point.
1611 So it is sometimes necessary to replace the ‘LC_ALL’ line in the code
1612 above by a sequence of ‘setlocale’ lines
1616 setlocale (LC_CTYPE, "");
1617 setlocale (LC_MESSAGES, "");
1621 On all POSIX conformant systems the locale categories ‘LC_CTYPE’,
1622 ‘LC_MESSAGES’, ‘LC_COLLATE’, ‘LC_MONETARY’, ‘LC_NUMERIC’, and ‘LC_TIME’
1623 are available. On some systems which are only ISO C compliant,
1624 ‘LC_MESSAGES’ is missing, but a substitute for it is defined in GNU
1625 gettext’s ‘<libintl.h>’ and in GNU gnulib’s ‘<locale.h>’.
1627 Note that changing the ‘LC_CTYPE’ also affects the functions declared
1628 in the ‘<ctype.h>’ standard header and some functions declared in the
1629 ‘<string.h>’ and ‘<stdlib.h>’ standard headers. If this is not
1630 desirable in your application (for example in a compiler’s parser), you
1631 can use a set of substitute functions which hardwire the C locale, such
1632 as found in the modules ‘c-ctype’, ‘c-strcase’, ‘c-strcasestr’,
1633 ‘c-strtod’, ‘c-strtold’ in the GNU gnulib source distribution.
1635 It is also possible to switch the locale forth and back between the
1636 environment dependent locale and the C locale, but this approach is
1637 normally avoided because a ‘setlocale’ call is expensive, because it is
1638 tedious to determine the places where a locale switch is needed in a
1639 large program’s source, and because switching a locale is not
1643 File: gettext.info, Node: Preparing Strings, Next: Mark Keywords, Prev: Triggering, Up: Sources
1645 4.3 Preparing Translatable Strings
1646 ==================================
1648 Before strings can be marked for translations, they sometimes need to
1649 be adjusted. Usually preparing a string for translation is done right
1650 before marking it, during the marking phase which is described in the
1651 next sections. What you have to keep in mind while doing that is the
1654 • Decent English style.
1658 • Split at paragraphs.
1660 • Use format strings instead of string concatenation.
1662 • Avoid unusual markup and unusual control characters.
1664 Let’s look at some examples of these guidelines.
1666 Translatable strings should be in good English style. If slang
1667 language with abbreviations and shortcuts is used, often translators
1668 will not understand the message and will produce very inappropriate
1671 "%s: is parameter\n"
1673 This is nearly untranslatable: Is the displayed item _a_ parameter or
1678 The ambiguity in this message makes it unintelligible: Is the program
1679 attempting to set something on fire? Does it mean "The given object
1680 does not match the template"? Does it mean "The template does not fit
1681 for any of the objects"?
1683 In both cases, adding more words to the message will help both the
1684 translator and the English speaking user.
1686 Translatable strings should be entire sentences. It is often not
1687 possible to translate single verbs or adjectives in a substitutable way.
1689 printf ("File %s is %s protected", filename, rw ? "write" : "read");
1691 Most translators will not look at the source and will thus only see the
1692 string ‘"File %s is %s protected"’, which is unintelligible. Change
1695 printf (rw ? "File %s is write protected" : "File %s is read protected",
1698 This way the translator will not only understand the message, she will
1699 also be able to find the appropriate grammatical construction. A French
1700 translator for example translates "write protected" like "protected
1703 Entire sentences are also important because in many languages, the
1704 declination of some word in a sentence depends on the gender or the
1705 number (singular/plural) of another part of the sentence. There are
1706 usually more interdependencies between words than in English. The
1707 consequence is that asking a translator to translate two half-sentences
1708 and then combining these two half-sentences through dumb string
1709 concatenation will not work, for many languages, even though it would
1710 work for English. That’s why translators need to handle entire
1713 Often sentences don’t fit into a single line. If a sentence is
1714 output using two subsequent ‘printf’ statements, like this
1716 printf ("Locale charset \"%s\" is different from\n", lcharset);
1717 printf ("input file charset \"%s\".\n", fcharset);
1719 the translator would have to translate two half sentences, but nothing
1720 in the POT file would tell her that the two half sentences belong
1721 together. It is necessary to merge the two ‘printf’ statements so that
1722 the translator can handle the entire sentence at once and decide at
1723 which place to insert a line break in the translation (if at all):
1725 printf ("Locale charset \"%s\" is different from\n\
1726 input file charset \"%s\".\n", lcharset, fcharset);
1728 You may now ask: how about two or more adjacent sentences? Like in
1731 puts ("Apollo 13 scenario: Stack overflow handling failed.");
1732 puts ("On the next stack overflow we will crash!!!");
1734 Should these two statements merged into a single one? I would recommend
1735 to merge them if the two sentences are related to each other, because
1736 then it makes it easier for the translator to understand and translate
1737 both. On the other hand, if one of the two messages is a stereotypic
1738 one, occurring in other places as well, you will do a favour to the
1739 translator by not merging the two. (Identical messages occurring in
1740 several places are combined by xgettext, so the translator has to handle
1743 Translatable strings should be limited to one paragraph; don’t let a
1744 single message be longer than ten lines. The reason is that when the
1745 translatable string changes, the translator is faced with the task of
1746 updating the entire translated string. Maybe only a single word will
1747 have changed in the English string, but the translator doesn’t see that
1748 (with the current translation tools), therefore she has to proofread the
1751 Many GNU programs have a ‘--help’ output that extends over several
1752 screen pages. It is a courtesy towards the translators to split such a
1753 message into several ones of five to ten lines each. While doing that,
1754 you can also attempt to split the documented options into groups, such
1755 as the input options, the output options, and the informative output
1756 options. This will help every user to find the option he is looking
1759 Hardcoded string concatenation is sometimes used to construct English
1762 strcpy (s, "Replace ");
1763 strcat (s, object1);
1764 strcat (s, " with ");
1765 strcat (s, object2);
1768 In order to present to the translator only entire sentences, and also
1769 because in some languages the translator might want to swap the order of
1770 ‘object1’ and ‘object2’, it is necessary to change this to use a format
1773 sprintf (s, "Replace %s with %s?", object1, object2);
1775 A similar case is compile time concatenation of strings. The ISO C
1776 99 include file ‘<inttypes.h>’ contains a macro ‘PRId64’ that can be
1777 used as a formatting directive for outputting an ‘int64_t’ integer
1778 through ‘printf’. It expands to a constant string, usually "d" or "ld"
1779 or "lld" or something like this, depending on the platform. Assume you
1782 printf ("The amount is %0" PRId64 "\n", number);
1784 The ‘gettext’ tools and library have special support for these
1785 ‘<inttypes.h>’ macros. You can therefore simply write
1787 printf (gettext ("The amount is %0" PRId64 "\n"), number);
1789 The PO file will contain the string "The amount is %0<PRId64>\n". The
1790 translators will provide a translation containing "%0<PRId64>" as well,
1791 and at runtime the ‘gettext’ function’s result will contain the
1792 appropriate constant string, "d" or "ld" or "lld".
1794 This works only for the predefined ‘<inttypes.h>’ macros. If you
1795 have defined your own similar macros, let’s say ‘MYPRId64’, that are not
1796 known to ‘xgettext’, the solution for this problem is to change the code
1800 sprintf (buf1, "%0" MYPRId64, number);
1801 printf (gettext ("The amount is %s\n"), buf1);
1803 This means, you put the platform dependent code in one statement, and
1804 the internationalization code in a different statement. Note that a
1805 buffer length of 100 is safe, because all available hardware integer
1806 types are limited to 128 bits, and to print a 128 bit integer one needs
1807 at most 54 characters, regardless whether in decimal, octal or
1810 All this applies to other programming languages as well. For
1811 example, in Java and C#, string concatenation is very frequently used,
1812 because it is a compiler built-in operator. Like in C, in Java, you
1815 System.out.println("Replace "+object1+" with "+object2+"?");
1817 into a statement involving a format string:
1820 MessageFormat.format("Replace {0} with {1}?",
1821 new Object[] { object1, object2 }));
1823 Similarly, in C#, you would change
1825 Console.WriteLine("Replace "+object1+" with "+object2+"?");
1827 into a statement involving a format string:
1830 String.Format("Replace {0} with {1}?", object1, object2));
1832 Unusual markup or control characters should not be used in
1833 translatable strings. Translators will likely not understand the
1834 particular meaning of the markup or control characters.
1836 For example, if you have a convention that ‘|’ delimits the left-hand
1837 and right-hand part of some GUI elements, translators will often not
1838 understand it without specific comments. It might be better to have the
1839 translator translate the left-hand and right-hand part separately.
1841 Another example is the ‘argp’ convention to use a single ‘\v’
1842 (vertical tab) control character to delimit two sections inside a
1843 string. This is flawed. Some translators may convert it to a simple
1844 newline, some to blank lines. With some PO file editors it may not be
1845 easy to even enter a vertical tab control character. So, you cannot be
1846 sure that the translation will contain a ‘\v’ character, at the
1847 corresponding position. The solution is, again, to let the translator
1848 translate two separate strings and combine at run-time the two
1849 translated strings with the ‘\v’ required by the convention.
1851 HTML markup, however, is common enough that it’s probably ok to use
1852 in translatable strings. But please bear in mind that the GNU gettext
1853 tools don’t verify that the translations are well-formed HTML.
1856 File: gettext.info, Node: Mark Keywords, Next: Marking, Prev: Preparing Strings, Up: Sources
1858 4.4 How Marks Appear in Sources
1859 ===============================
1861 All strings requiring translation should be marked in the C sources.
1862 Marking is done in such a way that each translatable string appears to
1863 be the sole argument of some function or preprocessor macro. There are
1864 only a few such possible functions or macros meant for translation, and
1865 their names are said to be marking keywords. The marking is attached to
1866 strings themselves, rather than to what we do with them. This approach
1867 has more uses. A blatant example is an error message produced by
1868 formatting. The format string needs translation, as well as some
1869 strings inserted through some ‘%s’ specification in the format, while
1870 the result from ‘sprintf’ may have so many different instances that it
1871 is impractical to list them all in some ‘error_string_out()’ routine,
1874 This marking operation has two goals. The first goal of marking is
1875 for triggering the retrieval of the translation, at run time. The
1876 keyword is possibly resolved into a routine able to dynamically return
1877 the proper translation, as far as possible or wanted, for the argument
1878 string. Most localizable strings are found in executable positions,
1879 that is, attached to variables or given as parameters to functions. But
1880 this is not universal usage, and some translatable strings appear in
1881 structured initializations. *Note Special cases::.
1883 The second goal of the marking operation is to help ‘xgettext’ at
1884 properly extracting all translatable strings when it scans a set of
1885 program sources and produces PO file templates.
1887 The canonical keyword for marking translatable strings is ‘gettext’,
1888 it gave its name to the whole GNU ‘gettext’ package. For packages
1889 making only light use of the ‘gettext’ keyword, macro or function, it is
1890 easily used _as is_. However, for packages using the ‘gettext’
1891 interface more heavily, it is usually more convenient to give the main
1892 keyword a shorter, less obtrusive name. Indeed, the keyword might
1893 appear on a lot of strings all over the package, and programmers usually
1894 do not want nor need their program sources to remind them forcefully,
1895 all the time, that they are internationalized. Further, a long keyword
1896 has the disadvantage of using more horizontal space, forcing more
1897 indentation work on sources for those trying to keep them within 79 or
1900 Many packages use ‘_’ (a simple underline) as a keyword, and write
1901 ‘_("Translatable string")’ instead of ‘gettext ("Translatable string")’.
1902 Further, the coding rule, from GNU standards, wanting that there is a
1903 space between the keyword and the opening parenthesis is relaxed, in
1904 practice, for this particular usage. So, the textual overhead per
1905 translatable string is reduced to only three characters: the underline
1906 and the two parentheses. However, even if GNU ‘gettext’ uses this
1907 convention internally, it does not offer it officially. The real,
1908 genuine keyword is truly ‘gettext’ indeed. It is fairly easy for those
1909 wanting to use ‘_’ instead of ‘gettext’ to declare:
1911 #include <libintl.h>
1912 #define _(String) gettext (String)
1914 instead of merely using ‘#include <libintl.h>’.
1916 The marking keywords ‘gettext’ and ‘_’ take the translatable string
1917 as sole argument. It is also possible to define marking functions that
1918 take it at another argument position. It is even possible to make the
1919 marked argument position depend on the total number of arguments of the
1920 function call; this is useful in C++. All this is achieved using
1921 ‘xgettext’’s ‘--keyword’ option. How to pass such an option to
1922 ‘xgettext’, assuming that ‘gettextize’ is used, is described in *note
1923 po/Makevars:: and *note AM_XGETTEXT_OPTION::.
1925 Note also that long strings can be split across lines, into multiple
1926 adjacent string tokens. Automatic string concatenation is performed at
1927 compile time according to ISO C and ISO C++; ‘xgettext’ also supports
1930 Later on, the maintenance is relatively easy. If, as a programmer,
1931 you add or modify a string, you will have to ask yourself if the new or
1932 altered string requires translation, and include it within ‘_()’ if you
1933 think it should be translated. For example, ‘"%s"’ is an example of
1934 string _not_ requiring translation. But ‘"%s: %d"’ _does_ require
1935 translation, because in French, unlike in English, it’s customary to put
1936 a space before a colon.
1939 File: gettext.info, Node: Marking, Next: c-format Flag, Prev: Mark Keywords, Up: Sources
1941 4.5 Marking Translatable Strings
1942 ================================
1944 In PO mode, one set of features is meant more for the programmer than
1945 for the translator, and allows him to interactively mark which strings,
1946 in a set of program sources, are translatable, and which are not. Even
1947 if it is a fairly easy job for a programmer to find and mark such
1948 strings by other means, using any editor of his choice, PO mode makes
1949 this work more comfortable. Further, this gives translators who feel a
1950 little like programmers, or programmers who feel a little like
1951 translators, a tool letting them work at marking translatable strings in
1952 the program sources, while simultaneously producing a set of translation
1953 in some language, for the package being internationalized.
1955 The set of program sources, targeted by the PO mode commands describe
1956 here, should have an Emacs tags table constructed for your project,
1957 prior to using these PO file commands. This is easy to do. In any
1958 shell window, change the directory to the root of your project, then
1959 execute a command resembling:
1961 etags src/*.[hc] lib/*.[hc]
1963 presuming here you want to process all ‘.h’ and ‘.c’ files from the
1964 ‘src/’ and ‘lib/’ directories. This command will explore all said files
1965 and create a ‘TAGS’ file in your root directory, somewhat summarizing
1966 the contents using a special file format Emacs can understand.
1968 For packages following the GNU coding standards, there is a make goal
1969 ‘tags’ or ‘TAGS’ which constructs the tag files in all directories and
1970 for all files containing source code.
1972 Once your ‘TAGS’ file is ready, the following commands assist the
1973 programmer at marking translatable strings in his set of sources. But
1974 these commands are necessarily driven from within a PO file window, and
1975 it is likely that you do not even have such a PO file yet. This is not
1976 a problem at all, as you may safely open a new, empty PO file, mainly
1977 for using these commands. This empty PO file will slowly fill in while
1978 you mark strings as translatable in your program sources.
1981 Search through program sources for a string which looks like a
1982 candidate for translation (‘po-tags-search’).
1985 Mark the last string found with ‘_()’ (‘po-mark-translatable’).
1988 Mark the last string found with a keyword taken from a set of
1989 possible keywords. This command with a prefix allows some
1990 management of these keywords (‘po-select-mark-and-mark’).
1992 The ‘,’ (‘po-tags-search’) command searches for the next occurrence
1993 of a string which looks like a possible candidate for translation, and
1994 displays the program source in another Emacs window, positioned in such
1995 a way that the string is near the top of this other window. If the
1996 string is too big to fit whole in this window, it is positioned so only
1997 its end is shown. In any case, the cursor is left in the PO file
1998 window. If the shown string would be better presented differently in
1999 different native languages, you may mark it using ‘M-,’ or ‘M-.’.
2000 Otherwise, you might rather ignore it and skip to the next string by
2001 merely repeating the ‘,’ command.
2003 A string is a good candidate for translation if it contains a
2004 sequence of three or more letters. A string containing at most two
2005 letters in a row will be considered as a candidate if it has more
2006 letters than non-letters. The command disregards strings containing no
2007 letters, or isolated letters only. It also disregards strings within
2008 comments, or strings already marked with some keyword PO mode knows (see
2011 If you have never told Emacs about some ‘TAGS’ file to use, the
2012 command will request that you specify one from the minibuffer, the first
2013 time you use the command. You may later change your ‘TAGS’ file by
2014 using the regular Emacs command ‘M-x visit-tags-table’, which will ask
2015 you to name the precise ‘TAGS’ file you want to use. *Note Tag Tables:
2018 Each time you use the ‘,’ command, the search resumes from where it
2019 was left by the previous search, and goes through all program sources,
2020 obeying the ‘TAGS’ file, until all sources have been processed.
2021 However, by giving a prefix argument to the command (‘C-u ,’), you may
2022 request that the search be restarted all over again from the first
2023 program source; but in this case, strings that you recently marked as
2024 translatable will be automatically skipped.
2026 Using this ‘,’ command does not prevent using of other regular Emacs
2027 tags commands. For example, regular ‘tags-search’ or
2028 ‘tags-query-replace’ commands may be used without disrupting the
2029 independent ‘,’ search sequence. However, as implemented, the _initial_
2030 ‘,’ command (or the ‘,’ command is used with a prefix) might also
2031 reinitialize the regular Emacs tags searching to the first tags file,
2032 this reinitialization might be considered spurious.
2034 The ‘M-,’ (‘po-mark-translatable’) command will mark the recently
2035 found string with the ‘_’ keyword. The ‘M-.’
2036 (‘po-select-mark-and-mark’) command will request that you type one
2037 keyword from the minibuffer and use that keyword for marking the string.
2038 Both commands will automatically create a new PO file untranslated entry
2039 for the string being marked, and make it the current entry (making it
2040 easy for you to immediately proceed to its translation, if you feel like
2041 doing it right away). It is possible that the modifications made to the
2042 program source by ‘M-,’ or ‘M-.’ render some source line longer than 80
2043 columns, forcing you to break and re-indent this line differently. You
2044 may use the ‘O’ command from PO mode, or any other window changing
2045 command from Emacs, to break out into the program source window, and do
2046 any needed adjustments. You will have to use some regular Emacs command
2047 to return the cursor to the PO file window, if you want command ‘,’ for
2048 the next string, say.
2050 The ‘M-.’ command has a few built-in speedups, so you do not have to
2051 explicitly type all keywords all the time. The first such speedup is
2052 that you are presented with a _preferred_ keyword, which you may accept
2053 by merely typing ‘<RET>’ at the prompt. The second speedup is that you
2054 may type any non-ambiguous prefix of the keyword you really mean, and
2055 the command will complete it automatically for you. This also means
2056 that PO mode has to _know_ all your possible keywords, and that it will
2057 not accept mistyped keywords.
2059 If you reply ‘?’ to the keyword request, the command gives a list of
2060 all known keywords, from which you may choose. When the command is
2061 prefixed by an argument (‘C-u M-.’), it inhibits updating any program
2062 source or PO file buffer, and does some simple keyword management
2063 instead. In this case, the command asks for a keyword, written in full,
2064 which becomes a new allowed keyword for later ‘M-.’ commands. Moreover,
2065 this new keyword automatically becomes the _preferred_ keyword for later
2066 commands. By typing an already known keyword in response to ‘C-u M-.’,
2067 one merely changes the _preferred_ keyword and does nothing more.
2069 All keywords known for ‘M-.’ are recognized by the ‘,’ command when
2070 scanning for strings, and strings already marked by any of those known
2071 keywords are automatically skipped. If many PO files are opened
2072 simultaneously, each one has its own independent set of known keywords.
2073 There is no provision in PO mode, currently, for deleting a known
2074 keyword, you have to quit the file (maybe using ‘q’) and reopen it
2075 afresh. When a PO file is newly brought up in an Emacs window, only
2076 ‘gettext’ and ‘_’ are known as keywords, and ‘gettext’ is preferred for
2077 the ‘M-.’ command. In fact, this is not useful to prefer ‘_’, as this
2078 one is already built in the ‘M-,’ command.
2081 File: gettext.info, Node: c-format Flag, Next: Special cases, Prev: Marking, Up: Sources
2083 4.6 Special Comments preceding Keywords
2084 =======================================
2086 In C programs strings are often used within calls of functions from
2087 the ‘printf’ family. The special thing about these format strings is
2088 that they can contain format specifiers introduced with ‘%’. Assume we
2091 printf (gettext ("String `%s' has %d characters\n"), s, strlen (s));
2093 A possible German translation for the above string might be:
2095 "%d Zeichen lang ist die Zeichenkette `%s'"
2097 A C programmer, even if he cannot speak German, will recognize that
2098 there is something wrong here. The order of the two format specifiers
2099 is changed but of course the arguments in the ‘printf’ don’t have. This
2100 will most probably lead to problems because now the length of the string
2101 is regarded as the address.
2103 To prevent errors at runtime caused by translations, the ‘msgfmt’
2104 tool can check statically whether the arguments in the original and the
2105 translation string match in type and number. If this is not the case
2106 and the ‘-c’ option has been passed to ‘msgfmt’, ‘msgfmt’ will give an
2107 error and refuse to produce a MO file. Thus consistent use of ‘msgfmt
2108 -c’ will catch the error, so that it cannot cause problems at runtime.
2110 If the word order in the above German translation would be correct one
2113 "%2$d Zeichen lang ist die Zeichenkette `%1$s'"
2115 The routines in ‘msgfmt’ know about this special notation.
2117 Because not all strings in a program will be format strings, it is
2118 not useful for ‘msgfmt’ to test all the strings in the ‘.po’ file. This
2119 might cause problems because the string might contain what looks like a
2120 format specifier, but the string is not used in ‘printf’.
2122 Therefore ‘xgettext’ adds a special tag to those messages it thinks
2123 might be a format string. There is no absolute rule for this, only a
2124 heuristic. In the ‘.po’ file the entry is marked using the ‘c-format’
2125 flag in the ‘#,’ comment line (*note PO Files::).
2127 The careful reader now might say that this again can cause problems.
2128 The heuristic might guess it wrong. This is true and therefore
2129 ‘xgettext’ knows about a special kind of comment which lets the
2130 programmer take over the decision. If in the same line as or the
2131 immediately preceding line to the ‘gettext’ keyword the ‘xgettext’
2132 program finds a comment containing the words ‘xgettext:c-format’, it
2133 will mark the string in any case with the ‘c-format’ flag. This kind of
2134 comment should be used when ‘xgettext’ does not recognize the string as
2135 a format string but it really is one and it should be tested. Please
2136 note that when the comment is in the same line as the ‘gettext’ keyword,
2137 it must be before the string to be translated.
2139 This situation happens quite often. The ‘printf’ function is often
2140 called with strings which do not contain a format specifier. Of course
2141 one would normally use ‘fputs’ but it does happen. In this case
2142 ‘xgettext’ does not recognize this as a format string but what happens
2143 if the translation introduces a valid format specifier? The ‘printf’
2144 function will try to access one of the parameters but none exists
2145 because the original code does not pass any parameters.
2147 ‘xgettext’ of course could make a wrong decision the other way round,
2148 i.e. a string marked as a format string actually is not a format string.
2149 In this case the ‘msgfmt’ might give too many warnings and would prevent
2150 translating the ‘.po’ file. The method to prevent this wrong decision
2151 is similar to the one used above, only the comment to use must contain
2152 the string ‘xgettext:no-c-format’.
2154 If a string is marked with ‘c-format’ and this is not correct the
2155 user can find out who is responsible for the decision. See *note
2156 xgettext Invocation:: to see how the ‘--debug’ option can be used for
2157 solving this problem.
2160 File: gettext.info, Node: Special cases, Next: Bug Report Address, Prev: c-format Flag, Up: Sources
2162 4.7 Special Cases of Translatable Strings
2163 =========================================
2165 The attentive reader might now point out that it is not always
2166 possible to mark translatable string with ‘gettext’ or something like
2167 this. Consider the following case:
2170 static const char *messages[] = {
2171 "some very meaningful message",
2177 = index > 1 ? "a default message" : messages[index];
2183 While it is no problem to mark the string ‘"a default message"’ it is
2184 not possible to mark the string initializers for ‘messages’. What is to
2185 be done? We have to fulfill two tasks. First we have to mark the
2186 strings so that the ‘xgettext’ program (*note xgettext Invocation::) can
2187 find them, and second we have to translate the string at runtime before
2190 The first task can be fulfilled by creating a new keyword, which
2191 names a no-op. For the second we have to mark all access points to a
2192 string from the array. So one solution can look like this:
2194 #define gettext_noop(String) String
2197 static const char *messages[] = {
2198 gettext_noop ("some very meaningful message"),
2199 gettext_noop ("and another one")
2204 = index > 1 ? gettext ("a default message") : gettext (messages[index]);
2210 Please convince yourself that the string which is written by ‘fputs’
2211 is translated in any case. How to get ‘xgettext’ know the additional
2212 keyword ‘gettext_noop’ is explained in *note xgettext Invocation::.
2214 The above is of course not the only solution. You could also come
2215 along with the following one:
2217 #define gettext_noop(String) String
2220 static const char *messages[] = {
2221 gettext_noop ("some very meaningful message"),
2222 gettext_noop ("and another one")
2227 = index > 1 ? gettext_noop ("a default message") : messages[index];
2229 fputs (gettext (string));
2233 But this has a drawback. The programmer has to take care that he
2234 uses ‘gettext_noop’ for the string ‘"a default message"’. A use of
2235 ‘gettext’ could have in rare cases unpredictable results.
2237 One advantage is that you need not make control flow analysis to make
2238 sure the output is really translated in any case. But this analysis is
2239 generally not very difficult. If it should be in any situation you can
2240 use this second method in this situation.
2243 File: gettext.info, Node: Bug Report Address, Next: Names, Prev: Special cases, Up: Sources
2245 4.8 Letting Users Report Translation Bugs
2246 =========================================
2248 Code sometimes has bugs, but translations sometimes have bugs too.
2249 The users need to be able to report them. Reporting translation bugs to
2250 the programmer or maintainer of a package is not very useful, since the
2251 maintainer must never change a translation, except on behalf of the
2252 translator. Hence the translation bugs must be reported to the
2255 Here is a way to organize this so that the maintainer does not need
2256 to forward translation bug reports, nor even keep a list of the
2257 addresses of the translators or their translation teams.
2259 Every program has a place where is shows the bug report address. For
2260 GNU programs, it is the code which handles the “–help” option, typically
2261 in a function called “usage”. In this place, instruct the translator to
2262 add her own bug reporting address. For example, if that code has a
2265 printf (_("Report bugs to <%s>.\n"), PACKAGE_BUGREPORT);
2267 you can add some translator instructions like this:
2269 /* TRANSLATORS: The placeholder indicates the bug-reporting address
2270 for this package. Please add _another line_ saying
2271 "Report translation bugs to <...>\n" with the address for translation
2272 bugs (typically your translation team's web or email address). */
2273 printf (_("Report bugs to <%s>.\n"), PACKAGE_BUGREPORT);
2275 These will be extracted by ‘xgettext’, leading to a .pot file that
2278 #. TRANSLATORS: The placeholder indicates the bug-reporting address
2279 #. for this package. Please add _another line_ saying
2280 #. "Report translation bugs to <...>\n" with the address for translation
2281 #. bugs (typically your translation team's web or email address).
2284 msgid "Report bugs to <%s>.\n"
2288 File: gettext.info, Node: Names, Next: Libraries, Prev: Bug Report Address, Up: Sources
2290 4.9 Marking Proper Names for Translation
2291 ========================================
2293 Should names of persons, cities, locations etc. be marked for
2294 translation or not? People who only know languages that can be written
2295 with Latin letters (English, Spanish, French, German, etc.) are tempted
2296 to say “no”, because names usually do not change when transported
2297 between these languages. However, in general when translating from one
2298 script to another, names are translated too, usually phonetically or by
2299 transliteration. For example, Russian or Greek names are converted to
2300 the Latin alphabet when being translated to English, and English or
2301 French names are converted to the Katakana script when being translated
2302 to Japanese. This is necessary because the speakers of the target
2303 language in general cannot read the script the name is originally
2306 As a programmer, you should therefore make sure that names are marked
2307 for translation, with a special comment telling the translators that it
2308 is a proper name and how to pronounce it. In its simple form, it looks
2311 printf (_("Written by %s.\n"),
2312 /* TRANSLATORS: This is a proper name. See the gettext
2313 manual, section Names. Note this is actually a non-ASCII
2314 name: The first name is (with Unicode escapes)
2315 "Fran\u00e7ois" or (with HTML entities) "François".
2316 Pronunciation is like "fraa-swa pee-nar". */
2317 _("Francois Pinard"));
2319 The GNU gnulib library offers a module ‘propername’
2320 (<http://www.gnu.org/software/gnulib/MODULES.html#module=propername>)
2321 which takes care to automatically append the original name, in
2322 parentheses, to the translated name. For names that cannot be written
2323 in ASCII, it also frees the translator from the task of entering the
2324 appropriate non-ASCII characters if no script change is needed. In this
2325 more comfortable form, it looks like this:
2327 printf (_("Written by %s and %s.\n"),
2328 proper_name ("Ulrich Drepper"),
2329 /* TRANSLATORS: This is a proper name. See the gettext
2330 manual, section Names. Note this is actually a non-ASCII
2331 name: The first name is (with Unicode escapes)
2332 "Fran\u00e7ois" or (with HTML entities) "François".
2333 Pronunciation is like "fraa-swa pee-nar". */
2334 proper_name_utf8 ("Francois Pinard", "Fran\303\247ois Pinard"));
2336 You can also write the original name directly in Unicode (rather than
2337 with Unicode escapes or HTML entities) and denote the pronunciation
2338 using the International Phonetic Alphabet (see
2339 <http://www.wikipedia.org/wiki/International_Phonetic_Alphabet>).
2341 As a translator, you should use some care when translating names,
2342 because it is frustrating if people see their names mutilated or
2345 If your language uses the Latin script, all you need to do is to
2346 reproduce the name as perfectly as you can within the usual character
2347 set of your language. In this particular case, this means to provide a
2348 translation containing the c-cedilla character. If your language uses a
2349 different script and the people speaking it don’t usually read Latin
2350 words, it means transliteration. If the programmer used the simple
2351 case, you should still give, in parentheses, the original writing of the
2352 name – for the sake of the people that do read the Latin script. If the
2353 programmer used the ‘propername’ module mentioned above, you don’t need
2354 to give the original writing of the name in parentheses, because the
2355 program will already do so. Here is an example, using Greek as the
2358 #. This is a proper name. See the gettext
2359 #. manual, section Names. Note this is actually a non-ASCII
2360 #. name: The first name is (with Unicode escapes)
2361 #. "Fran\u00e7ois" or (with HTML entities) "François".
2362 #. Pronunciation is like "fraa-swa pee-nar".
2363 msgid "Francois Pinard"
2364 msgstr "\phi\rho\alpha\sigma\omicron\alpha \pi\iota\nu\alpha\rho"
2365 " (Francois Pinard)"
2367 Because translation of names is such a sensitive domain, it is a good
2368 idea to test your translation before submitting it.
2371 File: gettext.info, Node: Libraries, Prev: Names, Up: Sources
2373 4.10 Preparing Library Sources
2374 ==============================
2376 When you are preparing a library, not a program, for the use of
2377 ‘gettext’, only a few details are different. Here we assume that the
2378 library has a translation domain and a POT file of its own. (If it uses
2379 the translation domain and POT file of the main program, then the
2380 previous sections apply without changes.)
2382 1. The library code doesn’t call ‘setlocale (LC_ALL, "")’. It’s the
2383 responsibility of the main program to set the locale. The
2384 library’s documentation should mention this fact, so that
2385 developers of programs using the library are aware of it.
2387 2. The library code doesn’t call ‘textdomain (PACKAGE)’, because it
2388 would interfere with the text domain set by the main program.
2390 3. The initialization code for a program was
2392 setlocale (LC_ALL, "");
2393 bindtextdomain (PACKAGE, LOCALEDIR);
2394 textdomain (PACKAGE);
2396 For a library it is reduced to
2398 bindtextdomain (PACKAGE, LOCALEDIR);
2400 If your library’s API doesn’t already have an initialization
2401 function, you need to create one, containing at least the
2402 ‘bindtextdomain’ invocation. However, you usually don’t need to
2403 export and document this initialization function: It is sufficient
2404 that all entry points of the library call the initialization
2405 function if it hasn’t been called before. The typical idiom used
2406 to achieve this is a static boolean variable that indicates whether
2407 the initialization function has been called. Like this:
2409 static bool libfoo_initialized;
2412 libfoo_initialize (void)
2414 bindtextdomain (PACKAGE, LOCALEDIR);
2415 libfoo_initialized = true;
2418 /* This function is part of the exported API. */
2422 /* Must ensure the initialization is performed. */
2423 if (!libfoo_initialized)
2424 libfoo_initialize ();
2428 /* This function is part of the exported API. The argument must be
2429 non-NULL and have been created through create_foo(). */
2431 foo_refcount (struct foo *argument)
2433 /* No need to invoke the initialization function here, because
2434 create_foo() must already have been called before. */
2438 4. The usual declaration of the ‘_’ macro in each source file was
2440 #include <libintl.h>
2441 #define _(String) gettext (String)
2443 for a program. For a library, which has its own translation
2444 domain, it reads like this:
2446 #include <libintl.h>
2447 #define _(String) dgettext (PACKAGE, String)
2449 In other words, ‘dgettext’ is used instead of ‘gettext’.
2450 Similarly, the ‘dngettext’ function should be used in place of the
2451 ‘ngettext’ function.
2454 File: gettext.info, Node: Template, Next: Creating, Prev: Sources, Up: Top
2456 5 Making the PO Template File
2457 *****************************
2459 After preparing the sources, the programmer creates a PO template
2460 file. This section explains how to use ‘xgettext’ for this purpose.
2462 ‘xgettext’ creates a file named ‘DOMAINNAME.po’. You should then
2463 rename it to ‘DOMAINNAME.pot’. (Why doesn’t ‘xgettext’ create it under
2464 the name ‘DOMAINNAME.pot’ right away? The answer is: for historical
2465 reasons. When ‘xgettext’ was specified, the distinction between a PO
2466 file and PO file template was fuzzy, and the suffix ‘.pot’ wasn’t in use
2471 * xgettext Invocation:: Invoking the ‘xgettext’ Program
2474 File: gettext.info, Node: xgettext Invocation, Prev: Template, Up: Template
2476 5.1 Invoking the ‘xgettext’ Program
2477 ===================================
2479 xgettext [OPTION] [INPUTFILE] …
2481 The ‘xgettext’ program extracts translatable strings from given input
2484 5.1.1 Input file location
2485 -------------------------
2492 Read the names of the input files from FILE instead of getting them
2493 from the command line.
2496 ‘--directory=DIRECTORY’
2497 Add DIRECTORY to the list of directories. Source files are
2498 searched relative to this list of directories. The resulting ‘.po’
2499 file will be written relative to the current directory, though.
2501 If INPUTFILE is ‘-’, standard input is read.
2503 5.1.2 Output file location
2504 --------------------------
2507 ‘--default-domain=NAME’
2508 Use ‘NAME.po’ for output (instead of ‘messages.po’).
2512 Write output to specified file (instead of ‘NAME.po’ or
2517 Output files will be placed in directory DIR.
2519 If the output FILE is ‘-’ or ‘/dev/stdout’, the output is written to
2522 5.1.3 Choice of input file language
2523 -----------------------------------
2527 Specifies the language of the input files. The supported languages
2528 are ‘C’, ‘C++’, ‘ObjectiveC’, ‘PO’, ‘Shell’, ‘Python’, ‘Lisp’,
2529 ‘EmacsLisp’, ‘librep’, ‘Scheme’, ‘Smalltalk’, ‘Java’,
2530 ‘JavaProperties’, ‘C#’, ‘awk’, ‘YCP’, ‘Tcl’, ‘Perl’, ‘PHP’,
2531 ‘GCC-source’, ‘NXStringTable’, ‘RST’, ‘Glade’, ‘Lua’, ‘JavaScript’,
2532 ‘Vala’, ‘GSettings’, ‘Desktop’.
2536 This is a shorthand for ‘--language=C++’.
2538 By default the language is guessed depending on the input file name
2541 5.1.4 Input file interpretation
2542 -------------------------------
2545 Specifies the encoding of the input files. This option is needed
2546 only if some untranslated message strings or their corresponding
2547 comments contain non-ASCII characters. Note that Tcl and Glade
2548 input files are always assumed to be in UTF-8, regardless of this
2551 By default the input files are assumed to be in ASCII.
2553 5.1.5 Operation mode
2554 --------------------
2558 Join messages with existing file.
2561 ‘--exclude-file=FILE’
2562 Entries from FILE are not extracted. FILE should be a PO or POT
2566 ‘--add-comments[=TAG]’
2567 Place comment blocks starting with TAG and preceding keyword lines
2568 in the output file. Without a TAG, the option means to put _all_
2569 comment blocks preceding keyword lines in the output file.
2571 Note that comment blocks supposed to be extracted must be adjacent
2572 to keyword lines. For example, in the following C source code:
2574 /* This is the first comment. */
2577 /* This is the second comment: not extracted */
2582 /* This is the third comment. */
2585 The second comment line will not be extracted, because there is one
2586 blank line between the comment line and the keyword.
2589 Perform a syntax check on msgid and msgid_plural. The supported
2593 Prefer Unicode ellipsis character over ASCII ‘...’
2596 Prohibit whitespace before an ellipsis character
2599 Prefer Unicode quotation marks over ASCII ‘"'`’
2601 The option has an effect on all input files. To enable or disable
2602 checks for a certain string, you can mark it with an ‘xgettext:’
2603 special comment in the source file. For example, if you specify
2604 the ‘--check=space-ellipsis’ option, but want to suppress the check
2605 on a particular string, add the following comment:
2607 /* xgettext: no-space-ellipsis-check */
2608 gettext ("We really want a space before ellipsis here ...");
2610 The ‘xgettext:’ comment can be followed by flags separated with a
2611 comma. The possible flags are of the form ‘[no-]NAME-check’, where
2612 NAME is the name of a valid syntax check. If a flag is prefixed by
2613 ‘no-’, the meaning is negated.
2615 Some tests apply the checks to each sentence within the msgid,
2616 rather than the whole string. xgettext detects the end of sentence
2617 by performing a pattern match, which usually looks for a period
2618 followed by a certain number of spaces. The number is specified
2619 with the ‘--sentence-end’ option.
2621 ‘--sentence-end[=TYPE]’
2622 The supported values are:
2625 Expect at least one whitespace after a period
2628 Expect at least two whitespaces after a period
2630 5.1.6 Language specific options
2631 -------------------------------
2635 Extract all strings.
2637 This option has an effect with most languages, namely C, C++,
2638 ObjectiveC, Shell, Python, Lisp, EmacsLisp, librep, Java, C#, awk,
2639 Tcl, Perl, PHP, GCC-source, Glade, Lua, JavaScript, Vala,
2643 ‘--keyword[=KEYWORDSPEC]’
2644 Specify KEYWORDSPEC as an additional keyword to be looked for.
2645 Without a KEYWORDSPEC, the option means to not use default
2648 If KEYWORDSPEC is a C identifier ID, ‘xgettext’ looks for strings
2649 in the first argument of each call to the function or macro ID. If
2650 KEYWORDSPEC is of the form ‘ID:ARGNUM’, ‘xgettext’ looks for
2651 strings in the ARGNUMth argument of the call. If KEYWORDSPEC is of
2652 the form ‘ID:ARGNUM1,ARGNUM2’, ‘xgettext’ looks for strings in the
2653 ARGNUM1st argument and in the ARGNUM2nd argument of the call, and
2654 treats them as singular/plural variants for a message with plural
2655 handling. Also, if KEYWORDSPEC is of the form
2656 ‘ID:CONTEXTARGNUMc,ARGNUM’ or ‘ID:ARGNUM,CONTEXTARGNUMc’,
2657 ‘xgettext’ treats strings in the CONTEXTARGNUMth argument as a
2658 context specifier. And, as a special-purpose support for GNOME, if
2659 KEYWORDSPEC is of the form ‘ID:ARGNUMg’, ‘xgettext’ recognizes the
2660 ARGNUMth argument as a string with context, using the GNOME ‘glib’
2661 syntax ‘"msgctxt|msgid"’.
2662 Furthermore, if KEYWORDSPEC is of the form ‘ID:…,TOTALNUMARGSt’,
2663 ‘xgettext’ recognizes this argument specification only if the
2664 number of actual arguments is equal to TOTALNUMARGS. This is
2665 useful for disambiguating overloaded function calls in C++.
2666 Finally, if KEYWORDSPEC is of the form ‘ID:ARGNUM...,"XCOMMENT"’,
2667 ‘xgettext’, when extracting a message from the specified argument
2668 strings, adds an extracted comment XCOMMENT to the message. Note
2669 that when used through a normal shell command line, the
2670 double-quotes around the XCOMMENT need to be escaped.
2672 This option has an effect with most languages, namely C, C++,
2673 ObjectiveC, Shell, Python, Lisp, EmacsLisp, librep, Java, C#, awk,
2674 Tcl, Perl, PHP, GCC-source, Glade, Lua, JavaScript, Vala,
2677 The default keyword specifications, which are always looked for if
2678 not explicitly disabled, are language dependent. They are:
2680 • For C, C++, and GCC-source: ‘gettext’, ‘dgettext:2’,
2681 ‘dcgettext:2’, ‘ngettext:1,2’, ‘dngettext:2,3’,
2682 ‘dcngettext:2,3’, ‘gettext_noop’, and ‘pgettext:1c,2’,
2683 ‘dpgettext:2c,3’, ‘dcpgettext:2c,3’, ‘npgettext:1c,2,3’,
2684 ‘dnpgettext:2c,3,4’, ‘dcnpgettext:2c,3,4’.
2686 • For Objective C: Like for C, and also ‘NSLocalizedString’,
2687 ‘_’, ‘NSLocalizedStaticString’, ‘__’.
2689 • For Shell scripts: ‘gettext’, ‘ngettext:1,2’, ‘eval_gettext’,
2690 ‘eval_ngettext:1,2’.
2692 • For Python: ‘gettext’, ‘ugettext’, ‘dgettext:2’,
2693 ‘ngettext:1,2’, ‘ungettext:1,2’, ‘dngettext:2,3’, ‘_’.
2695 • For Lisp: ‘gettext’, ‘ngettext:1,2’, ‘gettext-noop’.
2697 • For EmacsLisp: ‘_’.
2701 • For Scheme: ‘gettext’, ‘ngettext:1,2’, ‘gettext-noop’.
2703 • For Java: ‘GettextResource.gettext:2’,
2704 ‘GettextResource.ngettext:2,3’,
2705 ‘GettextResource.pgettext:2c,3’,
2706 ‘GettextResource.npgettext:2c,3,4’, ‘gettext’, ‘ngettext:1,2’,
2707 ‘pgettext:1c,2’, ‘npgettext:1c,2,3’, ‘getString’.
2709 • For C#: ‘GetString’, ‘GetPluralString:1,2’,
2710 ‘GetParticularString:1c,2’,
2711 ‘GetParticularPluralString:1c,2,3’.
2713 • For awk: ‘dcgettext’, ‘dcngettext:1,2’.
2715 • For Tcl: ‘::msgcat::mc’.
2717 • For Perl: ‘gettext’, ‘%gettext’, ‘$gettext’, ‘dgettext:2’,
2718 ‘dcgettext:2’, ‘ngettext:1,2’, ‘dngettext:2,3’,
2719 ‘dcngettext:2,3’, ‘gettext_noop’.
2721 • For PHP: ‘_’, ‘gettext’, ‘dgettext:2’, ‘dcgettext:2’,
2722 ‘ngettext:1,2’, ‘dngettext:2,3’, ‘dcngettext:2,3’.
2724 • For Glade 1: ‘label’, ‘title’, ‘text’, ‘format’, ‘copyright’,
2725 ‘comments’, ‘preview_text’, ‘tooltip’.
2727 • For Lua: ‘_’, ‘gettext.gettext’, ‘gettext.dgettext:2’,
2728 ‘gettext.dcgettext:2’, ‘gettext.ngettext:1,2’,
2729 ‘gettext.dngettext:2,3’, ‘gettext.dcngettext:2,3’.
2731 • For JavaScript: ‘_’, ‘gettext’, ‘dgettext:2’, ‘dcgettext:2’,
2732 ‘ngettext:1,2’, ‘dngettext:2,3’, ‘pgettext:1c,2’,
2735 • For Vala: ‘_’, ‘Q_’, ‘N_’, ‘NC_’, ‘dgettext:2’, ‘dcgettext:2’,
2736 ‘ngettext:1,2’, ‘dngettext:2,3’, ‘dpgettext:2c,3’,
2739 • For Desktop: ‘Name’, ‘GenericName’, ‘Comment’, ‘Icon’,
2742 To disable the default keyword specifications, the option ‘-k’ or
2743 ‘--keyword’ or ‘--keyword=’, without a KEYWORDSPEC, can be used.
2745 ‘--flag=WORD:ARG:FLAG’
2746 Specifies additional flags for strings occurring as part of the
2747 ARGth argument of the function WORD. The possible flags are the
2748 possible format string indicators, such as ‘c-format’, and their
2749 negations, such as ‘no-c-format’, possibly prefixed with ‘pass-’.
2750 The meaning of ‘--flag=FUNCTION:ARG:LANG-format’ is that in
2751 language LANG, the specified FUNCTION expects as ARGth argument a
2752 format string. (For those of you familiar with GCC function
2753 attributes, ‘--flag=FUNCTION:ARG:c-format’ is roughly equivalent to
2754 the declaration ‘__attribute__ ((__format__ (__printf__, ARG,
2755 ...)))’ attached to FUNCTION in a C source file.) For example, if
2756 you use the ‘error’ function from GNU libc, you can specify its
2757 behaviour through ‘--flag=error:3:c-format’. The effect of this
2758 specification is that ‘xgettext’ will mark as format strings all
2759 ‘gettext’ invocations that occur as ARGth argument of FUNCTION.
2760 This is useful when such strings contain no format string
2761 directives: together with the checks done by ‘msgfmt -c’ it will
2762 ensure that translators cannot accidentally use format string
2763 directives that would lead to a crash at runtime.
2764 The meaning of ‘--flag=FUNCTION:ARG:pass-LANG-format’ is that in
2765 language LANG, if the FUNCTION call occurs in a position that must
2766 yield a format string, then its ARGth argument must yield a format
2767 string of the same type as well. (If you know GCC function
2768 attributes, the ‘--flag=FUNCTION:ARG:pass-c-format’ option is
2769 roughly equivalent to the declaration ‘__attribute__
2770 ((__format_arg__ (ARG)))’ attached to FUNCTION in a C source file.)
2771 For example, if you use the ‘_’ shortcut for the ‘gettext’
2772 function, you should use ‘--flag=_:1:pass-c-format’. The effect of
2773 this specification is that ‘xgettext’ will propagate a format
2774 string requirement for a ‘_("string")’ call to its first argument,
2775 the literal ‘"string"’, and thus mark it as a format string. This
2776 is useful when such strings contain no format string directives:
2777 together with the checks done by ‘msgfmt -c’ it will ensure that
2778 translators cannot accidentally use format string directives that
2779 would lead to a crash at runtime.
2780 This option has an effect with most languages, namely C, C++,
2781 ObjectiveC, Shell, Python, Lisp, EmacsLisp, librep, Scheme, Java,
2782 C#, awk, YCP, Tcl, Perl, PHP, GCC-source, Lua, JavaScript, Vala.
2786 Understand ANSI C trigraphs for input.
2787 This option has an effect only with the languages C, C++,
2791 Recognize Qt format strings.
2792 This option has an effect only with the language C++.
2795 Recognize KDE 4 format strings.
2796 This option has an effect only with the language C++.
2799 Recognize Boost format strings.
2800 This option has an effect only with the language C++.
2803 Use the flags ‘c-format’ and ‘possible-c-format’ to show who was
2804 responsible for marking a message as a format string. The latter
2805 form is used if the ‘xgettext’ program decided, the former form is
2806 used if the programmer prescribed it.
2808 By default only the ‘c-format’ form is used. The translator should
2809 not have to care about these details.
2811 This implementation of ‘xgettext’ is able to process a few awkward
2812 cases, like strings in preprocessor macros, ANSI concatenation of
2813 adjacent strings, and escaped end of lines for continued strings.
2815 5.1.7 Output details
2816 --------------------
2820 Specify whether or when to use colors and other text attributes.
2821 See *note The --color option:: for details.
2823 ‘--style=STYLE_FILE’
2824 Specify the CSS style rule file to use for ‘--color’. See *note
2825 The --style option:: for details.
2828 Always write an output file even if no message is defined.
2832 Write the .po file using indented style.
2835 Do not write ‘#: FILENAME:LINE’ lines. Note that using this option
2836 makes it harder for technically skilled translators to understand
2837 each message’s context.
2840 ‘--add-location=TYPE’
2841 Generate ‘#: FILENAME:LINE’ lines (default).
2843 The optional TYPE can be either ‘full’, ‘file’, or ‘never’. If it
2844 is not given or ‘full’, it generates the lines with both file name
2845 and line number. If it is ‘file’, the line number part is omitted.
2846 If it is ‘never’, it completely suppresses the lines (same as
2850 Write out a strict Uniforum conforming PO file. Note that this
2851 Uniforum format should be avoided because it doesn’t support the
2854 ‘--properties-output’
2855 Write out a Java ResourceBundle in Java ‘.properties’ syntax. Note
2856 that this file format doesn’t support plural forms and silently
2857 drops obsolete messages.
2859 ‘--stringtable-output’
2860 Write out a NeXTstep/GNUstep localized resource file in ‘.strings’
2861 syntax. Note that this file format doesn’t support plural forms.
2864 Use ITS rules defined in FILE. Note that this is only effective
2868 Write out comments recognized by itstool (<http://itstool.org>).
2869 Note that this is only effective with XML files.
2873 Set the output page width. Long strings in the output files will
2874 be split across multiple lines in order to ensure that each line’s
2875 width (= number of screen columns) is less or equal to the given
2879 Do not break long message lines. Message lines whose width exceeds
2880 the output page width will not be split into several lines. Only
2881 file reference lines which are wider than the output page width
2886 Generate sorted output. Note that using this option makes it much
2887 harder for the translator to understand each message’s context.
2891 Sort output by file location.
2894 Don’t write header with ‘msgid ""’ entry.
2896 This is useful for testing purposes because it eliminates a source
2897 of variance for generated ‘.gmo’ files. With ‘--omit-header’, two
2898 invocations of ‘xgettext’ on the same files with the same options
2899 at different times are guaranteed to produce the same results.
2901 Note that using this option will lead to an error if the resulting
2902 file would not entirely be in ASCII.
2904 ‘--copyright-holder=STRING’
2905 Set the copyright holder in the output. STRING should be the
2906 copyright holder of the surrounding package. (Note that the msgstr
2907 strings, extracted from the package’s sources, belong to the
2908 copyright holder of the package.) Translators are expected to
2909 transfer or disclaim the copyright for their translations, so that
2910 package maintainers can distribute them without legal risk. If
2911 STRING is empty, the output files are marked as being in the public
2912 domain; in this case, the translators are expected to disclaim
2913 their copyright, again so that package maintainers can distribute
2914 them without legal risk.
2916 The default value for STRING is the Free Software Foundation, Inc.,
2917 simply because ‘xgettext’ was first used in the GNU project.
2920 Omit FSF copyright in output. This option is equivalent to
2921 ‘--copyright-holder=''’. It can be useful for packages outside the
2922 GNU project that want their translations to be in the public
2925 ‘--package-name=PACKAGE’
2926 Set the package name in the header of the output.
2928 ‘--package-version=VERSION’
2929 Set the package version in the header of the output. This option
2930 has an effect only if the ‘--package-name’ option is also used.
2932 ‘--msgid-bugs-address=EMAIL@ADDRESS’
2933 Set the reporting address for msgid bugs. This is the email
2934 address or URL to which the translators shall report bugs in the
2935 untranslated strings:
2937 - Strings which are not entire sentences; see the maintainer
2938 guidelines in *note Preparing Strings::.
2939 - Strings which use unclear terms or require additional context
2941 - Strings which make invalid assumptions about notation of date,
2943 - Pluralisation problems.
2944 - Incorrect English spelling.
2945 - Incorrect formatting.
2947 It can be your email address, or a mailing list address where
2948 translators can write to without being subscribed, or the URL of a
2949 web page through which the translators can contact you.
2951 The default value is empty, which means that translators will be
2952 clueless! Don’t forget to specify this option.
2955 ‘--msgstr-prefix[=STRING]’
2956 Use STRING (or "" if not specified) as prefix for msgstr values.
2959 ‘--msgstr-suffix[=STRING]’
2960 Use STRING (or "" if not specified) as suffix for msgstr values.
2962 5.1.8 Informative output
2963 ------------------------
2967 Display this help and exit.
2971 Output version information and exit.
2974 File: gettext.info, Node: Creating, Next: Updating, Prev: Template, Up: Top
2976 6 Creating a New PO File
2977 ************************
2979 When starting a new translation, the translator creates a file called
2980 ‘LANG.po’, as a copy of the ‘PACKAGE.pot’ template file with
2981 modifications in the initial comments (at the beginning of the file) and
2982 in the header entry (the first entry, near the beginning of the file).
2984 The easiest way to do so is by use of the ‘msginit’ program. For
2987 $ cd PACKAGE-VERSION
2991 The alternative way is to do the copy and modifications by hand. To
2992 do so, the translator copies ‘PACKAGE.pot’ to ‘LANG.po’. Then she
2993 modifies the initial comments and the header entry of this file.
2997 * msginit Invocation:: Invoking the ‘msginit’ Program
2998 * Header Entry:: Filling in the Header Entry
3001 File: gettext.info, Node: msginit Invocation, Next: Header Entry, Prev: Creating, Up: Creating
3003 6.1 Invoking the ‘msginit’ Program
3004 ==================================
3008 The ‘msginit’ program creates a new PO file, initializing the meta
3009 information with values from the user’s environment.
3011 Here are more details. The following header fields of a PO file are
3012 automatically filled, when possible.
3014 ‘Project-Id-Version’
3015 The value is guessed from the ‘configure’ script or any other files
3016 in the current directory.
3019 The value is taken from the ‘PO-Creation-Data’ in the input POT
3020 file, or the current date is used.
3023 The value is taken from user’s password file entry and the mailer
3024 configuration files.
3026 ‘Language-Team, Language’
3027 These values are set according to the current locale and the
3028 predefined list of translation teams.
3030 ‘MIME-Version, Content-Type, Content-Transfer-Encoding’
3031 These values are set according to the content of the POT file and
3032 the current locale. If the POT file contains charset=UTF-8, it
3033 means that the POT file contains non-ASCII characters, and we keep
3034 the UTF-8 encoding. Otherwise, when the POT file is plain ASCII,
3035 we use the locale’s encoding.
3038 The value is first looked up from the embedded table.
3040 As an experimental feature, you can instruct ‘msginit’ to use the
3041 information from Unicode CLDR, by setting the ‘GETTEXTCLDRDIR’
3042 environment variable.
3044 6.1.1 Input file location
3045 -------------------------
3051 If no INPUTFILE is given, the current directory is searched for the
3052 POT file. If it is ‘-’, standard input is read.
3054 6.1.2 Output file location
3055 --------------------------
3058 ‘--output-file=FILE’
3059 Write output to specified PO file.
3061 If no output file is given, it depends on the ‘--locale’ option or
3062 the user’s locale setting. If it is ‘-’, the results are written to
3065 6.1.3 Input file syntax
3066 -----------------------
3069 ‘--properties-input’
3070 Assume the input file is a Java ResourceBundle in Java
3071 ‘.properties’ syntax, not in PO file syntax.
3073 ‘--stringtable-input’
3074 Assume the input file is a NeXTstep/GNUstep localized resource file
3075 in ‘.strings’ syntax, not in PO file syntax.
3077 6.1.4 Output details
3078 --------------------
3082 Set target locale. LL should be a language code, and CC should be
3083 a country code. The command ‘locale -a’ can be used to output a
3084 list of all installed locales. The default is the user’s locale
3088 Declares that the PO file will not have a human translator and is
3089 instead automatically generated.
3093 Specify whether or when to use colors and other text attributes.
3094 See *note The --color option:: for details.
3096 ‘--style=STYLE_FILE’
3097 Specify the CSS style rule file to use for ‘--color’. See *note
3098 The --style option:: for details.
3101 ‘--properties-output’
3102 Write out a Java ResourceBundle in Java ‘.properties’ syntax. Note
3103 that this file format doesn’t support plural forms and silently
3104 drops obsolete messages.
3106 ‘--stringtable-output’
3107 Write out a NeXTstep/GNUstep localized resource file in ‘.strings’
3108 syntax. Note that this file format doesn’t support plural forms.
3112 Set the output page width. Long strings in the output files will
3113 be split across multiple lines in order to ensure that each line’s
3114 width (= number of screen columns) is less or equal to the given
3118 Do not break long message lines. Message lines whose width exceeds
3119 the output page width will not be split into several lines. Only
3120 file reference lines which are wider than the output page width
3123 6.1.5 Informative output
3124 ------------------------
3128 Display this help and exit.
3132 Output version information and exit.
3135 File: gettext.info, Node: Header Entry, Prev: msginit Invocation, Up: Creating
3137 6.2 Filling in the Header Entry
3138 ===============================
3140 The initial comments "SOME DESCRIPTIVE TITLE", "YEAR" and "FIRST
3141 AUTHOR <EMAIL@ADDRESS>, YEAR" ought to be replaced by sensible
3142 information. This can be done in any text editor; if Emacs is used and
3143 it switched to PO mode automatically (because it has recognized the
3144 file’s suffix), you can disable it by typing ‘M-x fundamental-mode’.
3146 Modifying the header entry can already be done using PO mode: in
3147 Emacs, type ‘M-x po-mode RET’ and then ‘RET’ again to start editing the
3148 entry. You should fill in the following fields.
3151 This is the name and version of the package. Fill it in if it has
3152 not already been filled in by ‘xgettext’.
3154 Report-Msgid-Bugs-To
3155 This has already been filled in by ‘xgettext’. It contains an
3156 email address or URL where you can report bugs in the untranslated
3159 - Strings which are not entire sentences, see the maintainer
3160 guidelines in *note Preparing Strings::.
3161 - Strings which use unclear terms or require additional context
3163 - Strings which make invalid assumptions about notation of date,
3165 - Pluralisation problems.
3166 - Incorrect English spelling.
3167 - Incorrect formatting.
3170 This has already been filled in by ‘xgettext’.
3173 You don’t need to fill this in. It will be filled by the PO file
3174 editor when you save the file.
3177 Fill in your name and email address (without double quotes).
3180 Fill in the English name of the language, and the email address or
3181 homepage URL of the language team you are part of.
3183 Before starting a translation, it is a good idea to get in touch
3184 with your translation team, not only to make sure you don’t do
3185 duplicated work, but also to coordinate difficult linguistic
3188 In the Free Translation Project, each translation team has its own
3189 mailing list. The up-to-date list of teams can be found at the
3190 Free Translation Project’s homepage,
3191 <http://translationproject.org/>, in the "Teams" area.
3194 Fill in the language code of the language. This can be in one of
3197 - ‘LL’, an ISO 639 two-letter language code (lowercase). See
3198 *note Language Codes:: for the list of codes.
3200 - ‘LL_CC’, where ‘LL’ is an ISO 639 two-letter language code
3201 (lowercase) and ‘CC’ is an ISO 3166 two-letter country code
3202 (uppercase). The country code specification is not redundant:
3203 Some languages have dialects in different countries. For
3204 example, ‘de_AT’ is used for Austria, and ‘pt_BR’ for Brazil.
3205 The country code serves to distinguish the dialects. See
3206 *note Language Codes:: and *note Country Codes:: for the lists
3209 - ‘LL_CC@VARIANT’, where ‘LL’ is an ISO 639 two-letter language
3210 code (lowercase), ‘CC’ is an ISO 3166 two-letter country code
3211 (uppercase), and ‘VARIANT’ is a variant designator. The
3212 variant designator (lowercase) can be a script designator,
3213 such as ‘latin’ or ‘cyrillic’.
3215 The naming convention ‘LL_CC’ is also the way locales are named on
3216 systems based on GNU libc. But there are three important
3219 • In this PO file field, but not in locale names, ‘LL_CC’
3220 combinations denoting a language’s main dialect are
3221 abbreviated as ‘LL’. For example, ‘de’ is equivalent to
3222 ‘de_DE’ (German as spoken in Germany), and ‘pt’ to ‘pt_PT’
3223 (Portuguese as spoken in Portugal) in this context.
3225 • In this PO file field, suffixes like ‘.ENCODING’ are not used.
3227 • In this PO file field, variant designators that are not
3228 relevant to message translation, such as ‘@euro’, are not
3231 So, if your locale name is ‘de_DE.UTF-8’, the language
3232 specification in PO files is just ‘de’.
3235 Replace ‘CHARSET’ with the character encoding used for your
3236 language, in your locale, or UTF-8. This field is needed for
3237 correct operation of the ‘msgmerge’ and ‘msgfmt’ programs, as well
3238 as for users whose locale’s character encoding differs from yours
3239 (see *note Charset conversion::).
3241 You get the character encoding of your locale by running the shell
3242 command ‘locale charmap’. If the result is ‘C’ or
3243 ‘ANSI_X3.4-1968’, which is equivalent to ‘ASCII’ (= ‘US-ASCII’), it
3244 means that your locale is not correctly configured. In this case,
3245 ask your translation team which charset to use. ‘ASCII’ is not
3246 usable for any language except Latin.
3248 Because the PO files must be portable to operating systems with
3249 less advanced internationalization facilities, the character
3250 encodings that can be used are limited to those supported by both
3251 GNU ‘libc’ and GNU ‘libiconv’. These are: ‘ASCII’, ‘ISO-8859-1’,
3252 ‘ISO-8859-2’, ‘ISO-8859-3’, ‘ISO-8859-4’, ‘ISO-8859-5’,
3253 ‘ISO-8859-6’, ‘ISO-8859-7’, ‘ISO-8859-8’, ‘ISO-8859-9’,
3254 ‘ISO-8859-13’, ‘ISO-8859-14’, ‘ISO-8859-15’, ‘KOI8-R’, ‘KOI8-U’,
3255 ‘KOI8-T’, ‘CP850’, ‘CP866’, ‘CP874’, ‘CP932’, ‘CP949’, ‘CP950’,
3256 ‘CP1250’, ‘CP1251’, ‘CP1252’, ‘CP1253’, ‘CP1254’, ‘CP1255’,
3257 ‘CP1256’, ‘CP1257’, ‘GB2312’, ‘EUC-JP’, ‘EUC-KR’, ‘EUC-TW’, ‘BIG5’,
3258 ‘BIG5-HKSCS’, ‘GBK’, ‘GB18030’, ‘SHIFT_JIS’, ‘JOHAB’, ‘TIS-620’,
3259 ‘VISCII’, ‘GEORGIAN-PS’, ‘UTF-8’.
3261 In the GNU system, the following encodings are frequently used for
3262 the corresponding languages.
3264 • ‘ISO-8859-1’ for Afrikaans, Albanian, Basque, Breton, Catalan,
3265 Cornish, Danish, Dutch, English, Estonian, Faroese, Finnish,
3266 French, Galician, German, Greenlandic, Icelandic, Indonesian,
3267 Irish, Italian, Malay, Manx, Norwegian, Occitan, Portuguese,
3268 Spanish, Swedish, Tagalog, Uzbek, Walloon,
3269 • ‘ISO-8859-2’ for Bosnian, Croatian, Czech, Hungarian, Polish,
3270 Romanian, Serbian, Slovak, Slovenian,
3271 • ‘ISO-8859-3’ for Maltese,
3272 • ‘ISO-8859-5’ for Macedonian, Serbian,
3273 • ‘ISO-8859-6’ for Arabic,
3274 • ‘ISO-8859-7’ for Greek,
3275 • ‘ISO-8859-8’ for Hebrew,
3276 • ‘ISO-8859-9’ for Turkish,
3277 • ‘ISO-8859-13’ for Latvian, Lithuanian, Maori,
3278 • ‘ISO-8859-14’ for Welsh,
3279 • ‘ISO-8859-15’ for Basque, Catalan, Dutch, English, Finnish,
3280 French, Galician, German, Irish, Italian, Portuguese, Spanish,
3282 • ‘KOI8-R’ for Russian,
3283 • ‘KOI8-U’ for Ukrainian,
3284 • ‘KOI8-T’ for Tajik,
3285 • ‘CP1251’ for Bulgarian, Belarusian,
3286 • ‘GB2312’, ‘GBK’, ‘GB18030’ for simplified writing of Chinese,
3287 • ‘BIG5’, ‘BIG5-HKSCS’ for traditional writing of Chinese,
3288 • ‘EUC-JP’ for Japanese,
3289 • ‘EUC-KR’ for Korean,
3290 • ‘TIS-620’ for Thai,
3291 • ‘GEORGIAN-PS’ for Georgian,
3292 • ‘UTF-8’ for any language, including those listed above.
3294 When single quote characters or double quote characters are used in
3295 translations for your language, and your locale’s encoding is one
3296 of the ISO-8859-* charsets, it is best if you create your PO files
3297 in UTF-8 encoding, instead of your locale’s encoding. This is
3298 because in UTF-8 the real quote characters can be represented
3299 (single quote characters: U+2018, U+2019, double quote characters:
3300 U+201C, U+201D), whereas none of ISO-8859-* charsets has them all.
3301 Users in UTF-8 locales will see the real quote characters, whereas
3302 users in ISO-8859-* locales will see the vertical apostrophe and
3303 the vertical double quote instead (because that’s what the
3304 character set conversion will transliterate them to).
3306 To enter such quote characters under X11, you can change your
3307 keyboard mapping using the ‘xmodmap’ program. The X11 names of the
3308 quote characters are "leftsinglequotemark", "rightsinglequotemark",
3309 "leftdoublequotemark", "rightdoublequotemark",
3310 "singlelowquotemark", "doublelowquotemark".
3312 Note that only recent versions of GNU Emacs support the UTF-8
3313 encoding: Emacs 20 with Mule-UCS, and Emacs 21. As of January
3314 2001, XEmacs doesn’t support the UTF-8 encoding.
3316 The character encoding name can be written in either upper or lower
3317 case. Usually upper case is preferred.
3319 Content-Transfer-Encoding
3323 This field is optional. It is only needed if the PO file has
3324 plural forms. You can find them by searching for the
3325 ‘msgid_plural’ keyword. The format of the plural forms field is
3326 described in *note Plural forms:: and *note Translating plural
3330 File: gettext.info, Node: Updating, Next: Editing, Prev: Creating, Up: Top
3332 7 Updating Existing PO Files
3333 ****************************
3337 * msgmerge Invocation:: Invoking the ‘msgmerge’ Program
3340 File: gettext.info, Node: msgmerge Invocation, Prev: Updating, Up: Updating
3342 7.1 Invoking the ‘msgmerge’ Program
3343 ===================================
3345 msgmerge [OPTION] DEF.po REF.pot
3347 The ‘msgmerge’ program merges two Uniforum style .po files together.
3348 The DEF.po file is an existing PO file with translations which will be
3349 taken over to the newly created file as long as they still match;
3350 comments will be preserved, but extracted comments and file positions
3351 will be discarded. The REF.pot file is the last created PO file with
3352 up-to-date source references but old translations, or a PO Template file
3353 (generally created by ‘xgettext’); any translations or comments in the
3354 file will be discarded, however dot comments and file positions will be
3355 preserved. Where an exact match cannot be found, fuzzy matching is used
3356 to produce better results.
3358 7.1.1 Input file location
3359 -------------------------
3362 Translations referring to old sources.
3365 References to the new sources.
3368 ‘--directory=DIRECTORY’
3369 Add DIRECTORY to the list of directories. Source files are
3370 searched relative to this list of directories. The resulting ‘.po’
3371 file will be written relative to the current directory, though.
3375 Specify an additional library of message translations. *Note
3376 Compendium::. This option may be specified more than once.
3378 7.1.2 Operation mode
3379 --------------------
3383 Update DEF.po. Do nothing if DEF.po is already up to date.
3385 7.1.3 Output file location
3386 --------------------------
3389 ‘--output-file=FILE’
3390 Write output to specified file.
3392 The results are written to standard output if no output file is
3393 specified or if it is ‘-’.
3395 7.1.4 Output file location in update mode
3396 -----------------------------------------
3398 The result is written back to DEF.po.
3401 Make a backup of DEF.po
3404 Override the usual backup suffix.
3406 The version control method may be selected via the ‘--backup’ option
3407 or through the ‘VERSION_CONTROL’ environment variable. Here are the
3412 Never make backups (even if ‘--backup’ is given).
3416 Make numbered backups.
3420 Make numbered backups if numbered backups for this file already
3421 exist, otherwise make simple backups.
3425 Always make simple backups.
3427 The backup suffix is ‘~’, unless set with ‘--suffix’ or the
3428 ‘SIMPLE_BACKUP_SUFFIX’ environment variable.
3430 7.1.5 Operation modifiers
3431 -------------------------
3435 Apply REF.pot to each of the domains in DEF.po.
3438 ‘--no-fuzzy-matching’
3439 Do not use fuzzy matching when an exact match is not found. This
3440 may speed up the operation considerably.
3443 Keep the previous msgids of translated messages, marked with ‘#|’,
3444 when adding the fuzzy marker to such messages.
3446 7.1.6 Input file syntax
3447 -----------------------
3450 ‘--properties-input’
3451 Assume the input files are Java ResourceBundles in Java
3452 ‘.properties’ syntax, not in PO file syntax.
3454 ‘--stringtable-input’
3455 Assume the input files are NeXTstep/GNUstep localized resource
3456 files in ‘.strings’ syntax, not in PO file syntax.
3458 7.1.7 Output details
3459 --------------------
3461 ‘--lang=CATALOGNAME’
3462 Specify the ‘Language’ field to be used in the header entry. See
3463 *note Header Entry:: for the meaning of this field. Note: The
3464 ‘Language-Team’ and ‘Plural-Forms’ fields are left unchanged. If
3465 this option is not specified, the ‘Language’ field is inferred, as
3466 best as possible, from the ‘Language-Team’ field.
3470 Specify whether or when to use colors and other text attributes.
3471 See *note The --color option:: for details.
3473 ‘--style=STYLE_FILE’
3474 Specify the CSS style rule file to use for ‘--color’. See *note
3475 The --style option:: for details.
3478 Always write an output file even if it contains no message.
3482 Write the .po file using indented style.
3485 Do not write ‘#: FILENAME:LINE’ lines.
3488 ‘--add-location=TYPE’
3489 Generate ‘#: FILENAME:LINE’ lines (default).
3491 The optional TYPE can be either ‘full’, ‘file’, or ‘never’. If it
3492 is not given or ‘full’, it generates the lines with both file name
3493 and line number. If it is ‘file’, the line number part is omitted.
3494 If it is ‘never’, it completely suppresses the lines (same as
3498 Write out a strict Uniforum conforming PO file. Note that this
3499 Uniforum format should be avoided because it doesn’t support the
3503 ‘--properties-output’
3504 Write out a Java ResourceBundle in Java ‘.properties’ syntax. Note
3505 that this file format doesn’t support plural forms and silently
3506 drops obsolete messages.
3508 ‘--stringtable-output’
3509 Write out a NeXTstep/GNUstep localized resource file in ‘.strings’
3510 syntax. Note that this file format doesn’t support plural forms.
3514 Set the output page width. Long strings in the output files will
3515 be split across multiple lines in order to ensure that each line’s
3516 width (= number of screen columns) is less or equal to the given
3520 Do not break long message lines. Message lines whose width exceeds
3521 the output page width will not be split into several lines. Only
3522 file reference lines which are wider than the output page width
3527 Generate sorted output. Note that using this option makes it much
3528 harder for the translator to understand each message’s context.
3532 Sort output by file location.
3534 7.1.8 Informative output
3535 ------------------------
3539 Display this help and exit.
3543 Output version information and exit.
3547 Increase verbosity level.
3552 Suppress progress indicators.
3555 File: gettext.info, Node: Editing, Next: Manipulating, Prev: Updating, Up: Top
3562 * KBabel:: KDE’s PO File Editor
3563 * Gtranslator:: GNOME’s PO File Editor
3564 * PO Mode:: Emacs’s PO File Editor
3565 * Compendium:: Using Translation Compendia
3568 File: gettext.info, Node: KBabel, Next: Gtranslator, Prev: Editing, Up: Editing
3570 8.1 KDE’s PO File Editor
3571 ========================
3574 File: gettext.info, Node: Gtranslator, Next: PO Mode, Prev: KBabel, Up: Editing
3576 8.2 GNOME’s PO File Editor
3577 ==========================
3580 File: gettext.info, Node: PO Mode, Next: Compendium, Prev: Gtranslator, Up: Editing
3582 8.3 Emacs’s PO File Editor
3583 ==========================
3585 For those of you being the lucky users of Emacs, PO mode has been
3586 specifically created for providing a cozy environment for editing or
3587 modifying PO files. While editing a PO file, PO mode allows for the
3588 easy browsing of auxiliary and compendium PO files, as well as for
3589 following references into the set of C program sources from which PO
3590 files have been derived. It has a few special features, among which are
3591 the interactive marking of program strings as translatable, and the
3592 validation of PO files with easy repositioning to PO file lines showing
3595 For the beginning, besides main PO mode commands (*note Main PO
3596 Commands::), you should know how to move between entries (*note Entry
3597 Positioning::), and how to handle untranslated entries (*note
3598 Untranslated Entries::).
3602 * Installation:: Completing GNU ‘gettext’ Installation
3603 * Main PO Commands:: Main Commands
3604 * Entry Positioning:: Entry Positioning
3605 * Normalizing:: Normalizing Strings in Entries
3606 * Translated Entries:: Translated Entries
3607 * Fuzzy Entries:: Fuzzy Entries
3608 * Untranslated Entries:: Untranslated Entries
3609 * Obsolete Entries:: Obsolete Entries
3610 * Modifying Translations:: Modifying Translations
3611 * Modifying Comments:: Modifying Comments
3612 * Subedit:: Mode for Editing Translations
3613 * C Sources Context:: C Sources Context
3614 * Auxiliary:: Consulting Auxiliary PO Files
3617 File: gettext.info, Node: Installation, Next: Main PO Commands, Prev: PO Mode, Up: PO Mode
3619 8.3.1 Completing GNU ‘gettext’ Installation
3620 -------------------------------------------
3622 Once you have received, unpacked, configured and compiled the GNU
3623 ‘gettext’ distribution, the ‘make install’ command puts in place the
3624 programs ‘xgettext’, ‘msgfmt’, ‘gettext’, and ‘msgmerge’, as well as
3625 their available message catalogs. To top off a comfortable
3626 installation, you might also want to make the PO mode available to your
3629 During the installation of the PO mode, you might want to modify your
3630 file ‘.emacs’, once and for all, so it contains a few lines looking
3633 (setq auto-mode-alist
3634 (cons '("\\.po\\'\\|\\.po\\." . po-mode) auto-mode-alist))
3635 (autoload 'po-mode "po-mode" "Major mode for translators to edit PO files" t)
3637 Later, whenever you edit some ‘.po’ file, or any file having the
3638 string ‘.po.’ within its name, Emacs loads ‘po-mode.elc’ (or
3639 ‘po-mode.el’) as needed, and automatically activates PO mode commands
3640 for the associated buffer. The string _PO_ appears in the mode line for
3641 any buffer for which PO mode is active. Many PO files may be active at
3642 once in a single Emacs session.
3644 If you are using Emacs version 20 or newer, and have already
3645 installed the appropriate international fonts on your system, you may
3646 also tell Emacs how to determine automatically the coding system of
3647 every PO file. This will often (but not always) cause the necessary
3648 fonts to be loaded and used for displaying the translations on your
3649 Emacs screen. For this to happen, add the lines:
3651 (modify-coding-system-alist 'file "\\.po\\'\\|\\.po\\."
3652 'po-find-file-coding-system)
3653 (autoload 'po-find-file-coding-system "po-mode")
3655 to your ‘.emacs’ file. If, with this, you still see boxes instead of
3656 international characters, try a different font set (via Shift Mouse
3660 File: gettext.info, Node: Main PO Commands, Next: Entry Positioning, Prev: Installation, Up: PO Mode
3662 8.3.2 Main PO mode Commands
3663 ---------------------------
3665 After setting up Emacs with something similar to the lines in *note
3666 Installation::, PO mode is activated for a window when Emacs finds a PO
3667 file in that window. This puts the window read-only and establishes a
3668 po-mode-map, which is a genuine Emacs mode, in a way that is not derived
3669 from text mode in any way. Functions found on ‘po-mode-hook’, if any,
3672 When PO mode is active in a window, the letters ‘PO’ appear in the
3673 mode line for that window. The mode line also displays how many entries
3674 of each kind are held in the PO file. For example, the string
3675 ‘132t+3f+10u+2o’ would tell the translator that the PO mode contains 132
3676 translated entries (*note Translated Entries::, 3 fuzzy entries (*note
3677 Fuzzy Entries::), 10 untranslated entries (*note Untranslated Entries::)
3678 and 2 obsolete entries (*note Obsolete Entries::). Zero-coefficients
3679 items are not shown. So, in this example, if the fuzzy entries were
3680 unfuzzied, the untranslated entries were translated and the obsolete
3681 entries were deleted, the mode line would merely display ‘145t’ for the
3684 The main PO commands are those which do not fit into the other
3685 categories of subsequent sections. These allow for quitting PO mode or
3686 for managing windows in special ways.
3689 Undo last modification to the PO file (‘po-undo’).
3692 Quit processing and save the PO file (‘po-quit’).
3695 Quit processing, possibly after confirmation
3696 (‘po-confirm-and-quit’).
3699 Temporary leave the PO file window (‘po-other-window’).
3703 Show help about PO mode (‘po-help’).
3706 Give some PO file statistics (‘po-statistics’).
3709 Batch validate the format of the whole PO file (‘po-validate’).
3711 The command ‘_’ (‘po-undo’) interfaces to the Emacs _undo_ facility.
3712 *Note Undoing Changes: (emacs)Undo. Each time ‘_’ is typed,
3713 modifications which the translator did to the PO file are undone a
3714 little more. For the purpose of undoing, each PO mode command is
3715 atomic. This is especially true for the ‘<RET>’ command: the whole
3716 edition made by using a single use of this command is undone at once,
3717 even if the edition itself implied several actions. However, while in
3718 the editing window, one can undo the edition work quite parsimoniously.
3720 The commands ‘Q’ (‘po-quit’) and ‘q’ (‘po-confirm-and-quit’) are used
3721 when the translator is done with the PO file. The former is a bit less
3722 verbose than the latter. If the file has been modified, it is saved to
3723 disk first. In both cases, and prior to all this, the commands check if
3724 any untranslated messages remain in the PO file and, if so, the
3725 translator is asked if she really wants to leave off working with this
3726 PO file. This is the preferred way of getting rid of an Emacs PO file
3727 buffer. Merely killing it through the usual command ‘C-x k’
3728 (‘kill-buffer’) is not the tidiest way to proceed.
3730 The command ‘0’ (‘po-other-window’) is another, softer way, to leave
3731 PO mode, temporarily. It just moves the cursor to some other Emacs
3732 window, and pops one if necessary. For example, if the translator just
3733 got PO mode to show some source context in some other, she might
3734 discover some apparent bug in the program source that needs correction.
3735 This command allows the translator to change sex, become a programmer,
3736 and have the cursor right into the window containing the program she (or
3737 rather _he_) wants to modify. By later getting the cursor back in the
3738 PO file window, or by asking Emacs to edit this file once again, PO mode
3741 The command ‘h’ (‘po-help’) displays a summary of all available PO
3742 mode commands. The translator should then type any character to resume
3743 normal PO mode operations. The command ‘?’ has the same effect as ‘h’.
3745 The command ‘=’ (‘po-statistics’) computes the total number of
3746 entries in the PO file, the ordinal of the current entry (counted from
3747 1), the number of untranslated entries, the number of obsolete entries,
3748 and displays all these numbers.
3750 The command ‘V’ (‘po-validate’) launches ‘msgfmt’ in checking and
3751 verbose mode over the current PO file. This command first offers to
3752 save the current PO file on disk. The ‘msgfmt’ tool, from GNU
3753 ‘gettext’, has the purpose of creating a MO file out of a PO file, and
3754 PO mode uses the features of this program for checking the overall
3755 format of a PO file, as well as all individual entries.
3757 The program ‘msgfmt’ runs asynchronously with Emacs, so the
3758 translator regains control immediately while her PO file is being
3759 studied. Error output is collected in the Emacs ‘*compilation*’ buffer,
3760 displayed in another window. The regular Emacs command ‘C-x`’
3761 (‘next-error’), as well as other usual compile commands, allow the
3762 translator to reposition quickly to the offending parts of the PO file.
3763 Once the cursor is on the line in error, the translator may decide on
3764 any PO mode action which would help correcting the error.
3767 File: gettext.info, Node: Entry Positioning, Next: Normalizing, Prev: Main PO Commands, Up: PO Mode
3769 8.3.3 Entry Positioning
3770 -----------------------
3772 The cursor in a PO file window is almost always part of an entry.
3773 The only exceptions are the special case when the cursor is after the
3774 last entry in the file, or when the PO file is empty. The entry where
3775 the cursor is found to be is said to be the current entry. Many PO mode
3776 commands operate on the current entry, so moving the cursor does more
3777 than allowing the translator to browse the PO file, this also selects on
3778 which entry commands operate.
3780 Some PO mode commands alter the position of the cursor in a
3781 specialized way. A few of those special purpose positioning are
3782 described here, the others are described in following sections (for a
3783 complete list try ‘C-h m’):
3786 Redisplay the current entry (‘po-current-entry’).
3789 Select the entry after the current one (‘po-next-entry’).
3792 Select the entry before the current one (‘po-previous-entry’).
3795 Select the first entry in the PO file (‘po-first-entry’).
3798 Select the last entry in the PO file (‘po-last-entry’).
3801 Record the location of the current entry for later use
3802 (‘po-push-location’).
3805 Return to a previously saved entry location (‘po-pop-location’).
3808 Exchange the current entry location with the previously saved one
3809 (‘po-exchange-location’).
3811 Any Emacs command able to reposition the cursor may be used to select
3812 the current entry in PO mode, including commands which move by
3813 characters, lines, paragraphs, screens or pages, and search commands.
3814 However, there is a kind of standard way to display the current entry in
3815 PO mode, which usual Emacs commands moving the cursor do not especially
3816 try to enforce. The command ‘.’ (‘po-current-entry’) has the sole
3817 purpose of redisplaying the current entry properly, after the current
3818 entry has been changed by means external to PO mode, or the Emacs screen
3821 It is yet to be decided if PO mode helps the translator, or otherwise
3822 irritates her, by forcing a rigid window disposition while she is doing
3823 her work. We originally had quite precise ideas about how windows
3824 should behave, but on the other hand, anyone used to Emacs is often
3825 happy to keep full control. Maybe a fixed window disposition might be
3826 offered as a PO mode option that the translator might activate or
3827 deactivate at will, so it could be offered on an experimental basis. If
3828 nobody feels a real need for using it, or a compulsion for writing it,
3829 we should drop this whole idea. The incentive for doing it should come
3830 from translators rather than programmers, as opinions from an
3831 experienced translator are surely more worth to me than opinions from
3832 programmers _thinking_ about how _others_ should do translation.
3834 The commands ‘n’ (‘po-next-entry’) and ‘p’ (‘po-previous-entry’) move
3835 the cursor the entry following, or preceding, the current one. If ‘n’
3836 is given while the cursor is on the last entry of the PO file, or if ‘p’
3837 is given while the cursor is on the first entry, no move is done.
3839 The commands ‘<’ (‘po-first-entry’) and ‘>’ (‘po-last-entry’) move
3840 the cursor to the first entry, or last entry, of the PO file. When the
3841 cursor is located past the last entry in a PO file, most PO mode
3842 commands will return an error saying ‘After last entry’. Moreover, the
3843 commands ‘<’ and ‘>’ have the special property of being able to work
3844 even when the cursor is not into some PO file entry, and one may use
3845 them for nicely correcting this situation. But even these commands will
3846 fail on a truly empty PO file. There are development plans for the PO
3847 mode for it to interactively fill an empty PO file from sources. *Note
3850 The translator may decide, before working at the translation of a
3851 particular entry, that she needs to browse the remainder of the PO file,
3852 maybe for finding the terminology or phraseology used in related
3853 entries. She can of course use the standard Emacs idioms for saving the
3854 current cursor location in some register, and use that register for
3855 getting back, or else, use the location ring.
3857 PO mode offers another approach, by which cursor locations may be
3858 saved onto a special stack. The command ‘m’ (‘po-push-location’) merely
3859 adds the location of current entry to the stack, pushing the already
3860 saved locations under the new one. The command ‘r’ (‘po-pop-location’)
3861 consumes the top stack element and repositions the cursor to the entry
3862 associated with that top element. This position is then lost, for the
3863 next ‘r’ will move the cursor to the previously saved location, and so
3864 on until no locations remain on the stack.
3866 If the translator wants the position to be kept on the location
3867 stack, maybe for taking a look at the entry associated with the top
3868 element, then go elsewhere with the intent of getting back later, she
3869 ought to use ‘m’ immediately after ‘r’.
3871 The command ‘x’ (‘po-exchange-location’) simultaneously repositions
3872 the cursor to the entry associated with the top element of the stack of
3873 saved locations, and replaces that top element with the location of the
3874 current entry before the move. Consequently, repeating the ‘x’ command
3875 toggles alternatively between two entries. For achieving this, the
3876 translator will position the cursor on the first entry, use ‘m’, then
3877 position to the second entry, and merely use ‘x’ for making the switch.
3880 File: gettext.info, Node: Normalizing, Next: Translated Entries, Prev: Entry Positioning, Up: PO Mode
3882 8.3.4 Normalizing Strings in Entries
3883 ------------------------------------
3885 There are many different ways for encoding a particular string into a
3886 PO file entry, because there are so many different ways to split and
3887 quote multi-line strings, and even, to represent special characters by
3888 backslashed escaped sequences. Some features of PO mode rely on the
3889 ability for PO mode to scan an already existing PO file for a particular
3890 string encoded into the ‘msgid’ field of some entry. Even if PO mode
3891 has internally all the built-in machinery for implementing this
3892 recognition easily, doing it fast is technically difficult. To
3893 facilitate a solution to this efficiency problem, we decided on a
3894 canonical representation for strings.
3896 A conventional representation of strings in a PO file is currently
3897 under discussion, and PO mode experiments with a canonical
3898 representation. Having both ‘xgettext’ and PO mode converging towards a
3899 uniform way of representing equivalent strings would be useful, as the
3900 internal normalization needed by PO mode could be automatically
3901 satisfied when using ‘xgettext’ from GNU ‘gettext’. An explicit PO mode
3902 normalization should then be only necessary for PO files imported from
3903 elsewhere, or for when the convention itself evolves.
3905 So, for achieving normalization of at least the strings of a given PO
3906 file needing a canonical representation, the following PO mode command
3910 Tidy the whole PO file by making entries more uniform.
3912 The special command ‘M-x po-normalize’, which has no associated keys,
3913 revises all entries, ensuring that strings of both original and
3914 translated entries use uniform internal quoting in the PO file. It also
3915 removes any crumb after the last entry. This command may be useful for
3916 PO files freshly imported from elsewhere, or if we ever improve on the
3917 canonical quoting format we use. This canonical format is not only
3918 meant for getting cleaner PO files, but also for greatly speeding up
3919 ‘msgid’ string lookup for some other PO mode commands.
3921 ‘M-x po-normalize’ presently makes three passes over the entries.
3922 The first implements heuristics for converting PO files for GNU
3923 ‘gettext’ 0.6 and earlier, in which ‘msgid’ and ‘msgstr’ fields were
3924 using K&R style C string syntax for multi-line strings. These
3925 heuristics may fail for comments not related to obsolete entries and
3926 ending with a backslash; they also depend on subsequent passes for
3927 finalizing the proper commenting of continued lines for obsolete
3928 entries. This first pass might disappear once all oldish PO files would
3929 have been adjusted. The second and third pass normalize all ‘msgid’ and
3930 ‘msgstr’ strings respectively. They also clean out those trailing
3931 backslashes used by XView’s ‘msgfmt’ for continued lines.
3933 Having such an explicit normalizing command allows for importing PO
3934 files from other sources, but also eases the evolution of the current
3935 convention, evolution driven mostly by aesthetic concerns, as of now.
3936 It is easy to make suggested adjustments at a later time, as the
3937 normalizing command and eventually, other GNU ‘gettext’ tools should
3938 greatly automate conformance. A description of the canonical string
3939 format is given below, for the particular benefit of those not having
3940 Emacs handy, and who would nevertheless want to handcraft their PO files
3943 Right now, in PO mode, strings are single line or multi-line. A
3944 string goes multi-line if and only if it has _embedded_ newlines, that
3945 is, if it matches ‘[^\n]\n+[^\n]’. So, we would have:
3947 msgstr "\n\nHello, world!\n\n\n"
3949 but, replacing the space by a newline, this becomes:
3959 We are deliberately using a caricatural example, here, to make the
3960 point clearer. Usually, multi-lines are not that bad looking. It is
3961 probable that we will implement the following suggestion. We might lump
3962 together all initial newlines into the empty string, and also all
3963 newlines introducing empty lines (that is, for N > 1, the N-1’th last
3964 newlines would go together on a separate string), so making the previous
3972 There are a few yet undecided little points about string
3973 normalization, to be documented in this manual, once these questions
3977 File: gettext.info, Node: Translated Entries, Next: Fuzzy Entries, Prev: Normalizing, Up: PO Mode
3979 8.3.5 Translated Entries
3980 ------------------------
3982 Each PO file entry for which the ‘msgstr’ field has been filled with
3983 a translation, and which is not marked as fuzzy (*note Fuzzy Entries::),
3984 is said to be a "translated" entry. Only translated entries will later
3985 be compiled by GNU ‘msgfmt’ and become usable in programs. Other entry
3986 types will be excluded; translation will not occur for them.
3988 Some commands are more specifically related to translated entry
3992 Find the next translated entry (‘po-next-translated-entry’).
3995 Find the previous translated entry
3996 (‘po-previous-translated-entry’).
3998 The commands ‘t’ (‘po-next-translated-entry’) and ‘T’
3999 (‘po-previous-translated-entry’) move forwards or backwards, chasing for
4000 an translated entry. If none is found, the search is extended and wraps
4001 around in the PO file buffer.
4003 Translated entries usually result from the translator having edited
4004 in a translation for them, *note Modifying Translations::. However, if
4005 the variable ‘po-auto-fuzzy-on-edit’ is not ‘nil’, the entry having
4006 received a new translation first becomes a fuzzy entry, which ought to
4007 be later unfuzzied before becoming an official, genuine translated
4008 entry. *Note Fuzzy Entries::.
4011 File: gettext.info, Node: Fuzzy Entries, Next: Untranslated Entries, Prev: Translated Entries, Up: PO Mode
4016 Each PO file entry may have a set of "attributes", which are
4017 qualities given a name and explicitly associated with the translation,
4018 using a special system comment. One of these attributes has the name
4019 ‘fuzzy’, and entries having this attribute are said to have a fuzzy
4020 translation. They are called fuzzy entries, for short.
4022 Fuzzy entries, even if they account for translated entries for most
4023 other purposes, usually call for revision by the translator. Those may
4024 be produced by applying the program ‘msgmerge’ to update an older
4025 translated PO files according to a new PO template file, when this tool
4026 hypothesises that some new ‘msgid’ has been modified only slightly out
4027 of an older one, and chooses to pair what it thinks to be the old
4028 translation for the new modified entry. The slight alteration in the
4029 original string (the ‘msgid’ string) should often be reflected in the
4030 translated string, and this requires the intervention of the translator.
4031 For this reason, ‘msgmerge’ might mark some entries as being fuzzy.
4033 Also, the translator may decide herself to mark an entry as fuzzy for
4034 her own convenience, when she wants to remember that the entry has to be
4035 later revisited. So, some commands are more specifically related to
4036 fuzzy entry processing.
4039 Find the next fuzzy entry (‘po-next-fuzzy-entry’).
4042 Find the previous fuzzy entry (‘po-previous-fuzzy-entry’).
4045 Remove the fuzzy attribute of the current entry (‘po-unfuzzy’).
4047 The commands ‘f’ (‘po-next-fuzzy-entry’) and ‘F’
4048 (‘po-previous-fuzzy-entry’) move forwards or backwards, chasing for a
4049 fuzzy entry. If none is found, the search is extended and wraps around
4050 in the PO file buffer.
4052 The command ‘<TAB>’ (‘po-unfuzzy’) removes the fuzzy attribute
4053 associated with an entry, usually leaving it translated. Further, if
4054 the variable ‘po-auto-select-on-unfuzzy’ has not the ‘nil’ value, the
4055 ‘<TAB>’ command will automatically chase for another interesting entry
4056 to work on. The initial value of ‘po-auto-select-on-unfuzzy’ is ‘nil’.
4058 The initial value of ‘po-auto-fuzzy-on-edit’ is ‘nil’. However, if
4059 the variable ‘po-auto-fuzzy-on-edit’ is set to ‘t’, any entry edited
4060 through the ‘<RET>’ command is marked fuzzy, as a way to ensure some
4061 kind of double check, later. In this case, the usual paradigm is that
4062 an entry becomes fuzzy (if not already) whenever the translator modifies
4063 it. If she is satisfied with the translation, she then uses ‘<TAB>’ to
4064 pick another entry to work on, clearing the fuzzy attribute on the same
4065 blow. If she is not satisfied yet, she merely uses ‘<SPC>’ to chase
4066 another entry, leaving the entry fuzzy.
4068 The translator may also use the ‘<DEL>’ command (‘po-fade-out-entry’)
4069 over any translated entry to mark it as being fuzzy, when she wants to
4070 easily leave a trace she wants to later return working at this entry.
4072 Also, when time comes to quit working on a PO file buffer with the
4073 ‘q’ command, the translator is asked for confirmation, if fuzzy string
4077 File: gettext.info, Node: Untranslated Entries, Next: Obsolete Entries, Prev: Fuzzy Entries, Up: PO Mode
4079 8.3.7 Untranslated Entries
4080 --------------------------
4082 When ‘xgettext’ originally creates a PO file, unless told otherwise,
4083 it initializes the ‘msgid’ field with the untranslated string, and
4084 leaves the ‘msgstr’ string to be empty. Such entries, having an empty
4085 translation, are said to be "untranslated" entries. Later, when the
4086 programmer slightly modifies some string right in the program, this
4087 change is later reflected in the PO file by the appearance of a new
4088 untranslated entry for the modified string.
4090 The usual commands moving from entry to entry consider untranslated
4091 entries on the same level as active entries. Untranslated entries are
4092 easily recognizable by the fact they end with ‘msgstr ""’.
4094 The work of the translator might be (quite naively) seen as the
4095 process of seeking for an untranslated entry, editing a translation for
4096 it, and repeating these actions until no untranslated entries remain.
4097 Some commands are more specifically related to untranslated entry
4101 Find the next untranslated entry (‘po-next-untranslated-entry’).
4104 Find the previous untranslated entry
4105 (‘po-previous-untransted-entry’).
4108 Turn the current entry into an untranslated one (‘po-kill-msgstr’).
4110 The commands ‘u’ (‘po-next-untranslated-entry’) and ‘U’
4111 (‘po-previous-untransted-entry’) move forwards or backwards, chasing for
4112 an untranslated entry. If none is found, the search is extended and
4113 wraps around in the PO file buffer.
4115 An entry can be turned back into an untranslated entry by merely
4116 emptying its translation, using the command ‘k’ (‘po-kill-msgstr’).
4117 *Note Modifying Translations::.
4119 Also, when time comes to quit working on a PO file buffer with the
4120 ‘q’ command, the translator is asked for confirmation, if some
4121 untranslated string still exists.
4124 File: gettext.info, Node: Obsolete Entries, Next: Modifying Translations, Prev: Untranslated Entries, Up: PO Mode
4126 8.3.8 Obsolete Entries
4127 ----------------------
4129 By "obsolete" PO file entries, we mean those entries which are
4130 commented out, usually by ‘msgmerge’ when it found that the translation
4131 is not needed anymore by the package being localized.
4133 The usual commands moving from entry to entry consider obsolete
4134 entries on the same level as active entries. Obsolete entries are
4135 easily recognizable by the fact that all their lines start with ‘#’,
4136 even those lines containing ‘msgid’ or ‘msgstr’.
4138 Commands exist for emptying the translation or reinitializing it to
4139 the original untranslated string. Commands interfacing with the kill
4140 ring may force some previously saved text into the translation. The
4141 user may interactively edit the translation. All these commands may
4142 apply to obsolete entries, carefully leaving the entry obsolete after
4145 Moreover, some commands are more specifically related to obsolete
4149 Find the next obsolete entry (‘po-next-obsolete-entry’).
4152 Find the previous obsolete entry (‘po-previous-obsolete-entry’).
4155 Make an active entry obsolete, or zap out an obsolete entry
4156 (‘po-fade-out-entry’).
4158 The commands ‘o’ (‘po-next-obsolete-entry’) and ‘O’
4159 (‘po-previous-obsolete-entry’) move forwards or backwards, chasing for
4160 an obsolete entry. If none is found, the search is extended and wraps
4161 around in the PO file buffer.
4163 PO mode does not provide ways for un-commenting an obsolete entry and
4164 making it active, because this would reintroduce an original
4165 untranslated string which does not correspond to any marked string in
4166 the program sources. This goes with the philosophy of never introducing
4167 useless ‘msgid’ values.
4169 However, it is possible to comment out an active entry, so making it
4170 obsolete. GNU ‘gettext’ utilities will later react to the disappearance
4171 of a translation by using the untranslated string. The command ‘<DEL>’
4172 (‘po-fade-out-entry’) pushes the current entry a little further towards
4173 annihilation. If the entry is active (it is a translated entry), then
4174 it is first made fuzzy. If it is already fuzzy, then the entry is
4175 merely commented out, with confirmation. If the entry is already
4176 obsolete, then it is completely deleted from the PO file. It is easy to
4177 recycle the translation so deleted into some other PO file entry,
4178 usually one which is untranslated. *Note Modifying Translations::.
4180 Here is a quite interesting problem to solve for later development of
4181 PO mode, for those nights you are not sleepy. The idea would be that PO
4182 mode might become bright enough, one of these days, to make good guesses
4183 at retrieving the most probable candidate, among all obsolete entries,
4184 for initializing the translation of a newly appeared string. I think it
4185 might be a quite hard problem to do this algorithmically, as we have to
4186 develop good and efficient measures of string similarity. Right now, PO
4187 mode completely lets the decision to the translator, when the time comes
4188 to find the adequate obsolete translation, it merely tries to provide
4189 handy tools for helping her to do so.
4192 File: gettext.info, Node: Modifying Translations, Next: Modifying Comments, Prev: Obsolete Entries, Up: PO Mode
4194 8.3.9 Modifying Translations
4195 ----------------------------
4197 PO mode prevents direct modification of the PO file, by the usual
4198 means Emacs gives for altering a buffer’s contents. By doing so, it
4199 pretends helping the translator to avoid little clerical errors about
4200 the overall file format, or the proper quoting of strings, as those
4201 errors would be easily made. Other kinds of errors are still possible,
4202 but some may be caught and diagnosed by the batch validation process,
4203 which the translator may always trigger by the ‘V’ command. For all
4204 other errors, the translator has to rely on her own judgment, and also
4205 on the linguistic reports submitted to her by the users of the
4206 translated package, having the same mother tongue.
4208 When the time comes to create a translation, correct an error
4209 diagnosed mechanically or reported by a user, the translators have to
4210 resort to using the following commands for modifying the translations.
4213 Interactively edit the translation (‘po-edit-msgstr’).
4217 Reinitialize the translation with the original, untranslated string
4218 (‘po-msgid-to-msgstr’).
4221 Save the translation on the kill ring, and delete it
4225 Save the translation on the kill ring, without deleting it
4226 (‘po-kill-ring-save-msgstr’).
4229 Replace the translation, taking the new from the kill ring
4232 The command ‘<RET>’ (‘po-edit-msgstr’) opens a new Emacs window meant
4233 to edit in a new translation, or to modify an already existing
4234 translation. The new window contains a copy of the translation taken
4235 from the current PO file entry, all ready for edition, expunged of all
4236 quoting marks, fully modifiable and with the complete extent of Emacs
4237 modifying commands. When the translator is done with her modifications,
4238 she may use ‘C-c C-c’ to close the subedit window with the automatically
4239 requoted results, or ‘C-c C-k’ to abort her modifications. *Note
4240 Subedit::, for more information.
4242 The command ‘<LFD>’ (‘po-msgid-to-msgstr’) initializes, or
4243 reinitializes the translation with the original string. This command is
4244 normally used when the translator wants to redo a fresh translation of
4245 the original string, disregarding any previous work.
4247 It is possible to arrange so, whenever editing an untranslated entry,
4248 the ‘<LFD>’ command be automatically executed. If you set
4249 ‘po-auto-edit-with-msgid’ to ‘t’, the translation gets initialised with
4250 the original string, in case none exists already. The default value for
4251 ‘po-auto-edit-with-msgid’ is ‘nil’.
4253 In fact, whether it is best to start a translation with an empty
4254 string, or rather with a copy of the original string, is a matter of
4255 taste or habit. Sometimes, the source language and the target language
4256 are so different that is simply best to start writing on an empty page.
4257 At other times, the source and target languages are so close that it
4258 would be a waste to retype a number of words already being written in
4259 the original string. A translator may also like having the original
4260 string right under her eyes, as she will progressively overwrite the
4261 original text with the translation, even if this requires some extra
4262 editing work to get rid of the original.
4264 The command ‘k’ (‘po-kill-msgstr’) merely empties the translation
4265 string, so turning the entry into an untranslated one. But while doing
4266 so, its previous contents is put apart in a special place, known as the
4267 kill ring. The command ‘w’ (‘po-kill-ring-save-msgstr’) has also the
4268 effect of taking a copy of the translation onto the kill ring, but it
4269 otherwise leaves the entry alone, and does _not_ remove the translation
4270 from the entry. Both commands use exactly the Emacs kill ring, which is
4271 shared between buffers, and which is well known already to Emacs lovers.
4273 The translator may use ‘k’ or ‘w’ many times in the course of her
4274 work, as the kill ring may hold several saved translations. From the
4275 kill ring, strings may later be reinserted in various Emacs buffers. In
4276 particular, the kill ring may be used for moving translation strings
4277 between different entries of a single PO file buffer, or if the
4278 translator is handling many such buffers at once, even between PO files.
4280 To facilitate exchanges with buffers which are not in PO mode, the
4281 translation string put on the kill ring by the ‘k’ command is fully
4282 unquoted before being saved: external quotes are removed, multi-line
4283 strings are concatenated, and backslash escaped sequences are turned
4284 into their corresponding characters. In the special case of obsolete
4285 entries, the translation is also uncommented prior to saving.
4287 The command ‘y’ (‘po-yank-msgstr’) completely replaces the
4288 translation of the current entry by a string taken from the kill ring.
4289 Following Emacs terminology, we then say that the replacement string is
4290 "yanked" into the PO file buffer. *Note (emacs)Yanking::. The first
4291 time ‘y’ is used, the translation receives the value of the most recent
4292 addition to the kill ring. If ‘y’ is typed once again, immediately,
4293 without intervening keystrokes, the translation just inserted is taken
4294 away and replaced by the second most recent addition to the kill ring.
4295 By repeating ‘y’ many times in a row, the translator may travel along
4296 the kill ring for saved strings, until she finds the string she really
4299 When a string is yanked into a PO file entry, it is fully and
4300 automatically requoted for complying with the format PO files should
4301 have. Further, if the entry is obsolete, PO mode then appropriately
4302 push the inserted string inside comments. Once again, translators
4303 should not burden themselves with quoting considerations besides, of
4304 course, the necessity of the translated string itself respective to the
4307 Note that ‘k’ or ‘w’ are not the only commands pushing strings on the
4308 kill ring, as almost any PO mode command replacing translation strings
4309 (or the translator comments) automatically saves the old string on the
4310 kill ring. The main exceptions to this general rule are the yanking
4311 commands themselves.
4313 To better illustrate the operation of killing and yanking, let’s use
4314 an actual example, taken from a common situation. When the programmer
4315 slightly modifies some string right in the program, his change is later
4316 reflected in the PO file by the appearance of a new untranslated entry
4317 for the modified string, and the fact that the entry translating the
4318 original or unmodified string becomes obsolete. In many cases, the
4319 translator might spare herself some work by retrieving the unmodified
4320 translation from the obsolete entry, then initializing the untranslated
4321 entry ‘msgstr’ field with this retrieved translation. Once this done,
4322 the obsolete entry is not wanted anymore, and may be safely deleted.
4324 When the translator finds an untranslated entry and suspects that a
4325 slight variant of the translation exists, she immediately uses ‘m’ to
4326 mark the current entry location, then starts chasing obsolete entries
4327 with ‘o’, hoping to find some translation corresponding to the
4328 unmodified string. Once found, she uses the ‘<DEL>’ command for
4329 deleting the obsolete entry, knowing that ‘<DEL>’ also _kills_ the
4330 translation, that is, pushes the translation on the kill ring. Then,
4331 ‘r’ returns to the initial untranslated entry, and ‘y’ then _yanks_ the
4332 saved translation right into the ‘msgstr’ field. The translator is then
4333 free to use ‘<RET>’ for fine tuning the translation contents, and maybe
4334 to later use ‘u’, then ‘m’ again, for going on with the next
4335 untranslated string.
4337 When some sequence of keys has to be typed over and over again, the
4338 translator may find it useful to become better acquainted with the Emacs
4339 capability of learning these sequences and playing them back under
4340 request. *Note (emacs)Keyboard Macros::.
4343 File: gettext.info, Node: Modifying Comments, Next: Subedit, Prev: Modifying Translations, Up: PO Mode
4345 8.3.10 Modifying Comments
4346 -------------------------
4348 Any translation work done seriously will raise many linguistic
4349 difficulties, for which decisions have to be made, and the choices
4350 further documented. These documents may be saved within the PO file in
4351 form of translator comments, which the translator is free to create,
4352 delete, or modify at will. These comments may be useful to herself when
4353 she returns to this PO file after a while.
4355 Comments not having whitespace after the initial ‘#’, for example,
4356 those beginning with ‘#.’ or ‘#:’, are _not_ translator comments, they
4357 are exclusively created by other ‘gettext’ tools. So, the commands
4358 below will never alter such system added comments, they are not meant
4359 for the translator to modify. *Note PO Files::.
4361 The following commands are somewhat similar to those modifying
4362 translations, so the general indications given for those apply here.
4363 *Note Modifying Translations::.
4366 Interactively edit the translator comments (‘po-edit-comment’).
4369 Save the translator comments on the kill ring, and delete it
4370 (‘po-kill-comment’).
4373 Save the translator comments on the kill ring, without deleting it
4374 (‘po-kill-ring-save-comment’).
4377 Replace the translator comments, taking the new from the kill ring
4378 (‘po-yank-comment’).
4380 These commands parallel PO mode commands for modifying the
4381 translation strings, and behave much the same way as they do, except
4382 that they handle this part of PO file comments meant for translator
4383 usage, rather than the translation strings. So, if the descriptions
4384 given below are slightly succinct, it is because the full details have
4385 already been given. *Note Modifying Translations::.
4387 The command ‘#’ (‘po-edit-comment’) opens a new Emacs window
4388 containing a copy of the translator comments on the current PO file
4389 entry. If there are no such comments, PO mode understands that the
4390 translator wants to add a comment to the entry, and she is presented
4391 with an empty screen. Comment marks (‘#’) and the space following them
4392 are automatically removed before edition, and reinstated after. For
4393 translator comments pertaining to obsolete entries, the uncommenting and
4394 recommenting operations are done twice. Once in the editing window, the
4395 keys ‘C-c C-c’ allow the translator to tell she is finished with editing
4396 the comment. *Note Subedit::, for further details.
4398 Functions found on ‘po-subedit-mode-hook’, if any, are executed after
4399 the string has been inserted in the edit buffer.
4401 The command ‘K’ (‘po-kill-comment’) gets rid of all translator
4402 comments, while saving those comments on the kill ring. The command ‘W’
4403 (‘po-kill-ring-save-comment’) takes a copy of the translator comments on
4404 the kill ring, but leaves them undisturbed in the current entry. The
4405 command ‘Y’ (‘po-yank-comment’) completely replaces the translator
4406 comments by a string taken at the front of the kill ring. When this
4407 command is immediately repeated, the comments just inserted are
4408 withdrawn, and replaced by other strings taken along the kill ring.
4410 On the kill ring, all strings have the same nature. There is no
4411 distinction between _translation_ strings and _translator comments_
4412 strings. So, for example, let’s presume the translator has just
4413 finished editing a translation, and wants to create a new translator
4414 comment to document why the previous translation was not good, just to
4415 remember what was the problem. Foreseeing that she will do that in her
4416 documentation, the translator may want to quote the previous translation
4417 in her translator comments. To do so, she may initialize the translator
4418 comments with the previous translation, still at the head of the kill
4419 ring. Because editing already pushed the previous translation on the
4420 kill ring, she merely has to type ‘M-w’ prior to ‘#’, and the previous
4421 translation will be right there, all ready for being introduced by some
4424 On the other hand, presume there are some translator comments already
4425 and that the translator wants to add to those comments, instead of
4426 wholly replacing them. Then, she should edit the comment right away
4427 with ‘#’. Once inside the editing window, she can use the regular Emacs
4428 commands ‘C-y’ (‘yank’) and ‘M-y’ (‘yank-pop’) to get the previous
4429 translation where she likes.
4432 File: gettext.info, Node: Subedit, Next: C Sources Context, Prev: Modifying Comments, Up: PO Mode
4434 8.3.11 Details of Sub Edition
4435 -----------------------------
4437 The PO subedit minor mode has a few peculiarities worth being
4438 described in fuller detail. It installs a few commands over the usual
4439 editing set of Emacs, which are described below.
4442 Complete edition (‘po-subedit-exit’).
4445 Abort edition (‘po-subedit-abort’).
4448 Consult auxiliary PO files (‘po-subedit-cycle-auxiliary’).
4450 The window’s contents represents a translation for a given message,
4451 or a translator comment. The translator may modify this window to her
4452 heart’s content. Once this is done, the command ‘C-c C-c’
4453 (‘po-subedit-exit’) may be used to return the edited translation into
4454 the PO file, replacing the original translation, even if it moved out of
4455 sight or if buffers were switched.
4457 If the translator becomes unsatisfied with her translation or
4458 comment, to the extent she prefers keeping what was existent prior to
4459 the ‘<RET>’ or ‘#’ command, she may use the command ‘C-c C-k’
4460 (‘po-subedit-abort’) to merely get rid of edition, while preserving the
4461 original translation or comment. Another way would be for her to exit
4462 normally with ‘C-c C-c’, then type ‘U’ once for undoing the whole effect
4465 The command ‘C-c C-a’ (‘po-subedit-cycle-auxiliary’) allows for
4466 glancing through translations already achieved in other languages,
4467 directly while editing the current translation. This may be quite
4468 convenient when the translator is fluent at many languages, but of
4469 course, only makes sense when such completed auxiliary PO files are
4470 already available to her (*note Auxiliary::).
4472 Functions found on ‘po-subedit-mode-hook’, if any, are executed after
4473 the string has been inserted in the edit buffer.
4475 While editing her translation, the translator should pay attention to
4476 not inserting unwanted ‘<RET>’ (newline) characters at the end of the
4477 translated string if those are not meant to be there, or to removing
4478 such characters when they are required. Since these characters are not
4479 visible in the editing buffer, they are easily introduced by mistake.
4480 To help her, ‘<RET>’ automatically puts the character ‘<’ at the end of
4481 the string being edited, but this ‘<’ is not really part of the string.
4482 On exiting the editing window with ‘C-c C-c’, PO mode automatically
4483 removes such ‘<’ and all whitespace added after it. If the translator
4484 adds characters after the terminating ‘<’, it looses its delimiting
4485 property and integrally becomes part of the string. If she removes the
4486 delimiting ‘<’, then the edited string is taken _as is_, with all
4487 trailing newlines, even if invisible. Also, if the translated string
4488 ought to end itself with a genuine ‘<’, then the delimiting ‘<’ may not
4489 be removed; so the string should appear, in the editing window, as
4490 ending with two ‘<’ in a row.
4492 When a translation (or a comment) is being edited, the translator may
4493 move the cursor back into the PO file buffer and freely move to other
4494 entries, browsing at will. If, with an edition pending, the translator
4495 wanders in the PO file buffer, she may decide to start modifying another
4496 entry. Each entry being edited has its own subedit buffer. It is
4497 possible to simultaneously edit the translation _and_ the comment of a
4498 single entry, or to edit entries in different PO files, all at once.
4499 Typing ‘<RET>’ on a field already being edited merely resumes that
4500 particular edit. Yet, the translator should better be comfortable at
4501 handling many Emacs windows!
4503 Pending subedits may be completed or aborted in any order, regardless
4504 of how or when they were started. When many subedits are pending and
4505 the translator asks for quitting the PO file (with the ‘q’ command),
4506 subedits are automatically resumed one at a time, so she may decide for
4510 File: gettext.info, Node: C Sources Context, Next: Auxiliary, Prev: Subedit, Up: PO Mode
4512 8.3.12 C Sources Context
4513 ------------------------
4515 PO mode is particularly powerful when used with PO files created
4516 through GNU ‘gettext’ utilities, as those utilities insert special
4517 comments in the PO files they generate. Some of these special comments
4518 relate the PO file entry to exactly where the untranslated string
4519 appears in the program sources.
4521 When the translator gets to an untranslated entry, she is fairly
4522 often faced with an original string which is not as informative as it
4523 normally should be, being succinct, cryptic, or otherwise ambiguous.
4524 Before choosing how to translate the string, she needs to understand
4525 better what the string really means and how tight the translation has to
4526 be. Most of the time, when problems arise, the only way left to make
4527 her judgment is looking at the true program sources from where this
4528 string originated, searching for surrounding comments the programmer
4529 might have put in there, and looking around for helping clues of _any_
4532 Surely, when looking at program sources, the translator will receive
4533 more help if she is a fluent programmer. However, even if she is not
4534 versed in programming and feels a little lost in C code, the translator
4535 should not be shy at taking a look, once in a while. It is most
4536 probable that she will still be able to find some of the hints she
4537 needs. She will learn quickly to not feel uncomfortable in program
4538 code, paying more attention to programmer’s comments, variable and
4539 function names (if he dared choosing them well), and overall
4540 organization, than to the program code itself.
4542 The following commands are meant to help the translator at getting
4543 program source context for a PO file entry.
4546 Resume the display of a program source context, or cycle through
4547 them (‘po-cycle-source-reference’).
4550 Display of a program source context selected by menu
4551 (‘po-select-source-reference’).
4554 Add a directory to the search path for source files
4555 (‘po-consider-source-path’).
4558 Delete a directory from the search path for source files
4559 (‘po-ignore-source-path’).
4561 The commands ‘s’ (‘po-cycle-source-reference’) and ‘M-s’
4562 (‘po-select-source-reference’) both open another window displaying some
4563 source program file, and already positioned in such a way that it shows
4564 an actual use of the string to be translated. By doing so, the command
4565 gives source program context for the string. But if the entry has no
4566 source context references, or if all references are unresolved along the
4567 search path for program sources, then the command diagnoses this as an
4570 Even if ‘s’ (or ‘M-s’) opens a new window, the cursor stays in the PO
4571 file window. If the translator really wants to get into the program
4572 source window, she ought to do it explicitly, maybe by using command
4575 When ‘s’ is typed for the first time, or for a PO file entry which is
4576 different of the last one used for getting source context, then the
4577 command reacts by giving the first context available for this entry, if
4578 any. If some context has already been recently displayed for the
4579 current PO file entry, and the translator wandered off to do other
4580 things, typing ‘s’ again will merely resume, in another window, the
4581 context last displayed. In particular, if the translator moved the
4582 cursor away from the context in the source file, the command will bring
4583 the cursor back to the context. By using ‘s’ many times in a row, with
4584 no other commands intervening, PO mode will cycle to the next available
4585 contexts for this particular entry, getting back to the first context
4586 once the last has been shown.
4588 The command ‘M-s’ behaves differently. Instead of cycling through
4589 references, it lets the translator choose a particular reference among
4590 many, and displays that reference. It is best used with completion, if
4591 the translator types ‘<TAB>’ immediately after ‘M-s’, in response to the
4592 question, she will be offered a menu of all possible references, as a
4593 reminder of which are the acceptable answers. This command is useful
4594 only where there are really many contexts available for a single string
4597 Program source files are usually found relative to where the PO file
4598 stands. As a special provision, when this fails, the file is also
4599 looked for, but relative to the directory immediately above it. Those
4600 two cases take proper care of most PO files. However, it might happen
4601 that a PO file has been moved, or is edited in a different place than
4602 its normal location. When this happens, the translator should tell PO
4603 mode in which directory normally sits the genuine PO file. Many such
4604 directories may be specified, and all together, they constitute what is
4605 called the "search path" for program sources. The command ‘S’
4606 (‘po-consider-source-path’) is used to interactively enter a new
4607 directory at the front of the search path, and the command ‘M-S’
4608 (‘po-ignore-source-path’) is used to select, with completion, one of the
4609 directories she does not want anymore on the search path.
4612 File: gettext.info, Node: Auxiliary, Prev: C Sources Context, Up: PO Mode
4614 8.3.13 Consulting Auxiliary PO Files
4615 ------------------------------------
4617 PO mode is able to help the knowledgeable translator, being fluent in
4618 many languages, at taking advantage of translations already achieved in
4619 other languages she just happens to know. It provides these other
4620 language translations as additional context for her own work. Moreover,
4621 it has features to ease the production of translations for many
4622 languages at once, for translators preferring to work in this way.
4624 An "auxiliary" PO file is an existing PO file meant for the same
4625 package the translator is working on, but targeted to a different mother
4626 tongue language. Commands exist for declaring and handling auxiliary PO
4627 files, and also for showing contexts for the entry under work.
4629 Here are the auxiliary file commands available in PO mode.
4632 Seek auxiliary files for another translation for the same entry
4633 (‘po-cycle-auxiliary’).
4636 Switch to a particular auxiliary file (‘po-select-auxiliary’).
4639 Declare this PO file as an auxiliary file
4640 (‘po-consider-as-auxiliary’).
4643 Remove this PO file from the list of auxiliary files
4644 (‘po-ignore-as-auxiliary’).
4646 Command ‘A’ (‘po-consider-as-auxiliary’) adds the current PO file to
4647 the list of auxiliary files, while command ‘M-A’
4648 (‘po-ignore-as-auxiliary’ just removes it.
4650 The command ‘a’ (‘po-cycle-auxiliary’) seeks all auxiliary PO files,
4651 round-robin, searching for a translated entry in some other language
4652 having an ‘msgid’ field identical as the one for the current entry. The
4653 found PO file, if any, takes the place of the current PO file in the
4654 display (its window gets on top). Before doing so, the current PO file
4655 is also made into an auxiliary file, if not already. So, ‘a’ in this
4656 newly displayed PO file will seek another PO file, and so on, so
4657 repeating ‘a’ will eventually yield back the original PO file.
4659 The command ‘C-c C-a’ (‘po-select-auxiliary’) asks the translator for
4660 her choice of a particular auxiliary file, with completion, and then
4661 switches to that selected PO file. The command also checks if the
4662 selected file has an ‘msgid’ field identical as the one for the current
4663 entry, and if yes, this entry becomes current. Otherwise, the cursor of
4664 the selected file is left undisturbed.
4666 For all this to work fully, auxiliary PO files will have to be
4667 normalized, in that way that ‘msgid’ fields should be written _exactly_
4668 the same way. It is possible to write ‘msgid’ fields in various ways
4669 for representing the same string, different writing would break the
4670 proper behaviour of the auxiliary file commands of PO mode. This is not
4671 expected to be much a problem in practice, as most existing PO files
4672 have their ‘msgid’ entries written by the same GNU ‘gettext’ tools.
4674 However, PO files initially created by PO mode itself, while marking
4675 strings in source files, are normalised differently. So are PO files
4676 resulting of the ‘M-x normalize’ command. Until these discrepancies
4677 between PO mode and other GNU ‘gettext’ tools get fully resolved, the
4678 translator should stay aware of normalisation issues.
4681 File: gettext.info, Node: Compendium, Prev: PO Mode, Up: Editing
4683 8.4 Using Translation Compendia
4684 ===============================
4686 A "compendium" is a special PO file containing a set of translations
4687 recurring in many different packages. The translator can use gettext
4688 tools to build a new compendium, to add entries to her compendium, and
4689 to initialize untranslated entries, or to update already translated
4690 entries, from translations kept in the compendium.
4694 * Creating Compendia:: Merging translations for later use
4695 * Using Compendia:: Using older translations if they fit
4698 File: gettext.info, Node: Creating Compendia, Next: Using Compendia, Prev: Compendium, Up: Compendium
4700 8.4.1 Creating Compendia
4701 ------------------------
4703 Basically every PO file consisting of translated entries only can be
4704 declared as a valid compendium. Often the translator wants to have
4705 special compendia; let’s consider two cases: ‘concatenating PO files’
4706 and ‘extracting a message subset from a PO file’.
4708 8.4.1.1 Concatenate PO Files
4709 ............................
4711 To concatenate several valid PO files into one compendium file you
4712 can use ‘msgcomm’ or ‘msgcat’ (the latter preferred):
4714 msgcat -o compendium.po file1.po file2.po
4716 By default, ‘msgcat’ will accumulate divergent translations for the
4717 same string. Those occurrences will be marked as ‘fuzzy’ and highly
4718 visible decorated; calling ‘msgcat’ on ‘file1.po’:
4722 msgid "Report bugs to <%s>.\n"
4723 msgstr "Comunicar `bugs' a <%s>.\n"
4729 msgid "Report bugs to <%s>.\n"
4730 msgstr "Comunicar \"bugs\" a <%s>.\n"
4734 #: src/hello.c:200 src/bye.c:100
4736 msgid "Report bugs to <%s>.\n"
4738 "#-#-#-#-# file1.po #-#-#-#-#\n"
4739 "Comunicar `bugs' a <%s>.\n"
4740 "#-#-#-#-# file2.po #-#-#-#-#\n"
4741 "Comunicar \"bugs\" a <%s>.\n"
4743 The translator will have to resolve this “conflict” manually; she has to
4744 decide whether the first or the second version is appropriate (or
4745 provide a new translation), to delete the “marker lines”, and finally to
4746 remove the ‘fuzzy’ mark.
4748 If the translator knows in advance the first found translation of a
4749 message is always the best translation she can make use to the
4750 ‘--use-first’ switch:
4752 msgcat --use-first -o compendium.po file1.po file2.po
4754 A good compendium file must not contain ‘fuzzy’ or untranslated
4755 entries. If input files are “dirty” you must preprocess the input files
4756 or postprocess the result using ‘msgattrib --translated --no-fuzzy’.
4758 8.4.1.2 Extract a Message Subset from a PO File
4759 ...............................................
4761 Nobody wants to translate the same messages again and again; thus you
4762 may wish to have a compendium file containing ‘getopt.c’ messages.
4764 To extract a message subset (e.g., all ‘getopt.c’ messages) from an
4765 existing PO file into one compendium file you can use ‘msggrep’:
4767 msggrep --location src/getopt.c -o compendium.po file.po
4770 File: gettext.info, Node: Using Compendia, Prev: Creating Compendia, Up: Compendium
4772 8.4.2 Using Compendia
4773 ---------------------
4775 You can use a compendium file to initialize a translation from
4776 scratch or to update an already existing translation.
4778 8.4.2.1 Initialize a New Translation File
4779 .........................................
4781 Since a PO file with translations does not exist the translator can
4782 merely use ‘/dev/null’ to fake the “old” translation file.
4784 msgmerge --compendium compendium.po -o file.po /dev/null file.pot
4786 8.4.2.2 Update an Existing Translation File
4787 ...........................................
4789 Concatenate the compendium file(s) and the existing PO, merge the
4790 result with the POT file and remove the obsolete entries (optional, here
4791 done using ‘msgattrib’):
4793 msgcat --use-first -o update.po compendium1.po compendium2.po file.po
4794 msgmerge update.po file.pot | msgattrib --no-obsolete > file.po
4797 File: gettext.info, Node: Manipulating, Next: Binaries, Prev: Editing, Up: Top
4799 9 Manipulating PO Files
4800 ***********************
4802 Sometimes it is necessary to manipulate PO files in a way that is
4803 better performed automatically than by hand. GNU ‘gettext’ includes a
4804 complete set of tools for this purpose.
4806 When merging two packages into a single package, the resulting POT
4807 file will be the concatenation of the two packages’ POT files. Thus the
4808 maintainer must concatenate the two existing package translations into a
4809 single translation catalog, for each language. This is best performed
4810 using ‘msgcat’. It is then the translators’ duty to deal with any
4811 possible conflicts that arose during the merge.
4813 When a translator takes over the translation job from another
4814 translator, but she uses a different character encoding in her locale,
4815 she will convert the catalog to her character encoding. This is best
4816 done through the ‘msgconv’ program.
4818 When a maintainer takes a source file with tagged messages from
4819 another package, he should also take the existing translations for this
4820 source file (and not let the translators do the same job twice). One
4821 way to do this is through ‘msggrep’, another is to create a POT file for
4822 that source file and use ‘msgmerge’.
4824 When a translator wants to adjust some translation catalog for a
4825 special dialect or orthography — for example, German as written in
4826 Switzerland versus German as written in Germany — she needs to apply
4827 some text processing to every message in the catalog. The tool for
4828 doing this is ‘msgfilter’.
4830 Another use of ‘msgfilter’ is to produce approximately the POT file
4831 for which a given PO file was made. This can be done through a filter
4832 command like ‘msgfilter sed -e d | sed -e '/^# /d'’. Note that the
4833 original POT file may have had different comments and different plural
4834 message counts, that’s why it’s better to use the original POT file if
4837 When a translator wants to check her translations, for example
4838 according to orthography rules or using a non-interactive spell checker,
4839 she can do so using the ‘msgexec’ program.
4841 When third party tools create PO or POT files, sometimes duplicates
4842 cannot be avoided. But the GNU ‘gettext’ tools give an error when they
4843 encounter duplicate msgids in the same file and in the same domain. To
4844 merge duplicates, the ‘msguniq’ program can be used.
4846 ‘msgcomm’ is a more general tool for keeping or throwing away
4847 duplicates, occurring in different files.
4849 ‘msgcmp’ can be used to check whether a translation catalog is
4850 completely translated.
4852 ‘msgattrib’ can be used to select and extract only the fuzzy or
4853 untranslated messages of a translation catalog.
4855 ‘msgen’ is useful as a first step for preparing English translation
4856 catalogs. It copies each message’s msgid to its msgstr.
4858 Finally, for those applications where all these various programs are
4859 not sufficient, a library ‘libgettextpo’ is provided that can be used to
4860 write other specialized programs that process PO files.
4864 * msgcat Invocation:: Invoking the ‘msgcat’ Program
4865 * msgconv Invocation:: Invoking the ‘msgconv’ Program
4866 * msggrep Invocation:: Invoking the ‘msggrep’ Program
4867 * msgfilter Invocation:: Invoking the ‘msgfilter’ Program
4868 * msguniq Invocation:: Invoking the ‘msguniq’ Program
4869 * msgcomm Invocation:: Invoking the ‘msgcomm’ Program
4870 * msgcmp Invocation:: Invoking the ‘msgcmp’ Program
4871 * msgattrib Invocation:: Invoking the ‘msgattrib’ Program
4872 * msgen Invocation:: Invoking the ‘msgen’ Program
4873 * msgexec Invocation:: Invoking the ‘msgexec’ Program
4874 * Colorizing:: Highlighting parts of PO files
4875 * libgettextpo:: Writing your own programs that process PO files
4878 File: gettext.info, Node: msgcat Invocation, Next: msgconv Invocation, Prev: Manipulating, Up: Manipulating
4880 9.1 Invoking the ‘msgcat’ Program
4881 =================================
4883 msgcat [OPTION] [INPUTFILE]...
4885 The ‘msgcat’ program concatenates and merges the specified PO files.
4886 It finds messages which are common to two or more of the specified PO
4887 files. By using the ‘--more-than’ option, greater commonality may be
4888 requested before messages are printed. Conversely, the ‘--less-than’
4889 option may be used to specify less commonality before messages are
4890 printed (i.e. ‘--less-than=2’ will only print the unique messages).
4891 Translations, comments, extracted comments, and file positions will be
4892 cumulated, except that if ‘--use-first’ is specified, they will be taken
4893 from the first PO file to define them.
4895 9.1.1 Input file location
4896 -------------------------
4903 Read the names of the input files from FILE instead of getting them
4904 from the command line.
4907 ‘--directory=DIRECTORY’
4908 Add DIRECTORY to the list of directories. Source files are
4909 searched relative to this list of directories. The resulting ‘.po’
4910 file will be written relative to the current directory, though.
4912 If INPUTFILE is ‘-’, standard input is read.
4914 9.1.2 Output file location
4915 --------------------------
4918 ‘--output-file=FILE’
4919 Write output to specified file.
4921 The results are written to standard output if no output file is
4922 specified or if it is ‘-’.
4924 9.1.3 Message selection
4925 -----------------------
4928 ‘--less-than=NUMBER’
4929 Print messages with less than NUMBER definitions, defaults to
4930 infinite if not set.
4933 ‘--more-than=NUMBER’
4934 Print messages with more than NUMBER definitions, defaults to 0 if
4939 Shorthand for ‘--less-than=2’. Requests that only unique messages
4942 9.1.4 Input file syntax
4943 -----------------------
4946 ‘--properties-input’
4947 Assume the input files are Java ResourceBundles in Java
4948 ‘.properties’ syntax, not in PO file syntax.
4950 ‘--stringtable-input’
4951 Assume the input files are NeXTstep/GNUstep localized resource
4952 files in ‘.strings’ syntax, not in PO file syntax.
4954 9.1.5 Output details
4955 --------------------
4959 Specify encoding for output.
4962 Use first available translation for each message. Don’t merge
4963 several translations into one.
4965 ‘--lang=CATALOGNAME’
4966 Specify the ‘Language’ field to be used in the header entry. See
4967 *note Header Entry:: for the meaning of this field. Note: The
4968 ‘Language-Team’ and ‘Plural-Forms’ fields are left unchanged.
4972 Specify whether or when to use colors and other text attributes.
4973 See *note The --color option:: for details.
4975 ‘--style=STYLE_FILE’
4976 Specify the CSS style rule file to use for ‘--color’. See *note
4977 The --style option:: for details.
4980 Always write an output file even if it contains no message.
4984 Write the .po file using indented style.
4987 Do not write ‘#: FILENAME:LINE’ lines.
4990 ‘--add-location=TYPE’
4991 Generate ‘#: FILENAME:LINE’ lines (default).
4993 The optional TYPE can be either ‘full’, ‘file’, or ‘never’. If it
4994 is not given or ‘full’, it generates the lines with both file name
4995 and line number. If it is ‘file’, the line number part is omitted.
4996 If it is ‘never’, it completely suppresses the lines (same as
5000 Write out a strict Uniforum conforming PO file. Note that this
5001 Uniforum format should be avoided because it doesn’t support the
5005 ‘--properties-output’
5006 Write out a Java ResourceBundle in Java ‘.properties’ syntax. Note
5007 that this file format doesn’t support plural forms and silently
5008 drops obsolete messages.
5010 ‘--stringtable-output’
5011 Write out a NeXTstep/GNUstep localized resource file in ‘.strings’
5012 syntax. Note that this file format doesn’t support plural forms.
5016 Set the output page width. Long strings in the output files will
5017 be split across multiple lines in order to ensure that each line’s
5018 width (= number of screen columns) is less or equal to the given
5022 Do not break long message lines. Message lines whose width exceeds
5023 the output page width will not be split into several lines. Only
5024 file reference lines which are wider than the output page width
5029 Generate sorted output. Note that using this option makes it much
5030 harder for the translator to understand each message’s context.
5034 Sort output by file location.
5036 9.1.6 Informative output
5037 ------------------------
5041 Display this help and exit.
5045 Output version information and exit.
5048 File: gettext.info, Node: msgconv Invocation, Next: msggrep Invocation, Prev: msgcat Invocation, Up: Manipulating
5050 9.2 Invoking the ‘msgconv’ Program
5051 ==================================
5053 msgconv [OPTION] [INPUTFILE]
5055 The ‘msgconv’ program converts a translation catalog to a different
5058 9.2.1 Input file location
5059 -------------------------
5065 ‘--directory=DIRECTORY’
5066 Add DIRECTORY to the list of directories. Source files are
5067 searched relative to this list of directories. The resulting ‘.po’
5068 file will be written relative to the current directory, though.
5070 If no INPUTFILE is given or if it is ‘-’, standard input is read.
5072 9.2.2 Output file location
5073 --------------------------
5076 ‘--output-file=FILE’
5077 Write output to specified file.
5079 The results are written to standard output if no output file is
5080 specified or if it is ‘-’.
5082 9.2.3 Conversion target
5083 -----------------------
5087 Specify encoding for output.
5089 The default encoding is the current locale’s encoding.
5091 9.2.4 Input file syntax
5092 -----------------------
5095 ‘--properties-input’
5096 Assume the input file is a Java ResourceBundle in Java
5097 ‘.properties’ syntax, not in PO file syntax.
5099 ‘--stringtable-input’
5100 Assume the input file is a NeXTstep/GNUstep localized resource file
5101 in ‘.strings’ syntax, not in PO file syntax.
5103 9.2.5 Output details
5104 --------------------
5108 Specify whether or when to use colors and other text attributes.
5109 See *note The --color option:: for details.
5111 ‘--style=STYLE_FILE’
5112 Specify the CSS style rule file to use for ‘--color’. See *note
5113 The --style option:: for details.
5116 Always write an output file even if it contains no message.
5120 Write the .po file using indented style.
5123 Do not write ‘#: FILENAME:LINE’ lines.
5126 ‘--add-location=TYPE’
5127 Generate ‘#: FILENAME:LINE’ lines (default).
5129 The optional TYPE can be either ‘full’, ‘file’, or ‘never’. If it
5130 is not given or ‘full’, it generates the lines with both file name
5131 and line number. If it is ‘file’, the line number part is omitted.
5132 If it is ‘never’, it completely suppresses the lines (same as
5136 Write out a strict Uniforum conforming PO file. Note that this
5137 Uniforum format should be avoided because it doesn’t support the
5141 ‘--properties-output’
5142 Write out a Java ResourceBundle in Java ‘.properties’ syntax. Note
5143 that this file format doesn’t support plural forms and silently
5144 drops obsolete messages.
5146 ‘--stringtable-output’
5147 Write out a NeXTstep/GNUstep localized resource file in ‘.strings’
5148 syntax. Note that this file format doesn’t support plural forms.
5152 Set the output page width. Long strings in the output files will
5153 be split across multiple lines in order to ensure that each line’s
5154 width (= number of screen columns) is less or equal to the given
5158 Do not break long message lines. Message lines whose width exceeds
5159 the output page width will not be split into several lines. Only
5160 file reference lines which are wider than the output page width
5165 Generate sorted output. Note that using this option makes it much
5166 harder for the translator to understand each message’s context.
5170 Sort output by file location.
5172 9.2.6 Informative output
5173 ------------------------
5177 Display this help and exit.
5181 Output version information and exit.
5184 File: gettext.info, Node: msggrep Invocation, Next: msgfilter Invocation, Prev: msgconv Invocation, Up: Manipulating
5186 9.3 Invoking the ‘msggrep’ Program
5187 ==================================
5189 msggrep [OPTION] [INPUTFILE]
5191 The ‘msggrep’ program extracts all messages of a translation catalog
5192 that match a given pattern or belong to some given source files.
5194 9.3.1 Input file location
5195 -------------------------
5201 ‘--directory=DIRECTORY’
5202 Add DIRECTORY to the list of directories. Source files are
5203 searched relative to this list of directories. The resulting ‘.po’
5204 file will be written relative to the current directory, though.
5206 If no INPUTFILE is given or if it is ‘-’, standard input is read.
5208 9.3.2 Output file location
5209 --------------------------
5212 ‘--output-file=FILE’
5213 Write output to specified file.
5215 The results are written to standard output if no output file is
5216 specified or if it is ‘-’.
5218 9.3.3 Message selection
5219 -----------------------
5221 [-N SOURCEFILE]... [-M DOMAINNAME]...
5222 [-J MSGCTXT-PATTERN] [-K MSGID-PATTERN] [-T MSGSTR-PATTERN]
5223 [-C COMMENT-PATTERN]
5225 A message is selected if
5226 • it comes from one of the specified source files,
5227 • or if it comes from one of the specified domains,
5228 • or if ‘-J’ is given and its context (msgctxt) matches
5230 • or if ‘-K’ is given and its key (msgid or msgid_plural) matches
5232 • or if ‘-T’ is given and its translation (msgstr) matches
5234 • or if ‘-C’ is given and the translator’s comment matches
5237 When more than one selection criterion is specified, the set of
5238 selected messages is the union of the selected messages of each
5241 MSGCTXT-PATTERN or MSGID-PATTERN or MSGSTR-PATTERN syntax:
5242 [-E | -F] [-e PATTERN | -f FILE]...
5243 PATTERNs are basic regular expressions by default, or extended
5244 regular expressions if -E is given, or fixed strings if -F is given.
5247 ‘--location=SOURCEFILE’
5248 Select messages extracted from SOURCEFILE. SOURCEFILE can be
5249 either a literal file name or a wildcard pattern.
5252 ‘--domain=DOMAINNAME’
5253 Select messages belonging to domain DOMAINNAME.
5257 Start of patterns for the msgctxt.
5261 Start of patterns for the msgid.
5265 Start of patterns for the msgstr.
5269 Start of patterns for the translator’s comment.
5272 ‘--extracted-comment’
5273 Start of patterns for the extracted comments.
5277 Specify that PATTERN is an extended regular expression.
5281 Specify that PATTERN is a set of newline-separated strings.
5285 Use PATTERN as a regular expression.
5289 Obtain PATTERN from FILE.
5293 Ignore case distinctions.
5297 Output only the messages that do not match any selection criterion,
5298 instead of the messages that match a selection criterion.
5300 9.3.4 Input file syntax
5301 -----------------------
5304 ‘--properties-input’
5305 Assume the input file is a Java ResourceBundle in Java
5306 ‘.properties’ syntax, not in PO file syntax.
5308 ‘--stringtable-input’
5309 Assume the input file is a NeXTstep/GNUstep localized resource file
5310 in ‘.strings’ syntax, not in PO file syntax.
5312 9.3.5 Output details
5313 --------------------
5317 Specify whether or when to use colors and other text attributes.
5318 See *note The --color option:: for details.
5320 ‘--style=STYLE_FILE’
5321 Specify the CSS style rule file to use for ‘--color’. See *note
5322 The --style option:: for details.
5325 Always write an output file even if it contains no message.
5328 Write the .po file using indented style.
5331 Do not write ‘#: FILENAME:LINE’ lines.
5334 ‘--add-location=TYPE’
5335 Generate ‘#: FILENAME:LINE’ lines (default).
5337 The optional TYPE can be either ‘full’, ‘file’, or ‘never’. If it
5338 is not given or ‘full’, it generates the lines with both file name
5339 and line number. If it is ‘file’, the line number part is omitted.
5340 If it is ‘never’, it completely suppresses the lines (same as
5344 Write out a strict Uniforum conforming PO file. Note that this
5345 Uniforum format should be avoided because it doesn’t support the
5349 ‘--properties-output’
5350 Write out a Java ResourceBundle in Java ‘.properties’ syntax. Note
5351 that this file format doesn’t support plural forms and silently
5352 drops obsolete messages.
5354 ‘--stringtable-output’
5355 Write out a NeXTstep/GNUstep localized resource file in ‘.strings’
5356 syntax. Note that this file format doesn’t support plural forms.
5360 Set the output page width. Long strings in the output files will
5361 be split across multiple lines in order to ensure that each line’s
5362 width (= number of screen columns) is less or equal to the given
5366 Do not break long message lines. Message lines whose width exceeds
5367 the output page width will not be split into several lines. Only
5368 file reference lines which are wider than the output page width
5372 Generate sorted output. Note that using this option makes it much
5373 harder for the translator to understand each message’s context.
5376 Sort output by file location.
5378 9.3.6 Informative output
5379 ------------------------
5383 Display this help and exit.
5387 Output version information and exit.
5392 To extract the messages that come from the source files
5393 ‘gnulib-lib/error.c’ and ‘gnulib-lib/getopt.c’:
5395 msggrep -N gnulib-lib/error.c -N gnulib-lib/getopt.c input.po
5397 To extract the messages that contain the string “Please specify” in
5398 the original string:
5400 msggrep --msgid -F -e 'Please specify' input.po
5402 To extract the messages that have a context specifier of either
5403 “Menu>File” or “Menu>Edit” or a submenu of them:
5405 msggrep --msgctxt -E -e '^Menu>(File|Edit)' input.po
5407 To extract the messages whose translation contains one of the strings
5408 in the file ‘wordlist.txt’:
5410 msggrep --msgstr -F -f wordlist.txt input.po
5413 File: gettext.info, Node: msgfilter Invocation, Next: msguniq Invocation, Prev: msggrep Invocation, Up: Manipulating
5415 9.4 Invoking the ‘msgfilter’ Program
5416 ====================================
5418 msgfilter [OPTION] FILTER [FILTER-OPTION]
5420 The ‘msgfilter’ program applies a filter to all translations of a
5421 translation catalog.
5423 During each FILTER invocation, the environment variable
5424 ‘MSGFILTER_MSGID’ is bound to the message’s msgid, and the environment
5425 variable ‘MSGFILTER_LOCATION’ is bound to the location in the PO file of
5426 the message. If the message has a context, the environment variable
5427 ‘MSGFILTER_MSGCTXT’ is bound to the message’s msgctxt, otherwise it is
5428 unbound. If the message has a plural form, environment variable
5429 ‘MSGFILTER_MSGID_PLURAL’ is bound to the message’s msgid_plural and
5430 ‘MSGFILTER_PLURAL_FORM’ is bound to the order number of the plural
5431 actually processed (starting with 0), otherwise both are unbound. If
5432 the message has a previous msgid (added by ‘msgmerge’), environment
5433 variable ‘MSGFILTER_PREV_MSGCTXT’ is bound to the message’s previous
5434 msgctxt, ‘MSGFILTER_PREV_MSGID’ is bound to the previous msgid, and
5435 ‘MSGFILTER_PREV_MSGID_PLURAL’ is bound to the previous msgid_plural.
5437 9.4.1 Input file location
5438 -------------------------
5445 ‘--directory=DIRECTORY’
5446 Add DIRECTORY to the list of directories. Source files are
5447 searched relative to this list of directories. The resulting ‘.po’
5448 file will be written relative to the current directory, though.
5450 If no INPUTFILE is given or if it is ‘-’, standard input is read.
5452 9.4.2 Output file location
5453 --------------------------
5456 ‘--output-file=FILE’
5457 Write output to specified file.
5459 The results are written to standard output if no output file is
5460 specified or if it is ‘-’.
5465 The FILTER can be any program that reads a translation from standard
5466 input and writes a modified translation to standard output. A
5467 frequently used filter is ‘sed’. A few particular built-in filters are
5471 Add newline at the end of each input line and also strip the ending
5472 newline from the output line.
5474 Note: If the filter is not a built-in filter, you have to care about
5475 encodings: It is your responsibility to ensure that the FILTER can cope
5476 with input encoded in the translation catalog’s encoding. If the FILTER
5477 wants input in a particular encoding, you can in a first step convert
5478 the translation catalog to that encoding using the ‘msgconv’ program,
5479 before invoking ‘msgfilter’. If the FILTER wants input in the locale’s
5480 encoding, but you want to avoid the locale’s encoding, then you can
5481 first convert the translation catalog to UTF-8 using the ‘msgconv’
5482 program and then make ‘msgfilter’ work in an UTF-8 locale, by using the
5483 ‘LC_ALL’ environment variable.
5485 Note: Most translations in a translation catalog don’t end with a
5486 newline character. For this reason, unless the ‘--newline’ option is
5487 used, it is important that the FILTER recognizes its last input line
5488 even if it ends without a newline, and that it doesn’t add an undesired
5489 trailing newline at the end. The ‘sed’ program on some platforms is
5490 known to ignore the last line of input if it is not terminated with a
5491 newline. You can use GNU ‘sed’ instead; it does not have this
5494 9.4.4 Useful FILTER-OPTIONs when the FILTER is ‘sed’
5495 ----------------------------------------------------
5498 ‘--expression=SCRIPT’
5499 Add SCRIPT to the commands to be executed.
5503 Add the contents of SCRIPTFILE to the commands to be executed.
5508 Suppress automatic printing of pattern space.
5510 9.4.5 Built-in FILTERs
5511 ----------------------
5513 The filter ‘recode-sr-latin’ is recognized as a built-in filter. The
5514 command ‘recode-sr-latin’ converts Serbian text, written in the Cyrillic
5515 script, to the Latin script. The command ‘msgfilter recode-sr-latin’
5516 applies this conversion to the translations of a PO file. Thus, it can
5517 be used to convert an ‘sr.po’ file to an ‘sr@latin.po’ file.
5519 The filter ‘quot’ is recognized as a built-in filter. The command
5520 ‘msgfilter quot’ converts any quotations surrounded by a pair of ‘"’,
5523 The filter ‘boldquot’ is recognized as a built-in filter. The
5524 command ‘msgfilter boldquot’ converts any quotations surrounded by a
5525 pair of ‘"’, ‘'’, and ‘`’, also adding the VT100 escape sequences to the
5526 text to decorate it as bold.
5528 The use of built-in filters is not sensitive to the current locale’s
5529 encoding. Moreover, when used with a built-in filter, ‘msgfilter’ can
5530 automatically convert the message catalog to the UTF-8 encoding when
5533 9.4.6 Input file syntax
5534 -----------------------
5537 ‘--properties-input’
5538 Assume the input file is a Java ResourceBundle in Java
5539 ‘.properties’ syntax, not in PO file syntax.
5541 ‘--stringtable-input’
5542 Assume the input file is a NeXTstep/GNUstep localized resource file
5543 in ‘.strings’ syntax, not in PO file syntax.
5545 9.4.7 Output details
5546 --------------------
5550 Specify whether or when to use colors and other text attributes.
5551 See *note The --color option:: for details.
5553 ‘--style=STYLE_FILE’
5554 Specify the CSS style rule file to use for ‘--color’. See *note
5555 The --style option:: for details.
5558 Always write an output file even if it contains no message.
5561 Write the .po file using indented style.
5564 Keep the header entry, i.e. the message with ‘msgid ""’,
5565 unmodified, instead of filtering it. By default, the header entry
5566 is subject to filtering like any other message.
5569 Do not write ‘#: FILENAME:LINE’ lines.
5572 ‘--add-location=TYPE’
5573 Generate ‘#: FILENAME:LINE’ lines (default).
5575 The optional TYPE can be either ‘full’, ‘file’, or ‘never’. If it
5576 is not given or ‘full’, it generates the lines with both file name
5577 and line number. If it is ‘file’, the line number part is omitted.
5578 If it is ‘never’, it completely suppresses the lines (same as
5582 Write out a strict Uniforum conforming PO file. Note that this
5583 Uniforum format should be avoided because it doesn’t support the
5587 ‘--properties-output’
5588 Write out a Java ResourceBundle in Java ‘.properties’ syntax. Note
5589 that this file format doesn’t support plural forms and silently
5590 drops obsolete messages.
5592 ‘--stringtable-output’
5593 Write out a NeXTstep/GNUstep localized resource file in ‘.strings’
5594 syntax. Note that this file format doesn’t support plural forms.
5598 Set the output page width. Long strings in the output files will
5599 be split across multiple lines in order to ensure that each line’s
5600 width (= number of screen columns) is less or equal to the given
5604 Do not break long message lines. Message lines whose width exceeds
5605 the output page width will not be split into several lines. Only
5606 file reference lines which are wider than the output page width
5611 Generate sorted output. Note that using this option makes it much
5612 harder for the translator to understand each message’s context.
5616 Sort output by file location.
5618 9.4.8 Informative output
5619 ------------------------
5623 Display this help and exit.
5627 Output version information and exit.
5632 To convert German translations to Swiss orthography (in an UTF-8
5635 msgconv -t UTF-8 de.po | msgfilter sed -e 's/ß/ss/g'
5637 To convert Serbian translations in Cyrillic script to Latin script:
5639 msgfilter recode-sr-latin < sr.po
5642 File: gettext.info, Node: msguniq Invocation, Next: msgcomm Invocation, Prev: msgfilter Invocation, Up: Manipulating
5644 9.5 Invoking the ‘msguniq’ Program
5645 ==================================
5647 msguniq [OPTION] [INPUTFILE]
5649 The ‘msguniq’ program unifies duplicate translations in a translation
5650 catalog. It finds duplicate translations of the same message ID. Such
5651 duplicates are invalid input for other programs like ‘msgfmt’,
5652 ‘msgmerge’ or ‘msgcat’. By default, duplicates are merged together.
5653 When using the ‘--repeated’ option, only duplicates are output, and all
5654 other messages are discarded. Comments and extracted comments will be
5655 cumulated, except that if ‘--use-first’ is specified, they will be taken
5656 from the first translation. File positions will be cumulated. When
5657 using the ‘--unique’ option, duplicates are discarded.
5659 9.5.1 Input file location
5660 -------------------------
5666 ‘--directory=DIRECTORY’
5667 Add DIRECTORY to the list of directories. Source files are
5668 searched relative to this list of directories. The resulting ‘.po’
5669 file will be written relative to the current directory, though.
5671 If no INPUTFILE is given or if it is ‘-’, standard input is read.
5673 9.5.2 Output file location
5674 --------------------------
5677 ‘--output-file=FILE’
5678 Write output to specified file.
5680 The results are written to standard output if no output file is
5681 specified or if it is ‘-’.
5683 9.5.3 Message selection
5684 -----------------------
5688 Print only duplicates.
5692 Print only unique messages, discard duplicates.
5694 9.5.4 Input file syntax
5695 -----------------------
5698 ‘--properties-input’
5699 Assume the input file is a Java ResourceBundle in Java
5700 ‘.properties’ syntax, not in PO file syntax.
5702 ‘--stringtable-input’
5703 Assume the input file is a NeXTstep/GNUstep localized resource file
5704 in ‘.strings’ syntax, not in PO file syntax.
5706 9.5.5 Output details
5707 --------------------
5711 Specify encoding for output.
5714 Use first available translation for each message. Don’t merge
5715 several translations into one.
5719 Specify whether or when to use colors and other text attributes.
5720 See *note The --color option:: for details.
5722 ‘--style=STYLE_FILE’
5723 Specify the CSS style rule file to use for ‘--color’. See *note
5724 The --style option:: for details.
5727 Always write an output file even if it contains no message.
5731 Write the .po file using indented style.
5734 Do not write ‘#: FILENAME:LINE’ lines.
5737 ‘--add-location=TYPE’
5738 Generate ‘#: FILENAME:LINE’ lines (default).
5740 The optional TYPE can be either ‘full’, ‘file’, or ‘never’. If it
5741 is not given or ‘full’, it generates the lines with both file name
5742 and line number. If it is ‘file’, the line number part is omitted.
5743 If it is ‘never’, it completely suppresses the lines (same as
5747 Write out a strict Uniforum conforming PO file. Note that this
5748 Uniforum format should be avoided because it doesn’t support the
5752 ‘--properties-output’
5753 Write out a Java ResourceBundle in Java ‘.properties’ syntax. Note
5754 that this file format doesn’t support plural forms and silently
5755 drops obsolete messages.
5757 ‘--stringtable-output’
5758 Write out a NeXTstep/GNUstep localized resource file in ‘.strings’
5759 syntax. Note that this file format doesn’t support plural forms.
5763 Set the output page width. Long strings in the output files will
5764 be split across multiple lines in order to ensure that each line’s
5765 width (= number of screen columns) is less or equal to the given
5769 Do not break long message lines. Message lines whose width exceeds
5770 the output page width will not be split into several lines. Only
5771 file reference lines which are wider than the output page width
5776 Generate sorted output. Note that using this option makes it much
5777 harder for the translator to understand each message’s context.
5781 Sort output by file location.
5783 9.5.6 Informative output
5784 ------------------------
5788 Display this help and exit.
5792 Output version information and exit.
5795 File: gettext.info, Node: msgcomm Invocation, Next: msgcmp Invocation, Prev: msguniq Invocation, Up: Manipulating
5797 9.6 Invoking the ‘msgcomm’ Program
5798 ==================================
5800 msgcomm [OPTION] [INPUTFILE]...
5802 The ‘msgcomm’ program finds messages which are common to two or more
5803 of the specified PO files. By using the ‘--more-than’ option, greater
5804 commonality may be requested before messages are printed. Conversely,
5805 the ‘--less-than’ option may be used to specify less commonality before
5806 messages are printed (i.e. ‘--less-than=2’ will only print the unique
5807 messages). Translations, comments and extracted comments will be
5808 preserved, but only from the first PO file to define them. File
5809 positions from all PO files will be cumulated.
5811 9.6.1 Input file location
5812 -------------------------
5819 Read the names of the input files from FILE instead of getting them
5820 from the command line.
5823 ‘--directory=DIRECTORY’
5824 Add DIRECTORY to the list of directories. Source files are
5825 searched relative to this list of directories. The resulting ‘.po’
5826 file will be written relative to the current directory, though.
5828 If INPUTFILE is ‘-’, standard input is read.
5830 9.6.2 Output file location
5831 --------------------------
5834 ‘--output-file=FILE’
5835 Write output to specified file.
5837 The results are written to standard output if no output file is
5838 specified or if it is ‘-’.
5840 9.6.3 Message selection
5841 -----------------------
5844 ‘--less-than=NUMBER’
5845 Print messages with less than NUMBER definitions, defaults to
5846 infinite if not set.
5849 ‘--more-than=NUMBER’
5850 Print messages with more than NUMBER definitions, defaults to 1 if
5855 Shorthand for ‘--less-than=2’. Requests that only unique messages
5858 9.6.4 Input file syntax
5859 -----------------------
5862 ‘--properties-input’
5863 Assume the input files are Java ResourceBundles in Java
5864 ‘.properties’ syntax, not in PO file syntax.
5866 ‘--stringtable-input’
5867 Assume the input files are NeXTstep/GNUstep localized resource
5868 files in ‘.strings’ syntax, not in PO file syntax.
5870 9.6.5 Output details
5871 --------------------
5875 Specify whether or when to use colors and other text attributes.
5876 See *note The --color option:: for details.
5878 ‘--style=STYLE_FILE’
5879 Specify the CSS style rule file to use for ‘--color’. See *note
5880 The --style option:: for details.
5883 Always write an output file even if it contains no message.
5887 Write the .po file using indented style.
5890 Do not write ‘#: FILENAME:LINE’ lines.
5893 ‘--add-location=TYPE’
5894 Generate ‘#: FILENAME:LINE’ lines (default).
5896 The optional TYPE can be either ‘full’, ‘file’, or ‘never’. If it
5897 is not given or ‘full’, it generates the lines with both file name
5898 and line number. If it is ‘file’, the line number part is omitted.
5899 If it is ‘never’, it completely suppresses the lines (same as
5903 Write out a strict Uniforum conforming PO file. Note that this
5904 Uniforum format should be avoided because it doesn’t support the
5908 ‘--properties-output’
5909 Write out a Java ResourceBundle in Java ‘.properties’ syntax. Note
5910 that this file format doesn’t support plural forms and silently
5911 drops obsolete messages.
5913 ‘--stringtable-output’
5914 Write out a NeXTstep/GNUstep localized resource file in ‘.strings’
5915 syntax. Note that this file format doesn’t support plural forms.
5919 Set the output page width. Long strings in the output files will
5920 be split across multiple lines in order to ensure that each line’s
5921 width (= number of screen columns) is less or equal to the given
5925 Do not break long message lines. Message lines whose width exceeds
5926 the output page width will not be split into several lines. Only
5927 file reference lines which are wider than the output page width
5932 Generate sorted output. Note that using this option makes it much
5933 harder for the translator to understand each message’s context.
5937 Sort output by file location.
5940 Don’t write header with ‘msgid ""’ entry.
5942 9.6.6 Informative output
5943 ------------------------
5947 Display this help and exit.
5951 Output version information and exit.
5954 File: gettext.info, Node: msgcmp Invocation, Next: msgattrib Invocation, Prev: msgcomm Invocation, Up: Manipulating
5956 9.7 Invoking the ‘msgcmp’ Program
5957 =================================
5959 msgcmp [OPTION] DEF.po REF.pot
5961 The ‘msgcmp’ program compares two Uniforum style .po files to check
5962 that both contain the same set of msgid strings. The DEF.po file is an
5963 existing PO file with the translations. The REF.pot file is the last
5964 created PO file, or a PO Template file (generally created by
5965 ‘xgettext’). This is useful for checking that you have translated each
5966 and every message in your program. Where an exact match cannot be
5967 found, fuzzy matching is used to produce better diagnostics.
5969 9.7.1 Input file location
5970 -------------------------
5976 References to the sources.
5979 ‘--directory=DIRECTORY’
5980 Add DIRECTORY to the list of directories. Source files are
5981 searched relative to this list of directories.
5983 9.7.2 Operation modifiers
5984 -------------------------
5988 Apply REF.pot to each of the domains in DEF.po.
5991 ‘--no-fuzzy-matching’
5992 Do not use fuzzy matching when an exact match is not found. This
5993 may speed up the operation considerably.
5996 Consider fuzzy messages in the DEF.po file like translated
5997 messages. Note that using this option is usually wrong, because
5998 fuzzy messages are exactly those which have not been validated by a
6001 ‘--use-untranslated’
6002 Consider untranslated messages in the DEF.po file like translated
6003 messages. Note that using this option is usually wrong.
6005 9.7.3 Input file syntax
6006 -----------------------
6009 ‘--properties-input’
6010 Assume the input files are Java ResourceBundles in Java
6011 ‘.properties’ syntax, not in PO file syntax.
6013 ‘--stringtable-input’
6014 Assume the input files are NeXTstep/GNUstep localized resource
6015 files in ‘.strings’ syntax, not in PO file syntax.
6017 9.7.4 Informative output
6018 ------------------------
6022 Display this help and exit.
6026 Output version information and exit.
6029 File: gettext.info, Node: msgattrib Invocation, Next: msgen Invocation, Prev: msgcmp Invocation, Up: Manipulating
6031 9.8 Invoking the ‘msgattrib’ Program
6032 ====================================
6034 msgattrib [OPTION] [INPUTFILE]
6036 The ‘msgattrib’ program filters the messages of a translation catalog
6037 according to their attributes, and manipulates the attributes.
6039 9.8.1 Input file location
6040 -------------------------
6046 ‘--directory=DIRECTORY’
6047 Add DIRECTORY to the list of directories. Source files are
6048 searched relative to this list of directories. The resulting ‘.po’
6049 file will be written relative to the current directory, though.
6051 If no INPUTFILE is given or if it is ‘-’, standard input is read.
6053 9.8.2 Output file location
6054 --------------------------
6057 ‘--output-file=FILE’
6058 Write output to specified file.
6060 The results are written to standard output if no output file is
6061 specified or if it is ‘-’.
6063 9.8.3 Message selection
6064 -----------------------
6067 Keep translated messages, remove untranslated messages.
6070 Keep untranslated messages, remove translated messages.
6073 Remove ‘fuzzy’ marked messages.
6076 Keep ‘fuzzy’ marked messages, remove all other messages.
6079 Remove obsolete #~ messages.
6082 Keep obsolete #~ messages, remove all other messages.
6084 9.8.4 Attribute manipulation
6085 ----------------------------
6087 Attributes are modified after the message selection/removal has been
6088 performed. If the ‘--only-file’ or ‘--ignore-file’ option is specified,
6089 the attribute modification is applied only to those messages that are
6090 listed in the ONLY-FILE and not listed in the IGNORE-FILE.
6093 Set all messages ‘fuzzy’.
6096 Set all messages non-‘fuzzy’.
6099 Set all messages obsolete.
6102 Set all messages non-obsolete.
6105 When setting ‘fuzzy’ mark, keep “previous msgid” of translated
6109 Remove the “previous msgid” (‘#|’) comments from all messages.
6112 When removing ‘fuzzy’ mark, also set msgstr empty.
6115 Limit the attribute changes to entries that are listed in FILE.
6116 FILE should be a PO or POT file.
6118 ‘--ignore-file=FILE’
6119 Limit the attribute changes to entries that are not listed in FILE.
6120 FILE should be a PO or POT file.
6123 Synonym for ‘--only-fuzzy --clear-fuzzy’: It keeps only the fuzzy
6124 messages and removes their ‘fuzzy’ mark.
6127 Synonym for ‘--only-obsolete --clear-obsolete’: It keeps only the
6128 obsolete messages and makes them non-obsolete.
6130 9.8.5 Input file syntax
6131 -----------------------
6134 ‘--properties-input’
6135 Assume the input file is a Java ResourceBundle in Java
6136 ‘.properties’ syntax, not in PO file syntax.
6138 ‘--stringtable-input’
6139 Assume the input file is a NeXTstep/GNUstep localized resource file
6140 in ‘.strings’ syntax, not in PO file syntax.
6142 9.8.6 Output details
6143 --------------------
6147 Specify whether or when to use colors and other text attributes.
6148 See *note The --color option:: for details.
6150 ‘--style=STYLE_FILE’
6151 Specify the CSS style rule file to use for ‘--color’. See *note
6152 The --style option:: for details.
6155 Always write an output file even if it contains no message.
6159 Write the .po file using indented style.
6162 Do not write ‘#: FILENAME:LINE’ lines.
6165 ‘--add-location=TYPE’
6166 Generate ‘#: FILENAME:LINE’ lines (default).
6168 The optional TYPE can be either ‘full’, ‘file’, or ‘never’. If it
6169 is not given or ‘full’, it generates the lines with both file name
6170 and line number. If it is ‘file’, the line number part is omitted.
6171 If it is ‘never’, it completely suppresses the lines (same as
6175 Write out a strict Uniforum conforming PO file. Note that this
6176 Uniforum format should be avoided because it doesn’t support the
6180 ‘--properties-output’
6181 Write out a Java ResourceBundle in Java ‘.properties’ syntax. Note
6182 that this file format doesn’t support plural forms and silently
6183 drops obsolete messages.
6185 ‘--stringtable-output’
6186 Write out a NeXTstep/GNUstep localized resource file in ‘.strings’
6187 syntax. Note that this file format doesn’t support plural forms.
6191 Set the output page width. Long strings in the output files will
6192 be split across multiple lines in order to ensure that each line’s
6193 width (= number of screen columns) is less or equal to the given
6197 Do not break long message lines. Message lines whose width exceeds
6198 the output page width will not be split into several lines. Only
6199 file reference lines which are wider than the output page width
6204 Generate sorted output. Note that using this option makes it much
6205 harder for the translator to understand each message’s context.
6209 Sort output by file location.
6211 9.8.7 Informative output
6212 ------------------------
6216 Display this help and exit.
6220 Output version information and exit.
6223 File: gettext.info, Node: msgen Invocation, Next: msgexec Invocation, Prev: msgattrib Invocation, Up: Manipulating
6225 9.9 Invoking the ‘msgen’ Program
6226 ================================
6228 msgen [OPTION] INPUTFILE
6230 The ‘msgen’ program creates an English translation catalog. The
6231 input file is the last created English PO file, or a PO Template file
6232 (generally created by xgettext). Untranslated entries are assigned a
6233 translation that is identical to the msgid.
6235 Note: ‘msginit --no-translator --locale=en’ performs a very similar
6236 task. The main difference is that ‘msginit’ cares specially about the
6237 header entry, whereas ‘msgen’ doesn’t.
6239 9.9.1 Input file location
6240 -------------------------
6243 Input PO or POT file.
6246 ‘--directory=DIRECTORY’
6247 Add DIRECTORY to the list of directories. Source files are
6248 searched relative to this list of directories. The resulting ‘.po’
6249 file will be written relative to the current directory, though.
6251 If INPUTFILE is ‘-’, standard input is read.
6253 9.9.2 Output file location
6254 --------------------------
6257 ‘--output-file=FILE’
6258 Write output to specified file.
6260 The results are written to standard output if no output file is
6261 specified or if it is ‘-’.
6263 9.9.3 Input file syntax
6264 -----------------------
6267 ‘--properties-input’
6268 Assume the input file is a Java ResourceBundle in Java
6269 ‘.properties’ syntax, not in PO file syntax.
6271 ‘--stringtable-input’
6272 Assume the input file is a NeXTstep/GNUstep localized resource file
6273 in ‘.strings’ syntax, not in PO file syntax.
6275 9.9.4 Output details
6276 --------------------
6278 ‘--lang=CATALOGNAME’
6279 Specify the ‘Language’ field to be used in the header entry. See
6280 *note Header Entry:: for the meaning of this field. Note: The
6281 ‘Language-Team’ and ‘Plural-Forms’ fields are not set by this
6286 Specify whether or when to use colors and other text attributes.
6287 See *note The --color option:: for details.
6289 ‘--style=STYLE_FILE’
6290 Specify the CSS style rule file to use for ‘--color’. See *note
6291 The --style option:: for details.
6294 Always write an output file even if it contains no message.
6298 Write the .po file using indented style.
6301 Do not write ‘#: FILENAME:LINE’ lines.
6304 ‘--add-location=TYPE’
6305 Generate ‘#: FILENAME:LINE’ lines (default).
6307 The optional TYPE can be either ‘full’, ‘file’, or ‘never’. If it
6308 is not given or ‘full’, it generates the lines with both file name
6309 and line number. If it is ‘file’, the line number part is omitted.
6310 If it is ‘never’, it completely suppresses the lines (same as
6314 Write out a strict Uniforum conforming PO file. Note that this
6315 Uniforum format should be avoided because it doesn’t support the
6319 ‘--properties-output’
6320 Write out a Java ResourceBundle in Java ‘.properties’ syntax. Note
6321 that this file format doesn’t support plural forms and silently
6322 drops obsolete messages.
6324 ‘--stringtable-output’
6325 Write out a NeXTstep/GNUstep localized resource file in ‘.strings’
6326 syntax. Note that this file format doesn’t support plural forms.
6330 Set the output page width. Long strings in the output files will
6331 be split across multiple lines in order to ensure that each line’s
6332 width (= number of screen columns) is less or equal to the given
6336 Do not break long message lines. Message lines whose width exceeds
6337 the output page width will not be split into several lines. Only
6338 file reference lines which are wider than the output page width
6343 Generate sorted output. Note that using this option makes it much
6344 harder for the translator to understand each message’s context.
6348 Sort output by file location.
6350 9.9.5 Informative output
6351 ------------------------
6355 Display this help and exit.
6359 Output version information and exit.
6362 File: gettext.info, Node: msgexec Invocation, Next: Colorizing, Prev: msgen Invocation, Up: Manipulating
6364 9.10 Invoking the ‘msgexec’ Program
6365 ===================================
6367 msgexec [OPTION] COMMAND [COMMAND-OPTION]
6369 The ‘msgexec’ program applies a command to all translations of a
6370 translation catalog. The COMMAND can be any program that reads a
6371 translation from standard input. It is invoked once for each
6372 translation. Its output becomes msgexec’s output. ‘msgexec’’s return
6373 code is the maximum return code across all invocations.
6375 A special builtin command called ‘0’ outputs the translation,
6376 followed by a null byte. The output of ‘msgexec 0’ is suitable as input
6380 Add newline at the end of each input line.
6382 During each COMMAND invocation, the environment variable
6383 ‘MSGEXEC_MSGID’ is bound to the message’s msgid, and the environment
6384 variable ‘MSGEXEC_LOCATION’ is bound to the location in the PO file of
6385 the message. If the message has a context, the environment variable
6386 ‘MSGEXEC_MSGCTXT’ is bound to the message’s msgctxt, otherwise it is
6387 unbound. If the message has a plural form, environment variable
6388 ‘MSGEXEC_MSGID_PLURAL’ is bound to the message’s msgid_plural and
6389 ‘MSGEXEC_PLURAL_FORM’ is bound to the order number of the plural
6390 actually processed (starting with 0), otherwise both are unbound. If
6391 the message has a previous msgid (added by ‘msgmerge’), environment
6392 variable ‘MSGEXEC_PREV_MSGCTXT’ is bound to the message’s previous
6393 msgctxt, ‘MSGEXEC_PREV_MSGID’ is bound to the previous msgid, and
6394 ‘MSGEXEC_PREV_MSGID_PLURAL’ is bound to the previous msgid_plural.
6396 Note: It is your responsibility to ensure that the COMMAND can cope
6397 with input encoded in the translation catalog’s encoding. If the
6398 COMMAND wants input in a particular encoding, you can in a first step
6399 convert the translation catalog to that encoding using the ‘msgconv’
6400 program, before invoking ‘msgexec’. If the COMMAND wants input in the
6401 locale’s encoding, but you want to avoid the locale’s encoding, then you
6402 can first convert the translation catalog to UTF-8 using the ‘msgconv’
6403 program and then make ‘msgexec’ work in an UTF-8 locale, by using the
6404 ‘LC_ALL’ environment variable.
6406 9.10.1 Input file location
6407 --------------------------
6414 ‘--directory=DIRECTORY’
6415 Add DIRECTORY to the list of directories. Source files are
6416 searched relative to this list of directories. The resulting ‘.po’
6417 file will be written relative to the current directory, though.
6419 If no INPUTFILE is given or if it is ‘-’, standard input is read.
6421 9.10.2 Input file syntax
6422 ------------------------
6425 ‘--properties-input’
6426 Assume the input file is a Java ResourceBundle in Java
6427 ‘.properties’ syntax, not in PO file syntax.
6429 ‘--stringtable-input’
6430 Assume the input file is a NeXTstep/GNUstep localized resource file
6431 in ‘.strings’ syntax, not in PO file syntax.
6433 9.10.3 Informative output
6434 -------------------------
6438 Display this help and exit.
6442 Output version information and exit.
6445 File: gettext.info, Node: Colorizing, Next: libgettextpo, Prev: msgexec Invocation, Up: Manipulating
6447 9.11 Highlighting parts of PO files
6448 ===================================
6450 Translators are usually only interested in seeing the untranslated
6451 and fuzzy messages of a PO file. Also, when a message is set fuzzy
6452 because the msgid changed, they want to see the differences between the
6453 previous msgid and the current one (especially if the msgid is long and
6454 only few words in it have changed). Finally, it’s always welcome to
6455 highlight the different sections of a message in a PO file (comments,
6456 msgid, msgstr, etc.).
6458 Such highlighting is possible through the ‘msgcat’ options ‘--color’
6463 * The --color option:: Triggering colorized output
6464 * The TERM variable:: The environment variable ‘TERM’
6465 * The --style option:: The ‘--style’ option
6466 * Style rules:: Style rules for PO files
6467 * Customizing less:: Customizing ‘less’ for viewing PO files
6470 File: gettext.info, Node: The --color option, Next: The TERM variable, Prev: Colorizing, Up: Colorizing
6472 9.11.1 The ‘--color’ option
6473 ---------------------------
6475 The ‘--color=WHEN’ option specifies under which conditions colorized
6476 output should be generated. The WHEN part can be one of the following:
6480 The output will be colorized.
6484 The output will not be colorized.
6488 The output will be colorized if the output device is a tty, i.e.
6489 when the output goes directly to a text screen or terminal emulator
6493 The output will be colorized and be in HTML format.
6495 ‘--color’ is equivalent to ‘--color=yes’. The default is
6498 Thus, a command like ‘msgcat vi.po’ will produce colorized output
6499 when called by itself in a command window. Whereas in a pipe, such as
6500 ‘msgcat vi.po | less -R’, it will not produce colorized output. To get
6501 colorized output in this situation nevertheless, use the command ‘msgcat
6502 --color vi.po | less -R’.
6504 The ‘--color=html’ option will produce output that can be viewed in a
6505 browser. This can be useful, for example, for Indic languages, because
6506 the renderic of Indic scripts in browser is usually better than in
6509 Note that the output produced with the ‘--color’ option is _not_ a
6510 valid PO file in itself. It contains additional terminal-specific
6511 escape sequences or HTML tags. A PO file reader will give a syntax
6512 error when confronted with such content. Except for the ‘--color=html’
6513 case, you therefore normally don’t need to save output produced with the
6514 ‘--color’ option in a file.
6517 File: gettext.info, Node: The TERM variable, Next: The --style option, Prev: The --color option, Up: Colorizing
6519 9.11.2 The environment variable ‘TERM’
6520 --------------------------------------
6522 The environment variable ‘TERM’ contains a identifier for the text
6523 window’s capabilities. You can get a detailed list of these
6524 cababilities by using the ‘infocmp’ command, using ‘man 5 terminfo’ as a
6527 When producing text with embedded color directives, ‘msgcat’ looks at
6528 the ‘TERM’ variable. Text windows today typically support at least 8
6529 colors. Often, however, the text window supports 16 or more colors,
6530 even though the ‘TERM’ variable is set to a identifier denoting only 8
6531 supported colors. It can be worth setting the ‘TERM’ variable to a
6532 different value in these cases:
6535 ‘xterm’ is in most cases built with support for 16 colors. It can
6536 also be built with support for 88 or 256 colors (but not both).
6537 You can try to set ‘TERM’ to either ‘xterm-16color’,
6538 ‘xterm-88color’, or ‘xterm-256color’.
6541 ‘rxvt’ is often built with support for 16 colors. You can try to
6542 set ‘TERM’ to ‘rxvt-16color’.
6545 ‘konsole’ too is often built with support for 16 colors. You can
6546 try to set ‘TERM’ to ‘konsole-16color’ or ‘xterm-16color’.
6548 After setting ‘TERM’, you can verify it by invoking ‘msgcat
6549 --color=test’ and seeing whether the output looks like a reasonable
6553 File: gettext.info, Node: The --style option, Next: Style rules, Prev: The TERM variable, Up: Colorizing
6555 9.11.3 The ‘--style’ option
6556 ---------------------------
6558 The ‘--style=STYLE_FILE’ option specifies the style file to use when
6559 colorizing. It has an effect only when the ‘--color’ option is
6562 If the ‘--style’ option is not specified, the environment variable
6563 ‘PO_STYLE’ is considered. It is meant to point to the user’s preferred
6566 The default style file is
6567 ‘$prefix/share/gettext/styles/po-default.css’, where ‘$prefix’ is the
6568 installation location.
6570 A few style files are predefined:
6572 This style imitates the look used by vim 7.
6575 This style imitates the look used by GNU Emacs 21 and 22 in an X11
6578 ‘po-emacs-xterm.css’
6579 ‘po-emacs-xterm16.css’
6580 ‘po-emacs-xterm256.css’
6581 This style imitates the look used by GNU Emacs 22 in a terminal of
6582 type ‘xterm’ (8 colors) or ‘xterm-16color’ (16 colors) or
6583 ‘xterm-256color’ (256 colors), respectively.
6585 You can use these styles without specifying a directory. They are
6586 actually located in ‘$prefix/share/gettext/styles/’, where ‘$prefix’ is
6587 the installation location.
6589 You can also design your own styles. This is described in the next
6593 File: gettext.info, Node: Style rules, Next: Customizing less, Prev: The --style option, Up: Colorizing
6595 9.11.4 Style rules for PO files
6596 -------------------------------
6598 The same style file can be used for styling of a PO file, for
6599 terminal output and for HTML output. It is written in CSS (Cascading
6600 Style Sheet) syntax. See <http://www.w3.org/TR/css2/cover.html> for a
6601 formal definition of CSS. Many HTML authoring tutorials also contain
6602 explanations of CSS.
6604 In the case of HTML output, the style file is embedded in the HTML
6605 output. In the case of text output, the style file is interpreted by
6606 the ‘msgcat’ program. This means, in particular, that when ‘@import’ is
6607 used with relative file names, the file names are
6609 − relative to the resulting HTML file, in the case of HTML output,
6611 − relative to the style sheet containing the ‘@import’, in the case
6612 of text output. (Actually, ‘@import’s are not yet supported in
6613 this case, due to a limitation in ‘libcroco’.)
6615 CSS rules are built up from selectors and declarations. The
6616 declarations specify graphical properties; the selectors specify specify
6619 In PO files, the following simple selectors (based on "CSS classes",
6620 see the CSS2 spec, section 5.8.3) are supported.
6622 • Selectors that apply to entire messages:
6625 This matches the header entry of a PO file.
6628 This matches a translated message.
6631 This matches an untranslated message (i.e. a message with
6635 This matches a fuzzy message (i.e. a message which has a
6636 translation that needs review by the translator).
6639 This matches an obsolete message (i.e. a message that was
6640 translated but is not needed by the current POT file any
6643 • Selectors that apply to parts of a message in PO syntax. Recall
6644 the general structure of a message in PO syntax:
6647 # TRANSLATOR-COMMENTS
6648 #. EXTRACTED-COMMENTS
6651 #| msgid PREVIOUS-UNTRANSLATED-STRING
6652 msgid UNTRANSLATED-STRING
6653 msgstr TRANSLATED-STRING
6656 This matches all comments (translator comments, extracted
6657 comments, source file reference comments, flag comments,
6658 previous message comments, as well as the entire obsolete
6661 ‘.translator-comment’
6662 This matches the translator comments.
6664 ‘.extracted-comment’
6665 This matches the extracted comments, i.e. the comments placed
6666 by the programmer at the attention of the translator.
6668 ‘.reference-comment’
6669 This matches the source file reference comments (entire
6673 This matches the individual source file references inside the
6674 source file reference comment lines.
6677 This matches the flag comment lines (entire lines).
6680 This matches the individual flags inside flag comment lines.
6683 This matches the ‘fuzzy’ flag inside flag comment lines.
6686 This matches the comments containing the previous untranslated
6687 string (entire lines).
6690 This matches the previous untranslated string including the
6691 string delimiters, the associated keywords (‘msgid’ etc.) and
6692 the spaces between them.
6695 This matches the untranslated string including the string
6696 delimiters, the associated keywords (‘msgid’ etc.) and the
6697 spaces between them.
6700 This matches the translated string including the string
6701 delimiters, the associated keywords (‘msgstr’ etc.) and the
6702 spaces between them.
6705 This matches the keywords (‘msgid’, ‘msgstr’, etc.).
6708 This matches strings, including the string delimiters (double
6711 • Selectors that apply to parts of strings:
6714 This matches the entire contents of a string (excluding the
6715 string delimiters, i.e. the double quotes).
6718 This matches an escape sequence (starting with a backslash).
6721 This matches a format string directive (starting with a ‘%’
6722 sign in the case of most programming languages, with a ‘{’ in
6723 the case of ‘java-format’ and ‘csharp-format’, with a ‘~’ in
6724 the case of ‘lisp-format’ and ‘scheme-format’, or with ‘$’ in
6725 the case of ‘sh-format’).
6727 ‘.invalid-format-directive’
6728 This matches an invalid format string directive.
6731 In an untranslated string, this matches a part of the string
6732 that was not present in the previous untranslated string.
6733 (Not yet implemented in this release.)
6736 In an untranslated string or in a previous untranslated
6737 string, this matches a part of the string that is changed or
6738 replaced. (Not yet implemented in this release.)
6741 In a previous untranslated string, this matches a part of the
6742 string that is not present in the current untranslated string.
6743 (Not yet implemented in this release.)
6745 These selectors can be combined to hierarchical selectors. For
6748 .msgstr .invalid-format-directive { color: red; }
6750 will highlight the invalid format directives in the translated strings.
6752 In text mode, pseudo-classes (CSS2 spec, section 5.11) and
6753 pseudo-elements (CSS2 spec, section 5.12) are not supported.
6755 The declarations in HTML mode are not limited; any graphical
6756 attribute supported by the browsers can be used.
6758 The declarations in text mode are limited to the following
6759 properties. Other properties will be silently ignored.
6761 ‘color’ (CSS2 spec, section 14.1)
6762 ‘background-color’ (CSS2 spec, section 14.2.1)
6763 These properties is supported. Colors will be adjusted to match
6764 the terminal’s capabilities. Note that many terminals support only
6767 ‘font-weight’ (CSS2 spec, section 15.2.3)
6768 This property is supported, but most terminals can only render two
6769 different weights: ‘normal’ and ‘bold’. Values >= 600 are rendered
6772 ‘font-style’ (CSS2 spec, section 15.2.3)
6773 This property is supported. The values ‘italic’ and ‘oblique’ are
6774 rendered the same way.
6776 ‘text-decoration’ (CSS2 spec, section 16.3.1)
6777 This property is supported, limited to the values ‘none’ and
6781 File: gettext.info, Node: Customizing less, Prev: Style rules, Up: Colorizing
6783 9.11.5 Customizing ‘less’ for viewing PO files
6784 ----------------------------------------------
6786 The ‘less’ program is a popular text file browser for use in a text
6787 screen or terminal emulator. It also supports text with embedded escape
6788 sequences for colors and text decorations.
6790 You can use ‘less’ to view a PO file like this (assuming an UTF-8
6793 msgcat --to-code=UTF-8 --color xyz.po | less -R
6795 You can simplify this to this simple command:
6799 after these three preparations:
6801 1. Add the options ‘-R’ and ‘-f’ to the ‘LESS’ environment variable.
6803 $ LESS="$LESS -R -f"
6806 2. If your system does not already have the ‘lessopen.sh’ and
6807 ‘lessclose.sh’ scripts, create them and set the ‘LESSOPEN’ and
6808 ‘LESSCLOSE’ environment variables, as indicated in the manual page
6811 3. Add to ‘lessopen.sh’ a piece of script that recognizes PO files
6812 through their file extension and invokes ‘msgcat’ on them,
6813 producing a temporary file. Like this:
6817 tmpfile=`mktemp "${TMPDIR-/tmp}/less.XXXXXX"`
6818 msgcat --to-code=UTF-8 --color "$1" > "$tmpfile"
6825 File: gettext.info, Node: libgettextpo, Prev: Colorizing, Up: Manipulating
6827 9.12 Writing your own programs that process PO files
6828 ====================================================
6830 For the tasks for which a combination of ‘msgattrib’, ‘msgcat’ etc.
6831 is not sufficient, a set of C functions is provided in a library, to
6832 make it possible to process PO files in your own programs. When you use
6833 this library, you don’t need to write routines to parse the PO file;
6834 instead, you retrieve a pointer in memory to each of messages contained
6835 in the PO file. Functions for writing PO files are not provided at this
6838 The functions are declared in the header file ‘<gettext-po.h>’, and
6839 are defined in a library called ‘libgettextpo’.
6841 -- Data Type: po_file_t
6842 This is a pointer type that refers to the contents of a PO file,
6843 after it has been read into memory.
6845 -- Data Type: po_message_iterator_t
6846 This is a pointer type that refers to an iterator that produces a
6847 sequence of messages.
6849 -- Data Type: po_message_t
6850 This is a pointer type that refers to a message of a PO file,
6851 including its translation.
6853 -- Function: po_file_t po_file_read (const char *FILENAME)
6854 The ‘po_file_read’ function reads a PO file into memory. The file
6855 name is given as argument. The return value is a handle to the PO
6856 file’s contents, valid until ‘po_file_free’ is called on it. In
6857 case of error, the return value is ‘NULL’, and ‘errno’ is set.
6859 -- Function: void po_file_free (po_file_t FILE)
6860 The ‘po_file_free’ function frees a PO file’s contents from memory,
6861 including all messages that are only implicitly accessible through
6864 -- Function: const char * const * po_file_domains (po_file_t FILE)
6865 The ‘po_file_domains’ function returns the domains for which the
6866 given PO file has messages. The return value is a ‘NULL’
6867 terminated array which is valid as long as the FILE handle is
6868 valid. For PO files which contain no ‘domain’ directive, the
6869 return value contains only one domain, namely the default domain
6872 -- Function: po_message_iterator_t po_message_iterator (po_file_t FILE,
6874 The ‘po_message_iterator’ returns an iterator that will produce the
6875 messages of FILE that belong to the given DOMAIN. If DOMAIN is
6876 ‘NULL’, the default domain is used instead. To list the messages,
6877 use the function ‘po_next_message’ repeatedly.
6879 -- Function: void po_message_iterator_free (po_message_iterator_t
6881 The ‘po_message_iterator_free’ function frees an iterator
6882 previously allocated through the ‘po_message_iterator’ function.
6884 -- Function: po_message_t po_next_message (po_message_iterator_t
6886 The ‘po_next_message’ function returns the next message from
6887 ITERATOR and advances the iterator. It returns ‘NULL’ when the
6888 iterator has reached the end of its message list.
6890 The following functions returns details of a ‘po_message_t’. Recall
6891 that the results are valid as long as the FILE handle is valid.
6893 -- Function: const char * po_message_msgid (po_message_t MESSAGE)
6894 The ‘po_message_msgid’ function returns the ‘msgid’ (untranslated
6895 English string) of a message. This is guaranteed to be non-‘NULL’.
6897 -- Function: const char * po_message_msgid_plural (po_message_t
6899 The ‘po_message_msgid_plural’ function returns the ‘msgid_plural’
6900 (untranslated English plural string) of a message with plurals, or
6901 ‘NULL’ for a message without plural.
6903 -- Function: const char * po_message_msgstr (po_message_t MESSAGE)
6904 The ‘po_message_msgstr’ function returns the ‘msgstr’ (translation)
6905 of a message. For an untranslated message, the return value is an
6908 -- Function: const char * po_message_msgstr_plural (po_message_t
6910 The ‘po_message_msgstr_plural’ function returns the ‘msgstr[INDEX]’
6911 of a message with plurals, or ‘NULL’ when the INDEX is out of range
6912 or for a message without plural.
6914 Here is an example code how these functions can be used.
6916 const char *filename = …;
6917 po_file_t file = po_file_read (filename);
6920 error (EXIT_FAILURE, errno, "couldn't open the PO file %s", filename);
6922 const char * const *domains = po_file_domains (file);
6923 const char * const *domainp;
6925 for (domainp = domains; *domainp; domainp++)
6927 const char *domain = *domainp;
6928 po_message_iterator_t iterator = po_message_iterator (file, domain);
6932 po_message_t *message = po_next_message (iterator);
6934 if (message == NULL)
6937 const char *msgid = po_message_msgid (message);
6938 const char *msgstr = po_message_msgstr (message);
6943 po_message_iterator_free (iterator);
6946 po_file_free (file);
6949 File: gettext.info, Node: Binaries, Next: Programmers, Prev: Manipulating, Up: Top
6951 10 Producing Binary MO Files
6952 ****************************
6956 * msgfmt Invocation:: Invoking the ‘msgfmt’ Program
6957 * msgunfmt Invocation:: Invoking the ‘msgunfmt’ Program
6958 * MO Files:: The Format of GNU MO Files
6961 File: gettext.info, Node: msgfmt Invocation, Next: msgunfmt Invocation, Prev: Binaries, Up: Binaries
6963 10.1 Invoking the ‘msgfmt’ Program
6964 ==================================
6966 msgfmt [OPTION] FILENAME.po …
6968 The ‘msgfmt’ programs generates a binary message catalog from a
6969 textual translation description.
6971 10.1.1 Input file location
6972 --------------------------
6977 ‘--directory=DIRECTORY’
6978 Add DIRECTORY to the list of directories. Source files are
6979 searched relative to this list of directories. The resulting
6980 binary file will be written relative to the current directory,
6983 If an input file is ‘-’, standard input is read.
6985 10.1.2 Operation mode
6986 ---------------------
6990 Java mode: generate a Java ‘ResourceBundle’ class.
6993 Like –java, and assume Java2 (JDK 1.2 or higher).
6996 C# mode: generate a .NET .dll file containing a subclass of
6997 ‘GettextResourceSet’.
6999 ‘--csharp-resources’
7000 C# resources mode: generate a .NET ‘.resources’ file.
7003 Tcl mode: generate a tcl/msgcat ‘.msg’ file.
7006 Qt mode: generate a Qt ‘.qm’ file.
7009 Desktop Entry mode: generate a ‘.desktop’ file.
7012 XML mode: generate an XML file.
7014 10.1.3 Output file location
7015 ---------------------------
7018 ‘--output-file=FILE’
7019 Write output to specified file.
7022 Direct the program to work strictly following the Uniforum/Sun
7023 implementation. Currently this only affects the naming of the
7024 output file. If this option is not given the name of the output
7025 file is the same as the domain name. If the strict Uniforum mode
7026 is enabled the suffix ‘.mo’ is added to the file name if it is not
7029 We find this behaviour of Sun’s implementation rather silly and so
7030 by default this mode is _not_ selected.
7032 If the output FILE is ‘-’, output is written to standard output.
7034 10.1.4 Output file location in Java mode
7035 ----------------------------------------
7038 ‘--resource=RESOURCE’
7039 Specify the resource name.
7043 Specify the locale name, either a language specification of the
7044 form LL or a combined language and country specification of the
7048 Specify the base directory of classes directory hierarchy.
7051 Produce a .java source file, instead of a compiled .class file.
7053 The class name is determined by appending the locale name to the
7054 resource name, separated with an underscore. The ‘-d’ option is
7055 mandatory. The class is written under the specified directory.
7057 10.1.5 Output file location in C# mode
7058 --------------------------------------
7061 ‘--resource=RESOURCE’
7062 Specify the resource name.
7066 Specify the locale name, either a language specification of the
7067 form LL or a combined language and country specification of the
7071 Specify the base directory for locale dependent ‘.dll’ files.
7073 The ‘-l’ and ‘-d’ options are mandatory. The ‘.dll’ file is written
7074 in a subdirectory of the specified directory whose name depends on the
7077 10.1.6 Output file location in Tcl mode
7078 ---------------------------------------
7082 Specify the locale name, either a language specification of the
7083 form LL or a combined language and country specification of the
7087 Specify the base directory of ‘.msg’ message catalogs.
7089 The ‘-l’ and ‘-d’ options are mandatory. The ‘.msg’ file is written
7090 in the specified directory.
7092 10.1.7 Desktop Entry mode operations
7093 ------------------------------------
7095 ‘--template=TEMPLATE’
7096 Specify a .desktop file used as a template.
7099 ‘--keyword[=KEYWORDSPEC]’
7100 Specify KEYWORDSPEC as an additional keyword to be looked for.
7101 Without a KEYWORDSPEC, the option means to not use default
7106 Specify the locale name, either a language specification of the
7107 form LL or a combined language and country specification of the
7111 Specify the directory where PO files are read. The directory must
7112 contain the ‘LINGUAS’ file.
7114 To generate a ‘.desktop’ file for a single locale, you can use it as
7117 msgfmt --desktop --template=TEMPLATE --locale=LOCALE \
7118 -o FILE FILENAME.po …
7120 msgfmt provides a special "bulk" operation mode to process multiple
7121 ‘.po’ files at a time.
7123 msgfmt --desktop --template=TEMPLATE -d DIRECTORY -o FILE
7125 msgfmt first reads the ‘LINGUAS’ file under DIRECTORY, and then
7126 processes all ‘.po’ files listed there. You can also limit the locales
7127 to a subset, through the ‘LINGUAS’ environment variable.
7129 For either operation modes, the ‘-o’ and ‘--template’ options are
7132 10.1.8 XML mode operations
7133 --------------------------
7135 ‘--template=TEMPLATE’
7136 Specify an XML file used as a template.
7140 Specifies the language of the input files.
7144 Specify the locale name, either a language specification of the
7145 form LL or a combined language and country specification of the
7149 Specify the base directory of ‘.po’ message catalogs.
7151 To generate an XML file for a single locale, you can use it as
7154 msgfmt --xml --template=TEMPLATE --locale=LOCALE \
7155 -o FILE FILENAME.po …
7157 msgfmt provides a special "bulk" operation mode to process multiple
7158 ‘.po’ files at a time.
7160 msgfmt --xml --template=TEMPLATE -d DIRECTORY -o FILE
7162 msgfmt first reads the ‘LINGUAS’ file under DIRECTORY, and then
7163 processes all ‘.po’ files listed there. You can also limit the locales
7164 to a subset, through the ‘LINGUAS’ environment variable.
7166 For either operation modes, the ‘-o’ and ‘--template’ options are
7169 10.1.9 Input file syntax
7170 ------------------------
7173 ‘--properties-input’
7174 Assume the input files are Java ResourceBundles in Java
7175 ‘.properties’ syntax, not in PO file syntax.
7177 ‘--stringtable-input’
7178 Assume the input files are NeXTstep/GNUstep localized resource
7179 files in ‘.strings’ syntax, not in PO file syntax.
7181 10.1.10 Input file interpretation
7182 ---------------------------------
7186 Perform all the checks implied by ‘--check-format’,
7187 ‘--check-header’, ‘--check-domain’.
7190 Check language dependent format strings.
7192 If the string represents a format string used in a ‘printf’-like
7193 function both strings should have the same number of ‘%’ format
7194 specifiers, with matching types. If the flag ‘c-format’ or
7195 ‘possible-c-format’ appears in the special comment <#,> for this
7196 entry a check is performed. For example, the check will diagnose
7197 using ‘%.*s’ against ‘%s’, or ‘%d’ against ‘%s’, or ‘%d’ against
7198 ‘%x’. It can even handle positional parameters.
7200 Normally the ‘xgettext’ program automatically decides whether a
7201 string is a format string or not. This algorithm is not perfect,
7202 though. It might regard a string as a format string though it is
7203 not used in a ‘printf’-like function and so ‘msgfmt’ might report
7204 errors where there are none.
7206 To solve this problem the programmer can dictate the decision to
7207 the ‘xgettext’ program (*note c-format::). The translator should
7208 not consider removing the flag from the <#,> line. This "fix"
7209 would be reversed again as soon as ‘msgmerge’ is called the next
7213 Verify presence and contents of the header entry. *Note Header
7214 Entry::, for a description of the various fields in the header
7218 Check for conflicts between domain directives and the
7219 ‘--output-file’ option
7222 ‘--check-compatibility’
7223 Check that GNU msgfmt behaves like X/Open msgfmt. This will give
7224 an error when attempting to use the GNU extensions.
7226 ‘--check-accelerators[=CHAR]’
7227 Check presence of keyboard accelerators for menu items. This is
7228 based on the convention used in some GUIs that a keyboard
7229 accelerator in a menu item string is designated by an immediately
7230 preceding ‘&’ character. Sometimes a keyboard accelerator is also
7231 called "keyboard mnemonic". This check verifies that if the
7232 untranslated string has exactly one ‘&’ character, the translated
7233 string has exactly one ‘&’ as well. If this option is given with a
7234 CHAR argument, this CHAR should be a non-alphanumeric character and
7235 is used as keyboard accelerator mark instead of ‘&’.
7239 Use fuzzy entries in output. Note that using this option is
7240 usually wrong, because fuzzy messages are exactly those which have
7241 not been validated by a human translator.
7243 10.1.11 Output details
7244 ----------------------
7247 ‘--alignment=NUMBER’
7248 Align strings to NUMBER bytes (default: 1).
7250 ‘--endianness=BYTEORDER’
7251 Write out 32-bit numbers in the given byte order. The possible
7252 values are ‘big’ and ‘little’. The default depends on the
7253 platform, namely on the endianness of the CPU.
7255 MO files of any endianness can be used on any platform. When a MO
7256 file has an endianness other than the platform’s one, the 32-bit
7257 numbers from the MO file are swapped at runtime. The performance
7258 impact is negligible.
7260 This option can be useful to produce MO files that are independent
7264 Don’t include a hash table in the binary file. Lookup will be more
7265 expensive at run time (binary search instead of hash table lookup).
7267 10.1.12 Informative output
7268 --------------------------
7272 Display this help and exit.
7276 Output version information and exit.
7279 Print statistics about translations. When the option ‘--verbose’
7280 is used in combination with ‘--statistics’, the input file name is
7281 printed in front of the statistics line.
7285 Increase verbosity level.
7288 File: gettext.info, Node: msgunfmt Invocation, Next: MO Files, Prev: msgfmt Invocation, Up: Binaries
7290 10.2 Invoking the ‘msgunfmt’ Program
7291 ====================================
7293 msgunfmt [OPTION] [FILE]...
7295 The ‘msgunfmt’ program converts a binary message catalog to a
7296 Uniforum style .po file.
7298 10.2.1 Operation mode
7299 ---------------------
7303 Java mode: input is a Java ‘ResourceBundle’ class.
7306 C# mode: input is a .NET .dll file containing a subclass of
7307 ‘GettextResourceSet’.
7309 ‘--csharp-resources’
7310 C# resources mode: input is a .NET ‘.resources’ file.
7313 Tcl mode: input is a tcl/msgcat ‘.msg’ file.
7315 10.2.2 Input file location
7316 --------------------------
7321 If no input FILE is given or if it is ‘-’, standard input is read.
7323 10.2.3 Input file location in Java mode
7324 ---------------------------------------
7327 ‘--resource=RESOURCE’
7328 Specify the resource name.
7332 Specify the locale name, either a language specification of the
7333 form LL or a combined language and country specification of the
7336 The class name is determined by appending the locale name to the
7337 resource name, separated with an underscore. The class is located using
7340 10.2.4 Input file location in C# mode
7341 -------------------------------------
7344 ‘--resource=RESOURCE’
7345 Specify the resource name.
7349 Specify the locale name, either a language specification of the
7350 form LL or a combined language and country specification of the
7354 Specify the base directory for locale dependent ‘.dll’ files.
7356 The ‘-l’ and ‘-d’ options are mandatory. The ‘.msg’ file is located
7357 in a subdirectory of the specified directory whose name depends on the
7360 10.2.5 Input file location in Tcl mode
7361 --------------------------------------
7365 Specify the locale name, either a language specification of the
7366 form LL or a combined language and country specification of the
7370 Specify the base directory of ‘.msg’ message catalogs.
7372 The ‘-l’ and ‘-d’ options are mandatory. The ‘.msg’ file is located
7373 in the specified directory.
7375 10.2.6 Output file location
7376 ---------------------------
7379 ‘--output-file=FILE’
7380 Write output to specified file.
7382 The results are written to standard output if no output file is
7383 specified or if it is ‘-’.
7385 10.2.7 Output details
7386 ---------------------
7390 Specify whether or when to use colors and other text attributes.
7391 See *note The --color option:: for details.
7393 ‘--style=STYLE_FILE’
7394 Specify the CSS style rule file to use for ‘--color’. See *note
7395 The --style option:: for details.
7398 Always write an output file even if it contains no message.
7402 Write the .po file using indented style.
7405 Write out a strict Uniforum conforming PO file. Note that this
7406 Uniforum format should be avoided because it doesn’t support the
7410 ‘--properties-output’
7411 Write out a Java ResourceBundle in Java ‘.properties’ syntax. Note
7412 that this file format doesn’t support plural forms and silently
7413 drops obsolete messages.
7415 ‘--stringtable-output’
7416 Write out a NeXTstep/GNUstep localized resource file in ‘.strings’
7417 syntax. Note that this file format doesn’t support plural forms.
7421 Set the output page width. Long strings in the output files will
7422 be split across multiple lines in order to ensure that each line’s
7423 width (= number of screen columns) is less or equal to the given
7427 Do not break long message lines. Message lines whose width exceeds
7428 the output page width will not be split into several lines. Only
7429 file reference lines which are wider than the output page width
7434 Generate sorted output. Note that using this option makes it much
7435 harder for the translator to understand each message’s context.
7437 10.2.8 Informative output
7438 -------------------------
7442 Display this help and exit.
7446 Output version information and exit.
7450 Increase verbosity level.
7453 File: gettext.info, Node: MO Files, Prev: msgunfmt Invocation, Up: Binaries
7455 10.3 The Format of GNU MO Files
7456 ===============================
7458 The format of the generated MO files is best described by a picture,
7459 which appears below.
7461 The first two words serve the identification of the file. The magic
7462 number will always signal GNU MO files. The number is stored in the
7463 byte order of the generating machine, so the magic number really is two
7464 numbers: ‘0x950412de’ and ‘0xde120495’.
7466 The second word describes the current revision of the file format,
7467 composed of a major and a minor revision number. The revision numbers
7468 ensure that the readers of MO files can distinguish new formats from old
7469 ones and handle their contents, as far as possible. For now the major
7470 revision is 0 or 1, and the minor revision is also 0 or 1. More
7471 revisions might be added in the future. A program seeing an unexpected
7472 major revision number should stop reading the MO file entirely; whereas
7473 an unexpected minor revision number means that the file can be read but
7474 will not reveal its full contents, when parsed by a program that
7475 supports only smaller minor revision numbers.
7477 The version is kept separate from the magic number, instead of using
7478 different magic numbers for different formats, mainly because
7479 ‘/etc/magic’ is not updated often.
7481 Follow a number of pointers to later tables in the file, allowing for
7482 the extension of the prefix part of MO files without having to recompile
7483 programs reading them. This might become useful for later inserting a
7484 few flag bits, indication about the charset used, new tables, or other
7487 Then, at offset O and offset T in the picture, two tables of string
7488 descriptors can be found. In both tables, each string descriptor uses
7489 two 32 bits integers, one for the string length, another for the offset
7490 of the string in the MO file, counting in bytes from the start of the
7491 file. The first table contains descriptors for the original strings,
7492 and is sorted so the original strings are in increasing lexicographical
7493 order. The second table contains descriptors for the translated
7494 strings, and is parallel to the first table: to find the corresponding
7495 translation one has to access the array slot in the second array with
7498 Having the original strings sorted enables the use of simple binary
7499 search, for when the MO file does not contain an hashing table, or for
7500 when it is not practical to use the hashing table provided in the MO
7501 file. This also has another advantage, as the empty string in a PO file
7502 GNU ‘gettext’ is usually _translated_ into some system information
7503 attached to that particular MO file, and the empty string necessarily
7504 becomes the first in both the original and translated tables, making the
7505 system information very easy to find.
7507 The size S of the hash table can be zero. In this case, the hash
7508 table itself is not contained in the MO file. Some people might prefer
7509 this because a precomputed hashing table takes disk space, and does not
7510 win _that_ much speed. The hash table contains indices to the sorted
7511 array of strings in the MO file. Conflict resolution is done by double
7512 hashing. The precise hashing algorithm used is fairly dependent on GNU
7513 ‘gettext’ code, and is not documented here.
7515 As for the strings themselves, they follow the hash file, and each is
7516 terminated with a <NUL>, and this <NUL> is not counted in the length
7517 which appears in the string descriptor. The ‘msgfmt’ program has an
7518 option selecting the alignment for MO file strings. With this option,
7519 each string is separately aligned so it starts at an offset which is a
7520 multiple of the alignment value. On some RISC machines, a correct
7521 alignment will speed things up.
7523 Contexts are stored by storing the concatenation of the context, a
7524 <EOT> byte, and the original string, instead of the original string.
7526 Plural forms are stored by letting the plural of the original string
7527 follow the singular of the original string, separated through a <NUL>
7528 byte. The length which appears in the string descriptor includes both.
7529 However, only the singular of the original string takes part in the hash
7530 table lookup. The plural variants of the translation are all stored
7531 consecutively, separated through a <NUL> byte. Here also, the length in
7532 the string descriptor includes all of them.
7534 Nothing prevents a MO file from having embedded <NUL>s in strings.
7535 However, the program interface currently used already presumes that
7536 strings are <NUL> terminated, so embedded <NUL>s are somewhat useless.
7537 But the MO file format is general enough so other interfaces would be
7538 later possible, if for example, we ever want to implement wide
7539 characters right in MO files, where <NUL> bytes may accidentally appear.
7540 (No, we don’t want to have wide characters in MO files. They would make
7541 the file unnecessarily large, and the ‘wchar_t’ type being platform
7542 dependent, MO files would be platform dependent as well.)
7544 This particular issue has been strongly debated in the GNU ‘gettext’
7545 development forum, and it is expectable that MO file format will evolve
7546 or change over time. It is even possible that many formats may later be
7547 supported concurrently. But surely, we have to start somewhere, and the
7548 MO file format described here is a good start. Nothing is cast in
7549 concrete, and the format may later evolve fairly easily, so we should
7550 feel comfortable with the current approach.
7553 +------------------------------------------+
7554 0 | magic number = 0x950412de |
7556 4 | file format revision = 0 |
7558 8 | number of strings | == N
7560 12 | offset of table with original strings | == O
7562 16 | offset of table with translation strings | == T
7564 20 | size of hashing table | == S
7566 24 | offset of hashing table | == H
7569 . (possibly more entries later) .
7572 O | length & offset 0th string ----------------.
7573 O + 8 | length & offset 1st string ------------------.
7575 O + ((N-1)*8)| length & offset (N-1)th string | | |
7577 T | length & offset 0th translation ---------------.
7578 T + 8 | length & offset 1st translation -----------------.
7580 T + ((N-1)*8)| length & offset (N-1)th translation | | | | |
7582 H | start hash table | | | | |
7584 H + S * 4 | end hash table | | | | |
7586 | NUL terminated 0th string <----------------' | | |
7588 | NUL terminated 1st string <------------------' | |
7592 | NUL terminated 0th translation <---------------' |
7594 | NUL terminated 1st translation <-----------------'
7598 +------------------------------------------+
7601 File: gettext.info, Node: Programmers, Next: Translators, Prev: Binaries, Up: Top
7603 11 The Programmer’s View
7604 ************************
7606 One aim of the current message catalog implementation provided by GNU
7607 ‘gettext’ was to use the system’s message catalog handling, if the
7608 installer wishes to do so. So we perhaps should first take a look at
7609 the solutions we know about. The people in the POSIX committee did not
7610 manage to agree on one of the semi-official standards which we’ll
7611 describe below. In fact they couldn’t agree on anything, so they
7612 decided only to include an example of an interface. The major Unix
7613 vendors are split in the usage of the two most important specifications:
7614 X/Open’s catgets vs. Uniforum’s gettext interface. We’ll describe them
7615 both and later explain our solution of this dilemma.
7619 * catgets:: About ‘catgets’
7620 * gettext:: About ‘gettext’
7621 * Comparison:: Comparing the two interfaces
7622 * Using libintl.a:: Using libintl.a in own programs
7623 * gettext grok:: Being a ‘gettext’ grok
7624 * Temp Programmers:: Temporary Notes for the Programmers Chapter
7627 File: gettext.info, Node: catgets, Next: gettext, Prev: Programmers, Up: Programmers
7629 11.1 About ‘catgets’
7630 ====================
7632 The ‘catgets’ implementation is defined in the X/Open Portability
7633 Guide, Volume 3, XSI Supplementary Definitions, Chapter 5. But the
7634 process of creating this standard seemed to be too slow for some of the
7635 Unix vendors so they created their implementations on preliminary
7636 versions of the standard. Of course this leads again to problems while
7637 writing platform independent programs: even the usage of ‘catgets’ does
7638 not guarantee a unique interface.
7640 Another, personal comment on this that only a bunch of committee
7641 members could have made this interface. They never really tried to
7642 program using this interface. It is a fast, memory-saving
7643 implementation, an user can happily live with it. But programmers hate
7644 it (at least I and some others do…)
7646 But we must not forget one point: after all the trouble with
7647 transferring the rights on Unix(tm) they at last came to X/Open, the
7648 very same who published this specification. This leads me to making the
7649 prediction that this interface will be in future Unix standards (e.g.
7650 Spec1170) and therefore part of all Unix implementation
7651 (implementations, which are _allowed_ to wear this name).
7655 * Interface to catgets:: The interface
7656 * Problems with catgets:: Problems with the ‘catgets’ interface?!
7659 File: gettext.info, Node: Interface to catgets, Next: Problems with catgets, Prev: catgets, Up: catgets
7661 11.1.1 The Interface
7662 --------------------
7664 The interface to the ‘catgets’ implementation consists of three
7665 functions which correspond to those used in file access: ‘catopen’ to
7666 open the catalog for using, ‘catgets’ for accessing the message tables,
7667 and ‘catclose’ for closing after work is done. Prototypes for the
7668 functions and the needed definitions are in the ‘<nl_types.h>’ header
7671 ‘catopen’ is used like in this:
7673 nl_catd catd = catopen ("catalog_name", 0);
7675 The function takes as the argument the name of the catalog. This
7676 usual refers to the name of the program or the package. The second
7677 parameter is not further specified in the standard. I don’t even know
7678 whether it is implemented consistently among various systems. So the
7679 common advice is to use ‘0’ as the value. The return value is a handle
7680 to the message catalog, equivalent to handles to file returned by
7683 This handle is of course used in the ‘catgets’ function which can be
7686 char *translation = catgets (catd, set_no, msg_id, "original string");
7688 The first parameter is this catalog descriptor. The second parameter
7689 specifies the set of messages in this catalog, in which the message
7690 described by ‘msg_id’ is obtained. ‘catgets’ therefore uses a
7691 three-stage addressing:
7693 catalog name ⇒ set number ⇒ message ID ⇒ translation
7695 The fourth argument is not used to address the translation. It is
7696 given as a default value in case when one of the addressing stages fail.
7697 One important thing to remember is that although the return type of
7698 catgets is ‘char *’ the resulting string _must not_ be changed. It
7699 should better be ‘const char *’, but the standard is published in 1988,
7700 one year before ANSI C.
7702 The last of these functions is used and behaves as expected:
7706 After this no ‘catgets’ call using the descriptor is legal anymore.
7709 File: gettext.info, Node: Problems with catgets, Prev: Interface to catgets, Up: catgets
7711 11.1.2 Problems with the ‘catgets’ Interface?!
7712 ----------------------------------------------
7714 Now that this description seemed to be really easy — where are the
7715 problems we speak of? In fact the interface could be used in a
7716 reasonable way, but constructing the message catalogs is a pain. The
7717 reason for this lies in the third argument of ‘catgets’: the unique
7718 message ID. This has to be a numeric value for all messages in a single
7719 set. Perhaps you could imagine the problems keeping such a list while
7720 changing the source code. Add a new message here, remove one there. Of
7721 course there have been developed a lot of tools helping to organize this
7722 chaos but one as the other fails in one aspect or the other. We don’t
7723 want to say that the other approach has no problems but they are far
7724 more easy to manage.
7727 File: gettext.info, Node: gettext, Next: Comparison, Prev: catgets, Up: Programmers
7729 11.2 About ‘gettext’
7730 ====================
7732 The definition of the ‘gettext’ interface comes from a Uniforum
7733 proposal. It was submitted there by Sun, who had implemented the
7734 ‘gettext’ function in SunOS 4, around 1990. Nowadays, the ‘gettext’
7735 interface is specified by the OpenI18N standard.
7737 The main point about this solution is that it does not follow the
7738 method of normal file handling (open-use-close) and that it does not
7739 burden the programmer with so many tasks, especially the unique key
7740 handling. Of course here also a unique key is needed, but this key is
7741 the message itself (how long or short it is). See *note Comparison::
7742 for a more detailed comparison of the two methods.
7744 The following section contains a rather detailed description of the
7745 interface. We make it that detailed because this is the interface we
7746 chose for the GNU ‘gettext’ Library. Programmers interested in using
7747 this library will be interested in this description.
7751 * Interface to gettext:: The interface
7752 * Ambiguities:: Solving ambiguities
7753 * Locating Catalogs:: Locating message catalog files
7754 * Charset conversion:: How to request conversion to Unicode
7755 * Contexts:: Solving ambiguities in GUI programs
7756 * Plural forms:: Additional functions for handling plurals
7757 * Optimized gettext:: Optimization of the *gettext functions
7760 File: gettext.info, Node: Interface to gettext, Next: Ambiguities, Prev: gettext, Up: gettext
7762 11.2.1 The Interface
7763 --------------------
7765 The minimal functionality an interface must have is a) to select a
7766 domain the strings are coming from (a single domain for all programs is
7767 not reasonable because its construction and maintenance is difficult,
7768 perhaps impossible) and b) to access a string in a selected domain.
7770 This is principally the description of the ‘gettext’ interface. It
7771 has a global domain which unqualified usages reference. Of course this
7772 domain is selectable by the user.
7774 char *textdomain (const char *domain_name);
7776 This provides the possibility to change or query the current status
7777 of the current global domain of the ‘LC_MESSAGE’ category. The argument
7778 is a null-terminated string, whose characters must be legal in the use
7779 in filenames. If the DOMAIN_NAME argument is ‘NULL’, the function
7780 returns the current value. If no value has been set before, the name of
7781 the default domain is returned: _messages_. Please note that although
7782 the return value of ‘textdomain’ is of type ‘char *’ no changing is
7783 allowed. It is also important to know that no checks of the
7784 availability are made. If the name is not available you will see this
7785 by the fact that no translations are provided.
7787 To use a domain set by ‘textdomain’ the function
7789 char *gettext (const char *msgid);
7791 is to be used. This is the simplest reasonable form one can imagine.
7792 The translation of the string MSGID is returned if it is available in
7793 the current domain. If it is not available, the argument itself is
7794 returned. If the argument is ‘NULL’ the result is undefined.
7796 One thing which should come into mind is that no explicit dependency
7797 to the used domain is given. The current value of the domain is used.
7798 If this changes between two executions of the same ‘gettext’ call in the
7799 program, both calls reference a different message catalog.
7801 For the easiest case, which is normally used in internationalized
7802 packages, once at the beginning of execution a call to ‘textdomain’ is
7803 issued, setting the domain to a unique name, normally the package name.
7804 In the following code all strings which have to be translated are
7805 filtered through the gettext function. That’s all, the package speaks
7809 File: gettext.info, Node: Ambiguities, Next: Locating Catalogs, Prev: Interface to gettext, Up: gettext
7811 11.2.2 Solving Ambiguities
7812 --------------------------
7814 While this single name domain works well for most applications there
7815 might be the need to get translations from more than one domain. Of
7816 course one could switch between different domains with calls to
7817 ‘textdomain’, but this is really not convenient nor is it fast. A
7818 possible situation could be one case subject to discussion during this
7819 writing: all error messages of functions in the set of common used
7820 functions should go into a separate domain ‘error’. By this mean we
7821 would only need to translate them once. Another case are messages from
7822 a library, as these _have_ to be independent of the current domain set
7825 For this reasons there are two more functions to retrieve strings:
7827 char *dgettext (const char *domain_name, const char *msgid);
7828 char *dcgettext (const char *domain_name, const char *msgid,
7831 Both take an additional argument at the first place, which
7832 corresponds to the argument of ‘textdomain’. The third argument of
7833 ‘dcgettext’ allows to use another locale category but ‘LC_MESSAGES’.
7834 But I really don’t know where this can be useful. If the DOMAIN_NAME is
7835 ‘NULL’ or CATEGORY has an value beside the known ones, the result is
7836 undefined. It should also be noted that this function is not part of
7837 the second known implementation of this function family, the one found
7840 A second ambiguity can arise by the fact, that perhaps more than one
7841 domain has the same name. This can be solved by specifying where the
7842 needed message catalog files can be found.
7844 char *bindtextdomain (const char *domain_name,
7845 const char *dir_name);
7847 Calling this function binds the given domain to a file in the
7848 specified directory (how this file is determined follows below).
7849 Especially a file in the systems default place is not favored against
7850 the specified file anymore (as it would be by solely using
7851 ‘textdomain’). A ‘NULL’ pointer for the DIR_NAME parameter returns the
7852 binding associated with DOMAIN_NAME. If DOMAIN_NAME itself is ‘NULL’
7853 nothing happens and a ‘NULL’ pointer is returned. Here again as for all
7854 the other functions is true that none of the return value must be
7857 It is important to remember that relative path names for the DIR_NAME
7858 parameter can be trouble. Since the path is always computed relative to
7859 the current directory different results will be achieved when the
7860 program executes a ‘chdir’ command. Relative paths should always be
7861 avoided to avoid dependencies and unreliabilities.
7864 File: gettext.info, Node: Locating Catalogs, Next: Charset conversion, Prev: Ambiguities, Up: gettext
7866 11.2.3 Locating Message Catalog Files
7867 -------------------------------------
7869 Because many different languages for many different packages have to
7870 be stored we need some way to add these information to file message
7871 catalog files. The way usually used in Unix environments is have this
7872 encoding in the file name. This is also done here. The directory name
7873 given in ‘bindtextdomain’s second argument (or the default directory),
7874 followed by the name of the locale, the locale category, and the domain
7875 name are concatenated:
7877 DIR_NAME/LOCALE/LC_CATEGORY/DOMAIN_NAME.mo
7879 The default value for DIR_NAME is system specific. For the GNU
7880 library, and for packages adhering to its conventions, it’s:
7881 /usr/local/share/locale
7883 LOCALE is the name of the locale category which is designated by
7884 ‘LC_CATEGORY’. For ‘gettext’ and ‘dgettext’ this ‘LC_CATEGORY’ is
7885 always ‘LC_MESSAGES’.(1) The name of the locale category is determined
7886 through ‘setlocale (LC_CATEGORY, NULL)’. (2) When using the function
7887 ‘dcgettext’, you can specify the locale category through the third
7890 ---------- Footnotes ----------
7892 (1) Some system, e.g. mingw, don’t have ‘LC_MESSAGES’. Here we use a
7893 more or less arbitrary value for it, namely 1729, the smallest positive
7894 integer which can be represented in two different ways as the sum of two
7897 (2) When the system does not support ‘setlocale’ its behavior in
7898 setting the locale values is simulated by looking at the environment
7902 File: gettext.info, Node: Charset conversion, Next: Contexts, Prev: Locating Catalogs, Up: gettext
7904 11.2.4 How to specify the output character set ‘gettext’ uses
7905 -------------------------------------------------------------
7907 ‘gettext’ not only looks up a translation in a message catalog. It
7908 also converts the translation on the fly to the desired output character
7909 set. This is useful if the user is working in a different character set
7910 than the translator who created the message catalog, because it avoids
7911 distributing variants of message catalogs which differ only in the
7914 The output character set is, by default, the value of ‘nl_langinfo
7915 (CODESET)’, which depends on the ‘LC_CTYPE’ part of the current locale.
7916 But programs which store strings in a locale independent way (e.g.
7917 UTF-8) can request that ‘gettext’ and related functions return the
7918 translations in that encoding, by use of the ‘bind_textdomain_codeset’
7921 Note that the MSGID argument to ‘gettext’ is not subject to character
7922 set conversion. Also, when ‘gettext’ does not find a translation for
7923 MSGID, it returns MSGID unchanged – independently of the current output
7924 character set. It is therefore recommended that all MSGIDs be US-ASCII
7927 -- Function: char * bind_textdomain_codeset (const char *DOMAINNAME,
7928 const char *CODESET)
7929 The ‘bind_textdomain_codeset’ function can be used to specify the
7930 output character set for message catalogs for domain DOMAINNAME.
7931 The CODESET argument must be a valid codeset name which can be used
7932 for the ‘iconv_open’ function, or a null pointer.
7934 If the CODESET parameter is the null pointer,
7935 ‘bind_textdomain_codeset’ returns the currently selected codeset
7936 for the domain with the name DOMAINNAME. It returns ‘NULL’ if no
7937 codeset has yet been selected.
7939 The ‘bind_textdomain_codeset’ function can be used several times.
7940 If used multiple times with the same DOMAINNAME argument, the later
7941 call overrides the settings made by the earlier one.
7943 The ‘bind_textdomain_codeset’ function returns a pointer to a
7944 string containing the name of the selected codeset. The string is
7945 allocated internally in the function and must not be changed by the
7946 user. If the system went out of core during the execution of
7947 ‘bind_textdomain_codeset’, the return value is ‘NULL’ and the
7948 global variable ERRNO is set accordingly.
7951 File: gettext.info, Node: Contexts, Next: Plural forms, Prev: Charset conversion, Up: gettext
7953 11.2.5 Using contexts for solving ambiguities
7954 ---------------------------------------------
7956 One place where the ‘gettext’ functions, if used normally, have big
7957 problems is within programs with graphical user interfaces (GUIs). The
7958 problem is that many of the strings which have to be translated are very
7959 short. They have to appear in pull-down menus which restricts the
7960 length. But strings which are not containing entire sentences or at
7961 least large fragments of a sentence may appear in more than one
7962 situation in the program but might have different translations. This is
7963 especially true for the one-word strings which are frequently used in
7966 As a consequence many people say that the ‘gettext’ approach is wrong
7967 and instead ‘catgets’ should be used which indeed does not have this
7968 problem. But there is a very simple and powerful method to handle this
7969 kind of problems with the ‘gettext’ functions.
7971 Contexts can be added to strings to be translated. A context
7972 dependent translation lookup is when a translation for a given string is
7973 searched, that is limited to a given context. The translation for the
7974 same string in a different context can be different. The different
7975 translations of the same string in different contexts can be stored in
7976 the in the same MO file, and can be edited by the translator in the same
7979 The ‘gettext.h’ include file contains the lookup macros for strings
7980 with contexts. They are implemented as thin macros and inline functions
7981 over the functions from ‘<libintl.h>’.
7983 const char *pgettext (const char *msgctxt, const char *msgid);
7985 In a call of this macro, MSGCTXT and MSGID must be string literals.
7986 The macro returns the translation of MSGID, restricted to the context
7989 The MSGCTXT string is visible in the PO file to the translator. You
7990 should try to make it somehow canonical and never changing. Because
7991 every time you change an MSGCTXT, the translator will have to review the
7992 translation of MSGID.
7994 Finding a canonical MSGCTXT string that doesn’t change over time can
7995 be hard. But you shouldn’t use the file name or class name containing
7996 the ‘pgettext’ call – because it is a common development task to rename
7997 a file or a class, and it shouldn’t cause translator work. Also you
7998 shouldn’t use a comment in the form of a complete English sentence as
7999 MSGCTXT – because orthography or grammar changes are often applied to
8000 such sentences, and again, it shouldn’t force the translator to do a
8003 The ‘p’ in ‘pgettext’ stands for “particular”: ‘pgettext’ fetches a
8004 particular translation of the MSGID.
8006 const char *dpgettext (const char *domain_name,
8007 const char *msgctxt, const char *msgid);
8008 const char *dcpgettext (const char *domain_name,
8009 const char *msgctxt, const char *msgid,
8012 These are generalizations of ‘pgettext’. They behave similarly to
8013 ‘dgettext’ and ‘dcgettext’, respectively. The DOMAIN_NAME argument
8014 defines the translation domain. The CATEGORY argument allows to use
8015 another locale category than ‘LC_MESSAGES’.
8017 As as example consider the following fictional situation. A GUI
8018 program has a menu bar with the following entries:
8020 +------------+------------+--------------------------------------+
8021 | File | Printer | |
8022 +------------+------------+--------------------------------------+
8025 +----------+ | Connect |
8028 To have the strings ‘File’, ‘Printer’, ‘Open’, ‘New’, ‘Select’, and
8029 ‘Connect’ translated there has to be at some point in the code a call to
8030 a function of the ‘gettext’ family. But in two places the string passed
8031 into the function would be ‘Open’. The translations might not be the
8032 same and therefore we are in the dilemma described above.
8034 What distinguishes the two places is the menu path from the menu root
8035 to the particular menu entries:
8043 Menu|Printer|Connect
8045 The context is thus the menu path without its last part. So, the
8046 calls look like this:
8048 pgettext ("Menu|", "File")
8049 pgettext ("Menu|", "Printer")
8050 pgettext ("Menu|File|", "Open")
8051 pgettext ("Menu|File|", "New")
8052 pgettext ("Menu|Printer|", "Select")
8053 pgettext ("Menu|Printer|", "Open")
8054 pgettext ("Menu|Printer|", "Connect")
8056 Whether or not to use the ‘|’ character at the end of the context is
8059 For more complex cases, where the MSGCTXT or MSGID are not string
8060 literals, more general macros are available:
8062 const char *pgettext_expr (const char *msgctxt, const char *msgid);
8063 const char *dpgettext_expr (const char *domain_name,
8064 const char *msgctxt, const char *msgid);
8065 const char *dcpgettext_expr (const char *domain_name,
8066 const char *msgctxt, const char *msgid,
8069 Here MSGCTXT and MSGID can be arbitrary string-valued expressions.
8070 These macros are more general. But in the case that both argument
8071 expressions are string literals, the macros without the ‘_expr’ suffix
8075 File: gettext.info, Node: Plural forms, Next: Optimized gettext, Prev: Contexts, Up: gettext
8077 11.2.6 Additional functions for plural forms
8078 --------------------------------------------
8080 The functions of the ‘gettext’ family described so far (and all the
8081 ‘catgets’ functions as well) have one problem in the real world which
8082 have been neglected completely in all existing approaches. What is
8083 meant here is the handling of plural forms.
8085 Looking through Unix source code before the time anybody thought
8086 about internationalization (and, sadly, even afterwards) one can often
8087 find code similar to the following:
8089 printf ("%d file%s deleted", n, n == 1 ? "" : "s");
8091 After the first complaints from people internationalizing the code
8092 people either completely avoided formulations like this or used strings
8093 like ‘"file(s)"’. Both look unnatural and should be avoided. First
8094 tries to solve the problem correctly looked like this:
8097 printf ("%d file deleted", n);
8099 printf ("%d files deleted", n);
8101 But this does not solve the problem. It helps languages where the
8102 plural form of a noun is not simply constructed by adding an ‘s’ but
8103 that is all. Once again people fell into the trap of believing the
8104 rules their language is using are universal. But the handling of plural
8105 forms differs widely between the language families. For example, Rafal
8106 Maszkowski ‘<rzm@mat.uni.torun.pl>’ reports:
8108 In Polish we use e.g. plik (file) this way:
8114 and so on (o’ means 8859-2 oacute which should be rather okreska,
8115 similar to aogonek).
8117 There are two things which can differ between languages (and even
8118 inside language families);
8120 • The form how plural forms are built differs. This is a problem
8121 with languages which have many irregularities. German, for
8122 instance, is a drastic case. Though English and German are part of
8123 the same language family (Germanic), the almost regular forming of
8124 plural noun forms (appending an ‘s’) is hardly found in German.
8126 • The number of plural forms differ. This is somewhat surprising for
8127 those who only have experiences with Romanic and Germanic languages
8128 since here the number is the same (there are two).
8130 But other language families have only one form or many forms. More
8131 information on this in an extra section.
8133 The consequence of this is that application writers should not try to
8134 solve the problem in their code. This would be localization since it is
8135 only usable for certain, hardcoded language environments. Instead the
8136 extended ‘gettext’ interface should be used.
8138 These extra functions are taking instead of the one key string two
8139 strings and a numerical argument. The idea behind this is that using
8140 the numerical argument and the first string as a key, the implementation
8141 can select using rules specified by the translator the right plural
8142 form. The two string arguments then will be used to provide a return
8143 value in case no message catalog is found (similar to the normal
8144 ‘gettext’ behavior). In this case the rules for Germanic language is
8145 used and it is assumed that the first string argument is the singular
8146 form, the second the plural form.
8148 This has the consequence that programs without language catalogs can
8149 display the correct strings only if the program itself is written using
8150 a Germanic language. This is a limitation but since the GNU C library
8151 (as well as the GNU ‘gettext’ package) are written as part of the GNU
8152 package and the coding standards for the GNU project require program
8153 being written in English, this solution nevertheless fulfills its
8156 -- Function: char * ngettext (const char *MSGID1, const char *MSGID2,
8157 unsigned long int N)
8158 The ‘ngettext’ function is similar to the ‘gettext’ function as it
8159 finds the message catalogs in the same way. But it takes two extra
8160 arguments. The MSGID1 parameter must contain the singular form of
8161 the string to be converted. It is also used as the key for the
8162 search in the catalog. The MSGID2 parameter is the plural form.
8163 The parameter N is used to determine the plural form. If no
8164 message catalog is found MSGID1 is returned if ‘n == 1’, otherwise
8167 An example for the use of this function is:
8169 printf (ngettext ("%d file removed", "%d files removed", n), n);
8171 Please note that the numeric value N has to be passed to the
8172 ‘printf’ function as well. It is not sufficient to pass it only to
8175 In the English singular case, the number – always 1 – can be
8176 replaced with "one":
8178 printf (ngettext ("One file removed", "%d files removed", n), n);
8180 This works because the ‘printf’ function discards excess arguments
8181 that are not consumed by the format string.
8183 If this function is meant to yield a format string that takes two
8184 or more arguments, you can not use it like this:
8186 printf (ngettext ("%d file removed from directory %s",
8187 "%d files removed from directory %s",
8191 because in many languages the translators want to replace the ‘%d’
8192 with an explicit word in the singular case, just like “one” in
8193 English, and C format strings cannot consume the second argument
8194 but skip the first argument. Instead, you have to reorder the
8195 arguments so that ‘n’ comes last:
8197 printf (ngettext ("%$2d file removed from directory %$1s",
8198 "%$2d files removed from directory %$1s",
8202 See *note c-format:: for details about this argument reordering
8205 When you know that the value of ‘n’ is within a given range, you
8206 can specify it as a comment directed to the ‘xgettext’ tool. This
8207 information may help translators to use more adequate translations.
8210 if (days > 7 && days < 14)
8211 /* xgettext: range: 1..6 */
8212 printf (ngettext ("one week and one day", "one week and %d days",
8216 It is also possible to use this function when the strings don’t
8217 contain a cardinal number:
8219 puts (ngettext ("Delete the selected file?",
8220 "Delete the selected files?",
8223 In this case the number N is only used to choose the plural form.
8225 -- Function: char * dngettext (const char *DOMAIN, const char *MSGID1,
8226 const char *MSGID2, unsigned long int N)
8227 The ‘dngettext’ is similar to the ‘dgettext’ function in the way
8228 the message catalog is selected. The difference is that it takes
8229 two extra parameter to provide the correct plural form. These two
8230 parameters are handled in the same way ‘ngettext’ handles them.
8232 -- Function: char * dcngettext (const char *DOMAIN, const char *MSGID1,
8233 const char *MSGID2, unsigned long int N, int CATEGORY)
8234 The ‘dcngettext’ is similar to the ‘dcgettext’ function in the way
8235 the message catalog is selected. The difference is that it takes
8236 two extra parameter to provide the correct plural form. These two
8237 parameters are handled in the same way ‘ngettext’ handles them.
8239 Now, how do these functions solve the problem of the plural forms?
8240 Without the input of linguists (which was not available) it was not
8241 possible to determine whether there are only a few different forms in
8242 which plural forms are formed or whether the number can increase with
8243 every new supported language.
8245 Therefore the solution implemented is to allow the translator to
8246 specify the rules of how to select the plural form. Since the formula
8247 varies with every language this is the only viable solution except for
8248 hardcoding the information in the code (which still would require the
8249 possibility of extensions to not prevent the use of new languages).
8251 The information about the plural form selection has to be stored in
8252 the header entry of the PO file (the one with the empty ‘msgid’ string).
8253 The plural form information looks like this:
8255 Plural-Forms: nplurals=2; plural=n == 1 ? 0 : 1;
8257 The ‘nplurals’ value must be a decimal number which specifies how
8258 many different plural forms exist for this language. The string
8259 following ‘plural’ is an expression which is using the C language
8260 syntax. Exceptions are that no negative numbers are allowed, numbers
8261 must be decimal, and the only variable allowed is ‘n’. Spaces are
8262 allowed in the expression, but backslash-newlines are not; in the
8263 examples below the backslash-newlines are present for formatting
8264 purposes only. This expression will be evaluated whenever one of the
8265 functions ‘ngettext’, ‘dngettext’, or ‘dcngettext’ is called. The
8266 numeric value passed to these functions is then substituted for all uses
8267 of the variable ‘n’ in the expression. The resulting value then must be
8268 greater or equal to zero and smaller than the value given as the value
8271 The following rules are known at this point. The language with families
8272 are listed. But this does not necessarily mean the information can be
8273 generalized for the whole family (as can be easily seen in the table
8277 Some languages only require one single form. There is no
8278 distinction between the singular and plural form. An appropriate
8279 header entry would look like this:
8281 Plural-Forms: nplurals=1; plural=0;
8283 Languages with this property include:
8286 Japanese, Vietnamese, Korean
8290 Two forms, singular used for one only
8291 This is the form used in most existing programs since it is what
8292 English is using. A header entry would look like this:
8294 Plural-Forms: nplurals=2; plural=n != 1;
8296 (Note: this uses the feature of C expressions that boolean
8297 expressions have to value zero or one.)
8299 Languages with this property include:
8302 English, German, Dutch, Swedish, Danish, Norwegian, Faroese
8304 Spanish, Portuguese, Italian, Bulgarian
8316 Other languages using the same header entry are:
8320 Turkic/Altaic family
8323 Hungarian does not appear to have a plural if you look at sentences
8324 involving cardinal numbers. For example, “1 apple” is “1 alma”,
8325 and “123 apples” is “123 alma”. But when the number is not
8326 explicit, the distinction between singular and plural exists: “the
8327 apple” is “az alma”, and “the apples” is “az almák”. Since
8328 ‘ngettext’ has to support both types of sentences, it is classified
8329 here, under “two forms”.
8331 The same holds for Turkish: “1 apple” is “1 elma”, and “123 apples”
8332 is “123 elma”. But when the number is omitted, the distinction
8333 between singular and plural exists: “the apple” is “elma”, and “the
8334 apples” is “elmalar”.
8336 Two forms, singular used for zero and one
8337 Exceptional case in the language family. The header entry would
8340 Plural-Forms: nplurals=2; plural=n>1;
8342 Languages with this property include:
8345 Brazilian Portuguese, French
8347 Three forms, special case for zero
8348 The header entry would be:
8350 Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n != 0 ? 1 : 2;
8352 Languages with this property include:
8357 Three forms, special cases for one and two
8358 The header entry would be:
8360 Plural-Forms: nplurals=3; plural=n==1 ? 0 : n==2 ? 1 : 2;
8362 Languages with this property include:
8367 Three forms, special case for numbers ending in 00 or [2-9][0-9]
8368 The header entry would be:
8370 Plural-Forms: nplurals=3; \
8371 plural=n==1 ? 0 : (n==0 || (n%100 > 0 && n%100 < 20)) ? 1 : 2;
8373 Languages with this property include:
8378 Three forms, special case for numbers ending in 1[2-9]
8379 The header entry would look like this:
8381 Plural-Forms: nplurals=3; \
8382 plural=n%10==1 && n%100!=11 ? 0 : \
8383 n%10>=2 && (n%100<10 || n%100>=20) ? 1 : 2;
8385 Languages with this property include:
8390 Three forms, special cases for numbers ending in 1 and 2, 3, 4, except those ending in 1[1-4]
8391 The header entry would look like this:
8393 Plural-Forms: nplurals=3; \
8394 plural=n%10==1 && n%100!=11 ? 0 : \
8395 n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;
8397 Languages with this property include:
8400 Russian, Ukrainian, Belarusian, Serbian, Croatian
8402 Three forms, special cases for 1 and 2, 3, 4
8403 The header entry would look like this:
8405 Plural-Forms: nplurals=3; \
8406 plural=(n==1) ? 0 : (n>=2 && n<=4) ? 1 : 2;
8408 Languages with this property include:
8413 Three forms, special case for one and some numbers ending in 2, 3, or 4
8414 The header entry would look like this:
8416 Plural-Forms: nplurals=3; \
8418 n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;
8420 Languages with this property include:
8425 Four forms, special case for one and all numbers ending in 02, 03, or 04
8426 The header entry would look like this:
8428 Plural-Forms: nplurals=4; \
8429 plural=n%100==1 ? 0 : n%100==2 ? 1 : n%100==3 || n%100==4 ? 2 : 3;
8431 Languages with this property include:
8436 Six forms, special cases for one, two, all numbers ending in 02, 03, … 10, all numbers ending in 11 … 99, and others
8437 The header entry would look like this:
8439 Plural-Forms: nplurals=6; \
8440 plural=n==0 ? 0 : n==1 ? 1 : n==2 ? 2 : n%100>=3 && n%100<=10 ? 3 \
8441 : n%100>=11 ? 4 : 5;
8443 Languages with this property include:
8448 You might now ask, ‘ngettext’ handles only numbers N of type
8449 ‘unsigned long’. What about larger integer types? What about negative
8450 numbers? What about floating-point numbers?
8452 About larger integer types, such as ‘uintmax_t’ or ‘unsigned long
8453 long’: they can be handled by reducing the value to a range that fits in
8454 an ‘unsigned long’. Simply casting the value to ‘unsigned long’ would
8455 not do the right thing, since it would treat ‘ULONG_MAX + 1’ like zero,
8456 ‘ULONG_MAX + 2’ like singular, and the like. Here you can exploit the
8457 fact that all mentioned plural form formulas eventually become periodic,
8458 with a period that is a divisor of 100 (or 1000 or 1000000). So, when
8459 you reduce a large value to another one in the range [1000000, 1999999]
8460 that ends in the same 6 decimal digits, you can assume that it will lead
8461 to the same plural form selection. This code does this:
8463 #include <inttypes.h>
8464 uintmax_t nbytes = ...;
8465 printf (ngettext ("The file has %"PRIuMAX" byte.",
8466 "The file has %"PRIuMAX" bytes.",
8468 ? (nbytes % 1000000) + 1000000
8472 Negative and floating-point values usually represent physical
8473 entities for which singular and plural don’t clearly apply. In such
8474 cases, there is no need to use ‘ngettext’; a simple ‘gettext’ call with
8475 a form suitable for all values will do. For example:
8477 printf (gettext ("Time elapsed: %.3f seconds"),
8478 num_milliseconds * 0.001);
8480 Even if NUM_MILLISECONDS happens to be a multiple of 1000, the output
8481 Time elapsed: 1.000 seconds
8482 is acceptable in English, and similarly for other languages.
8484 The translators’ perspective regarding plural forms is explained in
8485 *note Translating plural forms::.
8487 ---------- Footnotes ----------
8489 (1) Additions are welcome. Send appropriate information to
8490 <bug-gnu-gettext@gnu.org> and <bug-glibc-manual@gnu.org>. The Unicode
8491 CLDR Project (<http://cldr.unicode.org>) provides a comprehensive set of
8492 plural forms in a different format. The ‘msginit’ program has
8493 preliminary support for the format so you can use it as a baseline
8494 (*note msginit Invocation::).
8497 File: gettext.info, Node: Optimized gettext, Prev: Plural forms, Up: gettext
8499 11.2.7 Optimization of the *gettext functions
8500 ---------------------------------------------
8502 At this point of the discussion we should talk about an advantage of
8503 the GNU ‘gettext’ implementation. Some readers might have pointed out
8504 that an internationalized program might have a poor performance if some
8505 string has to be translated in an inner loop. While this is unavoidable
8506 when the string varies from one run of the loop to the other it is
8507 simply a waste of time when the string is always the same. Take the
8513 puts (gettext ("Hello world"));
8517 When the locale selection does not change between two runs the resulting
8518 string is always the same. One way to use this is:
8521 str = gettext ("Hello world");
8528 But this solution is not usable in all situation (e.g. when the locale
8529 selection changes) nor does it lead to legible code.
8531 For this reason, GNU ‘gettext’ caches previous translation results.
8532 When the same translation is requested twice, with no new message
8533 catalogs being loaded in between, ‘gettext’ will, the second time, find
8534 the result through a single cache lookup.
8537 File: gettext.info, Node: Comparison, Next: Using libintl.a, Prev: gettext, Up: Programmers
8539 11.3 Comparing the Two Interfaces
8540 =================================
8542 The following discussion is perhaps a little bit colored. As said
8543 above we implemented GNU ‘gettext’ following the Uniforum proposal and
8544 this surely has its reasons. But it should show how we came to this
8547 First we take a look at the developing process. When we write an
8548 application using NLS provided by ‘gettext’ we proceed as always. Only
8549 when we come to a string which might be seen by the users and thus has
8550 to be translated we use ‘gettext("…")’ instead of ‘"…"’. At the
8551 beginning of each source file (or in a central header file) we define
8553 #define gettext(String) (String)
8555 Even this definition can be avoided when the system supports the
8556 ‘gettext’ function in its C library. When we compile this code the
8557 result is the same as if no NLS code is used. When you take a look at
8558 the GNU ‘gettext’ code you will see that we use ‘_("…")’ instead of
8559 ‘gettext("…")’. This reduces the number of additional characters per
8560 translatable string to _3_ (in words: three).
8562 When now a production version of the program is needed we simply
8563 replace the definition
8565 #define _(String) (String)
8569 #include <libintl.h>
8570 #define _(String) gettext (String)
8572 Additionally we run the program ‘xgettext’ on all source code file which
8573 contain translatable strings and that’s it: we have a running program
8574 which does not depend on translations to be available, but which can use
8575 any that becomes available.
8577 The same procedure can be done for the ‘gettext_noop’ invocations
8578 (*note Special cases::). One usually defines ‘gettext_noop’ as a no-op
8579 macro. So you should consider the following code for your project:
8581 #define gettext_noop(String) String
8582 #define N_(String) gettext_noop (String)
8584 ‘N_’ is a short form similar to ‘_’. The ‘Makefile’ in the ‘po/’
8585 directory of GNU ‘gettext’ knows by default both of the mentioned short
8586 forms so you are invited to follow this proposal for your own ease.
8588 Now to ‘catgets’. The main problem is the work for the programmer.
8589 Every time he comes to a translatable string he has to define a number
8590 (or a symbolic constant) which has also be defined in the message
8591 catalog file. He also has to take care for duplicate entries, duplicate
8592 message IDs etc. If he wants to have the same quality in the message
8593 catalog as the GNU ‘gettext’ program provides he also has to put the
8594 descriptive comments for the strings and the location in all source code
8595 files in the message catalog. This is nearly a Mission: Impossible.
8597 But there are also some points people might call advantages speaking
8598 for ‘catgets’. If you have a single word in a string and this string is
8599 used in different contexts it is likely that in one or the other
8600 language the word has different translations. Example:
8602 printf ("%s: %d", gettext ("number"), number_of_errors)
8604 printf ("you should see %d %s", number_count,
8605 number_count == 1 ? gettext ("number") : gettext ("numbers"))
8607 Here we have to translate two times the string ‘"number"’. Even if
8608 you do not speak a language beside English it might be possible to
8609 recognize that the two words have a different meaning. In German the
8610 first appearance has to be translated to ‘"Anzahl"’ and the second to
8613 Now you can say that this example is really esoteric. And you are
8614 right! This is exactly how we felt about this problem and decide that
8615 it does not weight that much. The solution for the above problem could
8618 printf ("%s %d", gettext ("number:"), number_of_errors)
8620 printf (number_count == 1 ? gettext ("you should see %d number")
8621 : gettext ("you should see %d numbers"),
8624 We believe that we can solve all conflicts with this method. If it
8625 is difficult one can also consider changing one of the conflicting
8626 string a little bit. But it is not impossible to overcome.
8628 ‘catgets’ allows same original entry to have different translations,
8629 but ‘gettext’ has another, scalable approach for solving ambiguities of
8630 this kind: *Note Ambiguities::.
8633 File: gettext.info, Node: Using libintl.a, Next: gettext grok, Prev: Comparison, Up: Programmers
8635 11.4 Using libintl.a in own programs
8636 ====================================
8638 Starting with version 0.9.4 the library ‘libintl.h’ should be
8639 self-contained. I.e., you can use it in your own programs without
8640 providing additional functions. The ‘Makefile’ will put the header and
8641 the library in directories selected using the ‘$(prefix)’.
8644 File: gettext.info, Node: gettext grok, Next: Temp Programmers, Prev: Using libintl.a, Up: Programmers
8646 11.5 Being a ‘gettext’ grok
8647 ===========================
8649 * NOTE: * This documentation section is outdated and needs to be
8652 To fully exploit the functionality of the GNU ‘gettext’ library it is
8653 surely helpful to read the source code. But for those who don’t want to
8654 spend that much time in reading the (sometimes complicated) code here is
8657 • Changing the language at runtime
8659 For interactive programs it might be useful to offer a selection of
8660 the used language at runtime. To understand how to do this one
8661 need to know how the used language is determined while executing
8662 the ‘gettext’ function. The method which is presented here only
8663 works correctly with the GNU implementation of the ‘gettext’
8666 In the function ‘dcgettext’ at every call the current setting of
8667 the highest priority environment variable is determined and used.
8668 Highest priority means here the following list with decreasing
8673 3. ‘LC_xxx’, according to selected locale category
8676 Afterwards the path is constructed using the found value and the
8677 translation file is loaded if available.
8679 What happens now when the value for, say, ‘LANGUAGE’ changes?
8680 According to the process explained above the new value of this
8681 variable is found as soon as the ‘dcgettext’ function is called.
8682 But this also means the (perhaps) different message catalog file is
8683 loaded. In other words: the used language is changed.
8685 But there is one little hook. The code for gcc-2.7.0 and up
8686 provides some optimization. This optimization normally prevents
8687 the calling of the ‘dcgettext’ function as long as no new catalog
8688 is loaded. But if ‘dcgettext’ is not called the program also
8689 cannot find the ‘LANGUAGE’ variable be changed (*note Optimized
8690 gettext::). A solution for this is very easy. Include the
8691 following code in the language switching function.
8693 /* Change language. */
8694 setenv ("LANGUAGE", "fr", 1);
8696 /* Make change known. */
8698 extern int _nl_msg_cat_cntr;
8702 The variable ‘_nl_msg_cat_cntr’ is defined in ‘loadmsgcat.c’. You
8703 don’t need to know what this is for. But it can be used to detect
8704 whether a ‘gettext’ implementation is GNU gettext and not non-GNU
8705 system’s native gettext implementation.
8708 File: gettext.info, Node: Temp Programmers, Prev: gettext grok, Up: Programmers
8710 11.6 Temporary Notes for the Programmers Chapter
8711 ================================================
8713 * NOTE: * This documentation section is outdated and needs to be
8718 * Temp Implementations:: Temporary - Two Possible Implementations
8719 * Temp catgets:: Temporary - About ‘catgets’
8720 * Temp WSI:: Temporary - Why a single implementation
8721 * Temp Notes:: Temporary - Notes
8724 File: gettext.info, Node: Temp Implementations, Next: Temp catgets, Prev: Temp Programmers, Up: Temp Programmers
8726 11.6.1 Temporary - Two Possible Implementations
8727 -----------------------------------------------
8729 There are two competing methods for language independent messages:
8730 the X/Open ‘catgets’ method, and the Uniforum ‘gettext’ method. The
8731 ‘catgets’ method indexes messages by integers; the ‘gettext’ method
8732 indexes them by their English translations. The ‘catgets’ method has
8733 been around longer and is supported by more vendors. The ‘gettext’
8734 method is supported by Sun, and it has been heard that the COSE
8735 multi-vendor initiative is supporting it. Neither method is a POSIX
8736 standard; the POSIX.1 committee had a lot of disagreement in this area.
8738 Neither one is in the POSIX standard. There was much disagreement in
8739 the POSIX.1 committee about using the ‘gettext’ routines vs. ‘catgets’
8740 (XPG). In the end the committee couldn’t agree on anything, so no
8741 messaging system was included as part of the standard. I believe the
8742 informative annex of the standard includes the XPG3 messaging
8743 interfaces, “…as an example of a messaging system that has been
8746 They were very careful not to say anywhere that you should use one
8747 set of interfaces over the other. For more on this topic please see the
8748 Programming for Internationalization FAQ.
8751 File: gettext.info, Node: Temp catgets, Next: Temp WSI, Prev: Temp Implementations, Up: Temp Programmers
8753 11.6.2 Temporary - About ‘catgets’
8754 ----------------------------------
8756 There have been a few discussions of late on the use of ‘catgets’ as
8757 a base. I think it important to present both sides of the argument and
8758 hence am opting to play devil’s advocate for a little bit.
8760 I’ll not deny the fact that ‘catgets’ could have been designed a lot
8761 better. It currently has quite a number of limitations and these have
8762 already been pointed out.
8764 However there is a great deal to be said for consistency and
8765 standardization. A common recurring problem when writing Unix software
8766 is the myriad portability problems across Unix platforms. It seems as
8767 if every Unix vendor had a look at the operating system and found parts
8768 they could improve upon. Undoubtedly, these modifications are probably
8769 innovative and solve real problems. However, software developers have a
8770 hard time keeping up with all these changes across so many platforms.
8772 And this has prompted the Unix vendors to begin to standardize their
8773 systems. Hence the impetus for Spec1170. Every major Unix vendor has
8774 committed to supporting this standard and every Unix software developer
8775 waits with glee the day they can write software to this standard and
8776 simply recompile (without having to use autoconf) across different
8779 As I understand it, Spec1170 is roughly based upon version 4 of the
8780 X/Open Portability Guidelines (XPG4). Because ‘catgets’ and friends are
8781 defined in XPG4, I’m led to believe that ‘catgets’ is a part of Spec1170
8782 and hence will become a standardized component of all Unix systems.
8785 File: gettext.info, Node: Temp WSI, Next: Temp Notes, Prev: Temp catgets, Up: Temp Programmers
8787 11.6.3 Temporary - Why a single implementation
8788 ----------------------------------------------
8790 Now it seems kind of wasteful to me to have two different systems
8791 installed for accessing message catalogs. If we do want to remedy
8792 ‘catgets’ deficiencies why don’t we try to expand ‘catgets’ (in a
8793 compatible manner) rather than implement an entirely new system.
8794 Otherwise, we’ll end up with two message catalog access systems
8795 installed with an operating system - one set of routines for packages
8796 using GNU ‘gettext’ for their internationalization, and another set of
8797 routines (catgets) for all other software. Bloated?
8799 Supposing another catalog access system is implemented. Which do we
8800 recommend? At least for Linux, we need to attract as many software
8801 developers as possible. Hence we need to make it as easy for them to
8802 port their software as possible. Which means supporting ‘catgets’. We
8803 will be implementing the ‘libintl’ code within our ‘libc’, but does this
8804 mean we also have to incorporate another message catalog access scheme
8805 within our ‘libc’ as well? And what about people who are going to be
8806 using the ‘libintl’ + non-‘catgets’ routines. When they port their
8807 software to other platforms, they’re now going to have to include the
8808 front-end (‘libintl’) code plus the back-end code (the non-‘catgets’
8809 access routines) with their software instead of just including the
8810 ‘libintl’ code with their software.
8812 Message catalog support is however only the tip of the iceberg. What
8813 about the data for the other locale categories? They also have a number
8814 of deficiencies. Are we going to abandon them as well and develop
8815 another duplicate set of routines (should ‘libintl’ expand beyond
8816 message catalog support)?
8818 Like many parts of Unix that can be improved upon, we’re stuck with
8819 balancing compatibility with the past with useful improvements and
8820 innovations for the future.
8823 File: gettext.info, Node: Temp Notes, Prev: Temp WSI, Up: Temp Programmers
8825 11.6.4 Temporary - Notes
8826 ------------------------
8828 X/Open agreed very late on the standard form so that many
8829 implementations differ from the final form. Both of my system (old
8830 Linux catgets and Ultrix-4) have a strange variation.
8832 OK. After incorporating the last changes I have to spend some time on
8833 making the GNU/Linux ‘libc’ ‘gettext’ functions. So in future Solaris
8834 is not the only system having ‘gettext’.
8837 File: gettext.info, Node: Translators, Next: Maintainers, Prev: Programmers, Up: Top
8839 12 The Translator’s View
8840 ************************
8844 * Trans Intro 0:: Introduction 0
8845 * Trans Intro 1:: Introduction 1
8846 * Discussions:: Discussions
8847 * Organization:: Organization
8848 * Information Flow:: Information Flow
8849 * Translating plural forms:: How to fill in ‘msgstr[0]’, ‘msgstr[1]’
8850 * Prioritizing messages:: How to find which messages to translate first
8853 File: gettext.info, Node: Trans Intro 0, Next: Trans Intro 1, Prev: Translators, Up: Translators
8858 * NOTE: * This documentation section is outdated and needs to be
8861 Free software is going international! The Translation Project is a
8862 way to get maintainers, translators and users all together, so free
8863 software will gradually become able to speak many native languages.
8865 The GNU ‘gettext’ tool set contains _everything_ maintainers need for
8866 internationalizing their packages for messages. It also contains quite
8867 useful tools for helping translators at localizing messages to their
8868 native language, once a package has already been internationalized.
8870 To achieve the Translation Project, we need many interested people
8871 who like their own language and write it well, and who are also able to
8872 synergize with other translators speaking the same language. If you’d
8873 like to volunteer to _work_ at translating messages, please send mail to
8874 your translating team.
8876 Each team has its own mailing list, courtesy of Linux International.
8877 You may reach your translating team at the address ‘LL@li.org’,
8878 replacing LL by the two-letter ISO 639 code for your language. Language
8879 codes are _not_ the same as country codes given in ISO 3166. The
8880 following translating teams exist:
8882 Chinese ‘zh’, Czech ‘cs’, Danish ‘da’, Dutch ‘nl’, Esperanto ‘eo’,
8883 Finnish ‘fi’, French ‘fr’, Irish ‘ga’, German ‘de’, Greek ‘el’,
8884 Italian ‘it’, Japanese ‘ja’, Indonesian ‘in’, Norwegian ‘no’,
8885 Polish ‘pl’, Portuguese ‘pt’, Russian ‘ru’, Spanish ‘es’, Swedish
8886 ‘sv’ and Turkish ‘tr’.
8888 For example, you may reach the Chinese translating team by writing to
8889 ‘zh@li.org’. When you become a member of the translating team for your
8890 own language, you may subscribe to its list. For example, Swedish
8891 people can send a message to ‘sv-request@li.org’, having this message
8896 Keep in mind that team members should be interested in _working_ at
8897 translations, or at solving translational difficulties, rather than
8898 merely lurking around. If your team does not exist yet and you want to
8899 start one, please write to ‘coordinator@translationproject.org’; you
8900 will then reach the coordinator for all translator teams.
8902 A handful of GNU packages have already been adapted and provided with
8903 message translations for several languages. Translation teams have
8904 begun to organize, using these packages as a starting point. But there
8905 are many more packages and many languages for which we have no volunteer
8906 translators. If you would like to volunteer to work at translating
8907 messages, please send mail to ‘coordinator@translationproject.org’
8908 indicating what language(s) you can work on.
8911 File: gettext.info, Node: Trans Intro 1, Next: Discussions, Prev: Trans Intro 0, Up: Translators
8916 * NOTE: * This documentation section is outdated and needs to be
8919 This is now official, GNU is going international! Here is the
8920 announcement submitted for the January 1995 GNU Bulletin:
8922 A handful of GNU packages have already been adapted and provided
8923 with message translations for several languages. Translation teams
8924 have begun to organize, using these packages as a starting point.
8925 But there are many more packages and many languages for which we
8926 have no volunteer translators. If you’d like to volunteer to work
8927 at translating messages, please send mail to
8928 ‘coordinator@translationproject.org’ indicating what language(s)
8931 This document should answer many questions for those who are curious
8932 about the process or would like to contribute. Please at least skim
8933 over it, hoping to cut down a little of the high volume of e-mail
8934 generated by this collective effort towards internationalization of free
8937 Most free programming which is widely shared is done in English, and
8938 currently, English is used as the main communicating language between
8939 national communities collaborating to free software. This very document
8940 is written in English. This will not change in the foreseeable future.
8942 However, there is a strong appetite from national communities for
8943 having more software able to write using national language and habits,
8944 and there is an on-going effort to modify free software in such a way
8945 that it becomes able to do so. The experiments driven so far raised an
8946 enthusiastic response from pretesters, so we believe that
8947 internationalization of free software is dedicated to succeed.
8949 For suggestion clarifications, additions or corrections to this
8950 document, please e-mail to ‘coordinator@translationproject.org’.
8953 File: gettext.info, Node: Discussions, Next: Organization, Prev: Trans Intro 1, Up: Translators
8958 * NOTE: * This documentation section is outdated and needs to be
8961 Facing this internationalization effort, a few users expressed their
8962 concerns. Some of these doubts are presented and discussed, here.
8966 Some languages are not spoken by a very large number of people, so
8967 people speaking them sometimes consider that there may not be all
8968 that much demand such versions of free software packages.
8969 Moreover, many people being _into computers_, in some countries,
8970 generally seem to prefer English versions of their software.
8972 On the other end, people might enjoy their own language a lot, and
8973 be very motivated at providing to themselves the pleasure of having
8974 their beloved free software speaking their mother tongue. They do
8975 themselves a personal favor, and do not pay that much attention to
8976 the number of people benefiting of their work.
8980 Other users are shy to push forward their own language, seeing in
8981 this some kind of misplaced propaganda. Someone thought there must
8982 be some users of the language over the networks pestering other
8985 But any spoken language is worth localization, because there are
8986 people behind the language for whom the language is important and
8987 dear to their hearts.
8991 The biggest problem is to find the right translations so that
8992 everybody can understand the messages. Translations are usually a
8993 little odd. Some people get used to English, to the extent they
8994 may find translations into their own language “rather pushy,
8995 obnoxious and sometimes even hilarious.” As a French speaking man,
8996 I have the experience of those instruction manuals for goods, so
8997 poorly translated in French in Korea or Taiwan…
8999 The fact is that we sometimes have to create a kind of national
9000 computer culture, and this is not easy without the collaboration of
9001 many people liking their mother tongue. This is why translations
9002 are better achieved by people knowing and loving their own
9003 language, and ready to work together at improving the results they
9006 • Dependencies over the GPL or LGPL
9008 Some people wonder if using GNU ‘gettext’ necessarily brings their
9009 package under the protective wing of the GNU General Public License
9010 or the GNU Lesser General Public License, when they do not want to
9011 make their program free, or want other kinds of freedom. The
9012 simplest answer is “normally not”.
9014 The ‘gettext-runtime’ part of GNU ‘gettext’, i.e. the contents of
9015 ‘libintl’, is covered by the GNU Lesser General Public License.
9016 The ‘gettext-tools’ part of GNU ‘gettext’, i.e. the rest of the GNU
9017 ‘gettext’ package, is covered by the GNU General Public License.
9019 The mere marking of localizable strings in a package, or
9020 conditional inclusion of a few lines for initialization, is not
9021 really including GPL’ed or LGPL’ed code. However, since the
9022 localization routines in ‘libintl’ are under the LGPL, the LGPL
9023 needs to be considered. It gives the right to distribute the
9024 complete unmodified source of ‘libintl’ even with non-free
9025 programs. It also gives the right to use ‘libintl’ as a shared
9026 library, even for non-free programs. But it gives the right to use
9027 ‘libintl’ as a static library or to incorporate ‘libintl’ into
9028 another library only to free software.
9031 File: gettext.info, Node: Organization, Next: Information Flow, Prev: Discussions, Up: Translators
9036 * NOTE: * This documentation section is outdated and needs to be
9039 On a larger scale, the true solution would be to organize some kind
9040 of fairly precise set up in which volunteers could participate. I gave
9041 some thought to this idea lately, and realize there will be some touchy
9042 points. I thought of writing to Richard Stallman to launch such a
9043 project, but feel it might be good to shake out the ideas between
9044 ourselves first. Most probably that Linux International has some
9045 experience in the field already, or would like to orchestrate the
9046 volunteer work, maybe. Food for thought, in any case!
9048 I guess we have to setup something early, somehow, that will help
9049 many possible contributors of the same language to interlock and avoid
9050 work duplication, and further be put in contact for solving together
9051 problems particular to their tongue (in most languages, there are many
9052 difficulties peculiar to translating technical English). My Swedish
9053 contributor acknowledged these difficulties, and I’m well aware of them
9056 This is surely not a technical issue, but we should manage so the
9057 effort of locale contributors be maximally useful, despite the national
9058 team layer interface between contributors and maintainers.
9060 The Translation Project needs some setup for coordinating language
9061 coordinators. Localizing evolving programs will surely become a
9062 permanent and continuous activity in the free software community, once
9063 well started. The setup should be minimally completed and tested before
9064 GNU ‘gettext’ becomes an official reality. The e-mail address
9065 ‘coordinator@translationproject.org’ has been set up for receiving
9066 offers from volunteers and general e-mail on these topics. This address
9067 reaches the Translation Project coordinator.
9071 * Central Coordination:: Central Coordination
9072 * National Teams:: National Teams
9073 * Mailing Lists:: Mailing Lists
9076 File: gettext.info, Node: Central Coordination, Next: National Teams, Prev: Organization, Up: Organization
9078 12.4.1 Central Coordination
9079 ---------------------------
9081 I also think GNU will need sooner than it thinks, that someone set up
9082 a way to organize and coordinate these groups. Some kind of group of
9083 groups. My opinion is that it would be good that GNU delegates this
9084 task to a small group of collaborating volunteers, shortly. Perhaps in
9085 ‘gnu.announce’ a list of this national committee’s can be published.
9087 My role as coordinator would simply be to refer to Ulrich any German
9088 speaking volunteer interested to localization of free software packages,
9089 and maybe helping national groups to initially organize, while
9090 maintaining national registries for until national groups are ready to
9091 take over. In fact, the coordinator should ease volunteers to get in
9092 contact with one another for creating national teams, which should then
9093 select one coordinator per language, or country (regionalized language).
9094 If well done, the coordination should be useful without being an
9095 overwhelming task, the time to put delegations in place.
9098 File: gettext.info, Node: National Teams, Next: Mailing Lists, Prev: Central Coordination, Up: Organization
9100 12.4.2 National Teams
9101 ---------------------
9103 I suggest we look for volunteer coordinators/editors for individual
9104 languages. These people will scan contributions of translation files
9105 for various programs, for their own languages, and will ensure high and
9106 uniform standards of diction.
9108 From my current experience with other people in these days, those who
9109 provide localizations are very enthusiastic about the process, and are
9110 more interested in the localization process than in the program they
9111 localize, and want to do many programs, not just one. This seems to
9112 confirm that having a coordinator/editor for each language is a good
9115 We need to choose someone who is good at writing clear and concise
9116 prose in the language in question. That is hard—we can’t check it
9117 ourselves. So we need to ask a few people to judge each others’ writing
9118 and select the one who is best.
9120 I announce my prerelease to a few dozen people, and you would not
9121 believe all the discussions it generated already. I shudder to think
9122 what will happen when this will be launched, for true, officially, world
9123 wide. Who am I to arbitrate between two Czekolsovak users contradicting
9124 each other, for example?
9126 I assume that your German is not much better than my French so that I
9127 would not be able to judge about these formulations. What I would
9128 suggest is that for each language there is a group for people who
9129 maintain the PO files and judge about changes. I suspect there will be
9130 cultural differences between how such groups of people will behave.
9131 Some will have relaxed ways, reach consensus easily, and have anyone of
9132 the group relate to the maintainers, while others will fight to death,
9133 organize heavy administrations up to national standards, and use strict
9136 The German team is putting out a good example. Right now, they are
9137 maybe half a dozen people revising translations of each other and
9138 discussing the linguistic issues. I do not even have all the names.
9139 Ulrich Drepper is taking care of coordinating the German team. He
9140 subscribed to all my pretest lists, so I do not even have to warn him
9141 specifically of incoming releases.
9143 I’m sure, that is a good idea to get teams for each language working
9144 on translations. That will make the translations better and more
9149 * Sub-Cultures:: Sub-Cultures
9150 * Organizational Ideas:: Organizational Ideas
9153 File: gettext.info, Node: Sub-Cultures, Next: Organizational Ideas, Prev: National Teams, Up: National Teams
9155 12.4.2.1 Sub-Cultures
9156 .....................
9158 Taking French for example, there are a few sub-cultures around
9159 computers which developed diverging vocabularies. Picking volunteers
9160 here and there without addressing this problem in an organized way, soon
9161 in the project, might produce a distasteful mix of internationalized
9162 programs, and possibly trigger endless quarrels among those who really
9165 Keeping some kind of unity in the way French localization of
9166 internationalized programs is achieved is a difficult (and delicate)
9167 job. Knowing the latin character of French people (:-), if we take this
9168 the wrong way, we could end up nowhere, or spoil a lot of energies.
9169 Maybe we should begin to address this problem seriously _before_ GNU
9170 ‘gettext’ become officially published. And I suspect that this means
9174 File: gettext.info, Node: Organizational Ideas, Prev: Sub-Cultures, Up: National Teams
9176 12.4.2.2 Organizational Ideas
9177 .............................
9179 I expect the next big changes after the official release. Please
9180 note that I use the German translation of the short GPL message. We
9181 need to set a few good examples before the localization goes out for
9182 true in the free software community. Here are a few points to discuss:
9184 • Each group should have one FTP server (at least one master).
9186 • The files on the server should reflect the latest version (of
9187 course!) and it should also contain a RCS directory with the
9188 corresponding archives (I don’t have this now).
9190 • There should also be a ChangeLog file (this is more useful than the
9191 RCS archive but can be generated automatically from the later by
9194 • A "core group" should judge about questionable changes (for now
9195 this group consists solely by me but I ask some others
9196 occasionally; this also seems to work).
9199 File: gettext.info, Node: Mailing Lists, Prev: National Teams, Up: Organization
9201 12.4.3 Mailing Lists
9202 --------------------
9204 If we get any inquiries about GNU ‘gettext’, send them on to:
9206 coordinator@translationproject.org
9208 The ‘*-pretest’ lists are quite useful to me, maybe the idea could be
9209 generalized to many GNU, and non-GNU packages. But each maintainer
9212 François, we have a mechanism in place here at ‘gnu.ai.mit.edu’ to
9213 track teams, support mailing lists for them and log members. We have a
9214 slight preference that you use it. If this is OK with you, I can get
9217 Things are changing! A few years ago, when Daniel Fekete and I asked
9218 for a mailing list for GNU localization, nested at the FSF, we were
9219 politely invited to organize it anywhere else, and so did we. For
9220 communicating with my pretesters, I later made a handful of mailing
9221 lists located at iro.umontreal.ca and administrated by ‘majordomo’.
9222 These lists have been _very_ dependable so far…
9224 I suspect that the German team will organize itself a mailing list
9225 located in Germany, and so forth for other countries. But before they
9226 organize for true, it could surely be useful to offer mailing lists
9227 located at the FSF to each national team. So yes, please explain me how
9228 I should proceed to create and handle them.
9230 We should create temporary mailing lists, one per country, to help
9231 people organize. Temporary, because once regrouped and structured, it
9232 would be fair the volunteers from country bring back _their_ list in
9233 there and manage it as they want. My feeling is that, in the long run,
9234 each team should run its own list, from within their country. There
9235 also should be some central list to which all teams could subscribe as
9236 they see fit, as long as each team is represented in it.
9239 File: gettext.info, Node: Information Flow, Next: Translating plural forms, Prev: Organization, Up: Translators
9241 12.5 Information Flow
9242 =====================
9244 * NOTE: * This documentation section is outdated and needs to be
9247 There will surely be some discussion about this messages after the
9248 packages are finally released. If people now send you some proposals
9249 for better messages, how do you proceed? Jim, please note that right
9250 now, as I put forward nearly a dozen of localizable programs, I receive
9251 both the translations and the coordination concerns about them.
9253 If I put one of my things to pretest, Ulrich receives the
9254 announcement and passes it on to the German team, who make last minute
9255 revisions. Then he submits the translation files to me _as the
9256 maintainer_. For free packages I do not maintain, I would not even hear
9257 about it. This scheme could be made to work for the whole Translation
9258 Project, I think. For security reasons, maybe Ulrich (national
9259 coordinators, in fact) should update central registry kept at the
9260 Translation Project (Jim, me, or Len’s recruits) once in a while.
9262 In December/January, I was aggressively ready to internationalize all
9263 of GNU, giving myself the duty of one small GNU package per week or so,
9264 taking many weeks or months for bigger packages. But it does not work
9265 this way. I first did all the things I’m responsible for. I’ve nothing
9266 against some missionary work on other maintainers, but I’m also losing a
9267 lot of energy over it—same debates over again.
9269 And when the first localized packages are released we’ll get a lot of
9270 responses about ugly translations :-). Surely, and we need to have
9271 beforehand a fairly good idea about how to handle the information flow
9272 between the national teams and the package maintainers.
9274 Please start saving somewhere a quick history of each PO file. I
9275 know for sure that the file format will change, allowing for comments.
9276 It would be nice that each file has a kind of log, and references for
9277 those who want to submit comments or gripes, or otherwise contribute. I
9278 sent a proposal for a fast and flexible format, but it is not receiving
9279 acceptance yet by the GNU deciders. I’ll tell you when I have more
9280 information about this.
9283 File: gettext.info, Node: Translating plural forms, Next: Prioritizing messages, Prev: Information Flow, Up: Translators
9285 12.6 Translating plural forms
9286 =============================
9288 Suppose you are translating a PO file, and it contains an entry like
9292 msgid "One file removed"
9293 msgid_plural "%d files removed"
9297 What does this mean? How do you fill it in?
9299 Such an entry denotes a message with plural forms, that is, a message
9300 where the text depends on a cardinal number. The general form of the
9301 message, in English, is the ‘msgid_plural’ line. The ‘msgid’ line is
9302 the English singular form, that is, the form for when the number is
9303 equal to 1. More details about plural forms are explained in *note
9306 The first thing you need to look at is the ‘Plural-Forms’ line in the
9307 header entry of the PO file. It contains the number of plural forms and
9308 a formula. If the PO file does not yet have such a line, you have to
9309 add it. It only depends on the language into which you are translating.
9310 You can get this info by using the ‘msginit’ command (see *note
9311 Creating::) – it contains a database of known plural formulas – or by
9312 asking other members of your translation team.
9314 Suppose the line looks as follows:
9316 "Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n%10>=2 && n"
9317 "%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;\n"
9319 It’s logically one line; recall that the PO file formatting is
9320 allowed to break long lines so that each physical line fits in 80
9323 The value of ‘nplurals’ here tells you that there are three plural
9324 forms. The first thing you need to do is to ensure that the entry
9325 contains an ‘msgstr’ line for each of the forms:
9328 msgid "One file removed"
9329 msgid_plural "%d files removed"
9334 Then translate the ‘msgid_plural’ line and fill it in into each
9338 msgid "One file removed"
9339 msgid_plural "%d files removed"
9340 msgstr[0] "%d slika uklonjenih"
9341 msgstr[1] "%d slika uklonjenih"
9342 msgstr[2] "%d slika uklonjenih"
9344 Now you can refine the translation so that it matches the plural
9345 form. According to the formula above, ‘msgstr[0]’ is used when the
9346 number ends in 1 but does not end in 11; ‘msgstr[1]’ is used when the
9347 number ends in 2, 3, 4, but not in 12, 13, 14; and ‘msgstr[2]’ is used
9348 in all other cases. With this knowledge, you can refine the
9352 msgid "One file removed"
9353 msgid_plural "%d files removed"
9354 msgstr[0] "%d slika je uklonjena"
9355 msgstr[1] "%d datoteke uklonjenih"
9356 msgstr[2] "%d slika uklonjenih"
9358 You noticed that in the English singular form (‘msgid’) the number
9359 placeholder could be omitted and replaced by the numeral word “one”.
9360 Can you do this in your translation as well?
9362 msgstr[0] "jednom datotekom je uklonjen"
9364 Well, it depends on whether ‘msgstr[0]’ applies only to the number 1, or
9365 to other numbers as well. If, according to the plural formula,
9366 ‘msgstr[0]’ applies only to ‘n == 1’, then you can use the specialized
9367 translation without the number placeholder. In our case, however,
9368 ‘msgstr[0]’ also applies to the numbers 21, 31, 41, etc., and therefore
9369 you cannot omit the placeholder.
9372 File: gettext.info, Node: Prioritizing messages, Prev: Translating plural forms, Up: Translators
9374 12.7 Prioritizing messages: How to determine which messages to translate first
9375 ==============================================================================
9377 A translator sometimes has only a limited amount of time per week to
9378 spend on a package, and some packages have quite large message catalogs
9379 (over 1000 messages). Therefore she wishes to translate the messages
9380 first that are the most visible to the user, or that occur most
9381 frequently. This section describes how to determine these "most urgent"
9382 messages. It also applies to determine the "next most urgent" messages
9383 after the message catalog has already been partially translated.
9385 In a first step, she uses the programs like a user would do. While
9386 she does this, the GNU ‘gettext’ library logs into a file the not yet
9387 translated messages for which a translation was requested from the
9390 In a second step, she uses the PO mode to translate precisely this
9393 Here a more details. The GNU ‘libintl’ library (but not the
9394 corresponding functions in GNU ‘libc’) supports an environment variable
9395 ‘GETTEXT_LOG_UNTRANSLATED’. The GNU ‘libintl’ library will log into
9396 this file the messages for which ‘gettext()’ and related functions
9397 couldn’t find the translation. If the file doesn’t exist, it will be
9398 created as needed. On systems with GNU ‘libc’ a shared library
9399 ‘preloadable_libintl.so’ is provided that can be used with the ELF
9400 ‘LD_PRELOAD’ mechanism.
9402 So, in the first step, the translator uses these commands on systems
9405 $ LD_PRELOAD=/usr/local/lib/preloadable_libintl.so
9407 $ GETTEXT_LOG_UNTRANSLATED=$HOME/gettextlogused
9408 $ export GETTEXT_LOG_UNTRANSLATED
9410 and these commands on other systems:
9412 $ GETTEXT_LOG_UNTRANSLATED=$HOME/gettextlogused
9413 $ export GETTEXT_LOG_UNTRANSLATED
9415 Then she uses and peruses the programs. (It is a good and
9416 recommended practice to use the programs for which you provide
9417 translations: it gives you the needed context.) When done, she removes
9418 the environment variables:
9421 $ unset GETTEXT_LOG_UNTRANSLATED
9423 The second step starts with removing duplicates:
9425 $ msguniq $HOME/gettextlogused > missing.po
9427 The result is a PO file, but needs some preprocessing before a PO
9428 file editor can be used with it. First, it is a multi-domain PO file,
9429 containing messages from many translation domains. Second, it lacks all
9430 translator comments and source references. Here is how to get a list of
9431 the affected translation domains:
9433 $ sed -n -e 's,^domain "\(.*\)"$,\1,p' < missing.po | sort | uniq
9435 Then the translator can handle the domains one by one. For
9436 simplicity, let’s use environment variables to denote the language,
9437 domain and source package.
9439 $ lang=nl # your language
9440 $ domain=coreutils # the name of the domain to be handled
9441 $ package=/usr/src/gnu/coreutils-4.5.4 # the package where it comes from
9443 She takes the latest copy of ‘$lang.po’ from the Translation Project,
9444 or from the package (in most cases, ‘$package/po/$lang.po’), or creates
9445 a fresh one if she’s the first translator (see *note Creating::). She
9446 then uses the following commands to mark the not urgent messages as
9447 "obsolete". (This doesn’t mean that these messages - translated and
9448 untranslated ones - will go away. It simply means that the PO file
9449 editor will ignore them in the following editing session.)
9451 $ msggrep --domain=$domain missing.po | grep -v '^domain' \
9452 > $domain-missing.po
9453 $ msgattrib --set-obsolete --ignore-file $domain-missing.po $domain.$lang.po \
9454 > $domain.$lang-urgent.po
9456 The she translates ‘$domain.$lang-urgent.po’ by use of a PO file
9457 editor (*note Editing::). (FIXME: I don’t know whether ‘KBabel’ and
9458 ‘gtranslator’ also preserve obsolete messages, as they should.) Finally
9459 she restores the not urgent messages (with their earlier translations,
9460 for those which were already translated) through this command:
9462 $ msgmerge --no-fuzzy-matching $domain.$lang-urgent.po $package/po/$domain.pot \
9465 Then she can submit ‘$domain.$lang.po’ and proceed to the next
9469 File: gettext.info, Node: Maintainers, Next: Installers, Prev: Translators, Up: Top
9471 13 The Maintainer’s View
9472 ************************
9474 The maintainer of a package has many responsibilities. One of them
9475 is ensuring that the package will install easily on many platforms, and
9476 that the magic we described earlier (*note Users::) will work for
9477 installers and end users.
9479 Of course, there are many possible ways by which GNU ‘gettext’ might
9480 be integrated in a distribution, and this chapter does not cover them in
9481 all generality. Instead, it details one possible approach which is
9482 especially adequate for many free software distributions following GNU
9483 standards, or even better, Gnits standards, because GNU ‘gettext’ is
9484 purposely for helping the internationalization of the whole GNU project,
9485 and as many other good free packages as possible. So, the maintainer’s
9486 view presented here presumes that the package already has a
9487 ‘configure.ac’ file and uses GNU Autoconf.
9489 Nevertheless, GNU ‘gettext’ may surely be useful for free packages
9490 not following GNU standards and conventions, but the maintainers of such
9491 packages might have to show imagination and initiative in organizing
9492 their distributions so ‘gettext’ work for them in all situations. There
9493 are surely many, out there.
9495 Even if ‘gettext’ methods are now stabilizing, slight adjustments
9496 might be needed between successive ‘gettext’ versions, so you should
9497 ideally revise this chapter in subsequent releases, looking for changes.
9501 * Flat and Non-Flat:: Flat or Non-Flat Directory Structures
9502 * Prerequisites:: Prerequisite Works
9503 * gettextize Invocation:: Invoking the ‘gettextize’ Program
9504 * Adjusting Files:: Files You Must Create or Alter
9505 * autoconf macros:: Autoconf macros for use in ‘configure.ac’
9506 * Version Control Issues::
9507 * Release Management:: Creating a Distribution Tarball
9510 File: gettext.info, Node: Flat and Non-Flat, Next: Prerequisites, Prev: Maintainers, Up: Maintainers
9512 13.1 Flat or Non-Flat Directory Structures
9513 ==========================================
9515 Some free software packages are distributed as ‘tar’ files which
9516 unpack in a single directory, these are said to be "flat" distributions.
9517 Other free software packages have a one level hierarchy of
9518 subdirectories, using for example a subdirectory named ‘doc/’ for the
9519 Texinfo manual and man pages, another called ‘lib/’ for holding
9520 functions meant to replace or complement C libraries, and a subdirectory
9521 ‘src/’ for holding the proper sources for the package. These other
9522 distributions are said to be "non-flat".
9524 We cannot say much about flat distributions. A flat directory
9525 structure has the disadvantage of increasing the difficulty of updating
9526 to a new version of GNU ‘gettext’. Also, if you have many PO files,
9527 this could somewhat pollute your single directory. Also, GNU
9528 ‘gettext’’s libintl sources consist of C sources, shell scripts, ‘sed’
9529 scripts and complicated Makefile rules, which don’t fit well into an
9530 existing flat structure. For these reasons, we recommend to use
9531 non-flat approach in this case as well.
9533 Maybe because GNU ‘gettext’ itself has a non-flat structure, we have
9534 more experience with this approach, and this is what will be described
9535 in the remaining of this chapter. Some maintainers might use this as an
9536 opportunity to unflatten their package structure.
9539 File: gettext.info, Node: Prerequisites, Next: gettextize Invocation, Prev: Flat and Non-Flat, Up: Maintainers
9541 13.2 Prerequisite Works
9542 =======================
9544 There are some works which are required for using GNU ‘gettext’ in
9545 one of your package. These works have some kind of generality that
9546 escape the point by point descriptions used in the remainder of this
9547 chapter. So, we describe them here.
9549 • Before attempting to use ‘gettextize’ you should install some other
9550 packages first. Ensure that recent versions of GNU ‘m4’, GNU
9551 Autoconf and GNU ‘gettext’ are already installed at your site, and
9552 if not, proceed to do this first. If you get to install these
9553 things, beware that GNU ‘m4’ must be fully installed before GNU
9554 Autoconf is even _configured_.
9556 To further ease the task of a package maintainer the ‘automake’
9557 package was designed and implemented. GNU ‘gettext’ now uses this
9558 tool and the ‘Makefile’s in the ‘intl/’ and ‘po/’ therefore know
9559 about all the goals necessary for using ‘automake’ and ‘libintl’ in
9562 Those four packages are only needed by you, as a maintainer; the
9563 installers of your own package and end users do not really need any
9564 of GNU ‘m4’, GNU Autoconf, GNU ‘gettext’, or GNU ‘automake’ for
9565 successfully installing and running your package, with messages
9566 properly translated. But this is not completely true if you
9567 provide internationalized shell scripts within your own package:
9568 GNU ‘gettext’ shall then be installed at the user site if the end
9569 users want to see the translation of shell script messages.
9571 • Your package should use Autoconf and have a ‘configure.ac’ or
9572 ‘configure.in’ file. If it does not, you have to learn how. The
9573 Autoconf documentation is quite well written, it is a good idea
9574 that you print it and get familiar with it.
9576 • Your C sources should have already been modified according to
9577 instructions given earlier in this manual. *Note Sources::.
9579 • Your ‘po/’ directory should receive all PO files submitted to you
9580 by the translator teams, each having ‘LL.po’ as a name. This is
9581 not usually easy to get translation work done before your package
9582 gets internationalized and available! Since the cycle has to start
9583 somewhere, the easiest for the maintainer is to start with
9584 absolutely no PO files, and wait until various translator teams get
9585 interested in your package, and submit PO files.
9587 It is worth adding here a few words about how the maintainer should
9588 ideally behave with PO files submissions. As a maintainer, your role is
9589 to authenticate the origin of the submission as being the representative
9590 of the appropriate translating teams of the Translation Project (forward
9591 the submission to ‘coordinator@translationproject.org’ in case of
9592 doubt), to ensure that the PO file format is not severely broken and
9593 does not prevent successful installation, and for the rest, to merely
9594 put these PO files in ‘po/’ for distribution.
9596 As a maintainer, you do not have to take on your shoulders the
9597 responsibility of checking if the translations are adequate or complete,
9598 and should avoid diving into linguistic matters. Translation teams
9599 drive themselves and are fully responsible of their linguistic choices
9600 for the Translation Project. Keep in mind that translator teams are
9601 _not_ driven by maintainers. You can help by carefully redirecting all
9602 communications and reports from users about linguistic matters to the
9603 appropriate translation team, or explain users how to reach or join
9604 their team. The simplest might be to send them the ‘ABOUT-NLS’ file.
9606 Maintainers should _never ever_ apply PO file bug reports themselves,
9607 short-cutting translation teams. If some translator has difficulty to
9608 get some of her points through her team, it should not be an option for
9609 her to directly negotiate translations with maintainers. Teams ought to
9610 settle their problems themselves, if any. If you, as a maintainer, ever
9611 think there is a real problem with a team, please never try to _solve_ a
9612 team’s problem on your own.
9615 File: gettext.info, Node: gettextize Invocation, Next: Adjusting Files, Prev: Prerequisites, Up: Maintainers
9617 13.3 Invoking the ‘gettextize’ Program
9618 ======================================
9620 The ‘gettextize’ program is an interactive tool that helps the
9621 maintainer of a package internationalized through GNU ‘gettext’. It is
9622 used for two purposes:
9624 • As a wizard, when a package is modified to use GNU ‘gettext’ for
9627 • As a migration tool, for upgrading the GNU ‘gettext’ support in a
9628 package from a previous to a newer version of GNU ‘gettext’.
9630 This program performs the following tasks:
9632 • It copies into the package some files that are consistently and
9633 identically needed in every package internationalized through GNU
9636 • It performs as many of the tasks mentioned in the next section
9637 *note Adjusting Files:: as can be performed automatically.
9639 • It removes obsolete files and idioms used for previous GNU
9640 ‘gettext’ versions to the form recommended for the current GNU
9643 • It prints a summary of the tasks that ought to be done manually and
9644 could not be done automatically by ‘gettextize’.
9646 It can be invoked as follows:
9648 gettextize [ OPTION… ] [ DIRECTORY ]
9650 and accepts the following options:
9654 Force replacement of files which already exist.
9657 Install the libintl sources in a subdirectory named ‘intl/’. This
9658 libintl will be used to provide internationalization on systems
9659 that don’t have GNU libintl installed. If this option is omitted,
9660 the call to ‘AM_GNU_GETTEXT’ in ‘configure.ac’ should read:
9661 ‘AM_GNU_GETTEXT([external])’, and internationalization will not be
9662 enabled on systems lacking GNU gettext.
9665 Specify a directory containing PO files. Such a directory contains
9666 the translations into various languages of a particular POT file.
9667 This option can be specified multiple times, once for each
9668 translation domain. If it is not specified, the directory named
9672 Don’t update or create ChangeLog files. By default, ‘gettextize’
9673 logs all changes (file additions, modifications and removals) in a
9674 file called ‘ChangeLog’ in each affected directory.
9677 Make symbolic links instead of copying the needed files. This can
9678 be useful to save a few kilobytes of disk space, but it requires
9679 extra effort to create self-contained tarballs, it may disturb some
9680 mechanism the maintainer applies to the sources, and it is likely
9681 to introduce bugs when a newer version of ‘gettext’ is installed on
9686 Print modifications but don’t perform them. All actions that
9687 ‘gettextize’ would normally execute are inhibited and instead only
9688 listed on standard output.
9691 Display this help and exit.
9694 Output version information and exit.
9696 If DIRECTORY is given, this is the top level directory of a package
9697 to prepare for using GNU ‘gettext’. If not given, it is assumed that
9698 the current directory is the top level directory of such a package.
9700 The program ‘gettextize’ provides the following files. However, no
9701 existing file will be replaced unless the option ‘--force’ (‘-f’) is
9704 1. The ‘ABOUT-NLS’ file is copied in the main directory of your
9705 package, the one being at the top level. This file gives the main
9706 indications about how to install and use the Native Language
9707 Support features of your program. You might elect to use a more
9708 recent copy of this ‘ABOUT-NLS’ file than the one provided through
9709 ‘gettextize’, if you have one handy. You may also fetch a more
9710 recent copy of file ‘ABOUT-NLS’ from Translation Project sites, and
9711 from most GNU archive sites.
9713 2. A ‘po/’ directory is created for eventually holding all translation
9714 files, but initially only containing the file ‘po/Makefile.in.in’
9715 from the GNU ‘gettext’ distribution (beware the double ‘.in’ in the
9716 file name) and a few auxiliary files. If the ‘po/’ directory
9717 already exists, it will be preserved along with the files it
9718 contains, and only ‘Makefile.in.in’ and the auxiliary files will be
9721 If ‘--po-dir’ has been specified, this holds for every directory
9722 specified through ‘--po-dir’, instead of ‘po/’.
9724 3. Only if ‘--intl’ has been specified: A ‘intl/’ directory is created
9725 and filled with most of the files originally in the ‘intl/’
9726 directory of the GNU ‘gettext’ distribution. Also, if option
9727 ‘--force’ (‘-f’) is given, the ‘intl/’ directory is emptied first.
9729 4. The file ‘config.rpath’ is copied into the directory containing
9730 configuration support files. It is needed by the ‘AM_GNU_GETTEXT’
9733 5. Only if the project is using GNU ‘automake’: A set of ‘autoconf’
9734 macro files is copied into the package’s ‘autoconf’ macro
9735 repository, usually in a directory called ‘m4/’.
9737 If your site support symbolic links, ‘gettextize’ will not actually
9738 copy the files into your package, but establish symbolic links instead.
9739 This avoids duplicating the disk space needed in all packages. Merely
9740 using the ‘-h’ option while creating the ‘tar’ archive of your
9741 distribution will resolve each link by an actual copy in the
9742 distribution archive. So, to insist, you really should use ‘-h’ option
9743 with ‘tar’ within your ‘dist’ goal of your main ‘Makefile.in’.
9745 Furthermore, ‘gettextize’ will update all ‘Makefile.am’ files in each
9746 affected directory, as well as the top level ‘configure.ac’ or
9747 ‘configure.in’ file.
9749 It is interesting to understand that most new files for supporting
9750 GNU ‘gettext’ facilities in one package go in ‘intl/’, ‘po/’ and ‘m4/’
9751 subdirectories. One distinction between ‘intl/’ and the two other
9752 directories is that ‘intl/’ is meant to be completely identical in all
9753 packages using GNU ‘gettext’, while the other directories will mostly
9754 contain package dependent files.
9756 The ‘gettextize’ program makes backup files for all files it replaces
9757 or changes, and also write ChangeLog entries about these changes. This
9758 way, the careful maintainer can check after running ‘gettextize’ whether
9759 its changes are acceptable to him, and possibly adjust them. An
9760 exception to this rule is the ‘intl/’ directory, which is added or
9761 replaced or removed as a whole.
9763 It is important to understand that ‘gettextize’ can not do the entire
9764 job of adapting a package for using GNU ‘gettext’. The amount of
9765 remaining work depends on whether the package uses GNU ‘automake’ or
9766 not. But in any case, the maintainer should still read the section
9767 *note Adjusting Files:: after invoking ‘gettextize’.
9769 In particular, if after using ‘gettexize’, you get an error
9770 ‘AC_COMPILE_IFELSE was called before AC_GNU_SOURCE’ or ‘AC_RUN_IFELSE
9771 was called before AC_GNU_SOURCE’, you can fix it by modifying
9772 ‘configure.ac’, as described in *note configure.ac::.
9774 It is also important to understand that ‘gettextize’ is not part of
9775 the GNU build system, in the sense that it should not be invoked
9776 automatically, and not be invoked by someone who doesn’t assume the
9777 responsibilities of a package maintainer. For the latter purpose, a
9778 separate tool is provided, see *note autopoint Invocation::.
9781 File: gettext.info, Node: Adjusting Files, Next: autoconf macros, Prev: gettextize Invocation, Up: Maintainers
9783 13.4 Files You Must Create or Alter
9784 ===================================
9786 Besides files which are automatically added through ‘gettextize’,
9787 there are many files needing revision for properly interacting with GNU
9788 ‘gettext’. If you are closely following GNU standards for Makefile
9789 engineering and auto-configuration, the adaptations should be easier to
9790 achieve. Here is a point by point description of the changes needed in
9793 So, here comes a list of files, each one followed by a description of
9794 all alterations it needs. Many examples are taken out from the GNU
9795 ‘gettext’ 0.19.7 distribution itself, or from the GNU ‘hello’
9796 distribution (<http://www.gnu.org/software/hello>). You may indeed
9797 refer to the source code of the GNU ‘gettext’ and GNU ‘hello’ packages,
9798 as they are intended to be good examples for using GNU gettext
9803 * po/POTFILES.in:: ‘POTFILES.in’ in ‘po/’
9804 * po/LINGUAS:: ‘LINGUAS’ in ‘po/’
9805 * po/Makevars:: ‘Makevars’ in ‘po/’
9806 * po/Rules-*:: Extending ‘Makefile’ in ‘po/’
9807 * configure.ac:: ‘configure.ac’ at top level
9808 * config.guess:: ‘config.guess’, ‘config.sub’ at top level
9809 * mkinstalldirs:: ‘mkinstalldirs’ at top level
9810 * aclocal:: ‘aclocal.m4’ at top level
9811 * acconfig:: ‘acconfig.h’ at top level
9812 * config.h.in:: ‘config.h.in’ at top level
9813 * Makefile:: ‘Makefile.in’ at top level
9814 * src/Makefile:: ‘Makefile.in’ in ‘src/’
9815 * lib/gettext.h:: ‘gettext.h’ in ‘lib/’
9818 File: gettext.info, Node: po/POTFILES.in, Next: po/LINGUAS, Prev: Adjusting Files, Up: Adjusting Files
9820 13.4.1 ‘POTFILES.in’ in ‘po/’
9821 -----------------------------
9823 The ‘po/’ directory should receive a file named ‘POTFILES.in’. This
9824 file tells which files, among all program sources, have marked strings
9825 needing translation. Here is an example of such a file:
9827 # List of source files containing translatable strings.
9828 # Copyright (C) 1995 Free Software Foundation, Inc.
9830 # Common library files
9835 # Package source files
9840 Hash-marked comments and white lines are ignored. All other lines list
9841 those source files containing strings marked for translation (*note Mark
9842 Keywords::), in a notation relative to the top level of your whole
9843 distribution, rather than the location of the ‘POTFILES.in’ file itself.
9845 When a C file is automatically generated by a tool, like ‘flex’ or
9846 ‘bison’, that doesn’t introduce translatable strings by itself, it is
9847 recommended to list in ‘po/POTFILES.in’ the real source file (ending in
9848 ‘.l’ in the case of ‘flex’, or in ‘.y’ in the case of ‘bison’), not the
9852 File: gettext.info, Node: po/LINGUAS, Next: po/Makevars, Prev: po/POTFILES.in, Up: Adjusting Files
9854 13.4.2 ‘LINGUAS’ in ‘po/’
9855 -------------------------
9857 The ‘po/’ directory should also receive a file named ‘LINGUAS’. This
9858 file contains the list of available translations. It is a whitespace
9859 separated list. Hash-marked comments and white lines are ignored. Here
9862 # Set of available languages.
9865 This example means that German and French PO files are available, so
9866 that these languages are currently supported by your package. If you
9867 want to further restrict, at installation time, the set of installed
9868 languages, this should not be done by modifying the ‘LINGUAS’ file, but
9869 rather by using the ‘LINGUAS’ environment variable (*note Installers::).
9871 It is recommended that you add the "languages" ‘en@quot’ and
9872 ‘en@boldquot’ to the ‘LINGUAS’ file. ‘en@quot’ is a variant of English
9873 message catalogs (‘en’) which uses real quotation marks instead of the
9874 ugly looking asymmetric ASCII substitutes ‘`’ and ‘'’. ‘en@boldquot’ is
9875 a variant of ‘en@quot’ that additionally outputs quoted pieces of text
9876 in a bold font, when used in a terminal emulator which supports the
9877 VT100 escape sequences (such as ‘xterm’ or the Linux console, but not
9878 Emacs in ‘M-x shell’ mode).
9880 These extra message catalogs ‘en@quot’ and ‘en@boldquot’ are
9881 constructed automatically, not by translators; to support them, you need
9882 the files ‘Rules-quot’, ‘quot.sed’, ‘boldquot.sed’, ‘en@quot.header’,
9883 ‘en@boldquot.header’, ‘insert-header.sin’ in the ‘po/’ directory. You
9884 can copy them from GNU gettext’s ‘po/’ directory; they are also
9885 installed by running ‘gettextize’.
9888 File: gettext.info, Node: po/Makevars, Next: po/Rules-*, Prev: po/LINGUAS, Up: Adjusting Files
9890 13.4.3 ‘Makevars’ in ‘po/’
9891 --------------------------
9893 The ‘po/’ directory also has a file named ‘Makevars’. It contains
9894 variables that are specific to your project. ‘po/Makevars’ gets
9895 inserted into the ‘po/Makefile’ when the latter is created. The
9896 variables thus take effect when the POT file is created or updated, and
9897 when the message catalogs get installed.
9899 The first three variables can be left unmodified if your package has
9900 a single message domain and, accordingly, a single ‘po/’ directory.
9901 Only packages which have multiple ‘po/’ directories at different
9902 locations need to adjust the three first variables defined in
9905 As an alternative to the ‘XGETTEXT_OPTIONS’ variables, it is also
9906 possible to specify ‘xgettext’ options through the ‘AM_XGETTEXT_OPTION’
9907 autoconf macro. See *note AM_XGETTEXT_OPTION::.
9910 File: gettext.info, Node: po/Rules-*, Next: configure.ac, Prev: po/Makevars, Up: Adjusting Files
9912 13.4.4 Extending ‘Makefile’ in ‘po/’
9913 ------------------------------------
9915 All files called ‘Rules-*’ in the ‘po/’ directory get appended to the
9916 ‘po/Makefile’ when it is created. They present an opportunity to add
9917 rules for special PO files to the Makefile, without needing to mess with
9918 ‘po/Makefile.in.in’.
9920 GNU gettext comes with a ‘Rules-quot’ file, containing rules for
9921 building catalogs ‘en@quot.po’ and ‘en@boldquot.po’. The effect of
9922 ‘en@quot.po’ is that people who set their ‘LANGUAGE’ environment
9923 variable to ‘en@quot’ will get messages with proper looking symmetric
9924 Unicode quotation marks instead of abusing the ASCII grave accent and
9925 the ASCII apostrophe for indicating quotations. To enable this catalog,
9926 simply add ‘en@quot’ to the ‘po/LINGUAS’ file. The effect of
9927 ‘en@boldquot.po’ is that people who set ‘LANGUAGE’ to ‘en@boldquot’ will
9928 get not only proper quotation marks, but also the quoted text will be
9929 shown in a bold font on terminals and consoles. This catalog is useful
9930 only for command-line programs, not GUI programs. To enable it,
9931 similarly add ‘en@boldquot’ to the ‘po/LINGUAS’ file.
9933 Similarly, you can create rules for building message catalogs for the
9934 ‘sr@latin’ locale – Serbian written with the Latin alphabet – from those
9935 for the ‘sr’ locale – Serbian written with Cyrillic letters. See *note
9936 msgfilter Invocation::.
9939 File: gettext.info, Node: configure.ac, Next: config.guess, Prev: po/Rules-*, Up: Adjusting Files
9941 13.4.5 ‘configure.ac’ at top level
9942 ----------------------------------
9944 ‘configure.ac’ or ‘configure.in’ - this is the source from which
9945 ‘autoconf’ generates the ‘configure’ script.
9947 1. Declare the package and version.
9949 This is done by a set of lines like these:
9953 AC_DEFINE_UNQUOTED(PACKAGE, "$PACKAGE")
9954 AC_DEFINE_UNQUOTED(VERSION, "$VERSION")
9958 or, if you are using GNU ‘automake’, by a line like this:
9960 AM_INIT_AUTOMAKE(gettext, 0.19.7)
9962 Of course, you replace ‘gettext’ with the name of your package, and
9963 ‘0.19.7’ by its version numbers, exactly as they should appear in
9964 the packaged ‘tar’ file name of your distribution
9965 (‘gettext-0.19.7.tar.gz’, here).
9967 2. Check for internationalization support.
9969 Here is the main ‘m4’ macro for triggering internationalization
9970 support. Just add this line to ‘configure.ac’:
9974 This call is purposely simple, even if it generates a lot of
9975 configure time checking and actions.
9977 If you have suppressed the ‘intl/’ subdirectory by calling
9978 ‘gettextize’ without ‘--intl’ option, this call should read
9980 AM_GNU_GETTEXT([external])
9982 3. Have output files created.
9984 The ‘AC_OUTPUT’ directive, at the end of your ‘configure.ac’ file,
9985 needs to be modified in two ways:
9987 AC_OUTPUT([EXISTING CONFIGURATION FILES intl/Makefile po/Makefile.in],
9988 [EXISTING ADDITIONAL ACTIONS])
9990 The modification to the first argument to ‘AC_OUTPUT’ asks for
9991 substitution in the ‘intl/’ and ‘po/’ directories. Note the ‘.in’
9992 suffix used for ‘po/’ only. This is because the distributed file
9993 is really ‘po/Makefile.in.in’.
9995 If you have suppressed the ‘intl/’ subdirectory by calling
9996 ‘gettextize’ without ‘--intl’ option, then you don’t need to add
9997 ‘intl/Makefile’ to the ‘AC_OUTPUT’ line.
9999 If, after doing the recommended modifications, a command like
10000 ‘aclocal -I m4’ or ‘autoconf’ or ‘autoreconf’ fails with a trace similar
10003 configure.ac:44: warning: AC_COMPILE_IFELSE was called before AC_GNU_SOURCE
10004 ../../lib/autoconf/specific.m4:335: AC_GNU_SOURCE is expanded from...
10005 m4/lock.m4:224: gl_LOCK is expanded from...
10006 m4/gettext.m4:571: gt_INTL_SUBDIR_CORE is expanded from...
10007 m4/gettext.m4:472: AM_INTL_SUBDIR is expanded from...
10008 m4/gettext.m4:347: AM_GNU_GETTEXT is expanded from...
10009 configure.ac:44: the top level
10010 configure.ac:44: warning: AC_RUN_IFELSE was called before AC_GNU_SOURCE
10012 you need to add an explicit invocation of ‘AC_GNU_SOURCE’ in the
10013 ‘configure.ac’ file - after ‘AC_PROG_CC’ but before ‘AM_GNU_GETTEXT’,
10014 most likely very close to the ‘AC_PROG_CC’ invocation. This is
10015 necessary because of ordering restrictions imposed by GNU autoconf.
10018 File: gettext.info, Node: config.guess, Next: mkinstalldirs, Prev: configure.ac, Up: Adjusting Files
10020 13.4.6 ‘config.guess’, ‘config.sub’ at top level
10021 ------------------------------------------------
10023 If you haven’t suppressed the ‘intl/’ subdirectory, you need to add
10024 the GNU ‘config.guess’ and ‘config.sub’ files to your distribution.
10025 They are needed because the ‘intl/’ directory has platform dependent
10026 support for determining the locale’s character encoding and therefore
10027 needs to identify the platform.
10029 You can obtain the newest version of ‘config.guess’ and ‘config.sub’
10030 from the ‘config’ project at ‘http://savannah.gnu.org/’. The commands
10032 $ wget -O config.guess 'http://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.guess;hb=HEAD'
10033 $ wget -O config.sub 'http://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.sub;hb=HEAD'
10034 Less recent versions are also contained in the GNU ‘automake’ and GNU
10035 ‘libtool’ packages.
10037 Normally, ‘config.guess’ and ‘config.sub’ are put at the top level of
10038 a distribution. But it is also possible to put them in a subdirectory,
10039 altogether with other configuration support files like ‘install-sh’,
10040 ‘ltconfig’, ‘ltmain.sh’ or ‘missing’. All you need to do, other than
10041 moving the files, is to add the following line to your ‘configure.ac’.
10043 AC_CONFIG_AUX_DIR([SUBDIR])
10046 File: gettext.info, Node: mkinstalldirs, Next: aclocal, Prev: config.guess, Up: Adjusting Files
10048 13.4.7 ‘mkinstalldirs’ at top level
10049 -----------------------------------
10051 With earlier versions of GNU gettext, you needed to add the GNU
10052 ‘mkinstalldirs’ script to your distribution. This is not needed any
10053 more. You can remove it if you not also using an automake version older
10057 File: gettext.info, Node: aclocal, Next: acconfig, Prev: mkinstalldirs, Up: Adjusting Files
10059 13.4.8 ‘aclocal.m4’ at top level
10060 --------------------------------
10062 If you do not have an ‘aclocal.m4’ file in your distribution, the
10063 simplest is to concatenate the files ‘codeset.m4’, ‘fcntl-o.m4’,
10064 ‘gettext.m4’, ‘glibc2.m4’, ‘glibc21.m4’, ‘iconv.m4’, ‘intdiv0.m4’,
10065 ‘intl.m4’, ‘intldir.m4’, ‘intlmacosx.m4’, ‘intmax.m4’, ‘inttypes_h.m4’,
10066 ‘inttypes-pri.m4’, ‘lcmessage.m4’, ‘lib-ld.m4’, ‘lib-link.m4’,
10067 ‘lib-prefix.m4’, ‘lock.m4’, ‘longlong.m4’, ‘nls.m4’, ‘po.m4’,
10068 ‘printf-posix.m4’, ‘progtest.m4’, ‘size_max.m4’, ‘stdint_h.m4’,
10069 ‘threadlib.m4’, ‘uintmax_t.m4’, ‘visibility.m4’, ‘wchar_t.m4’,
10070 ‘wint_t.m4’, ‘xsize.m4’ from GNU ‘gettext’’s ‘m4/’ directory into a
10071 single file. If you have suppressed the ‘intl/’ directory, only
10072 ‘gettext.m4’, ‘iconv.m4’, ‘lib-ld.m4’, ‘lib-link.m4’, ‘lib-prefix.m4’,
10073 ‘nls.m4’, ‘po.m4’, ‘progtest.m4’ need to be concatenated.
10075 If you are not using GNU ‘automake’ 1.8 or newer, you will need to
10076 add a file ‘mkdirp.m4’ from a newer automake distribution to the list of
10079 If you already have an ‘aclocal.m4’ file, then you will have to merge
10080 the said macro files into your ‘aclocal.m4’. Note that if you are
10081 upgrading from a previous release of GNU ‘gettext’, you should most
10082 probably _replace_ the macros (‘AM_GNU_GETTEXT’, etc.), as they usually
10083 change a little from one release of GNU ‘gettext’ to the next. Their
10084 contents may vary as we get more experience with strange systems out
10087 If you are using GNU ‘automake’ 1.5 or newer, it is enough to put
10088 these macro files into a subdirectory named ‘m4/’ and add the line
10090 ACLOCAL_AMFLAGS = -I m4
10092 to your top level ‘Makefile.am’.
10094 If you are using GNU ‘automake’ 1.10 or newer, it is even easier: Add
10097 ACLOCAL_AMFLAGS = --install -I m4
10099 to your top level ‘Makefile.am’, and run ‘aclocal --install -I m4’.
10100 This will copy the needed files to the ‘m4/’ subdirectory automatically,
10101 before updating ‘aclocal.m4’.
10103 These macros check for the internationalization support functions and
10104 related informations. Hopefully, once stabilized, these macros might be
10105 integrated in the standard Autoconf set, because this piece of ‘m4’ code
10106 will be the same for all projects using GNU ‘gettext’.
10109 File: gettext.info, Node: acconfig, Next: config.h.in, Prev: aclocal, Up: Adjusting Files
10111 13.4.9 ‘acconfig.h’ at top level
10112 --------------------------------
10114 Earlier GNU ‘gettext’ releases required to put definitions for
10115 ‘ENABLE_NLS’, ‘HAVE_GETTEXT’ and ‘HAVE_LC_MESSAGES’, ‘HAVE_STPCPY’,
10116 ‘PACKAGE’ and ‘VERSION’ into an ‘acconfig.h’ file. This is not needed
10117 any more; you can remove them from your ‘acconfig.h’ file unless your
10118 package uses them independently from the ‘intl/’ directory.
10121 File: gettext.info, Node: config.h.in, Next: Makefile, Prev: acconfig, Up: Adjusting Files
10123 13.4.10 ‘config.h.in’ at top level
10124 ----------------------------------
10126 The include file template that holds the C macros to be defined by
10127 ‘configure’ is usually called ‘config.h.in’ and may be maintained either
10128 manually or automatically.
10130 If ‘gettextize’ has created an ‘intl/’ directory, this file must be
10131 called ‘config.h.in’ and must be at the top level. If, however, you
10132 have suppressed the ‘intl/’ directory by calling ‘gettextize’ without
10133 ‘--intl’ option, then you can choose the name of this file and its
10136 If it is maintained automatically, by use of the ‘autoheader’
10137 program, you need to do nothing about it. This is the case in
10138 particular if you are using GNU ‘automake’.
10140 If it is maintained manually, and if ‘gettextize’ has created an
10141 ‘intl/’ directory, you should switch to using ‘autoheader’. The list of
10142 C macros to be added for the sake of the ‘intl/’ directory is just too
10143 long to be maintained manually; it also changes between different
10144 versions of GNU ‘gettext’.
10146 If it is maintained manually, and if on the other hand you have
10147 suppressed the ‘intl/’ directory by calling ‘gettextize’ without
10148 ‘--intl’ option, then you can get away by adding the following lines to
10151 /* Define to 1 if translation of program messages to the user's
10152 native language is requested. */
10156 File: gettext.info, Node: Makefile, Next: src/Makefile, Prev: config.h.in, Up: Adjusting Files
10158 13.4.11 ‘Makefile.in’ at top level
10159 ----------------------------------
10161 Here are a few modifications you need to make to your main, top-level
10162 ‘Makefile.in’ file.
10164 1. Add the following lines near the beginning of your ‘Makefile.in’,
10165 so the ‘dist:’ goal will work properly (as explained further down):
10167 PACKAGE = @PACKAGE@
10168 VERSION = @VERSION@
10170 2. Add file ‘ABOUT-NLS’ to the ‘DISTFILES’ definition, so the file
10173 3. Wherever you process subdirectories in your ‘Makefile.in’, be sure
10174 you also process the subdirectories ‘intl’ and ‘po’. Special rules
10175 in the ‘Makefiles’ take care for the case where no
10176 internationalization is wanted.
10178 If you are using Makefiles, either generated by automake, or
10179 hand-written so they carefully follow the GNU coding standards, the
10180 effected goals for which the new subdirectories must be handled
10181 include ‘installdirs’, ‘install’, ‘uninstall’, ‘clean’,
10184 Here is an example of a canonical order of processing. In this
10185 example, we also define ‘SUBDIRS’ in ‘Makefile.in’ for it to be
10186 further used in the ‘dist:’ goal.
10188 SUBDIRS = doc intl lib src po
10190 Note that you must arrange for ‘make’ to descend into the ‘intl’
10191 directory before descending into other directories containing code
10192 which make use of the ‘libintl.h’ header file. For this reason,
10193 here we mention ‘intl’ before ‘lib’ and ‘src’.
10195 4. A delicate point is the ‘dist:’ goal, as both ‘intl/Makefile’ and
10196 ‘po/Makefile’ will later assume that the proper directory has been
10197 set up from the main ‘Makefile’. Here is an example at what the
10198 ‘dist:’ goal might look like:
10200 distdir = $(PACKAGE)-$(VERSION)
10204 chmod 777 $(distdir)
10205 for file in $(DISTFILES); do \
10206 ln $$file $(distdir) 2>/dev/null || cp -p $$file $(distdir); \
10208 for subdir in $(SUBDIRS); do \
10209 mkdir $(distdir)/$$subdir || exit 1; \
10210 chmod 777 $(distdir)/$$subdir; \
10211 (cd $$subdir && $(MAKE) $@) || exit 1; \
10213 tar chozf $(distdir).tar.gz $(distdir)
10216 Note that if you are using GNU ‘automake’, ‘Makefile.in’ is
10217 automatically generated from ‘Makefile.am’, and all needed changes to
10218 ‘Makefile.am’ are already made by running ‘gettextize’.
10221 File: gettext.info, Node: src/Makefile, Next: lib/gettext.h, Prev: Makefile, Up: Adjusting Files
10223 13.4.12 ‘Makefile.in’ in ‘src/’
10224 -------------------------------
10226 Some of the modifications made in the main ‘Makefile.in’ will also be
10227 needed in the ‘Makefile.in’ from your package sources, which we assume
10228 here to be in the ‘src/’ subdirectory. Here are all the modifications
10229 needed in ‘src/Makefile.in’:
10231 1. In view of the ‘dist:’ goal, you should have these lines near the
10232 beginning of ‘src/Makefile.in’:
10234 PACKAGE = @PACKAGE@
10235 VERSION = @VERSION@
10237 2. If not done already, you should guarantee that ‘top_srcdir’ gets
10238 defined. This will serve for ‘cpp’ include files. Just add the
10241 top_srcdir = @top_srcdir@
10243 3. You might also want to define ‘subdir’ as ‘src’, later allowing for
10244 almost uniform ‘dist:’ goals in all your ‘Makefile.in’. At list,
10245 the ‘dist:’ goal below assume that you used:
10249 4. The ‘main’ function of your program will normally call
10250 ‘bindtextdomain’ (see *note Triggering::), like this:
10252 bindtextdomain (PACKAGE, LOCALEDIR);
10253 textdomain (PACKAGE);
10255 To make LOCALEDIR known to the program, add the following lines to
10256 ‘Makefile.in’ if you are using Autoconf version 2.60 or newer:
10258 datadir = @datadir@
10259 datarootdir= @datarootdir@
10260 localedir = @localedir@
10261 DEFS = -DLOCALEDIR=\"$(localedir)\" @DEFS@
10263 or these lines if your version of Autoconf is older than 2.60:
10265 datadir = @datadir@
10266 localedir = $(datadir)/locale
10267 DEFS = -DLOCALEDIR=\"$(localedir)\" @DEFS@
10269 Note that ‘@datadir@’ defaults to ‘$(prefix)/share’, thus
10270 ‘$(localedir)’ defaults to ‘$(prefix)/share/locale’.
10272 5. You should ensure that the final linking will use ‘@LIBINTL@’ or
10273 ‘@LTLIBINTL@’ as a library. ‘@LIBINTL@’ is for use without
10274 ‘libtool’, ‘@LTLIBINTL@’ is for use with ‘libtool’. An easy way to
10275 achieve this is to manage that it gets into ‘LIBS’, like this:
10277 LIBS = @LIBINTL@ @LIBS@
10279 In most packages internationalized with GNU ‘gettext’, one will
10280 find a directory ‘lib/’ in which a library containing some helper
10281 functions will be build. (You need at least the few functions
10282 which the GNU ‘gettext’ Library itself needs.) However some of the
10283 functions in the ‘lib/’ also give messages to the user which of
10284 course should be translated, too. Taking care of this, the support
10285 library (say ‘libsupport.a’) should be placed before ‘@LIBINTL@’
10286 and ‘@LIBS@’ in the above example. So one has to write this:
10288 LIBS = ../lib/libsupport.a @LIBINTL@ @LIBS@
10290 6. You should also ensure that directory ‘intl/’ will be searched for
10291 C preprocessor include files in all circumstances. So, you have to
10292 manage so both ‘-I../intl’ and ‘-I$(top_srcdir)/intl’ will be given
10295 7. Your ‘dist:’ goal has to conform with others. Here is a reasonable
10298 distdir = ../$(PACKAGE)-$(VERSION)/$(subdir)
10299 dist: Makefile $(DISTFILES)
10300 for file in $(DISTFILES); do \
10301 ln $$file $(distdir) 2>/dev/null || cp -p $$file $(distdir) || exit 1; \
10304 Note that if you are using GNU ‘automake’, ‘Makefile.in’ is
10305 automatically generated from ‘Makefile.am’, and the first three changes
10306 and the last change are not necessary. The remaining needed
10307 ‘Makefile.am’ modifications are the following:
10309 1. To make LOCALEDIR known to the program, add the following to
10312 <module>_CPPFLAGS = -DLOCALEDIR=\"$(localedir)\"
10314 for each specific module or compilation unit, or
10316 AM_CPPFLAGS = -DLOCALEDIR=\"$(localedir)\"
10318 for all modules and compilation units together. Furthermore, if
10319 you are using an Autoconf version older then 2.60, add this line to
10320 define ‘localedir’:
10322 localedir = $(datadir)/locale
10324 2. To ensure that the final linking will use ‘@LIBINTL@’ or
10325 ‘@LTLIBINTL@’ as a library, add the following to ‘Makefile.am’:
10327 <program>_LDADD = @LIBINTL@
10329 for each specific program, or
10333 for all programs together. Remember that when you use ‘libtool’ to
10334 link a program, you need to use @LTLIBINTL@ instead of @LIBINTL@
10337 3. If you have an ‘intl/’ directory, whose contents is created by
10338 ‘gettextize’, then to ensure that it will be searched for C
10339 preprocessor include files in all circumstances, add something like
10340 this to ‘Makefile.am’:
10342 AM_CPPFLAGS = -I../intl -I$(top_srcdir)/intl
10345 File: gettext.info, Node: lib/gettext.h, Prev: src/Makefile, Up: Adjusting Files
10347 13.4.13 ‘gettext.h’ in ‘lib/’
10348 -----------------------------
10350 Internationalization of packages, as provided by GNU ‘gettext’, is
10351 optional. It can be turned off in two situations:
10353 • When the installer has specified ‘./configure --disable-nls’. This
10354 can be useful when small binaries are more important than features,
10355 for example when building utilities for boot diskettes. It can
10356 also be useful in order to get some specific C compiler warnings
10357 about code quality with some older versions of GCC (older than
10360 • When the package does not include the ‘intl/’ subdirectory, and the
10361 libintl.h header (with its associated libintl library, if any) is
10362 not already installed on the system, it is preferable that the
10363 package builds without internationalization support, rather than to
10364 give a compilation error.
10366 A C preprocessor macro can be used to detect these two cases.
10367 Usually, when ‘libintl.h’ was found and not explicitly disabled, the
10368 ‘ENABLE_NLS’ macro will be defined to 1 in the autoconf generated
10369 configuration file (usually called ‘config.h’). In the two negative
10370 situations, however, this macro will not be defined, thus it will
10371 evaluate to 0 in C preprocessor expressions.
10373 ‘gettext.h’ is a convenience header file for conditional use of
10374 ‘<libintl.h>’, depending on the ‘ENABLE_NLS’ macro. If ‘ENABLE_NLS’ is
10375 set, it includes ‘<libintl.h>’; otherwise it defines no-op substitutes
10376 for the libintl.h functions. We recommend the use of ‘"gettext.h"’ over
10377 direct use of ‘<libintl.h>’, so that portability to older systems is
10378 guaranteed and installers can turn off internationalization if they want
10379 to. In the C code, you will then write
10381 #include "gettext.h"
10385 #include <libintl.h>
10387 The location of ‘gettext.h’ is usually in a directory containing
10388 auxiliary include files. In many GNU packages, there is a directory
10389 ‘lib/’ containing helper functions; ‘gettext.h’ fits there. In other
10390 packages, it can go into the ‘src’ directory.
10392 Do not install the ‘gettext.h’ file in public locations. Every
10393 package that needs it should contain a copy of it on its own.
10396 File: gettext.info, Node: autoconf macros, Next: Version Control Issues, Prev: Adjusting Files, Up: Maintainers
10398 13.5 Autoconf macros for use in ‘configure.ac’
10399 ==============================================
10401 GNU ‘gettext’ installs macros for use in a package’s ‘configure.ac’
10402 or ‘configure.in’. *Note Introduction: (autoconf)Top. The primary
10403 macro is, of course, ‘AM_GNU_GETTEXT’.
10407 * AM_GNU_GETTEXT:: AM_GNU_GETTEXT in ‘gettext.m4’
10408 * AM_GNU_GETTEXT_VERSION:: AM_GNU_GETTEXT_VERSION in ‘gettext.m4’
10409 * AM_GNU_GETTEXT_NEED:: AM_GNU_GETTEXT_NEED in ‘gettext.m4’
10410 * AM_GNU_GETTEXT_INTL_SUBDIR:: AM_GNU_GETTEXT_INTL_SUBDIR in ‘intldir.m4’
10411 * AM_PO_SUBDIRS:: AM_PO_SUBDIRS in ‘po.m4’
10412 * AM_XGETTEXT_OPTION:: AM_XGETTEXT_OPTION in ‘po.m4’
10413 * AM_ICONV:: AM_ICONV in ‘iconv.m4’
10416 File: gettext.info, Node: AM_GNU_GETTEXT, Next: AM_GNU_GETTEXT_VERSION, Prev: autoconf macros, Up: autoconf macros
10418 13.5.1 AM_GNU_GETTEXT in ‘gettext.m4’
10419 -------------------------------------
10421 The ‘AM_GNU_GETTEXT’ macro tests for the presence of the GNU gettext
10422 function family in either the C library or a separate ‘libintl’ library
10423 (shared or static libraries are both supported) or in the package’s
10424 ‘intl/’ directory. It also invokes ‘AM_PO_SUBDIRS’, thus preparing the
10425 ‘po/’ directories of the package for building.
10427 ‘AM_GNU_GETTEXT’ accepts up to three optional arguments. The general
10430 AM_GNU_GETTEXT([INTLSYMBOL], [NEEDSYMBOL], [INTLDIR])
10432 INTLSYMBOL can be ‘external’ or ‘no-libtool’. The default (if it is
10433 not specified or empty) is ‘no-libtool’. INTLSYMBOL should be
10434 ‘external’ for packages with no ‘intl/’ directory. For packages with an
10435 ‘intl/’ directory, you can either use an INTLSYMBOL equal to
10436 ‘no-libtool’, or you can use ‘external’ and override by using the macro
10437 ‘AM_GNU_GETTEXT_INTL_SUBDIR’ elsewhere. The two ways to specify the
10438 existence of an ‘intl/’ directory are equivalent. At build time, a
10439 static library ‘$(top_builddir)/intl/libintl.a’ will then be created.
10441 If NEEDSYMBOL is specified and is ‘need-ngettext’, then GNU gettext
10442 implementations (in libc or libintl) without the ‘ngettext()’ function
10443 will be ignored. If NEEDSYMBOL is specified and is
10444 ‘need-formatstring-macros’, then GNU gettext implementations that don’t
10445 support the ISO C 99 ‘<inttypes.h>’ formatstring macros will be ignored.
10446 Only one NEEDSYMBOL can be specified. These requirements can also be
10447 specified by using the macro ‘AM_GNU_GETTEXT_NEED’ elsewhere. To
10448 specify more than one requirement, just specify the strongest one among
10449 them, or invoke the ‘AM_GNU_GETTEXT_NEED’ macro several times. The
10450 hierarchy among the various alternatives is as follows:
10451 ‘need-formatstring-macros’ implies ‘need-ngettext’.
10453 INTLDIR is used to find the intl libraries. If empty, the value
10454 ‘$(top_builddir)/intl/’ is used.
10456 The ‘AM_GNU_GETTEXT’ macro determines whether GNU gettext is
10457 available and should be used. If so, it sets the ‘USE_NLS’ variable to
10458 ‘yes’; it defines ‘ENABLE_NLS’ to 1 in the autoconf generated
10459 configuration file (usually called ‘config.h’); it sets the variables
10460 ‘LIBINTL’ and ‘LTLIBINTL’ to the linker options for use in a Makefile
10461 (‘LIBINTL’ for use without libtool, ‘LTLIBINTL’ for use with libtool);
10462 it adds an ‘-I’ option to ‘CPPFLAGS’ if necessary. In the negative
10463 case, it sets ‘USE_NLS’ to ‘no’; it sets ‘LIBINTL’ and ‘LTLIBINTL’ to
10464 empty and doesn’t change ‘CPPFLAGS’.
10466 The complexities that ‘AM_GNU_GETTEXT’ deals with are the following:
10468 • Some operating systems have ‘gettext’ in the C library, for example
10469 glibc. Some have it in a separate library ‘libintl’. GNU
10470 ‘libintl’ might have been installed as part of the GNU ‘gettext’
10473 • GNU ‘libintl’, if installed, is not necessarily already in the
10474 search path (‘CPPFLAGS’ for the include file search path, ‘LDFLAGS’
10475 for the library search path).
10477 • Except for glibc, the operating system’s native ‘gettext’ cannot
10478 exploit the GNU mo files, doesn’t have the necessary locale
10479 dependency features, and cannot convert messages from the catalog’s
10480 text encoding to the user’s locale encoding.
10482 • GNU ‘libintl’, if installed, is not necessarily already in the run
10483 time library search path. To avoid the need for setting an
10484 environment variable like ‘LD_LIBRARY_PATH’, the macro adds the
10485 appropriate run time search path options to the ‘LIBINTL’ and
10486 ‘LTLIBINTL’ variables. This works on most systems, but not on some
10487 operating systems with limited shared library support, like SCO.
10489 • GNU ‘libintl’ relies on POSIX/XSI ‘iconv’. The macro checks for
10490 linker options needed to use iconv and appends them to the
10491 ‘LIBINTL’ and ‘LTLIBINTL’ variables.
10494 File: gettext.info, Node: AM_GNU_GETTEXT_VERSION, Next: AM_GNU_GETTEXT_NEED, Prev: AM_GNU_GETTEXT, Up: autoconf macros
10496 13.5.2 AM_GNU_GETTEXT_VERSION in ‘gettext.m4’
10497 ---------------------------------------------
10499 The ‘AM_GNU_GETTEXT_VERSION’ macro declares the version number of the
10500 GNU gettext infrastructure that is used by the package.
10502 The use of this macro is optional; only the ‘autopoint’ program makes
10503 use of it (*note Version Control Issues::).
10506 File: gettext.info, Node: AM_GNU_GETTEXT_NEED, Next: AM_GNU_GETTEXT_INTL_SUBDIR, Prev: AM_GNU_GETTEXT_VERSION, Up: autoconf macros
10508 13.5.3 AM_GNU_GETTEXT_NEED in ‘gettext.m4’
10509 ------------------------------------------
10511 The ‘AM_GNU_GETTEXT_NEED’ macro declares a constraint regarding the
10512 GNU gettext implementation. The syntax is
10514 AM_GNU_GETTEXT_NEED([NEEDSYMBOL])
10516 If NEEDSYMBOL is ‘need-ngettext’, then GNU gettext implementations
10517 (in libc or libintl) without the ‘ngettext()’ function will be ignored.
10518 If NEEDSYMBOL is ‘need-formatstring-macros’, then GNU gettext
10519 implementations that don’t support the ISO C 99 ‘<inttypes.h>’
10520 formatstring macros will be ignored.
10522 The optional second argument of ‘AM_GNU_GETTEXT’ is also taken into
10525 The ‘AM_GNU_GETTEXT_NEED’ invocations can occur before or after the
10526 ‘AM_GNU_GETTEXT’ invocation; the order doesn’t matter.
10529 File: gettext.info, Node: AM_GNU_GETTEXT_INTL_SUBDIR, Next: AM_PO_SUBDIRS, Prev: AM_GNU_GETTEXT_NEED, Up: autoconf macros
10531 13.5.4 AM_GNU_GETTEXT_INTL_SUBDIR in ‘intldir.m4’
10532 -------------------------------------------------
10534 The ‘AM_GNU_GETTEXT_INTL_SUBDIR’ macro specifies that the
10535 ‘AM_GNU_GETTEXT’ macro, although invoked with the first argument
10536 ‘external’, should also prepare for building the ‘intl/’ subdirectory.
10538 The ‘AM_GNU_GETTEXT_INTL_SUBDIR’ invocation can occur before or after
10539 the ‘AM_GNU_GETTEXT’ invocation; the order doesn’t matter.
10541 The use of this macro requires GNU automake 1.10 or newer and GNU
10542 autoconf 2.61 or newer.
10545 File: gettext.info, Node: AM_PO_SUBDIRS, Next: AM_XGETTEXT_OPTION, Prev: AM_GNU_GETTEXT_INTL_SUBDIR, Up: autoconf macros
10547 13.5.5 AM_PO_SUBDIRS in ‘po.m4’
10548 -------------------------------
10550 The ‘AM_PO_SUBDIRS’ macro prepares the ‘po/’ directories of the
10551 package for building. This macro should be used in internationalized
10552 programs written in other programming languages than C, C++, Objective
10553 C, for example ‘sh’, ‘Python’, ‘Lisp’. See *note Programming
10554 Languages:: for a list of programming languages that support
10555 localization through PO files.
10557 The ‘AM_PO_SUBDIRS’ macro determines whether internationalization
10558 should be used. If so, it sets the ‘USE_NLS’ variable to ‘yes’,
10559 otherwise to ‘no’. It also determines the right values for Makefile
10560 variables in each ‘po/’ directory.
10563 File: gettext.info, Node: AM_XGETTEXT_OPTION, Next: AM_ICONV, Prev: AM_PO_SUBDIRS, Up: autoconf macros
10565 13.5.6 AM_XGETTEXT_OPTION in ‘po.m4’
10566 ------------------------------------
10568 The ‘AM_XGETTEXT_OPTION’ macro registers a command-line option to be
10569 used in the invocations of ‘xgettext’ in the ‘po/’ directories of the
10572 For example, if you have a source file that defines a function
10573 ‘error_at_line’ whose fifth argument is a format string, you can use
10574 AM_XGETTEXT_OPTION([--flag=error_at_line:5:c-format])
10575 to instruct ‘xgettext’ to mark all translatable strings in ‘gettext’
10576 invocations that occur as fifth argument to this function as ‘c-format’.
10578 See *note xgettext Invocation:: for the list of options that
10579 ‘xgettext’ accepts.
10581 The use of this macro is an alternative to the use of the
10582 ‘XGETTEXT_OPTIONS’ variable in ‘po/Makevars’.
10585 File: gettext.info, Node: AM_ICONV, Prev: AM_XGETTEXT_OPTION, Up: autoconf macros
10587 13.5.7 AM_ICONV in ‘iconv.m4’
10588 -----------------------------
10590 The ‘AM_ICONV’ macro tests for the presence of the POSIX/XSI ‘iconv’
10591 function family in either the C library or a separate ‘libiconv’
10592 library. If found, it sets the ‘am_cv_func_iconv’ variable to ‘yes’; it
10593 defines ‘HAVE_ICONV’ to 1 in the autoconf generated configuration file
10594 (usually called ‘config.h’); it defines ‘ICONV_CONST’ to ‘const’ or to
10595 empty, depending on whether the second argument of ‘iconv()’ is of type
10596 ‘const char **’ or ‘char **’; it sets the variables ‘LIBICONV’ and
10597 ‘LTLIBICONV’ to the linker options for use in a Makefile (‘LIBICONV’ for
10598 use without libtool, ‘LTLIBICONV’ for use with libtool); it adds an ‘-I’
10599 option to ‘CPPFLAGS’ if necessary. If not found, it sets ‘LIBICONV’ and
10600 ‘LTLIBICONV’ to empty and doesn’t change ‘CPPFLAGS’.
10602 The complexities that ‘AM_ICONV’ deals with are the following:
10604 • Some operating systems have ‘iconv’ in the C library, for example
10605 glibc. Some have it in a separate library ‘libiconv’, for example
10606 OSF/1 or FreeBSD. Regardless of the operating system, GNU
10607 ‘libiconv’ might have been installed. In that case, it should be
10608 used instead of the operating system’s native ‘iconv’.
10610 • GNU ‘libiconv’, if installed, is not necessarily already in the
10611 search path (‘CPPFLAGS’ for the include file search path, ‘LDFLAGS’
10612 for the library search path).
10614 • GNU ‘libiconv’ is binary incompatible with some operating system’s
10615 native ‘iconv’, for example on FreeBSD. Use of an ‘iconv.h’ and
10616 ‘libiconv.so’ that don’t fit together would produce program
10619 • GNU ‘libiconv’, if installed, is not necessarily already in the run
10620 time library search path. To avoid the need for setting an
10621 environment variable like ‘LD_LIBRARY_PATH’, the macro adds the
10622 appropriate run time search path options to the ‘LIBICONV’
10623 variable. This works on most systems, but not on some operating
10624 systems with limited shared library support, like SCO.
10626 ‘iconv.m4’ is distributed with the GNU gettext package because
10627 ‘gettext.m4’ relies on it.
10630 File: gettext.info, Node: Version Control Issues, Next: Release Management, Prev: autoconf macros, Up: Maintainers
10632 13.6 Integrating with Version Control Systems
10633 =============================================
10635 Many projects use version control systems for distributed development
10636 and source backup. This section gives some advice how to manage the
10637 uses of ‘gettextize’, ‘autopoint’ and ‘autoconf’ on version controlled
10642 * Distributed Development:: Avoiding version mismatch in distributed development
10643 * Files under Version Control:: Files to put under version control
10644 * Translations under Version Control:: Put PO Files under Version Control
10645 * autopoint Invocation:: Invoking the ‘autopoint’ Program
10648 File: gettext.info, Node: Distributed Development, Next: Files under Version Control, Prev: Version Control Issues, Up: Version Control Issues
10650 13.6.1 Avoiding version mismatch in distributed development
10651 -----------------------------------------------------------
10653 In a project development with multiple developers, there should be a
10654 single developer who occasionally - when there is desire to upgrade to a
10655 new ‘gettext’ version - runs ‘gettextize’ and performs the changes
10656 listed in *note Adjusting Files::, and then commits his changes to the
10659 It is highly recommended that all developers on a project use the
10660 same version of GNU ‘gettext’ in the package. In other words, if a
10661 developer runs ‘gettextize’, he should go the whole way, make the
10662 necessary remaining changes and commit his changes to the repository.
10663 Otherwise the following damages will likely occur:
10665 • Apparent version mismatch between developers. Since some ‘gettext’
10666 specific portions in ‘configure.ac’, ‘configure.in’ and
10667 ‘Makefile.am’, ‘Makefile.in’ files depend on the ‘gettext’ version,
10668 the use of infrastructure files belonging to different ‘gettext’
10669 versions can easily lead to build errors.
10671 • Hidden version mismatch. Such version mismatch can also lead to
10672 malfunctioning of the package, that may be undiscovered by the
10673 developers. The worst case of hidden version mismatch is that
10674 internationalization of the package doesn’t work at all.
10676 • Release risks. All developers implicitly perform constant testing
10677 on a package. This is important in the days and weeks before a
10678 release. If the guy who makes the release tar files uses a
10679 different version of GNU ‘gettext’ than the other developers, the
10680 distribution will be less well tested than if all had been using
10681 the same ‘gettext’ version. For example, it is possible that a
10682 platform specific bug goes undiscovered due to this constellation.
10685 File: gettext.info, Node: Files under Version Control, Next: Translations under Version Control, Prev: Distributed Development, Up: Version Control Issues
10687 13.6.2 Files to put under version control
10688 -----------------------------------------
10690 There are basically three ways to deal with generated files in the
10691 context of a version controlled repository, such as ‘configure’
10692 generated from ‘configure.ac’, ‘PARSER.c’ generated from ‘PARSER.y’, or
10693 ‘po/Makefile.in.in’ autoinstalled by ‘gettextize’ or ‘autopoint’.
10695 1. All generated files are always committed into the repository.
10697 2. All generated files are committed into the repository occasionally,
10698 for example each time a release is made.
10700 3. Generated files are never committed into the repository.
10702 Each of these three approaches has different advantages and
10705 1. The advantage is that anyone can check out the source at any moment
10706 and gets a working build. The drawbacks are: 1a. It requires some
10707 frequent "push" actions by the maintainers. 1b. The repository
10708 grows in size quite fast.
10710 2. The advantage is that anyone can check out the source, and the
10711 usual "./configure; make" will work. The drawbacks are: 2a. The
10712 one who checks out the repository needs tools like GNU ‘automake’,
10713 GNU ‘autoconf’, GNU ‘m4’ installed in his PATH; sometimes he even
10714 needs particular versions of them. 2b. When a release is made and
10715 a commit is made on the generated files, the other developers get
10716 conflicts on the generated files when merging the local work back
10717 to the repository. Although these conflicts are easy to resolve,
10720 3. The advantage is less work for the maintainers. The drawback is
10721 that anyone who checks out the source not only needs tools like GNU
10722 ‘automake’, GNU ‘autoconf’, GNU ‘m4’ installed in his PATH, but
10723 also that he needs to perform a package specific pre-build step
10724 before being able to "./configure; make".
10726 For the first and second approach, all files modified or brought in
10727 by the occasional ‘gettextize’ invocation and update should be committed
10728 into the repository.
10730 For the third approach, the maintainer can omit from the repository
10731 all the files that ‘gettextize’ mentions as "copy". Instead, he adds to
10732 the ‘configure.ac’ or ‘configure.in’ a line of the form
10734 AM_GNU_GETTEXT_VERSION(0.19.7)
10736 and adds to the package’s pre-build script an invocation of ‘autopoint’.
10737 For everyone who checks out the source, this ‘autopoint’ invocation will
10738 copy into the right place the ‘gettext’ infrastructure files that have
10739 been omitted from the repository.
10741 The version number used as argument to ‘AM_GNU_GETTEXT_VERSION’ is
10742 the version of the ‘gettext’ infrastructure that the package wants to
10743 use. It is also the minimum version number of the ‘autopoint’ program.
10744 So, if you write ‘AM_GNU_GETTEXT_VERSION(0.11.5)’ then the developers
10745 can have any version >= 0.11.5 installed; the package will work with the
10746 0.11.5 infrastructure in all developers’ builds. When the maintainer
10747 then runs gettextize from, say, version 0.12.1 on the package, the
10748 occurrence of ‘AM_GNU_GETTEXT_VERSION(0.11.5)’ will be changed into
10749 ‘AM_GNU_GETTEXT_VERSION(0.12.1)’, and all other developers that use the
10750 CVS will henceforth need to have GNU ‘gettext’ 0.12.1 or newer
10754 File: gettext.info, Node: Translations under Version Control, Next: autopoint Invocation, Prev: Files under Version Control, Up: Version Control Issues
10756 13.6.3 Put PO Files under Version Control
10757 -----------------------------------------
10759 Since translations are valuable assets as well as the source code, it
10760 would make sense to put them under version control. The GNU gettext
10761 infrastructure supports two ways to deal with translations in the
10762 context of a version controlled repository.
10764 1. Both POT file and PO files are committed into the repository.
10766 2. Only PO files are committed into the repository.
10768 If a POT file is absent when building, it will be generated by
10769 scanning the source files with ‘xgettext’, and then the PO files are
10770 regenerated as a dependency. On the other hand, some maintainers want
10771 to keep the POT file unchanged during the development phase. So, even
10772 if a POT file is present and older than the source code, it won’t be
10773 updated automatically. You can manually update it with ‘make
10774 $(DOMAIN).pot-update’, and commit it at certain point.
10776 Special advices for particular version control systems:
10778 • Recent version control systems, Git for instance, ignore file’s
10779 timestamp. In that case, PO files can be accidentally updated even
10780 if a POT file is not updated. To prevent this, you can set
10781 ‘PO_DEPENDS_ON_POT’ variable to ‘no’ in the ‘Makevars’ file and do
10782 ‘make update-po’ manually.
10784 • Location comments such as ‘#: lib/error.c:116’ are sometimes
10785 annoying, since these comments are volatile and may introduce
10786 unwanted change to the working copy when building. To mitigate
10787 this, you can decide to omit those comments from the PO files in
10790 This is possible with the ‘--no-location’ option of the ‘msgmerge’
10791 command (1). The drawback is that, if the location information is
10792 needed, translators have to recover the location comments by
10793 running ‘msgmerge’ again.
10795 ---------- Footnotes ----------
10797 (1) you can also use it through the ‘MSGMERGE_OPTIONS’ option from
10801 File: gettext.info, Node: autopoint Invocation, Prev: Translations under Version Control, Up: Version Control Issues
10803 13.6.4 Invoking the ‘autopoint’ Program
10804 ---------------------------------------
10806 autopoint [OPTION]...
10808 The ‘autopoint’ program copies standard gettext infrastructure files
10809 into a source package. It extracts from a macro call of the form
10810 ‘AM_GNU_GETTEXT_VERSION(VERSION)’, found in the package’s ‘configure.in’
10811 or ‘configure.ac’ file, the gettext version used by the package, and
10812 copies the infrastructure files belonging to this version into the
10815 To extract the latest available infrastructure which satisfies a
10816 version requirement, then you can use the form
10817 ‘AM_GNU_GETTEXT_REQUIRE_VERSION(VERSION)’ instead. For example, if
10818 gettext 0.19.7 is installed on your system and ‘0.19.1’ is requested,
10819 then the infrastructure files of version 0.19.7 will be copied into a
10827 Force overwriting of files that already exist.
10831 Print modifications but don’t perform them. All file copying
10832 actions that ‘autopoint’ would normally execute are inhibited and
10833 instead only listed on standard output.
10835 13.6.4.2 Informative output
10836 ...........................
10839 Display this help and exit.
10842 Output version information and exit.
10844 ‘autopoint’ supports the GNU ‘gettext’ versions from 0.10.35 to the
10845 current one, 0.19.7. In order to apply ‘autopoint’ to a package using a
10846 ‘gettext’ version newer than 0.19.7, you need to install this same
10847 version of GNU ‘gettext’ at least.
10849 In packages using GNU ‘automake’, an invocation of ‘autopoint’ should
10850 be followed by invocations of ‘aclocal’ and then ‘autoconf’ and
10851 ‘autoheader’. The reason is that ‘autopoint’ installs some autoconf
10852 macro files, which are used by ‘aclocal’ to create ‘aclocal.m4’, and the
10853 latter is used by ‘autoconf’ to create the package’s ‘configure’ script
10854 and by ‘autoheader’ to create the package’s ‘config.h.in’ include file
10857 The name ‘autopoint’ is an abbreviation of ‘auto-po-intl-m4’; the
10858 tool copies or updates mostly files in the ‘po’, ‘intl’, ‘m4’
10862 File: gettext.info, Node: Release Management, Prev: Version Control Issues, Up: Maintainers
10864 13.7 Creating a Distribution Tarball
10865 ====================================
10867 In projects that use GNU ‘automake’, the usual commands for creating
10868 a distribution tarball, ‘make dist’ or ‘make distcheck’, automatically
10869 update the PO files as needed.
10871 If GNU ‘automake’ is not used, the maintainer needs to perform this
10872 update before making a release:
10875 $ (cd po; make update-po)
10879 File: gettext.info, Node: Installers, Next: Programming Languages, Prev: Maintainers, Up: Top
10881 14 The Installer’s and Distributor’s View
10882 *****************************************
10884 By default, packages fully using GNU ‘gettext’, internally, are
10885 installed in such a way as to allow translation of messages. At
10886 _configuration_ time, those packages should automatically detect whether
10887 the underlying host system already provides the GNU ‘gettext’ functions.
10888 If not, the GNU ‘gettext’ library should be automatically prepared and
10889 used. Installers may use special options at configuration time for
10890 changing this behavior. The command ‘./configure
10891 --with-included-gettext’ bypasses system ‘gettext’ to use the included
10892 GNU ‘gettext’ instead, while ‘./configure --disable-nls’ produces
10893 programs totally unable to translate messages.
10895 Internationalized packages have usually many ‘LL.po’ files. Unless
10896 translations are disabled, all those available are installed together
10897 with the package. However, the environment variable ‘LINGUAS’ may be
10898 set, prior to configuration, to limit the installed set. ‘LINGUAS’
10899 should then contain a space separated list of two-letter codes, stating
10900 which languages are allowed.
10903 File: gettext.info, Node: Programming Languages, Next: Conclusion, Prev: Installers, Up: Top
10905 15 Other Programming Languages
10906 ******************************
10908 While the presentation of ‘gettext’ focuses mostly on C and
10909 implicitly applies to C++ as well, its scope is far broader than that:
10910 Many programming languages, scripting languages and other textual data
10911 like GUI resources or package descriptions can make use of the gettext
10916 * Language Implementors:: The Language Implementor’s View
10917 * Programmers for other Languages:: The Programmer’s View
10918 * Translators for other Languages:: The Translator’s View
10919 * Maintainers for other Languages:: The Maintainer’s View
10920 * List of Programming Languages:: Individual Programming Languages
10921 * List of Data Formats:: Internationalizable Data
10924 File: gettext.info, Node: Language Implementors, Next: Programmers for other Languages, Prev: Programming Languages, Up: Programming Languages
10926 15.1 The Language Implementor’s View
10927 ====================================
10929 All programming and scripting languages that have the notion of
10930 strings are eligible to supporting ‘gettext’. Supporting ‘gettext’
10931 means the following:
10933 1. You should add to the language a syntax for translatable strings.
10934 In principle, a function call of ‘gettext’ would do, but a
10935 shorthand syntax helps keeping the legibility of internationalized
10936 programs. For example, in C we use the syntax ‘_("string")’, and
10937 in GNU awk we use the shorthand ‘_"string"’.
10939 2. You should arrange that evaluation of such a translatable string at
10940 runtime calls the ‘gettext’ function, or performs equivalent
10943 3. Similarly, you should make the functions ‘ngettext’, ‘dcgettext’,
10944 ‘dcngettext’ available from within the language. These functions
10945 are less often used, but are nevertheless necessary for particular
10946 purposes: ‘ngettext’ for correct plural handling, and ‘dcgettext’
10947 and ‘dcngettext’ for obeying other locale-related environment
10948 variables than ‘LC_MESSAGES’, such as ‘LC_TIME’ or ‘LC_MONETARY’.
10949 For these latter functions, you need to make the ‘LC_*’ constants,
10950 available in the C header ‘<locale.h>’, referenceable from within
10951 the language, usually either as enumeration values or as strings.
10953 4. You should allow the programmer to designate a message domain,
10954 either by making the ‘textdomain’ function available from within
10955 the language, or by introducing a magic variable called
10956 ‘TEXTDOMAIN’. Similarly, you should allow the programmer to
10957 designate where to search for message catalogs, by providing access
10958 to the ‘bindtextdomain’ function.
10960 5. You should either perform a ‘setlocale (LC_ALL, "")’ call during
10961 the startup of your language runtime, or allow the programmer to do
10962 so. Remember that gettext will act as a no-op if the ‘LC_MESSAGES’
10963 and ‘LC_CTYPE’ locale categories are not both set.
10965 6. A programmer should have a way to extract translatable strings from
10966 a program into a PO file. The GNU ‘xgettext’ program is being
10967 extended to support very different programming languages. Please
10968 contact the GNU ‘gettext’ maintainers to help them doing this. If
10969 the string extractor is best integrated into your language’s
10970 parser, GNU ‘xgettext’ can function as a front end to your string
10973 7. The language’s library should have a string formatting facility
10974 where the arguments of a format string are denoted by a positional
10975 number or a name. This is needed because for some languages and
10976 some messages with more than one substitutable argument, the
10977 translation will need to output the substituted arguments in
10978 different order. *Note c-format Flag::.
10980 8. If the language has more than one implementation, and not all of
10981 the implementations use ‘gettext’, but the programs should be
10982 portable across implementations, you should provide a no-i18n
10983 emulation, that makes the other implementations accept programs
10984 written for yours, without actually translating the strings.
10986 9. To help the programmer in the task of marking translatable strings,
10987 which is sometimes performed using the Emacs PO mode (*note
10988 Marking::), you are welcome to contact the GNU ‘gettext’
10989 maintainers, so they can add support for your language to
10992 On the implementation side, three approaches are possible, with
10993 different effects on portability and copyright:
10995 • You may integrate the GNU ‘gettext’’s ‘intl/’ directory in your
10996 package, as described in *note Maintainers::. This allows you to
10997 have internationalization on all kinds of platforms. Note that
10998 when you then distribute your package, it legally falls under the
10999 GNU General Public License, and the GNU project will be glad about
11000 your contribution to the Free Software pool.
11002 • You may link against GNU ‘gettext’ functions if they are found in
11003 the C library. For example, an autoconf test for ‘gettext()’ and
11004 ‘ngettext()’ will detect this situation. For the moment, this test
11005 will succeed on GNU systems and not on other platforms. No severe
11006 copyright restrictions apply.
11008 • You may emulate or reimplement the GNU ‘gettext’ functionality.
11009 This has the advantage of full portability and no copyright
11010 restrictions, but also the drawback that you have to reimplement
11011 the GNU ‘gettext’ features (such as the ‘LANGUAGE’ environment
11012 variable, the locale aliases database, the automatic charset
11013 conversion, and plural handling).
11016 File: gettext.info, Node: Programmers for other Languages, Next: Translators for other Languages, Prev: Language Implementors, Up: Programming Languages
11018 15.2 The Programmer’s View
11019 ==========================
11021 For the programmer, the general procedure is the same as for the C
11022 language. The Emacs PO mode marking supports other languages, and the
11023 GNU ‘xgettext’ string extractor recognizes other languages based on the
11024 file extension or a command-line option. In some languages, ‘setlocale’
11025 is not needed because it is already performed by the underlying language
11029 File: gettext.info, Node: Translators for other Languages, Next: Maintainers for other Languages, Prev: Programmers for other Languages, Up: Programming Languages
11031 15.3 The Translator’s View
11032 ==========================
11034 The translator works exactly as in the C language case. The only
11035 difference is that when translating format strings, she has to be aware
11036 of the language’s particular syntax for positional arguments in format
11041 * c-format:: C Format Strings
11042 * objc-format:: Objective C Format Strings
11043 * sh-format:: Shell Format Strings
11044 * python-format:: Python Format Strings
11045 * lisp-format:: Lisp Format Strings
11046 * elisp-format:: Emacs Lisp Format Strings
11047 * librep-format:: librep Format Strings
11048 * scheme-format:: Scheme Format Strings
11049 * smalltalk-format:: Smalltalk Format Strings
11050 * java-format:: Java Format Strings
11051 * csharp-format:: C# Format Strings
11052 * awk-format:: awk Format Strings
11053 * object-pascal-format:: Object Pascal Format Strings
11054 * ycp-format:: YCP Format Strings
11055 * tcl-format:: Tcl Format Strings
11056 * perl-format:: Perl Format Strings
11057 * php-format:: PHP Format Strings
11058 * gcc-internal-format:: GCC internal Format Strings
11059 * gfc-internal-format:: GFC internal Format Strings
11060 * qt-format:: Qt Format Strings
11061 * qt-plural-format:: Qt Plural Format Strings
11062 * kde-format:: KDE Format Strings
11063 * kde-kuit-format:: KUIT Format Strings
11064 * boost-format:: Boost Format Strings
11065 * lua-format:: Lua Format Strings
11066 * javascript-format:: JavaScript Format Strings
11069 File: gettext.info, Node: c-format, Next: objc-format, Prev: Translators for other Languages, Up: Translators for other Languages
11071 15.3.1 C Format Strings
11072 -----------------------
11074 C format strings are described in POSIX (IEEE P1003.1 2001), section
11076 <http://www.opengroup.org/onlinepubs/007904975/functions/fprintf.html>.
11077 See also the fprintf() manual page,
11078 <http://www.linuxvalley.it/encyclopedia/ldp/manpage/man3/printf.3.php>,
11079 <http://informatik.fh-wuerzburg.de/student/i510/man/printf.html>.
11081 Although format strings with positions that reorder arguments, such
11084 "Only %2$d bytes free on '%1$s'."
11086 which is semantically equivalent to
11088 "'%s' has only %d bytes free."
11090 are a POSIX/XSI feature and not specified by ISO C 99, translators can
11091 rely on this reordering ability: On the few platforms where ‘printf()’,
11092 ‘fprintf()’ etc. don’t support this feature natively, ‘libintl.a’ or
11093 ‘libintl.so’ provides replacement functions, and GNU ‘<libintl.h>’
11094 activates these replacement functions automatically.
11096 As a special feature for Farsi (Persian) and maybe Arabic,
11097 translators can insert an ‘I’ flag into numeric format directives. For
11098 example, the translation of ‘"%d"’ can be ‘"%Id"’. The effect of this
11099 flag, on systems with GNU ‘libc’, is that in the output, the ASCII
11100 digits are replaced with the ‘outdigits’ defined in the ‘LC_CTYPE’
11101 locale category. On other systems, the ‘gettext’ function removes this
11102 flag, so that it has no effect.
11104 Note that the programmer should _not_ put this flag into the
11105 untranslated string. (Putting the ‘I’ format directive flag into an
11106 MSGID string would lead to undefined behaviour on platforms without
11107 glibc when NLS is disabled.)
11110 File: gettext.info, Node: objc-format, Next: sh-format, Prev: c-format, Up: Translators for other Languages
11112 15.3.2 Objective C Format Strings
11113 ---------------------------------
11115 Objective C format strings are like C format strings. They support
11116 an additional format directive: "%@", which when executed consumes an
11117 argument of type ‘Object *’.
11120 File: gettext.info, Node: sh-format, Next: python-format, Prev: objc-format, Up: Translators for other Languages
11122 15.3.3 Shell Format Strings
11123 ---------------------------
11125 Shell format strings, as supported by GNU gettext and the ‘envsubst’
11126 program, are strings with references to shell variables in the form
11127 ‘$VARIABLE’ or ‘${VARIABLE}’. References of the form
11128 ‘${VARIABLE-DEFAULT}’, ‘${VARIABLE:-DEFAULT}’, ‘${VARIABLE=DEFAULT}’,
11129 ‘${VARIABLE:=DEFAULT}’, ‘${VARIABLE+REPLACEMENT}’,
11130 ‘${VARIABLE:+REPLACEMENT}’, ‘${VARIABLE?IGNORED}’,
11131 ‘${VARIABLE:?IGNORED}’, that would be valid inside shell scripts, are
11132 not supported. The VARIABLE names must consist solely of alphanumeric
11133 or underscore ASCII characters, not start with a digit and be nonempty;
11134 otherwise such a variable reference is ignored.
11137 File: gettext.info, Node: python-format, Next: lisp-format, Prev: sh-format, Up: Translators for other Languages
11139 15.3.4 Python Format Strings
11140 ----------------------------
11142 There are two kinds of format strings in Python: those acceptable to
11143 the Python built-in format operator ‘%’, labelled as ‘python-format’,
11144 and those acceptable to the ‘format’ method of the ‘str’ object.
11146 Python ‘%’ format strings are described in Python Library reference /
11147 5. Built-in Types / 5.6. Sequence Types /
11148 5.6.2. String Formatting Operations.
11149 <http://docs.python.org/2/library/stdtypes.html#string-formatting-operations>.
11151 Python brace format strings are described in
11152 PEP 3101 – Advanced String Formatting,
11153 <http://www.python.org/dev/peps/pep-3101/>.
11156 File: gettext.info, Node: lisp-format, Next: elisp-format, Prev: python-format, Up: Translators for other Languages
11158 15.3.5 Lisp Format Strings
11159 --------------------------
11161 Lisp format strings are described in the Common Lisp HyperSpec,
11162 chapter 22.3 Formatted Output,
11163 <http://www.lisp.org/HyperSpec/Body/sec_22-3.html>.
11166 File: gettext.info, Node: elisp-format, Next: librep-format, Prev: lisp-format, Up: Translators for other Languages
11168 15.3.6 Emacs Lisp Format Strings
11169 --------------------------------
11171 Emacs Lisp format strings are documented in the Emacs Lisp reference,
11172 section Formatting Strings,
11173 <http://www.gnu.org/manual/elisp-manual-21-2.8/html_chapter/elisp_4.html#SEC75>.
11174 Note that as of version 21, XEmacs supports numbered argument
11175 specifications in format strings while FSF Emacs doesn’t.
11178 File: gettext.info, Node: librep-format, Next: scheme-format, Prev: elisp-format, Up: Translators for other Languages
11180 15.3.7 librep Format Strings
11181 ----------------------------
11183 librep format strings are documented in the librep manual, section
11185 <http://librep.sourceforge.net/librep-manual.html#Formatted%20Output>,
11186 <http://www.gwinnup.org/research/docs/librep.html#SEC122>.
11189 File: gettext.info, Node: scheme-format, Next: smalltalk-format, Prev: librep-format, Up: Translators for other Languages
11191 15.3.8 Scheme Format Strings
11192 ----------------------------
11194 Scheme format strings are documented in the SLIB manual, section
11195 Format Specification.
11198 File: gettext.info, Node: smalltalk-format, Next: java-format, Prev: scheme-format, Up: Translators for other Languages
11200 15.3.9 Smalltalk Format Strings
11201 -------------------------------
11203 Smalltalk format strings are described in the GNU Smalltalk
11204 documentation, class ‘CharArray’, methods ‘bindWith:’ and
11205 ‘bindWithArguments:’.
11206 <http://www.gnu.org/software/smalltalk/gst-manual/gst_68.html#SEC238>.
11207 In summary, a directive starts with ‘%’ and is followed by ‘%’ or a
11208 nonzero digit (‘1’ to ‘9’).
11211 File: gettext.info, Node: java-format, Next: csharp-format, Prev: smalltalk-format, Up: Translators for other Languages
11213 15.3.10 Java Format Strings
11214 ---------------------------
11216 Java format strings are described in the JDK documentation for class
11217 ‘java.text.MessageFormat’,
11218 <http://java.sun.com/j2se/1.4/docs/api/java/text/MessageFormat.html>.
11219 See also the ICU documentation
11220 <http://oss.software.ibm.com/icu/apiref/classMessageFormat.html>.
11223 File: gettext.info, Node: csharp-format, Next: awk-format, Prev: java-format, Up: Translators for other Languages
11225 15.3.11 C# Format Strings
11226 -------------------------
11228 C# format strings are described in the .NET documentation for class
11229 ‘System.String’ and in
11230 <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpConFormattingOverview.asp>.
11233 File: gettext.info, Node: awk-format, Next: object-pascal-format, Prev: csharp-format, Up: Translators for other Languages
11235 15.3.12 awk Format Strings
11236 --------------------------
11238 awk format strings are described in the gawk documentation, section
11239 Printf, <http://www.gnu.org/manual/gawk/html_node/Printf.html#Printf>.
11242 File: gettext.info, Node: object-pascal-format, Next: ycp-format, Prev: awk-format, Up: Translators for other Languages
11244 15.3.13 Object Pascal Format Strings
11245 ------------------------------------
11247 Object Pascal format strings are described in the documentation of
11248 the Free Pascal runtime library, section Format,
11249 <http://www.freepascal.org/docs-html/rtl/sysutils/format.html>.
11252 File: gettext.info, Node: ycp-format, Next: tcl-format, Prev: object-pascal-format, Up: Translators for other Languages
11254 15.3.14 YCP Format Strings
11255 --------------------------
11257 YCP sformat strings are described in the libycp documentation
11258 <file:/usr/share/doc/packages/libycp/YCP-builtins.html>. In summary, a
11259 directive starts with ‘%’ and is followed by ‘%’ or a nonzero digit (‘1’
11263 File: gettext.info, Node: tcl-format, Next: perl-format, Prev: ycp-format, Up: Translators for other Languages
11265 15.3.15 Tcl Format Strings
11266 --------------------------
11268 Tcl format strings are described in the ‘format.n’ manual page,
11269 <http://www.scriptics.com/man/tcl8.3/TclCmd/format.htm>.
11272 File: gettext.info, Node: perl-format, Next: php-format, Prev: tcl-format, Up: Translators for other Languages
11274 15.3.16 Perl Format Strings
11275 ---------------------------
11277 There are two kinds format strings in Perl: those acceptable to the
11278 Perl built-in function ‘printf’, labelled as ‘perl-format’, and those
11279 acceptable to the ‘libintl-perl’ function ‘__x’, labelled as
11280 ‘perl-brace-format’.
11282 Perl ‘printf’ format strings are described in the ‘sprintf’ section
11285 Perl brace format strings are described in the
11286 ‘Locale::TextDomain(3pm)’ manual page of the CPAN package libintl-perl.
11287 In brief, Perl format uses placeholders put between braces (‘{’ and
11288 ‘}’). The placeholder must have the syntax of simple identifiers.
11291 File: gettext.info, Node: php-format, Next: gcc-internal-format, Prev: perl-format, Up: Translators for other Languages
11293 15.3.17 PHP Format Strings
11294 --------------------------
11296 PHP format strings are described in the documentation of the PHP
11297 function ‘sprintf’, in ‘phpdoc/manual/function.sprintf.html’ or
11298 <http://www.php.net/manual/en/function.sprintf.php>.
11301 File: gettext.info, Node: gcc-internal-format, Next: gfc-internal-format, Prev: php-format, Up: Translators for other Languages
11303 15.3.18 GCC internal Format Strings
11304 -----------------------------------
11306 These format strings are used inside the GCC sources. In such a
11307 format string, a directive starts with ‘%’, is optionally followed by a
11308 size specifier ‘l’, an optional flag ‘+’, another optional flag ‘#’, and
11309 is finished by a specifier: ‘%’ denotes a literal percent sign, ‘c’
11310 denotes a character, ‘s’ denotes a string, ‘i’ and ‘d’ denote an
11311 integer, ‘o’, ‘u’, ‘x’ denote an unsigned integer, ‘.*s’ denotes a
11312 string preceded by a width specification, ‘H’ denotes a ‘location_t *’
11313 pointer, ‘D’ denotes a general declaration, ‘F’ denotes a function
11314 declaration, ‘T’ denotes a type, ‘A’ denotes a function argument, ‘C’
11315 denotes a tree code, ‘E’ denotes an expression, ‘L’ denotes a
11316 programming language, ‘O’ denotes a binary operator, ‘P’ denotes a
11317 function parameter, ‘Q’ denotes an assignment operator, ‘V’ denotes a
11318 const/volatile qualifier.
11321 File: gettext.info, Node: gfc-internal-format, Next: qt-format, Prev: gcc-internal-format, Up: Translators for other Languages
11323 15.3.19 GFC internal Format Strings
11324 -----------------------------------
11326 These format strings are used inside the GNU Fortran Compiler
11327 sources, that is, the Fortran frontend in the GCC sources. In such a
11328 format string, a directive starts with ‘%’ and is finished by a
11329 specifier: ‘%’ denotes a literal percent sign, ‘C’ denotes the current
11330 source location, ‘L’ denotes a source location, ‘c’ denotes a character,
11331 ‘s’ denotes a string, ‘i’ and ‘d’ denote an integer, ‘u’ denotes an
11332 unsigned integer. ‘i’, ‘d’, and ‘u’ may be preceded by a size specifier
11336 File: gettext.info, Node: qt-format, Next: qt-plural-format, Prev: gfc-internal-format, Up: Translators for other Languages
11338 15.3.20 Qt Format Strings
11339 -------------------------
11341 Qt format strings are described in the documentation of the QString
11342 class <file:/usr/lib/qt-4.3.0/doc/html/qstring.html>. In summary, a
11343 directive consists of a ‘%’ followed by a digit. The same directive
11344 cannot occur more than once in a format string.
11347 File: gettext.info, Node: qt-plural-format, Next: kde-format, Prev: qt-format, Up: Translators for other Languages
11349 15.3.21 Qt Format Strings
11350 -------------------------
11352 Qt format strings are described in the documentation of the
11353 QObject::tr method <file:/usr/lib/qt-4.3.0/doc/html/qobject.html>. In
11354 summary, the only allowed directive is ‘%n’.
11357 File: gettext.info, Node: kde-format, Next: kde-kuit-format, Prev: qt-plural-format, Up: Translators for other Languages
11359 15.3.22 KDE Format Strings
11360 --------------------------
11362 KDE 4 format strings are defined as follows: A directive consists of
11363 a ‘%’ followed by a non-zero decimal number. If a ‘%n’ occurs in a
11364 format strings, all of ‘%1’, ..., ‘%(n-1)’ must occur as well, except
11365 possibly one of them.
11368 File: gettext.info, Node: kde-kuit-format, Next: boost-format, Prev: kde-format, Up: Translators for other Languages
11370 15.3.23 KUIT Format Strings
11371 ---------------------------
11373 KUIT (KDE User Interface Text) is compatible with KDE 4 format
11374 strings, while it also allows programmers to add semantic information to
11375 a format string, through XML markup tags. For example, if the first
11376 format directive in a string is a filename, programmers could indicate
11377 that with a ‘filename’ tag, like ‘<filename>%1</filename>’.
11379 KUIT format strings are described in
11380 <http://api.kde.org/frameworks-api/frameworks5-apidocs/ki18n/html/prg_guide.html#kuit_markup>.
11383 File: gettext.info, Node: boost-format, Next: lua-format, Prev: kde-kuit-format, Up: Translators for other Languages
11385 15.3.24 Boost Format Strings
11386 ----------------------------
11388 Boost format strings are described in the documentation of the
11389 ‘boost::format’ class, at
11390 <http://www.boost.org/libs/format/doc/format.html>. In summary, a
11391 directive has either the same syntax as in a C format string, such as
11392 ‘%1$+5d’, or may be surrounded by vertical bars, such as ‘%|1$+5d|’ or
11393 ‘%|1$+5|’, or consists of just an argument number between percent signs,
11397 File: gettext.info, Node: lua-format, Next: javascript-format, Prev: boost-format, Up: Translators for other Languages
11399 15.3.25 Lua Format Strings
11400 --------------------------
11402 Lua format strings are described in the Lua reference manual, section
11403 String Manipulation,
11404 <http://www.lua.org/manual/5.1/manual.html#pdf-string.format>.
11407 File: gettext.info, Node: javascript-format, Prev: lua-format, Up: Translators for other Languages
11409 15.3.26 JavaScript Format Strings
11410 ---------------------------------
11412 Although JavaScript specification itself does not define any format
11413 strings, many JavaScript implementations provide printf-like functions.
11414 ‘xgettext’ understands a set of common format strings used in popular
11415 JavaScript implementations including Gjs, Seed, and Node.JS. In such a
11416 format string, a directive starts with ‘%’ and is finished by a
11417 specifier: ‘%’ denotes a literal percent sign, ‘c’ denotes a character,
11418 ‘s’ denotes a string, ‘b’, ‘d’, ‘o’, ‘x’, ‘X’ denote an integer, ‘f’
11419 denotes floating-point number, ‘j’ denotes a JSON object.
11422 File: gettext.info, Node: Maintainers for other Languages, Next: List of Programming Languages, Prev: Translators for other Languages, Up: Programming Languages
11424 15.4 The Maintainer’s View
11425 ==========================
11427 For the maintainer, the general procedure differs from the C language
11430 • For those languages that don’t use GNU gettext, the ‘intl/’
11431 directory is not needed and can be omitted. This means that the
11432 maintainer calls the ‘gettextize’ program without the ‘--intl’
11433 option, and that he invokes the ‘AM_GNU_GETTEXT’ autoconf macro via
11434 ‘AM_GNU_GETTEXT([external])’.
11436 • If only a single programming language is used, the
11437 ‘XGETTEXT_OPTIONS’ variable in ‘po/Makevars’ (*note po/Makevars::)
11438 should be adjusted to match the ‘xgettext’ options for that
11439 particular programming language. If the package uses more than one
11440 programming language with ‘gettext’ support, it becomes necessary
11441 to change the POT file construction rule in ‘po/Makefile.in.in’.
11442 It is recommended to make one ‘xgettext’ invocation per programming
11443 language, each with the options appropriate for that language, and
11444 to combine the resulting files using ‘msgcat’.
11447 File: gettext.info, Node: List of Programming Languages, Next: List of Data Formats, Prev: Maintainers for other Languages, Up: Programming Languages
11449 15.5 Individual Programming Languages
11450 =====================================
11454 * C:: C, C++, Objective C
11455 * sh:: sh - Shell Script
11456 * bash:: bash - Bourne-Again Shell Script
11458 * Common Lisp:: GNU clisp - Common Lisp
11459 * clisp C:: GNU clisp C sources
11460 * Emacs Lisp:: Emacs Lisp
11462 * Scheme:: GNU guile - Scheme
11463 * Smalltalk:: GNU Smalltalk
11467 * Pascal:: Pascal - Free Pascal Compiler
11468 * wxWidgets:: wxWidgets library
11469 * YCP:: YCP - YaST2 scripting language
11470 * Tcl:: Tcl - Tk’s scripting language
11472 * PHP:: PHP Hypertext Preprocessor
11474 * GCC-source:: GNU Compiler Collection sources
11476 * JavaScript:: JavaScript
11480 File: gettext.info, Node: C, Next: sh, Prev: List of Programming Languages, Up: List of Programming Languages
11482 15.5.1 C, C++, Objective C
11483 --------------------------
11486 gcc, gpp, gobjc, glibc, gettext
11490 For C++: ‘C’, ‘c++’, ‘cc’, ‘cxx’, ‘cpp’, ‘hpp’.
11491 For Objective C: ‘m’.
11499 gettext/ngettext functions
11500 ‘gettext’, ‘dgettext’, ‘dcgettext’, ‘ngettext’, ‘dngettext’,
11504 ‘textdomain’ function
11507 ‘bindtextdomain’ function
11510 Programmer must call ‘setlocale (LC_ALL, "")’
11513 ‘#include <libintl.h>’
11514 ‘#include <locale.h>’
11515 ‘#define _(string) gettext (string)’
11517 Use or emulate GNU gettext
11523 Formatting with positions
11524 ‘fprintf "%2$d %1$d"’
11525 In C++: ‘autosprintf "%2$d %1$d"’ (*note Introduction:
11529 autoconf (gettext.m4) and #if ENABLE_NLS
11534 The following examples are available in the ‘examples’ directory:
11535 ‘hello-c’, ‘hello-c-gnome’, ‘hello-c++’, ‘hello-c++-qt’,
11536 ‘hello-c++-kde’, ‘hello-c++-gnome’, ‘hello-c++-wxwidgets’, ‘hello-objc’,
11537 ‘hello-objc-gnustep’, ‘hello-objc-gnome’.
11540 File: gettext.info, Node: sh, Next: bash, Prev: C, Up: List of Programming Languages
11542 15.5.2 sh - Shell Script
11543 ------------------------
11552 ‘"abc"’, ‘'abc'’, ‘abc’
11555 ‘"`gettext \"abc\"`"’
11557 gettext/ngettext functions
11558 ‘gettext’, ‘ngettext’ programs
11559 ‘eval_gettext’, ‘eval_ngettext’ shell functions
11562 environment variable ‘TEXTDOMAIN’
11565 environment variable ‘TEXTDOMAINDIR’
11573 Use or emulate GNU gettext
11579 Formatting with positions
11588 An example is available in the ‘examples’ directory: ‘hello-sh’.
11592 * Preparing Shell Scripts:: Preparing Shell Scripts for Internationalization
11593 * gettext.sh:: Contents of ‘gettext.sh’
11594 * gettext Invocation:: Invoking the ‘gettext’ program
11595 * ngettext Invocation:: Invoking the ‘ngettext’ program
11596 * envsubst Invocation:: Invoking the ‘envsubst’ program
11597 * eval_gettext Invocation:: Invoking the ‘eval_gettext’ function
11598 * eval_ngettext Invocation:: Invoking the ‘eval_ngettext’ function
11601 File: gettext.info, Node: Preparing Shell Scripts, Next: gettext.sh, Prev: sh, Up: sh
11603 15.5.2.1 Preparing Shell Scripts for Internationalization
11604 .........................................................
11606 Preparing a shell script for internationalization is conceptually
11607 similar to the steps described in *note Sources::. The concrete steps
11608 for shell scripts are as follows.
11614 near the top of the script. ‘gettext.sh’ is a shell function
11615 library that provides the functions ‘eval_gettext’ (see *note
11616 eval_gettext Invocation::) and ‘eval_ngettext’ (see *note
11617 eval_ngettext Invocation::). You have to ensure that ‘gettext.sh’
11618 can be found in the ‘PATH’.
11620 2. Set and export the ‘TEXTDOMAIN’ and ‘TEXTDOMAINDIR’ environment
11621 variables. Usually ‘TEXTDOMAIN’ is the package or program name,
11622 and ‘TEXTDOMAINDIR’ is the absolute pathname corresponding to
11623 ‘$prefix/share/locale’, where ‘$prefix’ is the installation
11626 TEXTDOMAIN=@PACKAGE@
11628 TEXTDOMAINDIR=@LOCALEDIR@
11629 export TEXTDOMAINDIR
11631 3. Prepare the strings for translation, as described in *note
11632 Preparing Strings::.
11634 4. Simplify translatable strings so that they don’t contain command
11635 substitution (‘"`...`"’ or ‘"$(...)"’), variable access with
11636 defaulting (like ‘${VARIABLE-DEFAULT}’), access to positional
11637 arguments (like ‘$0’, ‘$1’, ...) or highly volatile shell
11638 variables (like ‘$?’). This can always be done through simple
11639 local code restructuring. For example,
11641 echo "Usage: $0 [OPTION] FILE..."
11646 echo "Usage: $program_name [OPTION] FILE..."
11650 echo "Remaining files: `ls | wc -l`"
11654 filecount="`ls | wc -l`"
11655 echo "Remaining files: $filecount"
11657 5. For each translatable string, change the output command ‘echo’ or
11658 ‘$echo’ to ‘gettext’ (if the string contains no references to shell
11659 variables) or to ‘eval_gettext’ (if it refers to shell variables),
11660 followed by a no-argument ‘echo’ command (to account for the
11661 terminating newline). Similarly, for cases with plural handling,
11662 replace a conditional ‘echo’ command with an invocation of
11663 ‘ngettext’ or ‘eval_ngettext’, followed by a no-argument ‘echo’
11666 When doing this, you also need to add an extra backslash before the
11667 dollar sign in references to shell variables, so that the
11668 ‘eval_gettext’ function receives the translatable string before the
11669 variable values are substituted into it. For example,
11671 echo "Remaining files: $filecount"
11675 eval_gettext "Remaining files: \$filecount"; echo
11677 If the output command is not ‘echo’, you can make it use ‘echo’
11678 nevertheless, through the use of backquotes. However, note that
11679 inside backquotes, backslashes must be doubled to be effective
11680 (because the backquoting eats one level of backslashes). For
11681 example, assuming that ‘error’ is a shell function that signals an
11684 error "file not found: $filename"
11686 is first transformed into
11688 error "`echo \"file not found: \$filename\"`"
11692 error "`eval_gettext \"file not found: \\\$filename\"`"
11695 File: gettext.info, Node: gettext.sh, Next: gettext Invocation, Prev: Preparing Shell Scripts, Up: sh
11697 15.5.2.2 Contents of ‘gettext.sh’
11698 .................................
11700 ‘gettext.sh’, contained in the run-time package of GNU gettext,
11701 provides the following:
11703 • $echo The variable ‘echo’ is set to a command that outputs its
11704 first argument and a newline, without interpreting backslashes in
11705 the argument string.
11707 • eval_gettext See *note eval_gettext Invocation::.
11709 • eval_ngettext See *note eval_ngettext Invocation::.
11712 File: gettext.info, Node: gettext Invocation, Next: ngettext Invocation, Prev: gettext.sh, Up: sh
11714 15.5.2.3 Invoking the ‘gettext’ program
11715 .......................................
11717 gettext [OPTION] [[TEXTDOMAIN] MSGID]
11718 gettext [OPTION] -s [MSGID]...
11720 The ‘gettext’ program displays the native language translation of a
11726 ‘--domain=TEXTDOMAIN’
11727 Retrieve translated messages from TEXTDOMAIN. Usually a TEXTDOMAIN
11728 corresponds to a package, a program, or a module of a program.
11731 Enable expansion of some escape sequences. This option is for
11732 compatibility with the ‘echo’ program or shell built-in. The
11733 escape sequences ‘\a’, ‘\b’, ‘\c’, ‘\f’, ‘\n’, ‘\r’, ‘\t’, ‘\v’,
11734 ‘\\’, and ‘\’ followed by one to three octal digits, are
11735 interpreted like the System V ‘echo’ program did.
11738 This option is only for compatibility with the ‘echo’ program or
11739 shell built-in. It has no effect.
11743 Display this help and exit.
11746 Suppress trailing newline. By default, ‘gettext’ adds a newline to
11751 Output version information and exit.
11753 ‘[TEXTDOMAIN] MSGID’
11754 Retrieve translated message corresponding to MSGID from TEXTDOMAIN.
11756 If the TEXTDOMAIN parameter is not given, the domain is determined
11757 from the environment variable ‘TEXTDOMAIN’. If the message catalog is
11758 not found in the regular directory, another location can be specified
11759 with the environment variable ‘TEXTDOMAINDIR’.
11761 When used with the ‘-s’ option the program behaves like the ‘echo’
11762 command. But it does not simply copy its arguments to stdout. Instead
11763 those messages found in the selected catalog are translated.
11765 Note: ‘xgettext’ supports only the one-argument form of the ‘gettext’
11766 invocation, where no options are present and the TEXTDOMAIN is implicit,
11767 from the environment.
11770 File: gettext.info, Node: ngettext Invocation, Next: envsubst Invocation, Prev: gettext Invocation, Up: sh
11772 15.5.2.4 Invoking the ‘ngettext’ program
11773 ........................................
11775 ngettext [OPTION] [TEXTDOMAIN] MSGID MSGID-PLURAL COUNT
11777 The ‘ngettext’ program displays the native language translation of a
11778 textual message whose grammatical form depends on a number.
11783 ‘--domain=TEXTDOMAIN’
11784 Retrieve translated messages from TEXTDOMAIN. Usually a TEXTDOMAIN
11785 corresponds to a package, a program, or a module of a program.
11788 Enable expansion of some escape sequences. This option is for
11789 compatibility with the ‘gettext’ program. The escape sequences
11790 ‘\a’, ‘\b’, ‘\c’, ‘\f’, ‘\n’, ‘\r’, ‘\t’, ‘\v’, ‘\\’, and ‘\’
11791 followed by one to three octal digits, are interpreted like the
11792 System V ‘echo’ program did.
11795 This option is only for compatibility with the ‘gettext’ program.
11800 Display this help and exit.
11804 Output version information and exit.
11807 Retrieve translated message from TEXTDOMAIN.
11809 ‘MSGID MSGID-PLURAL’
11810 Translate MSGID (English singular) / MSGID-PLURAL (English plural).
11813 Choose singular/plural form based on this value.
11815 If the TEXTDOMAIN parameter is not given, the domain is determined
11816 from the environment variable ‘TEXTDOMAIN’. If the message catalog is
11817 not found in the regular directory, another location can be specified
11818 with the environment variable ‘TEXTDOMAINDIR’.
11820 Note: ‘xgettext’ supports only the three-arguments form of the
11821 ‘ngettext’ invocation, where no options are present and the TEXTDOMAIN
11822 is implicit, from the environment.
11825 File: gettext.info, Node: envsubst Invocation, Next: eval_gettext Invocation, Prev: ngettext Invocation, Up: sh
11827 15.5.2.5 Invoking the ‘envsubst’ program
11828 ........................................
11830 envsubst [OPTION] [SHELL-FORMAT]
11832 The ‘envsubst’ program substitutes the values of environment
11839 Output the variables occurring in SHELL-FORMAT.
11841 *Informative output*
11845 Display this help and exit.
11849 Output version information and exit.
11851 In normal operation mode, standard input is copied to standard
11852 output, with references to environment variables of the form ‘$VARIABLE’
11853 or ‘${VARIABLE}’ being replaced with the corresponding values. If a
11854 SHELL-FORMAT is given, only those environment variables that are
11855 referenced in SHELL-FORMAT are substituted; otherwise all environment
11856 variables references occurring in standard input are substituted.
11858 These substitutions are a subset of the substitutions that a shell
11859 performs on unquoted and double-quoted strings. Other kinds of
11860 substitutions done by a shell, such as ‘${VARIABLE-DEFAULT}’ or
11861 ‘$(COMMAND-LIST)’ or ‘`COMMAND-LIST`’, are not performed by the
11862 ‘envsubst’ program, due to security reasons.
11864 When ‘--variables’ is used, standard input is ignored, and the output
11865 consists of the environment variables that are referenced in
11866 SHELL-FORMAT, one per line.
11869 File: gettext.info, Node: eval_gettext Invocation, Next: eval_ngettext Invocation, Prev: envsubst Invocation, Up: sh
11871 15.5.2.6 Invoking the ‘eval_gettext’ function
11872 .............................................
11876 This function outputs the native language translation of a textual
11877 message, performing dollar-substitution on the result. Note that only
11878 shell variables mentioned in MSGID will be dollar-substituted in the
11882 File: gettext.info, Node: eval_ngettext Invocation, Prev: eval_gettext Invocation, Up: sh
11884 15.5.2.7 Invoking the ‘eval_ngettext’ function
11885 ..............................................
11887 eval_ngettext MSGID MSGID-PLURAL COUNT
11889 This function outputs the native language translation of a textual
11890 message whose grammatical form depends on a number, performing
11891 dollar-substitution on the result. Note that only shell variables
11892 mentioned in MSGID or MSGID-PLURAL will be dollar-substituted in the
11896 File: gettext.info, Node: bash, Next: Python, Prev: sh, Up: List of Programming Languages
11898 15.5.3 bash - Bourne-Again Shell Script
11899 ---------------------------------------
11901 GNU ‘bash’ 2.0 or newer has a special shorthand for translating a
11902 string and substituting variable values in it: ‘$"msgid"’. But the use
11903 of this construct is *discouraged*, due to the security holes it opens
11904 and due to its portability problems.
11906 The security holes of ‘$"..."’ come from the fact that after looking
11907 up the translation of the string, ‘bash’ processes it like it processes
11908 any double-quoted string: dollar and backquote processing, like ‘eval’
11911 1. In a locale whose encoding is one of BIG5, BIG5-HKSCS, GBK,
11912 GB18030, SHIFT_JIS, JOHAB, some double-byte characters have a
11913 second byte whose value is ‘0x60’. For example, the byte sequence
11914 ‘\xe0\x60’ is a single character in these locales. Many versions
11915 of ‘bash’ (all versions up to bash-2.05, and newer versions on
11916 platforms without ‘mbsrtowcs()’ function) don’t know about
11917 character boundaries and see a backquote character where there is
11918 only a particular Chinese character. Thus it can start executing
11919 part of the translation as a command list. This situation can
11920 occur even without the translator being aware of it: if the
11921 translator provides translations in the UTF-8 encoding, it is the
11922 ‘gettext()’ function which will, during its conversion from the
11923 translator’s encoding to the user’s locale’s encoding, produce the
11924 dangerous ‘\x60’ bytes.
11926 2. A translator could - voluntarily or inadvertently - use backquotes
11927 ‘"`...`"’ or dollar-parentheses ‘"$(...)"’ in her translations.
11928 The enclosed strings would be executed as command lists by the
11931 The portability problem is that ‘bash’ must be built with
11932 internationalization support; this is normally not the case on systems
11933 that don’t have the ‘gettext()’ function in libc.
11936 File: gettext.info, Node: Python, Next: Common Lisp, Prev: bash, Up: List of Programming Languages
11948 ‘'abc'’, ‘u'abc'’, ‘r'abc'’, ‘ur'abc'’,
11949 ‘"abc"’, ‘u"abc"’, ‘r"abc"’, ‘ur"abc"’,
11950 ‘'''abc'''’, ‘u'''abc'''’, ‘r'''abc'''’, ‘ur'''abc'''’,
11951 ‘"""abc"""’, ‘u"""abc"""’, ‘r"""abc"""’, ‘ur"""abc"""’
11956 gettext/ngettext functions
11957 ‘gettext.gettext’, ‘gettext.dgettext’, ‘gettext.ngettext’,
11958 ‘gettext.dngettext’, also ‘ugettext’, ‘ungettext’
11961 ‘gettext.textdomain’ function, or ‘gettext.install(DOMAIN)’
11965 ‘gettext.bindtextdomain’ function, or
11966 ‘gettext.install(DOMAIN,LOCALEDIR)’ function
11969 not used by the gettext emulation
11974 Use or emulate GNU gettext
11980 Formatting with positions
11981 ‘'...%(ident)d...' % { 'ident': value }’
11989 An example is available in the ‘examples’ directory: ‘hello-python’.
11991 A note about format strings: Python supports format strings with
11992 unnamed arguments, such as ‘'...%d...'’, and format strings with named
11993 arguments, such as ‘'...%(ident)d...'’. The latter are preferable for
11994 internationalized programs, for two reasons:
11996 • When a format string takes more than one argument, the translator
11997 can provide a translation that uses the arguments in a different
11998 order, if the format string uses named arguments. For example, the
11999 translator can reformulate
12000 "'%(volume)s' has only %(freespace)d bytes free."
12002 "Only %(freespace)d bytes free on '%(volume)s'."
12003 Additionally, the identifiers also provide some context to the
12006 • In the context of plural forms, the format string used for the
12007 singular form does not use the numeric argument in many languages.
12008 Even in English, one prefers to write ‘"one hour"’ instead of ‘"1
12009 hour"’. Omitting individual arguments from format strings like
12010 this is only possible with the named argument syntax. (With
12011 unnamed arguments, Python – unlike C – verifies that the format
12012 string uses all supplied arguments.)
12015 File: gettext.info, Node: Common Lisp, Next: clisp C, Prev: Python, Up: List of Programming Languages
12017 15.5.5 GNU clisp - Common Lisp
12018 ------------------------------
12021 clisp 2.28 or newer
12030 ‘(_ "abc")’, ‘(ENGLISH "abc")’
12032 gettext/ngettext functions
12033 ‘i18n:gettext’, ‘i18n:ngettext’
12039 ‘i18n:textdomaindir’
12047 Use or emulate GNU gettext
12051 ‘xgettext -k_ -kENGLISH’
12053 Formatting with positions
12054 ‘format "~1@*~D ~0@*~D"’
12057 On platforms without gettext, no translation.
12062 An example is available in the ‘examples’ directory: ‘hello-clisp’.
12065 File: gettext.info, Node: clisp C, Next: Emacs Lisp, Prev: Common Lisp, Up: List of Programming Languages
12067 15.5.6 GNU clisp C sources
12068 --------------------------
12080 ‘ENGLISH ? "abc" : ""’
12084 gettext/ngettext functions
12085 ‘clgettext’, ‘clgettextl’
12097 ‘#include "lispbibl.c"’
12099 Use or emulate GNU gettext
12105 Formatting with positions
12106 ‘fprintf "%2$d %1$d"’
12109 On platforms without gettext, no translation.
12115 File: gettext.info, Node: Emacs Lisp, Next: librep, Prev: clisp C, Up: List of Programming Languages
12132 gettext/ngettext functions
12133 ‘gettext’, ‘dgettext’ (xemacs only)
12136 ‘domain’ special form (xemacs only)
12139 ‘bind-text-domain’ function (xemacs only)
12147 Use or emulate GNU gettext
12153 Formatting with positions
12154 ‘format "%2$d %1$d"’
12157 Only XEmacs. Without ‘I18N3’ defined at build time, no
12164 File: gettext.info, Node: librep, Next: Scheme, Prev: Emacs Lisp, Up: List of Programming Languages
12170 librep 0.15.3 or newer
12181 gettext/ngettext functions
12185 ‘textdomain’ function
12188 ‘bindtextdomain’ function
12194 ‘(require 'rep.i18n.gettext)’
12196 Use or emulate GNU gettext
12202 Formatting with positions
12203 ‘format "%2$d %1$d"’
12206 On platforms without gettext, no translation.
12211 An example is available in the ‘examples’ directory: ‘hello-librep’.
12214 File: gettext.info, Node: Scheme, Next: Smalltalk, Prev: librep, Up: List of Programming Languages
12216 15.5.9 GNU guile - Scheme
12217 -------------------------
12229 ‘(_ "abc")’, ‘_"abc"’ (GIMP script-fu extension)
12231 gettext/ngettext functions
12232 ‘gettext’, ‘ngettext’
12241 ‘(catch #t (lambda () (setlocale LC_ALL "")) (lambda args #f))’
12244 ‘(use-modules (ice-9 format))’
12246 Use or emulate GNU gettext
12252 Formatting with positions
12256 On platforms without gettext, no translation.
12261 An example is available in the ‘examples’ directory: ‘hello-guile’.
12264 File: gettext.info, Node: Smalltalk, Next: Java, Prev: Scheme, Up: List of Programming Languages
12266 15.5.10 GNU Smalltalk
12267 ---------------------
12281 gettext/ngettext functions
12282 ‘LcMessagesDomain>>#at:’, ‘LcMessagesDomain>>#at:plural:with:’
12285 ‘LcMessages>>#domain:localeDirectory:’ (returns a
12286 ‘LcMessagesDomain’ object).
12287 Example: ‘I18N Locale default messages domain: 'gettext'
12288 localeDirectory: /usr/local/share/locale'’
12291 ‘LcMessages>>#domain:localeDirectory:’, see above.
12294 Automatic if you use ‘I18N Locale default’.
12297 ‘PackageLoader fileInPackage: 'I18N'!’
12299 Use or emulate GNU gettext
12305 Formatting with positions
12306 ‘'%1 %2' bindWith: 'Hello' with: 'world'’
12314 An example is available in the ‘examples’ directory:
12318 File: gettext.info, Node: Java, Next: C#, Prev: Smalltalk, Up: List of Programming Languages
12335 gettext/ngettext functions
12336 ‘GettextResource.gettext’, ‘GettextResource.ngettext’,
12337 ‘GettextResource.pgettext’, ‘GettextResource.npgettext’
12340 —, use ‘ResourceBundle.getResource’ instead
12343 —, use CLASSPATH instead
12351 Use or emulate GNU gettext
12352 —, uses a Java specific message catalog format
12357 Formatting with positions
12358 ‘MessageFormat.format "{1,number} {0,number}"’
12366 Before marking strings as internationalizable, uses of the string
12367 concatenation operator need to be converted to ‘MessageFormat’
12368 applications. For example, ‘"file "+filename+" not found"’ becomes
12369 ‘MessageFormat.format("file {0} not found", new Object[] { filename })’.
12370 Only after this is done, can the strings be marked and extracted.
12372 GNU gettext uses the native Java internationalization mechanism,
12373 namely ‘ResourceBundle’s. There are two formats of ‘ResourceBundle’s:
12374 ‘.properties’ files and ‘.class’ files. The ‘.properties’ format is a
12375 text file which the translators can directly edit, like PO files, but
12376 which doesn’t support plural forms. Whereas the ‘.class’ format is
12377 compiled from ‘.java’ source code and can support plural forms (provided
12378 it is accessed through an appropriate API, see below).
12380 To convert a PO file to a ‘.properties’ file, the ‘msgcat’ program
12381 can be used with the option ‘--properties-output’. To convert a
12382 ‘.properties’ file back to a PO file, the ‘msgcat’ program can be used
12383 with the option ‘--properties-input’. All the tools that manipulate PO
12384 files can work with ‘.properties’ files as well, if given the
12385 ‘--properties-input’ and/or ‘--properties-output’ option.
12387 To convert a PO file to a ResourceBundle class, the ‘msgfmt’ program
12388 can be used with the option ‘--java’ or ‘--java2’. To convert a
12389 ResourceBundle back to a PO file, the ‘msgunfmt’ program can be used
12390 with the option ‘--java’.
12392 Two different programmatic APIs can be used to access
12393 ResourceBundles. Note that both APIs work with all kinds of
12394 ResourceBundles, whether GNU gettext generated classes, or other
12395 ‘.class’ or ‘.properties’ files.
12397 1. The ‘java.util.ResourceBundle’ API.
12399 In particular, its ‘getString’ function returns a string
12400 translation. Note that a missing translation yields a
12401 ‘MissingResourceException’.
12403 This has the advantage of being the standard API. And it does not
12404 require any additional libraries, only the ‘msgcat’ generated
12405 ‘.properties’ files or the ‘msgfmt’ generated ‘.class’ files. But
12406 it cannot do plural handling, even if the resource was generated by
12407 ‘msgfmt’ from a PO file with plural handling.
12409 2. The ‘gnu.gettext.GettextResource’ API.
12411 Reference documentation in Javadoc 1.1 style format is in the
12412 javadoc2 directory (javadoc2/index.html).
12414 Its ‘gettext’ function returns a string translation. Note that
12415 when a translation is missing, the MSGID argument is returned
12418 This has the advantage of having the ‘ngettext’ function for plural
12419 handling and the ‘pgettext’ and ‘npgettext’ for strings constraint
12420 to a particular context.
12422 To use this API, one needs the ‘libintl.jar’ file which is part of
12423 the GNU gettext package and distributed under the LGPL.
12425 Four examples, using the second API, are available in the ‘examples’
12426 directory: ‘hello-java’, ‘hello-java-awt’, ‘hello-java-swing’,
12427 ‘hello-java-qtjambi’.
12429 Now, to make use of the API and define a shorthand for ‘getString’,
12430 there are three idioms that you can choose from:
12432 • (This one assumes Java 1.5 or newer.) In a unique class of your
12433 project, say ‘Util’, define a static variable holding the
12434 ‘ResourceBundle’ instance and the shorthand:
12436 private static ResourceBundle myResources =
12437 ResourceBundle.getBundle("domain-name");
12438 public static String _(String s) {
12439 return myResources.getString(s);
12442 All classes containing internationalized strings then contain
12444 import static Util._;
12446 and the shorthand is used like this:
12448 System.out.println(_("Operation completed."));
12450 • In a unique class of your project, say ‘Util’, define a static
12451 variable holding the ‘ResourceBundle’ instance:
12453 public static ResourceBundle myResources =
12454 ResourceBundle.getBundle("domain-name");
12456 All classes containing internationalized strings then contain
12458 private static ResourceBundle res = Util.myResources;
12459 private static String _(String s) { return res.getString(s); }
12461 and the shorthand is used like this:
12463 System.out.println(_("Operation completed."));
12465 • You add a class with a very short name, say ‘S’, containing just
12466 the definition of the resource bundle and of the shorthand:
12469 public static ResourceBundle myResources =
12470 ResourceBundle.getBundle("domain-name");
12471 public static String _(String s) {
12472 return myResources.getString(s);
12476 and the shorthand is used like this:
12478 System.out.println(S._("Operation completed."));
12480 Which of the three idioms you choose, will depend on whether your
12481 project requires portability to Java versions prior to Java 1.5 and, if
12482 so, whether copying two lines of codes into every class is more
12483 acceptable in your project than a class with a single-letter name.
12486 File: gettext.info, Node: C#, Next: gawk, Prev: Java, Up: List of Programming Languages
12492 pnet, pnetlib 0.6.2 or newer, or mono 0.29 or newer
12503 gettext/ngettext functions
12504 ‘GettextResourceManager.GetString’,
12505 ‘GettextResourceManager.GetPluralString’
12506 ‘GettextResourceManager.GetParticularString’
12507 ‘GettextResourceManager.GetParticularPluralString’
12510 ‘new GettextResourceManager(domain)’
12513 —, compiled message catalogs are located in subdirectories of the
12514 directory containing the executable
12522 Use or emulate GNU gettext
12523 —, uses a C# specific message catalog format
12528 Formatting with positions
12529 ‘String.Format "{1} {0}"’
12537 Before marking strings as internationalizable, uses of the string
12538 concatenation operator need to be converted to ‘String.Format’
12539 invocations. For example, ‘"file "+filename+" not found"’ becomes
12540 ‘String.Format("file {0} not found", filename)’. Only after this is
12541 done, can the strings be marked and extracted.
12543 GNU gettext uses the native C#/.NET internationalization mechanism,
12544 namely the classes ‘ResourceManager’ and ‘ResourceSet’. Applications
12545 use the ‘ResourceManager’ methods to retrieve the native language
12546 translation of strings. An instance of ‘ResourceSet’ is the in-memory
12547 representation of a message catalog file. The ‘ResourceManager’ loads
12548 and accesses ‘ResourceSet’ instances as needed to look up the
12551 There are two formats of ‘ResourceSet’s that can be directly loaded
12552 by the C# runtime: ‘.resources’ files and ‘.dll’ files.
12554 • The ‘.resources’ format is a binary file usually generated through
12555 the ‘resgen’ or ‘monoresgen’ utility, but which doesn’t support
12556 plural forms. ‘.resources’ files can also be embedded in .NET
12557 ‘.exe’ files. This only affects whether a file system access is
12558 performed to load the message catalog; it doesn’t affect the
12559 contents of the message catalog.
12561 • On the other hand, the ‘.dll’ format is a binary file that is
12562 compiled from ‘.cs’ source code and can support plural forms
12563 (provided it is accessed through the GNU gettext API, see below).
12565 Note that these .NET ‘.dll’ and ‘.exe’ files are not tied to a
12566 particular platform; their file format and GNU gettext for C# can be
12567 used on any platform.
12569 To convert a PO file to a ‘.resources’ file, the ‘msgfmt’ program can
12570 be used with the option ‘--csharp-resources’. To convert a ‘.resources’
12571 file back to a PO file, the ‘msgunfmt’ program can be used with the
12572 option ‘--csharp-resources’. You can also, in some cases, use the
12573 ‘resgen’ program (from the ‘pnet’ package) or the ‘monoresgen’ program
12574 (from the ‘mono’/‘mcs’ package). These programs can also convert a
12575 ‘.resources’ file back to a PO file. But beware: as of this writing
12576 (January 2004), the ‘monoresgen’ converter is quite buggy and the
12577 ‘resgen’ converter ignores the encoding of the PO files.
12579 To convert a PO file to a ‘.dll’ file, the ‘msgfmt’ program can be
12580 used with the option ‘--csharp’. The result will be a ‘.dll’ file
12581 containing a subclass of ‘GettextResourceSet’, which itself is a
12582 subclass of ‘ResourceSet’. To convert a ‘.dll’ file containing a
12583 ‘GettextResourceSet’ subclass back to a PO file, the ‘msgunfmt’ program
12584 can be used with the option ‘--csharp’.
12586 The advantages of the ‘.dll’ format over the ‘.resources’ format are:
12588 1. Freedom to localize: Users can add their own translations to an
12589 application after it has been built and distributed. Whereas when
12590 the programmer uses a ‘ResourceManager’ constructor provided by the
12591 system, the set of ‘.resources’ files for an application must be
12592 specified when the application is built and cannot be extended
12595 2. Plural handling: A message catalog in ‘.dll’ format supports the
12596 plural handling function ‘GetPluralString’. Whereas ‘.resources’
12597 files can only contain data and only support lookups that depend on
12600 3. Context handling: A message catalog in ‘.dll’ format supports the
12601 query-with-context functions ‘GetParticularString’ and
12602 ‘GetParticularPluralString’. Whereas ‘.resources’ files can only
12603 contain data and only support lookups that depend on a single
12606 4. The ‘GettextResourceManager’ that loads the message catalogs in
12607 ‘.dll’ format also provides for inheritance on a per-message basis.
12608 For example, in Austrian (‘de_AT’) locale, translations from the
12609 German (‘de’) message catalog will be used for messages not found
12610 in the Austrian message catalog. This has the consequence that the
12611 Austrian translators need only translate those few messages for
12612 which the translation into Austrian differs from the German one.
12613 Whereas when working with ‘.resources’ files, each message catalog
12614 must provide the translations of all messages by itself.
12616 5. The ‘GettextResourceManager’ that loads the message catalogs in
12617 ‘.dll’ format also provides for a fallback: The English MSGID is
12618 returned when no translation can be found. Whereas when working
12619 with ‘.resources’ files, a language-neutral ‘.resources’ file must
12620 explicitly be provided as a fallback.
12622 On the side of the programmatic APIs, the programmer can use either
12623 the standard ‘ResourceManager’ API and the GNU ‘GettextResourceManager’
12624 API. The latter is an extension of the former, because
12625 ‘GettextResourceManager’ is a subclass of ‘ResourceManager’.
12627 1. The ‘System.Resources.ResourceManager’ API.
12629 This API works with resources in ‘.resources’ format.
12631 The creation of the ‘ResourceManager’ is done through
12632 new ResourceManager(domainname, Assembly.GetExecutingAssembly())
12634 The ‘GetString’ function returns a string’s translation. Note that
12635 this function returns null when a translation is missing (i.e. not
12636 even found in the fallback resource file).
12638 2. The ‘GNU.Gettext.GettextResourceManager’ API.
12640 This API works with resources in ‘.dll’ format.
12642 Reference documentation is in the csharpdoc directory
12643 (csharpdoc/index.html).
12645 The creation of the ‘ResourceManager’ is done through
12646 new GettextResourceManager(domainname)
12648 The ‘GetString’ function returns a string’s translation. Note that
12649 when a translation is missing, the MSGID argument is returned
12652 The ‘GetPluralString’ function returns a string translation with
12653 plural handling, like the ‘ngettext’ function in C.
12655 The ‘GetParticularString’ function returns a string’s translation,
12656 specific to a particular context, like the ‘pgettext’ function in
12657 C. Note that when a translation is missing, the MSGID argument is
12658 returned unchanged.
12660 The ‘GetParticularPluralString’ function returns a string
12661 translation, specific to a particular context, with plural
12662 handling, like the ‘npgettext’ function in C.
12664 To use this API, one needs the ‘GNU.Gettext.dll’ file which is part
12665 of the GNU gettext package and distributed under the LGPL.
12667 You can also mix both approaches: use the
12668 ‘GNU.Gettext.GettextResourceManager’ constructor, but otherwise use only
12669 the ‘ResourceManager’ type and only the ‘GetString’ method. This is
12670 appropriate when you want to profit from the tools for PO files, but
12671 don’t want to change an existing source code that uses ‘ResourceManager’
12672 and don’t (yet) need the ‘GetPluralString’ method.
12674 Two examples, using the second API, are available in the ‘examples’
12675 directory: ‘hello-csharp’, ‘hello-csharp-forms’.
12677 Now, to make use of the API and define a shorthand for ‘GetString’,
12678 there are two idioms that you can choose from:
12680 • In a unique class of your project, say ‘Util’, define a static
12681 variable holding the ‘ResourceManager’ instance:
12683 public static GettextResourceManager MyResourceManager =
12684 new GettextResourceManager("domain-name");
12686 All classes containing internationalized strings then contain
12688 private static GettextResourceManager Res = Util.MyResourceManager;
12689 private static String _(String s) { return Res.GetString(s); }
12691 and the shorthand is used like this:
12693 Console.WriteLine(_("Operation completed."));
12695 • You add a class with a very short name, say ‘S’, containing just
12696 the definition of the resource manager and of the shorthand:
12699 public static GettextResourceManager MyResourceManager =
12700 new GettextResourceManager("domain-name");
12701 public static String _(String s) {
12702 return MyResourceManager.GetString(s);
12706 and the shorthand is used like this:
12708 Console.WriteLine(S._("Operation completed."));
12710 Which of the two idioms you choose, will depend on whether copying
12711 two lines of codes into every class is more acceptable in your project
12712 than a class with a single-letter name.
12715 File: gettext.info, Node: gawk, Next: Pascal, Prev: C#, Up: List of Programming Languages
12724 ‘awk’, ‘gawk’, ‘twjr’. The file extension ‘twjr’ is used by
12725 TexiWeb Jr (<https://github.com/arnoldrobbins/texiwebjr>).
12733 gettext/ngettext functions
12734 ‘dcgettext’, missing ‘dcngettext’ in gawk-3.1.0
12737 ‘TEXTDOMAIN’ variable
12740 ‘bindtextdomain’ function
12743 automatic, but missing ‘setlocale (LC_MESSAGES, "")’ in gawk-3.1.0
12748 Use or emulate GNU gettext
12754 Formatting with positions
12755 ‘printf "%2$d %1$d"’ (GNU awk only)
12758 On platforms without gettext, no translation. On non-GNU awks, you
12759 must define ‘dcgettext’, ‘dcngettext’ and ‘bindtextdomain’
12765 An example is available in the ‘examples’ directory: ‘hello-gawk’.
12768 File: gettext.info, Node: Pascal, Next: wxWidgets, Prev: gawk, Up: List of Programming Languages
12770 15.5.14 Pascal - Free Pascal Compiler
12771 -------------------------------------
12785 gettext/ngettext functions
12786 —, use ‘ResourceString’ data type instead
12789 —, use ‘TranslateResourceStrings’ function instead
12792 —, use ‘TranslateResourceStrings’ function instead
12795 automatic, but uses only LANG, not LC_MESSAGES or LC_ALL
12798 ‘{$mode delphi}’ or ‘{$mode objfpc}’
12801 Use or emulate GNU gettext
12805 ‘ppc386’ followed by ‘xgettext’ or ‘rstconv’
12807 Formatting with positions
12809 ‘format "%1:d %0:d"’
12817 The Pascal compiler has special support for the ‘ResourceString’ data
12818 type. It generates a ‘.rst’ file. This is then converted to a ‘.pot’
12819 file by use of ‘xgettext’ or ‘rstconv’. At runtime, a ‘.mo’ file
12820 corresponding to translations of this ‘.pot’ file can be loaded using
12821 the ‘TranslateResourceStrings’ function in the ‘gettext’ unit.
12823 An example is available in the ‘examples’ directory: ‘hello-pascal’.
12826 File: gettext.info, Node: wxWidgets, Next: YCP, Prev: Pascal, Up: List of Programming Languages
12828 15.5.15 wxWidgets library
12829 -------------------------
12843 gettext/ngettext functions
12844 ‘wxLocale::GetString’, ‘wxGetTranslation’
12847 ‘wxLocale::AddCatalog’
12850 ‘wxLocale::AddCatalogLookupPathPrefix’
12853 ‘wxLocale::Init’, ‘wxSetLocale’
12856 ‘#include <wx/intl.h>’
12858 Use or emulate GNU gettext
12859 emulate, see ‘include/wx/intl.h’ and ‘src/common/intl.cpp’
12864 Formatting with positions
12865 wxString::Format supports positions if and only if the system has
12866 ‘wprintf()’, ‘vswprintf()’ functions and they support positions
12867 according to POSIX.
12876 File: gettext.info, Node: YCP, Next: Tcl, Prev: wxWidgets, Up: List of Programming Languages
12878 15.5.16 YCP - YaST2 scripting language
12879 --------------------------------------
12882 libycp, libycp-devel, yast2-core, yast2-core-devel
12893 gettext/ngettext functions
12894 ‘_()’ with 1 or 3 arguments
12897 ‘textdomain’ statement
12908 Use or emulate GNU gettext
12914 Formatting with positions
12923 An example is available in the ‘examples’ directory: ‘hello-ycp’.
12926 File: gettext.info, Node: Tcl, Next: Perl, Prev: YCP, Up: List of Programming Languages
12928 15.5.17 Tcl - Tk’s scripting language
12929 -------------------------------------
12943 gettext/ngettext functions
12950 —, use ‘::msgcat::mcload’ instead
12953 automatic, uses LANG, but ignores LC_MESSAGES and LC_ALL
12956 ‘package require msgcat’
12957 ‘proc _ {s} {return [::msgcat::mc $s]}’
12959 Use or emulate GNU gettext
12960 —, uses a Tcl specific message catalog format
12965 Formatting with positions
12966 ‘format "%2\$d %1\$d"’
12974 Two examples are available in the ‘examples’ directory: ‘hello-tcl’,
12977 Before marking strings as internationalizable, substitutions of
12978 variables into the string need to be converted to ‘format’ applications.
12979 For example, ‘"file $filename not found"’ becomes ‘[format "file %s not
12980 found" $filename]’. Only after this is done, can the strings be marked
12981 and extracted. After marking, this example becomes ‘[format [_ "file %s
12982 not found"] $filename]’ or ‘[msgcat::mc "file %s not found" $filename]’.
12983 Note that the ‘msgcat::mc’ function implicitly calls ‘format’ when more
12984 than one argument is given.
12987 File: gettext.info, Node: Perl, Next: PHP, Prev: Tcl, Up: List of Programming Languages
12996 ‘pl’, ‘PL’, ‘pm’, ‘perl’, ‘cgi’
13012 • ‘/pattern match/’
13014 • ‘?pattern match?’
13016 • ‘s/substitution/operators/’
13018 • ‘$tied_hash{"message"}’
13020 • ‘$tied_hash_reference->{"message"}’
13022 • etc., issue the command ‘man perlsyn’ for details
13025 ‘__’ (double underscore)
13027 gettext/ngettext functions
13028 ‘gettext’, ‘dgettext’, ‘dcgettext’, ‘ngettext’, ‘dngettext’,
13032 ‘textdomain’ function
13035 ‘bindtextdomain’ function
13037 bind_textdomain_codeset
13038 ‘bind_textdomain_codeset’ function
13041 Use ‘setlocale (LC_ALL, "");’
13045 ‘use Locale::TextDomain;’ (included in the package libintl-perl
13046 which is available on the Comprehensive Perl Archive Network CPAN,
13047 http://www.cpan.org/).
13049 Use or emulate GNU gettext
13050 platform dependent: gettext_pp emulates, gettext_xs uses GNU
13054 ‘xgettext -k__ -k\$__ -k%__ -k__x -k__n:1,2 -k__nx:1,2 -k__xn:1,2
13057 Formatting with positions
13058 Both kinds of format strings support formatting with positions.
13059 ‘printf "%2\$d %1\$d", ...’ (requires Perl 5.8.0 or newer)
13060 ‘__expand("[new] replaces [old]", old => $oldvalue, new =>
13064 The ‘libintl-perl’ package is platform independent but is not part
13065 of the Perl core. The programmer is responsible for providing a
13066 dummy implementation of the required functions if the package is
13067 not installed on the target system.
13073 Included in ‘libintl-perl’, available on CPAN
13074 (http://www.cpan.org/).
13076 An example is available in the ‘examples’ directory: ‘hello-perl’.
13078 The ‘xgettext’ parser backend for Perl differs significantly from the
13079 parser backends for other programming languages, just as Perl itself
13080 differs significantly from other programming languages. The Perl parser
13081 backend offers many more string marking facilities than the other
13082 backends but it also has some Perl specific limitations, the worst
13083 probably being its imperfectness.
13087 * General Problems:: General Problems Parsing Perl Code
13088 * Default Keywords:: Which Keywords Will xgettext Look For?
13089 * Special Keywords:: How to Extract Hash Keys
13090 * Quote-like Expressions:: What are Strings And Quote-like Expressions?
13091 * Interpolation I:: Invalid String Interpolation
13092 * Interpolation II:: Valid String Interpolation
13093 * Parentheses:: When To Use Parentheses
13094 * Long Lines:: How To Grok with Long Lines
13095 * Perl Pitfalls:: Bugs, Pitfalls, and Things That Do Not Work
13098 File: gettext.info, Node: General Problems, Next: Default Keywords, Prev: Perl, Up: Perl
13100 15.5.18.1 General Problems Parsing Perl Code
13101 ............................................
13103 It is often heard that only Perl can parse Perl. This is not true.
13104 Perl cannot be _parsed_ at all, it can only be _executed_. Perl has
13105 various built-in ambiguities that can only be resolved at runtime.
13107 The following example may illustrate one common problem:
13109 print gettext "Hello World!";
13111 Although this example looks like a bullet-proof case of a function
13112 invocation, it is not:
13114 open gettext, ">testfile" or die;
13115 print gettext "Hello world!"
13117 In this context, the string ‘gettext’ looks more like a file handle.
13118 But not necessarily:
13120 use Locale::Messages qw (:libintl_h);
13121 open gettext ">testfile" or die;
13122 print gettext "Hello world!";
13124 Now, the file is probably syntactically incorrect, provided that the
13125 module ‘Locale::Messages’ found first in the Perl include path exports a
13126 function ‘gettext’. But what if the module ‘Locale::Messages’ really
13129 use vars qw (*gettext);
13133 In this case, the string ‘gettext’ will be interpreted as a file
13134 handle again, and the above example will create a file ‘testfile’ and
13135 write the string “Hello world!” into it. Even advanced control flow
13136 analysis will not really help:
13143 print gettext "Hello world!";
13145 If the module ‘Sane’ exports a function ‘gettext’ that does what we
13146 expect, and the module ‘InSane’ opens a file for writing and associates
13147 the _handle_ ‘gettext’ with this output stream, we are clueless again
13148 about what will happen at runtime. It is completely unpredictable. The
13149 truth is that Perl has so many ways to fill its symbol table at runtime
13150 that it is impossible to interpret a particular piece of code without
13153 Of course, ‘xgettext’ will not execute your Perl sources while
13154 scanning for translatable strings, but rather use heuristics in order to
13155 guess what you meant.
13157 Another problem is the ambiguity of the slash and the question mark.
13158 Their interpretation depends on the context:
13161 print "OK\n" if /foobar/;
13166 # Another pattern match.
13167 print "OK\n" if ?foobar?;
13170 print $x ? "foo" : "bar";
13172 The slash may either act as the division operator or introduce a
13173 pattern match, whereas the question mark may act as the ternary
13174 conditional operator or as a pattern match, too. Other programming
13175 languages like ‘awk’ present similar problems, but the consequences of a
13176 misinterpretation are particularly nasty with Perl sources. In ‘awk’
13177 for instance, a statement can never exceed one line and the parser can
13178 recover from a parsing error at the next newline and interpret the rest
13179 of the input stream correctly. Perl is different, as a pattern match is
13180 terminated by the next appearance of the delimiter (the slash or the
13181 question mark) in the input stream, regardless of the semantic context.
13182 If a slash is really a division sign but mis-interpreted as a pattern
13183 match, the rest of the input file is most probably parsed incorrectly.
13185 There are certain cases, where the ambiguity cannot be resolved at
13188 $x = wantarray ? 1 : 0;
13190 The Perl built-in function ‘wantarray’ does not accept any arguments.
13191 The Perl parser therefore knows that the question mark does not start a
13192 regular expression but is the ternary conditional operator.
13195 $x = wantarrays ? 1 : 0;
13197 Now the situation is different. The function ‘wantarrays’ takes a
13198 variable number of arguments (like any non-prototyped Perl function).
13199 The question mark is now the delimiter of a pattern match, and hence the
13200 piece of code does not compile.
13202 sub wantarrays() {}
13203 $x = wantarrays ? 1 : 0;
13205 Now the function is prototyped, Perl knows that it does not accept
13206 any arguments, and the question mark is therefore interpreted as the
13207 ternaray operator again. But that unfortunately outsmarts ‘xgettext’.
13209 The Perl parser in ‘xgettext’ cannot know whether a function has a
13210 prototype and what that prototype would look like. It therefore makes
13211 an educated guess. If a function is known to be a Perl built-in and
13212 this function does not accept any arguments, a following question mark
13213 or slash is treated as an operator, otherwise as the delimiter of a
13214 following regular expression. The Perl built-ins that do not accept
13215 arguments are ‘wantarray’, ‘fork’, ‘time’, ‘times’, ‘getlogin’,
13216 ‘getppid’, ‘getpwent’, ‘getgrent’, ‘gethostent’, ‘getnetent’,
13217 ‘getprotoent’, ‘getservent’, ‘setpwent’, ‘setgrent’, ‘endpwent’,
13218 ‘endgrent’, ‘endhostent’, ‘endnetent’, ‘endprotoent’, and ‘endservent’.
13220 If you find that ‘xgettext’ fails to extract strings from portions of
13221 your sources, you should therefore look out for slashes and/or question
13222 marks preceding these sections. You may have come across a bug in
13223 ‘xgettext’’s Perl parser (and of course you should report that bug). In
13224 the meantime you should consider to reformulate your code in a manner
13225 less challenging to ‘xgettext’.
13227 In particular, if the parser is too dumb to see that a function does
13228 not accept arguments, use parentheses:
13230 $x = somefunc() ? 1 : 0;
13231 $y = (somefunc) ? 1 : 0;
13233 In fact the Perl parser itself has similar problems and warns you
13234 about such constructs.
13237 File: gettext.info, Node: Default Keywords, Next: Special Keywords, Prev: General Problems, Up: Perl
13239 15.5.18.2 Which keywords will xgettext look for?
13240 ................................................
13242 Unless you instruct ‘xgettext’ otherwise by invoking it with one of
13243 the options ‘--keyword’ or ‘-k’, it will recognize the following
13244 keywords in your Perl sources:
13254 The first (singular) and the second (plural) argument will be
13259 The first (singular) and the second (plural) argument will be
13264 The first (singular) and the second (plural) argument will be
13271 The keys of lookups into the hash ‘%gettext’ will be extracted.
13275 The keys of lookups into the hash reference ‘$gettext’ will be
13279 File: gettext.info, Node: Special Keywords, Next: Quote-like Expressions, Prev: Default Keywords, Up: Perl
13281 15.5.18.3 How to Extract Hash Keys
13282 ..................................
13284 Translating messages at runtime is normally performed by looking up
13285 the original string in the translation database and returning the
13286 translated version. The “natural” Perl implementation is a hash lookup,
13287 and, of course, ‘xgettext’ supports such practice.
13289 print __"Hello world!";
13290 print $__{"Hello world!"};
13291 print $__->{"Hello world!"};
13292 print $$__{"Hello world!"};
13294 The above four lines all do the same thing. The Perl module
13295 ‘Locale::TextDomain’ exports by default a hash ‘%__’ that is tied to the
13296 function ‘__()’. It also exports a reference ‘$__’ to ‘%__’.
13298 If an argument to the ‘xgettext’ option ‘--keyword’, resp. ‘-k’
13299 starts with a percent sign, the rest of the keyword is interpreted as
13300 the name of a hash. If it starts with a dollar sign, the rest of the
13301 keyword is interpreted as a reference to a hash.
13303 Note that you can omit the quotation marks (single or double) around
13304 the hash key (almost) whenever Perl itself allows it:
13306 print $gettext{Error};
13308 The exact rule is: You can omit the surrounding quotes, when the hash
13309 key is a valid C (!) identifier, i.e. when it starts with an underscore
13310 or an ASCII letter and is followed by an arbitrary number of
13311 underscores, ASCII letters or digits. Other Unicode characters are
13312 _not_ allowed, regardless of the ‘use utf8’ pragma.
13315 File: gettext.info, Node: Quote-like Expressions, Next: Interpolation I, Prev: Special Keywords, Up: Perl
13317 15.5.18.4 What are Strings And Quote-like Expressions?
13318 ......................................................
13320 Perl offers a plethora of different string constructs. Those that
13321 can be used either as arguments to functions or inside braces for hash
13322 lookups are generally supported by ‘xgettext’.
13324 • *double-quoted strings*
13325 print gettext "Hello World!";
13327 • *single-quoted strings*
13328 print gettext 'Hello World!';
13330 • *the operator qq*
13331 print gettext qq |Hello World!|;
13332 print gettext qq <E-mail: <guido\@imperia.net>>;
13334 The operator ‘qq’ is fully supported. You can use arbitrary
13335 delimiters, including the four bracketing delimiters (round, angle,
13336 square, curly) that nest.
13339 print gettext q |Hello World!|;
13340 print gettext q <E-mail: <guido@imperia.net>>;
13342 The operator ‘q’ is fully supported. You can use arbitrary
13343 delimiters, including the four bracketing delimiters (round, angle,
13344 square, curly) that nest.
13346 • *the operator qx*
13347 print gettext qx ;LANGUAGE=C /bin/date;
13348 print gettext qx [/usr/bin/ls | grep '^[A-Z]*'];
13350 The operator ‘qx’ is fully supported. You can use arbitrary
13351 delimiters, including the four bracketing delimiters (round, angle,
13352 square, curly) that nest.
13354 The example is actually a useless use of ‘gettext’. It will invoke
13355 the ‘gettext’ function on the output of the command specified with
13356 the ‘qx’ operator. The feature was included in order to make the
13357 interface consistent (the parser will extract all strings and
13358 quote-like expressions).
13361 print gettext <<'EOF';
13362 program not found in $PATH
13365 print ngettext <<EOF, <<"EOF";
13368 several files deleted
13371 Here-documents are recognized. If the delimiter is enclosed in
13372 single quotes, the string is not interpolated. If it is enclosed
13373 in double quotes or has no quotes at all, the string is
13376 Delimiters that start with a digit are not supported!
13379 File: gettext.info, Node: Interpolation I, Next: Interpolation II, Prev: Quote-like Expressions, Up: Perl
13381 15.5.18.5 Invalid Uses Of String Interpolation
13382 ..............................................
13384 Perl is capable of interpolating variables into strings. This offers
13385 some nice features in localized programs but can also lead to problems.
13387 A common error is a construct like the following:
13389 print gettext "This is the program $0!\n";
13391 Perl will interpolate at runtime the value of the variable ‘$0’ into
13392 the argument of the ‘gettext()’ function. Hence, this argument is not a
13393 string constant but a variable argument (‘$0’ is a global variable that
13394 holds the name of the Perl script being executed). The interpolation is
13395 performed by Perl before the string argument is passed to ‘gettext()’
13396 and will therefore depend on the name of the script which can only be
13397 determined at runtime. Consequently, it is almost impossible that a
13398 translation can be looked up at runtime (except if, by accident, the
13399 interpolated string is found in the message catalog).
13401 The ‘xgettext’ program will therefore terminate parsing with a fatal
13402 error if it encounters a variable inside of an extracted string. In
13403 general, this will happen for all kinds of string interpolations that
13404 cannot be safely performed at compile time. If you absolutely know what
13405 you are doing, you can always circumvent this behavior:
13407 my $know_what_i_am_doing = "This is program $0!\n";
13408 print gettext $know_what_i_am_doing;
13410 Since the parser only recognizes strings and quote-like expressions,
13411 but not variables or other terms, the above construct will be accepted.
13412 You will have to find another way, however, to let your original string
13413 make it into your message catalog.
13415 If invoked with the option ‘--extract-all’, resp. ‘-a’, variable
13416 interpolation will be accepted. Rationale: You will generally use this
13417 option in order to prepare your sources for internationalization.
13419 Please see the manual page ‘man perlop’ for details of strings and
13420 quote-like expressions that are subject to interpolation and those that
13421 are not. Safe interpolations (that will not lead to a fatal error) are:
13423 • the escape sequences ‘\t’ (tab, HT, TAB), ‘\n’ (newline, NL), ‘\r’
13424 (return, CR), ‘\f’ (form feed, FF), ‘\b’ (backspace, BS), ‘\a’
13425 (alarm, bell, BEL), and ‘\e’ (escape, ESC).
13427 • octal chars, like ‘\033’
13428 Note that octal escapes in the range of 400-777 are translated into
13429 a UTF-8 representation, regardless of the presence of the ‘use
13432 • hex chars, like ‘\x1b’
13434 • wide hex chars, like ‘\x{263a}’
13435 Note that this escape is translated into a UTF-8 representation,
13436 regardless of the presence of the ‘use utf8’ pragma.
13438 • control chars, like ‘\c[’ (CTRL-[)
13440 • named Unicode chars, like ‘\N{LATIN CAPITAL LETTER C WITH CEDILLA}’
13442 Note that this escape is translated into a UTF-8 representation,
13443 regardless of the presence of the ‘use utf8’ pragma.
13445 The following escapes are considered partially safe:
13447 • ‘\l’ lowercase next char
13449 • ‘\u’ uppercase next char
13451 • ‘\L’ lowercase till \E
13453 • ‘\U’ uppercase till \E
13455 • ‘\E’ end case modification
13457 • ‘\Q’ quote non-word characters till \E
13459 These escapes are only considered safe if the string consists of
13460 ASCII characters only. Translation of characters outside the range
13461 defined by ASCII is locale-dependent and can actually only be performed
13462 at runtime; ‘xgettext’ doesn’t do these locale-dependent translations at
13465 Except for the modifier ‘\Q’, these translations, albeit valid, are
13466 generally useless and only obfuscate your sources. If a translation can
13467 be safely performed at compile time you can just as well write what you
13471 File: gettext.info, Node: Interpolation II, Next: Parentheses, Prev: Interpolation I, Up: Perl
13473 15.5.18.6 Valid Uses Of String Interpolation
13474 ............................................
13476 Perl is often used to generate sources for other programming
13477 languages or arbitrary file formats. Web applications that output HTML
13478 code make a prominent example for such usage.
13480 You will often come across situations where you want to intersperse
13481 code written in the target (programming) language with translatable
13482 messages, like in the following HTML example:
13484 print gettext <<EOF;
13485 <h1>My Homepage</h1>
13486 <script language="JavaScript"><!--
13487 for (i = 0; i < 100; ++i) {
13488 alert ("Thank you so much for visiting my homepage!");
13493 The parser will extract the entire here document, and it will appear
13494 entirely in the resulting PO file, including the JavaScript snippet
13495 embedded in the HTML code. If you exaggerate with constructs like the
13496 above, you will run the risk that the translators of your package will
13497 look out for a less challenging project. You should consider an
13498 alternative expression here:
13501 <h1>$gettext{"My Homepage"}</h1>
13502 <script language="JavaScript"><!--
13503 for (i = 0; i < 100; ++i) {
13504 alert ("$gettext{'Thank you so much for visiting my homepage!'}");
13509 Only the translatable portions of the code will be extracted here,
13510 and the resulting PO file will begrudgingly improve in terms of
13513 You can interpolate hash lookups in all strings or quote-like
13514 expressions that are subject to interpolation (see the manual page ‘man
13515 perlop’ for details). Double interpolation is invalid, however:
13517 # TRANSLATORS: Replace "the earth" with the name of your planet.
13518 print gettext qq{Welcome to $gettext->{"the earth"}};
13520 The ‘qq’-quoted string is recognized as an argument to ‘xgettext’ in
13521 the first place, and checked for invalid variable interpolation. The
13522 dollar sign of hash-dereferencing will therefore terminate the parser
13523 with an “invalid interpolation” error.
13525 It is valid to interpolate hash lookups in regular expressions:
13527 if ($var =~ /$gettext{"the earth"}/) {
13528 print gettext "Match!\n";
13530 s/$gettext{"U. S. A."}/$gettext{"U. S. A."} $gettext{"(dial +0)"}/g;
13533 File: gettext.info, Node: Parentheses, Next: Long Lines, Prev: Interpolation II, Up: Perl
13535 15.5.18.7 When To Use Parentheses
13536 .................................
13538 In Perl, parentheses around function arguments are mostly optional.
13539 ‘xgettext’ will always assume that all recognized keywords (except for
13540 hashes and hash references) are names of properly prototyped functions,
13541 and will (hopefully) only require parentheses where Perl itself requires
13542 them. All constructs in the following example are therefore ok to use:
13544 print gettext ("Hello World!\n");
13545 print gettext "Hello World!\n";
13546 print dgettext ($package => "Hello World!\n");
13547 print dgettext $package, "Hello World!\n";
13549 # The "fat comma" => turns the left-hand side argument into a
13550 # single-quoted string!
13551 print dgettext smellovision => "Hello World!\n";
13553 # The following assignment only works with prototyped functions.
13554 # Otherwise, the functions will act as "greedy" list operators and
13555 # eat up all following arguments.
13556 my $anonymous_hash = {
13557 planet => gettext "earth",
13558 cakes => ngettext "one cake", "several cakes", $n,
13561 # The same without fat comma:
13563 'planet', gettext "earth",
13564 'cakes', ngettext "one cake", "several cakes", $n,
13568 # Parentheses are only significant for the first argument.
13569 print dngettext 'package', ("one cake", "several cakes", $n), $discarded;
13572 File: gettext.info, Node: Long Lines, Next: Perl Pitfalls, Prev: Parentheses, Up: Perl
13574 15.5.18.8 How To Grok with Long Lines
13575 .....................................
13577 The necessity of long messages can often lead to a cumbersome or
13578 unreadable coding style. Perl has several options that may prevent you
13579 from writing unreadable code, and ‘xgettext’ does its best to do
13580 likewise. This is where the dot operator (the string concatenation
13581 operator) may come in handy:
13583 print gettext ("This is a very long"
13584 . " message that is still"
13585 . " readable, because"
13586 . " it is split into"
13587 . " multiple lines.\n");
13589 Perl is smart enough to concatenate these constant string fragments
13590 into one long string at compile time, and so is ‘xgettext’. You will
13591 only find one long message in the resulting POT file.
13593 Note that the future Perl 6 will probably use the underscore (‘_’) as
13594 the string concatenation operator, and the dot (‘.’) for dereferencing.
13595 This new syntax is not yet supported by ‘xgettext’.
13597 If embedded newline characters are not an issue, or even desired, you
13598 may also insert newline characters inside quoted strings wherever you
13601 print gettext ("<em>In HTML output
13602 embedded newlines are generally no
13603 problem, since adjacent whitespace
13604 is always rendered into a single
13605 space character.</em>");
13607 You may also consider to use here documents:
13609 print gettext <<EOF;
13611 embedded newlines are generally no
13612 problem, since adjacent whitespace
13613 is always rendered into a single
13614 space character.</em>
13617 Please do not forget that the line breaks are real, i.e. they
13618 translate into newline characters that will consequently show up in the
13619 resulting POT file.
13622 File: gettext.info, Node: Perl Pitfalls, Prev: Long Lines, Up: Perl
13624 15.5.18.9 Bugs, Pitfalls, And Things That Do Not Work
13625 .....................................................
13627 The foregoing sections should have proven that ‘xgettext’ is quite
13628 smart in extracting translatable strings from Perl sources. Yet, some
13629 more or less exotic constructs that could be expected to work, actually
13632 One of the more relevant limitations can be found in the
13633 implementation of variable interpolation inside quoted strings. Only
13634 simple hash lookups can be used there:
13637 $gettext{"The dot operator"
13640 Likewise, you cannot @{[ gettext ("interpolate function calls") ]}
13641 inside quoted strings or quote-like expressions.
13644 This is valid Perl code and will actually trigger invocations of the
13645 ‘gettext’ function at runtime. Yet, the Perl parser in ‘xgettext’ will
13646 fail to recognize the strings. A less obvious example can be found in
13647 the interpolation of regular expressions:
13649 s/<!--START_OF_WEEK-->/gettext ("Sunday")/e;
13651 The modifier ‘e’ will cause the substitution to be interpreted as an
13652 evaluable statement. Consequently, at runtime the function ‘gettext()’
13653 is called, but again, the parser fails to extract the string “Sunday”.
13654 Use a temporary variable as a simple workaround if you really happen to
13657 my $sunday = gettext "Sunday";
13658 s/<!--START_OF_WEEK-->/$sunday/;
13660 Hash slices would also be handy but are not recognized:
13662 my @weekdays = @gettext{'Sunday', 'Monday', 'Tuesday', 'Wednesday',
13663 'Thursday', 'Friday', 'Saturday'};
13665 @weekdays = @gettext{qw (Sunday Monday Tuesday Wednesday Thursday
13666 Friday Saturday) };
13668 This is perfectly valid usage of the tied hash ‘%gettext’ but the
13669 strings are not recognized and therefore will not be extracted.
13671 Another caveat of the current version is its rudimentary support for
13672 non-ASCII characters in identifiers. You may encounter serious problems
13673 if you use identifiers with characters outside the range of ’A’-’Z’,
13674 ’a’-’z’, ’0’-’9’ and the underscore ’_’.
13676 Maybe some of these missing features will be implemented in future
13677 versions, but since you can always make do without them at minimal
13678 effort, these todos have very low priority.
13680 A nasty problem are brace format strings that already contain braces
13681 as part of the normal text, for example the usage strings typically
13682 encountered in programs:
13684 die "usage: $0 {OPTIONS} FILENAME...\n";
13686 If you want to internationalize this code with Perl brace format
13687 strings, you will run into a problem:
13689 die __x ("usage: {program} {OPTIONS} FILENAME...\n", program => $0);
13691 Whereas ‘{program}’ is a placeholder, ‘{OPTIONS}’ is not and should
13692 probably be translated. Yet, there is no way to teach the Perl parser
13693 in ‘xgettext’ to recognize the first one, and leave the other one alone.
13695 There are two possible work-arounds for this problem. If you are
13696 sure that your program will run under Perl 5.8.0 or newer (these Perl
13697 versions handle positional parameters in ‘printf()’) or if you are sure
13698 that the translator will not have to reorder the arguments in her
13699 translation – for example if you have only one brace placeholder in your
13700 string, or if it describes a syntax, like in this one –, you can mark
13701 the string as ‘no-perl-brace-format’ and use ‘printf()’:
13703 # xgettext: no-perl-brace-format
13704 die sprintf ("usage: %s {OPTIONS} FILENAME...\n", $0);
13706 If you want to use the more portable Perl brace format, you will have
13707 to do put placeholders in place of the literal braces:
13709 die __x ("usage: {program} {[}OPTIONS{]} FILENAME...\n",
13710 program => $0, '[' => '{', ']' => '}');
13712 Perl brace format strings know no escaping mechanism. No matter how
13713 this escaping mechanism looked like, it would either give the programmer
13714 a hard time, make translating Perl brace format strings heavy-going, or
13715 result in a performance penalty at runtime, when the format directives
13716 get executed. Most of the time you will happily get along with
13717 ‘printf()’ for this special case.
13720 File: gettext.info, Node: PHP, Next: Pike, Prev: Perl, Up: List of Programming Languages
13722 15.5.19 PHP Hypertext Preprocessor
13723 ----------------------------------
13726 mod_php4, mod_php4-core, phpdoc
13729 ‘php’, ‘php3’, ‘php4’
13737 gettext/ngettext functions
13738 ‘gettext’, ‘dgettext’, ‘dcgettext’; starting with PHP 4.2.0 also
13739 ‘ngettext’, ‘dngettext’, ‘dcngettext’
13742 ‘textdomain’ function
13745 ‘bindtextdomain’ function
13748 Programmer must call ‘setlocale (LC_ALL, "")’
13753 Use or emulate GNU gettext
13759 Formatting with positions
13760 ‘printf "%2\$d %1\$d"’
13763 On platforms without gettext, the functions are not available.
13768 An example is available in the ‘examples’ directory: ‘hello-php’.
13771 File: gettext.info, Node: Pike, Next: GCC-source, Prev: PHP, Up: List of Programming Languages
13788 gettext/ngettext functions
13789 ‘gettext’, ‘dgettext’, ‘dcgettext’
13792 ‘textdomain’ function
13795 ‘bindtextdomain’ function
13798 ‘setlocale’ function
13801 ‘import Locale.Gettext;’
13803 Use or emulate GNU gettext
13809 Formatting with positions
13813 On platforms without gettext, the functions are not available.
13819 File: gettext.info, Node: GCC-source, Next: Lua, Prev: Pike, Up: List of Programming Languages
13821 15.5.21 GNU Compiler Collection sources
13822 ---------------------------------------
13836 gettext/ngettext functions
13837 ‘gettext’, ‘dgettext’, ‘dcgettext’, ‘ngettext’, ‘dngettext’,
13841 ‘textdomain’ function
13844 ‘bindtextdomain’ function
13847 Programmer must call ‘setlocale (LC_ALL, "")’
13850 ‘#include "intl.h"’
13852 Use or emulate GNU gettext
13858 Formatting with positions
13862 Uses autoconf macros
13868 File: gettext.info, Node: Lua, Next: JavaScript, Prev: GCC-source, Up: List of Programming Languages
13896 gettext/ngettext functions
13897 ‘gettext.gettext’, ‘gettext.dgettext’, ‘gettext.dcgettext’,
13898 ‘gettext.ngettext’, ‘gettext.dngettext’, ‘gettext.dcngettext’
13901 ‘textdomain’ function
13904 ‘bindtextdomain’ function
13910 ‘require 'gettext'’ or running lua interpreter with ‘-l gettext’
13913 Use or emulate GNU gettext
13919 Formatting with positions
13923 On platforms without gettext, the functions are not available.
13929 File: gettext.info, Node: JavaScript, Next: Vala, Prev: Lua, Up: List of Programming Languages
13949 gettext/ngettext functions
13950 ‘gettext’, ‘dgettext’, ‘dcgettext’, ‘ngettext’, ‘dngettext’
13953 ‘textdomain’ function
13956 ‘bindtextdomain’ function
13964 Use or emulate GNU gettext
13970 Formatting with positions
13974 On platforms without gettext, the functions are not available.
13980 File: gettext.info, Node: Vala, Prev: JavaScript, Up: List of Programming Languages
14000 gettext/ngettext functions
14001 ‘gettext’, ‘dgettext’, ‘dcgettext’, ‘ngettext’, ‘dngettext’,
14002 ‘dpgettext’, ‘dpgettext2’
14005 ‘textdomain’ function, defined under the ‘Intl’ namespace
14008 ‘bindtextdomain’ function, defined under the ‘Intl’ namespace
14011 Programmer must call ‘Intl.setlocale (LocaleCategory.ALL, "")’
14016 Use or emulate GNU gettext
14022 Formatting with positions
14023 Same as for the C language.
14026 autoconf (gettext.m4) and #if ENABLE_NLS
14032 File: gettext.info, Node: List of Data Formats, Prev: List of Programming Languages, Up: Programming Languages
14034 15.6 Internationalizable Data
14035 =============================
14037 Here is a list of other data formats which can be internationalized
14042 * POT:: POT - Portable Object Template
14043 * RST:: Resource String Table
14044 * Glade:: Glade - GNOME user interface description
14045 * GSettings:: GSettings - GNOME user configuration schema
14046 * AppData:: AppData - freedesktop.org application description
14047 * Preparing ITS Rules:: Preparing Rules for XML Internationalization
14050 File: gettext.info, Node: POT, Next: RST, Prev: List of Data Formats, Up: List of Data Formats
14052 15.6.1 POT - Portable Object Template
14053 -------------------------------------
14065 File: gettext.info, Node: RST, Next: Glade, Prev: POT, Up: List of Data Formats
14067 15.6.2 Resource String Table
14068 ----------------------------
14077 ‘xgettext’, ‘rstconv’
14080 File: gettext.info, Node: Glade, Next: GSettings, Prev: RST, Up: List of Data Formats
14082 15.6.3 Glade - GNOME user interface description
14083 -----------------------------------------------
14086 glade, libglade, glade2, libglade2, intltool
14089 ‘glade’, ‘glade2’, ‘ui’
14092 ‘xgettext’, ‘libglade-xgettext’, ‘xml-i18n-extract’,
14096 File: gettext.info, Node: GSettings, Next: AppData, Prev: Glade, Up: List of Data Formats
14098 15.6.4 GSettings - GNOME user configuration schema
14099 --------------------------------------------------
14108 ‘xgettext’, ‘intltool-extract’
14111 File: gettext.info, Node: AppData, Next: Preparing ITS Rules, Prev: GSettings, Up: List of Data Formats
14113 15.6.5 AppData - freedesktop.org application description
14114 --------------------------------------------------------
14117 appdata-tools, appstream, libappstream-glib,
14118 libappstream-glib-builder
14124 ‘xgettext’, ‘intltool-extract’, ‘itstool’
14129 File: gettext.info, Node: Preparing ITS Rules, Prev: AppData, Up: List of Data Formats
14131 15.6.6 Preparing Rules for XML Internationalization
14132 ---------------------------------------------------
14134 Marking translatable strings in an XML file is done through a
14135 separate "rule" file, making use of the Internationalization Tag Set
14136 standard (ITS, <http://www.w3.org/TR/its20/>). The currently supported
14137 ITS data categories are: ‘Translate’, ‘Localization Note’, ‘Elements
14138 Within Text’, and ‘Preserve Space’. In addition to them, ‘xgettext’
14139 also recognizes the following extended data categories:
14143 This data category associates ‘msgctxt’ to the extracted text. In
14144 the global rule, the ‘contextRule’ element contains the following:
14146 • A required ‘selector’ attribute. It contains an absolute
14147 selector that selects the nodes to which this rule applies.
14149 • A required ‘contextPointer’ attribute that contains a relative
14150 selector pointing to a node that holds the ‘msgctxt’ value.
14152 • An optional ‘textPointer’ attribute that contains a relative
14153 selector pointing to a node that holds the ‘msgid’ value.
14155 ‘Escape Special Characters’
14157 This data category indicates whether the special XML characters
14158 (‘<’, ‘>’, ‘&’, ‘"’) are escaped with entity reference. In the
14159 global rule, the ‘escapeRule’ element contains the following:
14161 • A required ‘selector’ attribute. It contains an absolute
14162 selector that selects the nodes to which this rule applies.
14164 • A required ‘escape’ attribute with the value ‘yes’ or ‘no’.
14166 ‘Extended Preserve Space’
14168 This data category extends the standard ‘Preserve Space’ data
14169 category with the additional value ‘trim’. The value means to
14170 remove the leading and trailing whitespaces of the content, but not
14171 to normalize whitespaces in the middle. In the global rule, the
14172 ‘preserveSpaceRule’ element contains the following:
14174 • A required ‘selector’ attribute. It contains an absolute
14175 selector that selects the nodes to which this rule applies.
14177 • A required ‘space’ attribute with the value ‘default’,
14178 ‘preserve’, or ‘trim’.
14180 All those extended data categories can only be expressed with global
14181 rules, and the rule elements have to have the
14182 ‘https://www.gnu.org/s/gettext/ns/its/extensions/1.0’ namespace.
14184 Given the following XML document in a file ‘messages.xml’:
14186 <?xml version="1.0"?>
14189 <p>A translatable string</p>
14192 <p translatable="no">A non-translatable string</p>
14196 To extract the first text content ("A translatable string"), but not
14197 the second ("A non-translatable string"), the following ITS rules can be
14200 <?xml version="1.0"?>
14201 <its:rules xmlns:its="http://www.w3.org/2005/11/its" version="1.0">
14202 <its:translateRule selector="/messages" translate="no"/>
14203 <its:translateRule selector="//message/p" translate="yes"/>
14205 <!-- If 'p' has an attribute 'translatable' with the value 'no', then
14206 the content is not translatable. -->
14207 <its:translateRule selector="//message/p[@translatable = 'no']"
14211 ‘xgettext’ needs another file called "locating rule" to associate an
14212 ITS rule with an XML file. If the above ITS file is saved as
14213 ‘messages.its’, the locating rule would look like:
14215 <?xml version="1.0"?>
14217 <locatingRule name="Messages" pattern="*.xml">
14218 <documentRule localName="messages" target="messages.its"/>
14220 <locatingRule name="Messages" pattern="*.msg" target="messages.its"/>
14223 The ‘locatingRule’ element must have a ‘pattern’ attribute, which
14224 denotes either a literal file name or a wildcard pattern of the XML
14225 file. The ‘locatingRule’ element can have child ‘documentRule’ element,
14226 which adds checks on the content of the XML file.
14228 The first rule matches any file with the ‘.xml’ file extension, but
14229 it only applies to XML files whose root element is ‘<messages>’.
14231 The second rule indicates that the same ITS rule file are also
14232 applicable to any file with the ‘.msg’ file extension. The optional
14233 ‘name’ attribute of ‘locatingRule’ allows to choose rules by name,
14234 typically with ‘xgettext’’s ‘-L’ option.
14236 The associated ITS rule file is indicated by the ‘target’ attribute
14237 of ‘locatingRule’ or ‘documentRule’. If it is specified in a
14238 ‘documentRule’ element, the parent ‘locatingRule’ shouldn’t have the
14239 ‘target’ attribute.
14241 Locating rule files must have the ‘.loc’ file extension. Both ITS
14242 rule files and locating rule files must be installed in the
14243 ‘$prefix/share/gettext/its’ directory. Once those files are properly
14244 installed, ‘xgettext’ can extract translatable strings from the matching
14247 15.6.6.1 Two Use-cases of Translated Strings in XML
14248 ...................................................
14250 For XML, there are two use-cases of translated strings. One is the
14251 case where the translated strings are directly consumed by programs, and
14252 the other is the case where the translated strings are merged back to
14253 the original XML document. In the former case, special characters in
14254 the extracted strings shouldn’t be escaped, while they should in the
14255 latter case. To control wheter to escape special characters, the
14256 ‘Escape Special Characters’ data category can be used.
14258 To merge the translations, the ‘msgfmt’ program can be used with the
14259 option ‘--xml’. *Note msgfmt Invocation::, for more details about how
14260 one calls the ‘msgfmt’ program. ‘msgfmt’’s ‘--xml’ option doesn’t
14261 perform character escaping, so translated strings can have arbitrary XML
14262 constructs, such as elements for markup.
14265 File: gettext.info, Node: Conclusion, Next: Language Codes, Prev: Programming Languages, Up: Top
14267 16 Concluding Remarks
14268 *********************
14270 We would like to conclude this GNU ‘gettext’ manual by presenting an
14271 history of the Translation Project so far. We finally give a few
14272 pointers for those who want to do further research or readings about
14273 Native Language Support matters.
14277 * History:: History of GNU ‘gettext’
14278 * References:: Related Readings
14281 File: gettext.info, Node: History, Next: References, Prev: Conclusion, Up: Conclusion
14283 16.1 History of GNU ‘gettext’
14284 =============================
14286 Internationalization concerns and algorithms have been informally and
14287 casually discussed for years in GNU, sometimes around GNU ‘libc’, maybe
14288 around the incoming ‘Hurd’, or otherwise (nobody clearly remembers).
14289 And even then, when the work started for real, this was somewhat
14290 independently of these previous discussions.
14292 This all began in July 1994, when Patrick D’Cruze had the idea and
14293 initiative of internationalizing version 3.9.2 of GNU ‘fileutils’. He
14294 then asked Jim Meyering, the maintainer, how to get those changes folded
14295 into an official release. That first draft was full of ‘#ifdef’s and
14296 somewhat disconcerting, and Jim wanted to find nicer ways. Patrick and
14297 Jim shared some tries and experimentations in this area. Then, feeling
14298 that this might eventually have a deeper impact on GNU, Jim wanted to
14299 know what standards were, and contacted Richard Stallman, who very
14300 quickly and verbally described an overall design for what was meant to
14301 become ‘glocale’, at that time.
14303 Jim implemented ‘glocale’ and got a lot of exhausting feedback from
14304 Patrick and Richard, of course, but also from Mitchum DSouza (who wrote
14305 a ‘catgets’-like package), Roland McGrath, maybe David MacKenzie,
14306 François Pinard, and Paul Eggert, all pushing and pulling in various
14307 directions, not always compatible, to the extent that after a couple of
14308 test releases, ‘glocale’ was torn apart. In particular, Paul Eggert –
14309 always keeping an eye on developments in Solaris – advocated the use of
14310 the ‘gettext’ API over ‘glocale’’s ‘catgets’-based API.
14312 While Jim took some distance and time and became dad for a second
14313 time, Roland wanted to get GNU ‘libc’ internationalized, and got Ulrich
14314 Drepper involved in that project. Instead of starting from ‘glocale’,
14315 Ulrich rewrote something from scratch, but more conforming to the set of
14316 guidelines who emerged out of the ‘glocale’ effort. Then, Ulrich got
14317 people from the previous forum to involve themselves into this new
14318 project, and the switch from ‘glocale’ to what was first named
14319 ‘msgutils’, renamed ‘nlsutils’, and later ‘gettext’, became officially
14320 accepted by Richard in May 1995 or so.
14322 Let’s summarize by saying that Ulrich Drepper wrote GNU ‘gettext’ in
14323 April 1995. The first official release of the package, including PO
14324 mode, occurred in July 1995, and was numbered 0.7. Other people
14325 contributed to the effort by providing a discussion forum around Ulrich,
14326 writing little pieces of code, or testing. These are quoted in the
14327 ‘THANKS’ file which comes with the GNU ‘gettext’ distribution.
14329 While this was being done, François adapted half a dozen of GNU
14330 packages to ‘glocale’ first, then later to ‘gettext’, putting them in
14331 pretest, so providing along the way an effective user environment for
14332 fine tuning the evolving tools. He also took the responsibility of
14333 organizing and coordinating the Translation Project. After nearly a
14334 year of informal exchanges between people from many countries,
14335 translator teams started to exist in May 1995, through the creation and
14336 support by Patrick D’Cruze of twenty unmoderated mailing lists for that
14337 many native languages, and two moderated lists: one for reaching all
14338 teams at once, the other for reaching all willing maintainers of
14339 internationalized free software packages.
14341 François also wrote PO mode in June 1995 with the collaboration of
14342 Greg McGary, as a kind of contribution to Ulrich’s package. He also
14343 gave a hand with the GNU ‘gettext’ Texinfo manual.
14345 In 1997, Ulrich Drepper released the GNU libc 2.0, which included the
14346 ‘gettext’, ‘textdomain’ and ‘bindtextdomain’ functions.
14348 In 2000, Ulrich Drepper added plural form handling (the ‘ngettext’
14349 function) to GNU libc. Later, in 2001, he released GNU libc 2.2.x,
14350 which is the first free C library with full internationalization
14353 Ulrich being quite busy in his role of General Maintainer of GNU
14354 libc, he handed over the GNU ‘gettext’ maintenance to Bruno Haible in
14355 2000. Bruno added the plural form handling to the tools as well, added
14356 support for UTF-8 and CJK locales, and wrote a few new tools for
14357 manipulating PO files.
14360 File: gettext.info, Node: References, Prev: History, Up: Conclusion
14362 16.2 Related Readings
14363 =====================
14365 * NOTE: * This documentation section is outdated and needs to be
14368 Eugene H. Dorr (‘dorre@well.com’) maintains an interesting
14369 bibliography on internationalization matters, called
14370 ‘Internationalization Reference List’, which is available as:
14371 ftp://ftp.ora.com/pub/examples/nutshell/ujip/doc/i18n-books.txt
14373 Michael Gschwind (‘mike@vlsivie.tuwien.ac.at’) maintains a Frequently
14374 Asked Questions (FAQ) list, entitled ‘Programming for
14375 Internationalisation’. This FAQ discusses writing programs which can
14376 handle different language conventions, character sets, etc.; and is
14377 applicable to all character set encodings, with particular emphasis on
14378 ISO 8859-1. It is regularly published in Usenet groups
14379 ‘comp.unix.questions’, ‘comp.std.internat’,
14380 ‘comp.software.international’, ‘comp.lang.c’, ‘comp.windows.x’,
14381 ‘comp.std.c’, ‘comp.answers’ and ‘news.answers’. The home location of
14383 ftp://ftp.vlsivie.tuwien.ac.at/pub/8bit/ISO-programming
14385 Patrick D’Cruze (‘pdcruze@li.org’) wrote a tutorial about NLS
14386 matters, and Jochen Hein (‘Hein@student.tu-clausthal.de’) took over the
14387 responsibility of maintaining it. It may be found as:
14388 ftp://sunsite.unc.edu/pub/Linux/utils/nls/catalogs/Incoming/...
14389 ...locale-tutorial-0.8.txt.gz
14390 This site is mirrored in:
14391 ftp://ftp.ibp.fr/pub/linux/sunsite/
14393 A French version of the same tutorial should be findable at:
14394 ftp://ftp.ibp.fr/pub/linux/french/docs/
14395 together with French translations of many Linux-related documents.
14398 File: gettext.info, Node: Language Codes, Next: Country Codes, Prev: Conclusion, Up: Top
14400 Appendix A Language Codes
14401 *************************
14403 The ISO 639 standard defines two-letter codes for many languages, and
14404 three-letter codes for more rarely used languages. All abbreviations
14405 for languages used in the Translation Project should come from this
14410 * Usual Language Codes:: Two-letter ISO 639 language codes
14411 * Rare Language Codes:: Three-letter ISO 639 language codes
14414 File: gettext.info, Node: Usual Language Codes, Next: Rare Language Codes, Prev: Language Codes, Up: Language Codes
14416 A.1 Usual Language Codes
14417 ========================
14419 For the commonly used languages, the ISO 639-1 standard defines
14535 Hebrew (formerly iw).
14543 Haitian; Haitian Creole.
14553 Indonesian (formerly in).
14555 Interlingue; Occidental.
14581 Kuanyama; Kwanyama.
14585 Kalaallisut; Greenlandic.
14587 Central Khmer; Cambodian.
14607 Letzeburgesch; Luxembourgish.
14611 Limburgish; Limburger; Limburgan.
14667 Occitan; Provençal.
14709 Sinhala; Sinhalese.
14727 Sesotho; Sotho, Southern.
14783 Yiddish (formerly ji).
14794 File: gettext.info, Node: Rare Language Codes, Prev: Usual Language Codes, Up: Language Codes
14796 A.2 Rare Language Codes
14797 =======================
14799 For rarely used languages, the ISO 639-2 standard defines
14800 three-letter codes. Here is the current list, reduced to only living
14801 languages with at least one million of speakers.
14830 Filipino; Pilipino.
14836 Swiss German; Alemannic; Alsatian.
14858 Luo (Kenya and Tanzania).
14882 Pedi; Sepedi; Northern Sotho.
14890 Pampanga; Kapampangan.
14925 File: gettext.info, Node: Country Codes, Next: Licenses, Prev: Language Codes, Up: Top
14927 Appendix B Country Codes
14928 ************************
14930 The ISO 3166 standard defines two character codes for many countries
14931 and territories. All abbreviations for countries used in the
14932 Translation Project should come from this standard.
14937 United Arab Emirates.
14941 Antigua and Barbuda.
14967 Bosnia and Herzegovina.
14991 Bolivia, Plurinational State of.
14993 Bonaire, Sint Eustatius and Saba.
15011 Cocos (Keeling) Islands.
15013 Congo, The Democratic Republic of the.
15015 Central African Republic.
15055 Dominican Republic.
15077 Falkland Islands (Malvinas).
15079 Micronesia, Federated States of.
15113 South Georgia and the South Sandwich Islands.
15125 Heard Island and McDonald Islands.
15145 British Indian Ocean Territory.
15149 Iran, Islamic Republic of.
15173 Saint Kitts and Nevis.
15175 Korea, Democratic People’s Republic of.
15177 Korea, Republic of.
15185 Lao People’s Democratic Republic.
15211 Moldova, Republic of.
15215 Saint Martin (French part).
15221 Macedonia, The Former Yugoslav Republic of.
15231 Northern Mariana Islands.
15293 Saint Pierre and Miquelon.
15299 Palestine, State of.
15315 Russian Federation.
15331 Saint Helena, Ascension and Tristan da Cunha.
15335 Svalbard and Jan Mayen.
15351 Sao Tome and Principe.
15355 Sint Maarten (Dutch part).
15357 Syrian Arab Republic.
15361 Turks and Caicos Islands.
15365 French Southern Territories.
15385 Trinidad and Tobago.
15389 Taiwan, Province of China.
15391 Tanzania, United Republic of.
15397 United States Minor Outlying Islands.
15405 Holy See (Vatican City State).
15407 Saint Vincent and the Grenadines.
15409 Venezuela, Bolivarian Republic of.
15411 Virgin Islands, British.
15413 Virgin Islands, U.S..
15434 File: gettext.info, Node: Licenses, Next: Program Index, Prev: Country Codes, Up: Top
15436 Appendix C Licenses
15437 *******************
15439 The files of this package are covered by the licenses indicated in
15440 each particular file or directory. Here is a summary:
15442 • The ‘libintl’ and ‘libasprintf’ libraries are covered by the GNU
15443 Lesser General Public License (LGPL). A copy of the license is
15444 included in *note GNU LGPL::.
15446 • The executable programs of this package and the ‘libgettextpo’
15447 library are covered by the GNU General Public License (GPL). A copy
15448 of the license is included in *note GNU GPL::.
15450 • This manual is free documentation. It is dually licensed under the
15451 GNU FDL and the GNU GPL. This means that you can redistribute this
15452 manual under either of these two licenses, at your choice.
15453 This manual is covered by the GNU FDL. Permission is granted to
15454 copy, distribute and/or modify this document under the terms of the
15455 GNU Free Documentation License (FDL), either version 1.2 of the
15456 License, or (at your option) any later version published by the
15457 Free Software Foundation (FSF); with no Invariant Sections, with no
15458 Front-Cover Text, and with no Back-Cover Texts. A copy of the
15459 license is included in *note GNU FDL::.
15460 This manual is covered by the GNU GPL. You can redistribute it
15461 and/or modify it under the terms of the GNU General Public License
15462 (GPL), either version 2 of the License, or (at your option) any
15463 later version published by the Free Software Foundation (FSF). A
15464 copy of the license is included in *note GNU GPL::.
15468 * GNU GPL:: GNU General Public License
15469 * GNU LGPL:: GNU Lesser General Public License
15470 * GNU FDL:: GNU Free Documentation License
15473 File: gettext.info, Node: GNU GPL, Next: GNU LGPL, Prev: Licenses, Up: Licenses
15475 C.1 GNU GENERAL PUBLIC LICENSE
15476 ==============================
15478 Version 2, June 1991
15480 Copyright © 1989, 1991 Free Software Foundation, Inc.
15481 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
15483 Everyone is permitted to copy and distribute verbatim copies
15484 of this license document, but changing it is not allowed.
15489 The licenses for most software are designed to take away your freedom
15490 to share and change it. By contrast, the GNU General Public License is
15491 intended to guarantee your freedom to share and change free software—to
15492 make sure the software is free for all its users. This General Public
15493 License applies to most of the Free Software Foundation’s software and
15494 to any other program whose authors commit to using it. (Some other Free
15495 Software Foundation software is covered by the GNU Lesser General Public
15496 License instead.) You can apply it to your programs, too.
15498 When we speak of free software, we are referring to freedom, not
15499 price. Our General Public Licenses are designed to make sure that you
15500 have the freedom to distribute copies of free software (and charge for
15501 this service if you wish), that you receive source code or can get it if
15502 you want it, that you can change the software or use pieces of it in new
15503 free programs; and that you know you can do these things.
15505 To protect your rights, we need to make restrictions that forbid
15506 anyone to deny you these rights or to ask you to surrender the rights.
15507 These restrictions translate to certain responsibilities for you if you
15508 distribute copies of the software, or if you modify it.
15510 For example, if you distribute copies of such a program, whether
15511 gratis or for a fee, you must give the recipients all the rights that
15512 you have. You must make sure that they, too, receive or can get the
15513 source code. And you must show them these terms so they know their
15516 We protect your rights with two steps: (1) copyright the software,
15517 and (2) offer you this license which gives you legal permission to copy,
15518 distribute and/or modify the software.
15520 Also, for each author’s protection and ours, we want to make certain
15521 that everyone understands that there is no warranty for this free
15522 software. If the software is modified by someone else and passed on, we
15523 want its recipients to know that what they have is not the original, so
15524 that any problems introduced by others will not reflect on the original
15525 authors’ reputations.
15527 Finally, any free program is threatened constantly by software
15528 patents. We wish to avoid the danger that redistributors of a free
15529 program will individually obtain patent licenses, in effect making the
15530 program proprietary. To prevent this, we have made it clear that any
15531 patent must be licensed for everyone’s free use or not licensed at all.
15533 The precise terms and conditions for copying, distribution and
15534 modification follow.
15536 TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
15537 ===============================================================
15539 0. This License applies to any program or other work which contains a
15540 notice placed by the copyright holder saying it may be distributed
15541 under the terms of this General Public License. The “Program”,
15542 below, refers to any such program or work, and a “work based on the
15543 Program” means either the Program or any derivative work under
15544 copyright law: that is to say, a work containing the Program or a
15545 portion of it, either verbatim or with modifications and/or
15546 translated into another language. (Hereinafter, translation is
15547 included without limitation in the term “modification”.) Each
15548 licensee is addressed as “you”.
15550 Activities other than copying, distribution and modification are
15551 not covered by this License; they are outside its scope. The act
15552 of running the Program is not restricted, and the output from the
15553 Program is covered only if its contents constitute a work based on
15554 the Program (independent of having been made by running the
15555 Program). Whether that is true depends on what the Program does.
15557 1. You may copy and distribute verbatim copies of the Program’s source
15558 code as you receive it, in any medium, provided that you
15559 conspicuously and appropriately publish on each copy an appropriate
15560 copyright notice and disclaimer of warranty; keep intact all the
15561 notices that refer to this License and to the absence of any
15562 warranty; and give any other recipients of the Program a copy of
15563 this License along with the Program.
15565 You may charge a fee for the physical act of transferring a copy,
15566 and you may at your option offer warranty protection in exchange
15569 2. You may modify your copy or copies of the Program or any portion of
15570 it, thus forming a work based on the Program, and copy and
15571 distribute such modifications or work under the terms of Section 1
15572 above, provided that you also meet all of these conditions:
15574 a. You must cause the modified files to carry prominent notices
15575 stating that you changed the files and the date of any change.
15577 b. You must cause any work that you distribute or publish, that
15578 in whole or in part contains or is derived from the Program or
15579 any part thereof, to be licensed as a whole at no charge to
15580 all third parties under the terms of this License.
15582 c. If the modified program normally reads commands interactively
15583 when run, you must cause it, when started running for such
15584 interactive use in the most ordinary way, to print or display
15585 an announcement including an appropriate copyright notice and
15586 a notice that there is no warranty (or else, saying that you
15587 provide a warranty) and that users may redistribute the
15588 program under these conditions, and telling the user how to
15589 view a copy of this License. (Exception: if the Program
15590 itself is interactive but does not normally print such an
15591 announcement, your work based on the Program is not required
15592 to print an announcement.)
15594 These requirements apply to the modified work as a whole. If
15595 identifiable sections of that work are not derived from the
15596 Program, and can be reasonably considered independent and separate
15597 works in themselves, then this License, and its terms, do not apply
15598 to those sections when you distribute them as separate works. But
15599 when you distribute the same sections as part of a whole which is a
15600 work based on the Program, the distribution of the whole must be on
15601 the terms of this License, whose permissions for other licensees
15602 extend to the entire whole, and thus to each and every part
15603 regardless of who wrote it.
15605 Thus, it is not the intent of this section to claim rights or
15606 contest your rights to work written entirely by you; rather, the
15607 intent is to exercise the right to control the distribution of
15608 derivative or collective works based on the Program.
15610 In addition, mere aggregation of another work not based on the
15611 Program with the Program (or with a work based on the Program) on a
15612 volume of a storage or distribution medium does not bring the other
15613 work under the scope of this License.
15615 3. You may copy and distribute the Program (or a work based on it,
15616 under Section 2) in object code or executable form under the terms
15617 of Sections 1 and 2 above provided that you also do one of the
15620 a. Accompany it with the complete corresponding machine-readable
15621 source code, which must be distributed under the terms of
15622 Sections 1 and 2 above on a medium customarily used for
15623 software interchange; or,
15625 b. Accompany it with a written offer, valid for at least three
15626 years, to give any third party, for a charge no more than your
15627 cost of physically performing source distribution, a complete
15628 machine-readable copy of the corresponding source code, to be
15629 distributed under the terms of Sections 1 and 2 above on a
15630 medium customarily used for software interchange; or,
15632 c. Accompany it with the information you received as to the offer
15633 to distribute corresponding source code. (This alternative is
15634 allowed only for noncommercial distribution and only if you
15635 received the program in object code or executable form with
15636 such an offer, in accord with Subsection b above.)
15638 The source code for a work means the preferred form of the work for
15639 making modifications to it. For an executable work, complete
15640 source code means all the source code for all modules it contains,
15641 plus any associated interface definition files, plus the scripts
15642 used to control compilation and installation of the executable.
15643 However, as a special exception, the source code distributed need
15644 not include anything that is normally distributed (in either source
15645 or binary form) with the major components (compiler, kernel, and so
15646 on) of the operating system on which the executable runs, unless
15647 that component itself accompanies the executable.
15649 If distribution of executable or object code is made by offering
15650 access to copy from a designated place, then offering equivalent
15651 access to copy the source code from the same place counts as
15652 distribution of the source code, even though third parties are not
15653 compelled to copy the source along with the object code.
15655 4. You may not copy, modify, sublicense, or distribute the Program
15656 except as expressly provided under this License. Any attempt
15657 otherwise to copy, modify, sublicense or distribute the Program is
15658 void, and will automatically terminate your rights under this
15659 License. However, parties who have received copies, or rights,
15660 from you under this License will not have their licenses terminated
15661 so long as such parties remain in full compliance.
15663 5. You are not required to accept this License, since you have not
15664 signed it. However, nothing else grants you permission to modify
15665 or distribute the Program or its derivative works. These actions
15666 are prohibited by law if you do not accept this License.
15667 Therefore, by modifying or distributing the Program (or any work
15668 based on the Program), you indicate your acceptance of this License
15669 to do so, and all its terms and conditions for copying,
15670 distributing or modifying the Program or works based on it.
15672 6. Each time you redistribute the Program (or any work based on the
15673 Program), the recipient automatically receives a license from the
15674 original licensor to copy, distribute or modify the Program subject
15675 to these terms and conditions. You may not impose any further
15676 restrictions on the recipients’ exercise of the rights granted
15677 herein. You are not responsible for enforcing compliance by third
15678 parties to this License.
15680 7. If, as a consequence of a court judgment or allegation of patent
15681 infringement or for any other reason (not limited to patent
15682 issues), conditions are imposed on you (whether by court order,
15683 agreement or otherwise) that contradict the conditions of this
15684 License, they do not excuse you from the conditions of this
15685 License. If you cannot distribute so as to satisfy simultaneously
15686 your obligations under this License and any other pertinent
15687 obligations, then as a consequence you may not distribute the
15688 Program at all. For example, if a patent license would not permit
15689 royalty-free redistribution of the Program by all those who receive
15690 copies directly or indirectly through you, then the only way you
15691 could satisfy both it and this License would be to refrain entirely
15692 from distribution of the Program.
15694 If any portion of this section is held invalid or unenforceable
15695 under any particular circumstance, the balance of the section is
15696 intended to apply and the section as a whole is intended to apply
15697 in other circumstances.
15699 It is not the purpose of this section to induce you to infringe any
15700 patents or other property right claims or to contest validity of
15701 any such claims; this section has the sole purpose of protecting
15702 the integrity of the free software distribution system, which is
15703 implemented by public license practices. Many people have made
15704 generous contributions to the wide range of software distributed
15705 through that system in reliance on consistent application of that
15706 system; it is up to the author/donor to decide if he or she is
15707 willing to distribute software through any other system and a
15708 licensee cannot impose that choice.
15710 This section is intended to make thoroughly clear what is believed
15711 to be a consequence of the rest of this License.
15713 8. If the distribution and/or use of the Program is restricted in
15714 certain countries either by patents or by copyrighted interfaces,
15715 the original copyright holder who places the Program under this
15716 License may add an explicit geographical distribution limitation
15717 excluding those countries, so that distribution is permitted only
15718 in or among countries not thus excluded. In such case, this
15719 License incorporates the limitation as if written in the body of
15722 9. The Free Software Foundation may publish revised and/or new
15723 versions of the General Public License from time to time. Such new
15724 versions will be similar in spirit to the present version, but may
15725 differ in detail to address new problems or concerns.
15727 Each version is given a distinguishing version number. If the
15728 Program specifies a version number of this License which applies to
15729 it and “any later version”, you have the option of following the
15730 terms and conditions either of that version or of any later version
15731 published by the Free Software Foundation. If the Program does not
15732 specify a version number of this License, you may choose any
15733 version ever published by the Free Software Foundation.
15735 10. If you wish to incorporate parts of the Program into other free
15736 programs whose distribution conditions are different, write to the
15737 author to ask for permission. For software which is copyrighted by
15738 the Free Software Foundation, write to the Free Software
15739 Foundation; we sometimes make exceptions for this. Our decision
15740 will be guided by the two goals of preserving the free status of
15741 all derivatives of our free software and of promoting the sharing
15742 and reuse of software generally.
15746 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO
15747 WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE
15748 LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS
15749 AND/OR OTHER PARTIES PROVIDE THE PROGRAM “AS IS” WITHOUT WARRANTY
15750 OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
15751 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
15752 FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND
15753 PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE
15754 DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR
15757 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
15758 WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
15759 MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE
15760 LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
15761 INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
15762 INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
15763 DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU
15764 OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY
15765 OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
15766 ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
15768 END OF TERMS AND CONDITIONS
15770 Appendix: How to Apply These Terms to Your New Programs
15771 =======================================================
15773 If you develop a new program, and you want it to be of the greatest
15774 possible use to the public, the best way to achieve this is to make it
15775 free software which everyone can redistribute and change under these
15778 To do so, attach the following notices to the program. It is safest
15779 to attach them to the start of each source file to most effectively
15780 convey the exclusion of warranty; and each file should have at least the
15781 “copyright” line and a pointer to where the full notice is found.
15783 ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES.
15784 Copyright (C) YYYY NAME OF AUTHOR
15786 This program is free software; you can redistribute it and/or modify
15787 it under the terms of the GNU General Public License as published by
15788 the Free Software Foundation; either version 2 of the License, or
15789 (at your option) any later version.
15791 This program is distributed in the hope that it will be useful,
15792 but WITHOUT ANY WARRANTY; without even the implied warranty of
15793 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15794 GNU General Public License for more details.
15796 You should have received a copy of the GNU General Public License
15797 along with this program; if not, write to the Free Software
15798 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
15800 Also add information on how to contact you by electronic and paper
15803 If the program is interactive, make it output a short notice like
15804 this when it starts in an interactive mode:
15806 Gnomovision version 69, Copyright (C) YEAR NAME OF AUTHOR
15807 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
15808 This is free software, and you are welcome to redistribute it
15809 under certain conditions; type `show c' for details.
15811 The hypothetical commands ‘show w’ and ‘show c’ should show the
15812 appropriate parts of the General Public License. Of course, the
15813 commands you use may be called something other than ‘show w’ and ‘show
15814 c’; they could even be mouse-clicks or menu items—whatever suits your
15817 You should also get your employer (if you work as a programmer) or
15818 your school, if any, to sign a “copyright disclaimer” for the program,
15819 if necessary. Here is a sample; alter the names:
15821 Yoyodyne, Inc., hereby disclaims all copyright interest in the program
15822 `Gnomovision' (which makes passes at compilers) written by James Hacker.
15824 SIGNATURE OF TY COON, 1 April 1989
15825 Ty Coon, President of Vice
15827 This General Public License does not permit incorporating your
15828 program into proprietary programs. If your program is a subroutine
15829 library, you may consider it more useful to permit linking proprietary
15830 applications with the library. If this is what you want to do, use the
15831 GNU Lesser General Public License instead of this License.
15834 File: gettext.info, Node: GNU LGPL, Next: GNU FDL, Prev: GNU GPL, Up: Licenses
15836 C.2 GNU LESSER GENERAL PUBLIC LICENSE
15837 =====================================
15839 Version 2.1, February 1999
15841 Copyright © 1991, 1999 Free Software Foundation, Inc.
15842 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
15844 Everyone is permitted to copy and distribute verbatim copies
15845 of this license document, but changing it is not allowed.
15847 [This is the first released version of the Lesser GPL. It also counts
15848 as the successor of the GNU Library Public License, version 2, hence the
15849 version number 2.1.]
15854 The licenses for most software are designed to take away your freedom
15855 to share and change it. By contrast, the GNU General Public Licenses
15856 are intended to guarantee your freedom to share and change free
15857 software—to make sure the software is free for all its users.
15859 This license, the Lesser General Public License, applies to some
15860 specially designated software—typically libraries—of the Free Software
15861 Foundation and other authors who decide to use it. You can use it too,
15862 but we suggest you first think carefully about whether this license or
15863 the ordinary General Public License is the better strategy to use in any
15864 particular case, based on the explanations below.
15866 When we speak of free software, we are referring to freedom of use,
15867 not price. Our General Public Licenses are designed to make sure that
15868 you have the freedom to distribute copies of free software (and charge
15869 for this service if you wish); that you receive source code or can get
15870 it if you want it; that you can change the software and use pieces of it
15871 in new free programs; and that you are informed that you can do these
15874 To protect your rights, we need to make restrictions that forbid
15875 distributors to deny you these rights or to ask you to surrender these
15876 rights. These restrictions translate to certain responsibilities for
15877 you if you distribute copies of the library or if you modify it.
15879 For example, if you distribute copies of the library, whether gratis
15880 or for a fee, you must give the recipients all the rights that we gave
15881 you. You must make sure that they, too, receive or can get the source
15882 code. If you link other code with the library, you must provide
15883 complete object files to the recipients, so that they can relink them
15884 with the library after making changes to the library and recompiling it.
15885 And you must show them these terms so they know their rights.
15887 We protect your rights with a two-step method: (1) we copyright the
15888 library, and (2) we offer you this license, which gives you legal
15889 permission to copy, distribute and/or modify the library.
15891 To protect each distributor, we want to make it very clear that there
15892 is no warranty for the free library. Also, if the library is modified
15893 by someone else and passed on, the recipients should know that what they
15894 have is not the original version, so that the original author’s
15895 reputation will not be affected by problems that might be introduced by
15898 Finally, software patents pose a constant threat to the existence of
15899 any free program. We wish to make sure that a company cannot
15900 effectively restrict the users of a free program by obtaining a
15901 restrictive license from a patent holder. Therefore, we insist that any
15902 patent license obtained for a version of the library must be consistent
15903 with the full freedom of use specified in this license.
15905 Most GNU software, including some libraries, is covered by the
15906 ordinary GNU General Public License. This license, the GNU Lesser
15907 General Public License, applies to certain designated libraries, and is
15908 quite different from the ordinary General Public License. We use this
15909 license for certain libraries in order to permit linking those libraries
15910 into non-free programs.
15912 When a program is linked with a library, whether statically or using
15913 a shared library, the combination of the two is legally speaking a
15914 combined work, a derivative of the original library. The ordinary
15915 General Public License therefore permits such linking only if the entire
15916 combination fits its criteria of freedom. The Lesser General Public
15917 License permits more lax criteria for linking other code with the
15920 We call this license the "Lesser" General Public License because it
15921 does _Less_ to protect the user’s freedom than the ordinary General
15922 Public License. It also provides other free software developers Less of
15923 an advantage over competing non-free programs. These disadvantages are
15924 the reason we use the ordinary General Public License for many
15925 libraries. However, the Lesser license provides advantages in certain
15926 special circumstances.
15928 For example, on rare occasions, there may be a special need to
15929 encourage the widest possible use of a certain library, so that it
15930 becomes a de-facto standard. To achieve this, non-free programs must be
15931 allowed to use the library. A more frequent case is that a free library
15932 does the same job as widely used non-free libraries. In this case,
15933 there is little to gain by limiting the free library to free software
15934 only, so we use the Lesser General Public License.
15936 In other cases, permission to use a particular library in non-free
15937 programs enables a greater number of people to use a large body of free
15938 software. For example, permission to use the GNU C Library in non-free
15939 programs enables many more people to use the whole GNU operating system,
15940 as well as its variant, the GNU/Linux operating system.
15942 Although the Lesser General Public License is Less protective of the
15943 users’ freedom, it does ensure that the user of a program that is linked
15944 with the Library has the freedom and the wherewithal to run that program
15945 using a modified version of the Library.
15947 The precise terms and conditions for copying, distribution and
15948 modification follow. Pay close attention to the difference between a
15949 “work based on the library” and a “work that uses the library”. The
15950 former contains code derived from the library, whereas the latter must
15951 be combined with the library in order to run.
15953 TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
15954 ---------------------------------------------------------------
15956 0. This License Agreement applies to any software library or other
15957 program which contains a notice placed by the copyright holder or
15958 other authorized party saying it may be distributed under the terms
15959 of this Lesser General Public License (also called “this License”).
15960 Each licensee is addressed as “you”.
15962 A “library” means a collection of software functions and/or data
15963 prepared so as to be conveniently linked with application programs
15964 (which use some of those functions and data) to form executables.
15966 The “Library”, below, refers to any such software library or work
15967 which has been distributed under these terms. A “work based on the
15968 Library” means either the Library or any derivative work under
15969 copyright law: that is to say, a work containing the Library or a
15970 portion of it, either verbatim or with modifications and/or
15971 translated straightforwardly into another language. (Hereinafter,
15972 translation is included without limitation in the term
15975 “Source code” for a work means the preferred form of the work for
15976 making modifications to it. For a library, complete source code
15977 means all the source code for all modules it contains, plus any
15978 associated interface definition files, plus the scripts used to
15979 control compilation and installation of the library.
15981 Activities other than copying, distribution and modification are
15982 not covered by this License; they are outside its scope. The act
15983 of running a program using the Library is not restricted, and
15984 output from such a program is covered only if its contents
15985 constitute a work based on the Library (independent of the use of
15986 the Library in a tool for writing it). Whether that is true
15987 depends on what the Library does and what the program that uses the
15990 1. You may copy and distribute verbatim copies of the Library’s
15991 complete source code as you receive it, in any medium, provided
15992 that you conspicuously and appropriately publish on each copy an
15993 appropriate copyright notice and disclaimer of warranty; keep
15994 intact all the notices that refer to this License and to the
15995 absence of any warranty; and distribute a copy of this License
15996 along with the Library.
15998 You may charge a fee for the physical act of transferring a copy,
15999 and you may at your option offer warranty protection in exchange
16002 2. You may modify your copy or copies of the Library or any portion of
16003 it, thus forming a work based on the Library, and copy and
16004 distribute such modifications or work under the terms of Section 1
16005 above, provided that you also meet all of these conditions:
16007 a. The modified work must itself be a software library.
16009 b. You must cause the files modified to carry prominent notices
16010 stating that you changed the files and the date of any change.
16012 c. You must cause the whole of the work to be licensed at no
16013 charge to all third parties under the terms of this License.
16015 d. If a facility in the modified Library refers to a function or
16016 a table of data to be supplied by an application program that
16017 uses the facility, other than as an argument passed when the
16018 facility is invoked, then you must make a good faith effort to
16019 ensure that, in the event an application does not supply such
16020 function or table, the facility still operates, and performs
16021 whatever part of its purpose remains meaningful.
16023 (For example, a function in a library to compute square roots
16024 has a purpose that is entirely well-defined independent of the
16025 application. Therefore, Subsection 2d requires that any
16026 application-supplied function or table used by this function
16027 must be optional: if the application does not supply it, the
16028 square root function must still compute square roots.)
16030 These requirements apply to the modified work as a whole. If
16031 identifiable sections of that work are not derived from the
16032 Library, and can be reasonably considered independent and separate
16033 works in themselves, then this License, and its terms, do not apply
16034 to those sections when you distribute them as separate works. But
16035 when you distribute the same sections as part of a whole which is a
16036 work based on the Library, the distribution of the whole must be on
16037 the terms of this License, whose permissions for other licensees
16038 extend to the entire whole, and thus to each and every part
16039 regardless of who wrote it.
16041 Thus, it is not the intent of this section to claim rights or
16042 contest your rights to work written entirely by you; rather, the
16043 intent is to exercise the right to control the distribution of
16044 derivative or collective works based on the Library.
16046 In addition, mere aggregation of another work not based on the
16047 Library with the Library (or with a work based on the Library) on a
16048 volume of a storage or distribution medium does not bring the other
16049 work under the scope of this License.
16051 3. You may opt to apply the terms of the ordinary GNU General Public
16052 License instead of this License to a given copy of the Library. To
16053 do this, you must alter all the notices that refer to this License,
16054 so that they refer to the ordinary GNU General Public License,
16055 version 2, instead of to this License. (If a newer version than
16056 version 2 of the ordinary GNU General Public License has appeared,
16057 then you can specify that version instead if you wish.) Do not
16058 make any other change in these notices.
16060 Once this change is made in a given copy, it is irreversible for
16061 that copy, so the ordinary GNU General Public License applies to
16062 all subsequent copies and derivative works made from that copy.
16064 This option is useful when you wish to copy part of the code of the
16065 Library into a program that is not a library.
16067 4. You may copy and distribute the Library (or a portion or derivative
16068 of it, under Section 2) in object code or executable form under the
16069 terms of Sections 1 and 2 above provided that you accompany it with
16070 the complete corresponding machine-readable source code, which must
16071 be distributed under the terms of Sections 1 and 2 above on a
16072 medium customarily used for software interchange.
16074 If distribution of object code is made by offering access to copy
16075 from a designated place, then offering equivalent access to copy
16076 the source code from the same place satisfies the requirement to
16077 distribute the source code, even though third parties are not
16078 compelled to copy the source along with the object code.
16080 5. A program that contains no derivative of any portion of the
16081 Library, but is designed to work with the Library by being compiled
16082 or linked with it, is called a “work that uses the Library”. Such
16083 a work, in isolation, is not a derivative work of the Library, and
16084 therefore falls outside the scope of this License.
16086 However, linking a “work that uses the Library” with the Library
16087 creates an executable that is a derivative of the Library (because
16088 it contains portions of the Library), rather than a “work that uses
16089 the library”. The executable is therefore covered by this License.
16090 Section 6 states terms for distribution of such executables.
16092 When a “work that uses the Library” uses material from a header
16093 file that is part of the Library, the object code for the work may
16094 be a derivative work of the Library even though the source code is
16095 not. Whether this is true is especially significant if the work
16096 can be linked without the Library, or if the work is itself a
16097 library. The threshold for this to be true is not precisely
16100 If such an object file uses only numerical parameters, data
16101 structure layouts and accessors, and small macros and small inline
16102 functions (ten lines or less in length), then the use of the object
16103 file is unrestricted, regardless of whether it is legally a
16104 derivative work. (Executables containing this object code plus
16105 portions of the Library will still fall under Section 6.)
16107 Otherwise, if the work is a derivative of the Library, you may
16108 distribute the object code for the work under the terms of Section
16109 6. Any executables containing that work also fall under Section 6,
16110 whether or not they are linked directly with the Library itself.
16112 6. As an exception to the Sections above, you may also combine or link
16113 a “work that uses the Library” with the Library to produce a work
16114 containing portions of the Library, and distribute that work under
16115 terms of your choice, provided that the terms permit modification
16116 of the work for the customer’s own use and reverse engineering for
16117 debugging such modifications.
16119 You must give prominent notice with each copy of the work that the
16120 Library is used in it and that the Library and its use are covered
16121 by this License. You must supply a copy of this License. If the
16122 work during execution displays copyright notices, you must include
16123 the copyright notice for the Library among them, as well as a
16124 reference directing the user to the copy of this License. Also,
16125 you must do one of these things:
16127 a. Accompany the work with the complete corresponding
16128 machine-readable source code for the Library including
16129 whatever changes were used in the work (which must be
16130 distributed under Sections 1 and 2 above); and, if the work is
16131 an executable linked with the Library, with the complete
16132 machine-readable “work that uses the Library”, as object code
16133 and/or source code, so that the user can modify the Library
16134 and then relink to produce a modified executable containing
16135 the modified Library. (It is understood that the user who
16136 changes the contents of definitions files in the Library will
16137 not necessarily be able to recompile the application to use
16138 the modified definitions.)
16140 b. Use a suitable shared library mechanism for linking with the
16141 Library. A suitable mechanism is one that (1) uses at run
16142 time a copy of the library already present on the user’s
16143 computer system, rather than copying library functions into
16144 the executable, and (2) will operate properly with a modified
16145 version of the library, if the user installs one, as long as
16146 the modified version is interface-compatible with the version
16147 that the work was made with.
16149 c. Accompany the work with a written offer, valid for at least
16150 three years, to give the same user the materials specified in
16151 Subsection 6a, above, for a charge no more than the cost of
16152 performing this distribution.
16154 d. If distribution of the work is made by offering access to copy
16155 from a designated place, offer equivalent access to copy the
16156 above specified materials from the same place.
16158 e. Verify that the user has already received a copy of these
16159 materials or that you have already sent this user a copy.
16161 For an executable, the required form of the “work that uses the
16162 Library” must include any data and utility programs needed for
16163 reproducing the executable from it. However, as a special
16164 exception, the materials to be distributed need not include
16165 anything that is normally distributed (in either source or binary
16166 form) with the major components (compiler, kernel, and so on) of
16167 the operating system on which the executable runs, unless that
16168 component itself accompanies the executable.
16170 It may happen that this requirement contradicts the license
16171 restrictions of other proprietary libraries that do not normally
16172 accompany the operating system. Such a contradiction means you
16173 cannot use both them and the Library together in an executable that
16176 7. You may place library facilities that are a work based on the
16177 Library side-by-side in a single library together with other
16178 library facilities not covered by this License, and distribute such
16179 a combined library, provided that the separate distribution of the
16180 work based on the Library and of the other library facilities is
16181 otherwise permitted, and provided that you do these two things:
16183 a. Accompany the combined library with a copy of the same work
16184 based on the Library, uncombined with any other library
16185 facilities. This must be distributed under the terms of the
16188 b. Give prominent notice with the combined library of the fact
16189 that part of it is a work based on the Library, and explaining
16190 where to find the accompanying uncombined form of the same
16193 8. You may not copy, modify, sublicense, link with, or distribute the
16194 Library except as expressly provided under this License. Any
16195 attempt otherwise to copy, modify, sublicense, link with, or
16196 distribute the Library is void, and will automatically terminate
16197 your rights under this License. However, parties who have received
16198 copies, or rights, from you under this License will not have their
16199 licenses terminated so long as such parties remain in full
16202 9. You are not required to accept this License, since you have not
16203 signed it. However, nothing else grants you permission to modify
16204 or distribute the Library or its derivative works. These actions
16205 are prohibited by law if you do not accept this License.
16206 Therefore, by modifying or distributing the Library (or any work
16207 based on the Library), you indicate your acceptance of this License
16208 to do so, and all its terms and conditions for copying,
16209 distributing or modifying the Library or works based on it.
16211 10. Each time you redistribute the Library (or any work based on the
16212 Library), the recipient automatically receives a license from the
16213 original licensor to copy, distribute, link with or modify the
16214 Library subject to these terms and conditions. You may not impose
16215 any further restrictions on the recipients’ exercise of the rights
16216 granted herein. You are not responsible for enforcing compliance
16217 by third parties with this License.
16219 11. If, as a consequence of a court judgment or allegation of patent
16220 infringement or for any other reason (not limited to patent
16221 issues), conditions are imposed on you (whether by court order,
16222 agreement or otherwise) that contradict the conditions of this
16223 License, they do not excuse you from the conditions of this
16224 License. If you cannot distribute so as to satisfy simultaneously
16225 your obligations under this License and any other pertinent
16226 obligations, then as a consequence you may not distribute the
16227 Library at all. For example, if a patent license would not permit
16228 royalty-free redistribution of the Library by all those who receive
16229 copies directly or indirectly through you, then the only way you
16230 could satisfy both it and this License would be to refrain entirely
16231 from distribution of the Library.
16233 If any portion of this section is held invalid or unenforceable
16234 under any particular circumstance, the balance of the section is
16235 intended to apply, and the section as a whole is intended to apply
16236 in other circumstances.
16238 It is not the purpose of this section to induce you to infringe any
16239 patents or other property right claims or to contest validity of
16240 any such claims; this section has the sole purpose of protecting
16241 the integrity of the free software distribution system which is
16242 implemented by public license practices. Many people have made
16243 generous contributions to the wide range of software distributed
16244 through that system in reliance on consistent application of that
16245 system; it is up to the author/donor to decide if he or she is
16246 willing to distribute software through any other system and a
16247 licensee cannot impose that choice.
16249 This section is intended to make thoroughly clear what is believed
16250 to be a consequence of the rest of this License.
16252 12. If the distribution and/or use of the Library is restricted in
16253 certain countries either by patents or by copyrighted interfaces,
16254 the original copyright holder who places the Library under this
16255 License may add an explicit geographical distribution limitation
16256 excluding those countries, so that distribution is permitted only
16257 in or among countries not thus excluded. In such case, this
16258 License incorporates the limitation as if written in the body of
16261 13. The Free Software Foundation may publish revised and/or new
16262 versions of the Lesser General Public License from time to time.
16263 Such new versions will be similar in spirit to the present version,
16264 but may differ in detail to address new problems or concerns.
16266 Each version is given a distinguishing version number. If the
16267 Library specifies a version number of this License which applies to
16268 it and “any later version”, you have the option of following the
16269 terms and conditions either of that version or of any later version
16270 published by the Free Software Foundation. If the Library does not
16271 specify a license version number, you may choose any version ever
16272 published by the Free Software Foundation.
16274 14. If you wish to incorporate parts of the Library into other free
16275 programs whose distribution conditions are incompatible with these,
16276 write to the author to ask for permission. For software which is
16277 copyrighted by the Free Software Foundation, write to the Free
16278 Software Foundation; we sometimes make exceptions for this. Our
16279 decision will be guided by the two goals of preserving the free
16280 status of all derivatives of our free software and of promoting the
16281 sharing and reuse of software generally.
16285 15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
16286 WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE
16287 LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS
16288 AND/OR OTHER PARTIES PROVIDE THE LIBRARY “AS IS” WITHOUT WARRANTY
16289 OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
16290 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
16291 FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND
16292 PERFORMANCE OF THE LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE
16293 DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR
16296 16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
16297 WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
16298 MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE
16299 LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
16300 INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
16301 INABILITY TO USE THE LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF
16302 DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU
16303 OR THIRD PARTIES OR A FAILURE OF THE LIBRARY TO OPERATE WITH ANY
16304 OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
16305 ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
16307 END OF TERMS AND CONDITIONS
16308 ---------------------------
16310 How to Apply These Terms to Your New Libraries
16311 ----------------------------------------------
16313 If you develop a new library, and you want it to be of the greatest
16314 possible use to the public, we recommend making it free software that
16315 everyone can redistribute and change. You can do so by permitting
16316 redistribution under these terms (or, alternatively, under the terms of
16317 the ordinary General Public License).
16319 To apply these terms, attach the following notices to the library.
16320 It is safest to attach them to the start of each source file to most
16321 effectively convey the exclusion of warranty; and each file should have
16322 at least the “copyright” line and a pointer to where the full notice is
16325 ONE LINE TO GIVE THE LIBRARY'S NAME AND AN IDEA OF WHAT IT DOES.
16326 Copyright (C) YEAR NAME OF AUTHOR
16328 This library is free software; you can redistribute it and/or modify it
16329 under the terms of the GNU Lesser General Public License as published by
16330 the Free Software Foundation; either version 2.1 of the License, or (at
16331 your option) any later version.
16333 This library is distributed in the hope that it will be useful, but
16334 WITHOUT ANY WARRANTY; without even the implied warranty of
16335 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16336 Lesser General Public License for more details.
16338 You should have received a copy of the GNU Lesser General Public
16339 License along with this library; if not, write to the Free Software
16340 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
16343 Also add information on how to contact you by electronic and paper
16346 You should also get your employer (if you work as a programmer) or
16347 your school, if any, to sign a “copyright disclaimer” for the library,
16348 if necessary. Here is a sample; alter the names:
16350 Yoyodyne, Inc., hereby disclaims all copyright interest in the library
16351 `Frob' (a library for tweaking knobs) written by James Random Hacker.
16353 SIGNATURE OF TY COON, 1 April 1990
16354 Ty Coon, President of Vice
16356 That’s all there is to it!
16359 File: gettext.info, Node: GNU FDL, Prev: GNU LGPL, Up: Licenses
16361 C.3 GNU Free Documentation License
16362 ==================================
16364 Version 1.2, November 2002
16366 Copyright © 2000,2001,2002 Free Software Foundation, Inc.
16367 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
16369 Everyone is permitted to copy and distribute verbatim copies
16370 of this license document, but changing it is not allowed.
16374 The purpose of this License is to make a manual, textbook, or other
16375 functional and useful document "free" in the sense of freedom: to
16376 assure everyone the effective freedom to copy and redistribute it,
16377 with or without modifying it, either commercially or
16378 noncommercially. Secondarily, this License preserves for the
16379 author and publisher a way to get credit for their work, while not
16380 being considered responsible for modifications made by others.
16382 This License is a kind of “copyleft”, which means that derivative
16383 works of the document must themselves be free in the same sense.
16384 It complements the GNU General Public License, which is a copyleft
16385 license designed for free software.
16387 We have designed this License in order to use it for manuals for
16388 free software, because free software needs free documentation: a
16389 free program should come with manuals providing the same freedoms
16390 that the software does. But this License is not limited to
16391 software manuals; it can be used for any textual work, regardless
16392 of subject matter or whether it is published as a printed book. We
16393 recommend this License principally for works whose purpose is
16394 instruction or reference.
16396 1. APPLICABILITY AND DEFINITIONS
16398 This License applies to any manual or other work, in any medium,
16399 that contains a notice placed by the copyright holder saying it can
16400 be distributed under the terms of this License. Such a notice
16401 grants a world-wide, royalty-free license, unlimited in duration,
16402 to use that work under the conditions stated herein. The
16403 “Document”, below, refers to any such manual or work. Any member
16404 of the public is a licensee, and is addressed as “you”. You accept
16405 the license if you copy, modify or distribute the work in a way
16406 requiring permission under copyright law.
16408 A “Modified Version” of the Document means any work containing the
16409 Document or a portion of it, either copied verbatim, or with
16410 modifications and/or translated into another language.
16412 A “Secondary Section” is a named appendix or a front-matter section
16413 of the Document that deals exclusively with the relationship of the
16414 publishers or authors of the Document to the Document’s overall
16415 subject (or to related matters) and contains nothing that could
16416 fall directly within that overall subject. (Thus, if the Document
16417 is in part a textbook of mathematics, a Secondary Section may not
16418 explain any mathematics.) The relationship could be a matter of
16419 historical connection with the subject or with related matters, or
16420 of legal, commercial, philosophical, ethical or political position
16423 The “Invariant Sections” are certain Secondary Sections whose
16424 titles are designated, as being those of Invariant Sections, in the
16425 notice that says that the Document is released under this License.
16426 If a section does not fit the above definition of Secondary then it
16427 is not allowed to be designated as Invariant. The Document may
16428 contain zero Invariant Sections. If the Document does not identify
16429 any Invariant Sections then there are none.
16431 The “Cover Texts” are certain short passages of text that are
16432 listed, as Front-Cover Texts or Back-Cover Texts, in the notice
16433 that says that the Document is released under this License. A
16434 Front-Cover Text may be at most 5 words, and a Back-Cover Text may
16435 be at most 25 words.
16437 A “Transparent” copy of the Document means a machine-readable copy,
16438 represented in a format whose specification is available to the
16439 general public, that is suitable for revising the document
16440 straightforwardly with generic text editors or (for images composed
16441 of pixels) generic paint programs or (for drawings) some widely
16442 available drawing editor, and that is suitable for input to text
16443 formatters or for automatic translation to a variety of formats
16444 suitable for input to text formatters. A copy made in an otherwise
16445 Transparent file format whose markup, or absence of markup, has
16446 been arranged to thwart or discourage subsequent modification by
16447 readers is not Transparent. An image format is not Transparent if
16448 used for any substantial amount of text. A copy that is not
16449 “Transparent” is called “Opaque”.
16451 Examples of suitable formats for Transparent copies include plain
16452 ASCII without markup, Texinfo input format, LaTeX input format,
16453 SGML or XML using a publicly available DTD, and standard-conforming
16454 simple HTML, PostScript or PDF designed for human modification.
16455 Examples of transparent image formats include PNG, XCF and JPG.
16456 Opaque formats include proprietary formats that can be read and
16457 edited only by proprietary word processors, SGML or XML for which
16458 the DTD and/or processing tools are not generally available, and
16459 the machine-generated HTML, PostScript or PDF produced by some word
16460 processors for output purposes only.
16462 The “Title Page” means, for a printed book, the title page itself,
16463 plus such following pages as are needed to hold, legibly, the
16464 material this License requires to appear in the title page. For
16465 works in formats which do not have any title page as such, “Title
16466 Page” means the text near the most prominent appearance of the
16467 work’s title, preceding the beginning of the body of the text.
16469 A section “Entitled XYZ” means a named subunit of the Document
16470 whose title either is precisely XYZ or contains XYZ in parentheses
16471 following text that translates XYZ in another language. (Here XYZ
16472 stands for a specific section name mentioned below, such as
16473 “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.)
16474 To “Preserve the Title” of such a section when you modify the
16475 Document means that it remains a section “Entitled XYZ” according
16476 to this definition.
16478 The Document may include Warranty Disclaimers next to the notice
16479 which states that this License applies to the Document. These
16480 Warranty Disclaimers are considered to be included by reference in
16481 this License, but only as regards disclaiming warranties: any other
16482 implication that these Warranty Disclaimers may have is void and
16483 has no effect on the meaning of this License.
16485 2. VERBATIM COPYING
16487 You may copy and distribute the Document in any medium, either
16488 commercially or noncommercially, provided that this License, the
16489 copyright notices, and the license notice saying this License
16490 applies to the Document are reproduced in all copies, and that you
16491 add no other conditions whatsoever to those of this License. You
16492 may not use technical measures to obstruct or control the reading
16493 or further copying of the copies you make or distribute. However,
16494 you may accept compensation in exchange for copies. If you
16495 distribute a large enough number of copies you must also follow the
16496 conditions in section 3.
16498 You may also lend copies, under the same conditions stated above,
16499 and you may publicly display copies.
16501 3. COPYING IN QUANTITY
16503 If you publish printed copies (or copies in media that commonly
16504 have printed covers) of the Document, numbering more than 100, and
16505 the Document’s license notice requires Cover Texts, you must
16506 enclose the copies in covers that carry, clearly and legibly, all
16507 these Cover Texts: Front-Cover Texts on the front cover, and
16508 Back-Cover Texts on the back cover. Both covers must also clearly
16509 and legibly identify you as the publisher of these copies. The
16510 front cover must present the full title with all words of the title
16511 equally prominent and visible. You may add other material on the
16512 covers in addition. Copying with changes limited to the covers, as
16513 long as they preserve the title of the Document and satisfy these
16514 conditions, can be treated as verbatim copying in other respects.
16516 If the required texts for either cover are too voluminous to fit
16517 legibly, you should put the first ones listed (as many as fit
16518 reasonably) on the actual cover, and continue the rest onto
16521 If you publish or distribute Opaque copies of the Document
16522 numbering more than 100, you must either include a machine-readable
16523 Transparent copy along with each Opaque copy, or state in or with
16524 each Opaque copy a computer-network location from which the general
16525 network-using public has access to download using public-standard
16526 network protocols a complete Transparent copy of the Document, free
16527 of added material. If you use the latter option, you must take
16528 reasonably prudent steps, when you begin distribution of Opaque
16529 copies in quantity, to ensure that this Transparent copy will
16530 remain thus accessible at the stated location until at least one
16531 year after the last time you distribute an Opaque copy (directly or
16532 through your agents or retailers) of that edition to the public.
16534 It is requested, but not required, that you contact the authors of
16535 the Document well before redistributing any large number of copies,
16536 to give them a chance to provide you with an updated version of the
16541 You may copy and distribute a Modified Version of the Document
16542 under the conditions of sections 2 and 3 above, provided that you
16543 release the Modified Version under precisely this License, with the
16544 Modified Version filling the role of the Document, thus licensing
16545 distribution and modification of the Modified Version to whoever
16546 possesses a copy of it. In addition, you must do these things in
16547 the Modified Version:
16549 A. Use in the Title Page (and on the covers, if any) a title
16550 distinct from that of the Document, and from those of previous
16551 versions (which should, if there were any, be listed in the
16552 History section of the Document). You may use the same title
16553 as a previous version if the original publisher of that
16554 version gives permission.
16556 B. List on the Title Page, as authors, one or more persons or
16557 entities responsible for authorship of the modifications in
16558 the Modified Version, together with at least five of the
16559 principal authors of the Document (all of its principal
16560 authors, if it has fewer than five), unless they release you
16561 from this requirement.
16563 C. State on the Title page the name of the publisher of the
16564 Modified Version, as the publisher.
16566 D. Preserve all the copyright notices of the Document.
16568 E. Add an appropriate copyright notice for your modifications
16569 adjacent to the other copyright notices.
16571 F. Include, immediately after the copyright notices, a license
16572 notice giving the public permission to use the Modified
16573 Version under the terms of this License, in the form shown in
16574 the Addendum below.
16576 G. Preserve in that license notice the full lists of Invariant
16577 Sections and required Cover Texts given in the Document’s
16580 H. Include an unaltered copy of this License.
16582 I. Preserve the section Entitled “History”, Preserve its Title,
16583 and add to it an item stating at least the title, year, new
16584 authors, and publisher of the Modified Version as given on the
16585 Title Page. If there is no section Entitled “History” in the
16586 Document, create one stating the title, year, authors, and
16587 publisher of the Document as given on its Title Page, then add
16588 an item describing the Modified Version as stated in the
16591 J. Preserve the network location, if any, given in the Document
16592 for public access to a Transparent copy of the Document, and
16593 likewise the network locations given in the Document for
16594 previous versions it was based on. These may be placed in the
16595 “History” section. You may omit a network location for a work
16596 that was published at least four years before the Document
16597 itself, or if the original publisher of the version it refers
16598 to gives permission.
16600 K. For any section Entitled “Acknowledgements” or “Dedications”,
16601 Preserve the Title of the section, and preserve in the section
16602 all the substance and tone of each of the contributor
16603 acknowledgements and/or dedications given therein.
16605 L. Preserve all the Invariant Sections of the Document, unaltered
16606 in their text and in their titles. Section numbers or the
16607 equivalent are not considered part of the section titles.
16609 M. Delete any section Entitled “Endorsements”. Such a section
16610 may not be included in the Modified Version.
16612 N. Do not retitle any existing section to be Entitled
16613 “Endorsements” or to conflict in title with any Invariant
16616 O. Preserve any Warranty Disclaimers.
16618 If the Modified Version includes new front-matter sections or
16619 appendices that qualify as Secondary Sections and contain no
16620 material copied from the Document, you may at your option designate
16621 some or all of these sections as invariant. To do this, add their
16622 titles to the list of Invariant Sections in the Modified Version’s
16623 license notice. These titles must be distinct from any other
16626 You may add a section Entitled “Endorsements”, provided it contains
16627 nothing but endorsements of your Modified Version by various
16628 parties—for example, statements of peer review or that the text has
16629 been approved by an organization as the authoritative definition of
16632 You may add a passage of up to five words as a Front-Cover Text,
16633 and a passage of up to 25 words as a Back-Cover Text, to the end of
16634 the list of Cover Texts in the Modified Version. Only one passage
16635 of Front-Cover Text and one of Back-Cover Text may be added by (or
16636 through arrangements made by) any one entity. If the Document
16637 already includes a cover text for the same cover, previously added
16638 by you or by arrangement made by the same entity you are acting on
16639 behalf of, you may not add another; but you may replace the old
16640 one, on explicit permission from the previous publisher that added
16643 The author(s) and publisher(s) of the Document do not by this
16644 License give permission to use their names for publicity for or to
16645 assert or imply endorsement of any Modified Version.
16647 5. COMBINING DOCUMENTS
16649 You may combine the Document with other documents released under
16650 this License, under the terms defined in section 4 above for
16651 modified versions, provided that you include in the combination all
16652 of the Invariant Sections of all of the original documents,
16653 unmodified, and list them all as Invariant Sections of your
16654 combined work in its license notice, and that you preserve all
16655 their Warranty Disclaimers.
16657 The combined work need only contain one copy of this License, and
16658 multiple identical Invariant Sections may be replaced with a single
16659 copy. If there are multiple Invariant Sections with the same name
16660 but different contents, make the title of each such section unique
16661 by adding at the end of it, in parentheses, the name of the
16662 original author or publisher of that section if known, or else a
16663 unique number. Make the same adjustment to the section titles in
16664 the list of Invariant Sections in the license notice of the
16667 In the combination, you must combine any sections Entitled
16668 “History” in the various original documents, forming one section
16669 Entitled “History”; likewise combine any sections Entitled
16670 “Acknowledgements”, and any sections Entitled “Dedications”. You
16671 must delete all sections Entitled “Endorsements.”
16673 6. COLLECTIONS OF DOCUMENTS
16675 You may make a collection consisting of the Document and other
16676 documents released under this License, and replace the individual
16677 copies of this License in the various documents with a single copy
16678 that is included in the collection, provided that you follow the
16679 rules of this License for verbatim copying of each of the documents
16680 in all other respects.
16682 You may extract a single document from such a collection, and
16683 distribute it individually under this License, provided you insert
16684 a copy of this License into the extracted document, and follow this
16685 License in all other respects regarding verbatim copying of that
16688 7. AGGREGATION WITH INDEPENDENT WORKS
16690 A compilation of the Document or its derivatives with other
16691 separate and independent documents or works, in or on a volume of a
16692 storage or distribution medium, is called an “aggregate” if the
16693 copyright resulting from the compilation is not used to limit the
16694 legal rights of the compilation’s users beyond what the individual
16695 works permit. When the Document is included in an aggregate, this
16696 License does not apply to the other works in the aggregate which
16697 are not themselves derivative works of the Document.
16699 If the Cover Text requirement of section 3 is applicable to these
16700 copies of the Document, then if the Document is less than one half
16701 of the entire aggregate, the Document’s Cover Texts may be placed
16702 on covers that bracket the Document within the aggregate, or the
16703 electronic equivalent of covers if the Document is in electronic
16704 form. Otherwise they must appear on printed covers that bracket
16705 the whole aggregate.
16709 Translation is considered a kind of modification, so you may
16710 distribute translations of the Document under the terms of section
16711 4. Replacing Invariant Sections with translations requires special
16712 permission from their copyright holders, but you may include
16713 translations of some or all Invariant Sections in addition to the
16714 original versions of these Invariant Sections. You may include a
16715 translation of this License, and all the license notices in the
16716 Document, and any Warranty Disclaimers, provided that you also
16717 include the original English version of this License and the
16718 original versions of those notices and disclaimers. In case of a
16719 disagreement between the translation and the original version of
16720 this License or a notice or disclaimer, the original version will
16723 If a section in the Document is Entitled “Acknowledgements”,
16724 “Dedications”, or “History”, the requirement (section 4) to
16725 Preserve its Title (section 1) will typically require changing the
16730 You may not copy, modify, sublicense, or distribute the Document
16731 except as expressly provided for under this License. Any other
16732 attempt to copy, modify, sublicense or distribute the Document is
16733 void, and will automatically terminate your rights under this
16734 License. However, parties who have received copies, or rights,
16735 from you under this License will not have their licenses terminated
16736 so long as such parties remain in full compliance.
16738 10. FUTURE REVISIONS OF THIS LICENSE
16740 The Free Software Foundation may publish new, revised versions of
16741 the GNU Free Documentation License from time to time. Such new
16742 versions will be similar in spirit to the present version, but may
16743 differ in detail to address new problems or concerns. See
16744 <http://www.gnu.org/copyleft/>.
16746 Each version of the License is given a distinguishing version
16747 number. If the Document specifies that a particular numbered
16748 version of this License “or any later version” applies to it, you
16749 have the option of following the terms and conditions either of
16750 that specified version or of any later version that has been
16751 published (not as a draft) by the Free Software Foundation. If the
16752 Document does not specify a version number of this License, you may
16753 choose any version ever published (not as a draft) by the Free
16754 Software Foundation.
16756 ADDENDUM: How to use this License for your documents
16757 ====================================================
16759 To use this License in a document you have written, include a copy of
16760 the License in the document and put the following copyright and license
16761 notices just after the title page:
16763 Copyright (C) YEAR YOUR NAME.
16764 Permission is granted to copy, distribute and/or modify this document
16765 under the terms of the GNU Free Documentation License, Version 1.2
16766 or any later version published by the Free Software Foundation;
16767 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
16768 Texts. A copy of the license is included in the section entitled ``GNU
16769 Free Documentation License''.
16771 If you have Invariant Sections, Front-Cover Texts and Back-Cover
16772 Texts, replace the “with…Texts.” line with this:
16774 with the Invariant Sections being LIST THEIR TITLES, with
16775 the Front-Cover Texts being LIST, and with the Back-Cover Texts
16778 If you have Invariant Sections without Cover Texts, or some other
16779 combination of the three, merge those two alternatives to suit the
16782 If your document contains nontrivial examples of program code, we
16783 recommend releasing these examples in parallel under your choice of free
16784 software license, such as the GNU General Public License, to permit
16785 their use in free software.
16788 File: gettext.info, Node: Program Index, Next: Option Index, Prev: Licenses, Up: Top
16796 * autopoint: autopoint Invocation.
16798 * boldquot: msgfilter Invocation.
16800 * envsubst: envsubst Invocation. (line 6)
16801 * gettext: sh. (line 19)
16802 * gettext <1>: gettext Invocation. (line 6)
16803 * gettextize: gettextize Invocation.
16805 * msgattrib: msgattrib Invocation.
16807 * msgcat: msgcat Invocation. (line 6)
16808 * msgcmp: msgcmp Invocation. (line 6)
16809 * msgcomm: msgcomm Invocation. (line 6)
16810 * msgconv: msgconv Invocation. (line 6)
16811 * msgen: msgen Invocation. (line 6)
16812 * msgexec: msgexec Invocation. (line 6)
16813 * msgfilter: msgfilter Invocation.
16815 * msgfmt: msgfmt Invocation. (line 6)
16816 * msggrep: msggrep Invocation. (line 6)
16817 * msginit: msginit Invocation. (line 6)
16818 * msgmerge: msgmerge Invocation. (line 6)
16819 * msgunfmt: msgunfmt Invocation. (line 6)
16820 * msguniq: msguniq Invocation. (line 6)
16821 * ngettext: sh. (line 19)
16822 * ngettext <1>: ngettext Invocation. (line 6)
16823 * quot: msgfilter Invocation.
16825 * recode-sr-latin: msgfilter Invocation.
16827 * xgettext: xgettext Invocation. (line 6)
16830 File: gettext.info, Node: Option Index, Next: Variable Index, Prev: Program Index, Up: Top
16838 * --add-comments, ‘xgettext’ option: xgettext Invocation. (line 94)
16839 * --add-location, ‘msgattrib’ option: msgattrib Invocation.
16841 * --add-location, ‘msgcat’ option: msgcat Invocation. (line 114)
16842 * --add-location, ‘msgcomm’ option: msgcomm Invocation. (line 100)
16843 * --add-location, ‘msgconv’ option: msgconv Invocation. (line 80)
16844 * --add-location, ‘msgen’ option: msgen Invocation. (line 83)
16845 * --add-location, ‘msgfilter’ option: msgfilter Invocation.
16847 * --add-location, ‘msggrep’ option: msggrep Invocation. (line 152)
16848 * --add-location, ‘msgmerge’ option: msgmerge Invocation. (line 150)
16849 * --add-location, ‘msguniq’ option: msguniq Invocation. (line 97)
16850 * --add-location, ‘xgettext’ option: xgettext Invocation. (line 368)
16851 * --alignment, ‘msgfmt’ option: msgfmt Invocation. (line 288)
16852 * --backup, ‘msgmerge’ option: msgmerge Invocation. (line 62)
16853 * --boost, ‘xgettext’ option: xgettext Invocation. (line 326)
16854 * --c++, ‘xgettext’ option: xgettext Invocation. (line 63)
16855 * --check, ‘msgfmt’ option: msgfmt Invocation. (line 226)
16856 * --check, ‘xgettext’ option: xgettext Invocation. (line 116)
16857 * --check-accelerators, ‘msgfmt’ option: msgfmt Invocation. (line 267)
16858 * --check-compatibility, ‘msgfmt’ option: msgfmt Invocation. (line 263)
16859 * --check-domain, ‘msgfmt’ option: msgfmt Invocation. (line 258)
16860 * --check-format, ‘msgfmt’ option: msgfmt Invocation. (line 230)
16861 * --check-header, ‘msgfmt’ option: msgfmt Invocation. (line 253)
16862 * --clear-fuzzy, ‘msgattrib’ option: msgattrib Invocation.
16864 * --clear-obsolete, ‘msgattrib’ option: msgattrib Invocation.
16866 * --clear-previous, ‘msgattrib’ option: msgattrib Invocation.
16868 * --color, ‘msgattrib’ option: msgattrib Invocation.
16870 * --color, ‘msgcat’ option: msgcat Invocation. (line 95)
16871 * --color, ‘msgcat’ option <1>: The --color option. (line 6)
16872 * --color, ‘msgcomm’ option: msgcomm Invocation. (line 81)
16873 * --color, ‘msgconv’ option: msgconv Invocation. (line 61)
16874 * --color, ‘msgen’ option: msgen Invocation. (line 64)
16875 * --color, ‘msgfilter’ option: msgfilter Invocation.
16877 * --color, ‘msggrep’ option: msggrep Invocation. (line 134)
16878 * --color, ‘msginit’ option: msginit Invocation. (line 93)
16879 * --color, ‘msgmerge’ option: msgmerge Invocation. (line 131)
16880 * --color, ‘msgunfmt’ option: msgunfmt Invocation. (line 103)
16881 * --color, ‘msguniq’ option: msguniq Invocation. (line 78)
16882 * --color, ‘xgettext’ option: xgettext Invocation. (line 347)
16883 * --comment, ‘msggrep’ option: msggrep Invocation. (line 86)
16884 * --compendium, ‘msgmerge’ option: msgmerge Invocation. (line 36)
16885 * --copyright-holder, ‘xgettext’ option: xgettext Invocation. (line 432)
16886 * --csharp, ‘msgfmt’ option: msgfmt Invocation. (line 36)
16887 * --csharp, ‘msgunfmt’ option: msgunfmt Invocation. (line 19)
16888 * --csharp-resources, ‘msgfmt’ option: msgfmt Invocation. (line 40)
16889 * --csharp-resources, ‘msgunfmt’ option: msgunfmt Invocation. (line 23)
16890 * --debug, ‘xgettext’ option: xgettext Invocation. (line 330)
16891 * --default-domain, ‘xgettext’ option: xgettext Invocation. (line 35)
16892 * --desktop, ‘msgfmt’ option: msgfmt Invocation. (line 49)
16893 * --directory, ‘msgattrib’ option: msgattrib Invocation.
16895 * --directory, ‘msgcat’ option: msgcat Invocation. (line 31)
16896 * --directory, ‘msgcmp’ option: msgcmp Invocation. (line 27)
16897 * --directory, ‘msgcomm’ option: msgcomm Invocation. (line 30)
16898 * --directory, ‘msgconv’ option: msgconv Invocation. (line 19)
16899 * --directory, ‘msgen’ option: msgen Invocation. (line 25)
16900 * --directory, ‘msgexec’ option: msgexec Invocation. (line 54)
16901 * --directory, ‘msgfilter’ option: msgfilter Invocation.
16903 * --directory, ‘msgfmt’ option: msgfmt Invocation. (line 18)
16904 * --directory, ‘msggrep’ option: msggrep Invocation. (line 19)
16905 * --directory, ‘msgmerge’ option: msgmerge Invocation. (line 30)
16906 * --directory, ‘msguniq’ option: msguniq Invocation. (line 26)
16907 * --directory, ‘xgettext’ option: xgettext Invocation. (line 24)
16908 * --domain, ‘gettext’ option: gettext Invocation. (line 16)
16909 * --domain, ‘msggrep’ option: msggrep Invocation. (line 70)
16910 * --domain, ‘ngettext’ option: ngettext Invocation. (line 15)
16911 * --dry-run, ‘autopoint’ option: autopoint Invocation.
16913 * --dry-run, ‘gettextize’ option: gettextize Invocation.
16915 * --empty, ‘msgattrib’ option: msgattrib Invocation.
16917 * --endianness, ‘msgfmt’ option: msgfmt Invocation. (line 291)
16918 * --exclude-file, ‘xgettext’ option: xgettext Invocation. (line 89)
16919 * --expression, ‘msgfilter’ option: msgfilter Invocation.
16921 * --extended-regexp, ‘msggrep’ option: msggrep Invocation. (line 94)
16922 * --extract-all, ‘xgettext’ option: xgettext Invocation. (line 162)
16923 * --extracted-comment, ‘msggrep’ option: msggrep Invocation. (line 90)
16924 * --file, ‘msgfilter’ option: msgfilter Invocation.
16926 * --file, ‘msggrep’ option: msggrep Invocation. (line 106)
16927 * --files-from, ‘msgcat’ option: msgcat Invocation. (line 26)
16928 * --files-from, ‘msgcomm’ option: msgcomm Invocation. (line 25)
16929 * --files-from, ‘xgettext’ option: xgettext Invocation. (line 19)
16930 * --fixed-strings, ‘msggrep’ option: msggrep Invocation. (line 98)
16931 * --flag, ‘xgettext’ option: xgettext Invocation. (line 273)
16932 * --force, ‘autopoint’ option: autopoint Invocation.
16934 * --force, ‘gettextize’ option: gettextize Invocation.
16936 * --force-po, ‘msgattrib’ option: msgattrib Invocation.
16938 * --force-po, ‘msgcat’ option: msgcat Invocation. (line 103)
16939 * --force-po, ‘msgcomm’ option: msgcomm Invocation. (line 89)
16940 * --force-po, ‘msgconv’ option: msgconv Invocation. (line 69)
16941 * --force-po, ‘msgen’ option: msgen Invocation. (line 72)
16942 * --force-po, ‘msgfilter’ option: msgfilter Invocation.
16944 * --force-po, ‘msggrep’ option: msggrep Invocation. (line 142)
16945 * --force-po, ‘msgmerge’ option: msgmerge Invocation. (line 139)
16946 * --force-po, ‘msgunfmt’ option: msgunfmt Invocation. (line 111)
16947 * --force-po, ‘msguniq’ option: msguniq Invocation. (line 86)
16948 * --force-po, ‘xgettext’ option: xgettext Invocation. (line 355)
16949 * --foreign-user, ‘xgettext’ option: xgettext Invocation. (line 447)
16950 * --from-code, ‘xgettext’ option: xgettext Invocation. (line 72)
16951 * --fuzzy, ‘msgattrib’ option: msgattrib Invocation.
16953 * --help, ‘autopoint’ option: autopoint Invocation.
16955 * --help, ‘envsubst’ option: envsubst Invocation. (line 21)
16956 * --help, ‘gettext’ option: gettext Invocation. (line 32)
16957 * --help, ‘gettextize’ option: gettextize Invocation.
16959 * --help, ‘msgattrib’ option: msgattrib Invocation.
16961 * --help, ‘msgcat’ option: msgcat Invocation. (line 164)
16962 * --help, ‘msgcmp’ option: msgcmp Invocation. (line 69)
16963 * --help, ‘msgcomm’ option: msgcomm Invocation. (line 153)
16964 * --help, ‘msgconv’ option: msgconv Invocation. (line 130)
16965 * --help, ‘msgen’ option: msgen Invocation. (line 133)
16966 * --help, ‘msgexec’ option: msgexec Invocation. (line 77)
16967 * --help, ‘msgfilter’ option: msgfilter Invocation.
16969 * --help, ‘msgfmt’ option: msgfmt Invocation. (line 312)
16970 * --help, ‘msggrep’ option: msggrep Invocation. (line 200)
16971 * --help, ‘msginit’ option: msginit Invocation. (line 128)
16972 * --help, ‘msgmerge’ option: msgmerge Invocation. (line 200)
16973 * --help, ‘msgunfmt’ option: msgunfmt Invocation. (line 155)
16974 * --help, ‘msguniq’ option: msguniq Invocation. (line 147)
16975 * --help, ‘ngettext’ option: ngettext Invocation. (line 31)
16976 * --help, ‘xgettext’ option: xgettext Invocation. (line 494)
16977 * --ignore-case, ‘msggrep’ option: msggrep Invocation. (line 110)
16978 * --ignore-file, ‘msgattrib’ option: msgattrib Invocation.
16980 * --indent, ‘msgattrib’ option: msgattrib Invocation.
16982 * --indent, ‘msgcat’ option: msgcat Invocation. (line 107)
16983 * --indent, ‘msgcomm’ option: msgcomm Invocation. (line 93)
16984 * --indent, ‘msgconv’ option: msgconv Invocation. (line 73)
16985 * --indent, ‘msgen’ option: msgen Invocation. (line 76)
16986 * --indent, ‘msgfilter’ option: msgfilter Invocation.
16988 * --indent, ‘msggrep’ option: msggrep Invocation. (line 145)
16989 * --indent, ‘msgmerge’ option: msgmerge Invocation. (line 143)
16990 * --indent, ‘msgunfmt’ option: msgunfmt Invocation. (line 115)
16991 * --indent, ‘msguniq’ option: msguniq Invocation. (line 90)
16992 * --indent, ‘xgettext’ option: xgettext Invocation. (line 359)
16993 * --input, ‘msgexec’ option: msgexec Invocation. (line 50)
16994 * --input, ‘msgfilter’ option: msgfilter Invocation.
16996 * --input, ‘msginit’ option: msginit Invocation. (line 49)
16997 * --intl, ‘gettextize’ option: gettextize Invocation.
16999 * --invert-match, ‘msggrep’ option: msggrep Invocation. (line 114)
17000 * --its, ‘xgettext’ option: xgettext Invocation. (line 391)
17001 * --itstool, ‘xgettext’ option: xgettext Invocation. (line 395)
17002 * --java, ‘msgfmt’ option: msgfmt Invocation. (line 30)
17003 * --java, ‘msgunfmt’ option: msgunfmt Invocation. (line 16)
17004 * --java2, ‘msgfmt’ option: msgfmt Invocation. (line 33)
17005 * --join-existing, ‘xgettext’ option: xgettext Invocation. (line 85)
17006 * --kde, ‘xgettext’ option: xgettext Invocation. (line 322)
17007 * --keep-header, ‘msgfilter’ option: msgfilter Invocation.
17009 * --keyword, ‘msgfmt’ option: msgfmt Invocation. (line 140)
17010 * --keyword, ‘xgettext’ option: xgettext Invocation. (line 171)
17011 * --lang, ‘msgcat’ option: msgcat Invocation. (line 89)
17012 * --lang, ‘msgen’ option: msgen Invocation. (line 57)
17013 * --lang, ‘msgmerge’ option: msgmerge Invocation. (line 123)
17014 * --language, ‘msgfmt’ option: msgfmt Invocation. (line 180)
17015 * --language, ‘xgettext’ option: xgettext Invocation. (line 54)
17016 * --less-than, ‘msgcat’ option: msgcat Invocation. (line 52)
17017 * --less-than, ‘msgcomm’ option: msgcomm Invocation. (line 51)
17018 * --locale, ‘msgfmt’ option: msgfmt Invocation. (line 83)
17019 * --locale, ‘msgfmt’ option <1>: msgfmt Invocation. (line 106)
17020 * --locale, ‘msgfmt’ option <2>: msgfmt Invocation. (line 122)
17021 * --locale, ‘msgfmt’ option <3>: msgfmt Invocation. (line 146)
17022 * --locale, ‘msgfmt’ option <4>: msgfmt Invocation. (line 184)
17023 * --locale, ‘msginit’ option: msginit Invocation. (line 82)
17024 * --locale, ‘msgunfmt’ option: msgunfmt Invocation. (line 45)
17025 * --locale, ‘msgunfmt’ option <1>: msgunfmt Invocation. (line 62)
17026 * --locale, ‘msgunfmt’ option <2>: msgunfmt Invocation. (line 78)
17027 * --location, ‘msggrep’ option: msggrep Invocation. (line 65)
17028 * --more-than, ‘msgcat’ option: msgcat Invocation. (line 57)
17029 * --more-than, ‘msgcomm’ option: msgcomm Invocation. (line 56)
17030 * --msgctxt, ‘msggrep’ option: msggrep Invocation. (line 74)
17031 * --msgid, ‘msggrep’ option: msggrep Invocation. (line 78)
17032 * --msgid-bugs-address, ‘xgettext’ option: xgettext Invocation.
17034 * --msgstr, ‘msggrep’ option: msggrep Invocation. (line 82)
17035 * --msgstr-prefix, ‘xgettext’ option: xgettext Invocation. (line 483)
17036 * --msgstr-suffix, ‘xgettext’ option: xgettext Invocation. (line 487)
17037 * --multi-domain, ‘msgcmp’ option: msgcmp Invocation. (line 35)
17038 * --multi-domain, ‘msgmerge’ option: msgmerge Invocation. (line 96)
17039 * --newline, ‘msgfilter’ option: msgfilter Invocation.
17041 * --newline, ‘msgfilter’ option <1>: msgexec Invocation. (line 19)
17042 * --no-changelog, ‘gettextize’ option: gettextize Invocation.
17044 * --no-fuzzy, ‘msgattrib’ option: msgattrib Invocation.
17046 * --no-fuzzy-matching, ‘msgcmp’ option: msgcmp Invocation. (line 39)
17047 * --no-fuzzy-matching, ‘msgmerge’ option: msgmerge Invocation.
17049 * --no-hash, ‘msgfmt’ option: msgfmt Invocation. (line 304)
17050 * --no-location, ‘msgattrib’ option: msgattrib Invocation.
17052 * --no-location, ‘msgcat’ option: msgcat Invocation. (line 110)
17053 * --no-location, ‘msgcomm’ option: msgcomm Invocation. (line 96)
17054 * --no-location, ‘msgconv’ option: msgconv Invocation. (line 76)
17055 * --no-location, ‘msgen’ option: msgen Invocation. (line 79)
17056 * --no-location, ‘msgfilter’ option: msgfilter Invocation.
17058 * --no-location, ‘msggrep’ option: msggrep Invocation. (line 148)
17059 * --no-location, ‘msgmerge’ option: msgmerge Invocation. (line 146)
17060 * --no-location, ‘msguniq’ option: msguniq Invocation. (line 93)
17061 * --no-location, ‘xgettext’ option: xgettext Invocation. (line 362)
17062 * --no-obsolete, ‘msgattrib’ option: msgattrib Invocation.
17064 * --no-translator, ‘msginit’ option: msginit Invocation. (line 88)
17065 * --no-wrap, ‘msgattrib’ option: msgattrib Invocation.
17067 * --no-wrap, ‘msgcat’ option: msgcat Invocation. (line 145)
17068 * --no-wrap, ‘msgcomm’ option: msgcomm Invocation. (line 131)
17069 * --no-wrap, ‘msgconv’ option: msgconv Invocation. (line 111)
17070 * --no-wrap, ‘msgen’ option: msgen Invocation. (line 114)
17071 * --no-wrap, ‘msgfilter’ option: msgfilter Invocation.
17073 * --no-wrap, ‘msggrep’ option: msggrep Invocation. (line 183)
17074 * --no-wrap, ‘msginit’ option: msginit Invocation. (line 118)
17075 * --no-wrap, ‘msgmerge’ option: msgmerge Invocation. (line 181)
17076 * --no-wrap, ‘msgunfmt’ option: msgunfmt Invocation. (line 140)
17077 * --no-wrap, ‘msguniq’ option: msguniq Invocation. (line 128)
17078 * --no-wrap, ‘xgettext’ option: xgettext Invocation. (line 406)
17079 * --obsolete, ‘msgattrib’ option: msgattrib Invocation.
17081 * --omit-header, ‘msgcomm’ option: msgcomm Invocation. (line 146)
17082 * --omit-header, ‘xgettext’ option: xgettext Invocation. (line 421)
17083 * --only-file, ‘msgattrib’ option: msgattrib Invocation.
17085 * --only-fuzzy, ‘msgattrib’ option: msgattrib Invocation.
17087 * --only-obsolete, ‘msgattrib’ option: msgattrib Invocation.
17089 * --output, ‘xgettext’ option: xgettext Invocation. (line 39)
17090 * --output-dir, ‘xgettext’ option: xgettext Invocation. (line 44)
17091 * --output-file, ‘msgattrib’ option: msgattrib Invocation.
17093 * --output-file, ‘msgcat’ option: msgcat Invocation. (line 42)
17094 * --output-file, ‘msgcomm’ option: msgcomm Invocation. (line 41)
17095 * --output-file, ‘msgconv’ option: msgconv Invocation. (line 30)
17096 * --output-file, ‘msgen’ option: msgen Invocation. (line 36)
17097 * --output-file, ‘msgfilter’ option: msgfilter Invocation.
17099 * --output-file, ‘msgfmt’ option: msgfmt Invocation. (line 59)
17100 * --output-file, ‘msggrep’ option: msggrep Invocation. (line 30)
17101 * --output-file, ‘msginit’ option: msginit Invocation. (line 59)
17102 * --output-file, ‘msgmerge’ option: msgmerge Invocation. (line 51)
17103 * --output-file, ‘msgunfmt’ option: msgunfmt Invocation. (line 93)
17104 * --output-file, ‘msguniq’ option: msguniq Invocation. (line 37)
17105 * --package-name, ‘xgettext’ option: xgettext Invocation. (line 453)
17106 * --package-version, ‘xgettext’ option: xgettext Invocation. (line 456)
17107 * --po-dir, ‘gettextize’ option: gettextize Invocation.
17109 * --previous, ‘msgattrib’ option: msgattrib Invocation.
17111 * --previous, ‘msgmerge’ option: msgmerge Invocation. (line 104)
17112 * --properties-input, ‘msgattrib’ option: msgattrib Invocation.
17114 * --properties-input, ‘msgcat’ option: msgcat Invocation. (line 70)
17115 * --properties-input, ‘msgcmp’ option: msgcmp Invocation. (line 57)
17116 * --properties-input, ‘msgcomm’ option: msgcomm Invocation. (line 69)
17117 * --properties-input, ‘msgconv’ option: msgconv Invocation. (line 49)
17118 * --properties-input, ‘msgen’ option: msgen Invocation. (line 46)
17119 * --properties-input, ‘msgexec’ option: msgexec Invocation. (line 65)
17120 * --properties-input, ‘msgfilter’ option: msgfilter Invocation.
17122 * --properties-input, ‘msgfmt’ option: msgfmt Invocation. (line 214)
17123 * --properties-input, ‘msggrep’ option: msggrep Invocation. (line 122)
17124 * --properties-input, ‘msginit’ option: msginit Invocation. (line 70)
17125 * --properties-input, ‘msgmerge’ option: msgmerge Invocation. (line 112)
17126 * --properties-input, ‘msguniq’ option: msguniq Invocation. (line 58)
17127 * --properties-output, ‘msgattrib’ option: msgattrib Invocation.
17129 * --properties-output, ‘msgcat’ option: msgcat Invocation. (line 129)
17130 * --properties-output, ‘msgcomm’ option: msgcomm Invocation. (line 115)
17131 * --properties-output, ‘msgconv’ option: msgconv Invocation. (line 95)
17132 * --properties-output, ‘msgen’ option: msgen Invocation. (line 98)
17133 * --properties-output, ‘msgfilter’ option: msgfilter Invocation.
17135 * --properties-output, ‘msggrep’ option: msggrep Invocation. (line 167)
17136 * --properties-output, ‘msginit’ option: msginit Invocation. (line 102)
17137 * --properties-output, ‘msgmerge’ option: msgmerge Invocation.
17139 * --properties-output, ‘msgunfmt’ option: msgunfmt Invocation.
17141 * --properties-output, ‘msguniq’ option: msguniq Invocation. (line 112)
17142 * --properties-output, ‘xgettext’ option: xgettext Invocation.
17144 * --qt, ‘msgfmt’ option: msgfmt Invocation. (line 46)
17145 * --qt, ‘xgettext’ option: xgettext Invocation. (line 318)
17146 * --quiet, ‘msgfilter’ option: msgfilter Invocation.
17148 * --quiet, ‘msgmerge’ option: msgmerge Invocation. (line 213)
17149 * --regexp=, ‘msggrep’ option: msggrep Invocation. (line 102)
17150 * --repeated, ‘msguniq’ option: msguniq Invocation. (line 47)
17151 * --resource, ‘msgfmt’ option: msgfmt Invocation. (line 79)
17152 * --resource, ‘msgfmt’ option <1>: msgfmt Invocation. (line 102)
17153 * --resource, ‘msgunfmt’ option: msgunfmt Invocation. (line 41)
17154 * --resource, ‘msgunfmt’ option <1>: msgunfmt Invocation. (line 58)
17155 * --sentence-end, ‘xgettext’ option: xgettext Invocation. (line 149)
17156 * --set-fuzzy, ‘msgattrib’ option: msgattrib Invocation.
17158 * --set-obsolete, ‘msgattrib’ option: msgattrib Invocation.
17160 * --silent, ‘msgfilter’ option: msgfilter Invocation.
17162 * --silent, ‘msgmerge’ option: msgmerge Invocation. (line 213)
17163 * --sort-by-file, ‘msgattrib’ option: msgattrib Invocation.
17165 * --sort-by-file, ‘msgcat’ option: msgcat Invocation. (line 157)
17166 * --sort-by-file, ‘msgcomm’ option: msgcomm Invocation. (line 143)
17167 * --sort-by-file, ‘msgconv’ option: msgconv Invocation. (line 123)
17168 * --sort-by-file, ‘msgen’ option: msgen Invocation. (line 126)
17169 * --sort-by-file, ‘msgfilter’ option: msgfilter Invocation.
17171 * --sort-by-file, ‘msggrep’ option: msggrep Invocation. (line 193)
17172 * --sort-by-file, ‘msgmerge’ option: msgmerge Invocation. (line 193)
17173 * --sort-by-file, ‘msguniq’ option: msguniq Invocation. (line 140)
17174 * --sort-by-file, ‘xgettext’ option: xgettext Invocation. (line 418)
17175 * --sort-output, ‘msgattrib’ option: msgattrib Invocation.
17177 * --sort-output, ‘msgcat’ option: msgcat Invocation. (line 152)
17178 * --sort-output, ‘msgcomm’ option: msgcomm Invocation. (line 138)
17179 * --sort-output, ‘msgconv’ option: msgconv Invocation. (line 118)
17180 * --sort-output, ‘msgen’ option: msgen Invocation. (line 121)
17181 * --sort-output, ‘msgfilter’ option: msgfilter Invocation.
17183 * --sort-output, ‘msggrep’ option: msggrep Invocation. (line 189)
17184 * --sort-output, ‘msgmerge’ option: msgmerge Invocation. (line 188)
17185 * --sort-output, ‘msgunfmt’ option: msgunfmt Invocation. (line 147)
17186 * --sort-output, ‘msguniq’ option: msguniq Invocation. (line 135)
17187 * --sort-output, ‘xgettext’ option: xgettext Invocation. (line 413)
17188 * --source, ‘msgfmt’ option: msgfmt Invocation. (line 91)
17189 * --statistics, ‘msgfmt’ option: msgfmt Invocation. (line 319)
17190 * --strict, ‘msgattrib’ option: msgattrib Invocation.
17192 * --strict, ‘msgcat’ option: msgcat Invocation. (line 123)
17193 * --strict, ‘msgcomm’ option: msgcomm Invocation. (line 109)
17194 * --strict, ‘msgconv’ option: msgconv Invocation. (line 89)
17195 * --strict, ‘msgen’ option: msgen Invocation. (line 92)
17196 * --strict, ‘msgfilter’ option: msgfilter Invocation.
17198 * --strict, ‘msgfmt’ option: msgfmt Invocation. (line 62)
17199 * --strict, ‘msggrep’ option: msggrep Invocation. (line 161)
17200 * --strict, ‘msgmerge’ option: msgmerge Invocation. (line 159)
17201 * --strict, ‘msgunfmt’ option: msgunfmt Invocation. (line 118)
17202 * --strict, ‘msguniq’ option: msguniq Invocation. (line 106)
17203 * --strict, ‘xgettext’ option: xgettext Invocation. (line 377)
17204 * --stringtable-input, ‘msgattrib’ option: msgattrib Invocation.
17206 * --stringtable-input, ‘msgcat’ option: msgcat Invocation. (line 74)
17207 * --stringtable-input, ‘msgcmp’ option: msgcmp Invocation. (line 61)
17208 * --stringtable-input, ‘msgcomm’ option: msgcomm Invocation. (line 73)
17209 * --stringtable-input, ‘msgen’ option: msgen Invocation. (line 50)
17210 * --stringtable-input, ‘msgexec’ option: msgexec Invocation. (line 69)
17211 * --stringtable-input, ‘msgfilter’ option: msgfilter Invocation.
17213 * --stringtable-input, ‘msgfmt’ option: msgfmt Invocation. (line 218)
17214 * --stringtable-input, ‘msggrep’ option: msggrep Invocation. (line 126)
17215 * --stringtable-input, ‘msginit’ option: msginit Invocation. (line 74)
17216 * --stringtable-input, ‘msgmerge’ option: msgmerge Invocation.
17218 * --stringtable-input, ‘msgonv’ option: msgconv Invocation. (line 53)
17219 * --stringtable-input, ‘msguniq’ option: msguniq Invocation. (line 62)
17220 * --stringtable-output, ‘msgattrib’ option: msgattrib Invocation.
17222 * --stringtable-output, ‘msgcat’ option: msgcat Invocation. (line 134)
17223 * --stringtable-output, ‘msgcomm’ option: msgcomm Invocation. (line 120)
17224 * --stringtable-output, ‘msgconv’ option: msgconv Invocation. (line 100)
17225 * --stringtable-output, ‘msgen’ option: msgen Invocation. (line 103)
17226 * --stringtable-output, ‘msgfilter’ option: msgfilter Invocation.
17228 * --stringtable-output, ‘msggrep’ option: msggrep Invocation. (line 172)
17229 * --stringtable-output, ‘msginit’ option: msginit Invocation. (line 107)
17230 * --stringtable-output, ‘msgmerge’ option: msgmerge Invocation.
17232 * --stringtable-output, ‘msgunfmt’ option: msgunfmt Invocation.
17234 * --stringtable-output, ‘msguniq’ option: msguniq Invocation. (line 117)
17235 * --stringtable-output, ‘xgettext’ option: xgettext Invocation.
17237 * --style, ‘msgattrib’ option: msgattrib Invocation.
17239 * --style, ‘msgcat’ option: msgcat Invocation. (line 99)
17240 * --style, ‘msgcat’ option <1>: The --style option. (line 6)
17241 * --style, ‘msgcomm’ option: msgcomm Invocation. (line 85)
17242 * --style, ‘msgconv’ option: msgconv Invocation. (line 65)
17243 * --style, ‘msgen’ option: msgen Invocation. (line 68)
17244 * --style, ‘msgfilter’ option: msgfilter Invocation.
17246 * --style, ‘msggrep’ option: msggrep Invocation. (line 138)
17247 * --style, ‘msginit’ option: msginit Invocation. (line 97)
17248 * --style, ‘msgmerge’ option: msgmerge Invocation. (line 135)
17249 * --style, ‘msgunfmt’ option: msgunfmt Invocation. (line 107)
17250 * --style, ‘msguniq’ option: msguniq Invocation. (line 82)
17251 * --style, ‘xgettext’ option: xgettext Invocation. (line 351)
17252 * --suffix, ‘msgmerge’ option: msgmerge Invocation. (line 65)
17253 * --symlink, ‘gettextize’ option: gettextize Invocation.
17255 * --tcl, ‘msgfmt’ option: msgfmt Invocation. (line 43)
17256 * --tcl, ‘msgunfmt’ option: msgunfmt Invocation. (line 26)
17257 * --template, ‘msgfmt’ option: msgfmt Invocation. (line 136)
17258 * --template, ‘msgfmt’ option <1>: msgfmt Invocation. (line 176)
17259 * --to-code, ‘msgcat’ option: msgcat Invocation. (line 82)
17260 * --to-code, ‘msgconv’ option: msgconv Invocation. (line 40)
17261 * --to-code, ‘msguniq’ option: msguniq Invocation. (line 70)
17262 * --translated, ‘msgattrib’ option: msgattrib Invocation.
17264 * --trigraphs, ‘xgettext’ option: xgettext Invocation. (line 313)
17265 * --unique, ‘msgcat’ option: msgcat Invocation. (line 62)
17266 * --unique, ‘msgcomm’ option: msgcomm Invocation. (line 61)
17267 * --unique, ‘msguniq’ option: msguniq Invocation. (line 51)
17268 * --untranslated, ‘msgattrib’ option: msgattrib Invocation.
17270 * --update, ‘msgmerge’ option: msgmerge Invocation. (line 44)
17271 * --use-first, ‘msgcat’ option: msgcat Invocation. (line 85)
17272 * --use-first, ‘msguniq’ option: msguniq Invocation. (line 73)
17273 * --use-fuzzy, ‘msgcmp’ option: msgcmp Invocation. (line 43)
17274 * --use-fuzzy, ‘msgfmt’ option: msgfmt Invocation. (line 279)
17275 * --use-untranslated, ‘msgcmp’ option: msgcmp Invocation. (line 49)
17276 * --variables, ‘envsubst’ option: envsubst Invocation. (line 15)
17277 * --verbose, ‘msgfmt’ option: msgfmt Invocation. (line 325)
17278 * --verbose, ‘msgmerge’ option: msgmerge Invocation. (line 208)
17279 * --verbose, ‘msgunfmt’ option: msgunfmt Invocation. (line 163)
17280 * --version, ‘autopoint’ option: autopoint Invocation.
17282 * --version, ‘envsubst’ option: envsubst Invocation. (line 25)
17283 * --version, ‘gettext’ option: gettext Invocation. (line 40)
17284 * --version, ‘gettextize’ option: gettextize Invocation.
17286 * --version, ‘msgattrib’ option: msgattrib Invocation.
17288 * --version, ‘msgcat’ option: msgcat Invocation. (line 168)
17289 * --version, ‘msgcmp’ option: msgcmp Invocation. (line 73)
17290 * --version, ‘msgcomm’ option: msgcomm Invocation. (line 157)
17291 * --version, ‘msgconv’ option: msgconv Invocation. (line 134)
17292 * --version, ‘msgen’ option: msgen Invocation. (line 137)
17293 * --version, ‘msgexec’ option: msgexec Invocation. (line 81)
17294 * --version, ‘msgfilter’ option: msgfilter Invocation.
17296 * --version, ‘msgfmt’ option: msgfmt Invocation. (line 316)
17297 * --version, ‘msggrep’ option: msggrep Invocation. (line 204)
17298 * --version, ‘msginit’ option: msginit Invocation. (line 132)
17299 * --version, ‘msgmerge’ option: msgmerge Invocation. (line 204)
17300 * --version, ‘msgunfmt’ option: msgunfmt Invocation. (line 159)
17301 * --version, ‘msguniq’ option: msguniq Invocation. (line 151)
17302 * --version, ‘ngettext’ option: ngettext Invocation. (line 35)
17303 * --version, ‘xgettext’ option: xgettext Invocation. (line 498)
17304 * --width, ‘msgattrib’ option: msgattrib Invocation.
17306 * --width, ‘msgcat’ option: msgcat Invocation. (line 139)
17307 * --width, ‘msgcomm’ option: msgcomm Invocation. (line 125)
17308 * --width, ‘msgconv’ option: msgconv Invocation. (line 105)
17309 * --width, ‘msgen’ option: msgen Invocation. (line 108)
17310 * --width, ‘msgfilter’ option: msgfilter Invocation.
17312 * --width, ‘msggrep’ option: msggrep Invocation. (line 177)
17313 * --width, ‘msginit’ option: msginit Invocation. (line 112)
17314 * --width, ‘msgmerge’ option: msgmerge Invocation. (line 175)
17315 * --width, ‘msgunfmt’ option: msgunfmt Invocation. (line 134)
17316 * --width, ‘msguniq’ option: msguniq Invocation. (line 122)
17317 * --width, ‘xgettext’ option: xgettext Invocation. (line 400)
17318 * --xml, ‘msgfmt’ option: msgfmt Invocation. (line 52)
17319 * -<, ‘msgcat’ option: msgcat Invocation. (line 52)
17320 * -<, ‘msgcomm’ option: msgcomm Invocation. (line 51)
17321 * ->, ‘msgcat’ option: msgcat Invocation. (line 57)
17322 * ->, ‘msgcomm’ option: msgcomm Invocation. (line 56)
17323 * -a, ‘msgfmt’ option: msgfmt Invocation. (line 288)
17324 * -a, ‘xgettext’ option: xgettext Invocation. (line 162)
17325 * -c, ‘msgfmt’ option: msgfmt Invocation. (line 226)
17326 * -C, ‘msgfmt’ option: msgfmt Invocation. (line 263)
17327 * -C, ‘msggrep’ option: msggrep Invocation. (line 86)
17328 * -C, ‘msgmerge’ option: msgmerge Invocation. (line 36)
17329 * -C, ‘xgettext’ option: xgettext Invocation. (line 63)
17330 * -c, ‘xgettext’ option: xgettext Invocation. (line 94)
17331 * -d, ‘autopoint’ option: autopoint Invocation.
17333 * -d, ‘gettext’ option: gettext Invocation. (line 16)
17334 * -d, ‘gettextize’ option: gettextize Invocation.
17336 * -D, ‘msgattrib’ option: msgattrib Invocation.
17338 * -D, ‘msgcat’ option: msgcat Invocation. (line 31)
17339 * -D, ‘msgcmp’ option: msgcmp Invocation. (line 27)
17340 * -D, ‘msgcomm’ option: msgcomm Invocation. (line 30)
17341 * -D, ‘msgconv’ option: msgconv Invocation. (line 19)
17342 * -D, ‘msgen’ option: msgen Invocation. (line 25)
17343 * -D, ‘msgexec’ option: msgexec Invocation. (line 54)
17344 * -D, ‘msgfilter’ option: msgfilter Invocation.
17346 * -D, ‘msgfmt’ option: msgfmt Invocation. (line 18)
17347 * -d, ‘msgfmt’ option: msgfmt Invocation. (line 88)
17348 * -d, ‘msgfmt’ option <1>: msgfmt Invocation. (line 111)
17349 * -d, ‘msgfmt’ option <2>: msgfmt Invocation. (line 127)
17350 * -d, ‘msgfmt’ option <3>: msgfmt Invocation. (line 151)
17351 * -d, ‘msgfmt’ option <4>: msgfmt Invocation. (line 189)
17352 * -D, ‘msggrep’ option: msggrep Invocation. (line 19)
17353 * -D, ‘msgmerge’ option: msgmerge Invocation. (line 30)
17354 * -d, ‘msgunfmt’ option: msgunfmt Invocation. (line 67)
17355 * -d, ‘msgunfmt’ option <1>: msgunfmt Invocation. (line 83)
17356 * -D, ‘msguniq’ option: msguniq Invocation. (line 26)
17357 * -d, ‘msguniq’ option: msguniq Invocation. (line 47)
17358 * -d, ‘ngettext’ option: ngettext Invocation. (line 15)
17359 * -D, ‘xgettext’ option: xgettext Invocation. (line 24)
17360 * -d, ‘xgettext’ option: xgettext Invocation. (line 35)
17361 * -e, ‘gettext’ option: gettext Invocation. (line 20)
17362 * -E, ‘gettext’ option: gettext Invocation. (line 27)
17363 * -e, ‘msgfilter’ option: msgfilter Invocation.
17365 * -E, ‘msggrep’ option: msggrep Invocation. (line 94)
17366 * -e, ‘msggrep’ option: msggrep Invocation. (line 102)
17367 * -e, ‘ngettext’ option: ngettext Invocation. (line 19)
17368 * -E, ‘ngettext’ option: ngettext Invocation. (line 26)
17369 * -f, ‘autopoint’ option: autopoint Invocation.
17371 * -f, ‘gettextize’ option: gettextize Invocation.
17373 * -F, ‘msgattrib’ option: msgattrib Invocation.
17375 * -f, ‘msgcat’ option: msgcat Invocation. (line 26)
17376 * -F, ‘msgcat’ option: msgcat Invocation. (line 157)
17377 * -f, ‘msgcomm’ option: msgcomm Invocation. (line 25)
17378 * -F, ‘msgcomm’ option: msgcomm Invocation. (line 143)
17379 * -F, ‘msgconv’ option: msgconv Invocation. (line 123)
17380 * -F, ‘msgen’ option: msgen Invocation. (line 126)
17381 * -f, ‘msgfilter’ option: msgfilter Invocation.
17383 * -F, ‘msgfilter’ option: msgfilter Invocation.
17385 * -f, ‘msgfmt’ option: msgfmt Invocation. (line 279)
17386 * -F, ‘msggrep’ option: msggrep Invocation. (line 98)
17387 * -f, ‘msggrep’ option: msggrep Invocation. (line 106)
17388 * -F, ‘msgmerge’ option: msgmerge Invocation. (line 193)
17389 * -F, ‘msguniq’ option: msguniq Invocation. (line 140)
17390 * -f, ‘xgettext’ option: xgettext Invocation. (line 19)
17391 * -F, ‘xgettext’ option: xgettext Invocation. (line 418)
17392 * -h, ‘envsubst’ option: envsubst Invocation. (line 21)
17393 * -h, ‘gettext’ option: gettext Invocation. (line 32)
17394 * -h, ‘msgattrib’ option: msgattrib Invocation.
17396 * -h, ‘msgcat’ option: msgcat Invocation. (line 164)
17397 * -h, ‘msgcmp’ option: msgcmp Invocation. (line 69)
17398 * -h, ‘msgcomm’ option: msgcomm Invocation. (line 153)
17399 * -h, ‘msgconv’ option: msgconv Invocation. (line 130)
17400 * -h, ‘msgen’ option: msgen Invocation. (line 133)
17401 * -h, ‘msgexec’ option: msgexec Invocation. (line 77)
17402 * -h, ‘msgfilter’ option: msgfilter Invocation.
17404 * -h, ‘msgfmt’ option: msgfmt Invocation. (line 312)
17405 * -h, ‘msggrep’ option: msggrep Invocation. (line 200)
17406 * -h, ‘msginit’ option: msginit Invocation. (line 128)
17407 * -h, ‘msgmerge’ option: msgmerge Invocation. (line 200)
17408 * -h, ‘msgunfmt’ option: msgunfmt Invocation. (line 155)
17409 * -h, ‘msguniq’ option: msguniq Invocation. (line 147)
17410 * -h, ‘ngettext’ option: ngettext Invocation. (line 31)
17411 * -h, ‘xgettext’ option: xgettext Invocation. (line 494)
17412 * -i, ‘msgattrib’ option: msgattrib Invocation.
17414 * -i, ‘msgcat’ option: msgcat Invocation. (line 107)
17415 * -i, ‘msgcomm’ option: msgcomm Invocation. (line 93)
17416 * -i, ‘msgconv’ option: msgconv Invocation. (line 73)
17417 * -i, ‘msgen’ option: msgen Invocation. (line 76)
17418 * -i, ‘msgexec’ option: msgexec Invocation. (line 50)
17419 * -i, ‘msgfilter’ option: msgfilter Invocation.
17421 * -i, ‘msggrep’ option: msggrep Invocation. (line 110)
17422 * -i, ‘msginit’ option: msginit Invocation. (line 49)
17423 * -i, ‘msgmerge’ option: msgmerge Invocation. (line 143)
17424 * -i, ‘msgunfmt’ option: msgunfmt Invocation. (line 115)
17425 * -i, ‘msguniq’ option: msguniq Invocation. (line 90)
17426 * -i, ‘xgettext’ option: xgettext Invocation. (line 359)
17427 * -j, ‘msgfmt’ option: msgfmt Invocation. (line 30)
17428 * -J, ‘msggrep’ option: msggrep Invocation. (line 74)
17429 * -j, ‘msgunfmt’ option: msgunfmt Invocation. (line 16)
17430 * -j, ‘xgettext’ option: xgettext Invocation. (line 85)
17431 * -k, ‘msgfmt’ option: msgfmt Invocation. (line 140)
17432 * -K, ‘msggrep’ option: msggrep Invocation. (line 78)
17433 * -k, ‘xgettext’ option: xgettext Invocation. (line 171)
17434 * -l, ‘msgfmt’ option: msgfmt Invocation. (line 83)
17435 * -l, ‘msgfmt’ option <1>: msgfmt Invocation. (line 106)
17436 * -l, ‘msgfmt’ option <2>: msgfmt Invocation. (line 122)
17437 * -l, ‘msgfmt’ option <3>: msgfmt Invocation. (line 146)
17438 * -L, ‘msgfmt’ option: msgfmt Invocation. (line 180)
17439 * -l, ‘msgfmt’ option <4>: msgfmt Invocation. (line 184)
17440 * -l, ‘msginit’ option: msginit Invocation. (line 82)
17441 * -l, ‘msgunfmt’ option: msgunfmt Invocation. (line 45)
17442 * -l, ‘msgunfmt’ option <1>: msgunfmt Invocation. (line 62)
17443 * -l, ‘msgunfmt’ option <2>: msgunfmt Invocation. (line 78)
17444 * -L, ‘xgettext’ option: xgettext Invocation. (line 54)
17445 * -m, ‘msgcmp’ option: msgcmp Invocation. (line 35)
17446 * -M, ‘msggrep’ option: msggrep Invocation. (line 70)
17447 * -m, ‘msgmerge’ option: msgmerge Invocation. (line 96)
17448 * -m, ‘xgettext’ option: xgettext Invocation. (line 483)
17449 * -M, ‘xgettext’ option: xgettext Invocation. (line 487)
17450 * -n, ‘gettext’ option: gettext Invocation. (line 35)
17451 * -n, ‘msgattrib’ option: msgattrib Invocation.
17453 * -n, ‘msgcat’ option: msgcat Invocation. (line 114)
17454 * -N, ‘msgcmp’ option: msgcmp Invocation. (line 39)
17455 * -n, ‘msgcomm’ option: msgcomm Invocation. (line 100)
17456 * -n, ‘msgfilter’ option: msgfilter Invocation.
17458 * -N, ‘msggrep’ option: msggrep Invocation. (line 65)
17459 * -N, ‘msgmerge’ option: msgmerge Invocation. (line 100)
17460 * -n, ‘msguniq’ option: msguniq Invocation. (line 97)
17461 * -n, ‘xgettext’ option: xgettext Invocation. (line 368)
17462 * -o, ‘msgattrib’ option: msgattrib Invocation.
17464 * -o, ‘msgcat’ option: msgcat Invocation. (line 42)
17465 * -o, ‘msgcomm’ option: msgcomm Invocation. (line 41)
17466 * -o, ‘msgconv’ option: msgconv Invocation. (line 30)
17467 * -o, ‘msgen’ option: msgen Invocation. (line 36)
17468 * -o, ‘msgfilter’ option: msgfilter Invocation.
17470 * -o, ‘msgfmt’ option: msgfmt Invocation. (line 59)
17471 * -o, ‘msggrep’ option: msggrep Invocation. (line 30)
17472 * -o, ‘msginit’ option: msginit Invocation. (line 59)
17473 * -o, ‘msgmerge’ option: msgmerge Invocation. (line 51)
17474 * -o, ‘msgunfmt’ option: msgunfmt Invocation. (line 93)
17475 * -o, ‘msguniq’ option: msguniq Invocation. (line 37)
17476 * -o, ‘xgettext’ option: xgettext Invocation. (line 39)
17477 * -P, ‘msgattrib’ option: msgattrib Invocation.
17479 * -p, ‘msgattrib’ option: msgattrib Invocation.
17481 * -P, ‘msgcat’ option: msgcat Invocation. (line 70)
17482 * -p, ‘msgcat’ option: msgcat Invocation. (line 129)
17483 * -P, ‘msgcmp’ option: msgcmp Invocation. (line 57)
17484 * -P, ‘msgcomm’ option: msgcomm Invocation. (line 69)
17485 * -p, ‘msgcomm’ option: msgcomm Invocation. (line 115)
17486 * -P, ‘msgconv’ option: msgconv Invocation. (line 49)
17487 * -p, ‘msgconv’ option: msgconv Invocation. (line 95)
17488 * -P, ‘msgen’ option: msgen Invocation. (line 46)
17489 * -p, ‘msgen’ option: msgen Invocation. (line 98)
17490 * -P, ‘msgexec’ option: msgexec Invocation. (line 65)
17491 * -P, ‘msgfilter’ option: msgfilter Invocation.
17493 * -p, ‘msgfilter’ option: msgfilter Invocation.
17495 * -P, ‘msgfmt’ option: msgfmt Invocation. (line 214)
17496 * -P, ‘msggrep’ option: msggrep Invocation. (line 122)
17497 * -p, ‘msggrep’ option: msggrep Invocation. (line 167)
17498 * -P, ‘msginit’ option: msginit Invocation. (line 70)
17499 * -p, ‘msginit’ option: msginit Invocation. (line 102)
17500 * -P, ‘msgmerge’ option: msgmerge Invocation. (line 112)
17501 * -p, ‘msgmerge’ option: msgmerge Invocation. (line 165)
17502 * -p, ‘msgunfmt’ option: msgunfmt Invocation. (line 124)
17503 * -P, ‘msguniq’ option: msguniq Invocation. (line 58)
17504 * -p, ‘msguniq’ option: msguniq Invocation. (line 112)
17505 * -p, ‘xgettext’ option: xgettext Invocation. (line 44)
17506 * -q, ‘msgmerge’ option: msgmerge Invocation. (line 213)
17507 * -r, ‘msgfmt’ option: msgfmt Invocation. (line 79)
17508 * -r, ‘msgfmt’ option <1>: msgfmt Invocation. (line 102)
17509 * -r, ‘msgunfmt’ option: msgunfmt Invocation. (line 41)
17510 * -r, ‘msgunfmt’ option <1>: msgunfmt Invocation. (line 58)
17511 * -s, ‘msgattrib’ option: msgattrib Invocation.
17513 * -s, ‘msgcat’ option: msgcat Invocation. (line 152)
17514 * -s, ‘msgcomm’ option: msgcomm Invocation. (line 138)
17515 * -s, ‘msgconv’ option: msgconv Invocation. (line 118)
17516 * -s, ‘msgen’ option: msgen Invocation. (line 121)
17517 * -s, ‘msgfilter’ option: msgfilter Invocation.
17519 * -s, ‘msgmerge’ option: msgmerge Invocation. (line 188)
17520 * -s, ‘msgunfmt’ option: msgunfmt Invocation. (line 147)
17521 * -s, ‘msguniq’ option: msguniq Invocation. (line 135)
17522 * -s, ‘xgettext’ option: xgettext Invocation. (line 413)
17523 * -t, ‘msgcat’ option: msgcat Invocation. (line 82)
17524 * -t, ‘msgconv’ option: msgconv Invocation. (line 40)
17525 * -T, ‘msggrep’ option: msggrep Invocation. (line 82)
17526 * -t, ‘msguniq’ option: msguniq Invocation. (line 70)
17527 * -T, ‘xgettext’ option: xgettext Invocation. (line 313)
17528 * -u, ‘msgcat’ option: msgcat Invocation. (line 62)
17529 * -u, ‘msgcomm’ option: msgcomm Invocation. (line 61)
17530 * -U, ‘msgmerge’ option: msgmerge Invocation. (line 44)
17531 * -u, ‘msguniq’ option: msguniq Invocation. (line 51)
17532 * -v, ‘envsubst’ option: envsubst Invocation. (line 15)
17533 * -V, ‘envsubst’ option: envsubst Invocation. (line 25)
17534 * -V, ‘gettext’ option: gettext Invocation. (line 40)
17535 * -V, ‘msgattrib’ option: msgattrib Invocation.
17537 * -V, ‘msgcat’ option: msgcat Invocation. (line 168)
17538 * -V, ‘msgcmp’ option: msgcmp Invocation. (line 73)
17539 * -V, ‘msgcomm’ option: msgcomm Invocation. (line 157)
17540 * -V, ‘msgconv’ option: msgconv Invocation. (line 134)
17541 * -V, ‘msgen’ option: msgen Invocation. (line 137)
17542 * -V, ‘msgexec’ option: msgexec Invocation. (line 81)
17543 * -V, ‘msgfilter’ option: msgfilter Invocation.
17545 * -V, ‘msgfmt’ option: msgfmt Invocation. (line 316)
17546 * -v, ‘msgfmt’ option: msgfmt Invocation. (line 325)
17547 * -v, ‘msggrep’ option: msggrep Invocation. (line 114)
17548 * -V, ‘msggrep’ option: msggrep Invocation. (line 204)
17549 * -V, ‘msginit’ option: msginit Invocation. (line 132)
17550 * -V, ‘msgmerge’ option: msgmerge Invocation. (line 204)
17551 * -v, ‘msgmerge’ option: msgmerge Invocation. (line 208)
17552 * -V, ‘msgunfmt’ option: msgunfmt Invocation. (line 159)
17553 * -v, ‘msgunfmt’ option: msgunfmt Invocation. (line 163)
17554 * -V, ‘msguniq’ option: msguniq Invocation. (line 151)
17555 * -V, ‘ngettext’ option: ngettext Invocation. (line 35)
17556 * -V, ‘xgettext’ option: xgettext Invocation. (line 498)
17557 * -w, ‘msgattrib’ option: msgattrib Invocation.
17559 * -w, ‘msgcat’ option: msgcat Invocation. (line 139)
17560 * -w, ‘msgcomm’ option: msgcomm Invocation. (line 125)
17561 * -w, ‘msgconv’ option: msgconv Invocation. (line 105)
17562 * -w, ‘msgen’ option: msgen Invocation. (line 108)
17563 * -w, ‘msgfilter’ option: msgfilter Invocation.
17565 * -w, ‘msggrep’ option: msggrep Invocation. (line 177)
17566 * -w, ‘msginit’ option: msginit Invocation. (line 112)
17567 * -w, ‘msgmerge’ option: msgmerge Invocation. (line 175)
17568 * -w, ‘msgunfmt’ option: msgunfmt Invocation. (line 134)
17569 * -w, ‘msguniq’ option: msguniq Invocation. (line 122)
17570 * -w, ‘xgettext’ option: xgettext Invocation. (line 400)
17571 * -X, ‘msggrep’ option: msggrep Invocation. (line 90)
17572 * -x, ‘xgettext’ option: xgettext Invocation. (line 89)
17575 File: gettext.info, Node: Variable Index, Next: PO Mode Index, Prev: Option Index, Up: Top
17583 * GETTEXT_LOG_UNTRANSLATED, environment variable: Prioritizing messages.
17585 * LANG, environment variable: Locale Environment Variables.
17587 * LANG, environment variable <1>: gettext grok. (line 30)
17588 * LANGUAGE, environment variable: Locale Environment Variables.
17590 * LANGUAGE, environment variable <1>: gettext grok. (line 28)
17591 * LANGUAGE, environment variable <2>: po/Rules-*. (line 11)
17592 * LC_ALL, environment variable: Locale Environment Variables.
17594 * LC_ALL, environment variable <1>: gettext grok. (line 28)
17595 * LC_COLLATE, environment variable: Locale Environment Variables.
17597 * LC_COLLATE, environment variable <1>: gettext grok. (line 29)
17598 * LC_CTYPE, environment variable: Locale Environment Variables.
17600 * LC_CTYPE, environment variable <1>: gettext grok. (line 29)
17601 * LC_MESSAGES, environment variable: Locale Environment Variables.
17603 * LC_MESSAGES, environment variable <1>: gettext grok. (line 29)
17604 * LC_MONETARY, environment variable: Locale Environment Variables.
17606 * LC_MONETARY, environment variable <1>: gettext grok. (line 29)
17607 * LC_NUMERIC, environment variable: Locale Environment Variables.
17609 * LC_NUMERIC, environment variable <1>: gettext grok. (line 29)
17610 * LC_TIME, environment variable: Locale Environment Variables.
17612 * LC_TIME, environment variable <1>: gettext grok. (line 29)
17613 * LINGUAS, environment variable: Installers. (line 17)
17614 * MSGEXEC_LOCATION, environment variable: msgexec Invocation. (line 21)
17615 * MSGEXEC_MSGCTXT, environment variable: msgexec Invocation. (line 21)
17616 * MSGEXEC_MSGID, environment variable: msgexec Invocation. (line 21)
17617 * MSGEXEC_MSGID_PLURAL, environment variable: msgexec Invocation.
17619 * MSGEXEC_PLURAL_FORM, environment variable: msgexec Invocation.
17621 * MSGEXEC_PREV_MSGCTXT, environment variable: msgexec Invocation.
17623 * MSGEXEC_PREV_MSGID, environment variable: msgexec Invocation.
17625 * MSGEXEC_PREV_MSGID_PLURAL, environment variable: msgexec Invocation.
17627 * MSGFILTER_LOCATION, environment variable: msgfilter Invocation.
17629 * MSGFILTER_MSGCTXT, environment variable: msgfilter Invocation.
17631 * MSGFILTER_MSGID, environment variable: msgfilter Invocation. (line 11)
17632 * MSGFILTER_MSGID_PLURAL, environment variable: msgfilter Invocation.
17634 * MSGFILTER_PLURAL_FORM, environment variable: msgfilter Invocation.
17636 * MSGFILTER_PREV_MSGCTXT, environment variable: msgfilter Invocation.
17638 * MSGFILTER_PREV_MSGID, environment variable: msgfilter Invocation.
17640 * MSGFILTER_PREV_MSGID_PLURAL, environment variable: msgfilter Invocation.
17642 * PO_STYLE, environment variable: The --style option. (line 10)
17643 * TERM, environment variable: The TERM variable. (line 6)
17644 * TEXTDOMAIN, environment variable: sh. (line 23)
17645 * TEXTDOMAINDIR, environment variable: sh. (line 26)
17648 File: gettext.info, Node: PO Mode Index, Next: Autoconf Macro Index, Prev: Variable Index, Up: Top
17656 * #, PO Mode command: Modifying Comments. (line 24)
17657 * #, PO Mode command <1>: Modifying Comments. (line 45)
17658 * ,, PO Mode command: Marking. (line 43)
17659 * ., PO Mode command: Entry Positioning. (line 20)
17660 * ., PO Mode command <1>: Entry Positioning. (line 45)
17661 * ‘.emacs’ customizations: Installation. (line 13)
17662 * 0, PO Mode command: Main PO Commands. (line 40)
17663 * 0, PO Mode command <1>: Main PO Commands. (line 72)
17664 * <, PO Mode command: Entry Positioning. (line 29)
17665 * <, PO Mode command <1>: Entry Positioning. (line 73)
17666 * =, PO Mode command: Main PO Commands. (line 47)
17667 * =, PO Mode command <1>: Main PO Commands. (line 87)
17668 * >, PO Mode command: Entry Positioning. (line 32)
17669 * >, PO Mode command <1>: Entry Positioning. (line 73)
17670 * ?, PO Mode command: Main PO Commands. (line 44)
17671 * ?, PO Mode command <1>: Main PO Commands. (line 83)
17672 * _, PO Mode command: Main PO Commands. (line 30)
17673 * _, PO Mode command <1>: Main PO Commands. (line 52)
17674 * a, PO Mode command: Auxiliary. (line 21)
17675 * A, PO Mode command: Auxiliary. (line 28)
17676 * A, PO Mode command <1>: Auxiliary. (line 35)
17677 * a, PO Mode command <1>: Auxiliary. (line 39)
17678 * auxiliary PO file: Auxiliary. (line 13)
17679 * C-c C-a, PO Mode command: Subedit. (line 17)
17680 * C-c C-a, PO Mode command <1>: Subedit. (line 36)
17681 * C-c C-a, PO Mode command <2>: Auxiliary. (line 25)
17682 * C-c C-a, PO Mode command <3>: Auxiliary. (line 48)
17683 * C-c C-c, PO Mode command: Subedit. (line 11)
17684 * C-c C-c, PO Mode command <1>: Subedit. (line 19)
17685 * C-c C-k, PO Mode command: Subedit. (line 14)
17686 * C-c C-k, PO Mode command <1>: Subedit. (line 27)
17687 * C-j, PO Mode command: Modifying Translations.
17689 * C-j, PO Mode command <1>: Modifying Translations.
17691 * commands: Main PO Commands. (line 6)
17692 * comment out PO file entry: Obsolete Entries. (line 46)
17693 * consulting program sources: C Sources Context. (line 6)
17694 * consulting translations to other languages: Auxiliary. (line 6)
17695 * current entry of a PO file: Entry Positioning. (line 6)
17696 * cut and paste for translated strings: Modifying Translations.
17698 * DEL, PO Mode command: Fuzzy Entries. (line 58)
17699 * DEL, PO Mode command <1>: Obsolete Entries. (line 32)
17700 * DEL, PO Mode command <2>: Obsolete Entries. (line 46)
17701 * editing comments: Modifying Comments. (line 6)
17702 * editing multiple entries: Subedit. (line 64)
17703 * editing translations: Modifying Translations.
17705 * ‘etags’, using for marking strings: Marking. (line 17)
17706 * exiting PO subedit: Subedit. (line 19)
17707 * f, PO Mode command: Fuzzy Entries. (line 29)
17708 * F, PO Mode command: Fuzzy Entries. (line 32)
17709 * f, PO Mode command <1>: Fuzzy Entries. (line 37)
17710 * F, PO Mode command <1>: Fuzzy Entries. (line 37)
17711 * find source fragment for a PO file entry: C Sources Context.
17713 * h, PO Mode command: Main PO Commands. (line 44)
17714 * h, PO Mode command <1>: Main PO Commands. (line 83)
17715 * installing PO mode: Installation. (line 13)
17716 * k, PO Mode command: Untranslated Entries.
17718 * k, PO Mode command <1>: Untranslated Entries.
17720 * k, PO Mode command <2>: Modifying Translations.
17722 * k, PO Mode command <3>: Modifying Translations.
17724 * K, PO Mode command: Modifying Comments. (line 27)
17725 * K, PO Mode command <1>: Modifying Comments. (line 60)
17726 * LFD, PO Mode command: Modifying Translations.
17728 * LFD, PO Mode command <1>: Modifying Translations.
17730 * looking at the source to aid translation: C Sources Context.
17732 * m, PO Mode command: Entry Positioning. (line 35)
17733 * m, PO Mode command <1>: Entry Positioning. (line 91)
17734 * M-,, PO Mode command: Marking. (line 47)
17735 * M-., PO Mode command: Marking. (line 50)
17736 * M-A, PO Mode command: Auxiliary. (line 32)
17737 * M-A, PO Mode command <1>: Auxiliary. (line 35)
17738 * M-s, PO Mode command: C Sources Context. (line 41)
17739 * M-S, PO Mode command: C Sources Context. (line 49)
17740 * M-s, PO Mode command <1>: C Sources Context. (line 52)
17741 * M-S, PO Mode command <1>: C Sources Context. (line 88)
17742 * marking strings for translation: Marking. (line 6)
17743 * moving by fuzzy entries: Fuzzy Entries. (line 23)
17744 * moving by obsolete entries: Obsolete Entries. (line 22)
17745 * moving by translated entries: Translated Entries. (line 12)
17746 * moving by untranslated entries: Untranslated Entries.
17748 * moving through a PO file: Entry Positioning. (line 14)
17749 * n, PO Mode command: Entry Positioning. (line 23)
17750 * n, PO Mode command <1>: Entry Positioning. (line 68)
17751 * next-error, stepping through PO file validation results: Main PO Commands.
17753 * normalize, PO Mode command: Auxiliary. (line 63)
17754 * o, PO Mode command: Obsolete Entries. (line 26)
17755 * O, PO Mode command: Obsolete Entries. (line 29)
17756 * o, PO Mode command <1>: Obsolete Entries. (line 35)
17757 * O, PO Mode command <1>: Obsolete Entries. (line 35)
17758 * obsolete active entry: Obsolete Entries. (line 46)
17759 * p, PO Mode command: Entry Positioning. (line 26)
17760 * p, PO Mode command <1>: Entry Positioning. (line 68)
17761 * pending subedits: Subedit. (line 75)
17762 * po-auto-edit-with-msgid, PO Mode variable: Modifying Translations.
17764 * po-auto-fuzzy-on-edit, PO Mode variable: Translated Entries.
17766 * po-auto-select-on-unfuzzy, PO Mode variable: Fuzzy Entries. (line 42)
17767 * po-confirm-and-quit, PO Mode command: Main PO Commands. (line 61)
17768 * po-consider-as-auxiliary, PO Mode command: Auxiliary. (line 35)
17769 * po-consider-source-path, PO Mode command: C Sources Context.
17771 * po-current-entry, PO Mode command: Entry Positioning. (line 45)
17772 * po-cycle-auxiliary, PO Mode command: Auxiliary. (line 39)
17773 * po-cycle-source-reference, PO Mode command: C Sources Context.
17775 * po-edit-comment, PO Mode command: Modifying Comments. (line 45)
17776 * po-edit-msgstr, PO Mode command: Modifying Translations.
17778 * po-exchange-location, PO Mode command: Entry Positioning. (line 105)
17779 * po-fade-out-entry, PO Mode command: Fuzzy Entries. (line 58)
17780 * po-fade-out-entry, PO Mode command <1>: Obsolete Entries. (line 46)
17781 * po-first-entry, PO Mode command: Entry Positioning. (line 73)
17782 * po-help, PO Mode command: Main PO Commands. (line 83)
17783 * po-ignore-as-auxiliary, PO Mode command: Auxiliary. (line 35)
17784 * po-ignore-source-path, PO Mode command: C Sources Context. (line 88)
17785 * po-kill-comment, PO Mode command: Modifying Comments. (line 60)
17786 * po-kill-msgstr, PO Mode command: Untranslated Entries.
17788 * po-kill-msgstr, PO Mode command <1>: Modifying Translations.
17790 * po-kill-ring-save-comment, PO Mode command: Modifying Comments.
17792 * po-kill-ring-save-msgstr, PO Mode command: Modifying Translations.
17794 * po-last-entry, PO Mode command: Entry Positioning. (line 73)
17795 * po-mark-translatable, PO Mode command: Marking. (line 98)
17796 * po-msgid-to-msgstr, PO Mode command: Modifying Translations.
17798 * po-next-entry, PO Mode command: Entry Positioning. (line 68)
17799 * po-next-fuzzy-entry, PO Mode command: Fuzzy Entries. (line 37)
17800 * po-next-obsolete-entry, PO Mode command: Obsolete Entries. (line 35)
17801 * po-next-translated-entry, PO Mode command: Translated Entries.
17803 * po-next-untranslated-entry, PO Mode command: Untranslated Entries.
17805 * po-normalize, PO Mode command: Normalizing. (line 31)
17806 * po-other-window, PO Mode command: Main PO Commands. (line 72)
17807 * po-pop-location, PO Mode command: Entry Positioning. (line 91)
17808 * po-previous-entry, PO Mode command: Entry Positioning. (line 68)
17809 * po-previous-fuzzy-entry, PO Mode command: Fuzzy Entries. (line 37)
17810 * po-previous-obsolete-entry, PO Mode command: Obsolete Entries.
17812 * po-previous-translated-entry, PO Mode command: Translated Entries.
17814 * po-previous-untransted-entry, PO Mode command: Untranslated Entries.
17816 * po-push-location, PO Mode command: Entry Positioning. (line 91)
17817 * po-quit, PO Mode command: Main PO Commands. (line 61)
17818 * po-select-auxiliary, PO Mode command: Auxiliary. (line 48)
17819 * po-select-mark-and-mark, PO Mode command: Marking. (line 98)
17820 * po-select-source-reference, PO Mode command: C Sources Context.
17822 * po-statistics, PO Mode command: Main PO Commands. (line 87)
17823 * po-subedit-abort, PO Mode command: Subedit. (line 27)
17824 * po-subedit-cycle-auxiliary, PO Mode command: Subedit. (line 36)
17825 * po-subedit-exit, PO Mode command: Subedit. (line 19)
17826 * po-subedit-mode-hook, PO Mode variable: Modifying Comments. (line 57)
17827 * po-tags-search, PO Mode command: Marking. (line 54)
17828 * po-undo, PO Mode command: Main PO Commands. (line 52)
17829 * po-unfuzzy, PO Mode command: Fuzzy Entries. (line 42)
17830 * po-validate, PO Mode command: Main PO Commands. (line 92)
17831 * po-yank-comment, PO Mode command: Modifying Comments. (line 60)
17832 * po-yank-msgstr, PO Mode command: Modifying Translations.
17834 * Q, PO Mode command: Main PO Commands. (line 33)
17835 * q, PO Mode command: Main PO Commands. (line 36)
17836 * Q, PO Mode command <1>: Main PO Commands. (line 61)
17837 * q, PO Mode command <1>: Main PO Commands. (line 61)
17838 * r, PO Mode command: Entry Positioning. (line 39)
17839 * r, PO Mode command <1>: Entry Positioning. (line 91)
17840 * RET, PO Mode command: Modifying Translations.
17842 * RET, PO Mode command <1>: Modifying Translations.
17844 * s, PO Mode command: C Sources Context. (line 37)
17845 * S, PO Mode command: C Sources Context. (line 45)
17846 * s, PO Mode command <1>: C Sources Context. (line 52)
17847 * S, PO Mode command <1>: C Sources Context. (line 88)
17848 * starting a string translation: Modifying Translations.
17850 * string normalization in entries: Normalizing. (line 30)
17851 * subedit minor mode: Subedit. (line 6)
17852 * t, PO Mode command: Translated Entries. (line 16)
17853 * T, PO Mode command: Translated Entries. (line 19)
17854 * t, PO Mode command <1>: Translated Entries. (line 22)
17855 * T, PO Mode command <1>: Translated Entries. (line 22)
17856 * TAB, PO Mode command: Fuzzy Entries. (line 35)
17857 * TAB, PO Mode command <1>: Fuzzy Entries. (line 42)
17858 * ‘TAGS’, and marking translatable strings: Marking. (line 30)
17859 * u, PO Mode command: Untranslated Entries.
17861 * U, PO Mode command: Untranslated Entries.
17863 * u, PO Mode command <1>: Untranslated Entries.
17865 * U, PO Mode command <1>: Untranslated Entries.
17867 * use the source, Luke: C Sources Context. (line 6)
17868 * using obsolete translations to make new entries: Modifying Translations.
17870 * using translation compendia: Compendium. (line 6)
17871 * V, PO Mode command: Main PO Commands. (line 50)
17872 * V, PO Mode command <1>: Main PO Commands. (line 92)
17873 * w, PO Mode command: Modifying Translations.
17875 * w, PO Mode command <1>: Modifying Translations.
17877 * W, PO Mode command: Modifying Comments. (line 31)
17878 * W, PO Mode command <1>: Modifying Comments. (line 60)
17879 * x, PO Mode command: Entry Positioning. (line 42)
17880 * x, PO Mode command <1>: Entry Positioning. (line 105)
17881 * y, PO Mode command: Modifying Translations.
17883 * y, PO Mode command <1>: Modifying Translations.
17885 * Y, PO Mode command: Modifying Comments. (line 35)
17886 * Y, PO Mode command <1>: Modifying Comments. (line 60)
17889 File: gettext.info, Node: Autoconf Macro Index, Next: Index, Prev: PO Mode Index, Up: Top
17891 Autoconf Macro Index
17892 ********************
17897 * AM_GNU_GETTEXT: AM_GNU_GETTEXT. (line 6)
17898 * AM_GNU_GETTEXT_INTL_SUBDIR: AM_GNU_GETTEXT_INTL_SUBDIR.
17900 * AM_GNU_GETTEXT_NEED: AM_GNU_GETTEXT_NEED. (line 6)
17901 * AM_GNU_GETTEXT_VERSION: AM_GNU_GETTEXT_VERSION.
17903 * AM_ICONV: AM_ICONV. (line 6)
17904 * AM_PO_SUBDIRS: AM_PO_SUBDIRS. (line 6)
17905 * AM_XGETTEXT_OPTION: AM_XGETTEXT_OPTION. (line 6)
17908 File: gettext.info, Node: Index, Prev: Autoconf Macro Index, Up: Top
17916 * ‘_’, a macro to mark strings for translation: Mark Keywords.
17918 * ‘_nl_msg_cat_cntr’: gettext grok. (line 59)
17919 * ‘ABOUT-NLS’ file: Installing Localizations.
17921 * ‘acconfig.h’ file: acconfig. (line 6)
17922 * accumulating translations: Creating Compendia. (line 14)
17923 * ‘aclocal.m4’ file: aclocal. (line 6)
17924 * adding keywords, ‘xgettext’: xgettext Invocation. (line 175)
17925 * ambiguities: Preparing Strings. (line 41)
17926 * apply a filter to translations: msgfilter Invocation.
17928 * apply command to all translations in a catalog: msgexec Invocation.
17930 * Arabic digits: c-format. (line 28)
17931 * attribute manipulation: msgattrib Invocation.
17933 * attribute, fuzzy: Fuzzy Entries. (line 6)
17934 * attributes of a PO file entry: Fuzzy Entries. (line 6)
17935 * attributes, manipulating: Manipulating. (line 56)
17936 * autoconf macros for ‘gettext’: autoconf macros. (line 6)
17937 * ‘autopoint’ program, usage: autopoint Invocation.
17939 * auxiliary PO file: Auxiliary. (line 13)
17940 * available translations: Installing Localizations.
17942 * awk: gawk. (line 6)
17943 * awk-format flag: PO Files. (line 151)
17944 * backup old file, and ‘msgmerge’ program: msgmerge Invocation.
17946 * bash: bash. (line 6)
17947 * bibliography: References. (line 6)
17948 * big picture: Overview. (line 6)
17949 * bind_textdomain_codeset: Charset conversion. (line 26)
17950 * Boost format strings: xgettext Invocation. (line 326)
17951 * boost-format flag: PO Files. (line 200)
17952 * bug report address: Introduction. (line 24)
17953 * C and C-like languages: C. (line 6)
17954 * C trigraphs: xgettext Invocation. (line 313)
17956 * C# mode, and ‘msgfmt’ program: msgfmt Invocation. (line 36)
17957 * C# mode, and ‘msgunfmt’ program: msgunfmt Invocation. (line 19)
17958 * C# resources mode, and ‘msgfmt’ program: msgfmt Invocation. (line 40)
17959 * C# resources mode, and ‘msgunfmt’ program: msgunfmt Invocation.
17961 * C#, string concatenation: Preparing Strings. (line 168)
17962 * c-format flag: PO Files. (line 88)
17963 * c-format, and ‘xgettext’: c-format Flag. (line 47)
17964 * catalog encoding and ‘msgexec’ output: msgexec Invocation. (line 35)
17965 * ‘catclose’, a ‘catgets’ function: Interface to catgets.
17967 * ‘catgets’, a ‘catgets’ function: Interface to catgets.
17969 * ‘catgets’, X/Open specification: catgets. (line 6)
17970 * ‘catopen’, a ‘catgets’ function: Interface to catgets.
17972 * character encoding: Aspects. (line 67)
17973 * charset conversion at runtime: Charset conversion. (line 6)
17974 * charset of PO files: Header Entry. (line 101)
17975 * check format strings: msgfmt Invocation. (line 230)
17976 * checking of translations: Manipulating. (line 41)
17977 * clisp: Common Lisp. (line 6)
17978 * clisp C sources: clisp C. (line 6)
17979 * codeset: Aspects. (line 67)
17980 * comments in PO files: PO Files. (line 320)
17981 * comments, automatic: PO Files. (line 36)
17982 * comments, extracted: PO Files. (line 36)
17983 * comments, translator: PO Files. (line 36)
17984 * Common Lisp: Common Lisp. (line 6)
17985 * compare PO files: msgcmp Invocation. (line 8)
17986 * comparison of interfaces: Comparison. (line 6)
17987 * compatibility with X/Open ‘msgfmt’: msgfmt Invocation. (line 263)
17988 * compendium: Compendium. (line 6)
17989 * compendium, creating: Creating Compendia. (line 6)
17990 * concatenate PO files: msgcat Invocation. (line 8)
17991 * concatenating PO files into a compendium: Creating Compendia.
17993 * concatenation of strings: Preparing Strings. (line 117)
17994 * ‘config.h.in’ file: config.h.in. (line 6)
17995 * context: Contexts. (line 6)
17996 * context, argument specification in ‘xgettext’: xgettext Invocation.
17998 * context, in MO files: MO Files. (line 71)
17999 * context, in PO files: PO Files. (line 211)
18000 * control characters: Preparing Strings. (line 190)
18001 * convert binary message catalog into PO file: msgunfmt Invocation.
18003 * convert translations to a different encoding: msgconv Invocation.
18005 * converting a package to use ‘gettext’: Prerequisites. (line 6)
18006 * country codes: Country Codes. (line 6)
18007 * create new PO file: msginit Invocation. (line 8)
18008 * creating a new PO file: Creating. (line 6)
18009 * creating compendia: Creating Compendia. (line 6)
18010 * csharp-format flag: PO Files. (line 147)
18011 * currency symbols: Aspects. (line 80)
18012 * date format: Aspects. (line 86)
18013 * dcngettext: Plural forms. (line 158)
18014 * dcpgettext: Contexts. (line 56)
18015 * dcpgettext_expr: Contexts. (line 112)
18016 * debugging messages marked as format strings: xgettext Invocation.
18018 * Desktop Entry mode, and ‘msgfmt’ program: msgfmt Invocation.
18020 * dialect: Manipulating. (line 28)
18021 * disabling NLS: lib/gettext.h. (line 6)
18022 * distribution tarball: Release Management. (line 6)
18023 * dngettext: Plural forms. (line 151)
18024 * dollar substitution: envsubst Invocation. (line 8)
18025 * domain ambiguities: Ambiguities. (line 6)
18026 * dpgettext: Contexts. (line 56)
18027 * dpgettext_expr: Contexts. (line 112)
18028 * duplicate elimination: Manipulating. (line 45)
18029 * duplicate removal: msguniq Invocation. (line 8)
18030 * editing comments in PO files: Modifying Comments. (line 6)
18031 * Editing PO Files: Editing. (line 6)
18032 * editing translations: Modifying Translations.
18034 * elisp-format flag: PO Files. (line 127)
18035 * Emacs Lisp: Emacs Lisp. (line 6)
18036 * Emacs PO Mode: PO Mode. (line 6)
18037 * encoding: Aspects. (line 67)
18038 * encoding conversion: Manipulating. (line 17)
18039 * encoding conversion at runtime: Charset conversion. (line 6)
18040 * encoding for your language: Header Entry. (line 130)
18041 * encoding list: Header Entry. (line 114)
18042 * encoding of PO files: Header Entry. (line 101)
18043 * environment variables: envsubst Invocation. (line 8)
18044 * ‘envsubst’ program, usage: envsubst Invocation. (line 6)
18045 * ‘eval_gettext’ function, usage: eval_gettext Invocation.
18047 * ‘eval_ngettext’ function, usage: eval_ngettext Invocation.
18049 * evolution of packages: Overview. (line 127)
18050 * extracting parts of a PO file into a compendium: Creating Compendia.
18052 * FDL, GNU Free Documentation License: GNU FDL. (line 6)
18053 * file format, ‘.mo’: MO Files. (line 6)
18054 * file format, ‘.po’: PO Files. (line 6)
18055 * files, ‘.po’ and ‘.mo’: Files. (line 6)
18056 * files, ‘.pot’: Overview. (line 67)
18057 * filter messages according to attributes: msgattrib Invocation.
18059 * find common messages: msgcomm Invocation. (line 8)
18060 * force use of fuzzy entries: msgfmt Invocation. (line 279)
18061 * format strings: c-format Flag. (line 6)
18062 * Free Pascal: Pascal. (line 6)
18063 * function attribute, __format_arg__: xgettext Invocation. (line 291)
18064 * function attribute, __format__: xgettext Invocation. (line 277)
18065 * fuzzy entries: Fuzzy Entries. (line 6)
18066 * fuzzy flag: PO Files. (line 78)
18067 * gawk: gawk. (line 6)
18068 * gcc-internal-format flag: PO Files. (line 179)
18069 * GCC-source: GCC-source. (line 6)
18070 * generate binary message catalog from PO file: msgfmt Invocation.
18072 * generate translation catalog in English: msgen Invocation. (line 8)
18073 * ‘gettext’ files: Adjusting Files. (line 6)
18074 * ‘gettext’ installation: Installation. (line 6)
18075 * ‘gettext’ interface: Interface to gettext.
18077 * ‘gettext’ program, usage: gettext Invocation. (line 6)
18078 * ‘gettext’ vs ‘catgets’: Comparison. (line 6)
18079 * ‘gettext’, a programmer’s view: gettext. (line 6)
18080 * ‘gettext.h’ file: lib/gettext.h. (line 6)
18081 * ‘gettextize’ program, usage: gettextize Invocation.
18083 * gfc-internal-format flag: PO Files. (line 183)
18084 * GNOME PO file editor: Gtranslator. (line 5)
18085 * GPL, GNU General Public License: GNU GPL. (line 6)
18086 * GUI programs: Contexts. (line 6)
18087 * guile: Scheme. (line 6)
18088 * hash table, inside MO files: MO Files. (line 55)
18089 * he, she, and they: Introduction. (line 15)
18090 * header entry of a PO file: Header Entry. (line 6)
18091 * help option: Preparing Strings. (line 109)
18092 * history of GNU ‘gettext’: History. (line 6)
18093 * i18n: Concepts. (line 6)
18094 * importing PO files: Normalizing. (line 54)
18095 * include file ‘libintl.h’: Overview. (line 57)
18096 * include file ‘libintl.h’ <1>: Importing. (line 11)
18097 * include file ‘libintl.h’ <2>: Comparison. (line 33)
18098 * include file ‘libintl.h’ <3>: lib/gettext.h. (line 29)
18099 * initialization: Triggering. (line 6)
18100 * initialize new PO file: msginit Invocation. (line 8)
18101 * initialize translations from a compendium: Using Compendia. (line 12)
18102 * installing ‘gettext’: Installation. (line 6)
18103 * interface to ‘catgets’: Interface to catgets.
18105 * internationalization: Concepts. (line 16)
18106 * ‘inttypes.h’: Preparing Strings. (line 133)
18107 * ISO 3166: Country Codes. (line 6)
18108 * ISO 639: Language Codes. (line 6)
18109 * Java: Java. (line 6)
18110 * Java mode, and ‘msgfmt’ program: msgfmt Invocation. (line 30)
18111 * Java mode, and ‘msgunfmt’ program: msgunfmt Invocation. (line 16)
18112 * Java, string concatenation: Preparing Strings. (line 168)
18113 * java-format flag: PO Files. (line 143)
18114 * javascript-format flag: PO Files. (line 208)
18115 * KDE format strings: xgettext Invocation. (line 322)
18116 * KDE PO file editor: KBabel. (line 5)
18117 * kde-format flag: PO Files. (line 196)
18118 * keyboard accelerator checking: msgfmt Invocation. (line 267)
18119 * l10n: Concepts. (line 6)
18120 * language codes: Language Codes. (line 6)
18121 * language selection: Locale Environment Variables.
18123 * language selection at runtime: gettext grok. (line 14)
18124 * large package: Ambiguities. (line 6)
18125 * LGPL, GNU Lesser General Public License: GNU LGPL. (line 6)
18126 * ‘libiconv’ library: AM_ICONV. (line 20)
18127 * ‘libintl’ for C#: C#. (line 179)
18128 * ‘libintl’ for Java: Java. (line 105)
18129 * ‘libintl’ library: AM_GNU_GETTEXT. (line 53)
18130 * ‘librep’ Lisp: librep. (line 6)
18131 * librep-format flag: PO Files. (line 131)
18132 * License, GNU FDL: GNU FDL. (line 6)
18133 * License, GNU GPL: GNU GPL. (line 6)
18134 * License, GNU LGPL: GNU LGPL. (line 6)
18135 * Licenses: Licenses. (line 6)
18136 * ‘LINGUAS’ file: po/LINGUAS. (line 6)
18137 * link with ‘libintl’: Overview. (line 62)
18138 * Linux: Aspects. (line 129)
18139 * Linux <1>: Overview. (line 62)
18140 * Linux <2>: Header Entry. (line 127)
18141 * Lisp: Common Lisp. (line 6)
18142 * lisp-format flag: PO Files. (line 123)
18143 * list of translation teams, where to find: Header Entry. (line 54)
18144 * locale categories: Aspects. (line 61)
18145 * locale categories <1>: Aspects. (line 118)
18146 * locale category, LC_ALL: Triggering. (line 23)
18147 * locale category, LC_COLLATE: Triggering. (line 52)
18148 * locale category, LC_CTYPE: Aspects. (line 67)
18149 * locale category, LC_CTYPE <1>: Triggering. (line 23)
18150 * locale category, LC_CTYPE <2>: Triggering. (line 52)
18151 * locale category, LC_MESSAGES: Aspects. (line 112)
18152 * locale category, LC_MESSAGES <1>: Triggering. (line 52)
18153 * locale category, LC_MONETARY: Aspects. (line 80)
18154 * locale category, LC_MONETARY <1>: Triggering. (line 52)
18155 * locale category, LC_NUMERIC: Aspects. (line 97)
18156 * locale category, LC_NUMERIC <1>: Triggering. (line 52)
18157 * locale category, LC_RESPONSES: Triggering. (line 52)
18158 * locale category, LC_TIME: Aspects. (line 86)
18159 * locale category, LC_TIME <1>: Triggering. (line 52)
18160 * ‘locale’ program: Header Entry. (line 107)
18161 * localization: Concepts. (line 26)
18162 * lookup message translation: gettext Invocation. (line 9)
18163 * lookup message translation <1>: eval_gettext Invocation.
18165 * lookup plural message translation: ngettext Invocation. (line 8)
18166 * lookup plural message translation <1>: eval_ngettext Invocation.
18168 * lua-format flag: PO Files. (line 204)
18169 * magic signature of MO files: MO Files. (line 9)
18170 * ‘Makefile.in.in’ extensions: po/Rules-*. (line 6)
18171 * ‘Makevars’ file: po/Makevars. (line 6)
18172 * manipulating PO files: Manipulating. (line 6)
18173 * marking Perl sources: Perl. (line 92)
18174 * marking string initializers: Special cases. (line 6)
18175 * marking strings that require translation: Mark Keywords. (line 6)
18176 * marking strings, preparations: Preparing Strings. (line 6)
18177 * marking translatable strings: Overview. (line 34)
18178 * markup: Preparing Strings. (line 190)
18179 * menu entries: Contexts. (line 6)
18180 * menu, keyboard accelerator support: msgfmt Invocation. (line 267)
18181 * merge PO files: msgcat Invocation. (line 8)
18182 * merging two PO files: Manipulating. (line 10)
18183 * message catalog files location: Locating Catalogs. (line 6)
18184 * messages: Aspects. (line 112)
18185 * migration from earlier versions of ‘gettext’: Prerequisites.
18187 * ‘mkinstalldirs’ file: mkinstalldirs. (line 6)
18188 * mnemonics of menu entries: msgfmt Invocation. (line 267)
18189 * MO file’s format: MO Files. (line 6)
18190 * modify message attributes: msgattrib Invocation.
18192 * ‘msgattrib’ program, usage: msgattrib Invocation.
18194 * ‘msgcat’ program, usage: msgcat Invocation. (line 6)
18195 * ‘msgcmp’ program, usage: msgcmp Invocation. (line 6)
18196 * ‘msgcomm’ program, usage: msgcomm Invocation. (line 6)
18197 * ‘msgconv’ program, usage: msgconv Invocation. (line 6)
18198 * msgctxt: PO Files. (line 211)
18199 * ‘msgen’ program, usage: msgen Invocation. (line 6)
18200 * ‘msgexec’ program, usage: msgexec Invocation. (line 6)
18201 * ‘msgfilter’ filter and catalog encoding: msgfilter Invocation.
18203 * ‘msgfilter’ program, usage: msgfilter Invocation.
18205 * ‘msgfmt’ program, usage: msgfmt Invocation. (line 6)
18206 * ‘msggrep’ program, usage: msggrep Invocation. (line 6)
18207 * msgid: PO Files. (line 55)
18208 * msgid_plural: PO Files. (line 231)
18209 * ‘msginit’ program, usage: msginit Invocation. (line 6)
18210 * ‘msgmerge’ program, usage: msgmerge Invocation. (line 6)
18211 * msgstr: PO Files. (line 55)
18212 * ‘msgunfmt’ program, usage: msgunfmt Invocation. (line 6)
18213 * ‘msguniq’ program, usage: msguniq Invocation. (line 6)
18214 * multi-line strings: Normalizing. (line 64)
18215 * Native Language Support: Concepts. (line 51)
18216 * Natural Language Support: Concepts. (line 51)
18217 * newlines in PO files: PO Files. (line 315)
18218 * ngettext: Plural forms. (line 82)
18219 * ‘ngettext’ program, usage: ngettext Invocation. (line 6)
18220 * NLS: Concepts. (line 51)
18221 * no-awk-format flag: PO Files. (line 152)
18222 * no-boost-format flag: PO Files. (line 201)
18223 * no-c-format flag: PO Files. (line 89)
18224 * no-c-format, and ‘xgettext’: c-format Flag. (line 47)
18225 * no-csharp-format flag: PO Files. (line 148)
18226 * no-elisp-format flag: PO Files. (line 128)
18227 * no-gcc-internal-format flag: PO Files. (line 180)
18228 * no-gfc-internal-format flag: PO Files. (line 184)
18229 * no-java-format flag: PO Files. (line 144)
18230 * no-javascript-format flag: PO Files. (line 209)
18231 * no-kde-format flag: PO Files. (line 197)
18232 * no-librep-format flag: PO Files. (line 132)
18233 * no-lisp-format flag: PO Files. (line 124)
18234 * no-lua-format flag: PO Files. (line 205)
18235 * no-objc-format flag: PO Files. (line 108)
18236 * no-object-pascal-format flag: PO Files. (line 156)
18237 * no-perl-brace-format flag: PO Files. (line 172)
18238 * no-perl-format flag: PO Files. (line 168)
18239 * no-php-format flag: PO Files. (line 176)
18240 * no-python-brace-format flag: PO Files. (line 120)
18241 * no-python-format flag: PO Files. (line 116)
18242 * no-qt-format flag: PO Files. (line 189)
18243 * no-qt-plural-format flag: PO Files. (line 193)
18244 * no-scheme-format flag: PO Files. (line 136)
18245 * no-sh-format flag: PO Files. (line 112)
18246 * no-smalltalk-format flag: PO Files. (line 140)
18247 * no-tcl-format flag: PO Files. (line 164)
18248 * no-ycp-format flag: PO Files. (line 160)
18249 * nplurals, in a PO file header: Plural forms. (line 177)
18250 * number format: Aspects. (line 97)
18251 * ‘N_’, a convenience macro: Comparison. (line 41)
18252 * objc-format flag: PO Files. (line 107)
18253 * Object Pascal: Pascal. (line 6)
18254 * object-pascal-format flag: PO Files. (line 155)
18255 * obsolete entries: Obsolete Entries. (line 6)
18256 * optimization of ‘gettext’ functions: Optimized gettext. (line 6)
18257 * orthography: Manipulating. (line 28)
18258 * outdigits: c-format. (line 28)
18259 * output to stdout, ‘xgettext’: xgettext Invocation. (line 46)
18260 * overview of ‘gettext’: Overview. (line 6)
18261 * package and version declaration in ‘configure.ac’: configure.ac.
18263 * package build and installation options: Installers. (line 6)
18264 * package distributor’s view of ‘gettext’: Installers. (line 6)
18265 * package installer’s view of ‘gettext’: Installers. (line 6)
18266 * package maintainer’s view of ‘gettext’: Maintainers. (line 6)
18267 * paragraphs: Preparing Strings. (line 101)
18268 * Pascal: Pascal. (line 6)
18269 * Perl: Perl. (line 6)
18270 * Perl default keywords: Default Keywords. (line 6)
18271 * Perl invalid string interpolation: Interpolation I. (line 6)
18272 * Perl long lines: Long Lines. (line 6)
18273 * Perl parentheses: Parentheses. (line 6)
18274 * Perl pitfalls: Perl Pitfalls. (line 6)
18275 * Perl quote-like expressions: Quote-like Expressions.
18277 * Perl special keywords for hash-lookups: Special Keywords. (line 6)
18278 * Perl valid string interpolation: Interpolation II. (line 6)
18279 * perl-brace-format flag: PO Files. (line 171)
18280 * perl-format flag: PO Files. (line 167)
18281 * pgettext: Contexts. (line 33)
18282 * pgettext_expr: Contexts. (line 112)
18283 * PHP: PHP. (line 6)
18284 * php-format flag: PO Files. (line 175)
18285 * Pike: Pike. (line 6)
18286 * plural form formulas: Plural forms. (line 197)
18287 * plural forms: Plural forms. (line 6)
18288 * plural forms, in MO files: MO Files. (line 74)
18289 * plural forms, in PO files: PO Files. (line 231)
18290 * plural forms, translating: Translating plural forms.
18292 * plural, in a PO file header: Plural forms. (line 177)
18293 * PO files’ format: PO Files. (line 6)
18294 * PO mode (Emacs) commands: Main PO Commands. (line 6)
18295 * PO template file: Template. (line 6)
18296 * portability problems with ‘sed’: msgfilter Invocation.
18298 * ‘POTFILES.in’ file: po/POTFILES.in. (line 6)
18299 * po_file_domains: libgettextpo. (line 40)
18300 * po_file_free: libgettextpo. (line 35)
18301 * po_file_read: libgettextpo. (line 29)
18302 * po_message_iterator: libgettextpo. (line 48)
18303 * po_message_iterator_free: libgettextpo. (line 55)
18304 * po_message_msgid: libgettextpo. (line 69)
18305 * po_message_msgid_plural: libgettextpo. (line 73)
18306 * po_message_msgstr: libgettextpo. (line 79)
18307 * po_message_msgstr_plural: libgettextpo. (line 84)
18308 * po_next_message: libgettextpo. (line 60)
18309 * preparing programs for translation: Sources. (line 6)
18310 * preparing rules for XML translation: Preparing ITS Rules. (line 6)
18311 * preparing shell scripts for translation: Preparing Shell Scripts.
18313 * problems with ‘catgets’ interface: Problems with catgets.
18315 * programming languages: Language Implementors.
18317 * Python: Python. (line 6)
18318 * python-brace-format flag: PO Files. (line 119)
18319 * python-format flag: PO Files. (line 115)
18320 * Qt format strings: xgettext Invocation. (line 318)
18321 * Qt mode, and ‘msgfmt’ program: msgfmt Invocation. (line 46)
18322 * qt-format flag: PO Files. (line 188)
18323 * qt-plural-format flag: PO Files. (line 192)
18324 * quotation marks: Header Entry. (line 160)
18325 * quotation marks <1>: po/Rules-*. (line 11)
18326 * quote characters, use in PO files: Header Entry. (line 160)
18327 * range: flag: PO Files. (line 262)
18328 * ‘recode-sr-latin’ program: msgfilter Invocation.
18330 * related reading: References. (line 6)
18331 * release: Release Management. (line 6)
18332 * RST: RST. (line 6)
18333 * Scheme: Scheme. (line 6)
18334 * scheme-format flag: PO Files. (line 135)
18335 * scripting languages: Language Implementors.
18337 * search messages in a catalog: msggrep Invocation. (line 8)
18338 * selecting message language: Locale Environment Variables.
18340 * sentence end markers, ‘xgettext’: xgettext Invocation. (line 149)
18341 * sentences: Preparing Strings. (line 44)
18342 * setting up ‘gettext’ at build time: Installers. (line 6)
18343 * setting up ‘gettext’ at run time: Locale Environment Variables.
18345 * several domains: Ambiguities. (line 6)
18346 * sex: Introduction. (line 15)
18347 * sh-format flag: PO Files. (line 111)
18348 * she, he, and they: Introduction. (line 15)
18349 * shell format string: envsubst Invocation. (line 8)
18350 * shell scripts: sh. (line 6)
18351 * Smalltalk: Smalltalk. (line 6)
18352 * smalltalk-format flag: PO Files. (line 139)
18353 * sorting ‘msgcat’ output: msgcat Invocation. (line 152)
18354 * sorting ‘msgmerge’ output: msgmerge Invocation. (line 188)
18355 * sorting ‘msgunfmt’ output: msgunfmt Invocation. (line 147)
18356 * sorting output of ‘xgettext’: xgettext Invocation. (line 413)
18357 * specifying plural form in a PO file: Plural forms. (line 177)
18358 * standard output, and ‘msgcat’: msgcat Invocation. (line 44)
18359 * standard output, and ‘msgmerge’ program: msgmerge Invocation.
18361 * string concatenation: Preparing Strings. (line 117)
18362 * string normalization in entries: Normalizing. (line 6)
18363 * style: Preparing Strings. (line 24)
18364 * supported languages, ‘msgfmt’: msgfmt Invocation. (line 180)
18365 * supported languages, ‘xgettext’: xgettext Invocation. (line 54)
18366 * supported syntax checks, ‘xgettext’: xgettext Invocation. (line 116)
18367 * Tcl: Tcl. (line 6)
18368 * Tcl mode, and ‘msgfmt’ program: msgfmt Invocation. (line 43)
18369 * Tcl mode, and ‘msgunfmt’ program: msgunfmt Invocation. (line 26)
18370 * tcl-format flag: PO Files. (line 163)
18371 * template PO file: Overview. (line 67)
18372 * testing ‘.po’ files for equivalence: xgettext Invocation. (line 423)
18373 * Tk’s scripting language: Tcl. (line 6)
18374 * translated entries: Translated Entries. (line 6)
18375 * translating menu entries: Contexts. (line 6)
18376 * translation aspects: Aspects. (line 6)
18377 * Translation Matrix: Installing Localizations.
18379 * Translation Project: Why. (line 17)
18380 * turning off NLS support: lib/gettext.h. (line 6)
18381 * tutorial of ‘gettext’ usage: Overview. (line 6)
18382 * unify duplicate translations: msguniq Invocation. (line 8)
18383 * untranslated entries: Untranslated Entries.
18385 * update translations from a compendium: Using Compendia. (line 20)
18386 * upgrading to new versions of ‘gettext’: Prerequisites. (line 6)
18387 * version control for backup files, ‘msgmerge’: msgmerge Invocation.
18389 * ‘wxWidgets’ library: wxWidgets. (line 6)
18390 * ‘xargs’, and output from ‘msgexec’: msgexec Invocation. (line 14)
18391 * ‘xgettext’ program, usage: xgettext Invocation. (line 6)
18392 * XML mode, and ‘msgfmt’ program: msgfmt Invocation. (line 52)
18393 * ‘xmodmap’ program, and typing quotation marks: Header Entry.
18395 * YaST2 scripting language: YCP. (line 6)
18396 * YCP: YCP. (line 6)
18397 * ycp-format flag: PO Files. (line 159)
18403 Node: Introduction
\7f18343
18405 Ref: Why-Footnote-1
\7f23241
18406 Node: Concepts
\7f23397
18407 Node: Aspects
\7f26828
18408 Node: Files
\7f33436
18409 Node: Overview
\7f35386
18410 Node: Users
\7f45473
18411 Node: System Installation
\7f46388
18412 Node: Setting the GUI Locale
\7f48081
18413 Node: Setting the POSIX Locale
\7f49489
18414 Node: Locale Names
\7f50471
18415 Node: Locale Environment Variables
\7f52960
18416 Node: The LANGUAGE variable
\7f55303
18417 Node: Installing Localizations
\7f57324
18418 Node: PO Files
\7f58701
18419 Ref: PO Files-Footnote-1
\7f71839
18420 Node: Sources
\7f71974
18421 Node: Importing
\7f73216
18422 Node: Triggering
\7f73920
18423 Node: Preparing Strings
\7f77278
18424 Node: Mark Keywords
\7f86437
18425 Node: Marking
\7f91005
18426 Node: c-format Flag
\7f98962
18427 Node: Special cases
\7f103008
18428 Node: Bug Report Address
\7f105792
18429 Node: Names
\7f107771
18430 Node: Libraries
\7f112077
18431 Node: Template
\7f115167
18432 Node: xgettext Invocation
\7f115932
18433 Node: Creating
\7f136166
18434 Node: msginit Invocation
\7f137075
18435 Node: Header Entry
\7f141398
18436 Node: Updating
\7f150855
18437 Node: msgmerge Invocation
\7f151074
18438 Node: Editing
\7f157540
18439 Node: KBabel
\7f157904
18440 Node: Gtranslator
\7f158044
18441 Node: PO Mode
\7f158188
18442 Node: Installation
\7f159848
18443 Node: Main PO Commands
\7f161864
18444 Node: Entry Positioning
\7f167136
18445 Node: Normalizing
\7f172781
18446 Node: Translated Entries
\7f177342
18447 Node: Fuzzy Entries
\7f178747
18448 Node: Untranslated Entries
\7f182054
18449 Node: Obsolete Entries
\7f184053
18450 Node: Modifying Translations
\7f187352
18451 Node: Modifying Comments
\7f195494
18452 Node: Subedit
\7f200043
18453 Node: C Sources Context
\7f204061
18454 Node: Auxiliary
\7f209290
18455 Node: Compendium
\7f212610
18456 Node: Creating Compendia
\7f213225
18457 Node: Using Compendia
\7f215787
18458 Node: Manipulating
\7f216745
18459 Node: msgcat Invocation
\7f220689
18460 Node: msgconv Invocation
\7f226011
18461 Node: msggrep Invocation
\7f230002
18462 Node: msgfilter Invocation
\7f236824
18463 Node: msguniq Invocation
\7f245178
18464 Node: msgcomm Invocation
\7f249918
18465 Node: msgcmp Invocation
\7f254819
18466 Node: msgattrib Invocation
\7f257060
18467 Node: msgen Invocation
\7f262829
18468 Node: msgexec Invocation
\7f267238
18469 Node: Colorizing
\7f270562
18470 Node: The --color option
\7f271617
18471 Node: The TERM variable
\7f273346
18472 Node: The --style option
\7f274900
18473 Node: Style rules
\7f276278
18474 Node: Customizing less
\7f283291
18475 Node: libgettextpo
\7f284746
18476 Node: Binaries
\7f289996
18477 Node: msgfmt Invocation
\7f290348
18478 Node: msgunfmt Invocation
\7f301074
18479 Node: MO Files
\7f305758
18480 Node: Programmers
\7f314369
18481 Node: catgets
\7f315583
18482 Node: Interface to catgets
\7f317013
18483 Node: Problems with catgets
\7f319082
18484 Node: gettext
\7f320007
18485 Node: Interface to gettext
\7f321530
18486 Node: Ambiguities
\7f323898
18487 Node: Locating Catalogs
\7f326658
18488 Ref: Locating Catalogs-Footnote-1
\7f327923
18489 Ref: Locating Catalogs-Footnote-2
\7f328155
18490 Node: Charset conversion
\7f328308
18491 Node: Contexts
\7f330828
18492 Node: Plural forms
\7f336448
18493 Ref: Plural forms-Footnote-1
\7f353164
18494 Node: Optimized gettext
\7f353536
18495 Node: Comparison
\7f354887
18496 Node: Using libintl.a
\7f359254
18497 Node: gettext grok
\7f359709
18498 Node: Temp Programmers
\7f362418
18499 Node: Temp Implementations
\7f362950
18500 Node: Temp catgets
\7f364368
18501 Node: Temp WSI
\7f366095
18502 Node: Temp Notes
\7f368158
18503 Node: Translators
\7f368672
18504 Node: Trans Intro 0
\7f369217
18505 Node: Trans Intro 1
\7f372074
18506 Node: Discussions
\7f374047
18507 Node: Organization
\7f377765
18508 Node: Central Coordination
\7f379851
18509 Node: National Teams
\7f380999
18510 Node: Sub-Cultures
\7f383533
18511 Node: Organizational Ideas
\7f384474
18512 Node: Mailing Lists
\7f385505
18513 Node: Information Flow
\7f387342
18514 Node: Translating plural forms
\7f389609
18515 Node: Prioritizing messages
\7f393052
18516 Node: Maintainers
\7f397436
18517 Node: Flat and Non-Flat
\7f399413
18518 Node: Prerequisites
\7f400943
18519 Node: gettextize Invocation
\7f405202
18520 Node: Adjusting Files
\7f412982
18521 Node: po/POTFILES.in
\7f414828
18522 Node: po/LINGUAS
\7f416127
18523 Node: po/Makevars
\7f417934
18524 Node: po/Rules-*
\7f418924
18525 Node: configure.ac
\7f420485
18526 Node: config.guess
\7f423650
18527 Node: mkinstalldirs
\7f425116
18528 Node: aclocal
\7f425529
18529 Node: acconfig
\7f428084
18530 Node: config.h.in
\7f428628
18531 Node: Makefile
\7f430176
18532 Node: src/Makefile
\7f432908
18533 Node: lib/gettext.h
\7f437834
18534 Node: autoconf macros
\7f440167
18535 Node: AM_GNU_GETTEXT
\7f441071
18536 Node: AM_GNU_GETTEXT_VERSION
\7f445295
18537 Node: AM_GNU_GETTEXT_NEED
\7f445774
18538 Node: AM_GNU_GETTEXT_INTL_SUBDIR
\7f446707
18539 Node: AM_PO_SUBDIRS
\7f447392
18540 Node: AM_XGETTEXT_OPTION
\7f448231
18541 Node: AM_ICONV
\7f449142
18542 Node: Version Control Issues
\7f451527
18543 Node: Distributed Development
\7f452282
18544 Node: Files under Version Control
\7f454317
18545 Node: Translations under Version Control
\7f457808
18546 Ref: Translations under Version Control-Footnote-1
\7f459884
18547 Node: autopoint Invocation
\7f459974
18548 Node: Release Management
\7f462339
18549 Node: Installers
\7f462880
18550 Node: Programming Languages
\7f464143
18551 Node: Language Implementors
\7f464981
18552 Node: Programmers for other Languages
\7f469971
18553 Node: Translators for other Languages
\7f470565
18554 Node: c-format
\7f472427
18555 Node: objc-format
\7f474201
18556 Node: sh-format
\7f474560
18557 Node: python-format
\7f475409
18558 Node: lisp-format
\7f476182
18559 Node: elisp-format
\7f476511
18560 Node: librep-format
\7f477006
18561 Node: scheme-format
\7f477409
18562 Node: smalltalk-format
\7f477688
18563 Node: java-format
\7f478219
18564 Node: csharp-format
\7f478674
18565 Node: awk-format
\7f479056
18566 Node: object-pascal-format
\7f479384
18567 Node: ycp-format
\7f479770
18568 Node: tcl-format
\7f480188
18569 Node: perl-format
\7f480490
18570 Node: php-format
\7f481282
18571 Node: gcc-internal-format
\7f481658
18572 Node: gfc-internal-format
\7f482817
18573 Node: qt-format
\7f483566
18574 Node: qt-plural-format
\7f484012
18575 Node: kde-format
\7f484371
18576 Node: kde-kuit-format
\7f484803
18577 Node: boost-format
\7f485468
18578 Node: lua-format
\7f486060
18579 Node: javascript-format
\7f486399
18580 Node: Maintainers for other Languages
\7f487169
18581 Node: List of Programming Languages
\7f488457
18584 Node: Preparing Shell Scripts
\7f492666
18585 Node: gettext.sh
\7f496186
18586 Node: gettext Invocation
\7f496754
18587 Node: ngettext Invocation
\7f498805
18588 Node: envsubst Invocation
\7f500685
18589 Node: eval_gettext Invocation
\7f502164
18590 Node: eval_ngettext Invocation
\7f502629
18591 Node: bash
\7f503147
18592 Node: Python
\7f505196
18593 Node: Common Lisp
\7f507676
18594 Node: clisp C
\7f508526
18595 Node: Emacs Lisp
\7f509284
18596 Node: librep
\7f510052
18597 Node: Scheme
\7f510833
18598 Node: Smalltalk
\7f511708
18599 Node: Java
\7f512803
18601 Node: gawk
\7f528521
18602 Node: Pascal
\7f529626
18603 Node: wxWidgets
\7f531038
18606 Node: Perl
\7f534274
18607 Node: General Problems
\7f537466
18608 Node: Default Keywords
\7f543134
18609 Node: Special Keywords
\7f544162
18610 Node: Quote-like Expressions
\7f545724
18611 Node: Interpolation I
\7f548041
18612 Node: Interpolation II
\7f551985
18613 Node: Parentheses
\7f554369
18614 Node: Long Lines
\7f555894
18615 Node: Perl Pitfalls
\7f557761
18617 Node: Pike
\7f563104
18618 Node: GCC-source
\7f563805
18620 Node: JavaScript
\7f565631
18621 Node: Vala
\7f566399
18622 Node: List of Data Formats
\7f567318
18625 Node: Glade
\7f568523
18626 Node: GSettings
\7f568935
18627 Node: AppData
\7f569246
18628 Node: Preparing ITS Rules
\7f569677
18629 Node: Conclusion
\7f575810
18630 Node: History
\7f576324
18631 Node: References
\7f580727
18632 Node: Language Codes
\7f582426
18633 Node: Usual Language Codes
\7f582941
18634 Node: Rare Language Codes
\7f587859
18635 Node: Country Codes
\7f589709
18636 Node: Licenses
\7f596862
18637 Node: GNU GPL
\7f598718
18638 Node: GNU LGPL
\7f618035
18639 Node: GNU FDL
\7f646272
18640 Node: Program Index
\7f668803
18641 Node: Option Index
\7f671213
18642 Node: Variable Index
\7f726431
18643 Node: PO Mode Index
\7f731102
18644 Node: Autoconf Macro Index
\7f747812
18645 Node: Index
\7f748619