1 This is gettext.info, produced by makeinfo version 5.2 from
4 Copyright (C) 1995-1998, 2001-2016 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.8.1.
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 ‘"'`’
2602 Prefer Unicode bullet character over ASCII ‘*’ or ‘-’
2604 The option has an effect on all input files. To enable or disable
2605 checks for a certain string, you can mark it with an ‘xgettext:’
2606 special comment in the source file. For example, if you specify
2607 the ‘--check=space-ellipsis’ option, but want to suppress the check
2608 on a particular string, add the following comment:
2610 /* xgettext: no-space-ellipsis-check */
2611 gettext ("We really want a space before ellipsis here ...");
2613 The ‘xgettext:’ comment can be followed by flags separated with a
2614 comma. The possible flags are of the form ‘[no-]NAME-check’, where
2615 NAME is the name of a valid syntax check. If a flag is prefixed by
2616 ‘no-’, the meaning is negated.
2618 Some tests apply the checks to each sentence within the msgid,
2619 rather than the whole string. xgettext detects the end of sentence
2620 by performing a pattern match, which usually looks for a period
2621 followed by a certain number of spaces. The number is specified
2622 with the ‘--sentence-end’ option.
2624 ‘--sentence-end[=TYPE]’
2625 The supported values are:
2628 Expect at least one whitespace after a period
2631 Expect at least two whitespaces after a period
2633 5.1.6 Language specific options
2634 -------------------------------
2638 Extract all strings.
2640 This option has an effect with most languages, namely C, C++,
2641 ObjectiveC, Shell, Python, Lisp, EmacsLisp, librep, Java, C#, awk,
2642 Tcl, Perl, PHP, GCC-source, Glade, Lua, JavaScript, Vala,
2646 ‘--keyword[=KEYWORDSPEC]’
2647 Specify KEYWORDSPEC as an additional keyword to be looked for.
2648 Without a KEYWORDSPEC, the option means to not use default
2651 If KEYWORDSPEC is a C identifier ID, ‘xgettext’ looks for strings
2652 in the first argument of each call to the function or macro ID. If
2653 KEYWORDSPEC is of the form ‘ID:ARGNUM’, ‘xgettext’ looks for
2654 strings in the ARGNUMth argument of the call. If KEYWORDSPEC is of
2655 the form ‘ID:ARGNUM1,ARGNUM2’, ‘xgettext’ looks for strings in the
2656 ARGNUM1st argument and in the ARGNUM2nd argument of the call, and
2657 treats them as singular/plural variants for a message with plural
2658 handling. Also, if KEYWORDSPEC is of the form
2659 ‘ID:CONTEXTARGNUMc,ARGNUM’ or ‘ID:ARGNUM,CONTEXTARGNUMc’,
2660 ‘xgettext’ treats strings in the CONTEXTARGNUMth argument as a
2661 context specifier. And, as a special-purpose support for GNOME, if
2662 KEYWORDSPEC is of the form ‘ID:ARGNUMg’, ‘xgettext’ recognizes the
2663 ARGNUMth argument as a string with context, using the GNOME ‘glib’
2664 syntax ‘"msgctxt|msgid"’.
2665 Furthermore, if KEYWORDSPEC is of the form ‘ID:…,TOTALNUMARGSt’,
2666 ‘xgettext’ recognizes this argument specification only if the
2667 number of actual arguments is equal to TOTALNUMARGS. This is
2668 useful for disambiguating overloaded function calls in C++.
2669 Finally, if KEYWORDSPEC is of the form ‘ID:ARGNUM...,"XCOMMENT"’,
2670 ‘xgettext’, when extracting a message from the specified argument
2671 strings, adds an extracted comment XCOMMENT to the message. Note
2672 that when used through a normal shell command line, the
2673 double-quotes around the XCOMMENT need to be escaped.
2675 This option has an effect with most languages, namely C, C++,
2676 ObjectiveC, Shell, Python, Lisp, EmacsLisp, librep, Java, C#, awk,
2677 Tcl, Perl, PHP, GCC-source, Glade, Lua, JavaScript, Vala,
2680 The default keyword specifications, which are always looked for if
2681 not explicitly disabled, are language dependent. They are:
2683 • For C, C++, and GCC-source: ‘gettext’, ‘dgettext:2’,
2684 ‘dcgettext:2’, ‘ngettext:1,2’, ‘dngettext:2,3’,
2685 ‘dcngettext:2,3’, ‘gettext_noop’, and ‘pgettext:1c,2’,
2686 ‘dpgettext:2c,3’, ‘dcpgettext:2c,3’, ‘npgettext:1c,2,3’,
2687 ‘dnpgettext:2c,3,4’, ‘dcnpgettext:2c,3,4’.
2689 • For Objective C: Like for C, and also ‘NSLocalizedString’,
2690 ‘_’, ‘NSLocalizedStaticString’, ‘__’.
2692 • For Shell scripts: ‘gettext’, ‘ngettext:1,2’, ‘eval_gettext’,
2693 ‘eval_ngettext:1,2’.
2695 • For Python: ‘gettext’, ‘ugettext’, ‘dgettext:2’,
2696 ‘ngettext:1,2’, ‘ungettext:1,2’, ‘dngettext:2,3’, ‘_’.
2698 • For Lisp: ‘gettext’, ‘ngettext:1,2’, ‘gettext-noop’.
2700 • For EmacsLisp: ‘_’.
2704 • For Scheme: ‘gettext’, ‘ngettext:1,2’, ‘gettext-noop’.
2706 • For Java: ‘GettextResource.gettext:2’,
2707 ‘GettextResource.ngettext:2,3’,
2708 ‘GettextResource.pgettext:2c,3’,
2709 ‘GettextResource.npgettext:2c,3,4’, ‘gettext’, ‘ngettext:1,2’,
2710 ‘pgettext:1c,2’, ‘npgettext:1c,2,3’, ‘getString’.
2712 • For C#: ‘GetString’, ‘GetPluralString:1,2’,
2713 ‘GetParticularString:1c,2’,
2714 ‘GetParticularPluralString:1c,2,3’.
2716 • For awk: ‘dcgettext’, ‘dcngettext:1,2’.
2718 • For Tcl: ‘::msgcat::mc’.
2720 • For Perl: ‘gettext’, ‘%gettext’, ‘$gettext’, ‘dgettext:2’,
2721 ‘dcgettext:2’, ‘ngettext:1,2’, ‘dngettext:2,3’,
2722 ‘dcngettext:2,3’, ‘gettext_noop’.
2724 • For PHP: ‘_’, ‘gettext’, ‘dgettext:2’, ‘dcgettext:2’,
2725 ‘ngettext:1,2’, ‘dngettext:2,3’, ‘dcngettext:2,3’.
2727 • For Glade 1: ‘label’, ‘title’, ‘text’, ‘format’, ‘copyright’,
2728 ‘comments’, ‘preview_text’, ‘tooltip’.
2730 • For Lua: ‘_’, ‘gettext.gettext’, ‘gettext.dgettext:2’,
2731 ‘gettext.dcgettext:2’, ‘gettext.ngettext:1,2’,
2732 ‘gettext.dngettext:2,3’, ‘gettext.dcngettext:2,3’.
2734 • For JavaScript: ‘_’, ‘gettext’, ‘dgettext:2’, ‘dcgettext:2’,
2735 ‘ngettext:1,2’, ‘dngettext:2,3’, ‘pgettext:1c,2’,
2738 • For Vala: ‘_’, ‘Q_’, ‘N_’, ‘NC_’, ‘dgettext:2’, ‘dcgettext:2’,
2739 ‘ngettext:1,2’, ‘dngettext:2,3’, ‘dpgettext:2c,3’,
2742 • For Desktop: ‘Name’, ‘GenericName’, ‘Comment’, ‘Icon’,
2745 To disable the default keyword specifications, the option ‘-k’ or
2746 ‘--keyword’ or ‘--keyword=’, without a KEYWORDSPEC, can be used.
2748 ‘--flag=WORD:ARG:FLAG’
2749 Specifies additional flags for strings occurring as part of the
2750 ARGth argument of the function WORD. The possible flags are the
2751 possible format string indicators, such as ‘c-format’, and their
2752 negations, such as ‘no-c-format’, possibly prefixed with ‘pass-’.
2753 The meaning of ‘--flag=FUNCTION:ARG:LANG-format’ is that in
2754 language LANG, the specified FUNCTION expects as ARGth argument a
2755 format string. (For those of you familiar with GCC function
2756 attributes, ‘--flag=FUNCTION:ARG:c-format’ is roughly equivalent to
2757 the declaration ‘__attribute__ ((__format__ (__printf__, ARG,
2758 ...)))’ attached to FUNCTION in a C source file.) For example, if
2759 you use the ‘error’ function from GNU libc, you can specify its
2760 behaviour through ‘--flag=error:3:c-format’. The effect of this
2761 specification is that ‘xgettext’ will mark as format strings all
2762 ‘gettext’ invocations that occur as ARGth argument of FUNCTION.
2763 This is useful when such strings contain no format string
2764 directives: together with the checks done by ‘msgfmt -c’ it will
2765 ensure that translators cannot accidentally use format string
2766 directives that would lead to a crash at runtime.
2767 The meaning of ‘--flag=FUNCTION:ARG:pass-LANG-format’ is that in
2768 language LANG, if the FUNCTION call occurs in a position that must
2769 yield a format string, then its ARGth argument must yield a format
2770 string of the same type as well. (If you know GCC function
2771 attributes, the ‘--flag=FUNCTION:ARG:pass-c-format’ option is
2772 roughly equivalent to the declaration ‘__attribute__
2773 ((__format_arg__ (ARG)))’ attached to FUNCTION in a C source file.)
2774 For example, if you use the ‘_’ shortcut for the ‘gettext’
2775 function, you should use ‘--flag=_:1:pass-c-format’. The effect of
2776 this specification is that ‘xgettext’ will propagate a format
2777 string requirement for a ‘_("string")’ call to its first argument,
2778 the literal ‘"string"’, and thus mark it as a format string. This
2779 is useful when such strings contain no format string directives:
2780 together with the checks done by ‘msgfmt -c’ it will ensure that
2781 translators cannot accidentally use format string directives that
2782 would lead to a crash at runtime.
2783 This option has an effect with most languages, namely C, C++,
2784 ObjectiveC, Shell, Python, Lisp, EmacsLisp, librep, Scheme, Java,
2785 C#, awk, YCP, Tcl, Perl, PHP, GCC-source, Lua, JavaScript, Vala.
2789 Understand ANSI C trigraphs for input.
2790 This option has an effect only with the languages C, C++,
2794 Recognize Qt format strings.
2795 This option has an effect only with the language C++.
2798 Recognize KDE 4 format strings.
2799 This option has an effect only with the language C++.
2802 Recognize Boost format strings.
2803 This option has an effect only with the language C++.
2806 Use the flags ‘c-format’ and ‘possible-c-format’ to show who was
2807 responsible for marking a message as a format string. The latter
2808 form is used if the ‘xgettext’ program decided, the former form is
2809 used if the programmer prescribed it.
2811 By default only the ‘c-format’ form is used. The translator should
2812 not have to care about these details.
2814 This implementation of ‘xgettext’ is able to process a few awkward
2815 cases, like strings in preprocessor macros, ANSI concatenation of
2816 adjacent strings, and escaped end of lines for continued strings.
2818 5.1.7 Output details
2819 --------------------
2823 Specify whether or when to use colors and other text attributes.
2824 See *note The --color option:: for details.
2826 ‘--style=STYLE_FILE’
2827 Specify the CSS style rule file to use for ‘--color’. See *note
2828 The --style option:: for details.
2831 Always write an output file even if no message is defined.
2835 Write the .po file using indented style.
2838 Do not write ‘#: FILENAME:LINE’ lines. Note that using this option
2839 makes it harder for technically skilled translators to understand
2840 each message’s context.
2843 ‘--add-location=TYPE’
2844 Generate ‘#: FILENAME:LINE’ lines (default).
2846 The optional TYPE can be either ‘full’, ‘file’, or ‘never’. If it
2847 is not given or ‘full’, it generates the lines with both file name
2848 and line number. If it is ‘file’, the line number part is omitted.
2849 If it is ‘never’, it completely suppresses the lines (same as
2853 Write out a strict Uniforum conforming PO file. Note that this
2854 Uniforum format should be avoided because it doesn’t support the
2857 ‘--properties-output’
2858 Write out a Java ResourceBundle in Java ‘.properties’ syntax. Note
2859 that this file format doesn’t support plural forms and silently
2860 drops obsolete messages.
2862 ‘--stringtable-output’
2863 Write out a NeXTstep/GNUstep localized resource file in ‘.strings’
2864 syntax. Note that this file format doesn’t support plural forms.
2867 Use ITS rules defined in FILE. Note that this is only effective
2871 Write out comments recognized by itstool (<http://itstool.org>).
2872 Note that this is only effective with XML files.
2876 Set the output page width. Long strings in the output files will
2877 be split across multiple lines in order to ensure that each line’s
2878 width (= number of screen columns) is less or equal to the given
2882 Do not break long message lines. Message lines whose width exceeds
2883 the output page width will not be split into several lines. Only
2884 file reference lines which are wider than the output page width
2889 Generate sorted output. Note that using this option makes it much
2890 harder for the translator to understand each message’s context.
2894 Sort output by file location.
2897 Don’t write header with ‘msgid ""’ entry.
2899 This is useful for testing purposes because it eliminates a source
2900 of variance for generated ‘.gmo’ files. With ‘--omit-header’, two
2901 invocations of ‘xgettext’ on the same files with the same options
2902 at different times are guaranteed to produce the same results.
2904 Note that using this option will lead to an error if the resulting
2905 file would not entirely be in ASCII.
2907 ‘--copyright-holder=STRING’
2908 Set the copyright holder in the output. STRING should be the
2909 copyright holder of the surrounding package. (Note that the msgstr
2910 strings, extracted from the package’s sources, belong to the
2911 copyright holder of the package.) Translators are expected to
2912 transfer or disclaim the copyright for their translations, so that
2913 package maintainers can distribute them without legal risk. If
2914 STRING is empty, the output files are marked as being in the public
2915 domain; in this case, the translators are expected to disclaim
2916 their copyright, again so that package maintainers can distribute
2917 them without legal risk.
2919 The default value for STRING is the Free Software Foundation, Inc.,
2920 simply because ‘xgettext’ was first used in the GNU project.
2923 Omit FSF copyright in output. This option is equivalent to
2924 ‘--copyright-holder=''’. It can be useful for packages outside the
2925 GNU project that want their translations to be in the public
2928 ‘--package-name=PACKAGE’
2929 Set the package name in the header of the output.
2931 ‘--package-version=VERSION’
2932 Set the package version in the header of the output. This option
2933 has an effect only if the ‘--package-name’ option is also used.
2935 ‘--msgid-bugs-address=EMAIL@ADDRESS’
2936 Set the reporting address for msgid bugs. This is the email
2937 address or URL to which the translators shall report bugs in the
2938 untranslated strings:
2940 - Strings which are not entire sentences; see the maintainer
2941 guidelines in *note Preparing Strings::.
2942 - Strings which use unclear terms or require additional context
2944 - Strings which make invalid assumptions about notation of date,
2946 - Pluralisation problems.
2947 - Incorrect English spelling.
2948 - Incorrect formatting.
2950 It can be your email address, or a mailing list address where
2951 translators can write to without being subscribed, or the URL of a
2952 web page through which the translators can contact you.
2954 The default value is empty, which means that translators will be
2955 clueless! Don’t forget to specify this option.
2958 ‘--msgstr-prefix[=STRING]’
2959 Use STRING (or "" if not specified) as prefix for msgstr values.
2962 ‘--msgstr-suffix[=STRING]’
2963 Use STRING (or "" if not specified) as suffix for msgstr values.
2965 5.1.8 Informative output
2966 ------------------------
2970 Display this help and exit.
2974 Output version information and exit.
2977 File: gettext.info, Node: Creating, Next: Updating, Prev: Template, Up: Top
2979 6 Creating a New PO File
2980 ************************
2982 When starting a new translation, the translator creates a file called
2983 ‘LANG.po’, as a copy of the ‘PACKAGE.pot’ template file with
2984 modifications in the initial comments (at the beginning of the file) and
2985 in the header entry (the first entry, near the beginning of the file).
2987 The easiest way to do so is by use of the ‘msginit’ program. For
2990 $ cd PACKAGE-VERSION
2994 The alternative way is to do the copy and modifications by hand. To
2995 do so, the translator copies ‘PACKAGE.pot’ to ‘LANG.po’. Then she
2996 modifies the initial comments and the header entry of this file.
3000 * msginit Invocation:: Invoking the ‘msginit’ Program
3001 * Header Entry:: Filling in the Header Entry
3004 File: gettext.info, Node: msginit Invocation, Next: Header Entry, Prev: Creating, Up: Creating
3006 6.1 Invoking the ‘msginit’ Program
3007 ==================================
3011 The ‘msginit’ program creates a new PO file, initializing the meta
3012 information with values from the user’s environment.
3014 Here are more details. The following header fields of a PO file are
3015 automatically filled, when possible.
3017 ‘Project-Id-Version’
3018 The value is guessed from the ‘configure’ script or any other files
3019 in the current directory.
3022 The value is taken from the ‘PO-Creation-Data’ in the input POT
3023 file, or the current date is used.
3026 The value is taken from user’s password file entry and the mailer
3027 configuration files.
3029 ‘Language-Team, Language’
3030 These values are set according to the current locale and the
3031 predefined list of translation teams.
3033 ‘MIME-Version, Content-Type, Content-Transfer-Encoding’
3034 These values are set according to the content of the POT file and
3035 the current locale. If the POT file contains charset=UTF-8, it
3036 means that the POT file contains non-ASCII characters, and we keep
3037 the UTF-8 encoding. Otherwise, when the POT file is plain ASCII,
3038 we use the locale’s encoding.
3041 The value is first looked up from the embedded table.
3043 As an experimental feature, you can instruct ‘msginit’ to use the
3044 information from Unicode CLDR, by setting the ‘GETTEXTCLDRDIR’
3045 environment variable.
3047 6.1.1 Input file location
3048 -------------------------
3054 If no INPUTFILE is given, the current directory is searched for the
3055 POT file. If it is ‘-’, standard input is read.
3057 6.1.2 Output file location
3058 --------------------------
3061 ‘--output-file=FILE’
3062 Write output to specified PO file.
3064 If no output file is given, it depends on the ‘--locale’ option or
3065 the user’s locale setting. If it is ‘-’, the results are written to
3068 6.1.3 Input file syntax
3069 -----------------------
3072 ‘--properties-input’
3073 Assume the input file is a Java ResourceBundle in Java
3074 ‘.properties’ syntax, not in PO file syntax.
3076 ‘--stringtable-input’
3077 Assume the input file is a NeXTstep/GNUstep localized resource file
3078 in ‘.strings’ syntax, not in PO file syntax.
3080 6.1.4 Output details
3081 --------------------
3085 Set target locale. LL should be a language code, and CC should be
3086 a country code. The command ‘locale -a’ can be used to output a
3087 list of all installed locales. The default is the user’s locale
3091 Declares that the PO file will not have a human translator and is
3092 instead automatically generated.
3096 Specify whether or when to use colors and other text attributes.
3097 See *note The --color option:: for details.
3099 ‘--style=STYLE_FILE’
3100 Specify the CSS style rule file to use for ‘--color’. See *note
3101 The --style option:: for details.
3104 ‘--properties-output’
3105 Write out a Java ResourceBundle in Java ‘.properties’ syntax. Note
3106 that this file format doesn’t support plural forms and silently
3107 drops obsolete messages.
3109 ‘--stringtable-output’
3110 Write out a NeXTstep/GNUstep localized resource file in ‘.strings’
3111 syntax. Note that this file format doesn’t support plural forms.
3115 Set the output page width. Long strings in the output files will
3116 be split across multiple lines in order to ensure that each line’s
3117 width (= number of screen columns) is less or equal to the given
3121 Do not break long message lines. Message lines whose width exceeds
3122 the output page width will not be split into several lines. Only
3123 file reference lines which are wider than the output page width
3126 6.1.5 Informative output
3127 ------------------------
3131 Display this help and exit.
3135 Output version information and exit.
3138 File: gettext.info, Node: Header Entry, Prev: msginit Invocation, Up: Creating
3140 6.2 Filling in the Header Entry
3141 ===============================
3143 The initial comments "SOME DESCRIPTIVE TITLE", "YEAR" and "FIRST
3144 AUTHOR <EMAIL@ADDRESS>, YEAR" ought to be replaced by sensible
3145 information. This can be done in any text editor; if Emacs is used and
3146 it switched to PO mode automatically (because it has recognized the
3147 file’s suffix), you can disable it by typing ‘M-x fundamental-mode’.
3149 Modifying the header entry can already be done using PO mode: in
3150 Emacs, type ‘M-x po-mode RET’ and then ‘RET’ again to start editing the
3151 entry. You should fill in the following fields.
3154 This is the name and version of the package. Fill it in if it has
3155 not already been filled in by ‘xgettext’.
3157 Report-Msgid-Bugs-To
3158 This has already been filled in by ‘xgettext’. It contains an
3159 email address or URL where you can report bugs in the untranslated
3162 - Strings which are not entire sentences, see the maintainer
3163 guidelines in *note Preparing Strings::.
3164 - Strings which use unclear terms or require additional context
3166 - Strings which make invalid assumptions about notation of date,
3168 - Pluralisation problems.
3169 - Incorrect English spelling.
3170 - Incorrect formatting.
3173 This has already been filled in by ‘xgettext’.
3176 You don’t need to fill this in. It will be filled by the PO file
3177 editor when you save the file.
3180 Fill in your name and email address (without double quotes).
3183 Fill in the English name of the language, and the email address or
3184 homepage URL of the language team you are part of.
3186 Before starting a translation, it is a good idea to get in touch
3187 with your translation team, not only to make sure you don’t do
3188 duplicated work, but also to coordinate difficult linguistic
3191 In the Free Translation Project, each translation team has its own
3192 mailing list. The up-to-date list of teams can be found at the
3193 Free Translation Project’s homepage,
3194 <http://translationproject.org/>, in the "Teams" area.
3197 Fill in the language code of the language. This can be in one of
3200 - ‘LL’, an ISO 639 two-letter language code (lowercase). See
3201 *note Language Codes:: for the list of codes.
3203 - ‘LL_CC’, where ‘LL’ is an ISO 639 two-letter language code
3204 (lowercase) and ‘CC’ is an ISO 3166 two-letter country code
3205 (uppercase). The country code specification is not redundant:
3206 Some languages have dialects in different countries. For
3207 example, ‘de_AT’ is used for Austria, and ‘pt_BR’ for Brazil.
3208 The country code serves to distinguish the dialects. See
3209 *note Language Codes:: and *note Country Codes:: for the lists
3212 - ‘LL_CC@VARIANT’, where ‘LL’ is an ISO 639 two-letter language
3213 code (lowercase), ‘CC’ is an ISO 3166 two-letter country code
3214 (uppercase), and ‘VARIANT’ is a variant designator. The
3215 variant designator (lowercase) can be a script designator,
3216 such as ‘latin’ or ‘cyrillic’.
3218 The naming convention ‘LL_CC’ is also the way locales are named on
3219 systems based on GNU libc. But there are three important
3222 • In this PO file field, but not in locale names, ‘LL_CC’
3223 combinations denoting a language’s main dialect are
3224 abbreviated as ‘LL’. For example, ‘de’ is equivalent to
3225 ‘de_DE’ (German as spoken in Germany), and ‘pt’ to ‘pt_PT’
3226 (Portuguese as spoken in Portugal) in this context.
3228 • In this PO file field, suffixes like ‘.ENCODING’ are not used.
3230 • In this PO file field, variant designators that are not
3231 relevant to message translation, such as ‘@euro’, are not
3234 So, if your locale name is ‘de_DE.UTF-8’, the language
3235 specification in PO files is just ‘de’.
3238 Replace ‘CHARSET’ with the character encoding used for your
3239 language, in your locale, or UTF-8. This field is needed for
3240 correct operation of the ‘msgmerge’ and ‘msgfmt’ programs, as well
3241 as for users whose locale’s character encoding differs from yours
3242 (see *note Charset conversion::).
3244 You get the character encoding of your locale by running the shell
3245 command ‘locale charmap’. If the result is ‘C’ or
3246 ‘ANSI_X3.4-1968’, which is equivalent to ‘ASCII’ (= ‘US-ASCII’), it
3247 means that your locale is not correctly configured. In this case,
3248 ask your translation team which charset to use. ‘ASCII’ is not
3249 usable for any language except Latin.
3251 Because the PO files must be portable to operating systems with
3252 less advanced internationalization facilities, the character
3253 encodings that can be used are limited to those supported by both
3254 GNU ‘libc’ and GNU ‘libiconv’. These are: ‘ASCII’, ‘ISO-8859-1’,
3255 ‘ISO-8859-2’, ‘ISO-8859-3’, ‘ISO-8859-4’, ‘ISO-8859-5’,
3256 ‘ISO-8859-6’, ‘ISO-8859-7’, ‘ISO-8859-8’, ‘ISO-8859-9’,
3257 ‘ISO-8859-13’, ‘ISO-8859-14’, ‘ISO-8859-15’, ‘KOI8-R’, ‘KOI8-U’,
3258 ‘KOI8-T’, ‘CP850’, ‘CP866’, ‘CP874’, ‘CP932’, ‘CP949’, ‘CP950’,
3259 ‘CP1250’, ‘CP1251’, ‘CP1252’, ‘CP1253’, ‘CP1254’, ‘CP1255’,
3260 ‘CP1256’, ‘CP1257’, ‘GB2312’, ‘EUC-JP’, ‘EUC-KR’, ‘EUC-TW’, ‘BIG5’,
3261 ‘BIG5-HKSCS’, ‘GBK’, ‘GB18030’, ‘SHIFT_JIS’, ‘JOHAB’, ‘TIS-620’,
3262 ‘VISCII’, ‘GEORGIAN-PS’, ‘UTF-8’.
3264 In the GNU system, the following encodings are frequently used for
3265 the corresponding languages.
3267 • ‘ISO-8859-1’ for Afrikaans, Albanian, Basque, Breton, Catalan,
3268 Cornish, Danish, Dutch, English, Estonian, Faroese, Finnish,
3269 French, Galician, German, Greenlandic, Icelandic, Indonesian,
3270 Irish, Italian, Malay, Manx, Norwegian, Occitan, Portuguese,
3271 Spanish, Swedish, Tagalog, Uzbek, Walloon,
3272 • ‘ISO-8859-2’ for Bosnian, Croatian, Czech, Hungarian, Polish,
3273 Romanian, Serbian, Slovak, Slovenian,
3274 • ‘ISO-8859-3’ for Maltese,
3275 • ‘ISO-8859-5’ for Macedonian, Serbian,
3276 • ‘ISO-8859-6’ for Arabic,
3277 • ‘ISO-8859-7’ for Greek,
3278 • ‘ISO-8859-8’ for Hebrew,
3279 • ‘ISO-8859-9’ for Turkish,
3280 • ‘ISO-8859-13’ for Latvian, Lithuanian, Maori,
3281 • ‘ISO-8859-14’ for Welsh,
3282 • ‘ISO-8859-15’ for Basque, Catalan, Dutch, English, Finnish,
3283 French, Galician, German, Irish, Italian, Portuguese, Spanish,
3285 • ‘KOI8-R’ for Russian,
3286 • ‘KOI8-U’ for Ukrainian,
3287 • ‘KOI8-T’ for Tajik,
3288 • ‘CP1251’ for Bulgarian, Belarusian,
3289 • ‘GB2312’, ‘GBK’, ‘GB18030’ for simplified writing of Chinese,
3290 • ‘BIG5’, ‘BIG5-HKSCS’ for traditional writing of Chinese,
3291 • ‘EUC-JP’ for Japanese,
3292 • ‘EUC-KR’ for Korean,
3293 • ‘TIS-620’ for Thai,
3294 • ‘GEORGIAN-PS’ for Georgian,
3295 • ‘UTF-8’ for any language, including those listed above.
3297 When single quote characters or double quote characters are used in
3298 translations for your language, and your locale’s encoding is one
3299 of the ISO-8859-* charsets, it is best if you create your PO files
3300 in UTF-8 encoding, instead of your locale’s encoding. This is
3301 because in UTF-8 the real quote characters can be represented
3302 (single quote characters: U+2018, U+2019, double quote characters:
3303 U+201C, U+201D), whereas none of ISO-8859-* charsets has them all.
3304 Users in UTF-8 locales will see the real quote characters, whereas
3305 users in ISO-8859-* locales will see the vertical apostrophe and
3306 the vertical double quote instead (because that’s what the
3307 character set conversion will transliterate them to).
3309 To enter such quote characters under X11, you can change your
3310 keyboard mapping using the ‘xmodmap’ program. The X11 names of the
3311 quote characters are "leftsinglequotemark", "rightsinglequotemark",
3312 "leftdoublequotemark", "rightdoublequotemark",
3313 "singlelowquotemark", "doublelowquotemark".
3315 Note that only recent versions of GNU Emacs support the UTF-8
3316 encoding: Emacs 20 with Mule-UCS, and Emacs 21. As of January
3317 2001, XEmacs doesn’t support the UTF-8 encoding.
3319 The character encoding name can be written in either upper or lower
3320 case. Usually upper case is preferred.
3322 Content-Transfer-Encoding
3326 This field is optional. It is only needed if the PO file has
3327 plural forms. You can find them by searching for the
3328 ‘msgid_plural’ keyword. The format of the plural forms field is
3329 described in *note Plural forms:: and *note Translating plural
3333 File: gettext.info, Node: Updating, Next: Editing, Prev: Creating, Up: Top
3335 7 Updating Existing PO Files
3336 ****************************
3340 * msgmerge Invocation:: Invoking the ‘msgmerge’ Program
3343 File: gettext.info, Node: msgmerge Invocation, Prev: Updating, Up: Updating
3345 7.1 Invoking the ‘msgmerge’ Program
3346 ===================================
3348 msgmerge [OPTION] DEF.po REF.pot
3350 The ‘msgmerge’ program merges two Uniforum style .po files together.
3351 The DEF.po file is an existing PO file with translations which will be
3352 taken over to the newly created file as long as they still match;
3353 comments will be preserved, but extracted comments and file positions
3354 will be discarded. The REF.pot file is the last created PO file with
3355 up-to-date source references but old translations, or a PO Template file
3356 (generally created by ‘xgettext’); any translations or comments in the
3357 file will be discarded, however dot comments and file positions will be
3358 preserved. Where an exact match cannot be found, fuzzy matching is used
3359 to produce better results.
3361 7.1.1 Input file location
3362 -------------------------
3365 Translations referring to old sources.
3368 References to the new sources.
3371 ‘--directory=DIRECTORY’
3372 Add DIRECTORY to the list of directories. Source files are
3373 searched relative to this list of directories. The resulting ‘.po’
3374 file will be written relative to the current directory, though.
3378 Specify an additional library of message translations. *Note
3379 Compendium::. This option may be specified more than once.
3381 7.1.2 Operation mode
3382 --------------------
3386 Update DEF.po. Do nothing if DEF.po is already up to date.
3388 7.1.3 Output file location
3389 --------------------------
3392 ‘--output-file=FILE’
3393 Write output to specified file.
3395 The results are written to standard output if no output file is
3396 specified or if it is ‘-’.
3398 7.1.4 Output file location in update mode
3399 -----------------------------------------
3401 The result is written back to DEF.po.
3404 Make a backup of DEF.po
3407 Override the usual backup suffix.
3409 The version control method may be selected via the ‘--backup’ option
3410 or through the ‘VERSION_CONTROL’ environment variable. Here are the
3415 Never make backups (even if ‘--backup’ is given).
3419 Make numbered backups.
3423 Make numbered backups if numbered backups for this file already
3424 exist, otherwise make simple backups.
3428 Always make simple backups.
3430 The backup suffix is ‘~’, unless set with ‘--suffix’ or the
3431 ‘SIMPLE_BACKUP_SUFFIX’ environment variable.
3433 7.1.5 Operation modifiers
3434 -------------------------
3438 Apply REF.pot to each of the domains in DEF.po.
3441 ‘--no-fuzzy-matching’
3442 Do not use fuzzy matching when an exact match is not found. This
3443 may speed up the operation considerably.
3446 Keep the previous msgids of translated messages, marked with ‘#|’,
3447 when adding the fuzzy marker to such messages.
3449 7.1.6 Input file syntax
3450 -----------------------
3453 ‘--properties-input’
3454 Assume the input files are Java ResourceBundles in Java
3455 ‘.properties’ syntax, not in PO file syntax.
3457 ‘--stringtable-input’
3458 Assume the input files are NeXTstep/GNUstep localized resource
3459 files in ‘.strings’ syntax, not in PO file syntax.
3461 7.1.7 Output details
3462 --------------------
3464 ‘--lang=CATALOGNAME’
3465 Specify the ‘Language’ field to be used in the header entry. See
3466 *note Header Entry:: for the meaning of this field. Note: The
3467 ‘Language-Team’ and ‘Plural-Forms’ fields are left unchanged. If
3468 this option is not specified, the ‘Language’ field is inferred, as
3469 best as possible, from the ‘Language-Team’ field.
3473 Specify whether or when to use colors and other text attributes.
3474 See *note The --color option:: for details.
3476 ‘--style=STYLE_FILE’
3477 Specify the CSS style rule file to use for ‘--color’. See *note
3478 The --style option:: for details.
3481 Always write an output file even if it contains no message.
3485 Write the .po file using indented style.
3488 Do not write ‘#: FILENAME:LINE’ lines.
3491 ‘--add-location=TYPE’
3492 Generate ‘#: FILENAME:LINE’ lines (default).
3494 The optional TYPE can be either ‘full’, ‘file’, or ‘never’. If it
3495 is not given or ‘full’, it generates the lines with both file name
3496 and line number. If it is ‘file’, the line number part is omitted.
3497 If it is ‘never’, it completely suppresses the lines (same as
3501 Write out a strict Uniforum conforming PO file. Note that this
3502 Uniforum format should be avoided because it doesn’t support the
3506 ‘--properties-output’
3507 Write out a Java ResourceBundle in Java ‘.properties’ syntax. Note
3508 that this file format doesn’t support plural forms and silently
3509 drops obsolete messages.
3511 ‘--stringtable-output’
3512 Write out a NeXTstep/GNUstep localized resource file in ‘.strings’
3513 syntax. Note that this file format doesn’t support plural forms.
3517 Set the output page width. Long strings in the output files will
3518 be split across multiple lines in order to ensure that each line’s
3519 width (= number of screen columns) is less or equal to the given
3523 Do not break long message lines. Message lines whose width exceeds
3524 the output page width will not be split into several lines. Only
3525 file reference lines which are wider than the output page width
3530 Generate sorted output. Note that using this option makes it much
3531 harder for the translator to understand each message’s context.
3535 Sort output by file location.
3537 7.1.8 Informative output
3538 ------------------------
3542 Display this help and exit.
3546 Output version information and exit.
3550 Increase verbosity level.
3555 Suppress progress indicators.
3558 File: gettext.info, Node: Editing, Next: Manipulating, Prev: Updating, Up: Top
3565 * KBabel:: KDE’s PO File Editor
3566 * Gtranslator:: GNOME’s PO File Editor
3567 * PO Mode:: Emacs’s PO File Editor
3568 * Compendium:: Using Translation Compendia
3571 File: gettext.info, Node: KBabel, Next: Gtranslator, Prev: Editing, Up: Editing
3573 8.1 KDE’s PO File Editor
3574 ========================
3577 File: gettext.info, Node: Gtranslator, Next: PO Mode, Prev: KBabel, Up: Editing
3579 8.2 GNOME’s PO File Editor
3580 ==========================
3583 File: gettext.info, Node: PO Mode, Next: Compendium, Prev: Gtranslator, Up: Editing
3585 8.3 Emacs’s PO File Editor
3586 ==========================
3588 For those of you being the lucky users of Emacs, PO mode has been
3589 specifically created for providing a cozy environment for editing or
3590 modifying PO files. While editing a PO file, PO mode allows for the
3591 easy browsing of auxiliary and compendium PO files, as well as for
3592 following references into the set of C program sources from which PO
3593 files have been derived. It has a few special features, among which are
3594 the interactive marking of program strings as translatable, and the
3595 validation of PO files with easy repositioning to PO file lines showing
3598 For the beginning, besides main PO mode commands (*note Main PO
3599 Commands::), you should know how to move between entries (*note Entry
3600 Positioning::), and how to handle untranslated entries (*note
3601 Untranslated Entries::).
3605 * Installation:: Completing GNU ‘gettext’ Installation
3606 * Main PO Commands:: Main Commands
3607 * Entry Positioning:: Entry Positioning
3608 * Normalizing:: Normalizing Strings in Entries
3609 * Translated Entries:: Translated Entries
3610 * Fuzzy Entries:: Fuzzy Entries
3611 * Untranslated Entries:: Untranslated Entries
3612 * Obsolete Entries:: Obsolete Entries
3613 * Modifying Translations:: Modifying Translations
3614 * Modifying Comments:: Modifying Comments
3615 * Subedit:: Mode for Editing Translations
3616 * C Sources Context:: C Sources Context
3617 * Auxiliary:: Consulting Auxiliary PO Files
3620 File: gettext.info, Node: Installation, Next: Main PO Commands, Prev: PO Mode, Up: PO Mode
3622 8.3.1 Completing GNU ‘gettext’ Installation
3623 -------------------------------------------
3625 Once you have received, unpacked, configured and compiled the GNU
3626 ‘gettext’ distribution, the ‘make install’ command puts in place the
3627 programs ‘xgettext’, ‘msgfmt’, ‘gettext’, and ‘msgmerge’, as well as
3628 their available message catalogs. To top off a comfortable
3629 installation, you might also want to make the PO mode available to your
3632 During the installation of the PO mode, you might want to modify your
3633 file ‘.emacs’, once and for all, so it contains a few lines looking
3636 (setq auto-mode-alist
3637 (cons '("\\.po\\'\\|\\.po\\." . po-mode) auto-mode-alist))
3638 (autoload 'po-mode "po-mode" "Major mode for translators to edit PO files" t)
3640 Later, whenever you edit some ‘.po’ file, or any file having the
3641 string ‘.po.’ within its name, Emacs loads ‘po-mode.elc’ (or
3642 ‘po-mode.el’) as needed, and automatically activates PO mode commands
3643 for the associated buffer. The string _PO_ appears in the mode line for
3644 any buffer for which PO mode is active. Many PO files may be active at
3645 once in a single Emacs session.
3647 If you are using Emacs version 20 or newer, and have already
3648 installed the appropriate international fonts on your system, you may
3649 also tell Emacs how to determine automatically the coding system of
3650 every PO file. This will often (but not always) cause the necessary
3651 fonts to be loaded and used for displaying the translations on your
3652 Emacs screen. For this to happen, add the lines:
3654 (modify-coding-system-alist 'file "\\.po\\'\\|\\.po\\."
3655 'po-find-file-coding-system)
3656 (autoload 'po-find-file-coding-system "po-mode")
3658 to your ‘.emacs’ file. If, with this, you still see boxes instead of
3659 international characters, try a different font set (via Shift Mouse
3663 File: gettext.info, Node: Main PO Commands, Next: Entry Positioning, Prev: Installation, Up: PO Mode
3665 8.3.2 Main PO mode Commands
3666 ---------------------------
3668 After setting up Emacs with something similar to the lines in *note
3669 Installation::, PO mode is activated for a window when Emacs finds a PO
3670 file in that window. This puts the window read-only and establishes a
3671 po-mode-map, which is a genuine Emacs mode, in a way that is not derived
3672 from text mode in any way. Functions found on ‘po-mode-hook’, if any,
3675 When PO mode is active in a window, the letters ‘PO’ appear in the
3676 mode line for that window. The mode line also displays how many entries
3677 of each kind are held in the PO file. For example, the string
3678 ‘132t+3f+10u+2o’ would tell the translator that the PO mode contains 132
3679 translated entries (*note Translated Entries::, 3 fuzzy entries (*note
3680 Fuzzy Entries::), 10 untranslated entries (*note Untranslated Entries::)
3681 and 2 obsolete entries (*note Obsolete Entries::). Zero-coefficients
3682 items are not shown. So, in this example, if the fuzzy entries were
3683 unfuzzied, the untranslated entries were translated and the obsolete
3684 entries were deleted, the mode line would merely display ‘145t’ for the
3687 The main PO commands are those which do not fit into the other
3688 categories of subsequent sections. These allow for quitting PO mode or
3689 for managing windows in special ways.
3692 Undo last modification to the PO file (‘po-undo’).
3695 Quit processing and save the PO file (‘po-quit’).
3698 Quit processing, possibly after confirmation
3699 (‘po-confirm-and-quit’).
3702 Temporary leave the PO file window (‘po-other-window’).
3706 Show help about PO mode (‘po-help’).
3709 Give some PO file statistics (‘po-statistics’).
3712 Batch validate the format of the whole PO file (‘po-validate’).
3714 The command ‘_’ (‘po-undo’) interfaces to the Emacs _undo_ facility.
3715 *Note Undoing Changes: (emacs)Undo. Each time ‘_’ is typed,
3716 modifications which the translator did to the PO file are undone a
3717 little more. For the purpose of undoing, each PO mode command is
3718 atomic. This is especially true for the ‘<RET>’ command: the whole
3719 edition made by using a single use of this command is undone at once,
3720 even if the edition itself implied several actions. However, while in
3721 the editing window, one can undo the edition work quite parsimoniously.
3723 The commands ‘Q’ (‘po-quit’) and ‘q’ (‘po-confirm-and-quit’) are used
3724 when the translator is done with the PO file. The former is a bit less
3725 verbose than the latter. If the file has been modified, it is saved to
3726 disk first. In both cases, and prior to all this, the commands check if
3727 any untranslated messages remain in the PO file and, if so, the
3728 translator is asked if she really wants to leave off working with this
3729 PO file. This is the preferred way of getting rid of an Emacs PO file
3730 buffer. Merely killing it through the usual command ‘C-x k’
3731 (‘kill-buffer’) is not the tidiest way to proceed.
3733 The command ‘0’ (‘po-other-window’) is another, softer way, to leave
3734 PO mode, temporarily. It just moves the cursor to some other Emacs
3735 window, and pops one if necessary. For example, if the translator just
3736 got PO mode to show some source context in some other, she might
3737 discover some apparent bug in the program source that needs correction.
3738 This command allows the translator to change sex, become a programmer,
3739 and have the cursor right into the window containing the program she (or
3740 rather _he_) wants to modify. By later getting the cursor back in the
3741 PO file window, or by asking Emacs to edit this file once again, PO mode
3744 The command ‘h’ (‘po-help’) displays a summary of all available PO
3745 mode commands. The translator should then type any character to resume
3746 normal PO mode operations. The command ‘?’ has the same effect as ‘h’.
3748 The command ‘=’ (‘po-statistics’) computes the total number of
3749 entries in the PO file, the ordinal of the current entry (counted from
3750 1), the number of untranslated entries, the number of obsolete entries,
3751 and displays all these numbers.
3753 The command ‘V’ (‘po-validate’) launches ‘msgfmt’ in checking and
3754 verbose mode over the current PO file. This command first offers to
3755 save the current PO file on disk. The ‘msgfmt’ tool, from GNU
3756 ‘gettext’, has the purpose of creating a MO file out of a PO file, and
3757 PO mode uses the features of this program for checking the overall
3758 format of a PO file, as well as all individual entries.
3760 The program ‘msgfmt’ runs asynchronously with Emacs, so the
3761 translator regains control immediately while her PO file is being
3762 studied. Error output is collected in the Emacs ‘*compilation*’ buffer,
3763 displayed in another window. The regular Emacs command ‘C-x`’
3764 (‘next-error’), as well as other usual compile commands, allow the
3765 translator to reposition quickly to the offending parts of the PO file.
3766 Once the cursor is on the line in error, the translator may decide on
3767 any PO mode action which would help correcting the error.
3770 File: gettext.info, Node: Entry Positioning, Next: Normalizing, Prev: Main PO Commands, Up: PO Mode
3772 8.3.3 Entry Positioning
3773 -----------------------
3775 The cursor in a PO file window is almost always part of an entry.
3776 The only exceptions are the special case when the cursor is after the
3777 last entry in the file, or when the PO file is empty. The entry where
3778 the cursor is found to be is said to be the current entry. Many PO mode
3779 commands operate on the current entry, so moving the cursor does more
3780 than allowing the translator to browse the PO file, this also selects on
3781 which entry commands operate.
3783 Some PO mode commands alter the position of the cursor in a
3784 specialized way. A few of those special purpose positioning are
3785 described here, the others are described in following sections (for a
3786 complete list try ‘C-h m’):
3789 Redisplay the current entry (‘po-current-entry’).
3792 Select the entry after the current one (‘po-next-entry’).
3795 Select the entry before the current one (‘po-previous-entry’).
3798 Select the first entry in the PO file (‘po-first-entry’).
3801 Select the last entry in the PO file (‘po-last-entry’).
3804 Record the location of the current entry for later use
3805 (‘po-push-location’).
3808 Return to a previously saved entry location (‘po-pop-location’).
3811 Exchange the current entry location with the previously saved one
3812 (‘po-exchange-location’).
3814 Any Emacs command able to reposition the cursor may be used to select
3815 the current entry in PO mode, including commands which move by
3816 characters, lines, paragraphs, screens or pages, and search commands.
3817 However, there is a kind of standard way to display the current entry in
3818 PO mode, which usual Emacs commands moving the cursor do not especially
3819 try to enforce. The command ‘.’ (‘po-current-entry’) has the sole
3820 purpose of redisplaying the current entry properly, after the current
3821 entry has been changed by means external to PO mode, or the Emacs screen
3824 It is yet to be decided if PO mode helps the translator, or otherwise
3825 irritates her, by forcing a rigid window disposition while she is doing
3826 her work. We originally had quite precise ideas about how windows
3827 should behave, but on the other hand, anyone used to Emacs is often
3828 happy to keep full control. Maybe a fixed window disposition might be
3829 offered as a PO mode option that the translator might activate or
3830 deactivate at will, so it could be offered on an experimental basis. If
3831 nobody feels a real need for using it, or a compulsion for writing it,
3832 we should drop this whole idea. The incentive for doing it should come
3833 from translators rather than programmers, as opinions from an
3834 experienced translator are surely more worth to me than opinions from
3835 programmers _thinking_ about how _others_ should do translation.
3837 The commands ‘n’ (‘po-next-entry’) and ‘p’ (‘po-previous-entry’) move
3838 the cursor the entry following, or preceding, the current one. If ‘n’
3839 is given while the cursor is on the last entry of the PO file, or if ‘p’
3840 is given while the cursor is on the first entry, no move is done.
3842 The commands ‘<’ (‘po-first-entry’) and ‘>’ (‘po-last-entry’) move
3843 the cursor to the first entry, or last entry, of the PO file. When the
3844 cursor is located past the last entry in a PO file, most PO mode
3845 commands will return an error saying ‘After last entry’. Moreover, the
3846 commands ‘<’ and ‘>’ have the special property of being able to work
3847 even when the cursor is not into some PO file entry, and one may use
3848 them for nicely correcting this situation. But even these commands will
3849 fail on a truly empty PO file. There are development plans for the PO
3850 mode for it to interactively fill an empty PO file from sources. *Note
3853 The translator may decide, before working at the translation of a
3854 particular entry, that she needs to browse the remainder of the PO file,
3855 maybe for finding the terminology or phraseology used in related
3856 entries. She can of course use the standard Emacs idioms for saving the
3857 current cursor location in some register, and use that register for
3858 getting back, or else, use the location ring.
3860 PO mode offers another approach, by which cursor locations may be
3861 saved onto a special stack. The command ‘m’ (‘po-push-location’) merely
3862 adds the location of current entry to the stack, pushing the already
3863 saved locations under the new one. The command ‘r’ (‘po-pop-location’)
3864 consumes the top stack element and repositions the cursor to the entry
3865 associated with that top element. This position is then lost, for the
3866 next ‘r’ will move the cursor to the previously saved location, and so
3867 on until no locations remain on the stack.
3869 If the translator wants the position to be kept on the location
3870 stack, maybe for taking a look at the entry associated with the top
3871 element, then go elsewhere with the intent of getting back later, she
3872 ought to use ‘m’ immediately after ‘r’.
3874 The command ‘x’ (‘po-exchange-location’) simultaneously repositions
3875 the cursor to the entry associated with the top element of the stack of
3876 saved locations, and replaces that top element with the location of the
3877 current entry before the move. Consequently, repeating the ‘x’ command
3878 toggles alternatively between two entries. For achieving this, the
3879 translator will position the cursor on the first entry, use ‘m’, then
3880 position to the second entry, and merely use ‘x’ for making the switch.
3883 File: gettext.info, Node: Normalizing, Next: Translated Entries, Prev: Entry Positioning, Up: PO Mode
3885 8.3.4 Normalizing Strings in Entries
3886 ------------------------------------
3888 There are many different ways for encoding a particular string into a
3889 PO file entry, because there are so many different ways to split and
3890 quote multi-line strings, and even, to represent special characters by
3891 backslashed escaped sequences. Some features of PO mode rely on the
3892 ability for PO mode to scan an already existing PO file for a particular
3893 string encoded into the ‘msgid’ field of some entry. Even if PO mode
3894 has internally all the built-in machinery for implementing this
3895 recognition easily, doing it fast is technically difficult. To
3896 facilitate a solution to this efficiency problem, we decided on a
3897 canonical representation for strings.
3899 A conventional representation of strings in a PO file is currently
3900 under discussion, and PO mode experiments with a canonical
3901 representation. Having both ‘xgettext’ and PO mode converging towards a
3902 uniform way of representing equivalent strings would be useful, as the
3903 internal normalization needed by PO mode could be automatically
3904 satisfied when using ‘xgettext’ from GNU ‘gettext’. An explicit PO mode
3905 normalization should then be only necessary for PO files imported from
3906 elsewhere, or for when the convention itself evolves.
3908 So, for achieving normalization of at least the strings of a given PO
3909 file needing a canonical representation, the following PO mode command
3913 Tidy the whole PO file by making entries more uniform.
3915 The special command ‘M-x po-normalize’, which has no associated keys,
3916 revises all entries, ensuring that strings of both original and
3917 translated entries use uniform internal quoting in the PO file. It also
3918 removes any crumb after the last entry. This command may be useful for
3919 PO files freshly imported from elsewhere, or if we ever improve on the
3920 canonical quoting format we use. This canonical format is not only
3921 meant for getting cleaner PO files, but also for greatly speeding up
3922 ‘msgid’ string lookup for some other PO mode commands.
3924 ‘M-x po-normalize’ presently makes three passes over the entries.
3925 The first implements heuristics for converting PO files for GNU
3926 ‘gettext’ 0.6 and earlier, in which ‘msgid’ and ‘msgstr’ fields were
3927 using K&R style C string syntax for multi-line strings. These
3928 heuristics may fail for comments not related to obsolete entries and
3929 ending with a backslash; they also depend on subsequent passes for
3930 finalizing the proper commenting of continued lines for obsolete
3931 entries. This first pass might disappear once all oldish PO files would
3932 have been adjusted. The second and third pass normalize all ‘msgid’ and
3933 ‘msgstr’ strings respectively. They also clean out those trailing
3934 backslashes used by XView’s ‘msgfmt’ for continued lines.
3936 Having such an explicit normalizing command allows for importing PO
3937 files from other sources, but also eases the evolution of the current
3938 convention, evolution driven mostly by aesthetic concerns, as of now.
3939 It is easy to make suggested adjustments at a later time, as the
3940 normalizing command and eventually, other GNU ‘gettext’ tools should
3941 greatly automate conformance. A description of the canonical string
3942 format is given below, for the particular benefit of those not having
3943 Emacs handy, and who would nevertheless want to handcraft their PO files
3946 Right now, in PO mode, strings are single line or multi-line. A
3947 string goes multi-line if and only if it has _embedded_ newlines, that
3948 is, if it matches ‘[^\n]\n+[^\n]’. So, we would have:
3950 msgstr "\n\nHello, world!\n\n\n"
3952 but, replacing the space by a newline, this becomes:
3962 We are deliberately using a caricatural example, here, to make the
3963 point clearer. Usually, multi-lines are not that bad looking. It is
3964 probable that we will implement the following suggestion. We might lump
3965 together all initial newlines into the empty string, and also all
3966 newlines introducing empty lines (that is, for N > 1, the N-1’th last
3967 newlines would go together on a separate string), so making the previous
3975 There are a few yet undecided little points about string
3976 normalization, to be documented in this manual, once these questions
3980 File: gettext.info, Node: Translated Entries, Next: Fuzzy Entries, Prev: Normalizing, Up: PO Mode
3982 8.3.5 Translated Entries
3983 ------------------------
3985 Each PO file entry for which the ‘msgstr’ field has been filled with
3986 a translation, and which is not marked as fuzzy (*note Fuzzy Entries::),
3987 is said to be a "translated" entry. Only translated entries will later
3988 be compiled by GNU ‘msgfmt’ and become usable in programs. Other entry
3989 types will be excluded; translation will not occur for them.
3991 Some commands are more specifically related to translated entry
3995 Find the next translated entry (‘po-next-translated-entry’).
3998 Find the previous translated entry
3999 (‘po-previous-translated-entry’).
4001 The commands ‘t’ (‘po-next-translated-entry’) and ‘T’
4002 (‘po-previous-translated-entry’) move forwards or backwards, chasing for
4003 an translated entry. If none is found, the search is extended and wraps
4004 around in the PO file buffer.
4006 Translated entries usually result from the translator having edited
4007 in a translation for them, *note Modifying Translations::. However, if
4008 the variable ‘po-auto-fuzzy-on-edit’ is not ‘nil’, the entry having
4009 received a new translation first becomes a fuzzy entry, which ought to
4010 be later unfuzzied before becoming an official, genuine translated
4011 entry. *Note Fuzzy Entries::.
4014 File: gettext.info, Node: Fuzzy Entries, Next: Untranslated Entries, Prev: Translated Entries, Up: PO Mode
4019 Each PO file entry may have a set of "attributes", which are
4020 qualities given a name and explicitly associated with the translation,
4021 using a special system comment. One of these attributes has the name
4022 ‘fuzzy’, and entries having this attribute are said to have a fuzzy
4023 translation. They are called fuzzy entries, for short.
4025 Fuzzy entries, even if they account for translated entries for most
4026 other purposes, usually call for revision by the translator. Those may
4027 be produced by applying the program ‘msgmerge’ to update an older
4028 translated PO files according to a new PO template file, when this tool
4029 hypothesises that some new ‘msgid’ has been modified only slightly out
4030 of an older one, and chooses to pair what it thinks to be the old
4031 translation for the new modified entry. The slight alteration in the
4032 original string (the ‘msgid’ string) should often be reflected in the
4033 translated string, and this requires the intervention of the translator.
4034 For this reason, ‘msgmerge’ might mark some entries as being fuzzy.
4036 Also, the translator may decide herself to mark an entry as fuzzy for
4037 her own convenience, when she wants to remember that the entry has to be
4038 later revisited. So, some commands are more specifically related to
4039 fuzzy entry processing.
4042 Find the next fuzzy entry (‘po-next-fuzzy-entry’).
4045 Find the previous fuzzy entry (‘po-previous-fuzzy-entry’).
4048 Remove the fuzzy attribute of the current entry (‘po-unfuzzy’).
4050 The commands ‘f’ (‘po-next-fuzzy-entry’) and ‘F’
4051 (‘po-previous-fuzzy-entry’) move forwards or backwards, chasing for a
4052 fuzzy entry. If none is found, the search is extended and wraps around
4053 in the PO file buffer.
4055 The command ‘<TAB>’ (‘po-unfuzzy’) removes the fuzzy attribute
4056 associated with an entry, usually leaving it translated. Further, if
4057 the variable ‘po-auto-select-on-unfuzzy’ has not the ‘nil’ value, the
4058 ‘<TAB>’ command will automatically chase for another interesting entry
4059 to work on. The initial value of ‘po-auto-select-on-unfuzzy’ is ‘nil’.
4061 The initial value of ‘po-auto-fuzzy-on-edit’ is ‘nil’. However, if
4062 the variable ‘po-auto-fuzzy-on-edit’ is set to ‘t’, any entry edited
4063 through the ‘<RET>’ command is marked fuzzy, as a way to ensure some
4064 kind of double check, later. In this case, the usual paradigm is that
4065 an entry becomes fuzzy (if not already) whenever the translator modifies
4066 it. If she is satisfied with the translation, she then uses ‘<TAB>’ to
4067 pick another entry to work on, clearing the fuzzy attribute on the same
4068 blow. If she is not satisfied yet, she merely uses ‘<SPC>’ to chase
4069 another entry, leaving the entry fuzzy.
4071 The translator may also use the ‘<DEL>’ command (‘po-fade-out-entry’)
4072 over any translated entry to mark it as being fuzzy, when she wants to
4073 easily leave a trace she wants to later return working at this entry.
4075 Also, when time comes to quit working on a PO file buffer with the
4076 ‘q’ command, the translator is asked for confirmation, if fuzzy string
4080 File: gettext.info, Node: Untranslated Entries, Next: Obsolete Entries, Prev: Fuzzy Entries, Up: PO Mode
4082 8.3.7 Untranslated Entries
4083 --------------------------
4085 When ‘xgettext’ originally creates a PO file, unless told otherwise,
4086 it initializes the ‘msgid’ field with the untranslated string, and
4087 leaves the ‘msgstr’ string to be empty. Such entries, having an empty
4088 translation, are said to be "untranslated" entries. Later, when the
4089 programmer slightly modifies some string right in the program, this
4090 change is later reflected in the PO file by the appearance of a new
4091 untranslated entry for the modified string.
4093 The usual commands moving from entry to entry consider untranslated
4094 entries on the same level as active entries. Untranslated entries are
4095 easily recognizable by the fact they end with ‘msgstr ""’.
4097 The work of the translator might be (quite naively) seen as the
4098 process of seeking for an untranslated entry, editing a translation for
4099 it, and repeating these actions until no untranslated entries remain.
4100 Some commands are more specifically related to untranslated entry
4104 Find the next untranslated entry (‘po-next-untranslated-entry’).
4107 Find the previous untranslated entry
4108 (‘po-previous-untransted-entry’).
4111 Turn the current entry into an untranslated one (‘po-kill-msgstr’).
4113 The commands ‘u’ (‘po-next-untranslated-entry’) and ‘U’
4114 (‘po-previous-untransted-entry’) move forwards or backwards, chasing for
4115 an untranslated entry. If none is found, the search is extended and
4116 wraps around in the PO file buffer.
4118 An entry can be turned back into an untranslated entry by merely
4119 emptying its translation, using the command ‘k’ (‘po-kill-msgstr’).
4120 *Note Modifying Translations::.
4122 Also, when time comes to quit working on a PO file buffer with the
4123 ‘q’ command, the translator is asked for confirmation, if some
4124 untranslated string still exists.
4127 File: gettext.info, Node: Obsolete Entries, Next: Modifying Translations, Prev: Untranslated Entries, Up: PO Mode
4129 8.3.8 Obsolete Entries
4130 ----------------------
4132 By "obsolete" PO file entries, we mean those entries which are
4133 commented out, usually by ‘msgmerge’ when it found that the translation
4134 is not needed anymore by the package being localized.
4136 The usual commands moving from entry to entry consider obsolete
4137 entries on the same level as active entries. Obsolete entries are
4138 easily recognizable by the fact that all their lines start with ‘#’,
4139 even those lines containing ‘msgid’ or ‘msgstr’.
4141 Commands exist for emptying the translation or reinitializing it to
4142 the original untranslated string. Commands interfacing with the kill
4143 ring may force some previously saved text into the translation. The
4144 user may interactively edit the translation. All these commands may
4145 apply to obsolete entries, carefully leaving the entry obsolete after
4148 Moreover, some commands are more specifically related to obsolete
4152 Find the next obsolete entry (‘po-next-obsolete-entry’).
4155 Find the previous obsolete entry (‘po-previous-obsolete-entry’).
4158 Make an active entry obsolete, or zap out an obsolete entry
4159 (‘po-fade-out-entry’).
4161 The commands ‘o’ (‘po-next-obsolete-entry’) and ‘O’
4162 (‘po-previous-obsolete-entry’) move forwards or backwards, chasing for
4163 an obsolete entry. If none is found, the search is extended and wraps
4164 around in the PO file buffer.
4166 PO mode does not provide ways for un-commenting an obsolete entry and
4167 making it active, because this would reintroduce an original
4168 untranslated string which does not correspond to any marked string in
4169 the program sources. This goes with the philosophy of never introducing
4170 useless ‘msgid’ values.
4172 However, it is possible to comment out an active entry, so making it
4173 obsolete. GNU ‘gettext’ utilities will later react to the disappearance
4174 of a translation by using the untranslated string. The command ‘<DEL>’
4175 (‘po-fade-out-entry’) pushes the current entry a little further towards
4176 annihilation. If the entry is active (it is a translated entry), then
4177 it is first made fuzzy. If it is already fuzzy, then the entry is
4178 merely commented out, with confirmation. If the entry is already
4179 obsolete, then it is completely deleted from the PO file. It is easy to
4180 recycle the translation so deleted into some other PO file entry,
4181 usually one which is untranslated. *Note Modifying Translations::.
4183 Here is a quite interesting problem to solve for later development of
4184 PO mode, for those nights you are not sleepy. The idea would be that PO
4185 mode might become bright enough, one of these days, to make good guesses
4186 at retrieving the most probable candidate, among all obsolete entries,
4187 for initializing the translation of a newly appeared string. I think it
4188 might be a quite hard problem to do this algorithmically, as we have to
4189 develop good and efficient measures of string similarity. Right now, PO
4190 mode completely lets the decision to the translator, when the time comes
4191 to find the adequate obsolete translation, it merely tries to provide
4192 handy tools for helping her to do so.
4195 File: gettext.info, Node: Modifying Translations, Next: Modifying Comments, Prev: Obsolete Entries, Up: PO Mode
4197 8.3.9 Modifying Translations
4198 ----------------------------
4200 PO mode prevents direct modification of the PO file, by the usual
4201 means Emacs gives for altering a buffer’s contents. By doing so, it
4202 pretends helping the translator to avoid little clerical errors about
4203 the overall file format, or the proper quoting of strings, as those
4204 errors would be easily made. Other kinds of errors are still possible,
4205 but some may be caught and diagnosed by the batch validation process,
4206 which the translator may always trigger by the ‘V’ command. For all
4207 other errors, the translator has to rely on her own judgment, and also
4208 on the linguistic reports submitted to her by the users of the
4209 translated package, having the same mother tongue.
4211 When the time comes to create a translation, correct an error
4212 diagnosed mechanically or reported by a user, the translators have to
4213 resort to using the following commands for modifying the translations.
4216 Interactively edit the translation (‘po-edit-msgstr’).
4220 Reinitialize the translation with the original, untranslated string
4221 (‘po-msgid-to-msgstr’).
4224 Save the translation on the kill ring, and delete it
4228 Save the translation on the kill ring, without deleting it
4229 (‘po-kill-ring-save-msgstr’).
4232 Replace the translation, taking the new from the kill ring
4235 The command ‘<RET>’ (‘po-edit-msgstr’) opens a new Emacs window meant
4236 to edit in a new translation, or to modify an already existing
4237 translation. The new window contains a copy of the translation taken
4238 from the current PO file entry, all ready for edition, expunged of all
4239 quoting marks, fully modifiable and with the complete extent of Emacs
4240 modifying commands. When the translator is done with her modifications,
4241 she may use ‘C-c C-c’ to close the subedit window with the automatically
4242 requoted results, or ‘C-c C-k’ to abort her modifications. *Note
4243 Subedit::, for more information.
4245 The command ‘<LFD>’ (‘po-msgid-to-msgstr’) initializes, or
4246 reinitializes the translation with the original string. This command is
4247 normally used when the translator wants to redo a fresh translation of
4248 the original string, disregarding any previous work.
4250 It is possible to arrange so, whenever editing an untranslated entry,
4251 the ‘<LFD>’ command be automatically executed. If you set
4252 ‘po-auto-edit-with-msgid’ to ‘t’, the translation gets initialised with
4253 the original string, in case none exists already. The default value for
4254 ‘po-auto-edit-with-msgid’ is ‘nil’.
4256 In fact, whether it is best to start a translation with an empty
4257 string, or rather with a copy of the original string, is a matter of
4258 taste or habit. Sometimes, the source language and the target language
4259 are so different that is simply best to start writing on an empty page.
4260 At other times, the source and target languages are so close that it
4261 would be a waste to retype a number of words already being written in
4262 the original string. A translator may also like having the original
4263 string right under her eyes, as she will progressively overwrite the
4264 original text with the translation, even if this requires some extra
4265 editing work to get rid of the original.
4267 The command ‘k’ (‘po-kill-msgstr’) merely empties the translation
4268 string, so turning the entry into an untranslated one. But while doing
4269 so, its previous contents is put apart in a special place, known as the
4270 kill ring. The command ‘w’ (‘po-kill-ring-save-msgstr’) has also the
4271 effect of taking a copy of the translation onto the kill ring, but it
4272 otherwise leaves the entry alone, and does _not_ remove the translation
4273 from the entry. Both commands use exactly the Emacs kill ring, which is
4274 shared between buffers, and which is well known already to Emacs lovers.
4276 The translator may use ‘k’ or ‘w’ many times in the course of her
4277 work, as the kill ring may hold several saved translations. From the
4278 kill ring, strings may later be reinserted in various Emacs buffers. In
4279 particular, the kill ring may be used for moving translation strings
4280 between different entries of a single PO file buffer, or if the
4281 translator is handling many such buffers at once, even between PO files.
4283 To facilitate exchanges with buffers which are not in PO mode, the
4284 translation string put on the kill ring by the ‘k’ command is fully
4285 unquoted before being saved: external quotes are removed, multi-line
4286 strings are concatenated, and backslash escaped sequences are turned
4287 into their corresponding characters. In the special case of obsolete
4288 entries, the translation is also uncommented prior to saving.
4290 The command ‘y’ (‘po-yank-msgstr’) completely replaces the
4291 translation of the current entry by a string taken from the kill ring.
4292 Following Emacs terminology, we then say that the replacement string is
4293 "yanked" into the PO file buffer. *Note (emacs)Yanking::. The first
4294 time ‘y’ is used, the translation receives the value of the most recent
4295 addition to the kill ring. If ‘y’ is typed once again, immediately,
4296 without intervening keystrokes, the translation just inserted is taken
4297 away and replaced by the second most recent addition to the kill ring.
4298 By repeating ‘y’ many times in a row, the translator may travel along
4299 the kill ring for saved strings, until she finds the string she really
4302 When a string is yanked into a PO file entry, it is fully and
4303 automatically requoted for complying with the format PO files should
4304 have. Further, if the entry is obsolete, PO mode then appropriately
4305 push the inserted string inside comments. Once again, translators
4306 should not burden themselves with quoting considerations besides, of
4307 course, the necessity of the translated string itself respective to the
4310 Note that ‘k’ or ‘w’ are not the only commands pushing strings on the
4311 kill ring, as almost any PO mode command replacing translation strings
4312 (or the translator comments) automatically saves the old string on the
4313 kill ring. The main exceptions to this general rule are the yanking
4314 commands themselves.
4316 To better illustrate the operation of killing and yanking, let’s use
4317 an actual example, taken from a common situation. When the programmer
4318 slightly modifies some string right in the program, his change is later
4319 reflected in the PO file by the appearance of a new untranslated entry
4320 for the modified string, and the fact that the entry translating the
4321 original or unmodified string becomes obsolete. In many cases, the
4322 translator might spare herself some work by retrieving the unmodified
4323 translation from the obsolete entry, then initializing the untranslated
4324 entry ‘msgstr’ field with this retrieved translation. Once this done,
4325 the obsolete entry is not wanted anymore, and may be safely deleted.
4327 When the translator finds an untranslated entry and suspects that a
4328 slight variant of the translation exists, she immediately uses ‘m’ to
4329 mark the current entry location, then starts chasing obsolete entries
4330 with ‘o’, hoping to find some translation corresponding to the
4331 unmodified string. Once found, she uses the ‘<DEL>’ command for
4332 deleting the obsolete entry, knowing that ‘<DEL>’ also _kills_ the
4333 translation, that is, pushes the translation on the kill ring. Then,
4334 ‘r’ returns to the initial untranslated entry, and ‘y’ then _yanks_ the
4335 saved translation right into the ‘msgstr’ field. The translator is then
4336 free to use ‘<RET>’ for fine tuning the translation contents, and maybe
4337 to later use ‘u’, then ‘m’ again, for going on with the next
4338 untranslated string.
4340 When some sequence of keys has to be typed over and over again, the
4341 translator may find it useful to become better acquainted with the Emacs
4342 capability of learning these sequences and playing them back under
4343 request. *Note (emacs)Keyboard Macros::.
4346 File: gettext.info, Node: Modifying Comments, Next: Subedit, Prev: Modifying Translations, Up: PO Mode
4348 8.3.10 Modifying Comments
4349 -------------------------
4351 Any translation work done seriously will raise many linguistic
4352 difficulties, for which decisions have to be made, and the choices
4353 further documented. These documents may be saved within the PO file in
4354 form of translator comments, which the translator is free to create,
4355 delete, or modify at will. These comments may be useful to herself when
4356 she returns to this PO file after a while.
4358 Comments not having whitespace after the initial ‘#’, for example,
4359 those beginning with ‘#.’ or ‘#:’, are _not_ translator comments, they
4360 are exclusively created by other ‘gettext’ tools. So, the commands
4361 below will never alter such system added comments, they are not meant
4362 for the translator to modify. *Note PO Files::.
4364 The following commands are somewhat similar to those modifying
4365 translations, so the general indications given for those apply here.
4366 *Note Modifying Translations::.
4369 Interactively edit the translator comments (‘po-edit-comment’).
4372 Save the translator comments on the kill ring, and delete it
4373 (‘po-kill-comment’).
4376 Save the translator comments on the kill ring, without deleting it
4377 (‘po-kill-ring-save-comment’).
4380 Replace the translator comments, taking the new from the kill ring
4381 (‘po-yank-comment’).
4383 These commands parallel PO mode commands for modifying the
4384 translation strings, and behave much the same way as they do, except
4385 that they handle this part of PO file comments meant for translator
4386 usage, rather than the translation strings. So, if the descriptions
4387 given below are slightly succinct, it is because the full details have
4388 already been given. *Note Modifying Translations::.
4390 The command ‘#’ (‘po-edit-comment’) opens a new Emacs window
4391 containing a copy of the translator comments on the current PO file
4392 entry. If there are no such comments, PO mode understands that the
4393 translator wants to add a comment to the entry, and she is presented
4394 with an empty screen. Comment marks (‘#’) and the space following them
4395 are automatically removed before edition, and reinstated after. For
4396 translator comments pertaining to obsolete entries, the uncommenting and
4397 recommenting operations are done twice. Once in the editing window, the
4398 keys ‘C-c C-c’ allow the translator to tell she is finished with editing
4399 the comment. *Note Subedit::, for further details.
4401 Functions found on ‘po-subedit-mode-hook’, if any, are executed after
4402 the string has been inserted in the edit buffer.
4404 The command ‘K’ (‘po-kill-comment’) gets rid of all translator
4405 comments, while saving those comments on the kill ring. The command ‘W’
4406 (‘po-kill-ring-save-comment’) takes a copy of the translator comments on
4407 the kill ring, but leaves them undisturbed in the current entry. The
4408 command ‘Y’ (‘po-yank-comment’) completely replaces the translator
4409 comments by a string taken at the front of the kill ring. When this
4410 command is immediately repeated, the comments just inserted are
4411 withdrawn, and replaced by other strings taken along the kill ring.
4413 On the kill ring, all strings have the same nature. There is no
4414 distinction between _translation_ strings and _translator comments_
4415 strings. So, for example, let’s presume the translator has just
4416 finished editing a translation, and wants to create a new translator
4417 comment to document why the previous translation was not good, just to
4418 remember what was the problem. Foreseeing that she will do that in her
4419 documentation, the translator may want to quote the previous translation
4420 in her translator comments. To do so, she may initialize the translator
4421 comments with the previous translation, still at the head of the kill
4422 ring. Because editing already pushed the previous translation on the
4423 kill ring, she merely has to type ‘M-w’ prior to ‘#’, and the previous
4424 translation will be right there, all ready for being introduced by some
4427 On the other hand, presume there are some translator comments already
4428 and that the translator wants to add to those comments, instead of
4429 wholly replacing them. Then, she should edit the comment right away
4430 with ‘#’. Once inside the editing window, she can use the regular Emacs
4431 commands ‘C-y’ (‘yank’) and ‘M-y’ (‘yank-pop’) to get the previous
4432 translation where she likes.
4435 File: gettext.info, Node: Subedit, Next: C Sources Context, Prev: Modifying Comments, Up: PO Mode
4437 8.3.11 Details of Sub Edition
4438 -----------------------------
4440 The PO subedit minor mode has a few peculiarities worth being
4441 described in fuller detail. It installs a few commands over the usual
4442 editing set of Emacs, which are described below.
4445 Complete edition (‘po-subedit-exit’).
4448 Abort edition (‘po-subedit-abort’).
4451 Consult auxiliary PO files (‘po-subedit-cycle-auxiliary’).
4453 The window’s contents represents a translation for a given message,
4454 or a translator comment. The translator may modify this window to her
4455 heart’s content. Once this is done, the command ‘C-c C-c’
4456 (‘po-subedit-exit’) may be used to return the edited translation into
4457 the PO file, replacing the original translation, even if it moved out of
4458 sight or if buffers were switched.
4460 If the translator becomes unsatisfied with her translation or
4461 comment, to the extent she prefers keeping what was existent prior to
4462 the ‘<RET>’ or ‘#’ command, she may use the command ‘C-c C-k’
4463 (‘po-subedit-abort’) to merely get rid of edition, while preserving the
4464 original translation or comment. Another way would be for her to exit
4465 normally with ‘C-c C-c’, then type ‘U’ once for undoing the whole effect
4468 The command ‘C-c C-a’ (‘po-subedit-cycle-auxiliary’) allows for
4469 glancing through translations already achieved in other languages,
4470 directly while editing the current translation. This may be quite
4471 convenient when the translator is fluent at many languages, but of
4472 course, only makes sense when such completed auxiliary PO files are
4473 already available to her (*note Auxiliary::).
4475 Functions found on ‘po-subedit-mode-hook’, if any, are executed after
4476 the string has been inserted in the edit buffer.
4478 While editing her translation, the translator should pay attention to
4479 not inserting unwanted ‘<RET>’ (newline) characters at the end of the
4480 translated string if those are not meant to be there, or to removing
4481 such characters when they are required. Since these characters are not
4482 visible in the editing buffer, they are easily introduced by mistake.
4483 To help her, ‘<RET>’ automatically puts the character ‘<’ at the end of
4484 the string being edited, but this ‘<’ is not really part of the string.
4485 On exiting the editing window with ‘C-c C-c’, PO mode automatically
4486 removes such ‘<’ and all whitespace added after it. If the translator
4487 adds characters after the terminating ‘<’, it looses its delimiting
4488 property and integrally becomes part of the string. If she removes the
4489 delimiting ‘<’, then the edited string is taken _as is_, with all
4490 trailing newlines, even if invisible. Also, if the translated string
4491 ought to end itself with a genuine ‘<’, then the delimiting ‘<’ may not
4492 be removed; so the string should appear, in the editing window, as
4493 ending with two ‘<’ in a row.
4495 When a translation (or a comment) is being edited, the translator may
4496 move the cursor back into the PO file buffer and freely move to other
4497 entries, browsing at will. If, with an edition pending, the translator
4498 wanders in the PO file buffer, she may decide to start modifying another
4499 entry. Each entry being edited has its own subedit buffer. It is
4500 possible to simultaneously edit the translation _and_ the comment of a
4501 single entry, or to edit entries in different PO files, all at once.
4502 Typing ‘<RET>’ on a field already being edited merely resumes that
4503 particular edit. Yet, the translator should better be comfortable at
4504 handling many Emacs windows!
4506 Pending subedits may be completed or aborted in any order, regardless
4507 of how or when they were started. When many subedits are pending and
4508 the translator asks for quitting the PO file (with the ‘q’ command),
4509 subedits are automatically resumed one at a time, so she may decide for
4513 File: gettext.info, Node: C Sources Context, Next: Auxiliary, Prev: Subedit, Up: PO Mode
4515 8.3.12 C Sources Context
4516 ------------------------
4518 PO mode is particularly powerful when used with PO files created
4519 through GNU ‘gettext’ utilities, as those utilities insert special
4520 comments in the PO files they generate. Some of these special comments
4521 relate the PO file entry to exactly where the untranslated string
4522 appears in the program sources.
4524 When the translator gets to an untranslated entry, she is fairly
4525 often faced with an original string which is not as informative as it
4526 normally should be, being succinct, cryptic, or otherwise ambiguous.
4527 Before choosing how to translate the string, she needs to understand
4528 better what the string really means and how tight the translation has to
4529 be. Most of the time, when problems arise, the only way left to make
4530 her judgment is looking at the true program sources from where this
4531 string originated, searching for surrounding comments the programmer
4532 might have put in there, and looking around for helping clues of _any_
4535 Surely, when looking at program sources, the translator will receive
4536 more help if she is a fluent programmer. However, even if she is not
4537 versed in programming and feels a little lost in C code, the translator
4538 should not be shy at taking a look, once in a while. It is most
4539 probable that she will still be able to find some of the hints she
4540 needs. She will learn quickly to not feel uncomfortable in program
4541 code, paying more attention to programmer’s comments, variable and
4542 function names (if he dared choosing them well), and overall
4543 organization, than to the program code itself.
4545 The following commands are meant to help the translator at getting
4546 program source context for a PO file entry.
4549 Resume the display of a program source context, or cycle through
4550 them (‘po-cycle-source-reference’).
4553 Display of a program source context selected by menu
4554 (‘po-select-source-reference’).
4557 Add a directory to the search path for source files
4558 (‘po-consider-source-path’).
4561 Delete a directory from the search path for source files
4562 (‘po-ignore-source-path’).
4564 The commands ‘s’ (‘po-cycle-source-reference’) and ‘M-s’
4565 (‘po-select-source-reference’) both open another window displaying some
4566 source program file, and already positioned in such a way that it shows
4567 an actual use of the string to be translated. By doing so, the command
4568 gives source program context for the string. But if the entry has no
4569 source context references, or if all references are unresolved along the
4570 search path for program sources, then the command diagnoses this as an
4573 Even if ‘s’ (or ‘M-s’) opens a new window, the cursor stays in the PO
4574 file window. If the translator really wants to get into the program
4575 source window, she ought to do it explicitly, maybe by using command
4578 When ‘s’ is typed for the first time, or for a PO file entry which is
4579 different of the last one used for getting source context, then the
4580 command reacts by giving the first context available for this entry, if
4581 any. If some context has already been recently displayed for the
4582 current PO file entry, and the translator wandered off to do other
4583 things, typing ‘s’ again will merely resume, in another window, the
4584 context last displayed. In particular, if the translator moved the
4585 cursor away from the context in the source file, the command will bring
4586 the cursor back to the context. By using ‘s’ many times in a row, with
4587 no other commands intervening, PO mode will cycle to the next available
4588 contexts for this particular entry, getting back to the first context
4589 once the last has been shown.
4591 The command ‘M-s’ behaves differently. Instead of cycling through
4592 references, it lets the translator choose a particular reference among
4593 many, and displays that reference. It is best used with completion, if
4594 the translator types ‘<TAB>’ immediately after ‘M-s’, in response to the
4595 question, she will be offered a menu of all possible references, as a
4596 reminder of which are the acceptable answers. This command is useful
4597 only where there are really many contexts available for a single string
4600 Program source files are usually found relative to where the PO file
4601 stands. As a special provision, when this fails, the file is also
4602 looked for, but relative to the directory immediately above it. Those
4603 two cases take proper care of most PO files. However, it might happen
4604 that a PO file has been moved, or is edited in a different place than
4605 its normal location. When this happens, the translator should tell PO
4606 mode in which directory normally sits the genuine PO file. Many such
4607 directories may be specified, and all together, they constitute what is
4608 called the "search path" for program sources. The command ‘S’
4609 (‘po-consider-source-path’) is used to interactively enter a new
4610 directory at the front of the search path, and the command ‘M-S’
4611 (‘po-ignore-source-path’) is used to select, with completion, one of the
4612 directories she does not want anymore on the search path.
4615 File: gettext.info, Node: Auxiliary, Prev: C Sources Context, Up: PO Mode
4617 8.3.13 Consulting Auxiliary PO Files
4618 ------------------------------------
4620 PO mode is able to help the knowledgeable translator, being fluent in
4621 many languages, at taking advantage of translations already achieved in
4622 other languages she just happens to know. It provides these other
4623 language translations as additional context for her own work. Moreover,
4624 it has features to ease the production of translations for many
4625 languages at once, for translators preferring to work in this way.
4627 An "auxiliary" PO file is an existing PO file meant for the same
4628 package the translator is working on, but targeted to a different mother
4629 tongue language. Commands exist for declaring and handling auxiliary PO
4630 files, and also for showing contexts for the entry under work.
4632 Here are the auxiliary file commands available in PO mode.
4635 Seek auxiliary files for another translation for the same entry
4636 (‘po-cycle-auxiliary’).
4639 Switch to a particular auxiliary file (‘po-select-auxiliary’).
4642 Declare this PO file as an auxiliary file
4643 (‘po-consider-as-auxiliary’).
4646 Remove this PO file from the list of auxiliary files
4647 (‘po-ignore-as-auxiliary’).
4649 Command ‘A’ (‘po-consider-as-auxiliary’) adds the current PO file to
4650 the list of auxiliary files, while command ‘M-A’
4651 (‘po-ignore-as-auxiliary’ just removes it.
4653 The command ‘a’ (‘po-cycle-auxiliary’) seeks all auxiliary PO files,
4654 round-robin, searching for a translated entry in some other language
4655 having an ‘msgid’ field identical as the one for the current entry. The
4656 found PO file, if any, takes the place of the current PO file in the
4657 display (its window gets on top). Before doing so, the current PO file
4658 is also made into an auxiliary file, if not already. So, ‘a’ in this
4659 newly displayed PO file will seek another PO file, and so on, so
4660 repeating ‘a’ will eventually yield back the original PO file.
4662 The command ‘C-c C-a’ (‘po-select-auxiliary’) asks the translator for
4663 her choice of a particular auxiliary file, with completion, and then
4664 switches to that selected PO file. The command also checks if the
4665 selected file has an ‘msgid’ field identical as the one for the current
4666 entry, and if yes, this entry becomes current. Otherwise, the cursor of
4667 the selected file is left undisturbed.
4669 For all this to work fully, auxiliary PO files will have to be
4670 normalized, in that way that ‘msgid’ fields should be written _exactly_
4671 the same way. It is possible to write ‘msgid’ fields in various ways
4672 for representing the same string, different writing would break the
4673 proper behaviour of the auxiliary file commands of PO mode. This is not
4674 expected to be much a problem in practice, as most existing PO files
4675 have their ‘msgid’ entries written by the same GNU ‘gettext’ tools.
4677 However, PO files initially created by PO mode itself, while marking
4678 strings in source files, are normalised differently. So are PO files
4679 resulting of the ‘M-x normalize’ command. Until these discrepancies
4680 between PO mode and other GNU ‘gettext’ tools get fully resolved, the
4681 translator should stay aware of normalisation issues.
4684 File: gettext.info, Node: Compendium, Prev: PO Mode, Up: Editing
4686 8.4 Using Translation Compendia
4687 ===============================
4689 A "compendium" is a special PO file containing a set of translations
4690 recurring in many different packages. The translator can use gettext
4691 tools to build a new compendium, to add entries to her compendium, and
4692 to initialize untranslated entries, or to update already translated
4693 entries, from translations kept in the compendium.
4697 * Creating Compendia:: Merging translations for later use
4698 * Using Compendia:: Using older translations if they fit
4701 File: gettext.info, Node: Creating Compendia, Next: Using Compendia, Prev: Compendium, Up: Compendium
4703 8.4.1 Creating Compendia
4704 ------------------------
4706 Basically every PO file consisting of translated entries only can be
4707 declared as a valid compendium. Often the translator wants to have
4708 special compendia; let’s consider two cases: ‘concatenating PO files’
4709 and ‘extracting a message subset from a PO file’.
4711 8.4.1.1 Concatenate PO Files
4712 ............................
4714 To concatenate several valid PO files into one compendium file you
4715 can use ‘msgcomm’ or ‘msgcat’ (the latter preferred):
4717 msgcat -o compendium.po file1.po file2.po
4719 By default, ‘msgcat’ will accumulate divergent translations for the
4720 same string. Those occurrences will be marked as ‘fuzzy’ and highly
4721 visible decorated; calling ‘msgcat’ on ‘file1.po’:
4725 msgid "Report bugs to <%s>.\n"
4726 msgstr "Comunicar `bugs' a <%s>.\n"
4732 msgid "Report bugs to <%s>.\n"
4733 msgstr "Comunicar \"bugs\" a <%s>.\n"
4737 #: src/hello.c:200 src/bye.c:100
4739 msgid "Report bugs to <%s>.\n"
4741 "#-#-#-#-# file1.po #-#-#-#-#\n"
4742 "Comunicar `bugs' a <%s>.\n"
4743 "#-#-#-#-# file2.po #-#-#-#-#\n"
4744 "Comunicar \"bugs\" a <%s>.\n"
4746 The translator will have to resolve this “conflict” manually; she has to
4747 decide whether the first or the second version is appropriate (or
4748 provide a new translation), to delete the “marker lines”, and finally to
4749 remove the ‘fuzzy’ mark.
4751 If the translator knows in advance the first found translation of a
4752 message is always the best translation she can make use to the
4753 ‘--use-first’ switch:
4755 msgcat --use-first -o compendium.po file1.po file2.po
4757 A good compendium file must not contain ‘fuzzy’ or untranslated
4758 entries. If input files are “dirty” you must preprocess the input files
4759 or postprocess the result using ‘msgattrib --translated --no-fuzzy’.
4761 8.4.1.2 Extract a Message Subset from a PO File
4762 ...............................................
4764 Nobody wants to translate the same messages again and again; thus you
4765 may wish to have a compendium file containing ‘getopt.c’ messages.
4767 To extract a message subset (e.g., all ‘getopt.c’ messages) from an
4768 existing PO file into one compendium file you can use ‘msggrep’:
4770 msggrep --location src/getopt.c -o compendium.po file.po
4773 File: gettext.info, Node: Using Compendia, Prev: Creating Compendia, Up: Compendium
4775 8.4.2 Using Compendia
4776 ---------------------
4778 You can use a compendium file to initialize a translation from
4779 scratch or to update an already existing translation.
4781 8.4.2.1 Initialize a New Translation File
4782 .........................................
4784 Since a PO file with translations does not exist the translator can
4785 merely use ‘/dev/null’ to fake the “old” translation file.
4787 msgmerge --compendium compendium.po -o file.po /dev/null file.pot
4789 8.4.2.2 Update an Existing Translation File
4790 ...........................................
4792 Concatenate the compendium file(s) and the existing PO, merge the
4793 result with the POT file and remove the obsolete entries (optional, here
4794 done using ‘msgattrib’):
4796 msgcat --use-first -o update.po compendium1.po compendium2.po file.po
4797 msgmerge update.po file.pot | msgattrib --no-obsolete > file.po
4800 File: gettext.info, Node: Manipulating, Next: Binaries, Prev: Editing, Up: Top
4802 9 Manipulating PO Files
4803 ***********************
4805 Sometimes it is necessary to manipulate PO files in a way that is
4806 better performed automatically than by hand. GNU ‘gettext’ includes a
4807 complete set of tools for this purpose.
4809 When merging two packages into a single package, the resulting POT
4810 file will be the concatenation of the two packages’ POT files. Thus the
4811 maintainer must concatenate the two existing package translations into a
4812 single translation catalog, for each language. This is best performed
4813 using ‘msgcat’. It is then the translators’ duty to deal with any
4814 possible conflicts that arose during the merge.
4816 When a translator takes over the translation job from another
4817 translator, but she uses a different character encoding in her locale,
4818 she will convert the catalog to her character encoding. This is best
4819 done through the ‘msgconv’ program.
4821 When a maintainer takes a source file with tagged messages from
4822 another package, he should also take the existing translations for this
4823 source file (and not let the translators do the same job twice). One
4824 way to do this is through ‘msggrep’, another is to create a POT file for
4825 that source file and use ‘msgmerge’.
4827 When a translator wants to adjust some translation catalog for a
4828 special dialect or orthography — for example, German as written in
4829 Switzerland versus German as written in Germany — she needs to apply
4830 some text processing to every message in the catalog. The tool for
4831 doing this is ‘msgfilter’.
4833 Another use of ‘msgfilter’ is to produce approximately the POT file
4834 for which a given PO file was made. This can be done through a filter
4835 command like ‘msgfilter sed -e d | sed -e '/^# /d'’. Note that the
4836 original POT file may have had different comments and different plural
4837 message counts, that’s why it’s better to use the original POT file if
4840 When a translator wants to check her translations, for example
4841 according to orthography rules or using a non-interactive spell checker,
4842 she can do so using the ‘msgexec’ program.
4844 When third party tools create PO or POT files, sometimes duplicates
4845 cannot be avoided. But the GNU ‘gettext’ tools give an error when they
4846 encounter duplicate msgids in the same file and in the same domain. To
4847 merge duplicates, the ‘msguniq’ program can be used.
4849 ‘msgcomm’ is a more general tool for keeping or throwing away
4850 duplicates, occurring in different files.
4852 ‘msgcmp’ can be used to check whether a translation catalog is
4853 completely translated.
4855 ‘msgattrib’ can be used to select and extract only the fuzzy or
4856 untranslated messages of a translation catalog.
4858 ‘msgen’ is useful as a first step for preparing English translation
4859 catalogs. It copies each message’s msgid to its msgstr.
4861 Finally, for those applications where all these various programs are
4862 not sufficient, a library ‘libgettextpo’ is provided that can be used to
4863 write other specialized programs that process PO files.
4867 * msgcat Invocation:: Invoking the ‘msgcat’ Program
4868 * msgconv Invocation:: Invoking the ‘msgconv’ Program
4869 * msggrep Invocation:: Invoking the ‘msggrep’ Program
4870 * msgfilter Invocation:: Invoking the ‘msgfilter’ Program
4871 * msguniq Invocation:: Invoking the ‘msguniq’ Program
4872 * msgcomm Invocation:: Invoking the ‘msgcomm’ Program
4873 * msgcmp Invocation:: Invoking the ‘msgcmp’ Program
4874 * msgattrib Invocation:: Invoking the ‘msgattrib’ Program
4875 * msgen Invocation:: Invoking the ‘msgen’ Program
4876 * msgexec Invocation:: Invoking the ‘msgexec’ Program
4877 * Colorizing:: Highlighting parts of PO files
4878 * libgettextpo:: Writing your own programs that process PO files
4881 File: gettext.info, Node: msgcat Invocation, Next: msgconv Invocation, Prev: Manipulating, Up: Manipulating
4883 9.1 Invoking the ‘msgcat’ Program
4884 =================================
4886 msgcat [OPTION] [INPUTFILE]...
4888 The ‘msgcat’ program concatenates and merges the specified PO files.
4889 It finds messages which are common to two or more of the specified PO
4890 files. By using the ‘--more-than’ option, greater commonality may be
4891 requested before messages are printed. Conversely, the ‘--less-than’
4892 option may be used to specify less commonality before messages are
4893 printed (i.e. ‘--less-than=2’ will only print the unique messages).
4894 Translations, comments, extracted comments, and file positions will be
4895 cumulated, except that if ‘--use-first’ is specified, they will be taken
4896 from the first PO file to define them.
4898 9.1.1 Input file location
4899 -------------------------
4906 Read the names of the input files from FILE instead of getting them
4907 from the command line.
4910 ‘--directory=DIRECTORY’
4911 Add DIRECTORY to the list of directories. Source files are
4912 searched relative to this list of directories. The resulting ‘.po’
4913 file will be written relative to the current directory, though.
4915 If INPUTFILE is ‘-’, standard input is read.
4917 9.1.2 Output file location
4918 --------------------------
4921 ‘--output-file=FILE’
4922 Write output to specified file.
4924 The results are written to standard output if no output file is
4925 specified or if it is ‘-’.
4927 9.1.3 Message selection
4928 -----------------------
4931 ‘--less-than=NUMBER’
4932 Print messages with less than NUMBER definitions, defaults to
4933 infinite if not set.
4936 ‘--more-than=NUMBER’
4937 Print messages with more than NUMBER definitions, defaults to 0 if
4942 Shorthand for ‘--less-than=2’. Requests that only unique messages
4945 9.1.4 Input file syntax
4946 -----------------------
4949 ‘--properties-input’
4950 Assume the input files are Java ResourceBundles in Java
4951 ‘.properties’ syntax, not in PO file syntax.
4953 ‘--stringtable-input’
4954 Assume the input files are NeXTstep/GNUstep localized resource
4955 files in ‘.strings’ syntax, not in PO file syntax.
4957 9.1.5 Output details
4958 --------------------
4962 Specify encoding for output.
4965 Use first available translation for each message. Don’t merge
4966 several translations into one.
4968 ‘--lang=CATALOGNAME’
4969 Specify the ‘Language’ field to be used in the header entry. See
4970 *note Header Entry:: for the meaning of this field. Note: The
4971 ‘Language-Team’ and ‘Plural-Forms’ fields are left unchanged.
4975 Specify whether or when to use colors and other text attributes.
4976 See *note The --color option:: for details.
4978 ‘--style=STYLE_FILE’
4979 Specify the CSS style rule file to use for ‘--color’. See *note
4980 The --style option:: for details.
4983 Always write an output file even if it contains no message.
4987 Write the .po file using indented style.
4990 Do not write ‘#: FILENAME:LINE’ lines.
4993 ‘--add-location=TYPE’
4994 Generate ‘#: FILENAME:LINE’ lines (default).
4996 The optional TYPE can be either ‘full’, ‘file’, or ‘never’. If it
4997 is not given or ‘full’, it generates the lines with both file name
4998 and line number. If it is ‘file’, the line number part is omitted.
4999 If it is ‘never’, it completely suppresses the lines (same as
5003 Write out a strict Uniforum conforming PO file. Note that this
5004 Uniforum format should be avoided because it doesn’t support the
5008 ‘--properties-output’
5009 Write out a Java ResourceBundle in Java ‘.properties’ syntax. Note
5010 that this file format doesn’t support plural forms and silently
5011 drops obsolete messages.
5013 ‘--stringtable-output’
5014 Write out a NeXTstep/GNUstep localized resource file in ‘.strings’
5015 syntax. Note that this file format doesn’t support plural forms.
5019 Set the output page width. Long strings in the output files will
5020 be split across multiple lines in order to ensure that each line’s
5021 width (= number of screen columns) is less or equal to the given
5025 Do not break long message lines. Message lines whose width exceeds
5026 the output page width will not be split into several lines. Only
5027 file reference lines which are wider than the output page width
5032 Generate sorted output. Note that using this option makes it much
5033 harder for the translator to understand each message’s context.
5037 Sort output by file location.
5039 9.1.6 Informative output
5040 ------------------------
5044 Display this help and exit.
5048 Output version information and exit.
5051 File: gettext.info, Node: msgconv Invocation, Next: msggrep Invocation, Prev: msgcat Invocation, Up: Manipulating
5053 9.2 Invoking the ‘msgconv’ Program
5054 ==================================
5056 msgconv [OPTION] [INPUTFILE]
5058 The ‘msgconv’ program converts a translation catalog to a different
5061 9.2.1 Input file location
5062 -------------------------
5068 ‘--directory=DIRECTORY’
5069 Add DIRECTORY to the list of directories. Source files are
5070 searched relative to this list of directories. The resulting ‘.po’
5071 file will be written relative to the current directory, though.
5073 If no INPUTFILE is given or if it is ‘-’, standard input is read.
5075 9.2.2 Output file location
5076 --------------------------
5079 ‘--output-file=FILE’
5080 Write output to specified file.
5082 The results are written to standard output if no output file is
5083 specified or if it is ‘-’.
5085 9.2.3 Conversion target
5086 -----------------------
5090 Specify encoding for output.
5092 The default encoding is the current locale’s encoding.
5094 9.2.4 Input file syntax
5095 -----------------------
5098 ‘--properties-input’
5099 Assume the input file is a Java ResourceBundle in Java
5100 ‘.properties’ syntax, not in PO file syntax.
5102 ‘--stringtable-input’
5103 Assume the input file is a NeXTstep/GNUstep localized resource file
5104 in ‘.strings’ syntax, not in PO file syntax.
5106 9.2.5 Output details
5107 --------------------
5111 Specify whether or when to use colors and other text attributes.
5112 See *note The --color option:: for details.
5114 ‘--style=STYLE_FILE’
5115 Specify the CSS style rule file to use for ‘--color’. See *note
5116 The --style option:: for details.
5119 Always write an output file even if it contains no message.
5123 Write the .po file using indented style.
5126 Do not write ‘#: FILENAME:LINE’ lines.
5129 ‘--add-location=TYPE’
5130 Generate ‘#: FILENAME:LINE’ lines (default).
5132 The optional TYPE can be either ‘full’, ‘file’, or ‘never’. If it
5133 is not given or ‘full’, it generates the lines with both file name
5134 and line number. If it is ‘file’, the line number part is omitted.
5135 If it is ‘never’, it completely suppresses the lines (same as
5139 Write out a strict Uniforum conforming PO file. Note that this
5140 Uniforum format should be avoided because it doesn’t support the
5144 ‘--properties-output’
5145 Write out a Java ResourceBundle in Java ‘.properties’ syntax. Note
5146 that this file format doesn’t support plural forms and silently
5147 drops obsolete messages.
5149 ‘--stringtable-output’
5150 Write out a NeXTstep/GNUstep localized resource file in ‘.strings’
5151 syntax. Note that this file format doesn’t support plural forms.
5155 Set the output page width. Long strings in the output files will
5156 be split across multiple lines in order to ensure that each line’s
5157 width (= number of screen columns) is less or equal to the given
5161 Do not break long message lines. Message lines whose width exceeds
5162 the output page width will not be split into several lines. Only
5163 file reference lines which are wider than the output page width
5168 Generate sorted output. Note that using this option makes it much
5169 harder for the translator to understand each message’s context.
5173 Sort output by file location.
5175 9.2.6 Informative output
5176 ------------------------
5180 Display this help and exit.
5184 Output version information and exit.
5187 File: gettext.info, Node: msggrep Invocation, Next: msgfilter Invocation, Prev: msgconv Invocation, Up: Manipulating
5189 9.3 Invoking the ‘msggrep’ Program
5190 ==================================
5192 msggrep [OPTION] [INPUTFILE]
5194 The ‘msggrep’ program extracts all messages of a translation catalog
5195 that match a given pattern or belong to some given source files.
5197 9.3.1 Input file location
5198 -------------------------
5204 ‘--directory=DIRECTORY’
5205 Add DIRECTORY to the list of directories. Source files are
5206 searched relative to this list of directories. The resulting ‘.po’
5207 file will be written relative to the current directory, though.
5209 If no INPUTFILE is given or if it is ‘-’, standard input is read.
5211 9.3.2 Output file location
5212 --------------------------
5215 ‘--output-file=FILE’
5216 Write output to specified file.
5218 The results are written to standard output if no output file is
5219 specified or if it is ‘-’.
5221 9.3.3 Message selection
5222 -----------------------
5224 [-N SOURCEFILE]... [-M DOMAINNAME]...
5225 [-J MSGCTXT-PATTERN] [-K MSGID-PATTERN] [-T MSGSTR-PATTERN]
5226 [-C COMMENT-PATTERN]
5228 A message is selected if
5229 • it comes from one of the specified source files,
5230 • or if it comes from one of the specified domains,
5231 • or if ‘-J’ is given and its context (msgctxt) matches
5233 • or if ‘-K’ is given and its key (msgid or msgid_plural) matches
5235 • or if ‘-T’ is given and its translation (msgstr) matches
5237 • or if ‘-C’ is given and the translator’s comment matches
5240 When more than one selection criterion is specified, the set of
5241 selected messages is the union of the selected messages of each
5244 MSGCTXT-PATTERN or MSGID-PATTERN or MSGSTR-PATTERN syntax:
5245 [-E | -F] [-e PATTERN | -f FILE]...
5246 PATTERNs are basic regular expressions by default, or extended
5247 regular expressions if -E is given, or fixed strings if -F is given.
5250 ‘--location=SOURCEFILE’
5251 Select messages extracted from SOURCEFILE. SOURCEFILE can be
5252 either a literal file name or a wildcard pattern.
5255 ‘--domain=DOMAINNAME’
5256 Select messages belonging to domain DOMAINNAME.
5260 Start of patterns for the msgctxt.
5264 Start of patterns for the msgid.
5268 Start of patterns for the msgstr.
5272 Start of patterns for the translator’s comment.
5275 ‘--extracted-comment’
5276 Start of patterns for the extracted comments.
5280 Specify that PATTERN is an extended regular expression.
5284 Specify that PATTERN is a set of newline-separated strings.
5288 Use PATTERN as a regular expression.
5292 Obtain PATTERN from FILE.
5296 Ignore case distinctions.
5300 Output only the messages that do not match any selection criterion,
5301 instead of the messages that match a selection criterion.
5303 9.3.4 Input file syntax
5304 -----------------------
5307 ‘--properties-input’
5308 Assume the input file is a Java ResourceBundle in Java
5309 ‘.properties’ syntax, not in PO file syntax.
5311 ‘--stringtable-input’
5312 Assume the input file is a NeXTstep/GNUstep localized resource file
5313 in ‘.strings’ syntax, not in PO file syntax.
5315 9.3.5 Output details
5316 --------------------
5320 Specify whether or when to use colors and other text attributes.
5321 See *note The --color option:: for details.
5323 ‘--style=STYLE_FILE’
5324 Specify the CSS style rule file to use for ‘--color’. See *note
5325 The --style option:: for details.
5328 Always write an output file even if it contains no message.
5331 Write the .po file using indented style.
5334 Do not write ‘#: FILENAME:LINE’ lines.
5337 ‘--add-location=TYPE’
5338 Generate ‘#: FILENAME:LINE’ lines (default).
5340 The optional TYPE can be either ‘full’, ‘file’, or ‘never’. If it
5341 is not given or ‘full’, it generates the lines with both file name
5342 and line number. If it is ‘file’, the line number part is omitted.
5343 If it is ‘never’, it completely suppresses the lines (same as
5347 Write out a strict Uniforum conforming PO file. Note that this
5348 Uniforum format should be avoided because it doesn’t support the
5352 ‘--properties-output’
5353 Write out a Java ResourceBundle in Java ‘.properties’ syntax. Note
5354 that this file format doesn’t support plural forms and silently
5355 drops obsolete messages.
5357 ‘--stringtable-output’
5358 Write out a NeXTstep/GNUstep localized resource file in ‘.strings’
5359 syntax. Note that this file format doesn’t support plural forms.
5363 Set the output page width. Long strings in the output files will
5364 be split across multiple lines in order to ensure that each line’s
5365 width (= number of screen columns) is less or equal to the given
5369 Do not break long message lines. Message lines whose width exceeds
5370 the output page width will not be split into several lines. Only
5371 file reference lines which are wider than the output page width
5375 Generate sorted output. Note that using this option makes it much
5376 harder for the translator to understand each message’s context.
5379 Sort output by file location.
5381 9.3.6 Informative output
5382 ------------------------
5386 Display this help and exit.
5390 Output version information and exit.
5395 To extract the messages that come from the source files
5396 ‘gnulib-lib/error.c’ and ‘gnulib-lib/getopt.c’:
5398 msggrep -N gnulib-lib/error.c -N gnulib-lib/getopt.c input.po
5400 To extract the messages that contain the string “Please specify” in
5401 the original string:
5403 msggrep --msgid -F -e 'Please specify' input.po
5405 To extract the messages that have a context specifier of either
5406 “Menu>File” or “Menu>Edit” or a submenu of them:
5408 msggrep --msgctxt -E -e '^Menu>(File|Edit)' input.po
5410 To extract the messages whose translation contains one of the strings
5411 in the file ‘wordlist.txt’:
5413 msggrep --msgstr -F -f wordlist.txt input.po
5416 File: gettext.info, Node: msgfilter Invocation, Next: msguniq Invocation, Prev: msggrep Invocation, Up: Manipulating
5418 9.4 Invoking the ‘msgfilter’ Program
5419 ====================================
5421 msgfilter [OPTION] FILTER [FILTER-OPTION]
5423 The ‘msgfilter’ program applies a filter to all translations of a
5424 translation catalog.
5426 During each FILTER invocation, the environment variable
5427 ‘MSGFILTER_MSGID’ is bound to the message’s msgid, and the environment
5428 variable ‘MSGFILTER_LOCATION’ is bound to the location in the PO file of
5429 the message. If the message has a context, the environment variable
5430 ‘MSGFILTER_MSGCTXT’ is bound to the message’s msgctxt, otherwise it is
5431 unbound. If the message has a plural form, environment variable
5432 ‘MSGFILTER_MSGID_PLURAL’ is bound to the message’s msgid_plural and
5433 ‘MSGFILTER_PLURAL_FORM’ is bound to the order number of the plural
5434 actually processed (starting with 0), otherwise both are unbound. If
5435 the message has a previous msgid (added by ‘msgmerge’), environment
5436 variable ‘MSGFILTER_PREV_MSGCTXT’ is bound to the message’s previous
5437 msgctxt, ‘MSGFILTER_PREV_MSGID’ is bound to the previous msgid, and
5438 ‘MSGFILTER_PREV_MSGID_PLURAL’ is bound to the previous msgid_plural.
5440 9.4.1 Input file location
5441 -------------------------
5448 ‘--directory=DIRECTORY’
5449 Add DIRECTORY to the list of directories. Source files are
5450 searched relative to this list of directories. The resulting ‘.po’
5451 file will be written relative to the current directory, though.
5453 If no INPUTFILE is given or if it is ‘-’, standard input is read.
5455 9.4.2 Output file location
5456 --------------------------
5459 ‘--output-file=FILE’
5460 Write output to specified file.
5462 The results are written to standard output if no output file is
5463 specified or if it is ‘-’.
5468 The FILTER can be any program that reads a translation from standard
5469 input and writes a modified translation to standard output. A
5470 frequently used filter is ‘sed’. A few particular built-in filters are
5474 Add newline at the end of each input line and also strip the ending
5475 newline from the output line.
5477 Note: If the filter is not a built-in filter, you have to care about
5478 encodings: It is your responsibility to ensure that the FILTER can cope
5479 with input encoded in the translation catalog’s encoding. If the FILTER
5480 wants input in a particular encoding, you can in a first step convert
5481 the translation catalog to that encoding using the ‘msgconv’ program,
5482 before invoking ‘msgfilter’. If the FILTER wants input in the locale’s
5483 encoding, but you want to avoid the locale’s encoding, then you can
5484 first convert the translation catalog to UTF-8 using the ‘msgconv’
5485 program and then make ‘msgfilter’ work in an UTF-8 locale, by using the
5486 ‘LC_ALL’ environment variable.
5488 Note: Most translations in a translation catalog don’t end with a
5489 newline character. For this reason, unless the ‘--newline’ option is
5490 used, it is important that the FILTER recognizes its last input line
5491 even if it ends without a newline, and that it doesn’t add an undesired
5492 trailing newline at the end. The ‘sed’ program on some platforms is
5493 known to ignore the last line of input if it is not terminated with a
5494 newline. You can use GNU ‘sed’ instead; it does not have this
5497 9.4.4 Useful FILTER-OPTIONs when the FILTER is ‘sed’
5498 ----------------------------------------------------
5501 ‘--expression=SCRIPT’
5502 Add SCRIPT to the commands to be executed.
5506 Add the contents of SCRIPTFILE to the commands to be executed.
5511 Suppress automatic printing of pattern space.
5513 9.4.5 Built-in FILTERs
5514 ----------------------
5516 The filter ‘recode-sr-latin’ is recognized as a built-in filter. The
5517 command ‘recode-sr-latin’ converts Serbian text, written in the Cyrillic
5518 script, to the Latin script. The command ‘msgfilter recode-sr-latin’
5519 applies this conversion to the translations of a PO file. Thus, it can
5520 be used to convert an ‘sr.po’ file to an ‘sr@latin.po’ file.
5522 The filter ‘quot’ is recognized as a built-in filter. The command
5523 ‘msgfilter quot’ converts any quotations surrounded by a pair of ‘"’,
5526 The filter ‘boldquot’ is recognized as a built-in filter. The
5527 command ‘msgfilter boldquot’ converts any quotations surrounded by a
5528 pair of ‘"’, ‘'’, and ‘`’, also adding the VT100 escape sequences to the
5529 text to decorate it as bold.
5531 The use of built-in filters is not sensitive to the current locale’s
5532 encoding. Moreover, when used with a built-in filter, ‘msgfilter’ can
5533 automatically convert the message catalog to the UTF-8 encoding when
5536 9.4.6 Input file syntax
5537 -----------------------
5540 ‘--properties-input’
5541 Assume the input file is a Java ResourceBundle in Java
5542 ‘.properties’ syntax, not in PO file syntax.
5544 ‘--stringtable-input’
5545 Assume the input file is a NeXTstep/GNUstep localized resource file
5546 in ‘.strings’ syntax, not in PO file syntax.
5548 9.4.7 Output details
5549 --------------------
5553 Specify whether or when to use colors and other text attributes.
5554 See *note The --color option:: for details.
5556 ‘--style=STYLE_FILE’
5557 Specify the CSS style rule file to use for ‘--color’. See *note
5558 The --style option:: for details.
5561 Always write an output file even if it contains no message.
5564 Write the .po file using indented style.
5567 Keep the header entry, i.e. the message with ‘msgid ""’,
5568 unmodified, instead of filtering it. By default, the header entry
5569 is subject to filtering like any other message.
5572 Do not write ‘#: FILENAME:LINE’ lines.
5575 ‘--add-location=TYPE’
5576 Generate ‘#: FILENAME:LINE’ lines (default).
5578 The optional TYPE can be either ‘full’, ‘file’, or ‘never’. If it
5579 is not given or ‘full’, it generates the lines with both file name
5580 and line number. If it is ‘file’, the line number part is omitted.
5581 If it is ‘never’, it completely suppresses the lines (same as
5585 Write out a strict Uniforum conforming PO file. Note that this
5586 Uniforum format should be avoided because it doesn’t support the
5590 ‘--properties-output’
5591 Write out a Java ResourceBundle in Java ‘.properties’ syntax. Note
5592 that this file format doesn’t support plural forms and silently
5593 drops obsolete messages.
5595 ‘--stringtable-output’
5596 Write out a NeXTstep/GNUstep localized resource file in ‘.strings’
5597 syntax. Note that this file format doesn’t support plural forms.
5601 Set the output page width. Long strings in the output files will
5602 be split across multiple lines in order to ensure that each line’s
5603 width (= number of screen columns) is less or equal to the given
5607 Do not break long message lines. Message lines whose width exceeds
5608 the output page width will not be split into several lines. Only
5609 file reference lines which are wider than the output page width
5614 Generate sorted output. Note that using this option makes it much
5615 harder for the translator to understand each message’s context.
5619 Sort output by file location.
5621 9.4.8 Informative output
5622 ------------------------
5626 Display this help and exit.
5630 Output version information and exit.
5635 To convert German translations to Swiss orthography (in an UTF-8
5638 msgconv -t UTF-8 de.po | msgfilter sed -e 's/ß/ss/g'
5640 To convert Serbian translations in Cyrillic script to Latin script:
5642 msgfilter recode-sr-latin < sr.po
5645 File: gettext.info, Node: msguniq Invocation, Next: msgcomm Invocation, Prev: msgfilter Invocation, Up: Manipulating
5647 9.5 Invoking the ‘msguniq’ Program
5648 ==================================
5650 msguniq [OPTION] [INPUTFILE]
5652 The ‘msguniq’ program unifies duplicate translations in a translation
5653 catalog. It finds duplicate translations of the same message ID. Such
5654 duplicates are invalid input for other programs like ‘msgfmt’,
5655 ‘msgmerge’ or ‘msgcat’. By default, duplicates are merged together.
5656 When using the ‘--repeated’ option, only duplicates are output, and all
5657 other messages are discarded. Comments and extracted comments will be
5658 cumulated, except that if ‘--use-first’ is specified, they will be taken
5659 from the first translation. File positions will be cumulated. When
5660 using the ‘--unique’ option, duplicates are discarded.
5662 9.5.1 Input file location
5663 -------------------------
5669 ‘--directory=DIRECTORY’
5670 Add DIRECTORY to the list of directories. Source files are
5671 searched relative to this list of directories. The resulting ‘.po’
5672 file will be written relative to the current directory, though.
5674 If no INPUTFILE is given or if it is ‘-’, standard input is read.
5676 9.5.2 Output file location
5677 --------------------------
5680 ‘--output-file=FILE’
5681 Write output to specified file.
5683 The results are written to standard output if no output file is
5684 specified or if it is ‘-’.
5686 9.5.3 Message selection
5687 -----------------------
5691 Print only duplicates.
5695 Print only unique messages, discard duplicates.
5697 9.5.4 Input file syntax
5698 -----------------------
5701 ‘--properties-input’
5702 Assume the input file is a Java ResourceBundle in Java
5703 ‘.properties’ syntax, not in PO file syntax.
5705 ‘--stringtable-input’
5706 Assume the input file is a NeXTstep/GNUstep localized resource file
5707 in ‘.strings’ syntax, not in PO file syntax.
5709 9.5.5 Output details
5710 --------------------
5714 Specify encoding for output.
5717 Use first available translation for each message. Don’t merge
5718 several translations into one.
5722 Specify whether or when to use colors and other text attributes.
5723 See *note The --color option:: for details.
5725 ‘--style=STYLE_FILE’
5726 Specify the CSS style rule file to use for ‘--color’. See *note
5727 The --style option:: for details.
5730 Always write an output file even if it contains no message.
5734 Write the .po file using indented style.
5737 Do not write ‘#: FILENAME:LINE’ lines.
5740 ‘--add-location=TYPE’
5741 Generate ‘#: FILENAME:LINE’ lines (default).
5743 The optional TYPE can be either ‘full’, ‘file’, or ‘never’. If it
5744 is not given or ‘full’, it generates the lines with both file name
5745 and line number. If it is ‘file’, the line number part is omitted.
5746 If it is ‘never’, it completely suppresses the lines (same as
5750 Write out a strict Uniforum conforming PO file. Note that this
5751 Uniforum format should be avoided because it doesn’t support the
5755 ‘--properties-output’
5756 Write out a Java ResourceBundle in Java ‘.properties’ syntax. Note
5757 that this file format doesn’t support plural forms and silently
5758 drops obsolete messages.
5760 ‘--stringtable-output’
5761 Write out a NeXTstep/GNUstep localized resource file in ‘.strings’
5762 syntax. Note that this file format doesn’t support plural forms.
5766 Set the output page width. Long strings in the output files will
5767 be split across multiple lines in order to ensure that each line’s
5768 width (= number of screen columns) is less or equal to the given
5772 Do not break long message lines. Message lines whose width exceeds
5773 the output page width will not be split into several lines. Only
5774 file reference lines which are wider than the output page width
5779 Generate sorted output. Note that using this option makes it much
5780 harder for the translator to understand each message’s context.
5784 Sort output by file location.
5786 9.5.6 Informative output
5787 ------------------------
5791 Display this help and exit.
5795 Output version information and exit.
5798 File: gettext.info, Node: msgcomm Invocation, Next: msgcmp Invocation, Prev: msguniq Invocation, Up: Manipulating
5800 9.6 Invoking the ‘msgcomm’ Program
5801 ==================================
5803 msgcomm [OPTION] [INPUTFILE]...
5805 The ‘msgcomm’ program finds messages which are common to two or more
5806 of the specified PO files. By using the ‘--more-than’ option, greater
5807 commonality may be requested before messages are printed. Conversely,
5808 the ‘--less-than’ option may be used to specify less commonality before
5809 messages are printed (i.e. ‘--less-than=2’ will only print the unique
5810 messages). Translations, comments and extracted comments will be
5811 preserved, but only from the first PO file to define them. File
5812 positions from all PO files will be cumulated.
5814 9.6.1 Input file location
5815 -------------------------
5822 Read the names of the input files from FILE instead of getting them
5823 from the command line.
5826 ‘--directory=DIRECTORY’
5827 Add DIRECTORY to the list of directories. Source files are
5828 searched relative to this list of directories. The resulting ‘.po’
5829 file will be written relative to the current directory, though.
5831 If INPUTFILE is ‘-’, standard input is read.
5833 9.6.2 Output file location
5834 --------------------------
5837 ‘--output-file=FILE’
5838 Write output to specified file.
5840 The results are written to standard output if no output file is
5841 specified or if it is ‘-’.
5843 9.6.3 Message selection
5844 -----------------------
5847 ‘--less-than=NUMBER’
5848 Print messages with less than NUMBER definitions, defaults to
5849 infinite if not set.
5852 ‘--more-than=NUMBER’
5853 Print messages with more than NUMBER definitions, defaults to 1 if
5858 Shorthand for ‘--less-than=2’. Requests that only unique messages
5861 9.6.4 Input file syntax
5862 -----------------------
5865 ‘--properties-input’
5866 Assume the input files are Java ResourceBundles in Java
5867 ‘.properties’ syntax, not in PO file syntax.
5869 ‘--stringtable-input’
5870 Assume the input files are NeXTstep/GNUstep localized resource
5871 files in ‘.strings’ syntax, not in PO file syntax.
5873 9.6.5 Output details
5874 --------------------
5878 Specify whether or when to use colors and other text attributes.
5879 See *note The --color option:: for details.
5881 ‘--style=STYLE_FILE’
5882 Specify the CSS style rule file to use for ‘--color’. See *note
5883 The --style option:: for details.
5886 Always write an output file even if it contains no message.
5890 Write the .po file using indented style.
5893 Do not write ‘#: FILENAME:LINE’ lines.
5896 ‘--add-location=TYPE’
5897 Generate ‘#: FILENAME:LINE’ lines (default).
5899 The optional TYPE can be either ‘full’, ‘file’, or ‘never’. If it
5900 is not given or ‘full’, it generates the lines with both file name
5901 and line number. If it is ‘file’, the line number part is omitted.
5902 If it is ‘never’, it completely suppresses the lines (same as
5906 Write out a strict Uniforum conforming PO file. Note that this
5907 Uniforum format should be avoided because it doesn’t support the
5911 ‘--properties-output’
5912 Write out a Java ResourceBundle in Java ‘.properties’ syntax. Note
5913 that this file format doesn’t support plural forms and silently
5914 drops obsolete messages.
5916 ‘--stringtable-output’
5917 Write out a NeXTstep/GNUstep localized resource file in ‘.strings’
5918 syntax. Note that this file format doesn’t support plural forms.
5922 Set the output page width. Long strings in the output files will
5923 be split across multiple lines in order to ensure that each line’s
5924 width (= number of screen columns) is less or equal to the given
5928 Do not break long message lines. Message lines whose width exceeds
5929 the output page width will not be split into several lines. Only
5930 file reference lines which are wider than the output page width
5935 Generate sorted output. Note that using this option makes it much
5936 harder for the translator to understand each message’s context.
5940 Sort output by file location.
5943 Don’t write header with ‘msgid ""’ entry.
5945 9.6.6 Informative output
5946 ------------------------
5950 Display this help and exit.
5954 Output version information and exit.
5957 File: gettext.info, Node: msgcmp Invocation, Next: msgattrib Invocation, Prev: msgcomm Invocation, Up: Manipulating
5959 9.7 Invoking the ‘msgcmp’ Program
5960 =================================
5962 msgcmp [OPTION] DEF.po REF.pot
5964 The ‘msgcmp’ program compares two Uniforum style .po files to check
5965 that both contain the same set of msgid strings. The DEF.po file is an
5966 existing PO file with the translations. The REF.pot file is the last
5967 created PO file, or a PO Template file (generally created by
5968 ‘xgettext’). This is useful for checking that you have translated each
5969 and every message in your program. Where an exact match cannot be
5970 found, fuzzy matching is used to produce better diagnostics.
5972 9.7.1 Input file location
5973 -------------------------
5979 References to the sources.
5982 ‘--directory=DIRECTORY’
5983 Add DIRECTORY to the list of directories. Source files are
5984 searched relative to this list of directories.
5986 9.7.2 Operation modifiers
5987 -------------------------
5991 Apply REF.pot to each of the domains in DEF.po.
5994 ‘--no-fuzzy-matching’
5995 Do not use fuzzy matching when an exact match is not found. This
5996 may speed up the operation considerably.
5999 Consider fuzzy messages in the DEF.po file like translated
6000 messages. Note that using this option is usually wrong, because
6001 fuzzy messages are exactly those which have not been validated by a
6004 ‘--use-untranslated’
6005 Consider untranslated messages in the DEF.po file like translated
6006 messages. Note that using this option is usually wrong.
6008 9.7.3 Input file syntax
6009 -----------------------
6012 ‘--properties-input’
6013 Assume the input files are Java ResourceBundles in Java
6014 ‘.properties’ syntax, not in PO file syntax.
6016 ‘--stringtable-input’
6017 Assume the input files are NeXTstep/GNUstep localized resource
6018 files in ‘.strings’ syntax, not in PO file syntax.
6020 9.7.4 Informative output
6021 ------------------------
6025 Display this help and exit.
6029 Output version information and exit.
6032 File: gettext.info, Node: msgattrib Invocation, Next: msgen Invocation, Prev: msgcmp Invocation, Up: Manipulating
6034 9.8 Invoking the ‘msgattrib’ Program
6035 ====================================
6037 msgattrib [OPTION] [INPUTFILE]
6039 The ‘msgattrib’ program filters the messages of a translation catalog
6040 according to their attributes, and manipulates the attributes.
6042 9.8.1 Input file location
6043 -------------------------
6049 ‘--directory=DIRECTORY’
6050 Add DIRECTORY to the list of directories. Source files are
6051 searched relative to this list of directories. The resulting ‘.po’
6052 file will be written relative to the current directory, though.
6054 If no INPUTFILE is given or if it is ‘-’, standard input is read.
6056 9.8.2 Output file location
6057 --------------------------
6060 ‘--output-file=FILE’
6061 Write output to specified file.
6063 The results are written to standard output if no output file is
6064 specified or if it is ‘-’.
6066 9.8.3 Message selection
6067 -----------------------
6070 Keep translated messages, remove untranslated messages.
6073 Keep untranslated messages, remove translated messages.
6076 Remove ‘fuzzy’ marked messages.
6079 Keep ‘fuzzy’ marked messages, remove all other messages.
6082 Remove obsolete #~ messages.
6085 Keep obsolete #~ messages, remove all other messages.
6087 9.8.4 Attribute manipulation
6088 ----------------------------
6090 Attributes are modified after the message selection/removal has been
6091 performed. If the ‘--only-file’ or ‘--ignore-file’ option is specified,
6092 the attribute modification is applied only to those messages that are
6093 listed in the ONLY-FILE and not listed in the IGNORE-FILE.
6096 Set all messages ‘fuzzy’.
6099 Set all messages non-‘fuzzy’.
6102 Set all messages obsolete.
6105 Set all messages non-obsolete.
6108 When setting ‘fuzzy’ mark, keep “previous msgid” of translated
6112 Remove the “previous msgid” (‘#|’) comments from all messages.
6115 When removing ‘fuzzy’ mark, also set msgstr empty.
6118 Limit the attribute changes to entries that are listed in FILE.
6119 FILE should be a PO or POT file.
6121 ‘--ignore-file=FILE’
6122 Limit the attribute changes to entries that are not listed in FILE.
6123 FILE should be a PO or POT file.
6126 Synonym for ‘--only-fuzzy --clear-fuzzy’: It keeps only the fuzzy
6127 messages and removes their ‘fuzzy’ mark.
6130 Synonym for ‘--only-obsolete --clear-obsolete’: It keeps only the
6131 obsolete messages and makes them non-obsolete.
6133 9.8.5 Input file syntax
6134 -----------------------
6137 ‘--properties-input’
6138 Assume the input file is a Java ResourceBundle in Java
6139 ‘.properties’ syntax, not in PO file syntax.
6141 ‘--stringtable-input’
6142 Assume the input file is a NeXTstep/GNUstep localized resource file
6143 in ‘.strings’ syntax, not in PO file syntax.
6145 9.8.6 Output details
6146 --------------------
6150 Specify whether or when to use colors and other text attributes.
6151 See *note The --color option:: for details.
6153 ‘--style=STYLE_FILE’
6154 Specify the CSS style rule file to use for ‘--color’. See *note
6155 The --style option:: for details.
6158 Always write an output file even if it contains no message.
6162 Write the .po file using indented style.
6165 Do not write ‘#: FILENAME:LINE’ lines.
6168 ‘--add-location=TYPE’
6169 Generate ‘#: FILENAME:LINE’ lines (default).
6171 The optional TYPE can be either ‘full’, ‘file’, or ‘never’. If it
6172 is not given or ‘full’, it generates the lines with both file name
6173 and line number. If it is ‘file’, the line number part is omitted.
6174 If it is ‘never’, it completely suppresses the lines (same as
6178 Write out a strict Uniforum conforming PO file. Note that this
6179 Uniforum format should be avoided because it doesn’t support the
6183 ‘--properties-output’
6184 Write out a Java ResourceBundle in Java ‘.properties’ syntax. Note
6185 that this file format doesn’t support plural forms and silently
6186 drops obsolete messages.
6188 ‘--stringtable-output’
6189 Write out a NeXTstep/GNUstep localized resource file in ‘.strings’
6190 syntax. Note that this file format doesn’t support plural forms.
6194 Set the output page width. Long strings in the output files will
6195 be split across multiple lines in order to ensure that each line’s
6196 width (= number of screen columns) is less or equal to the given
6200 Do not break long message lines. Message lines whose width exceeds
6201 the output page width will not be split into several lines. Only
6202 file reference lines which are wider than the output page width
6207 Generate sorted output. Note that using this option makes it much
6208 harder for the translator to understand each message’s context.
6212 Sort output by file location.
6214 9.8.7 Informative output
6215 ------------------------
6219 Display this help and exit.
6223 Output version information and exit.
6226 File: gettext.info, Node: msgen Invocation, Next: msgexec Invocation, Prev: msgattrib Invocation, Up: Manipulating
6228 9.9 Invoking the ‘msgen’ Program
6229 ================================
6231 msgen [OPTION] INPUTFILE
6233 The ‘msgen’ program creates an English translation catalog. The
6234 input file is the last created English PO file, or a PO Template file
6235 (generally created by xgettext). Untranslated entries are assigned a
6236 translation that is identical to the msgid.
6238 Note: ‘msginit --no-translator --locale=en’ performs a very similar
6239 task. The main difference is that ‘msginit’ cares specially about the
6240 header entry, whereas ‘msgen’ doesn’t.
6242 9.9.1 Input file location
6243 -------------------------
6246 Input PO or POT file.
6249 ‘--directory=DIRECTORY’
6250 Add DIRECTORY to the list of directories. Source files are
6251 searched relative to this list of directories. The resulting ‘.po’
6252 file will be written relative to the current directory, though.
6254 If INPUTFILE is ‘-’, standard input is read.
6256 9.9.2 Output file location
6257 --------------------------
6260 ‘--output-file=FILE’
6261 Write output to specified file.
6263 The results are written to standard output if no output file is
6264 specified or if it is ‘-’.
6266 9.9.3 Input file syntax
6267 -----------------------
6270 ‘--properties-input’
6271 Assume the input file is a Java ResourceBundle in Java
6272 ‘.properties’ syntax, not in PO file syntax.
6274 ‘--stringtable-input’
6275 Assume the input file is a NeXTstep/GNUstep localized resource file
6276 in ‘.strings’ syntax, not in PO file syntax.
6278 9.9.4 Output details
6279 --------------------
6281 ‘--lang=CATALOGNAME’
6282 Specify the ‘Language’ field to be used in the header entry. See
6283 *note Header Entry:: for the meaning of this field. Note: The
6284 ‘Language-Team’ and ‘Plural-Forms’ fields are not set by this
6289 Specify whether or when to use colors and other text attributes.
6290 See *note The --color option:: for details.
6292 ‘--style=STYLE_FILE’
6293 Specify the CSS style rule file to use for ‘--color’. See *note
6294 The --style option:: for details.
6297 Always write an output file even if it contains no message.
6301 Write the .po file using indented style.
6304 Do not write ‘#: FILENAME:LINE’ lines.
6307 ‘--add-location=TYPE’
6308 Generate ‘#: FILENAME:LINE’ lines (default).
6310 The optional TYPE can be either ‘full’, ‘file’, or ‘never’. If it
6311 is not given or ‘full’, it generates the lines with both file name
6312 and line number. If it is ‘file’, the line number part is omitted.
6313 If it is ‘never’, it completely suppresses the lines (same as
6317 Write out a strict Uniforum conforming PO file. Note that this
6318 Uniforum format should be avoided because it doesn’t support the
6322 ‘--properties-output’
6323 Write out a Java ResourceBundle in Java ‘.properties’ syntax. Note
6324 that this file format doesn’t support plural forms and silently
6325 drops obsolete messages.
6327 ‘--stringtable-output’
6328 Write out a NeXTstep/GNUstep localized resource file in ‘.strings’
6329 syntax. Note that this file format doesn’t support plural forms.
6333 Set the output page width. Long strings in the output files will
6334 be split across multiple lines in order to ensure that each line’s
6335 width (= number of screen columns) is less or equal to the given
6339 Do not break long message lines. Message lines whose width exceeds
6340 the output page width will not be split into several lines. Only
6341 file reference lines which are wider than the output page width
6346 Generate sorted output. Note that using this option makes it much
6347 harder for the translator to understand each message’s context.
6351 Sort output by file location.
6353 9.9.5 Informative output
6354 ------------------------
6358 Display this help and exit.
6362 Output version information and exit.
6365 File: gettext.info, Node: msgexec Invocation, Next: Colorizing, Prev: msgen Invocation, Up: Manipulating
6367 9.10 Invoking the ‘msgexec’ Program
6368 ===================================
6370 msgexec [OPTION] COMMAND [COMMAND-OPTION]
6372 The ‘msgexec’ program applies a command to all translations of a
6373 translation catalog. The COMMAND can be any program that reads a
6374 translation from standard input. It is invoked once for each
6375 translation. Its output becomes msgexec’s output. ‘msgexec’’s return
6376 code is the maximum return code across all invocations.
6378 A special builtin command called ‘0’ outputs the translation,
6379 followed by a null byte. The output of ‘msgexec 0’ is suitable as input
6383 Add newline at the end of each input line.
6385 During each COMMAND invocation, the environment variable
6386 ‘MSGEXEC_MSGID’ is bound to the message’s msgid, and the environment
6387 variable ‘MSGEXEC_LOCATION’ is bound to the location in the PO file of
6388 the message. If the message has a context, the environment variable
6389 ‘MSGEXEC_MSGCTXT’ is bound to the message’s msgctxt, otherwise it is
6390 unbound. If the message has a plural form, environment variable
6391 ‘MSGEXEC_MSGID_PLURAL’ is bound to the message’s msgid_plural and
6392 ‘MSGEXEC_PLURAL_FORM’ is bound to the order number of the plural
6393 actually processed (starting with 0), otherwise both are unbound. If
6394 the message has a previous msgid (added by ‘msgmerge’), environment
6395 variable ‘MSGEXEC_PREV_MSGCTXT’ is bound to the message’s previous
6396 msgctxt, ‘MSGEXEC_PREV_MSGID’ is bound to the previous msgid, and
6397 ‘MSGEXEC_PREV_MSGID_PLURAL’ is bound to the previous msgid_plural.
6399 Note: It is your responsibility to ensure that the COMMAND can cope
6400 with input encoded in the translation catalog’s encoding. If the
6401 COMMAND wants input in a particular encoding, you can in a first step
6402 convert the translation catalog to that encoding using the ‘msgconv’
6403 program, before invoking ‘msgexec’. If the COMMAND wants input in the
6404 locale’s encoding, but you want to avoid the locale’s encoding, then you
6405 can first convert the translation catalog to UTF-8 using the ‘msgconv’
6406 program and then make ‘msgexec’ work in an UTF-8 locale, by using the
6407 ‘LC_ALL’ environment variable.
6409 9.10.1 Input file location
6410 --------------------------
6417 ‘--directory=DIRECTORY’
6418 Add DIRECTORY to the list of directories. Source files are
6419 searched relative to this list of directories. The resulting ‘.po’
6420 file will be written relative to the current directory, though.
6422 If no INPUTFILE is given or if it is ‘-’, standard input is read.
6424 9.10.2 Input file syntax
6425 ------------------------
6428 ‘--properties-input’
6429 Assume the input file is a Java ResourceBundle in Java
6430 ‘.properties’ syntax, not in PO file syntax.
6432 ‘--stringtable-input’
6433 Assume the input file is a NeXTstep/GNUstep localized resource file
6434 in ‘.strings’ syntax, not in PO file syntax.
6436 9.10.3 Informative output
6437 -------------------------
6441 Display this help and exit.
6445 Output version information and exit.
6448 File: gettext.info, Node: Colorizing, Next: libgettextpo, Prev: msgexec Invocation, Up: Manipulating
6450 9.11 Highlighting parts of PO files
6451 ===================================
6453 Translators are usually only interested in seeing the untranslated
6454 and fuzzy messages of a PO file. Also, when a message is set fuzzy
6455 because the msgid changed, they want to see the differences between the
6456 previous msgid and the current one (especially if the msgid is long and
6457 only few words in it have changed). Finally, it’s always welcome to
6458 highlight the different sections of a message in a PO file (comments,
6459 msgid, msgstr, etc.).
6461 Such highlighting is possible through the ‘msgcat’ options ‘--color’
6466 * The --color option:: Triggering colorized output
6467 * The TERM variable:: The environment variable ‘TERM’
6468 * The --style option:: The ‘--style’ option
6469 * Style rules:: Style rules for PO files
6470 * Customizing less:: Customizing ‘less’ for viewing PO files
6473 File: gettext.info, Node: The --color option, Next: The TERM variable, Prev: Colorizing, Up: Colorizing
6475 9.11.1 The ‘--color’ option
6476 ---------------------------
6478 The ‘--color=WHEN’ option specifies under which conditions colorized
6479 output should be generated. The WHEN part can be one of the following:
6483 The output will be colorized.
6487 The output will not be colorized.
6491 The output will be colorized if the output device is a tty, i.e.
6492 when the output goes directly to a text screen or terminal emulator
6496 The output will be colorized and be in HTML format.
6498 ‘--color’ is equivalent to ‘--color=yes’. The default is
6501 Thus, a command like ‘msgcat vi.po’ will produce colorized output
6502 when called by itself in a command window. Whereas in a pipe, such as
6503 ‘msgcat vi.po | less -R’, it will not produce colorized output. To get
6504 colorized output in this situation nevertheless, use the command ‘msgcat
6505 --color vi.po | less -R’.
6507 The ‘--color=html’ option will produce output that can be viewed in a
6508 browser. This can be useful, for example, for Indic languages, because
6509 the renderic of Indic scripts in browser is usually better than in
6512 Note that the output produced with the ‘--color’ option is _not_ a
6513 valid PO file in itself. It contains additional terminal-specific
6514 escape sequences or HTML tags. A PO file reader will give a syntax
6515 error when confronted with such content. Except for the ‘--color=html’
6516 case, you therefore normally don’t need to save output produced with the
6517 ‘--color’ option in a file.
6520 File: gettext.info, Node: The TERM variable, Next: The --style option, Prev: The --color option, Up: Colorizing
6522 9.11.2 The environment variable ‘TERM’
6523 --------------------------------------
6525 The environment variable ‘TERM’ contains a identifier for the text
6526 window’s capabilities. You can get a detailed list of these
6527 cababilities by using the ‘infocmp’ command, using ‘man 5 terminfo’ as a
6530 When producing text with embedded color directives, ‘msgcat’ looks at
6531 the ‘TERM’ variable. Text windows today typically support at least 8
6532 colors. Often, however, the text window supports 16 or more colors,
6533 even though the ‘TERM’ variable is set to a identifier denoting only 8
6534 supported colors. It can be worth setting the ‘TERM’ variable to a
6535 different value in these cases:
6538 ‘xterm’ is in most cases built with support for 16 colors. It can
6539 also be built with support for 88 or 256 colors (but not both).
6540 You can try to set ‘TERM’ to either ‘xterm-16color’,
6541 ‘xterm-88color’, or ‘xterm-256color’.
6544 ‘rxvt’ is often built with support for 16 colors. You can try to
6545 set ‘TERM’ to ‘rxvt-16color’.
6548 ‘konsole’ too is often built with support for 16 colors. You can
6549 try to set ‘TERM’ to ‘konsole-16color’ or ‘xterm-16color’.
6551 After setting ‘TERM’, you can verify it by invoking ‘msgcat
6552 --color=test’ and seeing whether the output looks like a reasonable
6556 File: gettext.info, Node: The --style option, Next: Style rules, Prev: The TERM variable, Up: Colorizing
6558 9.11.3 The ‘--style’ option
6559 ---------------------------
6561 The ‘--style=STYLE_FILE’ option specifies the style file to use when
6562 colorizing. It has an effect only when the ‘--color’ option is
6565 If the ‘--style’ option is not specified, the environment variable
6566 ‘PO_STYLE’ is considered. It is meant to point to the user’s preferred
6569 The default style file is
6570 ‘$prefix/share/gettext/styles/po-default.css’, where ‘$prefix’ is the
6571 installation location.
6573 A few style files are predefined:
6575 This style imitates the look used by vim 7.
6578 This style imitates the look used by GNU Emacs 21 and 22 in an X11
6581 ‘po-emacs-xterm.css’
6582 ‘po-emacs-xterm16.css’
6583 ‘po-emacs-xterm256.css’
6584 This style imitates the look used by GNU Emacs 22 in a terminal of
6585 type ‘xterm’ (8 colors) or ‘xterm-16color’ (16 colors) or
6586 ‘xterm-256color’ (256 colors), respectively.
6588 You can use these styles without specifying a directory. They are
6589 actually located in ‘$prefix/share/gettext/styles/’, where ‘$prefix’ is
6590 the installation location.
6592 You can also design your own styles. This is described in the next
6596 File: gettext.info, Node: Style rules, Next: Customizing less, Prev: The --style option, Up: Colorizing
6598 9.11.4 Style rules for PO files
6599 -------------------------------
6601 The same style file can be used for styling of a PO file, for
6602 terminal output and for HTML output. It is written in CSS (Cascading
6603 Style Sheet) syntax. See <http://www.w3.org/TR/css2/cover.html> for a
6604 formal definition of CSS. Many HTML authoring tutorials also contain
6605 explanations of CSS.
6607 In the case of HTML output, the style file is embedded in the HTML
6608 output. In the case of text output, the style file is interpreted by
6609 the ‘msgcat’ program. This means, in particular, that when ‘@import’ is
6610 used with relative file names, the file names are
6612 − relative to the resulting HTML file, in the case of HTML output,
6614 − relative to the style sheet containing the ‘@import’, in the case
6615 of text output. (Actually, ‘@import’s are not yet supported in
6616 this case, due to a limitation in ‘libcroco’.)
6618 CSS rules are built up from selectors and declarations. The
6619 declarations specify graphical properties; the selectors specify specify
6622 In PO files, the following simple selectors (based on "CSS classes",
6623 see the CSS2 spec, section 5.8.3) are supported.
6625 • Selectors that apply to entire messages:
6628 This matches the header entry of a PO file.
6631 This matches a translated message.
6634 This matches an untranslated message (i.e. a message with
6638 This matches a fuzzy message (i.e. a message which has a
6639 translation that needs review by the translator).
6642 This matches an obsolete message (i.e. a message that was
6643 translated but is not needed by the current POT file any
6646 • Selectors that apply to parts of a message in PO syntax. Recall
6647 the general structure of a message in PO syntax:
6650 # TRANSLATOR-COMMENTS
6651 #. EXTRACTED-COMMENTS
6654 #| msgid PREVIOUS-UNTRANSLATED-STRING
6655 msgid UNTRANSLATED-STRING
6656 msgstr TRANSLATED-STRING
6659 This matches all comments (translator comments, extracted
6660 comments, source file reference comments, flag comments,
6661 previous message comments, as well as the entire obsolete
6664 ‘.translator-comment’
6665 This matches the translator comments.
6667 ‘.extracted-comment’
6668 This matches the extracted comments, i.e. the comments placed
6669 by the programmer at the attention of the translator.
6671 ‘.reference-comment’
6672 This matches the source file reference comments (entire
6676 This matches the individual source file references inside the
6677 source file reference comment lines.
6680 This matches the flag comment lines (entire lines).
6683 This matches the individual flags inside flag comment lines.
6686 This matches the ‘fuzzy’ flag inside flag comment lines.
6689 This matches the comments containing the previous untranslated
6690 string (entire lines).
6693 This matches the previous untranslated string including the
6694 string delimiters, the associated keywords (‘msgid’ etc.) and
6695 the spaces between them.
6698 This matches the untranslated string including the string
6699 delimiters, the associated keywords (‘msgid’ etc.) and the
6700 spaces between them.
6703 This matches the translated string including the string
6704 delimiters, the associated keywords (‘msgstr’ etc.) and the
6705 spaces between them.
6708 This matches the keywords (‘msgid’, ‘msgstr’, etc.).
6711 This matches strings, including the string delimiters (double
6714 • Selectors that apply to parts of strings:
6717 This matches the entire contents of a string (excluding the
6718 string delimiters, i.e. the double quotes).
6721 This matches an escape sequence (starting with a backslash).
6724 This matches a format string directive (starting with a ‘%’
6725 sign in the case of most programming languages, with a ‘{’ in
6726 the case of ‘java-format’ and ‘csharp-format’, with a ‘~’ in
6727 the case of ‘lisp-format’ and ‘scheme-format’, or with ‘$’ in
6728 the case of ‘sh-format’).
6730 ‘.invalid-format-directive’
6731 This matches an invalid format string directive.
6734 In an untranslated string, this matches a part of the string
6735 that was not present in the previous untranslated string.
6736 (Not yet implemented in this release.)
6739 In an untranslated string or in a previous untranslated
6740 string, this matches a part of the string that is changed or
6741 replaced. (Not yet implemented in this release.)
6744 In a previous untranslated string, this matches a part of the
6745 string that is not present in the current untranslated string.
6746 (Not yet implemented in this release.)
6748 These selectors can be combined to hierarchical selectors. For
6751 .msgstr .invalid-format-directive { color: red; }
6753 will highlight the invalid format directives in the translated strings.
6755 In text mode, pseudo-classes (CSS2 spec, section 5.11) and
6756 pseudo-elements (CSS2 spec, section 5.12) are not supported.
6758 The declarations in HTML mode are not limited; any graphical
6759 attribute supported by the browsers can be used.
6761 The declarations in text mode are limited to the following
6762 properties. Other properties will be silently ignored.
6764 ‘color’ (CSS2 spec, section 14.1)
6765 ‘background-color’ (CSS2 spec, section 14.2.1)
6766 These properties is supported. Colors will be adjusted to match
6767 the terminal’s capabilities. Note that many terminals support only
6770 ‘font-weight’ (CSS2 spec, section 15.2.3)
6771 This property is supported, but most terminals can only render two
6772 different weights: ‘normal’ and ‘bold’. Values >= 600 are rendered
6775 ‘font-style’ (CSS2 spec, section 15.2.3)
6776 This property is supported. The values ‘italic’ and ‘oblique’ are
6777 rendered the same way.
6779 ‘text-decoration’ (CSS2 spec, section 16.3.1)
6780 This property is supported, limited to the values ‘none’ and
6784 File: gettext.info, Node: Customizing less, Prev: Style rules, Up: Colorizing
6786 9.11.5 Customizing ‘less’ for viewing PO files
6787 ----------------------------------------------
6789 The ‘less’ program is a popular text file browser for use in a text
6790 screen or terminal emulator. It also supports text with embedded escape
6791 sequences for colors and text decorations.
6793 You can use ‘less’ to view a PO file like this (assuming an UTF-8
6796 msgcat --to-code=UTF-8 --color xyz.po | less -R
6798 You can simplify this to this simple command:
6802 after these three preparations:
6804 1. Add the options ‘-R’ and ‘-f’ to the ‘LESS’ environment variable.
6806 $ LESS="$LESS -R -f"
6809 2. If your system does not already have the ‘lessopen.sh’ and
6810 ‘lessclose.sh’ scripts, create them and set the ‘LESSOPEN’ and
6811 ‘LESSCLOSE’ environment variables, as indicated in the manual page
6814 3. Add to ‘lessopen.sh’ a piece of script that recognizes PO files
6815 through their file extension and invokes ‘msgcat’ on them,
6816 producing a temporary file. Like this:
6820 tmpfile=`mktemp "${TMPDIR-/tmp}/less.XXXXXX"`
6821 msgcat --to-code=UTF-8 --color "$1" > "$tmpfile"
6828 File: gettext.info, Node: libgettextpo, Prev: Colorizing, Up: Manipulating
6830 9.12 Writing your own programs that process PO files
6831 ====================================================
6833 For the tasks for which a combination of ‘msgattrib’, ‘msgcat’ etc.
6834 is not sufficient, a set of C functions is provided in a library, to
6835 make it possible to process PO files in your own programs. When you use
6836 this library, you don’t need to write routines to parse the PO file;
6837 instead, you retrieve a pointer in memory to each of messages contained
6838 in the PO file. Functions for writing PO files are not provided at this
6841 The functions are declared in the header file ‘<gettext-po.h>’, and
6842 are defined in a library called ‘libgettextpo’.
6844 -- Data Type: po_file_t
6845 This is a pointer type that refers to the contents of a PO file,
6846 after it has been read into memory.
6848 -- Data Type: po_message_iterator_t
6849 This is a pointer type that refers to an iterator that produces a
6850 sequence of messages.
6852 -- Data Type: po_message_t
6853 This is a pointer type that refers to a message of a PO file,
6854 including its translation.
6856 -- Function: po_file_t po_file_read (const char *FILENAME)
6857 The ‘po_file_read’ function reads a PO file into memory. The file
6858 name is given as argument. The return value is a handle to the PO
6859 file’s contents, valid until ‘po_file_free’ is called on it. In
6860 case of error, the return value is ‘NULL’, and ‘errno’ is set.
6862 -- Function: void po_file_free (po_file_t FILE)
6863 The ‘po_file_free’ function frees a PO file’s contents from memory,
6864 including all messages that are only implicitly accessible through
6867 -- Function: const char * const * po_file_domains (po_file_t FILE)
6868 The ‘po_file_domains’ function returns the domains for which the
6869 given PO file has messages. The return value is a ‘NULL’
6870 terminated array which is valid as long as the FILE handle is
6871 valid. For PO files which contain no ‘domain’ directive, the
6872 return value contains only one domain, namely the default domain
6875 -- Function: po_message_iterator_t po_message_iterator (po_file_t FILE,
6877 The ‘po_message_iterator’ returns an iterator that will produce the
6878 messages of FILE that belong to the given DOMAIN. If DOMAIN is
6879 ‘NULL’, the default domain is used instead. To list the messages,
6880 use the function ‘po_next_message’ repeatedly.
6882 -- Function: void po_message_iterator_free (po_message_iterator_t
6884 The ‘po_message_iterator_free’ function frees an iterator
6885 previously allocated through the ‘po_message_iterator’ function.
6887 -- Function: po_message_t po_next_message (po_message_iterator_t
6889 The ‘po_next_message’ function returns the next message from
6890 ITERATOR and advances the iterator. It returns ‘NULL’ when the
6891 iterator has reached the end of its message list.
6893 The following functions returns details of a ‘po_message_t’. Recall
6894 that the results are valid as long as the FILE handle is valid.
6896 -- Function: const char * po_message_msgid (po_message_t MESSAGE)
6897 The ‘po_message_msgid’ function returns the ‘msgid’ (untranslated
6898 English string) of a message. This is guaranteed to be non-‘NULL’.
6900 -- Function: const char * po_message_msgid_plural (po_message_t
6902 The ‘po_message_msgid_plural’ function returns the ‘msgid_plural’
6903 (untranslated English plural string) of a message with plurals, or
6904 ‘NULL’ for a message without plural.
6906 -- Function: const char * po_message_msgstr (po_message_t MESSAGE)
6907 The ‘po_message_msgstr’ function returns the ‘msgstr’ (translation)
6908 of a message. For an untranslated message, the return value is an
6911 -- Function: const char * po_message_msgstr_plural (po_message_t
6913 The ‘po_message_msgstr_plural’ function returns the ‘msgstr[INDEX]’
6914 of a message with plurals, or ‘NULL’ when the INDEX is out of range
6915 or for a message without plural.
6917 Here is an example code how these functions can be used.
6919 const char *filename = …;
6920 po_file_t file = po_file_read (filename);
6923 error (EXIT_FAILURE, errno, "couldn't open the PO file %s", filename);
6925 const char * const *domains = po_file_domains (file);
6926 const char * const *domainp;
6928 for (domainp = domains; *domainp; domainp++)
6930 const char *domain = *domainp;
6931 po_message_iterator_t iterator = po_message_iterator (file, domain);
6935 po_message_t *message = po_next_message (iterator);
6937 if (message == NULL)
6940 const char *msgid = po_message_msgid (message);
6941 const char *msgstr = po_message_msgstr (message);
6946 po_message_iterator_free (iterator);
6949 po_file_free (file);
6952 File: gettext.info, Node: Binaries, Next: Programmers, Prev: Manipulating, Up: Top
6954 10 Producing Binary MO Files
6955 ****************************
6959 * msgfmt Invocation:: Invoking the ‘msgfmt’ Program
6960 * msgunfmt Invocation:: Invoking the ‘msgunfmt’ Program
6961 * MO Files:: The Format of GNU MO Files
6964 File: gettext.info, Node: msgfmt Invocation, Next: msgunfmt Invocation, Prev: Binaries, Up: Binaries
6966 10.1 Invoking the ‘msgfmt’ Program
6967 ==================================
6969 msgfmt [OPTION] FILENAME.po …
6971 The ‘msgfmt’ programs generates a binary message catalog from a
6972 textual translation description.
6974 10.1.1 Input file location
6975 --------------------------
6980 ‘--directory=DIRECTORY’
6981 Add DIRECTORY to the list of directories. Source files are
6982 searched relative to this list of directories. The resulting
6983 binary file will be written relative to the current directory,
6986 If an input file is ‘-’, standard input is read.
6988 10.1.2 Operation mode
6989 ---------------------
6993 Java mode: generate a Java ‘ResourceBundle’ class.
6996 Like –java, and assume Java2 (JDK 1.2 or higher).
6999 C# mode: generate a .NET .dll file containing a subclass of
7000 ‘GettextResourceSet’.
7002 ‘--csharp-resources’
7003 C# resources mode: generate a .NET ‘.resources’ file.
7006 Tcl mode: generate a tcl/msgcat ‘.msg’ file.
7009 Qt mode: generate a Qt ‘.qm’ file.
7012 Desktop Entry mode: generate a ‘.desktop’ file.
7015 XML mode: generate an XML file.
7017 10.1.3 Output file location
7018 ---------------------------
7021 ‘--output-file=FILE’
7022 Write output to specified file.
7025 Direct the program to work strictly following the Uniforum/Sun
7026 implementation. Currently this only affects the naming of the
7027 output file. If this option is not given the name of the output
7028 file is the same as the domain name. If the strict Uniforum mode
7029 is enabled the suffix ‘.mo’ is added to the file name if it is not
7032 We find this behaviour of Sun’s implementation rather silly and so
7033 by default this mode is _not_ selected.
7035 If the output FILE is ‘-’, output is written to standard output.
7037 10.1.4 Output file location in Java mode
7038 ----------------------------------------
7041 ‘--resource=RESOURCE’
7042 Specify the resource name.
7046 Specify the locale name, either a language specification of the
7047 form LL or a combined language and country specification of the
7051 Specify the base directory of classes directory hierarchy.
7054 Produce a .java source file, instead of a compiled .class file.
7056 The class name is determined by appending the locale name to the
7057 resource name, separated with an underscore. The ‘-d’ option is
7058 mandatory. The class is written under the specified directory.
7060 10.1.5 Output file location in C# mode
7061 --------------------------------------
7064 ‘--resource=RESOURCE’
7065 Specify the resource name.
7069 Specify the locale name, either a language specification of the
7070 form LL or a combined language and country specification of the
7074 Specify the base directory for locale dependent ‘.dll’ files.
7076 The ‘-l’ and ‘-d’ options are mandatory. The ‘.dll’ file is written
7077 in a subdirectory of the specified directory whose name depends on the
7080 10.1.6 Output file location in Tcl mode
7081 ---------------------------------------
7085 Specify the locale name, either a language specification of the
7086 form LL or a combined language and country specification of the
7090 Specify the base directory of ‘.msg’ message catalogs.
7092 The ‘-l’ and ‘-d’ options are mandatory. The ‘.msg’ file is written
7093 in the specified directory.
7095 10.1.7 Desktop Entry mode operations
7096 ------------------------------------
7098 ‘--template=TEMPLATE’
7099 Specify a .desktop file used as a template.
7102 ‘--keyword[=KEYWORDSPEC]’
7103 Specify KEYWORDSPEC as an additional keyword to be looked for.
7104 Without a KEYWORDSPEC, the option means to not use default
7109 Specify the locale name, either a language specification of the
7110 form LL or a combined language and country specification of the
7114 Specify the directory where PO files are read. The directory must
7115 contain the ‘LINGUAS’ file.
7117 To generate a ‘.desktop’ file for a single locale, you can use it as
7120 msgfmt --desktop --template=TEMPLATE --locale=LOCALE \
7121 -o FILE FILENAME.po …
7123 msgfmt provides a special "bulk" operation mode to process multiple
7124 ‘.po’ files at a time.
7126 msgfmt --desktop --template=TEMPLATE -d DIRECTORY -o FILE
7128 msgfmt first reads the ‘LINGUAS’ file under DIRECTORY, and then
7129 processes all ‘.po’ files listed there. You can also limit the locales
7130 to a subset, through the ‘LINGUAS’ environment variable.
7132 For either operation modes, the ‘-o’ and ‘--template’ options are
7135 10.1.8 XML mode operations
7136 --------------------------
7138 ‘--template=TEMPLATE’
7139 Specify an XML file used as a template.
7143 Specifies the language of the input files.
7147 Specify the locale name, either a language specification of the
7148 form LL or a combined language and country specification of the
7152 Specify the base directory of ‘.po’ message catalogs.
7154 To generate an XML file for a single locale, you can use it as
7157 msgfmt --xml --template=TEMPLATE --locale=LOCALE \
7158 -o FILE FILENAME.po …
7160 msgfmt provides a special "bulk" operation mode to process multiple
7161 ‘.po’ files at a time.
7163 msgfmt --xml --template=TEMPLATE -d DIRECTORY -o FILE
7165 msgfmt first reads the ‘LINGUAS’ file under DIRECTORY, and then
7166 processes all ‘.po’ files listed there. You can also limit the locales
7167 to a subset, through the ‘LINGUAS’ environment variable.
7169 For either operation modes, the ‘-o’ and ‘--template’ options are
7172 10.1.9 Input file syntax
7173 ------------------------
7176 ‘--properties-input’
7177 Assume the input files are Java ResourceBundles in Java
7178 ‘.properties’ syntax, not in PO file syntax.
7180 ‘--stringtable-input’
7181 Assume the input files are NeXTstep/GNUstep localized resource
7182 files in ‘.strings’ syntax, not in PO file syntax.
7184 10.1.10 Input file interpretation
7185 ---------------------------------
7189 Perform all the checks implied by ‘--check-format’,
7190 ‘--check-header’, ‘--check-domain’.
7193 Check language dependent format strings.
7195 If the string represents a format string used in a ‘printf’-like
7196 function both strings should have the same number of ‘%’ format
7197 specifiers, with matching types. If the flag ‘c-format’ or
7198 ‘possible-c-format’ appears in the special comment <#,> for this
7199 entry a check is performed. For example, the check will diagnose
7200 using ‘%.*s’ against ‘%s’, or ‘%d’ against ‘%s’, or ‘%d’ against
7201 ‘%x’. It can even handle positional parameters.
7203 Normally the ‘xgettext’ program automatically decides whether a
7204 string is a format string or not. This algorithm is not perfect,
7205 though. It might regard a string as a format string though it is
7206 not used in a ‘printf’-like function and so ‘msgfmt’ might report
7207 errors where there are none.
7209 To solve this problem the programmer can dictate the decision to
7210 the ‘xgettext’ program (*note c-format::). The translator should
7211 not consider removing the flag from the <#,> line. This "fix"
7212 would be reversed again as soon as ‘msgmerge’ is called the next
7216 Verify presence and contents of the header entry. *Note Header
7217 Entry::, for a description of the various fields in the header
7221 Check for conflicts between domain directives and the
7222 ‘--output-file’ option
7225 ‘--check-compatibility’
7226 Check that GNU msgfmt behaves like X/Open msgfmt. This will give
7227 an error when attempting to use the GNU extensions.
7229 ‘--check-accelerators[=CHAR]’
7230 Check presence of keyboard accelerators for menu items. This is
7231 based on the convention used in some GUIs that a keyboard
7232 accelerator in a menu item string is designated by an immediately
7233 preceding ‘&’ character. Sometimes a keyboard accelerator is also
7234 called "keyboard mnemonic". This check verifies that if the
7235 untranslated string has exactly one ‘&’ character, the translated
7236 string has exactly one ‘&’ as well. If this option is given with a
7237 CHAR argument, this CHAR should be a non-alphanumeric character and
7238 is used as keyboard accelerator mark instead of ‘&’.
7242 Use fuzzy entries in output. Note that using this option is
7243 usually wrong, because fuzzy messages are exactly those which have
7244 not been validated by a human translator.
7246 10.1.11 Output details
7247 ----------------------
7250 ‘--alignment=NUMBER’
7251 Align strings to NUMBER bytes (default: 1).
7253 ‘--endianness=BYTEORDER’
7254 Write out 32-bit numbers in the given byte order. The possible
7255 values are ‘big’ and ‘little’. The default is ‘little’.
7257 MO files of any endianness can be used on any platform. When a MO
7258 file has an endianness other than the platform’s one, the 32-bit
7259 numbers from the MO file are swapped at runtime. The performance
7260 impact is negligible.
7262 This option can be useful to produce MO files that are optimized
7266 Don’t include a hash table in the binary file. Lookup will be more
7267 expensive at run time (binary search instead of hash table lookup).
7269 10.1.12 Informative output
7270 --------------------------
7274 Display this help and exit.
7278 Output version information and exit.
7281 Print statistics about translations. When the option ‘--verbose’
7282 is used in combination with ‘--statistics’, the input file name is
7283 printed in front of the statistics line.
7287 Increase verbosity level.
7290 File: gettext.info, Node: msgunfmt Invocation, Next: MO Files, Prev: msgfmt Invocation, Up: Binaries
7292 10.2 Invoking the ‘msgunfmt’ Program
7293 ====================================
7295 msgunfmt [OPTION] [FILE]...
7297 The ‘msgunfmt’ program converts a binary message catalog to a
7298 Uniforum style .po file.
7300 10.2.1 Operation mode
7301 ---------------------
7305 Java mode: input is a Java ‘ResourceBundle’ class.
7308 C# mode: input is a .NET .dll file containing a subclass of
7309 ‘GettextResourceSet’.
7311 ‘--csharp-resources’
7312 C# resources mode: input is a .NET ‘.resources’ file.
7315 Tcl mode: input is a tcl/msgcat ‘.msg’ file.
7317 10.2.2 Input file location
7318 --------------------------
7323 If no input FILE is given or if it is ‘-’, standard input is read.
7325 10.2.3 Input file location in Java mode
7326 ---------------------------------------
7329 ‘--resource=RESOURCE’
7330 Specify the resource name.
7334 Specify the locale name, either a language specification of the
7335 form LL or a combined language and country specification of the
7338 The class name is determined by appending the locale name to the
7339 resource name, separated with an underscore. The class is located using
7342 10.2.4 Input file location in C# mode
7343 -------------------------------------
7346 ‘--resource=RESOURCE’
7347 Specify the resource name.
7351 Specify the locale name, either a language specification of the
7352 form LL or a combined language and country specification of the
7356 Specify the base directory for locale dependent ‘.dll’ files.
7358 The ‘-l’ and ‘-d’ options are mandatory. The ‘.msg’ file is located
7359 in a subdirectory of the specified directory whose name depends on the
7362 10.2.5 Input file location in Tcl mode
7363 --------------------------------------
7367 Specify the locale name, either a language specification of the
7368 form LL or a combined language and country specification of the
7372 Specify the base directory of ‘.msg’ message catalogs.
7374 The ‘-l’ and ‘-d’ options are mandatory. The ‘.msg’ file is located
7375 in the specified directory.
7377 10.2.6 Output file location
7378 ---------------------------
7381 ‘--output-file=FILE’
7382 Write output to specified file.
7384 The results are written to standard output if no output file is
7385 specified or if it is ‘-’.
7387 10.2.7 Output details
7388 ---------------------
7392 Specify whether or when to use colors and other text attributes.
7393 See *note The --color option:: for details.
7395 ‘--style=STYLE_FILE’
7396 Specify the CSS style rule file to use for ‘--color’. See *note
7397 The --style option:: for details.
7400 Always write an output file even if it contains no message.
7404 Write the .po file using indented style.
7407 Write out a strict Uniforum conforming PO file. Note that this
7408 Uniforum format should be avoided because it doesn’t support the
7412 ‘--properties-output’
7413 Write out a Java ResourceBundle in Java ‘.properties’ syntax. Note
7414 that this file format doesn’t support plural forms and silently
7415 drops obsolete messages.
7417 ‘--stringtable-output’
7418 Write out a NeXTstep/GNUstep localized resource file in ‘.strings’
7419 syntax. Note that this file format doesn’t support plural forms.
7423 Set the output page width. Long strings in the output files will
7424 be split across multiple lines in order to ensure that each line’s
7425 width (= number of screen columns) is less or equal to the given
7429 Do not break long message lines. Message lines whose width exceeds
7430 the output page width will not be split into several lines. Only
7431 file reference lines which are wider than the output page width
7436 Generate sorted output. Note that using this option makes it much
7437 harder for the translator to understand each message’s context.
7439 10.2.8 Informative output
7440 -------------------------
7444 Display this help and exit.
7448 Output version information and exit.
7452 Increase verbosity level.
7455 File: gettext.info, Node: MO Files, Prev: msgunfmt Invocation, Up: Binaries
7457 10.3 The Format of GNU MO Files
7458 ===============================
7460 The format of the generated MO files is best described by a picture,
7461 which appears below.
7463 The first two words serve the identification of the file. The magic
7464 number will always signal GNU MO files. The number is stored in the
7465 byte order used when the MO file was generated, so the magic number
7466 really is two numbers: ‘0x950412de’ and ‘0xde120495’.
7468 The second word describes the current revision of the file format,
7469 composed of a major and a minor revision number. The revision numbers
7470 ensure that the readers of MO files can distinguish new formats from old
7471 ones and handle their contents, as far as possible. For now the major
7472 revision is 0 or 1, and the minor revision is also 0 or 1. More
7473 revisions might be added in the future. A program seeing an unexpected
7474 major revision number should stop reading the MO file entirely; whereas
7475 an unexpected minor revision number means that the file can be read but
7476 will not reveal its full contents, when parsed by a program that
7477 supports only smaller minor revision numbers.
7479 The version is kept separate from the magic number, instead of using
7480 different magic numbers for different formats, mainly because
7481 ‘/etc/magic’ is not updated often.
7483 Follow a number of pointers to later tables in the file, allowing for
7484 the extension of the prefix part of MO files without having to recompile
7485 programs reading them. This might become useful for later inserting a
7486 few flag bits, indication about the charset used, new tables, or other
7489 Then, at offset O and offset T in the picture, two tables of string
7490 descriptors can be found. In both tables, each string descriptor uses
7491 two 32 bits integers, one for the string length, another for the offset
7492 of the string in the MO file, counting in bytes from the start of the
7493 file. The first table contains descriptors for the original strings,
7494 and is sorted so the original strings are in increasing lexicographical
7495 order. The second table contains descriptors for the translated
7496 strings, and is parallel to the first table: to find the corresponding
7497 translation one has to access the array slot in the second array with
7500 Having the original strings sorted enables the use of simple binary
7501 search, for when the MO file does not contain an hashing table, or for
7502 when it is not practical to use the hashing table provided in the MO
7503 file. This also has another advantage, as the empty string in a PO file
7504 GNU ‘gettext’ is usually _translated_ into some system information
7505 attached to that particular MO file, and the empty string necessarily
7506 becomes the first in both the original and translated tables, making the
7507 system information very easy to find.
7509 The size S of the hash table can be zero. In this case, the hash
7510 table itself is not contained in the MO file. Some people might prefer
7511 this because a precomputed hashing table takes disk space, and does not
7512 win _that_ much speed. The hash table contains indices to the sorted
7513 array of strings in the MO file. Conflict resolution is done by double
7514 hashing. The precise hashing algorithm used is fairly dependent on GNU
7515 ‘gettext’ code, and is not documented here.
7517 As for the strings themselves, they follow the hash file, and each is
7518 terminated with a <NUL>, and this <NUL> is not counted in the length
7519 which appears in the string descriptor. The ‘msgfmt’ program has an
7520 option selecting the alignment for MO file strings. With this option,
7521 each string is separately aligned so it starts at an offset which is a
7522 multiple of the alignment value. On some RISC machines, a correct
7523 alignment will speed things up.
7525 Contexts are stored by storing the concatenation of the context, a
7526 <EOT> byte, and the original string, instead of the original string.
7528 Plural forms are stored by letting the plural of the original string
7529 follow the singular of the original string, separated through a <NUL>
7530 byte. The length which appears in the string descriptor includes both.
7531 However, only the singular of the original string takes part in the hash
7532 table lookup. The plural variants of the translation are all stored
7533 consecutively, separated through a <NUL> byte. Here also, the length in
7534 the string descriptor includes all of them.
7536 Nothing prevents a MO file from having embedded <NUL>s in strings.
7537 However, the program interface currently used already presumes that
7538 strings are <NUL> terminated, so embedded <NUL>s are somewhat useless.
7539 But the MO file format is general enough so other interfaces would be
7540 later possible, if for example, we ever want to implement wide
7541 characters right in MO files, where <NUL> bytes may accidentally appear.
7542 (No, we don’t want to have wide characters in MO files. They would make
7543 the file unnecessarily large, and the ‘wchar_t’ type being platform
7544 dependent, MO files would be platform dependent as well.)
7546 This particular issue has been strongly debated in the GNU ‘gettext’
7547 development forum, and it is expectable that MO file format will evolve
7548 or change over time. It is even possible that many formats may later be
7549 supported concurrently. But surely, we have to start somewhere, and the
7550 MO file format described here is a good start. Nothing is cast in
7551 concrete, and the format may later evolve fairly easily, so we should
7552 feel comfortable with the current approach.
7555 +------------------------------------------+
7556 0 | magic number = 0x950412de |
7558 4 | file format revision = 0 |
7560 8 | number of strings | == N
7562 12 | offset of table with original strings | == O
7564 16 | offset of table with translation strings | == T
7566 20 | size of hashing table | == S
7568 24 | offset of hashing table | == H
7571 . (possibly more entries later) .
7574 O | length & offset 0th string ----------------.
7575 O + 8 | length & offset 1st string ------------------.
7577 O + ((N-1)*8)| length & offset (N-1)th string | | |
7579 T | length & offset 0th translation ---------------.
7580 T + 8 | length & offset 1st translation -----------------.
7582 T + ((N-1)*8)| length & offset (N-1)th translation | | | | |
7584 H | start hash table | | | | |
7586 H + S * 4 | end hash table | | | | |
7588 | NUL terminated 0th string <----------------' | | |
7590 | NUL terminated 1st string <------------------' | |
7594 | NUL terminated 0th translation <---------------' |
7596 | NUL terminated 1st translation <-----------------'
7600 +------------------------------------------+
7603 File: gettext.info, Node: Programmers, Next: Translators, Prev: Binaries, Up: Top
7605 11 The Programmer’s View
7606 ************************
7608 One aim of the current message catalog implementation provided by GNU
7609 ‘gettext’ was to use the system’s message catalog handling, if the
7610 installer wishes to do so. So we perhaps should first take a look at
7611 the solutions we know about. The people in the POSIX committee did not
7612 manage to agree on one of the semi-official standards which we’ll
7613 describe below. In fact they couldn’t agree on anything, so they
7614 decided only to include an example of an interface. The major Unix
7615 vendors are split in the usage of the two most important specifications:
7616 X/Open’s catgets vs. Uniforum’s gettext interface. We’ll describe them
7617 both and later explain our solution of this dilemma.
7621 * catgets:: About ‘catgets’
7622 * gettext:: About ‘gettext’
7623 * Comparison:: Comparing the two interfaces
7624 * Using libintl.a:: Using libintl.a in own programs
7625 * gettext grok:: Being a ‘gettext’ grok
7626 * Temp Programmers:: Temporary Notes for the Programmers Chapter
7629 File: gettext.info, Node: catgets, Next: gettext, Prev: Programmers, Up: Programmers
7631 11.1 About ‘catgets’
7632 ====================
7634 The ‘catgets’ implementation is defined in the X/Open Portability
7635 Guide, Volume 3, XSI Supplementary Definitions, Chapter 5. But the
7636 process of creating this standard seemed to be too slow for some of the
7637 Unix vendors so they created their implementations on preliminary
7638 versions of the standard. Of course this leads again to problems while
7639 writing platform independent programs: even the usage of ‘catgets’ does
7640 not guarantee a unique interface.
7642 Another, personal comment on this that only a bunch of committee
7643 members could have made this interface. They never really tried to
7644 program using this interface. It is a fast, memory-saving
7645 implementation, an user can happily live with it. But programmers hate
7646 it (at least I and some others do…)
7648 But we must not forget one point: after all the trouble with
7649 transferring the rights on Unix(tm) they at last came to X/Open, the
7650 very same who published this specification. This leads me to making the
7651 prediction that this interface will be in future Unix standards (e.g.
7652 Spec1170) and therefore part of all Unix implementation
7653 (implementations, which are _allowed_ to wear this name).
7657 * Interface to catgets:: The interface
7658 * Problems with catgets:: Problems with the ‘catgets’ interface?!
7661 File: gettext.info, Node: Interface to catgets, Next: Problems with catgets, Prev: catgets, Up: catgets
7663 11.1.1 The Interface
7664 --------------------
7666 The interface to the ‘catgets’ implementation consists of three
7667 functions which correspond to those used in file access: ‘catopen’ to
7668 open the catalog for using, ‘catgets’ for accessing the message tables,
7669 and ‘catclose’ for closing after work is done. Prototypes for the
7670 functions and the needed definitions are in the ‘<nl_types.h>’ header
7673 ‘catopen’ is used like in this:
7675 nl_catd catd = catopen ("catalog_name", 0);
7677 The function takes as the argument the name of the catalog. This
7678 usual refers to the name of the program or the package. The second
7679 parameter is not further specified in the standard. I don’t even know
7680 whether it is implemented consistently among various systems. So the
7681 common advice is to use ‘0’ as the value. The return value is a handle
7682 to the message catalog, equivalent to handles to file returned by
7685 This handle is of course used in the ‘catgets’ function which can be
7688 char *translation = catgets (catd, set_no, msg_id, "original string");
7690 The first parameter is this catalog descriptor. The second parameter
7691 specifies the set of messages in this catalog, in which the message
7692 described by ‘msg_id’ is obtained. ‘catgets’ therefore uses a
7693 three-stage addressing:
7695 catalog name ⇒ set number ⇒ message ID ⇒ translation
7697 The fourth argument is not used to address the translation. It is
7698 given as a default value in case when one of the addressing stages fail.
7699 One important thing to remember is that although the return type of
7700 catgets is ‘char *’ the resulting string _must not_ be changed. It
7701 should better be ‘const char *’, but the standard is published in 1988,
7702 one year before ANSI C.
7704 The last of these functions is used and behaves as expected:
7708 After this no ‘catgets’ call using the descriptor is legal anymore.
7711 File: gettext.info, Node: Problems with catgets, Prev: Interface to catgets, Up: catgets
7713 11.1.2 Problems with the ‘catgets’ Interface?!
7714 ----------------------------------------------
7716 Now that this description seemed to be really easy — where are the
7717 problems we speak of? In fact the interface could be used in a
7718 reasonable way, but constructing the message catalogs is a pain. The
7719 reason for this lies in the third argument of ‘catgets’: the unique
7720 message ID. This has to be a numeric value for all messages in a single
7721 set. Perhaps you could imagine the problems keeping such a list while
7722 changing the source code. Add a new message here, remove one there. Of
7723 course there have been developed a lot of tools helping to organize this
7724 chaos but one as the other fails in one aspect or the other. We don’t
7725 want to say that the other approach has no problems but they are far
7726 more easy to manage.
7729 File: gettext.info, Node: gettext, Next: Comparison, Prev: catgets, Up: Programmers
7731 11.2 About ‘gettext’
7732 ====================
7734 The definition of the ‘gettext’ interface comes from a Uniforum
7735 proposal. It was submitted there by Sun, who had implemented the
7736 ‘gettext’ function in SunOS 4, around 1990. Nowadays, the ‘gettext’
7737 interface is specified by the OpenI18N standard.
7739 The main point about this solution is that it does not follow the
7740 method of normal file handling (open-use-close) and that it does not
7741 burden the programmer with so many tasks, especially the unique key
7742 handling. Of course here also a unique key is needed, but this key is
7743 the message itself (how long or short it is). See *note Comparison::
7744 for a more detailed comparison of the two methods.
7746 The following section contains a rather detailed description of the
7747 interface. We make it that detailed because this is the interface we
7748 chose for the GNU ‘gettext’ Library. Programmers interested in using
7749 this library will be interested in this description.
7753 * Interface to gettext:: The interface
7754 * Ambiguities:: Solving ambiguities
7755 * Locating Catalogs:: Locating message catalog files
7756 * Charset conversion:: How to request conversion to Unicode
7757 * Contexts:: Solving ambiguities in GUI programs
7758 * Plural forms:: Additional functions for handling plurals
7759 * Optimized gettext:: Optimization of the *gettext functions
7762 File: gettext.info, Node: Interface to gettext, Next: Ambiguities, Prev: gettext, Up: gettext
7764 11.2.1 The Interface
7765 --------------------
7767 The minimal functionality an interface must have is a) to select a
7768 domain the strings are coming from (a single domain for all programs is
7769 not reasonable because its construction and maintenance is difficult,
7770 perhaps impossible) and b) to access a string in a selected domain.
7772 This is principally the description of the ‘gettext’ interface. It
7773 has a global domain which unqualified usages reference. Of course this
7774 domain is selectable by the user.
7776 char *textdomain (const char *domain_name);
7778 This provides the possibility to change or query the current status
7779 of the current global domain of the ‘LC_MESSAGE’ category. The argument
7780 is a null-terminated string, whose characters must be legal in the use
7781 in filenames. If the DOMAIN_NAME argument is ‘NULL’, the function
7782 returns the current value. If no value has been set before, the name of
7783 the default domain is returned: _messages_. Please note that although
7784 the return value of ‘textdomain’ is of type ‘char *’ no changing is
7785 allowed. It is also important to know that no checks of the
7786 availability are made. If the name is not available you will see this
7787 by the fact that no translations are provided.
7789 To use a domain set by ‘textdomain’ the function
7791 char *gettext (const char *msgid);
7793 is to be used. This is the simplest reasonable form one can imagine.
7794 The translation of the string MSGID is returned if it is available in
7795 the current domain. If it is not available, the argument itself is
7796 returned. If the argument is ‘NULL’ the result is undefined.
7798 One thing which should come into mind is that no explicit dependency
7799 to the used domain is given. The current value of the domain is used.
7800 If this changes between two executions of the same ‘gettext’ call in the
7801 program, both calls reference a different message catalog.
7803 For the easiest case, which is normally used in internationalized
7804 packages, once at the beginning of execution a call to ‘textdomain’ is
7805 issued, setting the domain to a unique name, normally the package name.
7806 In the following code all strings which have to be translated are
7807 filtered through the gettext function. That’s all, the package speaks
7811 File: gettext.info, Node: Ambiguities, Next: Locating Catalogs, Prev: Interface to gettext, Up: gettext
7813 11.2.2 Solving Ambiguities
7814 --------------------------
7816 While this single name domain works well for most applications there
7817 might be the need to get translations from more than one domain. Of
7818 course one could switch between different domains with calls to
7819 ‘textdomain’, but this is really not convenient nor is it fast. A
7820 possible situation could be one case subject to discussion during this
7821 writing: all error messages of functions in the set of common used
7822 functions should go into a separate domain ‘error’. By this mean we
7823 would only need to translate them once. Another case are messages from
7824 a library, as these _have_ to be independent of the current domain set
7827 For this reasons there are two more functions to retrieve strings:
7829 char *dgettext (const char *domain_name, const char *msgid);
7830 char *dcgettext (const char *domain_name, const char *msgid,
7833 Both take an additional argument at the first place, which
7834 corresponds to the argument of ‘textdomain’. The third argument of
7835 ‘dcgettext’ allows to use another locale category but ‘LC_MESSAGES’.
7836 But I really don’t know where this can be useful. If the DOMAIN_NAME is
7837 ‘NULL’ or CATEGORY has an value beside the known ones, the result is
7838 undefined. It should also be noted that this function is not part of
7839 the second known implementation of this function family, the one found
7842 A second ambiguity can arise by the fact, that perhaps more than one
7843 domain has the same name. This can be solved by specifying where the
7844 needed message catalog files can be found.
7846 char *bindtextdomain (const char *domain_name,
7847 const char *dir_name);
7849 Calling this function binds the given domain to a file in the
7850 specified directory (how this file is determined follows below).
7851 Especially a file in the systems default place is not favored against
7852 the specified file anymore (as it would be by solely using
7853 ‘textdomain’). A ‘NULL’ pointer for the DIR_NAME parameter returns the
7854 binding associated with DOMAIN_NAME. If DOMAIN_NAME itself is ‘NULL’
7855 nothing happens and a ‘NULL’ pointer is returned. Here again as for all
7856 the other functions is true that none of the return value must be
7859 It is important to remember that relative path names for the DIR_NAME
7860 parameter can be trouble. Since the path is always computed relative to
7861 the current directory different results will be achieved when the
7862 program executes a ‘chdir’ command. Relative paths should always be
7863 avoided to avoid dependencies and unreliabilities.
7866 File: gettext.info, Node: Locating Catalogs, Next: Charset conversion, Prev: Ambiguities, Up: gettext
7868 11.2.3 Locating Message Catalog Files
7869 -------------------------------------
7871 Because many different languages for many different packages have to
7872 be stored we need some way to add these information to file message
7873 catalog files. The way usually used in Unix environments is have this
7874 encoding in the file name. This is also done here. The directory name
7875 given in ‘bindtextdomain’s second argument (or the default directory),
7876 followed by the name of the locale, the locale category, and the domain
7877 name are concatenated:
7879 DIR_NAME/LOCALE/LC_CATEGORY/DOMAIN_NAME.mo
7881 The default value for DIR_NAME is system specific. For the GNU
7882 library, and for packages adhering to its conventions, it’s:
7883 /usr/local/share/locale
7885 LOCALE is the name of the locale category which is designated by
7886 ‘LC_CATEGORY’. For ‘gettext’ and ‘dgettext’ this ‘LC_CATEGORY’ is
7887 always ‘LC_MESSAGES’.(1) The name of the locale category is determined
7888 through ‘setlocale (LC_CATEGORY, NULL)’. (2) When using the function
7889 ‘dcgettext’, you can specify the locale category through the third
7892 ---------- Footnotes ----------
7894 (1) Some system, e.g. mingw, don’t have ‘LC_MESSAGES’. Here we use a
7895 more or less arbitrary value for it, namely 1729, the smallest positive
7896 integer which can be represented in two different ways as the sum of two
7899 (2) When the system does not support ‘setlocale’ its behavior in
7900 setting the locale values is simulated by looking at the environment
7904 File: gettext.info, Node: Charset conversion, Next: Contexts, Prev: Locating Catalogs, Up: gettext
7906 11.2.4 How to specify the output character set ‘gettext’ uses
7907 -------------------------------------------------------------
7909 ‘gettext’ not only looks up a translation in a message catalog. It
7910 also converts the translation on the fly to the desired output character
7911 set. This is useful if the user is working in a different character set
7912 than the translator who created the message catalog, because it avoids
7913 distributing variants of message catalogs which differ only in the
7916 The output character set is, by default, the value of ‘nl_langinfo
7917 (CODESET)’, which depends on the ‘LC_CTYPE’ part of the current locale.
7918 But programs which store strings in a locale independent way (e.g.
7919 UTF-8) can request that ‘gettext’ and related functions return the
7920 translations in that encoding, by use of the ‘bind_textdomain_codeset’
7923 Note that the MSGID argument to ‘gettext’ is not subject to character
7924 set conversion. Also, when ‘gettext’ does not find a translation for
7925 MSGID, it returns MSGID unchanged – independently of the current output
7926 character set. It is therefore recommended that all MSGIDs be US-ASCII
7929 -- Function: char * bind_textdomain_codeset (const char *DOMAINNAME,
7930 const char *CODESET)
7931 The ‘bind_textdomain_codeset’ function can be used to specify the
7932 output character set for message catalogs for domain DOMAINNAME.
7933 The CODESET argument must be a valid codeset name which can be used
7934 for the ‘iconv_open’ function, or a null pointer.
7936 If the CODESET parameter is the null pointer,
7937 ‘bind_textdomain_codeset’ returns the currently selected codeset
7938 for the domain with the name DOMAINNAME. It returns ‘NULL’ if no
7939 codeset has yet been selected.
7941 The ‘bind_textdomain_codeset’ function can be used several times.
7942 If used multiple times with the same DOMAINNAME argument, the later
7943 call overrides the settings made by the earlier one.
7945 The ‘bind_textdomain_codeset’ function returns a pointer to a
7946 string containing the name of the selected codeset. The string is
7947 allocated internally in the function and must not be changed by the
7948 user. If the system went out of core during the execution of
7949 ‘bind_textdomain_codeset’, the return value is ‘NULL’ and the
7950 global variable ERRNO is set accordingly.
7953 File: gettext.info, Node: Contexts, Next: Plural forms, Prev: Charset conversion, Up: gettext
7955 11.2.5 Using contexts for solving ambiguities
7956 ---------------------------------------------
7958 One place where the ‘gettext’ functions, if used normally, have big
7959 problems is within programs with graphical user interfaces (GUIs). The
7960 problem is that many of the strings which have to be translated are very
7961 short. They have to appear in pull-down menus which restricts the
7962 length. But strings which are not containing entire sentences or at
7963 least large fragments of a sentence may appear in more than one
7964 situation in the program but might have different translations. This is
7965 especially true for the one-word strings which are frequently used in
7968 As a consequence many people say that the ‘gettext’ approach is wrong
7969 and instead ‘catgets’ should be used which indeed does not have this
7970 problem. But there is a very simple and powerful method to handle this
7971 kind of problems with the ‘gettext’ functions.
7973 Contexts can be added to strings to be translated. A context
7974 dependent translation lookup is when a translation for a given string is
7975 searched, that is limited to a given context. The translation for the
7976 same string in a different context can be different. The different
7977 translations of the same string in different contexts can be stored in
7978 the in the same MO file, and can be edited by the translator in the same
7981 The ‘gettext.h’ include file contains the lookup macros for strings
7982 with contexts. They are implemented as thin macros and inline functions
7983 over the functions from ‘<libintl.h>’.
7985 const char *pgettext (const char *msgctxt, const char *msgid);
7987 In a call of this macro, MSGCTXT and MSGID must be string literals.
7988 The macro returns the translation of MSGID, restricted to the context
7991 The MSGCTXT string is visible in the PO file to the translator. You
7992 should try to make it somehow canonical and never changing. Because
7993 every time you change an MSGCTXT, the translator will have to review the
7994 translation of MSGID.
7996 Finding a canonical MSGCTXT string that doesn’t change over time can
7997 be hard. But you shouldn’t use the file name or class name containing
7998 the ‘pgettext’ call – because it is a common development task to rename
7999 a file or a class, and it shouldn’t cause translator work. Also you
8000 shouldn’t use a comment in the form of a complete English sentence as
8001 MSGCTXT – because orthography or grammar changes are often applied to
8002 such sentences, and again, it shouldn’t force the translator to do a
8005 The ‘p’ in ‘pgettext’ stands for “particular”: ‘pgettext’ fetches a
8006 particular translation of the MSGID.
8008 const char *dpgettext (const char *domain_name,
8009 const char *msgctxt, const char *msgid);
8010 const char *dcpgettext (const char *domain_name,
8011 const char *msgctxt, const char *msgid,
8014 These are generalizations of ‘pgettext’. They behave similarly to
8015 ‘dgettext’ and ‘dcgettext’, respectively. The DOMAIN_NAME argument
8016 defines the translation domain. The CATEGORY argument allows to use
8017 another locale category than ‘LC_MESSAGES’.
8019 As as example consider the following fictional situation. A GUI
8020 program has a menu bar with the following entries:
8022 +------------+------------+--------------------------------------+
8023 | File | Printer | |
8024 +------------+------------+--------------------------------------+
8027 +----------+ | Connect |
8030 To have the strings ‘File’, ‘Printer’, ‘Open’, ‘New’, ‘Select’, and
8031 ‘Connect’ translated there has to be at some point in the code a call to
8032 a function of the ‘gettext’ family. But in two places the string passed
8033 into the function would be ‘Open’. The translations might not be the
8034 same and therefore we are in the dilemma described above.
8036 What distinguishes the two places is the menu path from the menu root
8037 to the particular menu entries:
8045 Menu|Printer|Connect
8047 The context is thus the menu path without its last part. So, the
8048 calls look like this:
8050 pgettext ("Menu|", "File")
8051 pgettext ("Menu|", "Printer")
8052 pgettext ("Menu|File|", "Open")
8053 pgettext ("Menu|File|", "New")
8054 pgettext ("Menu|Printer|", "Select")
8055 pgettext ("Menu|Printer|", "Open")
8056 pgettext ("Menu|Printer|", "Connect")
8058 Whether or not to use the ‘|’ character at the end of the context is
8061 For more complex cases, where the MSGCTXT or MSGID are not string
8062 literals, more general macros are available:
8064 const char *pgettext_expr (const char *msgctxt, const char *msgid);
8065 const char *dpgettext_expr (const char *domain_name,
8066 const char *msgctxt, const char *msgid);
8067 const char *dcpgettext_expr (const char *domain_name,
8068 const char *msgctxt, const char *msgid,
8071 Here MSGCTXT and MSGID can be arbitrary string-valued expressions.
8072 These macros are more general. But in the case that both argument
8073 expressions are string literals, the macros without the ‘_expr’ suffix
8077 File: gettext.info, Node: Plural forms, Next: Optimized gettext, Prev: Contexts, Up: gettext
8079 11.2.6 Additional functions for plural forms
8080 --------------------------------------------
8082 The functions of the ‘gettext’ family described so far (and all the
8083 ‘catgets’ functions as well) have one problem in the real world which
8084 have been neglected completely in all existing approaches. What is
8085 meant here is the handling of plural forms.
8087 Looking through Unix source code before the time anybody thought
8088 about internationalization (and, sadly, even afterwards) one can often
8089 find code similar to the following:
8091 printf ("%d file%s deleted", n, n == 1 ? "" : "s");
8093 After the first complaints from people internationalizing the code
8094 people either completely avoided formulations like this or used strings
8095 like ‘"file(s)"’. Both look unnatural and should be avoided. First
8096 tries to solve the problem correctly looked like this:
8099 printf ("%d file deleted", n);
8101 printf ("%d files deleted", n);
8103 But this does not solve the problem. It helps languages where the
8104 plural form of a noun is not simply constructed by adding an ‘s’ but
8105 that is all. Once again people fell into the trap of believing the
8106 rules their language is using are universal. But the handling of plural
8107 forms differs widely between the language families. For example, Rafal
8108 Maszkowski ‘<rzm@mat.uni.torun.pl>’ reports:
8110 In Polish we use e.g. plik (file) this way:
8116 and so on (o’ means 8859-2 oacute which should be rather okreska,
8117 similar to aogonek).
8119 There are two things which can differ between languages (and even
8120 inside language families);
8122 • The form how plural forms are built differs. This is a problem
8123 with languages which have many irregularities. German, for
8124 instance, is a drastic case. Though English and German are part of
8125 the same language family (Germanic), the almost regular forming of
8126 plural noun forms (appending an ‘s’) is hardly found in German.
8128 • The number of plural forms differ. This is somewhat surprising for
8129 those who only have experiences with Romanic and Germanic languages
8130 since here the number is the same (there are two).
8132 But other language families have only one form or many forms. More
8133 information on this in an extra section.
8135 The consequence of this is that application writers should not try to
8136 solve the problem in their code. This would be localization since it is
8137 only usable for certain, hardcoded language environments. Instead the
8138 extended ‘gettext’ interface should be used.
8140 These extra functions are taking instead of the one key string two
8141 strings and a numerical argument. The idea behind this is that using
8142 the numerical argument and the first string as a key, the implementation
8143 can select using rules specified by the translator the right plural
8144 form. The two string arguments then will be used to provide a return
8145 value in case no message catalog is found (similar to the normal
8146 ‘gettext’ behavior). In this case the rules for Germanic language is
8147 used and it is assumed that the first string argument is the singular
8148 form, the second the plural form.
8150 This has the consequence that programs without language catalogs can
8151 display the correct strings only if the program itself is written using
8152 a Germanic language. This is a limitation but since the GNU C library
8153 (as well as the GNU ‘gettext’ package) are written as part of the GNU
8154 package and the coding standards for the GNU project require program
8155 being written in English, this solution nevertheless fulfills its
8158 -- Function: char * ngettext (const char *MSGID1, const char *MSGID2,
8159 unsigned long int N)
8160 The ‘ngettext’ function is similar to the ‘gettext’ function as it
8161 finds the message catalogs in the same way. But it takes two extra
8162 arguments. The MSGID1 parameter must contain the singular form of
8163 the string to be converted. It is also used as the key for the
8164 search in the catalog. The MSGID2 parameter is the plural form.
8165 The parameter N is used to determine the plural form. If no
8166 message catalog is found MSGID1 is returned if ‘n == 1’, otherwise
8169 An example for the use of this function is:
8171 printf (ngettext ("%d file removed", "%d files removed", n), n);
8173 Please note that the numeric value N has to be passed to the
8174 ‘printf’ function as well. It is not sufficient to pass it only to
8177 In the English singular case, the number – always 1 – can be
8178 replaced with "one":
8180 printf (ngettext ("One file removed", "%d files removed", n), n);
8182 This works because the ‘printf’ function discards excess arguments
8183 that are not consumed by the format string.
8185 If this function is meant to yield a format string that takes two
8186 or more arguments, you can not use it like this:
8188 printf (ngettext ("%d file removed from directory %s",
8189 "%d files removed from directory %s",
8193 because in many languages the translators want to replace the ‘%d’
8194 with an explicit word in the singular case, just like “one” in
8195 English, and C format strings cannot consume the second argument
8196 but skip the first argument. Instead, you have to reorder the
8197 arguments so that ‘n’ comes last:
8199 printf (ngettext ("%2$d file removed from directory %1$s",
8200 "%2$d files removed from directory %1$s",
8204 See *note c-format:: for details about this argument reordering
8207 When you know that the value of ‘n’ is within a given range, you
8208 can specify it as a comment directed to the ‘xgettext’ tool. This
8209 information may help translators to use more adequate translations.
8212 if (days > 7 && days < 14)
8213 /* xgettext: range: 1..6 */
8214 printf (ngettext ("one week and one day", "one week and %d days",
8218 It is also possible to use this function when the strings don’t
8219 contain a cardinal number:
8221 puts (ngettext ("Delete the selected file?",
8222 "Delete the selected files?",
8225 In this case the number N is only used to choose the plural form.
8227 -- Function: char * dngettext (const char *DOMAIN, const char *MSGID1,
8228 const char *MSGID2, unsigned long int N)
8229 The ‘dngettext’ is similar to the ‘dgettext’ function in the way
8230 the message catalog is selected. The difference is that it takes
8231 two extra parameter to provide the correct plural form. These two
8232 parameters are handled in the same way ‘ngettext’ handles them.
8234 -- Function: char * dcngettext (const char *DOMAIN, const char *MSGID1,
8235 const char *MSGID2, unsigned long int N, int CATEGORY)
8236 The ‘dcngettext’ is similar to the ‘dcgettext’ function in the way
8237 the message catalog is selected. The difference is that it takes
8238 two extra parameter to provide the correct plural form. These two
8239 parameters are handled in the same way ‘ngettext’ handles them.
8241 Now, how do these functions solve the problem of the plural forms?
8242 Without the input of linguists (which was not available) it was not
8243 possible to determine whether there are only a few different forms in
8244 which plural forms are formed or whether the number can increase with
8245 every new supported language.
8247 Therefore the solution implemented is to allow the translator to
8248 specify the rules of how to select the plural form. Since the formula
8249 varies with every language this is the only viable solution except for
8250 hardcoding the information in the code (which still would require the
8251 possibility of extensions to not prevent the use of new languages).
8253 The information about the plural form selection has to be stored in
8254 the header entry of the PO file (the one with the empty ‘msgid’ string).
8255 The plural form information looks like this:
8257 Plural-Forms: nplurals=2; plural=n == 1 ? 0 : 1;
8259 The ‘nplurals’ value must be a decimal number which specifies how
8260 many different plural forms exist for this language. The string
8261 following ‘plural’ is an expression which is using the C language
8262 syntax. Exceptions are that no negative numbers are allowed, numbers
8263 must be decimal, and the only variable allowed is ‘n’. Spaces are
8264 allowed in the expression, but backslash-newlines are not; in the
8265 examples below the backslash-newlines are present for formatting
8266 purposes only. This expression will be evaluated whenever one of the
8267 functions ‘ngettext’, ‘dngettext’, or ‘dcngettext’ is called. The
8268 numeric value passed to these functions is then substituted for all uses
8269 of the variable ‘n’ in the expression. The resulting value then must be
8270 greater or equal to zero and smaller than the value given as the value
8273 The following rules are known at this point. The language with families
8274 are listed. But this does not necessarily mean the information can be
8275 generalized for the whole family (as can be easily seen in the table
8279 Some languages only require one single form. There is no
8280 distinction between the singular and plural form. An appropriate
8281 header entry would look like this:
8283 Plural-Forms: nplurals=1; plural=0;
8285 Languages with this property include:
8288 Japanese, Vietnamese, Korean
8292 Two forms, singular used for one only
8293 This is the form used in most existing programs since it is what
8294 English is using. A header entry would look like this:
8296 Plural-Forms: nplurals=2; plural=n != 1;
8298 (Note: this uses the feature of C expressions that boolean
8299 expressions have to value zero or one.)
8301 Languages with this property include:
8304 English, German, Dutch, Swedish, Danish, Norwegian, Faroese
8306 Spanish, Portuguese, Italian, Bulgarian
8318 Other languages using the same header entry are:
8322 Turkic/Altaic family
8325 Hungarian does not appear to have a plural if you look at sentences
8326 involving cardinal numbers. For example, “1 apple” is “1 alma”,
8327 and “123 apples” is “123 alma”. But when the number is not
8328 explicit, the distinction between singular and plural exists: “the
8329 apple” is “az alma”, and “the apples” is “az almák”. Since
8330 ‘ngettext’ has to support both types of sentences, it is classified
8331 here, under “two forms”.
8333 The same holds for Turkish: “1 apple” is “1 elma”, and “123 apples”
8334 is “123 elma”. But when the number is omitted, the distinction
8335 between singular and plural exists: “the apple” is “elma”, and “the
8336 apples” is “elmalar”.
8338 Two forms, singular used for zero and one
8339 Exceptional case in the language family. The header entry would
8342 Plural-Forms: nplurals=2; plural=n>1;
8344 Languages with this property include:
8347 Brazilian Portuguese, French
8349 Three forms, special case for zero
8350 The header entry would be:
8352 Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n != 0 ? 1 : 2;
8354 Languages with this property include:
8359 Three forms, special cases for one and two
8360 The header entry would be:
8362 Plural-Forms: nplurals=3; plural=n==1 ? 0 : n==2 ? 1 : 2;
8364 Languages with this property include:
8369 Three forms, special case for numbers ending in 00 or [2-9][0-9]
8370 The header entry would be:
8372 Plural-Forms: nplurals=3; \
8373 plural=n==1 ? 0 : (n==0 || (n%100 > 0 && n%100 < 20)) ? 1 : 2;
8375 Languages with this property include:
8380 Three forms, special case for numbers ending in 1[2-9]
8381 The header entry would look like this:
8383 Plural-Forms: nplurals=3; \
8384 plural=n%10==1 && n%100!=11 ? 0 : \
8385 n%10>=2 && (n%100<10 || n%100>=20) ? 1 : 2;
8387 Languages with this property include:
8392 Three forms, special cases for numbers ending in 1 and 2, 3, 4, except those ending in 1[1-4]
8393 The header entry would look like this:
8395 Plural-Forms: nplurals=3; \
8396 plural=n%10==1 && n%100!=11 ? 0 : \
8397 n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;
8399 Languages with this property include:
8402 Russian, Ukrainian, Belarusian, Serbian, Croatian
8404 Three forms, special cases for 1 and 2, 3, 4
8405 The header entry would look like this:
8407 Plural-Forms: nplurals=3; \
8408 plural=(n==1) ? 0 : (n>=2 && n<=4) ? 1 : 2;
8410 Languages with this property include:
8415 Three forms, special case for one and some numbers ending in 2, 3, or 4
8416 The header entry would look like this:
8418 Plural-Forms: nplurals=3; \
8420 n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;
8422 Languages with this property include:
8427 Four forms, special case for one and all numbers ending in 02, 03, or 04
8428 The header entry would look like this:
8430 Plural-Forms: nplurals=4; \
8431 plural=n%100==1 ? 0 : n%100==2 ? 1 : n%100==3 || n%100==4 ? 2 : 3;
8433 Languages with this property include:
8438 Six forms, special cases for one, two, all numbers ending in 02, 03, … 10, all numbers ending in 11 … 99, and others
8439 The header entry would look like this:
8441 Plural-Forms: nplurals=6; \
8442 plural=n==0 ? 0 : n==1 ? 1 : n==2 ? 2 : n%100>=3 && n%100<=10 ? 3 \
8443 : n%100>=11 ? 4 : 5;
8445 Languages with this property include:
8450 You might now ask, ‘ngettext’ handles only numbers N of type
8451 ‘unsigned long’. What about larger integer types? What about negative
8452 numbers? What about floating-point numbers?
8454 About larger integer types, such as ‘uintmax_t’ or ‘unsigned long
8455 long’: they can be handled by reducing the value to a range that fits in
8456 an ‘unsigned long’. Simply casting the value to ‘unsigned long’ would
8457 not do the right thing, since it would treat ‘ULONG_MAX + 1’ like zero,
8458 ‘ULONG_MAX + 2’ like singular, and the like. Here you can exploit the
8459 fact that all mentioned plural form formulas eventually become periodic,
8460 with a period that is a divisor of 100 (or 1000 or 1000000). So, when
8461 you reduce a large value to another one in the range [1000000, 1999999]
8462 that ends in the same 6 decimal digits, you can assume that it will lead
8463 to the same plural form selection. This code does this:
8465 #include <inttypes.h>
8466 uintmax_t nbytes = ...;
8467 printf (ngettext ("The file has %"PRIuMAX" byte.",
8468 "The file has %"PRIuMAX" bytes.",
8470 ? (nbytes % 1000000) + 1000000
8474 Negative and floating-point values usually represent physical
8475 entities for which singular and plural don’t clearly apply. In such
8476 cases, there is no need to use ‘ngettext’; a simple ‘gettext’ call with
8477 a form suitable for all values will do. For example:
8479 printf (gettext ("Time elapsed: %.3f seconds"),
8480 num_milliseconds * 0.001);
8482 Even if NUM_MILLISECONDS happens to be a multiple of 1000, the output
8483 Time elapsed: 1.000 seconds
8484 is acceptable in English, and similarly for other languages.
8486 The translators’ perspective regarding plural forms is explained in
8487 *note Translating plural forms::.
8489 ---------- Footnotes ----------
8491 (1) Additions are welcome. Send appropriate information to
8492 <bug-gnu-gettext@gnu.org> and <bug-glibc-manual@gnu.org>. The Unicode
8493 CLDR Project (<http://cldr.unicode.org>) provides a comprehensive set of
8494 plural forms in a different format. The ‘msginit’ program has
8495 preliminary support for the format so you can use it as a baseline
8496 (*note msginit Invocation::).
8499 File: gettext.info, Node: Optimized gettext, Prev: Plural forms, Up: gettext
8501 11.2.7 Optimization of the *gettext functions
8502 ---------------------------------------------
8504 At this point of the discussion we should talk about an advantage of
8505 the GNU ‘gettext’ implementation. Some readers might have pointed out
8506 that an internationalized program might have a poor performance if some
8507 string has to be translated in an inner loop. While this is unavoidable
8508 when the string varies from one run of the loop to the other it is
8509 simply a waste of time when the string is always the same. Take the
8515 puts (gettext ("Hello world"));
8519 When the locale selection does not change between two runs the resulting
8520 string is always the same. One way to use this is:
8523 str = gettext ("Hello world");
8530 But this solution is not usable in all situation (e.g. when the locale
8531 selection changes) nor does it lead to legible code.
8533 For this reason, GNU ‘gettext’ caches previous translation results.
8534 When the same translation is requested twice, with no new message
8535 catalogs being loaded in between, ‘gettext’ will, the second time, find
8536 the result through a single cache lookup.
8539 File: gettext.info, Node: Comparison, Next: Using libintl.a, Prev: gettext, Up: Programmers
8541 11.3 Comparing the Two Interfaces
8542 =================================
8544 The following discussion is perhaps a little bit colored. As said
8545 above we implemented GNU ‘gettext’ following the Uniforum proposal and
8546 this surely has its reasons. But it should show how we came to this
8549 First we take a look at the developing process. When we write an
8550 application using NLS provided by ‘gettext’ we proceed as always. Only
8551 when we come to a string which might be seen by the users and thus has
8552 to be translated we use ‘gettext("…")’ instead of ‘"…"’. At the
8553 beginning of each source file (or in a central header file) we define
8555 #define gettext(String) (String)
8557 Even this definition can be avoided when the system supports the
8558 ‘gettext’ function in its C library. When we compile this code the
8559 result is the same as if no NLS code is used. When you take a look at
8560 the GNU ‘gettext’ code you will see that we use ‘_("…")’ instead of
8561 ‘gettext("…")’. This reduces the number of additional characters per
8562 translatable string to _3_ (in words: three).
8564 When now a production version of the program is needed we simply
8565 replace the definition
8567 #define _(String) (String)
8571 #include <libintl.h>
8572 #define _(String) gettext (String)
8574 Additionally we run the program ‘xgettext’ on all source code file which
8575 contain translatable strings and that’s it: we have a running program
8576 which does not depend on translations to be available, but which can use
8577 any that becomes available.
8579 The same procedure can be done for the ‘gettext_noop’ invocations
8580 (*note Special cases::). One usually defines ‘gettext_noop’ as a no-op
8581 macro. So you should consider the following code for your project:
8583 #define gettext_noop(String) String
8584 #define N_(String) gettext_noop (String)
8586 ‘N_’ is a short form similar to ‘_’. The ‘Makefile’ in the ‘po/’
8587 directory of GNU ‘gettext’ knows by default both of the mentioned short
8588 forms so you are invited to follow this proposal for your own ease.
8590 Now to ‘catgets’. The main problem is the work for the programmer.
8591 Every time he comes to a translatable string he has to define a number
8592 (or a symbolic constant) which has also be defined in the message
8593 catalog file. He also has to take care for duplicate entries, duplicate
8594 message IDs etc. If he wants to have the same quality in the message
8595 catalog as the GNU ‘gettext’ program provides he also has to put the
8596 descriptive comments for the strings and the location in all source code
8597 files in the message catalog. This is nearly a Mission: Impossible.
8599 But there are also some points people might call advantages speaking
8600 for ‘catgets’. If you have a single word in a string and this string is
8601 used in different contexts it is likely that in one or the other
8602 language the word has different translations. Example:
8604 printf ("%s: %d", gettext ("number"), number_of_errors)
8606 printf ("you should see %d %s", number_count,
8607 number_count == 1 ? gettext ("number") : gettext ("numbers"))
8609 Here we have to translate two times the string ‘"number"’. Even if
8610 you do not speak a language beside English it might be possible to
8611 recognize that the two words have a different meaning. In German the
8612 first appearance has to be translated to ‘"Anzahl"’ and the second to
8615 Now you can say that this example is really esoteric. And you are
8616 right! This is exactly how we felt about this problem and decide that
8617 it does not weight that much. The solution for the above problem could
8620 printf ("%s %d", gettext ("number:"), number_of_errors)
8622 printf (number_count == 1 ? gettext ("you should see %d number")
8623 : gettext ("you should see %d numbers"),
8626 We believe that we can solve all conflicts with this method. If it
8627 is difficult one can also consider changing one of the conflicting
8628 string a little bit. But it is not impossible to overcome.
8630 ‘catgets’ allows same original entry to have different translations,
8631 but ‘gettext’ has another, scalable approach for solving ambiguities of
8632 this kind: *Note Ambiguities::.
8635 File: gettext.info, Node: Using libintl.a, Next: gettext grok, Prev: Comparison, Up: Programmers
8637 11.4 Using libintl.a in own programs
8638 ====================================
8640 Starting with version 0.9.4 the library ‘libintl.h’ should be
8641 self-contained. I.e., you can use it in your own programs without
8642 providing additional functions. The ‘Makefile’ will put the header and
8643 the library in directories selected using the ‘$(prefix)’.
8646 File: gettext.info, Node: gettext grok, Next: Temp Programmers, Prev: Using libintl.a, Up: Programmers
8648 11.5 Being a ‘gettext’ grok
8649 ===========================
8651 * NOTE: * This documentation section is outdated and needs to be
8654 To fully exploit the functionality of the GNU ‘gettext’ library it is
8655 surely helpful to read the source code. But for those who don’t want to
8656 spend that much time in reading the (sometimes complicated) code here is
8659 • Changing the language at runtime
8661 For interactive programs it might be useful to offer a selection of
8662 the used language at runtime. To understand how to do this one
8663 need to know how the used language is determined while executing
8664 the ‘gettext’ function. The method which is presented here only
8665 works correctly with the GNU implementation of the ‘gettext’
8668 In the function ‘dcgettext’ at every call the current setting of
8669 the highest priority environment variable is determined and used.
8670 Highest priority means here the following list with decreasing
8675 3. ‘LC_xxx’, according to selected locale category
8678 Afterwards the path is constructed using the found value and the
8679 translation file is loaded if available.
8681 What happens now when the value for, say, ‘LANGUAGE’ changes?
8682 According to the process explained above the new value of this
8683 variable is found as soon as the ‘dcgettext’ function is called.
8684 But this also means the (perhaps) different message catalog file is
8685 loaded. In other words: the used language is changed.
8687 But there is one little hook. The code for gcc-2.7.0 and up
8688 provides some optimization. This optimization normally prevents
8689 the calling of the ‘dcgettext’ function as long as no new catalog
8690 is loaded. But if ‘dcgettext’ is not called the program also
8691 cannot find the ‘LANGUAGE’ variable be changed (*note Optimized
8692 gettext::). A solution for this is very easy. Include the
8693 following code in the language switching function.
8695 /* Change language. */
8696 setenv ("LANGUAGE", "fr", 1);
8698 /* Make change known. */
8700 extern int _nl_msg_cat_cntr;
8704 The variable ‘_nl_msg_cat_cntr’ is defined in ‘loadmsgcat.c’. You
8705 don’t need to know what this is for. But it can be used to detect
8706 whether a ‘gettext’ implementation is GNU gettext and not non-GNU
8707 system’s native gettext implementation.
8710 File: gettext.info, Node: Temp Programmers, Prev: gettext grok, Up: Programmers
8712 11.6 Temporary Notes for the Programmers Chapter
8713 ================================================
8715 * NOTE: * This documentation section is outdated and needs to be
8720 * Temp Implementations:: Temporary - Two Possible Implementations
8721 * Temp catgets:: Temporary - About ‘catgets’
8722 * Temp WSI:: Temporary - Why a single implementation
8723 * Temp Notes:: Temporary - Notes
8726 File: gettext.info, Node: Temp Implementations, Next: Temp catgets, Prev: Temp Programmers, Up: Temp Programmers
8728 11.6.1 Temporary - Two Possible Implementations
8729 -----------------------------------------------
8731 There are two competing methods for language independent messages:
8732 the X/Open ‘catgets’ method, and the Uniforum ‘gettext’ method. The
8733 ‘catgets’ method indexes messages by integers; the ‘gettext’ method
8734 indexes them by their English translations. The ‘catgets’ method has
8735 been around longer and is supported by more vendors. The ‘gettext’
8736 method is supported by Sun, and it has been heard that the COSE
8737 multi-vendor initiative is supporting it. Neither method is a POSIX
8738 standard; the POSIX.1 committee had a lot of disagreement in this area.
8740 Neither one is in the POSIX standard. There was much disagreement in
8741 the POSIX.1 committee about using the ‘gettext’ routines vs. ‘catgets’
8742 (XPG). In the end the committee couldn’t agree on anything, so no
8743 messaging system was included as part of the standard. I believe the
8744 informative annex of the standard includes the XPG3 messaging
8745 interfaces, “…as an example of a messaging system that has been
8748 They were very careful not to say anywhere that you should use one
8749 set of interfaces over the other. For more on this topic please see the
8750 Programming for Internationalization FAQ.
8753 File: gettext.info, Node: Temp catgets, Next: Temp WSI, Prev: Temp Implementations, Up: Temp Programmers
8755 11.6.2 Temporary - About ‘catgets’
8756 ----------------------------------
8758 There have been a few discussions of late on the use of ‘catgets’ as
8759 a base. I think it important to present both sides of the argument and
8760 hence am opting to play devil’s advocate for a little bit.
8762 I’ll not deny the fact that ‘catgets’ could have been designed a lot
8763 better. It currently has quite a number of limitations and these have
8764 already been pointed out.
8766 However there is a great deal to be said for consistency and
8767 standardization. A common recurring problem when writing Unix software
8768 is the myriad portability problems across Unix platforms. It seems as
8769 if every Unix vendor had a look at the operating system and found parts
8770 they could improve upon. Undoubtedly, these modifications are probably
8771 innovative and solve real problems. However, software developers have a
8772 hard time keeping up with all these changes across so many platforms.
8774 And this has prompted the Unix vendors to begin to standardize their
8775 systems. Hence the impetus for Spec1170. Every major Unix vendor has
8776 committed to supporting this standard and every Unix software developer
8777 waits with glee the day they can write software to this standard and
8778 simply recompile (without having to use autoconf) across different
8781 As I understand it, Spec1170 is roughly based upon version 4 of the
8782 X/Open Portability Guidelines (XPG4). Because ‘catgets’ and friends are
8783 defined in XPG4, I’m led to believe that ‘catgets’ is a part of Spec1170
8784 and hence will become a standardized component of all Unix systems.
8787 File: gettext.info, Node: Temp WSI, Next: Temp Notes, Prev: Temp catgets, Up: Temp Programmers
8789 11.6.3 Temporary - Why a single implementation
8790 ----------------------------------------------
8792 Now it seems kind of wasteful to me to have two different systems
8793 installed for accessing message catalogs. If we do want to remedy
8794 ‘catgets’ deficiencies why don’t we try to expand ‘catgets’ (in a
8795 compatible manner) rather than implement an entirely new system.
8796 Otherwise, we’ll end up with two message catalog access systems
8797 installed with an operating system - one set of routines for packages
8798 using GNU ‘gettext’ for their internationalization, and another set of
8799 routines (catgets) for all other software. Bloated?
8801 Supposing another catalog access system is implemented. Which do we
8802 recommend? At least for Linux, we need to attract as many software
8803 developers as possible. Hence we need to make it as easy for them to
8804 port their software as possible. Which means supporting ‘catgets’. We
8805 will be implementing the ‘libintl’ code within our ‘libc’, but does this
8806 mean we also have to incorporate another message catalog access scheme
8807 within our ‘libc’ as well? And what about people who are going to be
8808 using the ‘libintl’ + non-‘catgets’ routines. When they port their
8809 software to other platforms, they’re now going to have to include the
8810 front-end (‘libintl’) code plus the back-end code (the non-‘catgets’
8811 access routines) with their software instead of just including the
8812 ‘libintl’ code with their software.
8814 Message catalog support is however only the tip of the iceberg. What
8815 about the data for the other locale categories? They also have a number
8816 of deficiencies. Are we going to abandon them as well and develop
8817 another duplicate set of routines (should ‘libintl’ expand beyond
8818 message catalog support)?
8820 Like many parts of Unix that can be improved upon, we’re stuck with
8821 balancing compatibility with the past with useful improvements and
8822 innovations for the future.
8825 File: gettext.info, Node: Temp Notes, Prev: Temp WSI, Up: Temp Programmers
8827 11.6.4 Temporary - Notes
8828 ------------------------
8830 X/Open agreed very late on the standard form so that many
8831 implementations differ from the final form. Both of my system (old
8832 Linux catgets and Ultrix-4) have a strange variation.
8834 OK. After incorporating the last changes I have to spend some time on
8835 making the GNU/Linux ‘libc’ ‘gettext’ functions. So in future Solaris
8836 is not the only system having ‘gettext’.
8839 File: gettext.info, Node: Translators, Next: Maintainers, Prev: Programmers, Up: Top
8841 12 The Translator’s View
8842 ************************
8846 * Trans Intro 0:: Introduction 0
8847 * Trans Intro 1:: Introduction 1
8848 * Discussions:: Discussions
8849 * Organization:: Organization
8850 * Information Flow:: Information Flow
8851 * Translating plural forms:: How to fill in ‘msgstr[0]’, ‘msgstr[1]’
8852 * Prioritizing messages:: How to find which messages to translate first
8855 File: gettext.info, Node: Trans Intro 0, Next: Trans Intro 1, Prev: Translators, Up: Translators
8860 * NOTE: * This documentation section is outdated and needs to be
8863 Free software is going international! The Translation Project is a
8864 way to get maintainers, translators and users all together, so free
8865 software will gradually become able to speak many native languages.
8867 The GNU ‘gettext’ tool set contains _everything_ maintainers need for
8868 internationalizing their packages for messages. It also contains quite
8869 useful tools for helping translators at localizing messages to their
8870 native language, once a package has already been internationalized.
8872 To achieve the Translation Project, we need many interested people
8873 who like their own language and write it well, and who are also able to
8874 synergize with other translators speaking the same language. If you’d
8875 like to volunteer to _work_ at translating messages, please send mail to
8876 your translating team.
8878 Each team has its own mailing list, courtesy of Linux International.
8879 You may reach your translating team at the address ‘LL@li.org’,
8880 replacing LL by the two-letter ISO 639 code for your language. Language
8881 codes are _not_ the same as country codes given in ISO 3166. The
8882 following translating teams exist:
8884 Chinese ‘zh’, Czech ‘cs’, Danish ‘da’, Dutch ‘nl’, Esperanto ‘eo’,
8885 Finnish ‘fi’, French ‘fr’, Irish ‘ga’, German ‘de’, Greek ‘el’,
8886 Italian ‘it’, Japanese ‘ja’, Indonesian ‘in’, Norwegian ‘no’,
8887 Polish ‘pl’, Portuguese ‘pt’, Russian ‘ru’, Spanish ‘es’, Swedish
8888 ‘sv’ and Turkish ‘tr’.
8890 For example, you may reach the Chinese translating team by writing to
8891 ‘zh@li.org’. When you become a member of the translating team for your
8892 own language, you may subscribe to its list. For example, Swedish
8893 people can send a message to ‘sv-request@li.org’, having this message
8898 Keep in mind that team members should be interested in _working_ at
8899 translations, or at solving translational difficulties, rather than
8900 merely lurking around. If your team does not exist yet and you want to
8901 start one, please write to ‘coordinator@translationproject.org’; you
8902 will then reach the coordinator for all translator teams.
8904 A handful of GNU packages have already been adapted and provided with
8905 message translations for several languages. Translation teams have
8906 begun to organize, using these packages as a starting point. But there
8907 are many more packages and many languages for which we have no volunteer
8908 translators. If you would like to volunteer to work at translating
8909 messages, please send mail to ‘coordinator@translationproject.org’
8910 indicating what language(s) you can work on.
8913 File: gettext.info, Node: Trans Intro 1, Next: Discussions, Prev: Trans Intro 0, Up: Translators
8918 * NOTE: * This documentation section is outdated and needs to be
8921 This is now official, GNU is going international! Here is the
8922 announcement submitted for the January 1995 GNU Bulletin:
8924 A handful of GNU packages have already been adapted and provided
8925 with message translations for several languages. Translation teams
8926 have begun to organize, using these packages as a starting point.
8927 But there are many more packages and many languages for which we
8928 have no volunteer translators. If you’d like to volunteer to work
8929 at translating messages, please send mail to
8930 ‘coordinator@translationproject.org’ indicating what language(s)
8933 This document should answer many questions for those who are curious
8934 about the process or would like to contribute. Please at least skim
8935 over it, hoping to cut down a little of the high volume of e-mail
8936 generated by this collective effort towards internationalization of free
8939 Most free programming which is widely shared is done in English, and
8940 currently, English is used as the main communicating language between
8941 national communities collaborating to free software. This very document
8942 is written in English. This will not change in the foreseeable future.
8944 However, there is a strong appetite from national communities for
8945 having more software able to write using national language and habits,
8946 and there is an on-going effort to modify free software in such a way
8947 that it becomes able to do so. The experiments driven so far raised an
8948 enthusiastic response from pretesters, so we believe that
8949 internationalization of free software is dedicated to succeed.
8951 For suggestion clarifications, additions or corrections to this
8952 document, please e-mail to ‘coordinator@translationproject.org’.
8955 File: gettext.info, Node: Discussions, Next: Organization, Prev: Trans Intro 1, Up: Translators
8960 * NOTE: * This documentation section is outdated and needs to be
8963 Facing this internationalization effort, a few users expressed their
8964 concerns. Some of these doubts are presented and discussed, here.
8968 Some languages are not spoken by a very large number of people, so
8969 people speaking them sometimes consider that there may not be all
8970 that much demand such versions of free software packages.
8971 Moreover, many people being _into computers_, in some countries,
8972 generally seem to prefer English versions of their software.
8974 On the other end, people might enjoy their own language a lot, and
8975 be very motivated at providing to themselves the pleasure of having
8976 their beloved free software speaking their mother tongue. They do
8977 themselves a personal favor, and do not pay that much attention to
8978 the number of people benefiting of their work.
8982 Other users are shy to push forward their own language, seeing in
8983 this some kind of misplaced propaganda. Someone thought there must
8984 be some users of the language over the networks pestering other
8987 But any spoken language is worth localization, because there are
8988 people behind the language for whom the language is important and
8989 dear to their hearts.
8993 The biggest problem is to find the right translations so that
8994 everybody can understand the messages. Translations are usually a
8995 little odd. Some people get used to English, to the extent they
8996 may find translations into their own language “rather pushy,
8997 obnoxious and sometimes even hilarious.” As a French speaking man,
8998 I have the experience of those instruction manuals for goods, so
8999 poorly translated in French in Korea or Taiwan…
9001 The fact is that we sometimes have to create a kind of national
9002 computer culture, and this is not easy without the collaboration of
9003 many people liking their mother tongue. This is why translations
9004 are better achieved by people knowing and loving their own
9005 language, and ready to work together at improving the results they
9008 • Dependencies over the GPL or LGPL
9010 Some people wonder if using GNU ‘gettext’ necessarily brings their
9011 package under the protective wing of the GNU General Public License
9012 or the GNU Lesser General Public License, when they do not want to
9013 make their program free, or want other kinds of freedom. The
9014 simplest answer is “normally not”.
9016 The ‘gettext-runtime’ part of GNU ‘gettext’, i.e. the contents of
9017 ‘libintl’, is covered by the GNU Lesser General Public License.
9018 The ‘gettext-tools’ part of GNU ‘gettext’, i.e. the rest of the GNU
9019 ‘gettext’ package, is covered by the GNU General Public License.
9021 The mere marking of localizable strings in a package, or
9022 conditional inclusion of a few lines for initialization, is not
9023 really including GPL’ed or LGPL’ed code. However, since the
9024 localization routines in ‘libintl’ are under the LGPL, the LGPL
9025 needs to be considered. It gives the right to distribute the
9026 complete unmodified source of ‘libintl’ even with non-free
9027 programs. It also gives the right to use ‘libintl’ as a shared
9028 library, even for non-free programs. But it gives the right to use
9029 ‘libintl’ as a static library or to incorporate ‘libintl’ into
9030 another library only to free software.
9033 File: gettext.info, Node: Organization, Next: Information Flow, Prev: Discussions, Up: Translators
9038 * NOTE: * This documentation section is outdated and needs to be
9041 On a larger scale, the true solution would be to organize some kind
9042 of fairly precise set up in which volunteers could participate. I gave
9043 some thought to this idea lately, and realize there will be some touchy
9044 points. I thought of writing to Richard Stallman to launch such a
9045 project, but feel it might be good to shake out the ideas between
9046 ourselves first. Most probably that Linux International has some
9047 experience in the field already, or would like to orchestrate the
9048 volunteer work, maybe. Food for thought, in any case!
9050 I guess we have to setup something early, somehow, that will help
9051 many possible contributors of the same language to interlock and avoid
9052 work duplication, and further be put in contact for solving together
9053 problems particular to their tongue (in most languages, there are many
9054 difficulties peculiar to translating technical English). My Swedish
9055 contributor acknowledged these difficulties, and I’m well aware of them
9058 This is surely not a technical issue, but we should manage so the
9059 effort of locale contributors be maximally useful, despite the national
9060 team layer interface between contributors and maintainers.
9062 The Translation Project needs some setup for coordinating language
9063 coordinators. Localizing evolving programs will surely become a
9064 permanent and continuous activity in the free software community, once
9065 well started. The setup should be minimally completed and tested before
9066 GNU ‘gettext’ becomes an official reality. The e-mail address
9067 ‘coordinator@translationproject.org’ has been set up for receiving
9068 offers from volunteers and general e-mail on these topics. This address
9069 reaches the Translation Project coordinator.
9073 * Central Coordination:: Central Coordination
9074 * National Teams:: National Teams
9075 * Mailing Lists:: Mailing Lists
9078 File: gettext.info, Node: Central Coordination, Next: National Teams, Prev: Organization, Up: Organization
9080 12.4.1 Central Coordination
9081 ---------------------------
9083 I also think GNU will need sooner than it thinks, that someone set up
9084 a way to organize and coordinate these groups. Some kind of group of
9085 groups. My opinion is that it would be good that GNU delegates this
9086 task to a small group of collaborating volunteers, shortly. Perhaps in
9087 ‘gnu.announce’ a list of this national committee’s can be published.
9089 My role as coordinator would simply be to refer to Ulrich any German
9090 speaking volunteer interested to localization of free software packages,
9091 and maybe helping national groups to initially organize, while
9092 maintaining national registries for until national groups are ready to
9093 take over. In fact, the coordinator should ease volunteers to get in
9094 contact with one another for creating national teams, which should then
9095 select one coordinator per language, or country (regionalized language).
9096 If well done, the coordination should be useful without being an
9097 overwhelming task, the time to put delegations in place.
9100 File: gettext.info, Node: National Teams, Next: Mailing Lists, Prev: Central Coordination, Up: Organization
9102 12.4.2 National Teams
9103 ---------------------
9105 I suggest we look for volunteer coordinators/editors for individual
9106 languages. These people will scan contributions of translation files
9107 for various programs, for their own languages, and will ensure high and
9108 uniform standards of diction.
9110 From my current experience with other people in these days, those who
9111 provide localizations are very enthusiastic about the process, and are
9112 more interested in the localization process than in the program they
9113 localize, and want to do many programs, not just one. This seems to
9114 confirm that having a coordinator/editor for each language is a good
9117 We need to choose someone who is good at writing clear and concise
9118 prose in the language in question. That is hard—we can’t check it
9119 ourselves. So we need to ask a few people to judge each others’ writing
9120 and select the one who is best.
9122 I announce my prerelease to a few dozen people, and you would not
9123 believe all the discussions it generated already. I shudder to think
9124 what will happen when this will be launched, for true, officially, world
9125 wide. Who am I to arbitrate between two Czekolsovak users contradicting
9126 each other, for example?
9128 I assume that your German is not much better than my French so that I
9129 would not be able to judge about these formulations. What I would
9130 suggest is that for each language there is a group for people who
9131 maintain the PO files and judge about changes. I suspect there will be
9132 cultural differences between how such groups of people will behave.
9133 Some will have relaxed ways, reach consensus easily, and have anyone of
9134 the group relate to the maintainers, while others will fight to death,
9135 organize heavy administrations up to national standards, and use strict
9138 The German team is putting out a good example. Right now, they are
9139 maybe half a dozen people revising translations of each other and
9140 discussing the linguistic issues. I do not even have all the names.
9141 Ulrich Drepper is taking care of coordinating the German team. He
9142 subscribed to all my pretest lists, so I do not even have to warn him
9143 specifically of incoming releases.
9145 I’m sure, that is a good idea to get teams for each language working
9146 on translations. That will make the translations better and more
9151 * Sub-Cultures:: Sub-Cultures
9152 * Organizational Ideas:: Organizational Ideas
9155 File: gettext.info, Node: Sub-Cultures, Next: Organizational Ideas, Prev: National Teams, Up: National Teams
9157 12.4.2.1 Sub-Cultures
9158 .....................
9160 Taking French for example, there are a few sub-cultures around
9161 computers which developed diverging vocabularies. Picking volunteers
9162 here and there without addressing this problem in an organized way, soon
9163 in the project, might produce a distasteful mix of internationalized
9164 programs, and possibly trigger endless quarrels among those who really
9167 Keeping some kind of unity in the way French localization of
9168 internationalized programs is achieved is a difficult (and delicate)
9169 job. Knowing the latin character of French people (:-), if we take this
9170 the wrong way, we could end up nowhere, or spoil a lot of energies.
9171 Maybe we should begin to address this problem seriously _before_ GNU
9172 ‘gettext’ become officially published. And I suspect that this means
9176 File: gettext.info, Node: Organizational Ideas, Prev: Sub-Cultures, Up: National Teams
9178 12.4.2.2 Organizational Ideas
9179 .............................
9181 I expect the next big changes after the official release. Please
9182 note that I use the German translation of the short GPL message. We
9183 need to set a few good examples before the localization goes out for
9184 true in the free software community. Here are a few points to discuss:
9186 • Each group should have one FTP server (at least one master).
9188 • The files on the server should reflect the latest version (of
9189 course!) and it should also contain a RCS directory with the
9190 corresponding archives (I don’t have this now).
9192 • There should also be a ChangeLog file (this is more useful than the
9193 RCS archive but can be generated automatically from the later by
9196 • A "core group" should judge about questionable changes (for now
9197 this group consists solely by me but I ask some others
9198 occasionally; this also seems to work).
9201 File: gettext.info, Node: Mailing Lists, Prev: National Teams, Up: Organization
9203 12.4.3 Mailing Lists
9204 --------------------
9206 If we get any inquiries about GNU ‘gettext’, send them on to:
9208 coordinator@translationproject.org
9210 The ‘*-pretest’ lists are quite useful to me, maybe the idea could be
9211 generalized to many GNU, and non-GNU packages. But each maintainer
9214 François, we have a mechanism in place here at ‘gnu.ai.mit.edu’ to
9215 track teams, support mailing lists for them and log members. We have a
9216 slight preference that you use it. If this is OK with you, I can get
9219 Things are changing! A few years ago, when Daniel Fekete and I asked
9220 for a mailing list for GNU localization, nested at the FSF, we were
9221 politely invited to organize it anywhere else, and so did we. For
9222 communicating with my pretesters, I later made a handful of mailing
9223 lists located at iro.umontreal.ca and administrated by ‘majordomo’.
9224 These lists have been _very_ dependable so far…
9226 I suspect that the German team will organize itself a mailing list
9227 located in Germany, and so forth for other countries. But before they
9228 organize for true, it could surely be useful to offer mailing lists
9229 located at the FSF to each national team. So yes, please explain me how
9230 I should proceed to create and handle them.
9232 We should create temporary mailing lists, one per country, to help
9233 people organize. Temporary, because once regrouped and structured, it
9234 would be fair the volunteers from country bring back _their_ list in
9235 there and manage it as they want. My feeling is that, in the long run,
9236 each team should run its own list, from within their country. There
9237 also should be some central list to which all teams could subscribe as
9238 they see fit, as long as each team is represented in it.
9241 File: gettext.info, Node: Information Flow, Next: Translating plural forms, Prev: Organization, Up: Translators
9243 12.5 Information Flow
9244 =====================
9246 * NOTE: * This documentation section is outdated and needs to be
9249 There will surely be some discussion about this messages after the
9250 packages are finally released. If people now send you some proposals
9251 for better messages, how do you proceed? Jim, please note that right
9252 now, as I put forward nearly a dozen of localizable programs, I receive
9253 both the translations and the coordination concerns about them.
9255 If I put one of my things to pretest, Ulrich receives the
9256 announcement and passes it on to the German team, who make last minute
9257 revisions. Then he submits the translation files to me _as the
9258 maintainer_. For free packages I do not maintain, I would not even hear
9259 about it. This scheme could be made to work for the whole Translation
9260 Project, I think. For security reasons, maybe Ulrich (national
9261 coordinators, in fact) should update central registry kept at the
9262 Translation Project (Jim, me, or Len’s recruits) once in a while.
9264 In December/January, I was aggressively ready to internationalize all
9265 of GNU, giving myself the duty of one small GNU package per week or so,
9266 taking many weeks or months for bigger packages. But it does not work
9267 this way. I first did all the things I’m responsible for. I’ve nothing
9268 against some missionary work on other maintainers, but I’m also losing a
9269 lot of energy over it—same debates over again.
9271 And when the first localized packages are released we’ll get a lot of
9272 responses about ugly translations :-). Surely, and we need to have
9273 beforehand a fairly good idea about how to handle the information flow
9274 between the national teams and the package maintainers.
9276 Please start saving somewhere a quick history of each PO file. I
9277 know for sure that the file format will change, allowing for comments.
9278 It would be nice that each file has a kind of log, and references for
9279 those who want to submit comments or gripes, or otherwise contribute. I
9280 sent a proposal for a fast and flexible format, but it is not receiving
9281 acceptance yet by the GNU deciders. I’ll tell you when I have more
9282 information about this.
9285 File: gettext.info, Node: Translating plural forms, Next: Prioritizing messages, Prev: Information Flow, Up: Translators
9287 12.6 Translating plural forms
9288 =============================
9290 Suppose you are translating a PO file, and it contains an entry like
9294 msgid "One file removed"
9295 msgid_plural "%d files removed"
9299 What does this mean? How do you fill it in?
9301 Such an entry denotes a message with plural forms, that is, a message
9302 where the text depends on a cardinal number. The general form of the
9303 message, in English, is the ‘msgid_plural’ line. The ‘msgid’ line is
9304 the English singular form, that is, the form for when the number is
9305 equal to 1. More details about plural forms are explained in *note
9308 The first thing you need to look at is the ‘Plural-Forms’ line in the
9309 header entry of the PO file. It contains the number of plural forms and
9310 a formula. If the PO file does not yet have such a line, you have to
9311 add it. It only depends on the language into which you are translating.
9312 You can get this info by using the ‘msginit’ command (see *note
9313 Creating::) – it contains a database of known plural formulas – or by
9314 asking other members of your translation team.
9316 Suppose the line looks as follows:
9318 "Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n%10>=2 && n"
9319 "%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;\n"
9321 It’s logically one line; recall that the PO file formatting is
9322 allowed to break long lines so that each physical line fits in 80
9325 The value of ‘nplurals’ here tells you that there are three plural
9326 forms. The first thing you need to do is to ensure that the entry
9327 contains an ‘msgstr’ line for each of the forms:
9330 msgid "One file removed"
9331 msgid_plural "%d files removed"
9336 Then translate the ‘msgid_plural’ line and fill it in into each
9340 msgid "One file removed"
9341 msgid_plural "%d files removed"
9342 msgstr[0] "%d slika uklonjenih"
9343 msgstr[1] "%d slika uklonjenih"
9344 msgstr[2] "%d slika uklonjenih"
9346 Now you can refine the translation so that it matches the plural
9347 form. According to the formula above, ‘msgstr[0]’ is used when the
9348 number ends in 1 but does not end in 11; ‘msgstr[1]’ is used when the
9349 number ends in 2, 3, 4, but not in 12, 13, 14; and ‘msgstr[2]’ is used
9350 in all other cases. With this knowledge, you can refine the
9354 msgid "One file removed"
9355 msgid_plural "%d files removed"
9356 msgstr[0] "%d slika je uklonjena"
9357 msgstr[1] "%d datoteke uklonjenih"
9358 msgstr[2] "%d slika uklonjenih"
9360 You noticed that in the English singular form (‘msgid’) the number
9361 placeholder could be omitted and replaced by the numeral word “one”.
9362 Can you do this in your translation as well?
9364 msgstr[0] "jednom datotekom je uklonjen"
9366 Well, it depends on whether ‘msgstr[0]’ applies only to the number 1, or
9367 to other numbers as well. If, according to the plural formula,
9368 ‘msgstr[0]’ applies only to ‘n == 1’, then you can use the specialized
9369 translation without the number placeholder. In our case, however,
9370 ‘msgstr[0]’ also applies to the numbers 21, 31, 41, etc., and therefore
9371 you cannot omit the placeholder.
9374 File: gettext.info, Node: Prioritizing messages, Prev: Translating plural forms, Up: Translators
9376 12.7 Prioritizing messages: How to determine which messages to translate first
9377 ==============================================================================
9379 A translator sometimes has only a limited amount of time per week to
9380 spend on a package, and some packages have quite large message catalogs
9381 (over 1000 messages). Therefore she wishes to translate the messages
9382 first that are the most visible to the user, or that occur most
9383 frequently. This section describes how to determine these "most urgent"
9384 messages. It also applies to determine the "next most urgent" messages
9385 after the message catalog has already been partially translated.
9387 In a first step, she uses the programs like a user would do. While
9388 she does this, the GNU ‘gettext’ library logs into a file the not yet
9389 translated messages for which a translation was requested from the
9392 In a second step, she uses the PO mode to translate precisely this
9395 Here a more details. The GNU ‘libintl’ library (but not the
9396 corresponding functions in GNU ‘libc’) supports an environment variable
9397 ‘GETTEXT_LOG_UNTRANSLATED’. The GNU ‘libintl’ library will log into
9398 this file the messages for which ‘gettext()’ and related functions
9399 couldn’t find the translation. If the file doesn’t exist, it will be
9400 created as needed. On systems with GNU ‘libc’ a shared library
9401 ‘preloadable_libintl.so’ is provided that can be used with the ELF
9402 ‘LD_PRELOAD’ mechanism.
9404 So, in the first step, the translator uses these commands on systems
9407 $ LD_PRELOAD=/usr/local/lib/preloadable_libintl.so
9409 $ GETTEXT_LOG_UNTRANSLATED=$HOME/gettextlogused
9410 $ export GETTEXT_LOG_UNTRANSLATED
9412 and these commands on other systems:
9414 $ GETTEXT_LOG_UNTRANSLATED=$HOME/gettextlogused
9415 $ export GETTEXT_LOG_UNTRANSLATED
9417 Then she uses and peruses the programs. (It is a good and
9418 recommended practice to use the programs for which you provide
9419 translations: it gives you the needed context.) When done, she removes
9420 the environment variables:
9423 $ unset GETTEXT_LOG_UNTRANSLATED
9425 The second step starts with removing duplicates:
9427 $ msguniq $HOME/gettextlogused > missing.po
9429 The result is a PO file, but needs some preprocessing before a PO
9430 file editor can be used with it. First, it is a multi-domain PO file,
9431 containing messages from many translation domains. Second, it lacks all
9432 translator comments and source references. Here is how to get a list of
9433 the affected translation domains:
9435 $ sed -n -e 's,^domain "\(.*\)"$,\1,p' < missing.po | sort | uniq
9437 Then the translator can handle the domains one by one. For
9438 simplicity, let’s use environment variables to denote the language,
9439 domain and source package.
9441 $ lang=nl # your language
9442 $ domain=coreutils # the name of the domain to be handled
9443 $ package=/usr/src/gnu/coreutils-4.5.4 # the package where it comes from
9445 She takes the latest copy of ‘$lang.po’ from the Translation Project,
9446 or from the package (in most cases, ‘$package/po/$lang.po’), or creates
9447 a fresh one if she’s the first translator (see *note Creating::). She
9448 then uses the following commands to mark the not urgent messages as
9449 "obsolete". (This doesn’t mean that these messages - translated and
9450 untranslated ones - will go away. It simply means that the PO file
9451 editor will ignore them in the following editing session.)
9453 $ msggrep --domain=$domain missing.po | grep -v '^domain' \
9454 > $domain-missing.po
9455 $ msgattrib --set-obsolete --ignore-file $domain-missing.po $domain.$lang.po \
9456 > $domain.$lang-urgent.po
9458 The she translates ‘$domain.$lang-urgent.po’ by use of a PO file
9459 editor (*note Editing::). (FIXME: I don’t know whether ‘KBabel’ and
9460 ‘gtranslator’ also preserve obsolete messages, as they should.) Finally
9461 she restores the not urgent messages (with their earlier translations,
9462 for those which were already translated) through this command:
9464 $ msgmerge --no-fuzzy-matching $domain.$lang-urgent.po $package/po/$domain.pot \
9467 Then she can submit ‘$domain.$lang.po’ and proceed to the next
9471 File: gettext.info, Node: Maintainers, Next: Installers, Prev: Translators, Up: Top
9473 13 The Maintainer’s View
9474 ************************
9476 The maintainer of a package has many responsibilities. One of them
9477 is ensuring that the package will install easily on many platforms, and
9478 that the magic we described earlier (*note Users::) will work for
9479 installers and end users.
9481 Of course, there are many possible ways by which GNU ‘gettext’ might
9482 be integrated in a distribution, and this chapter does not cover them in
9483 all generality. Instead, it details one possible approach which is
9484 especially adequate for many free software distributions following GNU
9485 standards, or even better, Gnits standards, because GNU ‘gettext’ is
9486 purposely for helping the internationalization of the whole GNU project,
9487 and as many other good free packages as possible. So, the maintainer’s
9488 view presented here presumes that the package already has a
9489 ‘configure.ac’ file and uses GNU Autoconf.
9491 Nevertheless, GNU ‘gettext’ may surely be useful for free packages
9492 not following GNU standards and conventions, but the maintainers of such
9493 packages might have to show imagination and initiative in organizing
9494 their distributions so ‘gettext’ work for them in all situations. There
9495 are surely many, out there.
9497 Even if ‘gettext’ methods are now stabilizing, slight adjustments
9498 might be needed between successive ‘gettext’ versions, so you should
9499 ideally revise this chapter in subsequent releases, looking for changes.
9503 * Flat and Non-Flat:: Flat or Non-Flat Directory Structures
9504 * Prerequisites:: Prerequisite Works
9505 * gettextize Invocation:: Invoking the ‘gettextize’ Program
9506 * Adjusting Files:: Files You Must Create or Alter
9507 * autoconf macros:: Autoconf macros for use in ‘configure.ac’
9508 * Version Control Issues::
9509 * Release Management:: Creating a Distribution Tarball
9512 File: gettext.info, Node: Flat and Non-Flat, Next: Prerequisites, Prev: Maintainers, Up: Maintainers
9514 13.1 Flat or Non-Flat Directory Structures
9515 ==========================================
9517 Some free software packages are distributed as ‘tar’ files which
9518 unpack in a single directory, these are said to be "flat" distributions.
9519 Other free software packages have a one level hierarchy of
9520 subdirectories, using for example a subdirectory named ‘doc/’ for the
9521 Texinfo manual and man pages, another called ‘lib/’ for holding
9522 functions meant to replace or complement C libraries, and a subdirectory
9523 ‘src/’ for holding the proper sources for the package. These other
9524 distributions are said to be "non-flat".
9526 We cannot say much about flat distributions. A flat directory
9527 structure has the disadvantage of increasing the difficulty of updating
9528 to a new version of GNU ‘gettext’. Also, if you have many PO files,
9529 this could somewhat pollute your single directory. Also, GNU
9530 ‘gettext’’s libintl sources consist of C sources, shell scripts, ‘sed’
9531 scripts and complicated Makefile rules, which don’t fit well into an
9532 existing flat structure. For these reasons, we recommend to use
9533 non-flat approach in this case as well.
9535 Maybe because GNU ‘gettext’ itself has a non-flat structure, we have
9536 more experience with this approach, and this is what will be described
9537 in the remaining of this chapter. Some maintainers might use this as an
9538 opportunity to unflatten their package structure.
9541 File: gettext.info, Node: Prerequisites, Next: gettextize Invocation, Prev: Flat and Non-Flat, Up: Maintainers
9543 13.2 Prerequisite Works
9544 =======================
9546 There are some works which are required for using GNU ‘gettext’ in
9547 one of your package. These works have some kind of generality that
9548 escape the point by point descriptions used in the remainder of this
9549 chapter. So, we describe them here.
9551 • Before attempting to use ‘gettextize’ you should install some other
9552 packages first. Ensure that recent versions of GNU ‘m4’, GNU
9553 Autoconf and GNU ‘gettext’ are already installed at your site, and
9554 if not, proceed to do this first. If you get to install these
9555 things, beware that GNU ‘m4’ must be fully installed before GNU
9556 Autoconf is even _configured_.
9558 To further ease the task of a package maintainer the ‘automake’
9559 package was designed and implemented. GNU ‘gettext’ now uses this
9560 tool and the ‘Makefile’s in the ‘intl/’ and ‘po/’ therefore know
9561 about all the goals necessary for using ‘automake’ and ‘libintl’ in
9564 Those four packages are only needed by you, as a maintainer; the
9565 installers of your own package and end users do not really need any
9566 of GNU ‘m4’, GNU Autoconf, GNU ‘gettext’, or GNU ‘automake’ for
9567 successfully installing and running your package, with messages
9568 properly translated. But this is not completely true if you
9569 provide internationalized shell scripts within your own package:
9570 GNU ‘gettext’ shall then be installed at the user site if the end
9571 users want to see the translation of shell script messages.
9573 • Your package should use Autoconf and have a ‘configure.ac’ or
9574 ‘configure.in’ file. If it does not, you have to learn how. The
9575 Autoconf documentation is quite well written, it is a good idea
9576 that you print it and get familiar with it.
9578 • Your C sources should have already been modified according to
9579 instructions given earlier in this manual. *Note Sources::.
9581 • Your ‘po/’ directory should receive all PO files submitted to you
9582 by the translator teams, each having ‘LL.po’ as a name. This is
9583 not usually easy to get translation work done before your package
9584 gets internationalized and available! Since the cycle has to start
9585 somewhere, the easiest for the maintainer is to start with
9586 absolutely no PO files, and wait until various translator teams get
9587 interested in your package, and submit PO files.
9589 It is worth adding here a few words about how the maintainer should
9590 ideally behave with PO files submissions. As a maintainer, your role is
9591 to authenticate the origin of the submission as being the representative
9592 of the appropriate translating teams of the Translation Project (forward
9593 the submission to ‘coordinator@translationproject.org’ in case of
9594 doubt), to ensure that the PO file format is not severely broken and
9595 does not prevent successful installation, and for the rest, to merely
9596 put these PO files in ‘po/’ for distribution.
9598 As a maintainer, you do not have to take on your shoulders the
9599 responsibility of checking if the translations are adequate or complete,
9600 and should avoid diving into linguistic matters. Translation teams
9601 drive themselves and are fully responsible of their linguistic choices
9602 for the Translation Project. Keep in mind that translator teams are
9603 _not_ driven by maintainers. You can help by carefully redirecting all
9604 communications and reports from users about linguistic matters to the
9605 appropriate translation team, or explain users how to reach or join
9606 their team. The simplest might be to send them the ‘ABOUT-NLS’ file.
9608 Maintainers should _never ever_ apply PO file bug reports themselves,
9609 short-cutting translation teams. If some translator has difficulty to
9610 get some of her points through her team, it should not be an option for
9611 her to directly negotiate translations with maintainers. Teams ought to
9612 settle their problems themselves, if any. If you, as a maintainer, ever
9613 think there is a real problem with a team, please never try to _solve_ a
9614 team’s problem on your own.
9617 File: gettext.info, Node: gettextize Invocation, Next: Adjusting Files, Prev: Prerequisites, Up: Maintainers
9619 13.3 Invoking the ‘gettextize’ Program
9620 ======================================
9622 The ‘gettextize’ program is an interactive tool that helps the
9623 maintainer of a package internationalized through GNU ‘gettext’. It is
9624 used for two purposes:
9626 • As a wizard, when a package is modified to use GNU ‘gettext’ for
9629 • As a migration tool, for upgrading the GNU ‘gettext’ support in a
9630 package from a previous to a newer version of GNU ‘gettext’.
9632 This program performs the following tasks:
9634 • It copies into the package some files that are consistently and
9635 identically needed in every package internationalized through GNU
9638 • It performs as many of the tasks mentioned in the next section
9639 *note Adjusting Files:: as can be performed automatically.
9641 • It removes obsolete files and idioms used for previous GNU
9642 ‘gettext’ versions to the form recommended for the current GNU
9645 • It prints a summary of the tasks that ought to be done manually and
9646 could not be done automatically by ‘gettextize’.
9648 It can be invoked as follows:
9650 gettextize [ OPTION… ] [ DIRECTORY ]
9652 and accepts the following options:
9656 Force replacement of files which already exist.
9659 Install the libintl sources in a subdirectory named ‘intl/’. This
9660 libintl will be used to provide internationalization on systems
9661 that don’t have GNU libintl installed. If this option is omitted,
9662 the call to ‘AM_GNU_GETTEXT’ in ‘configure.ac’ should read:
9663 ‘AM_GNU_GETTEXT([external])’, and internationalization will not be
9664 enabled on systems lacking GNU gettext.
9667 Specify a directory containing PO files. Such a directory contains
9668 the translations into various languages of a particular POT file.
9669 This option can be specified multiple times, once for each
9670 translation domain. If it is not specified, the directory named
9674 Don’t update or create ChangeLog files. By default, ‘gettextize’
9675 logs all changes (file additions, modifications and removals) in a
9676 file called ‘ChangeLog’ in each affected directory.
9679 Make symbolic links instead of copying the needed files. This can
9680 be useful to save a few kilobytes of disk space, but it requires
9681 extra effort to create self-contained tarballs, it may disturb some
9682 mechanism the maintainer applies to the sources, and it is likely
9683 to introduce bugs when a newer version of ‘gettext’ is installed on
9688 Print modifications but don’t perform them. All actions that
9689 ‘gettextize’ would normally execute are inhibited and instead only
9690 listed on standard output.
9693 Display this help and exit.
9696 Output version information and exit.
9698 If DIRECTORY is given, this is the top level directory of a package
9699 to prepare for using GNU ‘gettext’. If not given, it is assumed that
9700 the current directory is the top level directory of such a package.
9702 The program ‘gettextize’ provides the following files. However, no
9703 existing file will be replaced unless the option ‘--force’ (‘-f’) is
9706 1. The ‘ABOUT-NLS’ file is copied in the main directory of your
9707 package, the one being at the top level. This file gives the main
9708 indications about how to install and use the Native Language
9709 Support features of your program. You might elect to use a more
9710 recent copy of this ‘ABOUT-NLS’ file than the one provided through
9711 ‘gettextize’, if you have one handy. You may also fetch a more
9712 recent copy of file ‘ABOUT-NLS’ from Translation Project sites, and
9713 from most GNU archive sites.
9715 2. A ‘po/’ directory is created for eventually holding all translation
9716 files, but initially only containing the file ‘po/Makefile.in.in’
9717 from the GNU ‘gettext’ distribution (beware the double ‘.in’ in the
9718 file name) and a few auxiliary files. If the ‘po/’ directory
9719 already exists, it will be preserved along with the files it
9720 contains, and only ‘Makefile.in.in’ and the auxiliary files will be
9723 If ‘--po-dir’ has been specified, this holds for every directory
9724 specified through ‘--po-dir’, instead of ‘po/’.
9726 3. Only if ‘--intl’ has been specified: A ‘intl/’ directory is created
9727 and filled with most of the files originally in the ‘intl/’
9728 directory of the GNU ‘gettext’ distribution. Also, if option
9729 ‘--force’ (‘-f’) is given, the ‘intl/’ directory is emptied first.
9731 4. The file ‘config.rpath’ is copied into the directory containing
9732 configuration support files. It is needed by the ‘AM_GNU_GETTEXT’
9735 5. Only if the project is using GNU ‘automake’: A set of ‘autoconf’
9736 macro files is copied into the package’s ‘autoconf’ macro
9737 repository, usually in a directory called ‘m4/’.
9739 If your site support symbolic links, ‘gettextize’ will not actually
9740 copy the files into your package, but establish symbolic links instead.
9741 This avoids duplicating the disk space needed in all packages. Merely
9742 using the ‘-h’ option while creating the ‘tar’ archive of your
9743 distribution will resolve each link by an actual copy in the
9744 distribution archive. So, to insist, you really should use ‘-h’ option
9745 with ‘tar’ within your ‘dist’ goal of your main ‘Makefile.in’.
9747 Furthermore, ‘gettextize’ will update all ‘Makefile.am’ files in each
9748 affected directory, as well as the top level ‘configure.ac’ or
9749 ‘configure.in’ file.
9751 It is interesting to understand that most new files for supporting
9752 GNU ‘gettext’ facilities in one package go in ‘intl/’, ‘po/’ and ‘m4/’
9753 subdirectories. One distinction between ‘intl/’ and the two other
9754 directories is that ‘intl/’ is meant to be completely identical in all
9755 packages using GNU ‘gettext’, while the other directories will mostly
9756 contain package dependent files.
9758 The ‘gettextize’ program makes backup files for all files it replaces
9759 or changes, and also write ChangeLog entries about these changes. This
9760 way, the careful maintainer can check after running ‘gettextize’ whether
9761 its changes are acceptable to him, and possibly adjust them. An
9762 exception to this rule is the ‘intl/’ directory, which is added or
9763 replaced or removed as a whole.
9765 It is important to understand that ‘gettextize’ can not do the entire
9766 job of adapting a package for using GNU ‘gettext’. The amount of
9767 remaining work depends on whether the package uses GNU ‘automake’ or
9768 not. But in any case, the maintainer should still read the section
9769 *note Adjusting Files:: after invoking ‘gettextize’.
9771 In particular, if after using ‘gettexize’, you get an error
9772 ‘AC_COMPILE_IFELSE was called before AC_GNU_SOURCE’ or ‘AC_RUN_IFELSE
9773 was called before AC_GNU_SOURCE’, you can fix it by modifying
9774 ‘configure.ac’, as described in *note configure.ac::.
9776 It is also important to understand that ‘gettextize’ is not part of
9777 the GNU build system, in the sense that it should not be invoked
9778 automatically, and not be invoked by someone who doesn’t assume the
9779 responsibilities of a package maintainer. For the latter purpose, a
9780 separate tool is provided, see *note autopoint Invocation::.
9783 File: gettext.info, Node: Adjusting Files, Next: autoconf macros, Prev: gettextize Invocation, Up: Maintainers
9785 13.4 Files You Must Create or Alter
9786 ===================================
9788 Besides files which are automatically added through ‘gettextize’,
9789 there are many files needing revision for properly interacting with GNU
9790 ‘gettext’. If you are closely following GNU standards for Makefile
9791 engineering and auto-configuration, the adaptations should be easier to
9792 achieve. Here is a point by point description of the changes needed in
9795 So, here comes a list of files, each one followed by a description of
9796 all alterations it needs. Many examples are taken out from the GNU
9797 ‘gettext’ 0.19.8.1 distribution itself, or from the GNU ‘hello’
9798 distribution (<http://www.gnu.org/software/hello>). You may indeed
9799 refer to the source code of the GNU ‘gettext’ and GNU ‘hello’ packages,
9800 as they are intended to be good examples for using GNU gettext
9805 * po/POTFILES.in:: ‘POTFILES.in’ in ‘po/’
9806 * po/LINGUAS:: ‘LINGUAS’ in ‘po/’
9807 * po/Makevars:: ‘Makevars’ in ‘po/’
9808 * po/Rules-*:: Extending ‘Makefile’ in ‘po/’
9809 * configure.ac:: ‘configure.ac’ at top level
9810 * config.guess:: ‘config.guess’, ‘config.sub’ at top level
9811 * mkinstalldirs:: ‘mkinstalldirs’ at top level
9812 * aclocal:: ‘aclocal.m4’ at top level
9813 * acconfig:: ‘acconfig.h’ at top level
9814 * config.h.in:: ‘config.h.in’ at top level
9815 * Makefile:: ‘Makefile.in’ at top level
9816 * src/Makefile:: ‘Makefile.in’ in ‘src/’
9817 * lib/gettext.h:: ‘gettext.h’ in ‘lib/’
9820 File: gettext.info, Node: po/POTFILES.in, Next: po/LINGUAS, Prev: Adjusting Files, Up: Adjusting Files
9822 13.4.1 ‘POTFILES.in’ in ‘po/’
9823 -----------------------------
9825 The ‘po/’ directory should receive a file named ‘POTFILES.in’. This
9826 file tells which files, among all program sources, have marked strings
9827 needing translation. Here is an example of such a file:
9829 # List of source files containing translatable strings.
9830 # Copyright (C) 1995 Free Software Foundation, Inc.
9832 # Common library files
9837 # Package source files
9842 Hash-marked comments and white lines are ignored. All other lines list
9843 those source files containing strings marked for translation (*note Mark
9844 Keywords::), in a notation relative to the top level of your whole
9845 distribution, rather than the location of the ‘POTFILES.in’ file itself.
9847 When a C file is automatically generated by a tool, like ‘flex’ or
9848 ‘bison’, that doesn’t introduce translatable strings by itself, it is
9849 recommended to list in ‘po/POTFILES.in’ the real source file (ending in
9850 ‘.l’ in the case of ‘flex’, or in ‘.y’ in the case of ‘bison’), not the
9854 File: gettext.info, Node: po/LINGUAS, Next: po/Makevars, Prev: po/POTFILES.in, Up: Adjusting Files
9856 13.4.2 ‘LINGUAS’ in ‘po/’
9857 -------------------------
9859 The ‘po/’ directory should also receive a file named ‘LINGUAS’. This
9860 file contains the list of available translations. It is a whitespace
9861 separated list. Hash-marked comments and white lines are ignored. Here
9864 # Set of available languages.
9867 This example means that German and French PO files are available, so
9868 that these languages are currently supported by your package. If you
9869 want to further restrict, at installation time, the set of installed
9870 languages, this should not be done by modifying the ‘LINGUAS’ file, but
9871 rather by using the ‘LINGUAS’ environment variable (*note Installers::).
9873 It is recommended that you add the "languages" ‘en@quot’ and
9874 ‘en@boldquot’ to the ‘LINGUAS’ file. ‘en@quot’ is a variant of English
9875 message catalogs (‘en’) which uses real quotation marks instead of the
9876 ugly looking asymmetric ASCII substitutes ‘`’ and ‘'’. ‘en@boldquot’ is
9877 a variant of ‘en@quot’ that additionally outputs quoted pieces of text
9878 in a bold font, when used in a terminal emulator which supports the
9879 VT100 escape sequences (such as ‘xterm’ or the Linux console, but not
9880 Emacs in ‘M-x shell’ mode).
9882 These extra message catalogs ‘en@quot’ and ‘en@boldquot’ are
9883 constructed automatically, not by translators; to support them, you need
9884 the files ‘Rules-quot’, ‘quot.sed’, ‘boldquot.sed’, ‘en@quot.header’,
9885 ‘en@boldquot.header’, ‘insert-header.sin’ in the ‘po/’ directory. You
9886 can copy them from GNU gettext’s ‘po/’ directory; they are also
9887 installed by running ‘gettextize’.
9890 File: gettext.info, Node: po/Makevars, Next: po/Rules-*, Prev: po/LINGUAS, Up: Adjusting Files
9892 13.4.3 ‘Makevars’ in ‘po/’
9893 --------------------------
9895 The ‘po/’ directory also has a file named ‘Makevars’. It contains
9896 variables that are specific to your project. ‘po/Makevars’ gets
9897 inserted into the ‘po/Makefile’ when the latter is created. The
9898 variables thus take effect when the POT file is created or updated, and
9899 when the message catalogs get installed.
9901 The first three variables can be left unmodified if your package has
9902 a single message domain and, accordingly, a single ‘po/’ directory.
9903 Only packages which have multiple ‘po/’ directories at different
9904 locations need to adjust the three first variables defined in
9907 As an alternative to the ‘XGETTEXT_OPTIONS’ variables, it is also
9908 possible to specify ‘xgettext’ options through the ‘AM_XGETTEXT_OPTION’
9909 autoconf macro. See *note AM_XGETTEXT_OPTION::.
9912 File: gettext.info, Node: po/Rules-*, Next: configure.ac, Prev: po/Makevars, Up: Adjusting Files
9914 13.4.4 Extending ‘Makefile’ in ‘po/’
9915 ------------------------------------
9917 All files called ‘Rules-*’ in the ‘po/’ directory get appended to the
9918 ‘po/Makefile’ when it is created. They present an opportunity to add
9919 rules for special PO files to the Makefile, without needing to mess with
9920 ‘po/Makefile.in.in’.
9922 GNU gettext comes with a ‘Rules-quot’ file, containing rules for
9923 building catalogs ‘en@quot.po’ and ‘en@boldquot.po’. The effect of
9924 ‘en@quot.po’ is that people who set their ‘LANGUAGE’ environment
9925 variable to ‘en@quot’ will get messages with proper looking symmetric
9926 Unicode quotation marks instead of abusing the ASCII grave accent and
9927 the ASCII apostrophe for indicating quotations. To enable this catalog,
9928 simply add ‘en@quot’ to the ‘po/LINGUAS’ file. The effect of
9929 ‘en@boldquot.po’ is that people who set ‘LANGUAGE’ to ‘en@boldquot’ will
9930 get not only proper quotation marks, but also the quoted text will be
9931 shown in a bold font on terminals and consoles. This catalog is useful
9932 only for command-line programs, not GUI programs. To enable it,
9933 similarly add ‘en@boldquot’ to the ‘po/LINGUAS’ file.
9935 Similarly, you can create rules for building message catalogs for the
9936 ‘sr@latin’ locale – Serbian written with the Latin alphabet – from those
9937 for the ‘sr’ locale – Serbian written with Cyrillic letters. See *note
9938 msgfilter Invocation::.
9941 File: gettext.info, Node: configure.ac, Next: config.guess, Prev: po/Rules-*, Up: Adjusting Files
9943 13.4.5 ‘configure.ac’ at top level
9944 ----------------------------------
9946 ‘configure.ac’ or ‘configure.in’ - this is the source from which
9947 ‘autoconf’ generates the ‘configure’ script.
9949 1. Declare the package and version.
9951 This is done by a set of lines like these:
9955 AC_DEFINE_UNQUOTED(PACKAGE, "$PACKAGE")
9956 AC_DEFINE_UNQUOTED(VERSION, "$VERSION")
9960 or, if you are using GNU ‘automake’, by a line like this:
9962 AM_INIT_AUTOMAKE(gettext, 0.19.8.1)
9964 Of course, you replace ‘gettext’ with the name of your package, and
9965 ‘0.19.8.1’ by its version numbers, exactly as they should appear in
9966 the packaged ‘tar’ file name of your distribution
9967 (‘gettext-0.19.8.1.tar.gz’, here).
9969 2. Check for internationalization support.
9971 Here is the main ‘m4’ macro for triggering internationalization
9972 support. Just add this line to ‘configure.ac’:
9976 This call is purposely simple, even if it generates a lot of
9977 configure time checking and actions.
9979 If you have suppressed the ‘intl/’ subdirectory by calling
9980 ‘gettextize’ without ‘--intl’ option, this call should read
9982 AM_GNU_GETTEXT([external])
9984 3. Have output files created.
9986 The ‘AC_OUTPUT’ directive, at the end of your ‘configure.ac’ file,
9987 needs to be modified in two ways:
9989 AC_OUTPUT([EXISTING CONFIGURATION FILES intl/Makefile po/Makefile.in],
9990 [EXISTING ADDITIONAL ACTIONS])
9992 The modification to the first argument to ‘AC_OUTPUT’ asks for
9993 substitution in the ‘intl/’ and ‘po/’ directories. Note the ‘.in’
9994 suffix used for ‘po/’ only. This is because the distributed file
9995 is really ‘po/Makefile.in.in’.
9997 If you have suppressed the ‘intl/’ subdirectory by calling
9998 ‘gettextize’ without ‘--intl’ option, then you don’t need to add
9999 ‘intl/Makefile’ to the ‘AC_OUTPUT’ line.
10001 If, after doing the recommended modifications, a command like
10002 ‘aclocal -I m4’ or ‘autoconf’ or ‘autoreconf’ fails with a trace similar
10005 configure.ac:44: warning: AC_COMPILE_IFELSE was called before AC_GNU_SOURCE
10006 ../../lib/autoconf/specific.m4:335: AC_GNU_SOURCE is expanded from...
10007 m4/lock.m4:224: gl_LOCK is expanded from...
10008 m4/gettext.m4:571: gt_INTL_SUBDIR_CORE is expanded from...
10009 m4/gettext.m4:472: AM_INTL_SUBDIR is expanded from...
10010 m4/gettext.m4:347: AM_GNU_GETTEXT is expanded from...
10011 configure.ac:44: the top level
10012 configure.ac:44: warning: AC_RUN_IFELSE was called before AC_GNU_SOURCE
10014 you need to add an explicit invocation of ‘AC_GNU_SOURCE’ in the
10015 ‘configure.ac’ file - after ‘AC_PROG_CC’ but before ‘AM_GNU_GETTEXT’,
10016 most likely very close to the ‘AC_PROG_CC’ invocation. This is
10017 necessary because of ordering restrictions imposed by GNU autoconf.
10020 File: gettext.info, Node: config.guess, Next: mkinstalldirs, Prev: configure.ac, Up: Adjusting Files
10022 13.4.6 ‘config.guess’, ‘config.sub’ at top level
10023 ------------------------------------------------
10025 If you haven’t suppressed the ‘intl/’ subdirectory, you need to add
10026 the GNU ‘config.guess’ and ‘config.sub’ files to your distribution.
10027 They are needed because the ‘intl/’ directory has platform dependent
10028 support for determining the locale’s character encoding and therefore
10029 needs to identify the platform.
10031 You can obtain the newest version of ‘config.guess’ and ‘config.sub’
10032 from the ‘config’ project at ‘http://savannah.gnu.org/’. The commands
10034 $ wget -O config.guess 'http://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.guess;hb=HEAD'
10035 $ wget -O config.sub 'http://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.sub;hb=HEAD'
10036 Less recent versions are also contained in the GNU ‘automake’ and GNU
10037 ‘libtool’ packages.
10039 Normally, ‘config.guess’ and ‘config.sub’ are put at the top level of
10040 a distribution. But it is also possible to put them in a subdirectory,
10041 altogether with other configuration support files like ‘install-sh’,
10042 ‘ltconfig’, ‘ltmain.sh’ or ‘missing’. All you need to do, other than
10043 moving the files, is to add the following line to your ‘configure.ac’.
10045 AC_CONFIG_AUX_DIR([SUBDIR])
10048 File: gettext.info, Node: mkinstalldirs, Next: aclocal, Prev: config.guess, Up: Adjusting Files
10050 13.4.7 ‘mkinstalldirs’ at top level
10051 -----------------------------------
10053 With earlier versions of GNU gettext, you needed to add the GNU
10054 ‘mkinstalldirs’ script to your distribution. This is not needed any
10055 more. You can remove it if you not also using an automake version older
10059 File: gettext.info, Node: aclocal, Next: acconfig, Prev: mkinstalldirs, Up: Adjusting Files
10061 13.4.8 ‘aclocal.m4’ at top level
10062 --------------------------------
10064 If you do not have an ‘aclocal.m4’ file in your distribution, the
10065 simplest is to concatenate the files ‘codeset.m4’, ‘fcntl-o.m4’,
10066 ‘gettext.m4’, ‘glibc2.m4’, ‘glibc21.m4’, ‘iconv.m4’, ‘intdiv0.m4’,
10067 ‘intl.m4’, ‘intldir.m4’, ‘intlmacosx.m4’, ‘intmax.m4’, ‘inttypes_h.m4’,
10068 ‘inttypes-pri.m4’, ‘lcmessage.m4’, ‘lib-ld.m4’, ‘lib-link.m4’,
10069 ‘lib-prefix.m4’, ‘lock.m4’, ‘longlong.m4’, ‘nls.m4’, ‘po.m4’,
10070 ‘printf-posix.m4’, ‘progtest.m4’, ‘size_max.m4’, ‘stdint_h.m4’,
10071 ‘threadlib.m4’, ‘uintmax_t.m4’, ‘visibility.m4’, ‘wchar_t.m4’,
10072 ‘wint_t.m4’, ‘xsize.m4’ from GNU ‘gettext’’s ‘m4/’ directory into a
10073 single file. If you have suppressed the ‘intl/’ directory, only
10074 ‘gettext.m4’, ‘iconv.m4’, ‘lib-ld.m4’, ‘lib-link.m4’, ‘lib-prefix.m4’,
10075 ‘nls.m4’, ‘po.m4’, ‘progtest.m4’ need to be concatenated.
10077 If you are not using GNU ‘automake’ 1.8 or newer, you will need to
10078 add a file ‘mkdirp.m4’ from a newer automake distribution to the list of
10081 If you already have an ‘aclocal.m4’ file, then you will have to merge
10082 the said macro files into your ‘aclocal.m4’. Note that if you are
10083 upgrading from a previous release of GNU ‘gettext’, you should most
10084 probably _replace_ the macros (‘AM_GNU_GETTEXT’, etc.), as they usually
10085 change a little from one release of GNU ‘gettext’ to the next. Their
10086 contents may vary as we get more experience with strange systems out
10089 If you are using GNU ‘automake’ 1.5 or newer, it is enough to put
10090 these macro files into a subdirectory named ‘m4/’ and add the line
10092 ACLOCAL_AMFLAGS = -I m4
10094 to your top level ‘Makefile.am’.
10096 If you are using GNU ‘automake’ 1.10 or newer, it is even easier: Add
10099 ACLOCAL_AMFLAGS = --install -I m4
10101 to your top level ‘Makefile.am’, and run ‘aclocal --install -I m4’.
10102 This will copy the needed files to the ‘m4/’ subdirectory automatically,
10103 before updating ‘aclocal.m4’.
10105 These macros check for the internationalization support functions and
10106 related informations. Hopefully, once stabilized, these macros might be
10107 integrated in the standard Autoconf set, because this piece of ‘m4’ code
10108 will be the same for all projects using GNU ‘gettext’.
10111 File: gettext.info, Node: acconfig, Next: config.h.in, Prev: aclocal, Up: Adjusting Files
10113 13.4.9 ‘acconfig.h’ at top level
10114 --------------------------------
10116 Earlier GNU ‘gettext’ releases required to put definitions for
10117 ‘ENABLE_NLS’, ‘HAVE_GETTEXT’ and ‘HAVE_LC_MESSAGES’, ‘HAVE_STPCPY’,
10118 ‘PACKAGE’ and ‘VERSION’ into an ‘acconfig.h’ file. This is not needed
10119 any more; you can remove them from your ‘acconfig.h’ file unless your
10120 package uses them independently from the ‘intl/’ directory.
10123 File: gettext.info, Node: config.h.in, Next: Makefile, Prev: acconfig, Up: Adjusting Files
10125 13.4.10 ‘config.h.in’ at top level
10126 ----------------------------------
10128 The include file template that holds the C macros to be defined by
10129 ‘configure’ is usually called ‘config.h.in’ and may be maintained either
10130 manually or automatically.
10132 If ‘gettextize’ has created an ‘intl/’ directory, this file must be
10133 called ‘config.h.in’ and must be at the top level. If, however, you
10134 have suppressed the ‘intl/’ directory by calling ‘gettextize’ without
10135 ‘--intl’ option, then you can choose the name of this file and its
10138 If it is maintained automatically, by use of the ‘autoheader’
10139 program, you need to do nothing about it. This is the case in
10140 particular if you are using GNU ‘automake’.
10142 If it is maintained manually, and if ‘gettextize’ has created an
10143 ‘intl/’ directory, you should switch to using ‘autoheader’. The list of
10144 C macros to be added for the sake of the ‘intl/’ directory is just too
10145 long to be maintained manually; it also changes between different
10146 versions of GNU ‘gettext’.
10148 If it is maintained manually, and if on the other hand you have
10149 suppressed the ‘intl/’ directory by calling ‘gettextize’ without
10150 ‘--intl’ option, then you can get away by adding the following lines to
10153 /* Define to 1 if translation of program messages to the user's
10154 native language is requested. */
10158 File: gettext.info, Node: Makefile, Next: src/Makefile, Prev: config.h.in, Up: Adjusting Files
10160 13.4.11 ‘Makefile.in’ at top level
10161 ----------------------------------
10163 Here are a few modifications you need to make to your main, top-level
10164 ‘Makefile.in’ file.
10166 1. Add the following lines near the beginning of your ‘Makefile.in’,
10167 so the ‘dist:’ goal will work properly (as explained further down):
10169 PACKAGE = @PACKAGE@
10170 VERSION = @VERSION@
10172 2. Add file ‘ABOUT-NLS’ to the ‘DISTFILES’ definition, so the file
10175 3. Wherever you process subdirectories in your ‘Makefile.in’, be sure
10176 you also process the subdirectories ‘intl’ and ‘po’. Special rules
10177 in the ‘Makefiles’ take care for the case where no
10178 internationalization is wanted.
10180 If you are using Makefiles, either generated by automake, or
10181 hand-written so they carefully follow the GNU coding standards, the
10182 effected goals for which the new subdirectories must be handled
10183 include ‘installdirs’, ‘install’, ‘uninstall’, ‘clean’,
10186 Here is an example of a canonical order of processing. In this
10187 example, we also define ‘SUBDIRS’ in ‘Makefile.in’ for it to be
10188 further used in the ‘dist:’ goal.
10190 SUBDIRS = doc intl lib src po
10192 Note that you must arrange for ‘make’ to descend into the ‘intl’
10193 directory before descending into other directories containing code
10194 which make use of the ‘libintl.h’ header file. For this reason,
10195 here we mention ‘intl’ before ‘lib’ and ‘src’.
10197 4. A delicate point is the ‘dist:’ goal, as both ‘intl/Makefile’ and
10198 ‘po/Makefile’ will later assume that the proper directory has been
10199 set up from the main ‘Makefile’. Here is an example at what the
10200 ‘dist:’ goal might look like:
10202 distdir = $(PACKAGE)-$(VERSION)
10206 chmod 777 $(distdir)
10207 for file in $(DISTFILES); do \
10208 ln $$file $(distdir) 2>/dev/null || cp -p $$file $(distdir); \
10210 for subdir in $(SUBDIRS); do \
10211 mkdir $(distdir)/$$subdir || exit 1; \
10212 chmod 777 $(distdir)/$$subdir; \
10213 (cd $$subdir && $(MAKE) $@) || exit 1; \
10215 tar chozf $(distdir).tar.gz $(distdir)
10218 Note that if you are using GNU ‘automake’, ‘Makefile.in’ is
10219 automatically generated from ‘Makefile.am’, and all needed changes to
10220 ‘Makefile.am’ are already made by running ‘gettextize’.
10223 File: gettext.info, Node: src/Makefile, Next: lib/gettext.h, Prev: Makefile, Up: Adjusting Files
10225 13.4.12 ‘Makefile.in’ in ‘src/’
10226 -------------------------------
10228 Some of the modifications made in the main ‘Makefile.in’ will also be
10229 needed in the ‘Makefile.in’ from your package sources, which we assume
10230 here to be in the ‘src/’ subdirectory. Here are all the modifications
10231 needed in ‘src/Makefile.in’:
10233 1. In view of the ‘dist:’ goal, you should have these lines near the
10234 beginning of ‘src/Makefile.in’:
10236 PACKAGE = @PACKAGE@
10237 VERSION = @VERSION@
10239 2. If not done already, you should guarantee that ‘top_srcdir’ gets
10240 defined. This will serve for ‘cpp’ include files. Just add the
10243 top_srcdir = @top_srcdir@
10245 3. You might also want to define ‘subdir’ as ‘src’, later allowing for
10246 almost uniform ‘dist:’ goals in all your ‘Makefile.in’. At list,
10247 the ‘dist:’ goal below assume that you used:
10251 4. The ‘main’ function of your program will normally call
10252 ‘bindtextdomain’ (see *note Triggering::), like this:
10254 bindtextdomain (PACKAGE, LOCALEDIR);
10255 textdomain (PACKAGE);
10257 To make LOCALEDIR known to the program, add the following lines to
10258 ‘Makefile.in’ if you are using Autoconf version 2.60 or newer:
10260 datadir = @datadir@
10261 datarootdir= @datarootdir@
10262 localedir = @localedir@
10263 DEFS = -DLOCALEDIR=\"$(localedir)\" @DEFS@
10265 or these lines if your version of Autoconf is older than 2.60:
10267 datadir = @datadir@
10268 localedir = $(datadir)/locale
10269 DEFS = -DLOCALEDIR=\"$(localedir)\" @DEFS@
10271 Note that ‘@datadir@’ defaults to ‘$(prefix)/share’, thus
10272 ‘$(localedir)’ defaults to ‘$(prefix)/share/locale’.
10274 5. You should ensure that the final linking will use ‘@LIBINTL@’ or
10275 ‘@LTLIBINTL@’ as a library. ‘@LIBINTL@’ is for use without
10276 ‘libtool’, ‘@LTLIBINTL@’ is for use with ‘libtool’. An easy way to
10277 achieve this is to manage that it gets into ‘LIBS’, like this:
10279 LIBS = @LIBINTL@ @LIBS@
10281 In most packages internationalized with GNU ‘gettext’, one will
10282 find a directory ‘lib/’ in which a library containing some helper
10283 functions will be build. (You need at least the few functions
10284 which the GNU ‘gettext’ Library itself needs.) However some of the
10285 functions in the ‘lib/’ also give messages to the user which of
10286 course should be translated, too. Taking care of this, the support
10287 library (say ‘libsupport.a’) should be placed before ‘@LIBINTL@’
10288 and ‘@LIBS@’ in the above example. So one has to write this:
10290 LIBS = ../lib/libsupport.a @LIBINTL@ @LIBS@
10292 6. You should also ensure that directory ‘intl/’ will be searched for
10293 C preprocessor include files in all circumstances. So, you have to
10294 manage so both ‘-I../intl’ and ‘-I$(top_srcdir)/intl’ will be given
10297 7. Your ‘dist:’ goal has to conform with others. Here is a reasonable
10300 distdir = ../$(PACKAGE)-$(VERSION)/$(subdir)
10301 dist: Makefile $(DISTFILES)
10302 for file in $(DISTFILES); do \
10303 ln $$file $(distdir) 2>/dev/null || cp -p $$file $(distdir) || exit 1; \
10306 Note that if you are using GNU ‘automake’, ‘Makefile.in’ is
10307 automatically generated from ‘Makefile.am’, and the first three changes
10308 and the last change are not necessary. The remaining needed
10309 ‘Makefile.am’ modifications are the following:
10311 1. To make LOCALEDIR known to the program, add the following to
10314 <module>_CPPFLAGS = -DLOCALEDIR=\"$(localedir)\"
10316 for each specific module or compilation unit, or
10318 AM_CPPFLAGS = -DLOCALEDIR=\"$(localedir)\"
10320 for all modules and compilation units together. Furthermore, if
10321 you are using an Autoconf version older then 2.60, add this line to
10322 define ‘localedir’:
10324 localedir = $(datadir)/locale
10326 2. To ensure that the final linking will use ‘@LIBINTL@’ or
10327 ‘@LTLIBINTL@’ as a library, add the following to ‘Makefile.am’:
10329 <program>_LDADD = @LIBINTL@
10331 for each specific program, or
10335 for all programs together. Remember that when you use ‘libtool’ to
10336 link a program, you need to use @LTLIBINTL@ instead of @LIBINTL@
10339 3. If you have an ‘intl/’ directory, whose contents is created by
10340 ‘gettextize’, then to ensure that it will be searched for C
10341 preprocessor include files in all circumstances, add something like
10342 this to ‘Makefile.am’:
10344 AM_CPPFLAGS = -I../intl -I$(top_srcdir)/intl
10347 File: gettext.info, Node: lib/gettext.h, Prev: src/Makefile, Up: Adjusting Files
10349 13.4.13 ‘gettext.h’ in ‘lib/’
10350 -----------------------------
10352 Internationalization of packages, as provided by GNU ‘gettext’, is
10353 optional. It can be turned off in two situations:
10355 • When the installer has specified ‘./configure --disable-nls’. This
10356 can be useful when small binaries are more important than features,
10357 for example when building utilities for boot diskettes. It can
10358 also be useful in order to get some specific C compiler warnings
10359 about code quality with some older versions of GCC (older than
10362 • When the package does not include the ‘intl/’ subdirectory, and the
10363 libintl.h header (with its associated libintl library, if any) is
10364 not already installed on the system, it is preferable that the
10365 package builds without internationalization support, rather than to
10366 give a compilation error.
10368 A C preprocessor macro can be used to detect these two cases.
10369 Usually, when ‘libintl.h’ was found and not explicitly disabled, the
10370 ‘ENABLE_NLS’ macro will be defined to 1 in the autoconf generated
10371 configuration file (usually called ‘config.h’). In the two negative
10372 situations, however, this macro will not be defined, thus it will
10373 evaluate to 0 in C preprocessor expressions.
10375 ‘gettext.h’ is a convenience header file for conditional use of
10376 ‘<libintl.h>’, depending on the ‘ENABLE_NLS’ macro. If ‘ENABLE_NLS’ is
10377 set, it includes ‘<libintl.h>’; otherwise it defines no-op substitutes
10378 for the libintl.h functions. We recommend the use of ‘"gettext.h"’ over
10379 direct use of ‘<libintl.h>’, so that portability to older systems is
10380 guaranteed and installers can turn off internationalization if they want
10381 to. In the C code, you will then write
10383 #include "gettext.h"
10387 #include <libintl.h>
10389 The location of ‘gettext.h’ is usually in a directory containing
10390 auxiliary include files. In many GNU packages, there is a directory
10391 ‘lib/’ containing helper functions; ‘gettext.h’ fits there. In other
10392 packages, it can go into the ‘src’ directory.
10394 Do not install the ‘gettext.h’ file in public locations. Every
10395 package that needs it should contain a copy of it on its own.
10398 File: gettext.info, Node: autoconf macros, Next: Version Control Issues, Prev: Adjusting Files, Up: Maintainers
10400 13.5 Autoconf macros for use in ‘configure.ac’
10401 ==============================================
10403 GNU ‘gettext’ installs macros for use in a package’s ‘configure.ac’
10404 or ‘configure.in’. *Note Introduction: (autoconf)Top. The primary
10405 macro is, of course, ‘AM_GNU_GETTEXT’.
10409 * AM_GNU_GETTEXT:: AM_GNU_GETTEXT in ‘gettext.m4’
10410 * AM_GNU_GETTEXT_VERSION:: AM_GNU_GETTEXT_VERSION in ‘gettext.m4’
10411 * AM_GNU_GETTEXT_NEED:: AM_GNU_GETTEXT_NEED in ‘gettext.m4’
10412 * AM_GNU_GETTEXT_INTL_SUBDIR:: AM_GNU_GETTEXT_INTL_SUBDIR in ‘intldir.m4’
10413 * AM_PO_SUBDIRS:: AM_PO_SUBDIRS in ‘po.m4’
10414 * AM_XGETTEXT_OPTION:: AM_XGETTEXT_OPTION in ‘po.m4’
10415 * AM_ICONV:: AM_ICONV in ‘iconv.m4’
10418 File: gettext.info, Node: AM_GNU_GETTEXT, Next: AM_GNU_GETTEXT_VERSION, Prev: autoconf macros, Up: autoconf macros
10420 13.5.1 AM_GNU_GETTEXT in ‘gettext.m4’
10421 -------------------------------------
10423 The ‘AM_GNU_GETTEXT’ macro tests for the presence of the GNU gettext
10424 function family in either the C library or a separate ‘libintl’ library
10425 (shared or static libraries are both supported) or in the package’s
10426 ‘intl/’ directory. It also invokes ‘AM_PO_SUBDIRS’, thus preparing the
10427 ‘po/’ directories of the package for building.
10429 ‘AM_GNU_GETTEXT’ accepts up to three optional arguments. The general
10432 AM_GNU_GETTEXT([INTLSYMBOL], [NEEDSYMBOL], [INTLDIR])
10434 INTLSYMBOL can be ‘external’ or ‘no-libtool’. The default (if it is
10435 not specified or empty) is ‘no-libtool’. INTLSYMBOL should be
10436 ‘external’ for packages with no ‘intl/’ directory. For packages with an
10437 ‘intl/’ directory, you can either use an INTLSYMBOL equal to
10438 ‘no-libtool’, or you can use ‘external’ and override by using the macro
10439 ‘AM_GNU_GETTEXT_INTL_SUBDIR’ elsewhere. The two ways to specify the
10440 existence of an ‘intl/’ directory are equivalent. At build time, a
10441 static library ‘$(top_builddir)/intl/libintl.a’ will then be created.
10443 If NEEDSYMBOL is specified and is ‘need-ngettext’, then GNU gettext
10444 implementations (in libc or libintl) without the ‘ngettext()’ function
10445 will be ignored. If NEEDSYMBOL is specified and is
10446 ‘need-formatstring-macros’, then GNU gettext implementations that don’t
10447 support the ISO C 99 ‘<inttypes.h>’ formatstring macros will be ignored.
10448 Only one NEEDSYMBOL can be specified. These requirements can also be
10449 specified by using the macro ‘AM_GNU_GETTEXT_NEED’ elsewhere. To
10450 specify more than one requirement, just specify the strongest one among
10451 them, or invoke the ‘AM_GNU_GETTEXT_NEED’ macro several times. The
10452 hierarchy among the various alternatives is as follows:
10453 ‘need-formatstring-macros’ implies ‘need-ngettext’.
10455 INTLDIR is used to find the intl libraries. If empty, the value
10456 ‘$(top_builddir)/intl/’ is used.
10458 The ‘AM_GNU_GETTEXT’ macro determines whether GNU gettext is
10459 available and should be used. If so, it sets the ‘USE_NLS’ variable to
10460 ‘yes’; it defines ‘ENABLE_NLS’ to 1 in the autoconf generated
10461 configuration file (usually called ‘config.h’); it sets the variables
10462 ‘LIBINTL’ and ‘LTLIBINTL’ to the linker options for use in a Makefile
10463 (‘LIBINTL’ for use without libtool, ‘LTLIBINTL’ for use with libtool);
10464 it adds an ‘-I’ option to ‘CPPFLAGS’ if necessary. In the negative
10465 case, it sets ‘USE_NLS’ to ‘no’; it sets ‘LIBINTL’ and ‘LTLIBINTL’ to
10466 empty and doesn’t change ‘CPPFLAGS’.
10468 The complexities that ‘AM_GNU_GETTEXT’ deals with are the following:
10470 • Some operating systems have ‘gettext’ in the C library, for example
10471 glibc. Some have it in a separate library ‘libintl’. GNU
10472 ‘libintl’ might have been installed as part of the GNU ‘gettext’
10475 • GNU ‘libintl’, if installed, is not necessarily already in the
10476 search path (‘CPPFLAGS’ for the include file search path, ‘LDFLAGS’
10477 for the library search path).
10479 • Except for glibc, the operating system’s native ‘gettext’ cannot
10480 exploit the GNU mo files, doesn’t have the necessary locale
10481 dependency features, and cannot convert messages from the catalog’s
10482 text encoding to the user’s locale encoding.
10484 • GNU ‘libintl’, if installed, is not necessarily already in the run
10485 time library search path. To avoid the need for setting an
10486 environment variable like ‘LD_LIBRARY_PATH’, the macro adds the
10487 appropriate run time search path options to the ‘LIBINTL’ and
10488 ‘LTLIBINTL’ variables. This works on most systems, but not on some
10489 operating systems with limited shared library support, like SCO.
10491 • GNU ‘libintl’ relies on POSIX/XSI ‘iconv’. The macro checks for
10492 linker options needed to use iconv and appends them to the
10493 ‘LIBINTL’ and ‘LTLIBINTL’ variables.
10496 File: gettext.info, Node: AM_GNU_GETTEXT_VERSION, Next: AM_GNU_GETTEXT_NEED, Prev: AM_GNU_GETTEXT, Up: autoconf macros
10498 13.5.2 AM_GNU_GETTEXT_VERSION in ‘gettext.m4’
10499 ---------------------------------------------
10501 The ‘AM_GNU_GETTEXT_VERSION’ macro declares the version number of the
10502 GNU gettext infrastructure that is used by the package.
10504 The use of this macro is optional; only the ‘autopoint’ program makes
10505 use of it (*note Version Control Issues::).
10508 File: gettext.info, Node: AM_GNU_GETTEXT_NEED, Next: AM_GNU_GETTEXT_INTL_SUBDIR, Prev: AM_GNU_GETTEXT_VERSION, Up: autoconf macros
10510 13.5.3 AM_GNU_GETTEXT_NEED in ‘gettext.m4’
10511 ------------------------------------------
10513 The ‘AM_GNU_GETTEXT_NEED’ macro declares a constraint regarding the
10514 GNU gettext implementation. The syntax is
10516 AM_GNU_GETTEXT_NEED([NEEDSYMBOL])
10518 If NEEDSYMBOL is ‘need-ngettext’, then GNU gettext implementations
10519 (in libc or libintl) without the ‘ngettext()’ function will be ignored.
10520 If NEEDSYMBOL is ‘need-formatstring-macros’, then GNU gettext
10521 implementations that don’t support the ISO C 99 ‘<inttypes.h>’
10522 formatstring macros will be ignored.
10524 The optional second argument of ‘AM_GNU_GETTEXT’ is also taken into
10527 The ‘AM_GNU_GETTEXT_NEED’ invocations can occur before or after the
10528 ‘AM_GNU_GETTEXT’ invocation; the order doesn’t matter.
10531 File: gettext.info, Node: AM_GNU_GETTEXT_INTL_SUBDIR, Next: AM_PO_SUBDIRS, Prev: AM_GNU_GETTEXT_NEED, Up: autoconf macros
10533 13.5.4 AM_GNU_GETTEXT_INTL_SUBDIR in ‘intldir.m4’
10534 -------------------------------------------------
10536 The ‘AM_GNU_GETTEXT_INTL_SUBDIR’ macro specifies that the
10537 ‘AM_GNU_GETTEXT’ macro, although invoked with the first argument
10538 ‘external’, should also prepare for building the ‘intl/’ subdirectory.
10540 The ‘AM_GNU_GETTEXT_INTL_SUBDIR’ invocation can occur before or after
10541 the ‘AM_GNU_GETTEXT’ invocation; the order doesn’t matter.
10543 The use of this macro requires GNU automake 1.10 or newer and GNU
10544 autoconf 2.61 or newer.
10547 File: gettext.info, Node: AM_PO_SUBDIRS, Next: AM_XGETTEXT_OPTION, Prev: AM_GNU_GETTEXT_INTL_SUBDIR, Up: autoconf macros
10549 13.5.5 AM_PO_SUBDIRS in ‘po.m4’
10550 -------------------------------
10552 The ‘AM_PO_SUBDIRS’ macro prepares the ‘po/’ directories of the
10553 package for building. This macro should be used in internationalized
10554 programs written in other programming languages than C, C++, Objective
10555 C, for example ‘sh’, ‘Python’, ‘Lisp’. See *note Programming
10556 Languages:: for a list of programming languages that support
10557 localization through PO files.
10559 The ‘AM_PO_SUBDIRS’ macro determines whether internationalization
10560 should be used. If so, it sets the ‘USE_NLS’ variable to ‘yes’,
10561 otherwise to ‘no’. It also determines the right values for Makefile
10562 variables in each ‘po/’ directory.
10565 File: gettext.info, Node: AM_XGETTEXT_OPTION, Next: AM_ICONV, Prev: AM_PO_SUBDIRS, Up: autoconf macros
10567 13.5.6 AM_XGETTEXT_OPTION in ‘po.m4’
10568 ------------------------------------
10570 The ‘AM_XGETTEXT_OPTION’ macro registers a command-line option to be
10571 used in the invocations of ‘xgettext’ in the ‘po/’ directories of the
10574 For example, if you have a source file that defines a function
10575 ‘error_at_line’ whose fifth argument is a format string, you can use
10576 AM_XGETTEXT_OPTION([--flag=error_at_line:5:c-format])
10577 to instruct ‘xgettext’ to mark all translatable strings in ‘gettext’
10578 invocations that occur as fifth argument to this function as ‘c-format’.
10580 See *note xgettext Invocation:: for the list of options that
10581 ‘xgettext’ accepts.
10583 The use of this macro is an alternative to the use of the
10584 ‘XGETTEXT_OPTIONS’ variable in ‘po/Makevars’.
10587 File: gettext.info, Node: AM_ICONV, Prev: AM_XGETTEXT_OPTION, Up: autoconf macros
10589 13.5.7 AM_ICONV in ‘iconv.m4’
10590 -----------------------------
10592 The ‘AM_ICONV’ macro tests for the presence of the POSIX/XSI ‘iconv’
10593 function family in either the C library or a separate ‘libiconv’
10594 library. If found, it sets the ‘am_cv_func_iconv’ variable to ‘yes’; it
10595 defines ‘HAVE_ICONV’ to 1 in the autoconf generated configuration file
10596 (usually called ‘config.h’); it defines ‘ICONV_CONST’ to ‘const’ or to
10597 empty, depending on whether the second argument of ‘iconv()’ is of type
10598 ‘const char **’ or ‘char **’; it sets the variables ‘LIBICONV’ and
10599 ‘LTLIBICONV’ to the linker options for use in a Makefile (‘LIBICONV’ for
10600 use without libtool, ‘LTLIBICONV’ for use with libtool); it adds an ‘-I’
10601 option to ‘CPPFLAGS’ if necessary. If not found, it sets ‘LIBICONV’ and
10602 ‘LTLIBICONV’ to empty and doesn’t change ‘CPPFLAGS’.
10604 The complexities that ‘AM_ICONV’ deals with are the following:
10606 • Some operating systems have ‘iconv’ in the C library, for example
10607 glibc. Some have it in a separate library ‘libiconv’, for example
10608 OSF/1 or FreeBSD. Regardless of the operating system, GNU
10609 ‘libiconv’ might have been installed. In that case, it should be
10610 used instead of the operating system’s native ‘iconv’.
10612 • GNU ‘libiconv’, if installed, is not necessarily already in the
10613 search path (‘CPPFLAGS’ for the include file search path, ‘LDFLAGS’
10614 for the library search path).
10616 • GNU ‘libiconv’ is binary incompatible with some operating system’s
10617 native ‘iconv’, for example on FreeBSD. Use of an ‘iconv.h’ and
10618 ‘libiconv.so’ that don’t fit together would produce program
10621 • GNU ‘libiconv’, if installed, is not necessarily already in the run
10622 time library search path. To avoid the need for setting an
10623 environment variable like ‘LD_LIBRARY_PATH’, the macro adds the
10624 appropriate run time search path options to the ‘LIBICONV’
10625 variable. This works on most systems, but not on some operating
10626 systems with limited shared library support, like SCO.
10628 ‘iconv.m4’ is distributed with the GNU gettext package because
10629 ‘gettext.m4’ relies on it.
10632 File: gettext.info, Node: Version Control Issues, Next: Release Management, Prev: autoconf macros, Up: Maintainers
10634 13.6 Integrating with Version Control Systems
10635 =============================================
10637 Many projects use version control systems for distributed development
10638 and source backup. This section gives some advice how to manage the
10639 uses of ‘gettextize’, ‘autopoint’ and ‘autoconf’ on version controlled
10644 * Distributed Development:: Avoiding version mismatch in distributed development
10645 * Files under Version Control:: Files to put under version control
10646 * Translations under Version Control:: Put PO Files under Version Control
10647 * autopoint Invocation:: Invoking the ‘autopoint’ Program
10650 File: gettext.info, Node: Distributed Development, Next: Files under Version Control, Prev: Version Control Issues, Up: Version Control Issues
10652 13.6.1 Avoiding version mismatch in distributed development
10653 -----------------------------------------------------------
10655 In a project development with multiple developers, there should be a
10656 single developer who occasionally - when there is desire to upgrade to a
10657 new ‘gettext’ version - runs ‘gettextize’ and performs the changes
10658 listed in *note Adjusting Files::, and then commits his changes to the
10661 It is highly recommended that all developers on a project use the
10662 same version of GNU ‘gettext’ in the package. In other words, if a
10663 developer runs ‘gettextize’, he should go the whole way, make the
10664 necessary remaining changes and commit his changes to the repository.
10665 Otherwise the following damages will likely occur:
10667 • Apparent version mismatch between developers. Since some ‘gettext’
10668 specific portions in ‘configure.ac’, ‘configure.in’ and
10669 ‘Makefile.am’, ‘Makefile.in’ files depend on the ‘gettext’ version,
10670 the use of infrastructure files belonging to different ‘gettext’
10671 versions can easily lead to build errors.
10673 • Hidden version mismatch. Such version mismatch can also lead to
10674 malfunctioning of the package, that may be undiscovered by the
10675 developers. The worst case of hidden version mismatch is that
10676 internationalization of the package doesn’t work at all.
10678 • Release risks. All developers implicitly perform constant testing
10679 on a package. This is important in the days and weeks before a
10680 release. If the guy who makes the release tar files uses a
10681 different version of GNU ‘gettext’ than the other developers, the
10682 distribution will be less well tested than if all had been using
10683 the same ‘gettext’ version. For example, it is possible that a
10684 platform specific bug goes undiscovered due to this constellation.
10687 File: gettext.info, Node: Files under Version Control, Next: Translations under Version Control, Prev: Distributed Development, Up: Version Control Issues
10689 13.6.2 Files to put under version control
10690 -----------------------------------------
10692 There are basically three ways to deal with generated files in the
10693 context of a version controlled repository, such as ‘configure’
10694 generated from ‘configure.ac’, ‘PARSER.c’ generated from ‘PARSER.y’, or
10695 ‘po/Makefile.in.in’ autoinstalled by ‘gettextize’ or ‘autopoint’.
10697 1. All generated files are always committed into the repository.
10699 2. All generated files are committed into the repository occasionally,
10700 for example each time a release is made.
10702 3. Generated files are never committed into the repository.
10704 Each of these three approaches has different advantages and
10707 1. The advantage is that anyone can check out the source at any moment
10708 and gets a working build. The drawbacks are: 1a. It requires some
10709 frequent "push" actions by the maintainers. 1b. The repository
10710 grows in size quite fast.
10712 2. The advantage is that anyone can check out the source, and the
10713 usual "./configure; make" will work. The drawbacks are: 2a. The
10714 one who checks out the repository needs tools like GNU ‘automake’,
10715 GNU ‘autoconf’, GNU ‘m4’ installed in his PATH; sometimes he even
10716 needs particular versions of them. 2b. When a release is made and
10717 a commit is made on the generated files, the other developers get
10718 conflicts on the generated files when merging the local work back
10719 to the repository. Although these conflicts are easy to resolve,
10722 3. The advantage is less work for the maintainers. The drawback is
10723 that anyone who checks out the source not only needs tools like GNU
10724 ‘automake’, GNU ‘autoconf’, GNU ‘m4’ installed in his PATH, but
10725 also that he needs to perform a package specific pre-build step
10726 before being able to "./configure; make".
10728 For the first and second approach, all files modified or brought in
10729 by the occasional ‘gettextize’ invocation and update should be committed
10730 into the repository.
10732 For the third approach, the maintainer can omit from the repository
10733 all the files that ‘gettextize’ mentions as "copy". Instead, he adds to
10734 the ‘configure.ac’ or ‘configure.in’ a line of the form
10736 AM_GNU_GETTEXT_VERSION(0.19.8)
10738 and adds to the package’s pre-build script an invocation of ‘autopoint’.
10739 For everyone who checks out the source, this ‘autopoint’ invocation will
10740 copy into the right place the ‘gettext’ infrastructure files that have
10741 been omitted from the repository.
10743 The version number used as argument to ‘AM_GNU_GETTEXT_VERSION’ is
10744 the version of the ‘gettext’ infrastructure that the package wants to
10745 use. It is also the minimum version number of the ‘autopoint’ program.
10746 So, if you write ‘AM_GNU_GETTEXT_VERSION(0.11.5)’ then the developers
10747 can have any version >= 0.11.5 installed; the package will work with the
10748 0.11.5 infrastructure in all developers’ builds. When the maintainer
10749 then runs gettextize from, say, version 0.12.1 on the package, the
10750 occurrence of ‘AM_GNU_GETTEXT_VERSION(0.11.5)’ will be changed into
10751 ‘AM_GNU_GETTEXT_VERSION(0.12.1)’, and all other developers that use the
10752 CVS will henceforth need to have GNU ‘gettext’ 0.12.1 or newer
10756 File: gettext.info, Node: Translations under Version Control, Next: autopoint Invocation, Prev: Files under Version Control, Up: Version Control Issues
10758 13.6.3 Put PO Files under Version Control
10759 -----------------------------------------
10761 Since translations are valuable assets as well as the source code, it
10762 would make sense to put them under version control. The GNU gettext
10763 infrastructure supports two ways to deal with translations in the
10764 context of a version controlled repository.
10766 1. Both POT file and PO files are committed into the repository.
10768 2. Only PO files are committed into the repository.
10770 If a POT file is absent when building, it will be generated by
10771 scanning the source files with ‘xgettext’, and then the PO files are
10772 regenerated as a dependency. On the other hand, some maintainers want
10773 to keep the POT file unchanged during the development phase. So, even
10774 if a POT file is present and older than the source code, it won’t be
10775 updated automatically. You can manually update it with ‘make
10776 $(DOMAIN).pot-update’, and commit it at certain point.
10778 Special advices for particular version control systems:
10780 • Recent version control systems, Git for instance, ignore file’s
10781 timestamp. In that case, PO files can be accidentally updated even
10782 if a POT file is not updated. To prevent this, you can set
10783 ‘PO_DEPENDS_ON_POT’ variable to ‘no’ in the ‘Makevars’ file and do
10784 ‘make update-po’ manually.
10786 • Location comments such as ‘#: lib/error.c:116’ are sometimes
10787 annoying, since these comments are volatile and may introduce
10788 unwanted change to the working copy when building. To mitigate
10789 this, you can decide to omit those comments from the PO files in
10792 This is possible with the ‘--no-location’ option of the ‘msgmerge’
10793 command (1). The drawback is that, if the location information is
10794 needed, translators have to recover the location comments by
10795 running ‘msgmerge’ again.
10797 ---------- Footnotes ----------
10799 (1) you can also use it through the ‘MSGMERGE_OPTIONS’ option from
10803 File: gettext.info, Node: autopoint Invocation, Prev: Translations under Version Control, Up: Version Control Issues
10805 13.6.4 Invoking the ‘autopoint’ Program
10806 ---------------------------------------
10808 autopoint [OPTION]...
10810 The ‘autopoint’ program copies standard gettext infrastructure files
10811 into a source package. It extracts from a macro call of the form
10812 ‘AM_GNU_GETTEXT_VERSION(VERSION)’, found in the package’s ‘configure.in’
10813 or ‘configure.ac’ file, the gettext version used by the package, and
10814 copies the infrastructure files belonging to this version into the
10817 To extract the latest available infrastructure which satisfies a
10818 version requirement, then you can use the form
10819 ‘AM_GNU_GETTEXT_REQUIRE_VERSION(VERSION)’ instead. For example, if
10820 gettext 0.19.8 is installed on your system and ‘0.19.1’ is requested,
10821 then the infrastructure files of version 0.19.8 will be copied into a
10829 Force overwriting of files that already exist.
10833 Print modifications but don’t perform them. All file copying
10834 actions that ‘autopoint’ would normally execute are inhibited and
10835 instead only listed on standard output.
10837 13.6.4.2 Informative output
10838 ...........................
10841 Display this help and exit.
10844 Output version information and exit.
10846 ‘autopoint’ supports the GNU ‘gettext’ versions from 0.10.35 to the
10847 current one, 0.19.8. In order to apply ‘autopoint’ to a package using a
10848 ‘gettext’ version newer than 0.19.8, you need to install this same
10849 version of GNU ‘gettext’ at least.
10851 In packages using GNU ‘automake’, an invocation of ‘autopoint’ should
10852 be followed by invocations of ‘aclocal’ and then ‘autoconf’ and
10853 ‘autoheader’. The reason is that ‘autopoint’ installs some autoconf
10854 macro files, which are used by ‘aclocal’ to create ‘aclocal.m4’, and the
10855 latter is used by ‘autoconf’ to create the package’s ‘configure’ script
10856 and by ‘autoheader’ to create the package’s ‘config.h.in’ include file
10859 The name ‘autopoint’ is an abbreviation of ‘auto-po-intl-m4’; the
10860 tool copies or updates mostly files in the ‘po’, ‘intl’, ‘m4’
10864 File: gettext.info, Node: Release Management, Prev: Version Control Issues, Up: Maintainers
10866 13.7 Creating a Distribution Tarball
10867 ====================================
10869 In projects that use GNU ‘automake’, the usual commands for creating
10870 a distribution tarball, ‘make dist’ or ‘make distcheck’, automatically
10871 update the PO files as needed.
10873 If GNU ‘automake’ is not used, the maintainer needs to perform this
10874 update before making a release:
10877 $ (cd po; make update-po)
10881 File: gettext.info, Node: Installers, Next: Programming Languages, Prev: Maintainers, Up: Top
10883 14 The Installer’s and Distributor’s View
10884 *****************************************
10886 By default, packages fully using GNU ‘gettext’, internally, are
10887 installed in such a way as to allow translation of messages. At
10888 _configuration_ time, those packages should automatically detect whether
10889 the underlying host system already provides the GNU ‘gettext’ functions.
10890 If not, the GNU ‘gettext’ library should be automatically prepared and
10891 used. Installers may use special options at configuration time for
10892 changing this behavior. The command ‘./configure
10893 --with-included-gettext’ bypasses system ‘gettext’ to use the included
10894 GNU ‘gettext’ instead, while ‘./configure --disable-nls’ produces
10895 programs totally unable to translate messages.
10897 Internationalized packages have usually many ‘LL.po’ files. Unless
10898 translations are disabled, all those available are installed together
10899 with the package. However, the environment variable ‘LINGUAS’ may be
10900 set, prior to configuration, to limit the installed set. ‘LINGUAS’
10901 should then contain a space separated list of two-letter codes, stating
10902 which languages are allowed.
10905 File: gettext.info, Node: Programming Languages, Next: Conclusion, Prev: Installers, Up: Top
10907 15 Other Programming Languages
10908 ******************************
10910 While the presentation of ‘gettext’ focuses mostly on C and
10911 implicitly applies to C++ as well, its scope is far broader than that:
10912 Many programming languages, scripting languages and other textual data
10913 like GUI resources or package descriptions can make use of the gettext
10918 * Language Implementors:: The Language Implementor’s View
10919 * Programmers for other Languages:: The Programmer’s View
10920 * Translators for other Languages:: The Translator’s View
10921 * Maintainers for other Languages:: The Maintainer’s View
10922 * List of Programming Languages:: Individual Programming Languages
10923 * List of Data Formats:: Internationalizable Data
10926 File: gettext.info, Node: Language Implementors, Next: Programmers for other Languages, Prev: Programming Languages, Up: Programming Languages
10928 15.1 The Language Implementor’s View
10929 ====================================
10931 All programming and scripting languages that have the notion of
10932 strings are eligible to supporting ‘gettext’. Supporting ‘gettext’
10933 means the following:
10935 1. You should add to the language a syntax for translatable strings.
10936 In principle, a function call of ‘gettext’ would do, but a
10937 shorthand syntax helps keeping the legibility of internationalized
10938 programs. For example, in C we use the syntax ‘_("string")’, and
10939 in GNU awk we use the shorthand ‘_"string"’.
10941 2. You should arrange that evaluation of such a translatable string at
10942 runtime calls the ‘gettext’ function, or performs equivalent
10945 3. Similarly, you should make the functions ‘ngettext’, ‘dcgettext’,
10946 ‘dcngettext’ available from within the language. These functions
10947 are less often used, but are nevertheless necessary for particular
10948 purposes: ‘ngettext’ for correct plural handling, and ‘dcgettext’
10949 and ‘dcngettext’ for obeying other locale-related environment
10950 variables than ‘LC_MESSAGES’, such as ‘LC_TIME’ or ‘LC_MONETARY’.
10951 For these latter functions, you need to make the ‘LC_*’ constants,
10952 available in the C header ‘<locale.h>’, referenceable from within
10953 the language, usually either as enumeration values or as strings.
10955 4. You should allow the programmer to designate a message domain,
10956 either by making the ‘textdomain’ function available from within
10957 the language, or by introducing a magic variable called
10958 ‘TEXTDOMAIN’. Similarly, you should allow the programmer to
10959 designate where to search for message catalogs, by providing access
10960 to the ‘bindtextdomain’ function.
10962 5. You should either perform a ‘setlocale (LC_ALL, "")’ call during
10963 the startup of your language runtime, or allow the programmer to do
10964 so. Remember that gettext will act as a no-op if the ‘LC_MESSAGES’
10965 and ‘LC_CTYPE’ locale categories are not both set.
10967 6. A programmer should have a way to extract translatable strings from
10968 a program into a PO file. The GNU ‘xgettext’ program is being
10969 extended to support very different programming languages. Please
10970 contact the GNU ‘gettext’ maintainers to help them doing this. If
10971 the string extractor is best integrated into your language’s
10972 parser, GNU ‘xgettext’ can function as a front end to your string
10975 7. The language’s library should have a string formatting facility
10976 where the arguments of a format string are denoted by a positional
10977 number or a name. This is needed because for some languages and
10978 some messages with more than one substitutable argument, the
10979 translation will need to output the substituted arguments in
10980 different order. *Note c-format Flag::.
10982 8. If the language has more than one implementation, and not all of
10983 the implementations use ‘gettext’, but the programs should be
10984 portable across implementations, you should provide a no-i18n
10985 emulation, that makes the other implementations accept programs
10986 written for yours, without actually translating the strings.
10988 9. To help the programmer in the task of marking translatable strings,
10989 which is sometimes performed using the Emacs PO mode (*note
10990 Marking::), you are welcome to contact the GNU ‘gettext’
10991 maintainers, so they can add support for your language to
10994 On the implementation side, three approaches are possible, with
10995 different effects on portability and copyright:
10997 • You may integrate the GNU ‘gettext’’s ‘intl/’ directory in your
10998 package, as described in *note Maintainers::. This allows you to
10999 have internationalization on all kinds of platforms. Note that
11000 when you then distribute your package, it legally falls under the
11001 GNU General Public License, and the GNU project will be glad about
11002 your contribution to the Free Software pool.
11004 • You may link against GNU ‘gettext’ functions if they are found in
11005 the C library. For example, an autoconf test for ‘gettext()’ and
11006 ‘ngettext()’ will detect this situation. For the moment, this test
11007 will succeed on GNU systems and not on other platforms. No severe
11008 copyright restrictions apply.
11010 • You may emulate or reimplement the GNU ‘gettext’ functionality.
11011 This has the advantage of full portability and no copyright
11012 restrictions, but also the drawback that you have to reimplement
11013 the GNU ‘gettext’ features (such as the ‘LANGUAGE’ environment
11014 variable, the locale aliases database, the automatic charset
11015 conversion, and plural handling).
11018 File: gettext.info, Node: Programmers for other Languages, Next: Translators for other Languages, Prev: Language Implementors, Up: Programming Languages
11020 15.2 The Programmer’s View
11021 ==========================
11023 For the programmer, the general procedure is the same as for the C
11024 language. The Emacs PO mode marking supports other languages, and the
11025 GNU ‘xgettext’ string extractor recognizes other languages based on the
11026 file extension or a command-line option. In some languages, ‘setlocale’
11027 is not needed because it is already performed by the underlying language
11031 File: gettext.info, Node: Translators for other Languages, Next: Maintainers for other Languages, Prev: Programmers for other Languages, Up: Programming Languages
11033 15.3 The Translator’s View
11034 ==========================
11036 The translator works exactly as in the C language case. The only
11037 difference is that when translating format strings, she has to be aware
11038 of the language’s particular syntax for positional arguments in format
11043 * c-format:: C Format Strings
11044 * objc-format:: Objective C Format Strings
11045 * sh-format:: Shell Format Strings
11046 * python-format:: Python Format Strings
11047 * lisp-format:: Lisp Format Strings
11048 * elisp-format:: Emacs Lisp Format Strings
11049 * librep-format:: librep Format Strings
11050 * scheme-format:: Scheme Format Strings
11051 * smalltalk-format:: Smalltalk Format Strings
11052 * java-format:: Java Format Strings
11053 * csharp-format:: C# Format Strings
11054 * awk-format:: awk Format Strings
11055 * object-pascal-format:: Object Pascal Format Strings
11056 * ycp-format:: YCP Format Strings
11057 * tcl-format:: Tcl Format Strings
11058 * perl-format:: Perl Format Strings
11059 * php-format:: PHP Format Strings
11060 * gcc-internal-format:: GCC internal Format Strings
11061 * gfc-internal-format:: GFC internal Format Strings
11062 * qt-format:: Qt Format Strings
11063 * qt-plural-format:: Qt Plural Format Strings
11064 * kde-format:: KDE Format Strings
11065 * kde-kuit-format:: KUIT Format Strings
11066 * boost-format:: Boost Format Strings
11067 * lua-format:: Lua Format Strings
11068 * javascript-format:: JavaScript Format Strings
11071 File: gettext.info, Node: c-format, Next: objc-format, Prev: Translators for other Languages, Up: Translators for other Languages
11073 15.3.1 C Format Strings
11074 -----------------------
11076 C format strings are described in POSIX (IEEE P1003.1 2001), section
11078 <http://www.opengroup.org/onlinepubs/007904975/functions/fprintf.html>.
11079 See also the fprintf() manual page,
11080 <http://www.linuxvalley.it/encyclopedia/ldp/manpage/man3/printf.3.php>,
11081 <http://informatik.fh-wuerzburg.de/student/i510/man/printf.html>.
11083 Although format strings with positions that reorder arguments, such
11086 "Only %2$d bytes free on '%1$s'."
11088 which is semantically equivalent to
11090 "'%s' has only %d bytes free."
11092 are a POSIX/XSI feature and not specified by ISO C 99, translators can
11093 rely on this reordering ability: On the few platforms where ‘printf()’,
11094 ‘fprintf()’ etc. don’t support this feature natively, ‘libintl.a’ or
11095 ‘libintl.so’ provides replacement functions, and GNU ‘<libintl.h>’
11096 activates these replacement functions automatically.
11098 As a special feature for Farsi (Persian) and maybe Arabic,
11099 translators can insert an ‘I’ flag into numeric format directives. For
11100 example, the translation of ‘"%d"’ can be ‘"%Id"’. The effect of this
11101 flag, on systems with GNU ‘libc’, is that in the output, the ASCII
11102 digits are replaced with the ‘outdigits’ defined in the ‘LC_CTYPE’
11103 locale category. On other systems, the ‘gettext’ function removes this
11104 flag, so that it has no effect.
11106 Note that the programmer should _not_ put this flag into the
11107 untranslated string. (Putting the ‘I’ format directive flag into an
11108 MSGID string would lead to undefined behaviour on platforms without
11109 glibc when NLS is disabled.)
11112 File: gettext.info, Node: objc-format, Next: sh-format, Prev: c-format, Up: Translators for other Languages
11114 15.3.2 Objective C Format Strings
11115 ---------------------------------
11117 Objective C format strings are like C format strings. They support
11118 an additional format directive: "%@", which when executed consumes an
11119 argument of type ‘Object *’.
11122 File: gettext.info, Node: sh-format, Next: python-format, Prev: objc-format, Up: Translators for other Languages
11124 15.3.3 Shell Format Strings
11125 ---------------------------
11127 Shell format strings, as supported by GNU gettext and the ‘envsubst’
11128 program, are strings with references to shell variables in the form
11129 ‘$VARIABLE’ or ‘${VARIABLE}’. References of the form
11130 ‘${VARIABLE-DEFAULT}’, ‘${VARIABLE:-DEFAULT}’, ‘${VARIABLE=DEFAULT}’,
11131 ‘${VARIABLE:=DEFAULT}’, ‘${VARIABLE+REPLACEMENT}’,
11132 ‘${VARIABLE:+REPLACEMENT}’, ‘${VARIABLE?IGNORED}’,
11133 ‘${VARIABLE:?IGNORED}’, that would be valid inside shell scripts, are
11134 not supported. The VARIABLE names must consist solely of alphanumeric
11135 or underscore ASCII characters, not start with a digit and be nonempty;
11136 otherwise such a variable reference is ignored.
11139 File: gettext.info, Node: python-format, Next: lisp-format, Prev: sh-format, Up: Translators for other Languages
11141 15.3.4 Python Format Strings
11142 ----------------------------
11144 There are two kinds of format strings in Python: those acceptable to
11145 the Python built-in format operator ‘%’, labelled as ‘python-format’,
11146 and those acceptable to the ‘format’ method of the ‘str’ object.
11148 Python ‘%’ format strings are described in Python Library reference /
11149 5. Built-in Types / 5.6. Sequence Types /
11150 5.6.2. String Formatting Operations.
11151 <http://docs.python.org/2/library/stdtypes.html#string-formatting-operations>.
11153 Python brace format strings are described in
11154 PEP 3101 – Advanced String Formatting,
11155 <http://www.python.org/dev/peps/pep-3101/>.
11158 File: gettext.info, Node: lisp-format, Next: elisp-format, Prev: python-format, Up: Translators for other Languages
11160 15.3.5 Lisp Format Strings
11161 --------------------------
11163 Lisp format strings are described in the Common Lisp HyperSpec,
11164 chapter 22.3 Formatted Output,
11165 <http://www.lisp.org/HyperSpec/Body/sec_22-3.html>.
11168 File: gettext.info, Node: elisp-format, Next: librep-format, Prev: lisp-format, Up: Translators for other Languages
11170 15.3.6 Emacs Lisp Format Strings
11171 --------------------------------
11173 Emacs Lisp format strings are documented in the Emacs Lisp reference,
11174 section Formatting Strings,
11175 <http://www.gnu.org/manual/elisp-manual-21-2.8/html_chapter/elisp_4.html#SEC75>.
11176 Note that as of version 21, XEmacs supports numbered argument
11177 specifications in format strings while FSF Emacs doesn’t.
11180 File: gettext.info, Node: librep-format, Next: scheme-format, Prev: elisp-format, Up: Translators for other Languages
11182 15.3.7 librep Format Strings
11183 ----------------------------
11185 librep format strings are documented in the librep manual, section
11187 <http://librep.sourceforge.net/librep-manual.html#Formatted%20Output>,
11188 <http://www.gwinnup.org/research/docs/librep.html#SEC122>.
11191 File: gettext.info, Node: scheme-format, Next: smalltalk-format, Prev: librep-format, Up: Translators for other Languages
11193 15.3.8 Scheme Format Strings
11194 ----------------------------
11196 Scheme format strings are documented in the SLIB manual, section
11197 Format Specification.
11200 File: gettext.info, Node: smalltalk-format, Next: java-format, Prev: scheme-format, Up: Translators for other Languages
11202 15.3.9 Smalltalk Format Strings
11203 -------------------------------
11205 Smalltalk format strings are described in the GNU Smalltalk
11206 documentation, class ‘CharArray’, methods ‘bindWith:’ and
11207 ‘bindWithArguments:’.
11208 <http://www.gnu.org/software/smalltalk/gst-manual/gst_68.html#SEC238>.
11209 In summary, a directive starts with ‘%’ and is followed by ‘%’ or a
11210 nonzero digit (‘1’ to ‘9’).
11213 File: gettext.info, Node: java-format, Next: csharp-format, Prev: smalltalk-format, Up: Translators for other Languages
11215 15.3.10 Java Format Strings
11216 ---------------------------
11218 Java format strings are described in the JDK documentation for class
11219 ‘java.text.MessageFormat’,
11220 <http://java.sun.com/j2se/1.4/docs/api/java/text/MessageFormat.html>.
11221 See also the ICU documentation
11222 <http://oss.software.ibm.com/icu/apiref/classMessageFormat.html>.
11225 File: gettext.info, Node: csharp-format, Next: awk-format, Prev: java-format, Up: Translators for other Languages
11227 15.3.11 C# Format Strings
11228 -------------------------
11230 C# format strings are described in the .NET documentation for class
11231 ‘System.String’ and in
11232 <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpConFormattingOverview.asp>.
11235 File: gettext.info, Node: awk-format, Next: object-pascal-format, Prev: csharp-format, Up: Translators for other Languages
11237 15.3.12 awk Format Strings
11238 --------------------------
11240 awk format strings are described in the gawk documentation, section
11241 Printf, <http://www.gnu.org/manual/gawk/html_node/Printf.html#Printf>.
11244 File: gettext.info, Node: object-pascal-format, Next: ycp-format, Prev: awk-format, Up: Translators for other Languages
11246 15.3.13 Object Pascal Format Strings
11247 ------------------------------------
11249 Object Pascal format strings are described in the documentation of
11250 the Free Pascal runtime library, section Format,
11251 <http://www.freepascal.org/docs-html/rtl/sysutils/format.html>.
11254 File: gettext.info, Node: ycp-format, Next: tcl-format, Prev: object-pascal-format, Up: Translators for other Languages
11256 15.3.14 YCP Format Strings
11257 --------------------------
11259 YCP sformat strings are described in the libycp documentation
11260 <file:/usr/share/doc/packages/libycp/YCP-builtins.html>. In summary, a
11261 directive starts with ‘%’ and is followed by ‘%’ or a nonzero digit (‘1’
11265 File: gettext.info, Node: tcl-format, Next: perl-format, Prev: ycp-format, Up: Translators for other Languages
11267 15.3.15 Tcl Format Strings
11268 --------------------------
11270 Tcl format strings are described in the ‘format.n’ manual page,
11271 <http://www.scriptics.com/man/tcl8.3/TclCmd/format.htm>.
11274 File: gettext.info, Node: perl-format, Next: php-format, Prev: tcl-format, Up: Translators for other Languages
11276 15.3.16 Perl Format Strings
11277 ---------------------------
11279 There are two kinds format strings in Perl: those acceptable to the
11280 Perl built-in function ‘printf’, labelled as ‘perl-format’, and those
11281 acceptable to the ‘libintl-perl’ function ‘__x’, labelled as
11282 ‘perl-brace-format’.
11284 Perl ‘printf’ format strings are described in the ‘sprintf’ section
11287 Perl brace format strings are described in the
11288 ‘Locale::TextDomain(3pm)’ manual page of the CPAN package libintl-perl.
11289 In brief, Perl format uses placeholders put between braces (‘{’ and
11290 ‘}’). The placeholder must have the syntax of simple identifiers.
11293 File: gettext.info, Node: php-format, Next: gcc-internal-format, Prev: perl-format, Up: Translators for other Languages
11295 15.3.17 PHP Format Strings
11296 --------------------------
11298 PHP format strings are described in the documentation of the PHP
11299 function ‘sprintf’, in ‘phpdoc/manual/function.sprintf.html’ or
11300 <http://www.php.net/manual/en/function.sprintf.php>.
11303 File: gettext.info, Node: gcc-internal-format, Next: gfc-internal-format, Prev: php-format, Up: Translators for other Languages
11305 15.3.18 GCC internal Format Strings
11306 -----------------------------------
11308 These format strings are used inside the GCC sources. In such a
11309 format string, a directive starts with ‘%’, is optionally followed by a
11310 size specifier ‘l’, an optional flag ‘+’, another optional flag ‘#’, and
11311 is finished by a specifier: ‘%’ denotes a literal percent sign, ‘c’
11312 denotes a character, ‘s’ denotes a string, ‘i’ and ‘d’ denote an
11313 integer, ‘o’, ‘u’, ‘x’ denote an unsigned integer, ‘.*s’ denotes a
11314 string preceded by a width specification, ‘H’ denotes a ‘location_t *’
11315 pointer, ‘D’ denotes a general declaration, ‘F’ denotes a function
11316 declaration, ‘T’ denotes a type, ‘A’ denotes a function argument, ‘C’
11317 denotes a tree code, ‘E’ denotes an expression, ‘L’ denotes a
11318 programming language, ‘O’ denotes a binary operator, ‘P’ denotes a
11319 function parameter, ‘Q’ denotes an assignment operator, ‘V’ denotes a
11320 const/volatile qualifier.
11323 File: gettext.info, Node: gfc-internal-format, Next: qt-format, Prev: gcc-internal-format, Up: Translators for other Languages
11325 15.3.19 GFC internal Format Strings
11326 -----------------------------------
11328 These format strings are used inside the GNU Fortran Compiler
11329 sources, that is, the Fortran frontend in the GCC sources. In such a
11330 format string, a directive starts with ‘%’ and is finished by a
11331 specifier: ‘%’ denotes a literal percent sign, ‘C’ denotes the current
11332 source location, ‘L’ denotes a source location, ‘c’ denotes a character,
11333 ‘s’ denotes a string, ‘i’ and ‘d’ denote an integer, ‘u’ denotes an
11334 unsigned integer. ‘i’, ‘d’, and ‘u’ may be preceded by a size specifier
11338 File: gettext.info, Node: qt-format, Next: qt-plural-format, Prev: gfc-internal-format, Up: Translators for other Languages
11340 15.3.20 Qt Format Strings
11341 -------------------------
11343 Qt format strings are described in the documentation of the QString
11344 class <file:/usr/lib/qt-4.3.0/doc/html/qstring.html>. In summary, a
11345 directive consists of a ‘%’ followed by a digit. The same directive
11346 cannot occur more than once in a format string.
11349 File: gettext.info, Node: qt-plural-format, Next: kde-format, Prev: qt-format, Up: Translators for other Languages
11351 15.3.21 Qt Format Strings
11352 -------------------------
11354 Qt format strings are described in the documentation of the
11355 QObject::tr method <file:/usr/lib/qt-4.3.0/doc/html/qobject.html>. In
11356 summary, the only allowed directive is ‘%n’.
11359 File: gettext.info, Node: kde-format, Next: kde-kuit-format, Prev: qt-plural-format, Up: Translators for other Languages
11361 15.3.22 KDE Format Strings
11362 --------------------------
11364 KDE 4 format strings are defined as follows: A directive consists of
11365 a ‘%’ followed by a non-zero decimal number. If a ‘%n’ occurs in a
11366 format strings, all of ‘%1’, ..., ‘%(n-1)’ must occur as well, except
11367 possibly one of them.
11370 File: gettext.info, Node: kde-kuit-format, Next: boost-format, Prev: kde-format, Up: Translators for other Languages
11372 15.3.23 KUIT Format Strings
11373 ---------------------------
11375 KUIT (KDE User Interface Text) is compatible with KDE 4 format
11376 strings, while it also allows programmers to add semantic information to
11377 a format string, through XML markup tags. For example, if the first
11378 format directive in a string is a filename, programmers could indicate
11379 that with a ‘filename’ tag, like ‘<filename>%1</filename>’.
11381 KUIT format strings are described in
11382 <http://api.kde.org/frameworks-api/frameworks5-apidocs/ki18n/html/prg_guide.html#kuit_markup>.
11385 File: gettext.info, Node: boost-format, Next: lua-format, Prev: kde-kuit-format, Up: Translators for other Languages
11387 15.3.24 Boost Format Strings
11388 ----------------------------
11390 Boost format strings are described in the documentation of the
11391 ‘boost::format’ class, at
11392 <http://www.boost.org/libs/format/doc/format.html>. In summary, a
11393 directive has either the same syntax as in a C format string, such as
11394 ‘%1$+5d’, or may be surrounded by vertical bars, such as ‘%|1$+5d|’ or
11395 ‘%|1$+5|’, or consists of just an argument number between percent signs,
11399 File: gettext.info, Node: lua-format, Next: javascript-format, Prev: boost-format, Up: Translators for other Languages
11401 15.3.25 Lua Format Strings
11402 --------------------------
11404 Lua format strings are described in the Lua reference manual, section
11405 String Manipulation,
11406 <http://www.lua.org/manual/5.1/manual.html#pdf-string.format>.
11409 File: gettext.info, Node: javascript-format, Prev: lua-format, Up: Translators for other Languages
11411 15.3.26 JavaScript Format Strings
11412 ---------------------------------
11414 Although JavaScript specification itself does not define any format
11415 strings, many JavaScript implementations provide printf-like functions.
11416 ‘xgettext’ understands a set of common format strings used in popular
11417 JavaScript implementations including Gjs, Seed, and Node.JS. In such a
11418 format string, a directive starts with ‘%’ and is finished by a
11419 specifier: ‘%’ denotes a literal percent sign, ‘c’ denotes a character,
11420 ‘s’ denotes a string, ‘b’, ‘d’, ‘o’, ‘x’, ‘X’ denote an integer, ‘f’
11421 denotes floating-point number, ‘j’ denotes a JSON object.
11424 File: gettext.info, Node: Maintainers for other Languages, Next: List of Programming Languages, Prev: Translators for other Languages, Up: Programming Languages
11426 15.4 The Maintainer’s View
11427 ==========================
11429 For the maintainer, the general procedure differs from the C language
11432 • For those languages that don’t use GNU gettext, the ‘intl/’
11433 directory is not needed and can be omitted. This means that the
11434 maintainer calls the ‘gettextize’ program without the ‘--intl’
11435 option, and that he invokes the ‘AM_GNU_GETTEXT’ autoconf macro via
11436 ‘AM_GNU_GETTEXT([external])’.
11438 • If only a single programming language is used, the
11439 ‘XGETTEXT_OPTIONS’ variable in ‘po/Makevars’ (*note po/Makevars::)
11440 should be adjusted to match the ‘xgettext’ options for that
11441 particular programming language. If the package uses more than one
11442 programming language with ‘gettext’ support, it becomes necessary
11443 to change the POT file construction rule in ‘po/Makefile.in.in’.
11444 It is recommended to make one ‘xgettext’ invocation per programming
11445 language, each with the options appropriate for that language, and
11446 to combine the resulting files using ‘msgcat’.
11449 File: gettext.info, Node: List of Programming Languages, Next: List of Data Formats, Prev: Maintainers for other Languages, Up: Programming Languages
11451 15.5 Individual Programming Languages
11452 =====================================
11456 * C:: C, C++, Objective C
11457 * sh:: sh - Shell Script
11458 * bash:: bash - Bourne-Again Shell Script
11460 * Common Lisp:: GNU clisp - Common Lisp
11461 * clisp C:: GNU clisp C sources
11462 * Emacs Lisp:: Emacs Lisp
11464 * Scheme:: GNU guile - Scheme
11465 * Smalltalk:: GNU Smalltalk
11469 * Pascal:: Pascal - Free Pascal Compiler
11470 * wxWidgets:: wxWidgets library
11471 * YCP:: YCP - YaST2 scripting language
11472 * Tcl:: Tcl - Tk’s scripting language
11474 * PHP:: PHP Hypertext Preprocessor
11476 * GCC-source:: GNU Compiler Collection sources
11478 * JavaScript:: JavaScript
11482 File: gettext.info, Node: C, Next: sh, Prev: List of Programming Languages, Up: List of Programming Languages
11484 15.5.1 C, C++, Objective C
11485 --------------------------
11488 gcc, gpp, gobjc, glibc, gettext
11492 For C++: ‘C’, ‘c++’, ‘cc’, ‘cxx’, ‘cpp’, ‘hpp’.
11493 For Objective C: ‘m’.
11501 gettext/ngettext functions
11502 ‘gettext’, ‘dgettext’, ‘dcgettext’, ‘ngettext’, ‘dngettext’,
11506 ‘textdomain’ function
11509 ‘bindtextdomain’ function
11512 Programmer must call ‘setlocale (LC_ALL, "")’
11515 ‘#include <libintl.h>’
11516 ‘#include <locale.h>’
11517 ‘#define _(string) gettext (string)’
11519 Use or emulate GNU gettext
11525 Formatting with positions
11526 ‘fprintf "%2$d %1$d"’
11527 In C++: ‘autosprintf "%2$d %1$d"’ (*note Introduction:
11531 autoconf (gettext.m4) and #if ENABLE_NLS
11536 The following examples are available in the ‘examples’ directory:
11537 ‘hello-c’, ‘hello-c-gnome’, ‘hello-c++’, ‘hello-c++-qt’,
11538 ‘hello-c++-kde’, ‘hello-c++-gnome’, ‘hello-c++-wxwidgets’, ‘hello-objc’,
11539 ‘hello-objc-gnustep’, ‘hello-objc-gnome’.
11542 File: gettext.info, Node: sh, Next: bash, Prev: C, Up: List of Programming Languages
11544 15.5.2 sh - Shell Script
11545 ------------------------
11554 ‘"abc"’, ‘'abc'’, ‘abc’
11557 ‘"`gettext \"abc\"`"’
11559 gettext/ngettext functions
11560 ‘gettext’, ‘ngettext’ programs
11561 ‘eval_gettext’, ‘eval_ngettext’ shell functions
11564 environment variable ‘TEXTDOMAIN’
11567 environment variable ‘TEXTDOMAINDIR’
11575 Use or emulate GNU gettext
11581 Formatting with positions
11590 An example is available in the ‘examples’ directory: ‘hello-sh’.
11594 * Preparing Shell Scripts:: Preparing Shell Scripts for Internationalization
11595 * gettext.sh:: Contents of ‘gettext.sh’
11596 * gettext Invocation:: Invoking the ‘gettext’ program
11597 * ngettext Invocation:: Invoking the ‘ngettext’ program
11598 * envsubst Invocation:: Invoking the ‘envsubst’ program
11599 * eval_gettext Invocation:: Invoking the ‘eval_gettext’ function
11600 * eval_ngettext Invocation:: Invoking the ‘eval_ngettext’ function
11603 File: gettext.info, Node: Preparing Shell Scripts, Next: gettext.sh, Prev: sh, Up: sh
11605 15.5.2.1 Preparing Shell Scripts for Internationalization
11606 .........................................................
11608 Preparing a shell script for internationalization is conceptually
11609 similar to the steps described in *note Sources::. The concrete steps
11610 for shell scripts are as follows.
11616 near the top of the script. ‘gettext.sh’ is a shell function
11617 library that provides the functions ‘eval_gettext’ (see *note
11618 eval_gettext Invocation::) and ‘eval_ngettext’ (see *note
11619 eval_ngettext Invocation::). You have to ensure that ‘gettext.sh’
11620 can be found in the ‘PATH’.
11622 2. Set and export the ‘TEXTDOMAIN’ and ‘TEXTDOMAINDIR’ environment
11623 variables. Usually ‘TEXTDOMAIN’ is the package or program name,
11624 and ‘TEXTDOMAINDIR’ is the absolute pathname corresponding to
11625 ‘$prefix/share/locale’, where ‘$prefix’ is the installation
11628 TEXTDOMAIN=@PACKAGE@
11630 TEXTDOMAINDIR=@LOCALEDIR@
11631 export TEXTDOMAINDIR
11633 3. Prepare the strings for translation, as described in *note
11634 Preparing Strings::.
11636 4. Simplify translatable strings so that they don’t contain command
11637 substitution (‘"`...`"’ or ‘"$(...)"’), variable access with
11638 defaulting (like ‘${VARIABLE-DEFAULT}’), access to positional
11639 arguments (like ‘$0’, ‘$1’, ...) or highly volatile shell
11640 variables (like ‘$?’). This can always be done through simple
11641 local code restructuring. For example,
11643 echo "Usage: $0 [OPTION] FILE..."
11648 echo "Usage: $program_name [OPTION] FILE..."
11652 echo "Remaining files: `ls | wc -l`"
11656 filecount="`ls | wc -l`"
11657 echo "Remaining files: $filecount"
11659 5. For each translatable string, change the output command ‘echo’ or
11660 ‘$echo’ to ‘gettext’ (if the string contains no references to shell
11661 variables) or to ‘eval_gettext’ (if it refers to shell variables),
11662 followed by a no-argument ‘echo’ command (to account for the
11663 terminating newline). Similarly, for cases with plural handling,
11664 replace a conditional ‘echo’ command with an invocation of
11665 ‘ngettext’ or ‘eval_ngettext’, followed by a no-argument ‘echo’
11668 When doing this, you also need to add an extra backslash before the
11669 dollar sign in references to shell variables, so that the
11670 ‘eval_gettext’ function receives the translatable string before the
11671 variable values are substituted into it. For example,
11673 echo "Remaining files: $filecount"
11677 eval_gettext "Remaining files: \$filecount"; echo
11679 If the output command is not ‘echo’, you can make it use ‘echo’
11680 nevertheless, through the use of backquotes. However, note that
11681 inside backquotes, backslashes must be doubled to be effective
11682 (because the backquoting eats one level of backslashes). For
11683 example, assuming that ‘error’ is a shell function that signals an
11686 error "file not found: $filename"
11688 is first transformed into
11690 error "`echo \"file not found: \$filename\"`"
11694 error "`eval_gettext \"file not found: \\\$filename\"`"
11697 File: gettext.info, Node: gettext.sh, Next: gettext Invocation, Prev: Preparing Shell Scripts, Up: sh
11699 15.5.2.2 Contents of ‘gettext.sh’
11700 .................................
11702 ‘gettext.sh’, contained in the run-time package of GNU gettext,
11703 provides the following:
11705 • $echo The variable ‘echo’ is set to a command that outputs its
11706 first argument and a newline, without interpreting backslashes in
11707 the argument string.
11709 • eval_gettext See *note eval_gettext Invocation::.
11711 • eval_ngettext See *note eval_ngettext Invocation::.
11714 File: gettext.info, Node: gettext Invocation, Next: ngettext Invocation, Prev: gettext.sh, Up: sh
11716 15.5.2.3 Invoking the ‘gettext’ program
11717 .......................................
11719 gettext [OPTION] [[TEXTDOMAIN] MSGID]
11720 gettext [OPTION] -s [MSGID]...
11722 The ‘gettext’ program displays the native language translation of a
11728 ‘--domain=TEXTDOMAIN’
11729 Retrieve translated messages from TEXTDOMAIN. Usually a TEXTDOMAIN
11730 corresponds to a package, a program, or a module of a program.
11733 Enable expansion of some escape sequences. This option is for
11734 compatibility with the ‘echo’ program or shell built-in. The
11735 escape sequences ‘\a’, ‘\b’, ‘\c’, ‘\f’, ‘\n’, ‘\r’, ‘\t’, ‘\v’,
11736 ‘\\’, and ‘\’ followed by one to three octal digits, are
11737 interpreted like the System V ‘echo’ program did.
11740 This option is only for compatibility with the ‘echo’ program or
11741 shell built-in. It has no effect.
11745 Display this help and exit.
11748 Suppress trailing newline. By default, ‘gettext’ adds a newline to
11753 Output version information and exit.
11755 ‘[TEXTDOMAIN] MSGID’
11756 Retrieve translated message corresponding to MSGID from TEXTDOMAIN.
11758 If the TEXTDOMAIN parameter is not given, the domain is determined
11759 from the environment variable ‘TEXTDOMAIN’. If the message catalog is
11760 not found in the regular directory, another location can be specified
11761 with the environment variable ‘TEXTDOMAINDIR’.
11763 When used with the ‘-s’ option the program behaves like the ‘echo’
11764 command. But it does not simply copy its arguments to stdout. Instead
11765 those messages found in the selected catalog are translated.
11767 Note: ‘xgettext’ supports only the one-argument form of the ‘gettext’
11768 invocation, where no options are present and the TEXTDOMAIN is implicit,
11769 from the environment.
11772 File: gettext.info, Node: ngettext Invocation, Next: envsubst Invocation, Prev: gettext Invocation, Up: sh
11774 15.5.2.4 Invoking the ‘ngettext’ program
11775 ........................................
11777 ngettext [OPTION] [TEXTDOMAIN] MSGID MSGID-PLURAL COUNT
11779 The ‘ngettext’ program displays the native language translation of a
11780 textual message whose grammatical form depends on a number.
11785 ‘--domain=TEXTDOMAIN’
11786 Retrieve translated messages from TEXTDOMAIN. Usually a TEXTDOMAIN
11787 corresponds to a package, a program, or a module of a program.
11790 Enable expansion of some escape sequences. This option is for
11791 compatibility with the ‘gettext’ program. The escape sequences
11792 ‘\a’, ‘\b’, ‘\c’, ‘\f’, ‘\n’, ‘\r’, ‘\t’, ‘\v’, ‘\\’, and ‘\’
11793 followed by one to three octal digits, are interpreted like the
11794 System V ‘echo’ program did.
11797 This option is only for compatibility with the ‘gettext’ program.
11802 Display this help and exit.
11806 Output version information and exit.
11809 Retrieve translated message from TEXTDOMAIN.
11811 ‘MSGID MSGID-PLURAL’
11812 Translate MSGID (English singular) / MSGID-PLURAL (English plural).
11815 Choose singular/plural form based on this value.
11817 If the TEXTDOMAIN parameter is not given, the domain is determined
11818 from the environment variable ‘TEXTDOMAIN’. If the message catalog is
11819 not found in the regular directory, another location can be specified
11820 with the environment variable ‘TEXTDOMAINDIR’.
11822 Note: ‘xgettext’ supports only the three-arguments form of the
11823 ‘ngettext’ invocation, where no options are present and the TEXTDOMAIN
11824 is implicit, from the environment.
11827 File: gettext.info, Node: envsubst Invocation, Next: eval_gettext Invocation, Prev: ngettext Invocation, Up: sh
11829 15.5.2.5 Invoking the ‘envsubst’ program
11830 ........................................
11832 envsubst [OPTION] [SHELL-FORMAT]
11834 The ‘envsubst’ program substitutes the values of environment
11841 Output the variables occurring in SHELL-FORMAT.
11843 *Informative output*
11847 Display this help and exit.
11851 Output version information and exit.
11853 In normal operation mode, standard input is copied to standard
11854 output, with references to environment variables of the form ‘$VARIABLE’
11855 or ‘${VARIABLE}’ being replaced with the corresponding values. If a
11856 SHELL-FORMAT is given, only those environment variables that are
11857 referenced in SHELL-FORMAT are substituted; otherwise all environment
11858 variables references occurring in standard input are substituted.
11860 These substitutions are a subset of the substitutions that a shell
11861 performs on unquoted and double-quoted strings. Other kinds of
11862 substitutions done by a shell, such as ‘${VARIABLE-DEFAULT}’ or
11863 ‘$(COMMAND-LIST)’ or ‘`COMMAND-LIST`’, are not performed by the
11864 ‘envsubst’ program, due to security reasons.
11866 When ‘--variables’ is used, standard input is ignored, and the output
11867 consists of the environment variables that are referenced in
11868 SHELL-FORMAT, one per line.
11871 File: gettext.info, Node: eval_gettext Invocation, Next: eval_ngettext Invocation, Prev: envsubst Invocation, Up: sh
11873 15.5.2.6 Invoking the ‘eval_gettext’ function
11874 .............................................
11878 This function outputs the native language translation of a textual
11879 message, performing dollar-substitution on the result. Note that only
11880 shell variables mentioned in MSGID will be dollar-substituted in the
11884 File: gettext.info, Node: eval_ngettext Invocation, Prev: eval_gettext Invocation, Up: sh
11886 15.5.2.7 Invoking the ‘eval_ngettext’ function
11887 ..............................................
11889 eval_ngettext MSGID MSGID-PLURAL COUNT
11891 This function outputs the native language translation of a textual
11892 message whose grammatical form depends on a number, performing
11893 dollar-substitution on the result. Note that only shell variables
11894 mentioned in MSGID or MSGID-PLURAL will be dollar-substituted in the
11898 File: gettext.info, Node: bash, Next: Python, Prev: sh, Up: List of Programming Languages
11900 15.5.3 bash - Bourne-Again Shell Script
11901 ---------------------------------------
11903 GNU ‘bash’ 2.0 or newer has a special shorthand for translating a
11904 string and substituting variable values in it: ‘$"msgid"’. But the use
11905 of this construct is *discouraged*, due to the security holes it opens
11906 and due to its portability problems.
11908 The security holes of ‘$"..."’ come from the fact that after looking
11909 up the translation of the string, ‘bash’ processes it like it processes
11910 any double-quoted string: dollar and backquote processing, like ‘eval’
11913 1. In a locale whose encoding is one of BIG5, BIG5-HKSCS, GBK,
11914 GB18030, SHIFT_JIS, JOHAB, some double-byte characters have a
11915 second byte whose value is ‘0x60’. For example, the byte sequence
11916 ‘\xe0\x60’ is a single character in these locales. Many versions
11917 of ‘bash’ (all versions up to bash-2.05, and newer versions on
11918 platforms without ‘mbsrtowcs()’ function) don’t know about
11919 character boundaries and see a backquote character where there is
11920 only a particular Chinese character. Thus it can start executing
11921 part of the translation as a command list. This situation can
11922 occur even without the translator being aware of it: if the
11923 translator provides translations in the UTF-8 encoding, it is the
11924 ‘gettext()’ function which will, during its conversion from the
11925 translator’s encoding to the user’s locale’s encoding, produce the
11926 dangerous ‘\x60’ bytes.
11928 2. A translator could - voluntarily or inadvertently - use backquotes
11929 ‘"`...`"’ or dollar-parentheses ‘"$(...)"’ in her translations.
11930 The enclosed strings would be executed as command lists by the
11933 The portability problem is that ‘bash’ must be built with
11934 internationalization support; this is normally not the case on systems
11935 that don’t have the ‘gettext()’ function in libc.
11938 File: gettext.info, Node: Python, Next: Common Lisp, Prev: bash, Up: List of Programming Languages
11950 ‘'abc'’, ‘u'abc'’, ‘r'abc'’, ‘ur'abc'’,
11951 ‘"abc"’, ‘u"abc"’, ‘r"abc"’, ‘ur"abc"’,
11952 ‘'''abc'''’, ‘u'''abc'''’, ‘r'''abc'''’, ‘ur'''abc'''’,
11953 ‘"""abc"""’, ‘u"""abc"""’, ‘r"""abc"""’, ‘ur"""abc"""’
11958 gettext/ngettext functions
11959 ‘gettext.gettext’, ‘gettext.dgettext’, ‘gettext.ngettext’,
11960 ‘gettext.dngettext’, also ‘ugettext’, ‘ungettext’
11963 ‘gettext.textdomain’ function, or ‘gettext.install(DOMAIN)’
11967 ‘gettext.bindtextdomain’ function, or
11968 ‘gettext.install(DOMAIN,LOCALEDIR)’ function
11971 not used by the gettext emulation
11976 Use or emulate GNU gettext
11982 Formatting with positions
11983 ‘'...%(ident)d...' % { 'ident': value }’
11991 An example is available in the ‘examples’ directory: ‘hello-python’.
11993 A note about format strings: Python supports format strings with
11994 unnamed arguments, such as ‘'...%d...'’, and format strings with named
11995 arguments, such as ‘'...%(ident)d...'’. The latter are preferable for
11996 internationalized programs, for two reasons:
11998 • When a format string takes more than one argument, the translator
11999 can provide a translation that uses the arguments in a different
12000 order, if the format string uses named arguments. For example, the
12001 translator can reformulate
12002 "'%(volume)s' has only %(freespace)d bytes free."
12004 "Only %(freespace)d bytes free on '%(volume)s'."
12005 Additionally, the identifiers also provide some context to the
12008 • In the context of plural forms, the format string used for the
12009 singular form does not use the numeric argument in many languages.
12010 Even in English, one prefers to write ‘"one hour"’ instead of ‘"1
12011 hour"’. Omitting individual arguments from format strings like
12012 this is only possible with the named argument syntax. (With
12013 unnamed arguments, Python – unlike C – verifies that the format
12014 string uses all supplied arguments.)
12017 File: gettext.info, Node: Common Lisp, Next: clisp C, Prev: Python, Up: List of Programming Languages
12019 15.5.5 GNU clisp - Common Lisp
12020 ------------------------------
12023 clisp 2.28 or newer
12032 ‘(_ "abc")’, ‘(ENGLISH "abc")’
12034 gettext/ngettext functions
12035 ‘i18n:gettext’, ‘i18n:ngettext’
12041 ‘i18n:textdomaindir’
12049 Use or emulate GNU gettext
12053 ‘xgettext -k_ -kENGLISH’
12055 Formatting with positions
12056 ‘format "~1@*~D ~0@*~D"’
12059 On platforms without gettext, no translation.
12064 An example is available in the ‘examples’ directory: ‘hello-clisp’.
12067 File: gettext.info, Node: clisp C, Next: Emacs Lisp, Prev: Common Lisp, Up: List of Programming Languages
12069 15.5.6 GNU clisp C sources
12070 --------------------------
12082 ‘ENGLISH ? "abc" : ""’
12086 gettext/ngettext functions
12087 ‘clgettext’, ‘clgettextl’
12099 ‘#include "lispbibl.c"’
12101 Use or emulate GNU gettext
12107 Formatting with positions
12108 ‘fprintf "%2$d %1$d"’
12111 On platforms without gettext, no translation.
12117 File: gettext.info, Node: Emacs Lisp, Next: librep, Prev: clisp C, Up: List of Programming Languages
12134 gettext/ngettext functions
12135 ‘gettext’, ‘dgettext’ (xemacs only)
12138 ‘domain’ special form (xemacs only)
12141 ‘bind-text-domain’ function (xemacs only)
12149 Use or emulate GNU gettext
12155 Formatting with positions
12156 ‘format "%2$d %1$d"’
12159 Only XEmacs. Without ‘I18N3’ defined at build time, no
12166 File: gettext.info, Node: librep, Next: Scheme, Prev: Emacs Lisp, Up: List of Programming Languages
12172 librep 0.15.3 or newer
12183 gettext/ngettext functions
12187 ‘textdomain’ function
12190 ‘bindtextdomain’ function
12196 ‘(require 'rep.i18n.gettext)’
12198 Use or emulate GNU gettext
12204 Formatting with positions
12205 ‘format "%2$d %1$d"’
12208 On platforms without gettext, no translation.
12213 An example is available in the ‘examples’ directory: ‘hello-librep’.
12216 File: gettext.info, Node: Scheme, Next: Smalltalk, Prev: librep, Up: List of Programming Languages
12218 15.5.9 GNU guile - Scheme
12219 -------------------------
12231 ‘(_ "abc")’, ‘_"abc"’ (GIMP script-fu extension)
12233 gettext/ngettext functions
12234 ‘gettext’, ‘ngettext’
12243 ‘(catch #t (lambda () (setlocale LC_ALL "")) (lambda args #f))’
12246 ‘(use-modules (ice-9 format))’
12248 Use or emulate GNU gettext
12254 Formatting with positions
12258 On platforms without gettext, no translation.
12263 An example is available in the ‘examples’ directory: ‘hello-guile’.
12266 File: gettext.info, Node: Smalltalk, Next: Java, Prev: Scheme, Up: List of Programming Languages
12268 15.5.10 GNU Smalltalk
12269 ---------------------
12283 gettext/ngettext functions
12284 ‘LcMessagesDomain>>#at:’, ‘LcMessagesDomain>>#at:plural:with:’
12287 ‘LcMessages>>#domain:localeDirectory:’ (returns a
12288 ‘LcMessagesDomain’ object).
12289 Example: ‘I18N Locale default messages domain: 'gettext'
12290 localeDirectory: /usr/local/share/locale'’
12293 ‘LcMessages>>#domain:localeDirectory:’, see above.
12296 Automatic if you use ‘I18N Locale default’.
12299 ‘PackageLoader fileInPackage: 'I18N'!’
12301 Use or emulate GNU gettext
12307 Formatting with positions
12308 ‘'%1 %2' bindWith: 'Hello' with: 'world'’
12316 An example is available in the ‘examples’ directory:
12320 File: gettext.info, Node: Java, Next: C#, Prev: Smalltalk, Up: List of Programming Languages
12337 gettext/ngettext functions
12338 ‘GettextResource.gettext’, ‘GettextResource.ngettext’,
12339 ‘GettextResource.pgettext’, ‘GettextResource.npgettext’
12342 —, use ‘ResourceBundle.getResource’ instead
12345 —, use CLASSPATH instead
12353 Use or emulate GNU gettext
12354 —, uses a Java specific message catalog format
12359 Formatting with positions
12360 ‘MessageFormat.format "{1,number} {0,number}"’
12368 Before marking strings as internationalizable, uses of the string
12369 concatenation operator need to be converted to ‘MessageFormat’
12370 applications. For example, ‘"file "+filename+" not found"’ becomes
12371 ‘MessageFormat.format("file {0} not found", new Object[] { filename })’.
12372 Only after this is done, can the strings be marked and extracted.
12374 GNU gettext uses the native Java internationalization mechanism,
12375 namely ‘ResourceBundle’s. There are two formats of ‘ResourceBundle’s:
12376 ‘.properties’ files and ‘.class’ files. The ‘.properties’ format is a
12377 text file which the translators can directly edit, like PO files, but
12378 which doesn’t support plural forms. Whereas the ‘.class’ format is
12379 compiled from ‘.java’ source code and can support plural forms (provided
12380 it is accessed through an appropriate API, see below).
12382 To convert a PO file to a ‘.properties’ file, the ‘msgcat’ program
12383 can be used with the option ‘--properties-output’. To convert a
12384 ‘.properties’ file back to a PO file, the ‘msgcat’ program can be used
12385 with the option ‘--properties-input’. All the tools that manipulate PO
12386 files can work with ‘.properties’ files as well, if given the
12387 ‘--properties-input’ and/or ‘--properties-output’ option.
12389 To convert a PO file to a ResourceBundle class, the ‘msgfmt’ program
12390 can be used with the option ‘--java’ or ‘--java2’. To convert a
12391 ResourceBundle back to a PO file, the ‘msgunfmt’ program can be used
12392 with the option ‘--java’.
12394 Two different programmatic APIs can be used to access
12395 ResourceBundles. Note that both APIs work with all kinds of
12396 ResourceBundles, whether GNU gettext generated classes, or other
12397 ‘.class’ or ‘.properties’ files.
12399 1. The ‘java.util.ResourceBundle’ API.
12401 In particular, its ‘getString’ function returns a string
12402 translation. Note that a missing translation yields a
12403 ‘MissingResourceException’.
12405 This has the advantage of being the standard API. And it does not
12406 require any additional libraries, only the ‘msgcat’ generated
12407 ‘.properties’ files or the ‘msgfmt’ generated ‘.class’ files. But
12408 it cannot do plural handling, even if the resource was generated by
12409 ‘msgfmt’ from a PO file with plural handling.
12411 2. The ‘gnu.gettext.GettextResource’ API.
12413 Reference documentation in Javadoc 1.1 style format is in the
12414 javadoc2 directory (javadoc2/index.html).
12416 Its ‘gettext’ function returns a string translation. Note that
12417 when a translation is missing, the MSGID argument is returned
12420 This has the advantage of having the ‘ngettext’ function for plural
12421 handling and the ‘pgettext’ and ‘npgettext’ for strings constraint
12422 to a particular context.
12424 To use this API, one needs the ‘libintl.jar’ file which is part of
12425 the GNU gettext package and distributed under the LGPL.
12427 Four examples, using the second API, are available in the ‘examples’
12428 directory: ‘hello-java’, ‘hello-java-awt’, ‘hello-java-swing’,
12429 ‘hello-java-qtjambi’.
12431 Now, to make use of the API and define a shorthand for ‘getString’,
12432 there are three idioms that you can choose from:
12434 • (This one assumes Java 1.5 or newer.) In a unique class of your
12435 project, say ‘Util’, define a static variable holding the
12436 ‘ResourceBundle’ instance and the shorthand:
12438 private static ResourceBundle myResources =
12439 ResourceBundle.getBundle("domain-name");
12440 public static String _(String s) {
12441 return myResources.getString(s);
12444 All classes containing internationalized strings then contain
12446 import static Util._;
12448 and the shorthand is used like this:
12450 System.out.println(_("Operation completed."));
12452 • In a unique class of your project, say ‘Util’, define a static
12453 variable holding the ‘ResourceBundle’ instance:
12455 public static ResourceBundle myResources =
12456 ResourceBundle.getBundle("domain-name");
12458 All classes containing internationalized strings then contain
12460 private static ResourceBundle res = Util.myResources;
12461 private static String _(String s) { return res.getString(s); }
12463 and the shorthand is used like this:
12465 System.out.println(_("Operation completed."));
12467 • You add a class with a very short name, say ‘S’, containing just
12468 the definition of the resource bundle and of the shorthand:
12471 public static ResourceBundle myResources =
12472 ResourceBundle.getBundle("domain-name");
12473 public static String _(String s) {
12474 return myResources.getString(s);
12478 and the shorthand is used like this:
12480 System.out.println(S._("Operation completed."));
12482 Which of the three idioms you choose, will depend on whether your
12483 project requires portability to Java versions prior to Java 1.5 and, if
12484 so, whether copying two lines of codes into every class is more
12485 acceptable in your project than a class with a single-letter name.
12488 File: gettext.info, Node: C#, Next: gawk, Prev: Java, Up: List of Programming Languages
12494 pnet, pnetlib 0.6.2 or newer, or mono 0.29 or newer
12505 gettext/ngettext functions
12506 ‘GettextResourceManager.GetString’,
12507 ‘GettextResourceManager.GetPluralString’
12508 ‘GettextResourceManager.GetParticularString’
12509 ‘GettextResourceManager.GetParticularPluralString’
12512 ‘new GettextResourceManager(domain)’
12515 —, compiled message catalogs are located in subdirectories of the
12516 directory containing the executable
12524 Use or emulate GNU gettext
12525 —, uses a C# specific message catalog format
12530 Formatting with positions
12531 ‘String.Format "{1} {0}"’
12539 Before marking strings as internationalizable, uses of the string
12540 concatenation operator need to be converted to ‘String.Format’
12541 invocations. For example, ‘"file "+filename+" not found"’ becomes
12542 ‘String.Format("file {0} not found", filename)’. Only after this is
12543 done, can the strings be marked and extracted.
12545 GNU gettext uses the native C#/.NET internationalization mechanism,
12546 namely the classes ‘ResourceManager’ and ‘ResourceSet’. Applications
12547 use the ‘ResourceManager’ methods to retrieve the native language
12548 translation of strings. An instance of ‘ResourceSet’ is the in-memory
12549 representation of a message catalog file. The ‘ResourceManager’ loads
12550 and accesses ‘ResourceSet’ instances as needed to look up the
12553 There are two formats of ‘ResourceSet’s that can be directly loaded
12554 by the C# runtime: ‘.resources’ files and ‘.dll’ files.
12556 • The ‘.resources’ format is a binary file usually generated through
12557 the ‘resgen’ or ‘monoresgen’ utility, but which doesn’t support
12558 plural forms. ‘.resources’ files can also be embedded in .NET
12559 ‘.exe’ files. This only affects whether a file system access is
12560 performed to load the message catalog; it doesn’t affect the
12561 contents of the message catalog.
12563 • On the other hand, the ‘.dll’ format is a binary file that is
12564 compiled from ‘.cs’ source code and can support plural forms
12565 (provided it is accessed through the GNU gettext API, see below).
12567 Note that these .NET ‘.dll’ and ‘.exe’ files are not tied to a
12568 particular platform; their file format and GNU gettext for C# can be
12569 used on any platform.
12571 To convert a PO file to a ‘.resources’ file, the ‘msgfmt’ program can
12572 be used with the option ‘--csharp-resources’. To convert a ‘.resources’
12573 file back to a PO file, the ‘msgunfmt’ program can be used with the
12574 option ‘--csharp-resources’. You can also, in some cases, use the
12575 ‘resgen’ program (from the ‘pnet’ package) or the ‘monoresgen’ program
12576 (from the ‘mono’/‘mcs’ package). These programs can also convert a
12577 ‘.resources’ file back to a PO file. But beware: as of this writing
12578 (January 2004), the ‘monoresgen’ converter is quite buggy and the
12579 ‘resgen’ converter ignores the encoding of the PO files.
12581 To convert a PO file to a ‘.dll’ file, the ‘msgfmt’ program can be
12582 used with the option ‘--csharp’. The result will be a ‘.dll’ file
12583 containing a subclass of ‘GettextResourceSet’, which itself is a
12584 subclass of ‘ResourceSet’. To convert a ‘.dll’ file containing a
12585 ‘GettextResourceSet’ subclass back to a PO file, the ‘msgunfmt’ program
12586 can be used with the option ‘--csharp’.
12588 The advantages of the ‘.dll’ format over the ‘.resources’ format are:
12590 1. Freedom to localize: Users can add their own translations to an
12591 application after it has been built and distributed. Whereas when
12592 the programmer uses a ‘ResourceManager’ constructor provided by the
12593 system, the set of ‘.resources’ files for an application must be
12594 specified when the application is built and cannot be extended
12597 2. Plural handling: A message catalog in ‘.dll’ format supports the
12598 plural handling function ‘GetPluralString’. Whereas ‘.resources’
12599 files can only contain data and only support lookups that depend on
12602 3. Context handling: A message catalog in ‘.dll’ format supports the
12603 query-with-context functions ‘GetParticularString’ and
12604 ‘GetParticularPluralString’. Whereas ‘.resources’ files can only
12605 contain data and only support lookups that depend on a single
12608 4. The ‘GettextResourceManager’ that loads the message catalogs in
12609 ‘.dll’ format also provides for inheritance on a per-message basis.
12610 For example, in Austrian (‘de_AT’) locale, translations from the
12611 German (‘de’) message catalog will be used for messages not found
12612 in the Austrian message catalog. This has the consequence that the
12613 Austrian translators need only translate those few messages for
12614 which the translation into Austrian differs from the German one.
12615 Whereas when working with ‘.resources’ files, each message catalog
12616 must provide the translations of all messages by itself.
12618 5. The ‘GettextResourceManager’ that loads the message catalogs in
12619 ‘.dll’ format also provides for a fallback: The English MSGID is
12620 returned when no translation can be found. Whereas when working
12621 with ‘.resources’ files, a language-neutral ‘.resources’ file must
12622 explicitly be provided as a fallback.
12624 On the side of the programmatic APIs, the programmer can use either
12625 the standard ‘ResourceManager’ API and the GNU ‘GettextResourceManager’
12626 API. The latter is an extension of the former, because
12627 ‘GettextResourceManager’ is a subclass of ‘ResourceManager’.
12629 1. The ‘System.Resources.ResourceManager’ API.
12631 This API works with resources in ‘.resources’ format.
12633 The creation of the ‘ResourceManager’ is done through
12634 new ResourceManager(domainname, Assembly.GetExecutingAssembly())
12636 The ‘GetString’ function returns a string’s translation. Note that
12637 this function returns null when a translation is missing (i.e. not
12638 even found in the fallback resource file).
12640 2. The ‘GNU.Gettext.GettextResourceManager’ API.
12642 This API works with resources in ‘.dll’ format.
12644 Reference documentation is in the csharpdoc directory
12645 (csharpdoc/index.html).
12647 The creation of the ‘ResourceManager’ is done through
12648 new GettextResourceManager(domainname)
12650 The ‘GetString’ function returns a string’s translation. Note that
12651 when a translation is missing, the MSGID argument is returned
12654 The ‘GetPluralString’ function returns a string translation with
12655 plural handling, like the ‘ngettext’ function in C.
12657 The ‘GetParticularString’ function returns a string’s translation,
12658 specific to a particular context, like the ‘pgettext’ function in
12659 C. Note that when a translation is missing, the MSGID argument is
12660 returned unchanged.
12662 The ‘GetParticularPluralString’ function returns a string
12663 translation, specific to a particular context, with plural
12664 handling, like the ‘npgettext’ function in C.
12666 To use this API, one needs the ‘GNU.Gettext.dll’ file which is part
12667 of the GNU gettext package and distributed under the LGPL.
12669 You can also mix both approaches: use the
12670 ‘GNU.Gettext.GettextResourceManager’ constructor, but otherwise use only
12671 the ‘ResourceManager’ type and only the ‘GetString’ method. This is
12672 appropriate when you want to profit from the tools for PO files, but
12673 don’t want to change an existing source code that uses ‘ResourceManager’
12674 and don’t (yet) need the ‘GetPluralString’ method.
12676 Two examples, using the second API, are available in the ‘examples’
12677 directory: ‘hello-csharp’, ‘hello-csharp-forms’.
12679 Now, to make use of the API and define a shorthand for ‘GetString’,
12680 there are two idioms that you can choose from:
12682 • In a unique class of your project, say ‘Util’, define a static
12683 variable holding the ‘ResourceManager’ instance:
12685 public static GettextResourceManager MyResourceManager =
12686 new GettextResourceManager("domain-name");
12688 All classes containing internationalized strings then contain
12690 private static GettextResourceManager Res = Util.MyResourceManager;
12691 private static String _(String s) { return Res.GetString(s); }
12693 and the shorthand is used like this:
12695 Console.WriteLine(_("Operation completed."));
12697 • You add a class with a very short name, say ‘S’, containing just
12698 the definition of the resource manager and of the shorthand:
12701 public static GettextResourceManager MyResourceManager =
12702 new GettextResourceManager("domain-name");
12703 public static String _(String s) {
12704 return MyResourceManager.GetString(s);
12708 and the shorthand is used like this:
12710 Console.WriteLine(S._("Operation completed."));
12712 Which of the two idioms you choose, will depend on whether copying
12713 two lines of codes into every class is more acceptable in your project
12714 than a class with a single-letter name.
12717 File: gettext.info, Node: gawk, Next: Pascal, Prev: C#, Up: List of Programming Languages
12726 ‘awk’, ‘gawk’, ‘twjr’. The file extension ‘twjr’ is used by
12727 TexiWeb Jr (<https://github.com/arnoldrobbins/texiwebjr>).
12735 gettext/ngettext functions
12736 ‘dcgettext’, missing ‘dcngettext’ in gawk-3.1.0
12739 ‘TEXTDOMAIN’ variable
12742 ‘bindtextdomain’ function
12745 automatic, but missing ‘setlocale (LC_MESSAGES, "")’ in gawk-3.1.0
12750 Use or emulate GNU gettext
12756 Formatting with positions
12757 ‘printf "%2$d %1$d"’ (GNU awk only)
12760 On platforms without gettext, no translation. On non-GNU awks, you
12761 must define ‘dcgettext’, ‘dcngettext’ and ‘bindtextdomain’
12767 An example is available in the ‘examples’ directory: ‘hello-gawk’.
12770 File: gettext.info, Node: Pascal, Next: wxWidgets, Prev: gawk, Up: List of Programming Languages
12772 15.5.14 Pascal - Free Pascal Compiler
12773 -------------------------------------
12787 gettext/ngettext functions
12788 —, use ‘ResourceString’ data type instead
12791 —, use ‘TranslateResourceStrings’ function instead
12794 —, use ‘TranslateResourceStrings’ function instead
12797 automatic, but uses only LANG, not LC_MESSAGES or LC_ALL
12800 ‘{$mode delphi}’ or ‘{$mode objfpc}’
12803 Use or emulate GNU gettext
12807 ‘ppc386’ followed by ‘xgettext’ or ‘rstconv’
12809 Formatting with positions
12811 ‘format "%1:d %0:d"’
12819 The Pascal compiler has special support for the ‘ResourceString’ data
12820 type. It generates a ‘.rst’ file. This is then converted to a ‘.pot’
12821 file by use of ‘xgettext’ or ‘rstconv’. At runtime, a ‘.mo’ file
12822 corresponding to translations of this ‘.pot’ file can be loaded using
12823 the ‘TranslateResourceStrings’ function in the ‘gettext’ unit.
12825 An example is available in the ‘examples’ directory: ‘hello-pascal’.
12828 File: gettext.info, Node: wxWidgets, Next: YCP, Prev: Pascal, Up: List of Programming Languages
12830 15.5.15 wxWidgets library
12831 -------------------------
12845 gettext/ngettext functions
12846 ‘wxLocale::GetString’, ‘wxGetTranslation’
12849 ‘wxLocale::AddCatalog’
12852 ‘wxLocale::AddCatalogLookupPathPrefix’
12855 ‘wxLocale::Init’, ‘wxSetLocale’
12858 ‘#include <wx/intl.h>’
12860 Use or emulate GNU gettext
12861 emulate, see ‘include/wx/intl.h’ and ‘src/common/intl.cpp’
12866 Formatting with positions
12867 wxString::Format supports positions if and only if the system has
12868 ‘wprintf()’, ‘vswprintf()’ functions and they support positions
12869 according to POSIX.
12878 File: gettext.info, Node: YCP, Next: Tcl, Prev: wxWidgets, Up: List of Programming Languages
12880 15.5.16 YCP - YaST2 scripting language
12881 --------------------------------------
12884 libycp, libycp-devel, yast2-core, yast2-core-devel
12895 gettext/ngettext functions
12896 ‘_()’ with 1 or 3 arguments
12899 ‘textdomain’ statement
12910 Use or emulate GNU gettext
12916 Formatting with positions
12925 An example is available in the ‘examples’ directory: ‘hello-ycp’.
12928 File: gettext.info, Node: Tcl, Next: Perl, Prev: YCP, Up: List of Programming Languages
12930 15.5.17 Tcl - Tk’s scripting language
12931 -------------------------------------
12945 gettext/ngettext functions
12952 —, use ‘::msgcat::mcload’ instead
12955 automatic, uses LANG, but ignores LC_MESSAGES and LC_ALL
12958 ‘package require msgcat’
12959 ‘proc _ {s} {return [::msgcat::mc $s]}’
12961 Use or emulate GNU gettext
12962 —, uses a Tcl specific message catalog format
12967 Formatting with positions
12968 ‘format "%2\$d %1\$d"’
12976 Two examples are available in the ‘examples’ directory: ‘hello-tcl’,
12979 Before marking strings as internationalizable, substitutions of
12980 variables into the string need to be converted to ‘format’ applications.
12981 For example, ‘"file $filename not found"’ becomes ‘[format "file %s not
12982 found" $filename]’. Only after this is done, can the strings be marked
12983 and extracted. After marking, this example becomes ‘[format [_ "file %s
12984 not found"] $filename]’ or ‘[msgcat::mc "file %s not found" $filename]’.
12985 Note that the ‘msgcat::mc’ function implicitly calls ‘format’ when more
12986 than one argument is given.
12989 File: gettext.info, Node: Perl, Next: PHP, Prev: Tcl, Up: List of Programming Languages
12998 ‘pl’, ‘PL’, ‘pm’, ‘perl’, ‘cgi’
13014 • ‘/pattern match/’
13016 • ‘?pattern match?’
13018 • ‘s/substitution/operators/’
13020 • ‘$tied_hash{"message"}’
13022 • ‘$tied_hash_reference->{"message"}’
13024 • etc., issue the command ‘man perlsyn’ for details
13027 ‘__’ (double underscore)
13029 gettext/ngettext functions
13030 ‘gettext’, ‘dgettext’, ‘dcgettext’, ‘ngettext’, ‘dngettext’,
13034 ‘textdomain’ function
13037 ‘bindtextdomain’ function
13039 bind_textdomain_codeset
13040 ‘bind_textdomain_codeset’ function
13043 Use ‘setlocale (LC_ALL, "");’
13047 ‘use Locale::TextDomain;’ (included in the package libintl-perl
13048 which is available on the Comprehensive Perl Archive Network CPAN,
13049 http://www.cpan.org/).
13051 Use or emulate GNU gettext
13052 platform dependent: gettext_pp emulates, gettext_xs uses GNU
13056 ‘xgettext -k__ -k\$__ -k%__ -k__x -k__n:1,2 -k__nx:1,2 -k__xn:1,2
13059 Formatting with positions
13060 Both kinds of format strings support formatting with positions.
13061 ‘printf "%2\$d %1\$d", ...’ (requires Perl 5.8.0 or newer)
13062 ‘__expand("[new] replaces [old]", old => $oldvalue, new =>
13066 The ‘libintl-perl’ package is platform independent but is not part
13067 of the Perl core. The programmer is responsible for providing a
13068 dummy implementation of the required functions if the package is
13069 not installed on the target system.
13075 Included in ‘libintl-perl’, available on CPAN
13076 (http://www.cpan.org/).
13078 An example is available in the ‘examples’ directory: ‘hello-perl’.
13080 The ‘xgettext’ parser backend for Perl differs significantly from the
13081 parser backends for other programming languages, just as Perl itself
13082 differs significantly from other programming languages. The Perl parser
13083 backend offers many more string marking facilities than the other
13084 backends but it also has some Perl specific limitations, the worst
13085 probably being its imperfectness.
13089 * General Problems:: General Problems Parsing Perl Code
13090 * Default Keywords:: Which Keywords Will xgettext Look For?
13091 * Special Keywords:: How to Extract Hash Keys
13092 * Quote-like Expressions:: What are Strings And Quote-like Expressions?
13093 * Interpolation I:: Invalid String Interpolation
13094 * Interpolation II:: Valid String Interpolation
13095 * Parentheses:: When To Use Parentheses
13096 * Long Lines:: How To Grok with Long Lines
13097 * Perl Pitfalls:: Bugs, Pitfalls, and Things That Do Not Work
13100 File: gettext.info, Node: General Problems, Next: Default Keywords, Prev: Perl, Up: Perl
13102 15.5.18.1 General Problems Parsing Perl Code
13103 ............................................
13105 It is often heard that only Perl can parse Perl. This is not true.
13106 Perl cannot be _parsed_ at all, it can only be _executed_. Perl has
13107 various built-in ambiguities that can only be resolved at runtime.
13109 The following example may illustrate one common problem:
13111 print gettext "Hello World!";
13113 Although this example looks like a bullet-proof case of a function
13114 invocation, it is not:
13116 open gettext, ">testfile" or die;
13117 print gettext "Hello world!"
13119 In this context, the string ‘gettext’ looks more like a file handle.
13120 But not necessarily:
13122 use Locale::Messages qw (:libintl_h);
13123 open gettext ">testfile" or die;
13124 print gettext "Hello world!";
13126 Now, the file is probably syntactically incorrect, provided that the
13127 module ‘Locale::Messages’ found first in the Perl include path exports a
13128 function ‘gettext’. But what if the module ‘Locale::Messages’ really
13131 use vars qw (*gettext);
13135 In this case, the string ‘gettext’ will be interpreted as a file
13136 handle again, and the above example will create a file ‘testfile’ and
13137 write the string “Hello world!” into it. Even advanced control flow
13138 analysis will not really help:
13145 print gettext "Hello world!";
13147 If the module ‘Sane’ exports a function ‘gettext’ that does what we
13148 expect, and the module ‘InSane’ opens a file for writing and associates
13149 the _handle_ ‘gettext’ with this output stream, we are clueless again
13150 about what will happen at runtime. It is completely unpredictable. The
13151 truth is that Perl has so many ways to fill its symbol table at runtime
13152 that it is impossible to interpret a particular piece of code without
13155 Of course, ‘xgettext’ will not execute your Perl sources while
13156 scanning for translatable strings, but rather use heuristics in order to
13157 guess what you meant.
13159 Another problem is the ambiguity of the slash and the question mark.
13160 Their interpretation depends on the context:
13163 print "OK\n" if /foobar/;
13168 # Another pattern match.
13169 print "OK\n" if ?foobar?;
13172 print $x ? "foo" : "bar";
13174 The slash may either act as the division operator or introduce a
13175 pattern match, whereas the question mark may act as the ternary
13176 conditional operator or as a pattern match, too. Other programming
13177 languages like ‘awk’ present similar problems, but the consequences of a
13178 misinterpretation are particularly nasty with Perl sources. In ‘awk’
13179 for instance, a statement can never exceed one line and the parser can
13180 recover from a parsing error at the next newline and interpret the rest
13181 of the input stream correctly. Perl is different, as a pattern match is
13182 terminated by the next appearance of the delimiter (the slash or the
13183 question mark) in the input stream, regardless of the semantic context.
13184 If a slash is really a division sign but mis-interpreted as a pattern
13185 match, the rest of the input file is most probably parsed incorrectly.
13187 There are certain cases, where the ambiguity cannot be resolved at
13190 $x = wantarray ? 1 : 0;
13192 The Perl built-in function ‘wantarray’ does not accept any arguments.
13193 The Perl parser therefore knows that the question mark does not start a
13194 regular expression but is the ternary conditional operator.
13197 $x = wantarrays ? 1 : 0;
13199 Now the situation is different. The function ‘wantarrays’ takes a
13200 variable number of arguments (like any non-prototyped Perl function).
13201 The question mark is now the delimiter of a pattern match, and hence the
13202 piece of code does not compile.
13204 sub wantarrays() {}
13205 $x = wantarrays ? 1 : 0;
13207 Now the function is prototyped, Perl knows that it does not accept
13208 any arguments, and the question mark is therefore interpreted as the
13209 ternaray operator again. But that unfortunately outsmarts ‘xgettext’.
13211 The Perl parser in ‘xgettext’ cannot know whether a function has a
13212 prototype and what that prototype would look like. It therefore makes
13213 an educated guess. If a function is known to be a Perl built-in and
13214 this function does not accept any arguments, a following question mark
13215 or slash is treated as an operator, otherwise as the delimiter of a
13216 following regular expression. The Perl built-ins that do not accept
13217 arguments are ‘wantarray’, ‘fork’, ‘time’, ‘times’, ‘getlogin’,
13218 ‘getppid’, ‘getpwent’, ‘getgrent’, ‘gethostent’, ‘getnetent’,
13219 ‘getprotoent’, ‘getservent’, ‘setpwent’, ‘setgrent’, ‘endpwent’,
13220 ‘endgrent’, ‘endhostent’, ‘endnetent’, ‘endprotoent’, and ‘endservent’.
13222 If you find that ‘xgettext’ fails to extract strings from portions of
13223 your sources, you should therefore look out for slashes and/or question
13224 marks preceding these sections. You may have come across a bug in
13225 ‘xgettext’’s Perl parser (and of course you should report that bug). In
13226 the meantime you should consider to reformulate your code in a manner
13227 less challenging to ‘xgettext’.
13229 In particular, if the parser is too dumb to see that a function does
13230 not accept arguments, use parentheses:
13232 $x = somefunc() ? 1 : 0;
13233 $y = (somefunc) ? 1 : 0;
13235 In fact the Perl parser itself has similar problems and warns you
13236 about such constructs.
13239 File: gettext.info, Node: Default Keywords, Next: Special Keywords, Prev: General Problems, Up: Perl
13241 15.5.18.2 Which keywords will xgettext look for?
13242 ................................................
13244 Unless you instruct ‘xgettext’ otherwise by invoking it with one of
13245 the options ‘--keyword’ or ‘-k’, it will recognize the following
13246 keywords in your Perl sources:
13256 The first (singular) and the second (plural) argument will be
13261 The first (singular) and the second (plural) argument will be
13266 The first (singular) and the second (plural) argument will be
13273 The keys of lookups into the hash ‘%gettext’ will be extracted.
13277 The keys of lookups into the hash reference ‘$gettext’ will be
13281 File: gettext.info, Node: Special Keywords, Next: Quote-like Expressions, Prev: Default Keywords, Up: Perl
13283 15.5.18.3 How to Extract Hash Keys
13284 ..................................
13286 Translating messages at runtime is normally performed by looking up
13287 the original string in the translation database and returning the
13288 translated version. The “natural” Perl implementation is a hash lookup,
13289 and, of course, ‘xgettext’ supports such practice.
13291 print __"Hello world!";
13292 print $__{"Hello world!"};
13293 print $__->{"Hello world!"};
13294 print $$__{"Hello world!"};
13296 The above four lines all do the same thing. The Perl module
13297 ‘Locale::TextDomain’ exports by default a hash ‘%__’ that is tied to the
13298 function ‘__()’. It also exports a reference ‘$__’ to ‘%__’.
13300 If an argument to the ‘xgettext’ option ‘--keyword’, resp. ‘-k’
13301 starts with a percent sign, the rest of the keyword is interpreted as
13302 the name of a hash. If it starts with a dollar sign, the rest of the
13303 keyword is interpreted as a reference to a hash.
13305 Note that you can omit the quotation marks (single or double) around
13306 the hash key (almost) whenever Perl itself allows it:
13308 print $gettext{Error};
13310 The exact rule is: You can omit the surrounding quotes, when the hash
13311 key is a valid C (!) identifier, i.e. when it starts with an underscore
13312 or an ASCII letter and is followed by an arbitrary number of
13313 underscores, ASCII letters or digits. Other Unicode characters are
13314 _not_ allowed, regardless of the ‘use utf8’ pragma.
13317 File: gettext.info, Node: Quote-like Expressions, Next: Interpolation I, Prev: Special Keywords, Up: Perl
13319 15.5.18.4 What are Strings And Quote-like Expressions?
13320 ......................................................
13322 Perl offers a plethora of different string constructs. Those that
13323 can be used either as arguments to functions or inside braces for hash
13324 lookups are generally supported by ‘xgettext’.
13326 • *double-quoted strings*
13327 print gettext "Hello World!";
13329 • *single-quoted strings*
13330 print gettext 'Hello World!';
13332 • *the operator qq*
13333 print gettext qq |Hello World!|;
13334 print gettext qq <E-mail: <guido\@imperia.net>>;
13336 The operator ‘qq’ is fully supported. You can use arbitrary
13337 delimiters, including the four bracketing delimiters (round, angle,
13338 square, curly) that nest.
13341 print gettext q |Hello World!|;
13342 print gettext q <E-mail: <guido@imperia.net>>;
13344 The operator ‘q’ is fully supported. You can use arbitrary
13345 delimiters, including the four bracketing delimiters (round, angle,
13346 square, curly) that nest.
13348 • *the operator qx*
13349 print gettext qx ;LANGUAGE=C /bin/date;
13350 print gettext qx [/usr/bin/ls | grep '^[A-Z]*'];
13352 The operator ‘qx’ is fully supported. You can use arbitrary
13353 delimiters, including the four bracketing delimiters (round, angle,
13354 square, curly) that nest.
13356 The example is actually a useless use of ‘gettext’. It will invoke
13357 the ‘gettext’ function on the output of the command specified with
13358 the ‘qx’ operator. The feature was included in order to make the
13359 interface consistent (the parser will extract all strings and
13360 quote-like expressions).
13363 print gettext <<'EOF';
13364 program not found in $PATH
13367 print ngettext <<EOF, <<"EOF";
13370 several files deleted
13373 Here-documents are recognized. If the delimiter is enclosed in
13374 single quotes, the string is not interpolated. If it is enclosed
13375 in double quotes or has no quotes at all, the string is
13378 Delimiters that start with a digit are not supported!
13381 File: gettext.info, Node: Interpolation I, Next: Interpolation II, Prev: Quote-like Expressions, Up: Perl
13383 15.5.18.5 Invalid Uses Of String Interpolation
13384 ..............................................
13386 Perl is capable of interpolating variables into strings. This offers
13387 some nice features in localized programs but can also lead to problems.
13389 A common error is a construct like the following:
13391 print gettext "This is the program $0!\n";
13393 Perl will interpolate at runtime the value of the variable ‘$0’ into
13394 the argument of the ‘gettext()’ function. Hence, this argument is not a
13395 string constant but a variable argument (‘$0’ is a global variable that
13396 holds the name of the Perl script being executed). The interpolation is
13397 performed by Perl before the string argument is passed to ‘gettext()’
13398 and will therefore depend on the name of the script which can only be
13399 determined at runtime. Consequently, it is almost impossible that a
13400 translation can be looked up at runtime (except if, by accident, the
13401 interpolated string is found in the message catalog).
13403 The ‘xgettext’ program will therefore terminate parsing with a fatal
13404 error if it encounters a variable inside of an extracted string. In
13405 general, this will happen for all kinds of string interpolations that
13406 cannot be safely performed at compile time. If you absolutely know what
13407 you are doing, you can always circumvent this behavior:
13409 my $know_what_i_am_doing = "This is program $0!\n";
13410 print gettext $know_what_i_am_doing;
13412 Since the parser only recognizes strings and quote-like expressions,
13413 but not variables or other terms, the above construct will be accepted.
13414 You will have to find another way, however, to let your original string
13415 make it into your message catalog.
13417 If invoked with the option ‘--extract-all’, resp. ‘-a’, variable
13418 interpolation will be accepted. Rationale: You will generally use this
13419 option in order to prepare your sources for internationalization.
13421 Please see the manual page ‘man perlop’ for details of strings and
13422 quote-like expressions that are subject to interpolation and those that
13423 are not. Safe interpolations (that will not lead to a fatal error) are:
13425 • the escape sequences ‘\t’ (tab, HT, TAB), ‘\n’ (newline, NL), ‘\r’
13426 (return, CR), ‘\f’ (form feed, FF), ‘\b’ (backspace, BS), ‘\a’
13427 (alarm, bell, BEL), and ‘\e’ (escape, ESC).
13429 • octal chars, like ‘\033’
13430 Note that octal escapes in the range of 400-777 are translated into
13431 a UTF-8 representation, regardless of the presence of the ‘use
13434 • hex chars, like ‘\x1b’
13436 • wide hex chars, like ‘\x{263a}’
13437 Note that this escape is translated into a UTF-8 representation,
13438 regardless of the presence of the ‘use utf8’ pragma.
13440 • control chars, like ‘\c[’ (CTRL-[)
13442 • named Unicode chars, like ‘\N{LATIN CAPITAL LETTER C WITH CEDILLA}’
13444 Note that this escape is translated into a UTF-8 representation,
13445 regardless of the presence of the ‘use utf8’ pragma.
13447 The following escapes are considered partially safe:
13449 • ‘\l’ lowercase next char
13451 • ‘\u’ uppercase next char
13453 • ‘\L’ lowercase till \E
13455 • ‘\U’ uppercase till \E
13457 • ‘\E’ end case modification
13459 • ‘\Q’ quote non-word characters till \E
13461 These escapes are only considered safe if the string consists of
13462 ASCII characters only. Translation of characters outside the range
13463 defined by ASCII is locale-dependent and can actually only be performed
13464 at runtime; ‘xgettext’ doesn’t do these locale-dependent translations at
13467 Except for the modifier ‘\Q’, these translations, albeit valid, are
13468 generally useless and only obfuscate your sources. If a translation can
13469 be safely performed at compile time you can just as well write what you
13473 File: gettext.info, Node: Interpolation II, Next: Parentheses, Prev: Interpolation I, Up: Perl
13475 15.5.18.6 Valid Uses Of String Interpolation
13476 ............................................
13478 Perl is often used to generate sources for other programming
13479 languages or arbitrary file formats. Web applications that output HTML
13480 code make a prominent example for such usage.
13482 You will often come across situations where you want to intersperse
13483 code written in the target (programming) language with translatable
13484 messages, like in the following HTML example:
13486 print gettext <<EOF;
13487 <h1>My Homepage</h1>
13488 <script language="JavaScript"><!--
13489 for (i = 0; i < 100; ++i) {
13490 alert ("Thank you so much for visiting my homepage!");
13495 The parser will extract the entire here document, and it will appear
13496 entirely in the resulting PO file, including the JavaScript snippet
13497 embedded in the HTML code. If you exaggerate with constructs like the
13498 above, you will run the risk that the translators of your package will
13499 look out for a less challenging project. You should consider an
13500 alternative expression here:
13503 <h1>$gettext{"My Homepage"}</h1>
13504 <script language="JavaScript"><!--
13505 for (i = 0; i < 100; ++i) {
13506 alert ("$gettext{'Thank you so much for visiting my homepage!'}");
13511 Only the translatable portions of the code will be extracted here,
13512 and the resulting PO file will begrudgingly improve in terms of
13515 You can interpolate hash lookups in all strings or quote-like
13516 expressions that are subject to interpolation (see the manual page ‘man
13517 perlop’ for details). Double interpolation is invalid, however:
13519 # TRANSLATORS: Replace "the earth" with the name of your planet.
13520 print gettext qq{Welcome to $gettext->{"the earth"}};
13522 The ‘qq’-quoted string is recognized as an argument to ‘xgettext’ in
13523 the first place, and checked for invalid variable interpolation. The
13524 dollar sign of hash-dereferencing will therefore terminate the parser
13525 with an “invalid interpolation” error.
13527 It is valid to interpolate hash lookups in regular expressions:
13529 if ($var =~ /$gettext{"the earth"}/) {
13530 print gettext "Match!\n";
13532 s/$gettext{"U. S. A."}/$gettext{"U. S. A."} $gettext{"(dial +0)"}/g;
13535 File: gettext.info, Node: Parentheses, Next: Long Lines, Prev: Interpolation II, Up: Perl
13537 15.5.18.7 When To Use Parentheses
13538 .................................
13540 In Perl, parentheses around function arguments are mostly optional.
13541 ‘xgettext’ will always assume that all recognized keywords (except for
13542 hashes and hash references) are names of properly prototyped functions,
13543 and will (hopefully) only require parentheses where Perl itself requires
13544 them. All constructs in the following example are therefore ok to use:
13546 print gettext ("Hello World!\n");
13547 print gettext "Hello World!\n";
13548 print dgettext ($package => "Hello World!\n");
13549 print dgettext $package, "Hello World!\n";
13551 # The "fat comma" => turns the left-hand side argument into a
13552 # single-quoted string!
13553 print dgettext smellovision => "Hello World!\n";
13555 # The following assignment only works with prototyped functions.
13556 # Otherwise, the functions will act as "greedy" list operators and
13557 # eat up all following arguments.
13558 my $anonymous_hash = {
13559 planet => gettext "earth",
13560 cakes => ngettext "one cake", "several cakes", $n,
13563 # The same without fat comma:
13565 'planet', gettext "earth",
13566 'cakes', ngettext "one cake", "several cakes", $n,
13570 # Parentheses are only significant for the first argument.
13571 print dngettext 'package', ("one cake", "several cakes", $n), $discarded;
13574 File: gettext.info, Node: Long Lines, Next: Perl Pitfalls, Prev: Parentheses, Up: Perl
13576 15.5.18.8 How To Grok with Long Lines
13577 .....................................
13579 The necessity of long messages can often lead to a cumbersome or
13580 unreadable coding style. Perl has several options that may prevent you
13581 from writing unreadable code, and ‘xgettext’ does its best to do
13582 likewise. This is where the dot operator (the string concatenation
13583 operator) may come in handy:
13585 print gettext ("This is a very long"
13586 . " message that is still"
13587 . " readable, because"
13588 . " it is split into"
13589 . " multiple lines.\n");
13591 Perl is smart enough to concatenate these constant string fragments
13592 into one long string at compile time, and so is ‘xgettext’. You will
13593 only find one long message in the resulting POT file.
13595 Note that the future Perl 6 will probably use the underscore (‘_’) as
13596 the string concatenation operator, and the dot (‘.’) for dereferencing.
13597 This new syntax is not yet supported by ‘xgettext’.
13599 If embedded newline characters are not an issue, or even desired, you
13600 may also insert newline characters inside quoted strings wherever you
13603 print gettext ("<em>In HTML output
13604 embedded newlines are generally no
13605 problem, since adjacent whitespace
13606 is always rendered into a single
13607 space character.</em>");
13609 You may also consider to use here documents:
13611 print gettext <<EOF;
13613 embedded newlines are generally no
13614 problem, since adjacent whitespace
13615 is always rendered into a single
13616 space character.</em>
13619 Please do not forget that the line breaks are real, i.e. they
13620 translate into newline characters that will consequently show up in the
13621 resulting POT file.
13624 File: gettext.info, Node: Perl Pitfalls, Prev: Long Lines, Up: Perl
13626 15.5.18.9 Bugs, Pitfalls, And Things That Do Not Work
13627 .....................................................
13629 The foregoing sections should have proven that ‘xgettext’ is quite
13630 smart in extracting translatable strings from Perl sources. Yet, some
13631 more or less exotic constructs that could be expected to work, actually
13634 One of the more relevant limitations can be found in the
13635 implementation of variable interpolation inside quoted strings. Only
13636 simple hash lookups can be used there:
13639 $gettext{"The dot operator"
13642 Likewise, you cannot @{[ gettext ("interpolate function calls") ]}
13643 inside quoted strings or quote-like expressions.
13646 This is valid Perl code and will actually trigger invocations of the
13647 ‘gettext’ function at runtime. Yet, the Perl parser in ‘xgettext’ will
13648 fail to recognize the strings. A less obvious example can be found in
13649 the interpolation of regular expressions:
13651 s/<!--START_OF_WEEK-->/gettext ("Sunday")/e;
13653 The modifier ‘e’ will cause the substitution to be interpreted as an
13654 evaluable statement. Consequently, at runtime the function ‘gettext()’
13655 is called, but again, the parser fails to extract the string “Sunday”.
13656 Use a temporary variable as a simple workaround if you really happen to
13659 my $sunday = gettext "Sunday";
13660 s/<!--START_OF_WEEK-->/$sunday/;
13662 Hash slices would also be handy but are not recognized:
13664 my @weekdays = @gettext{'Sunday', 'Monday', 'Tuesday', 'Wednesday',
13665 'Thursday', 'Friday', 'Saturday'};
13667 @weekdays = @gettext{qw (Sunday Monday Tuesday Wednesday Thursday
13668 Friday Saturday) };
13670 This is perfectly valid usage of the tied hash ‘%gettext’ but the
13671 strings are not recognized and therefore will not be extracted.
13673 Another caveat of the current version is its rudimentary support for
13674 non-ASCII characters in identifiers. You may encounter serious problems
13675 if you use identifiers with characters outside the range of ’A’-’Z’,
13676 ’a’-’z’, ’0’-’9’ and the underscore ’_’.
13678 Maybe some of these missing features will be implemented in future
13679 versions, but since you can always make do without them at minimal
13680 effort, these todos have very low priority.
13682 A nasty problem are brace format strings that already contain braces
13683 as part of the normal text, for example the usage strings typically
13684 encountered in programs:
13686 die "usage: $0 {OPTIONS} FILENAME...\n";
13688 If you want to internationalize this code with Perl brace format
13689 strings, you will run into a problem:
13691 die __x ("usage: {program} {OPTIONS} FILENAME...\n", program => $0);
13693 Whereas ‘{program}’ is a placeholder, ‘{OPTIONS}’ is not and should
13694 probably be translated. Yet, there is no way to teach the Perl parser
13695 in ‘xgettext’ to recognize the first one, and leave the other one alone.
13697 There are two possible work-arounds for this problem. If you are
13698 sure that your program will run under Perl 5.8.0 or newer (these Perl
13699 versions handle positional parameters in ‘printf()’) or if you are sure
13700 that the translator will not have to reorder the arguments in her
13701 translation – for example if you have only one brace placeholder in your
13702 string, or if it describes a syntax, like in this one –, you can mark
13703 the string as ‘no-perl-brace-format’ and use ‘printf()’:
13705 # xgettext: no-perl-brace-format
13706 die sprintf ("usage: %s {OPTIONS} FILENAME...\n", $0);
13708 If you want to use the more portable Perl brace format, you will have
13709 to do put placeholders in place of the literal braces:
13711 die __x ("usage: {program} {[}OPTIONS{]} FILENAME...\n",
13712 program => $0, '[' => '{', ']' => '}');
13714 Perl brace format strings know no escaping mechanism. No matter how
13715 this escaping mechanism looked like, it would either give the programmer
13716 a hard time, make translating Perl brace format strings heavy-going, or
13717 result in a performance penalty at runtime, when the format directives
13718 get executed. Most of the time you will happily get along with
13719 ‘printf()’ for this special case.
13722 File: gettext.info, Node: PHP, Next: Pike, Prev: Perl, Up: List of Programming Languages
13724 15.5.19 PHP Hypertext Preprocessor
13725 ----------------------------------
13728 mod_php4, mod_php4-core, phpdoc
13731 ‘php’, ‘php3’, ‘php4’
13739 gettext/ngettext functions
13740 ‘gettext’, ‘dgettext’, ‘dcgettext’; starting with PHP 4.2.0 also
13741 ‘ngettext’, ‘dngettext’, ‘dcngettext’
13744 ‘textdomain’ function
13747 ‘bindtextdomain’ function
13750 Programmer must call ‘setlocale (LC_ALL, "")’
13755 Use or emulate GNU gettext
13761 Formatting with positions
13762 ‘printf "%2\$d %1\$d"’
13765 On platforms without gettext, the functions are not available.
13770 An example is available in the ‘examples’ directory: ‘hello-php’.
13773 File: gettext.info, Node: Pike, Next: GCC-source, Prev: PHP, Up: List of Programming Languages
13790 gettext/ngettext functions
13791 ‘gettext’, ‘dgettext’, ‘dcgettext’
13794 ‘textdomain’ function
13797 ‘bindtextdomain’ function
13800 ‘setlocale’ function
13803 ‘import Locale.Gettext;’
13805 Use or emulate GNU gettext
13811 Formatting with positions
13815 On platforms without gettext, the functions are not available.
13821 File: gettext.info, Node: GCC-source, Next: Lua, Prev: Pike, Up: List of Programming Languages
13823 15.5.21 GNU Compiler Collection sources
13824 ---------------------------------------
13838 gettext/ngettext functions
13839 ‘gettext’, ‘dgettext’, ‘dcgettext’, ‘ngettext’, ‘dngettext’,
13843 ‘textdomain’ function
13846 ‘bindtextdomain’ function
13849 Programmer must call ‘setlocale (LC_ALL, "")’
13852 ‘#include "intl.h"’
13854 Use or emulate GNU gettext
13860 Formatting with positions
13864 Uses autoconf macros
13870 File: gettext.info, Node: Lua, Next: JavaScript, Prev: GCC-source, Up: List of Programming Languages
13898 gettext/ngettext functions
13899 ‘gettext.gettext’, ‘gettext.dgettext’, ‘gettext.dcgettext’,
13900 ‘gettext.ngettext’, ‘gettext.dngettext’, ‘gettext.dcngettext’
13903 ‘textdomain’ function
13906 ‘bindtextdomain’ function
13912 ‘require 'gettext'’ or running lua interpreter with ‘-l gettext’
13915 Use or emulate GNU gettext
13921 Formatting with positions
13925 On platforms without gettext, the functions are not available.
13931 File: gettext.info, Node: JavaScript, Next: Vala, Prev: Lua, Up: List of Programming Languages
13951 gettext/ngettext functions
13952 ‘gettext’, ‘dgettext’, ‘dcgettext’, ‘ngettext’, ‘dngettext’
13955 ‘textdomain’ function
13958 ‘bindtextdomain’ function
13966 Use or emulate GNU gettext
13972 Formatting with positions
13976 On platforms without gettext, the functions are not available.
13982 File: gettext.info, Node: Vala, Prev: JavaScript, Up: List of Programming Languages
14002 gettext/ngettext functions
14003 ‘gettext’, ‘dgettext’, ‘dcgettext’, ‘ngettext’, ‘dngettext’,
14004 ‘dpgettext’, ‘dpgettext2’
14007 ‘textdomain’ function, defined under the ‘Intl’ namespace
14010 ‘bindtextdomain’ function, defined under the ‘Intl’ namespace
14013 Programmer must call ‘Intl.setlocale (LocaleCategory.ALL, "")’
14018 Use or emulate GNU gettext
14024 Formatting with positions
14025 Same as for the C language.
14028 autoconf (gettext.m4) and #if ENABLE_NLS
14034 File: gettext.info, Node: List of Data Formats, Prev: List of Programming Languages, Up: Programming Languages
14036 15.6 Internationalizable Data
14037 =============================
14039 Here is a list of other data formats which can be internationalized
14044 * POT:: POT - Portable Object Template
14045 * RST:: Resource String Table
14046 * Glade:: Glade - GNOME user interface description
14047 * GSettings:: GSettings - GNOME user configuration schema
14048 * AppData:: AppData - freedesktop.org application description
14049 * Preparing ITS Rules:: Preparing Rules for XML Internationalization
14052 File: gettext.info, Node: POT, Next: RST, Prev: List of Data Formats, Up: List of Data Formats
14054 15.6.1 POT - Portable Object Template
14055 -------------------------------------
14067 File: gettext.info, Node: RST, Next: Glade, Prev: POT, Up: List of Data Formats
14069 15.6.2 Resource String Table
14070 ----------------------------
14079 ‘xgettext’, ‘rstconv’
14082 File: gettext.info, Node: Glade, Next: GSettings, Prev: RST, Up: List of Data Formats
14084 15.6.3 Glade - GNOME user interface description
14085 -----------------------------------------------
14088 glade, libglade, glade2, libglade2, intltool
14091 ‘glade’, ‘glade2’, ‘ui’
14094 ‘xgettext’, ‘libglade-xgettext’, ‘xml-i18n-extract’,
14098 File: gettext.info, Node: GSettings, Next: AppData, Prev: Glade, Up: List of Data Formats
14100 15.6.4 GSettings - GNOME user configuration schema
14101 --------------------------------------------------
14110 ‘xgettext’, ‘intltool-extract’
14113 File: gettext.info, Node: AppData, Next: Preparing ITS Rules, Prev: GSettings, Up: List of Data Formats
14115 15.6.5 AppData - freedesktop.org application description
14116 --------------------------------------------------------
14119 appdata-tools, appstream, libappstream-glib,
14120 libappstream-glib-builder
14126 ‘xgettext’, ‘intltool-extract’, ‘itstool’
14131 File: gettext.info, Node: Preparing ITS Rules, Prev: AppData, Up: List of Data Formats
14133 15.6.6 Preparing Rules for XML Internationalization
14134 ---------------------------------------------------
14136 Marking translatable strings in an XML file is done through a
14137 separate "rule" file, making use of the Internationalization Tag Set
14138 standard (ITS, <http://www.w3.org/TR/its20/>). The currently supported
14139 ITS data categories are: ‘Translate’, ‘Localization Note’, ‘Elements
14140 Within Text’, and ‘Preserve Space’. In addition to them, ‘xgettext’
14141 also recognizes the following extended data categories:
14145 This data category associates ‘msgctxt’ to the extracted text. In
14146 the global rule, the ‘contextRule’ element contains the following:
14148 • A required ‘selector’ attribute. It contains an absolute
14149 selector that selects the nodes to which this rule applies.
14151 • A required ‘contextPointer’ attribute that contains a relative
14152 selector pointing to a node that holds the ‘msgctxt’ value.
14154 • An optional ‘textPointer’ attribute that contains a relative
14155 selector pointing to a node that holds the ‘msgid’ value.
14157 ‘Escape Special Characters’
14159 This data category indicates whether the special XML characters
14160 (‘<’, ‘>’, ‘&’, ‘"’) are escaped with entity reference. In the
14161 global rule, the ‘escapeRule’ element contains the following:
14163 • A required ‘selector’ attribute. It contains an absolute
14164 selector that selects the nodes to which this rule applies.
14166 • A required ‘escape’ attribute with the value ‘yes’ or ‘no’.
14168 ‘Extended Preserve Space’
14170 This data category extends the standard ‘Preserve Space’ data
14171 category with the additional value ‘trim’. The value means to
14172 remove the leading and trailing whitespaces of the content, but not
14173 to normalize whitespaces in the middle. In the global rule, the
14174 ‘preserveSpaceRule’ element contains the following:
14176 • A required ‘selector’ attribute. It contains an absolute
14177 selector that selects the nodes to which this rule applies.
14179 • A required ‘space’ attribute with the value ‘default’,
14180 ‘preserve’, or ‘trim’.
14182 All those extended data categories can only be expressed with global
14183 rules, and the rule elements have to have the
14184 ‘https://www.gnu.org/s/gettext/ns/its/extensions/1.0’ namespace.
14186 Given the following XML document in a file ‘messages.xml’:
14188 <?xml version="1.0"?>
14191 <p>A translatable string</p>
14194 <p translatable="no">A non-translatable string</p>
14198 To extract the first text content ("A translatable string"), but not
14199 the second ("A non-translatable string"), the following ITS rules can be
14202 <?xml version="1.0"?>
14203 <its:rules xmlns:its="http://www.w3.org/2005/11/its" version="1.0">
14204 <its:translateRule selector="/messages" translate="no"/>
14205 <its:translateRule selector="//message/p" translate="yes"/>
14207 <!-- If 'p' has an attribute 'translatable' with the value 'no', then
14208 the content is not translatable. -->
14209 <its:translateRule selector="//message/p[@translatable = 'no']"
14213 ‘xgettext’ needs another file called "locating rule" to associate an
14214 ITS rule with an XML file. If the above ITS file is saved as
14215 ‘messages.its’, the locating rule would look like:
14217 <?xml version="1.0"?>
14219 <locatingRule name="Messages" pattern="*.xml">
14220 <documentRule localName="messages" target="messages.its"/>
14222 <locatingRule name="Messages" pattern="*.msg" target="messages.its"/>
14225 The ‘locatingRule’ element must have a ‘pattern’ attribute, which
14226 denotes either a literal file name or a wildcard pattern of the XML
14227 file(1). The ‘locatingRule’ element can have child ‘documentRule’
14228 element, which adds checks on the content of the XML file.
14230 The first rule matches any file with the ‘.xml’ file extension, but
14231 it only applies to XML files whose root element is ‘<messages>’.
14233 The second rule indicates that the same ITS rule file are also
14234 applicable to any file with the ‘.msg’ file extension. The optional
14235 ‘name’ attribute of ‘locatingRule’ allows to choose rules by name,
14236 typically with ‘xgettext’’s ‘-L’ option.
14238 The associated ITS rule file is indicated by the ‘target’ attribute
14239 of ‘locatingRule’ or ‘documentRule’. If it is specified in a
14240 ‘documentRule’ element, the parent ‘locatingRule’ shouldn’t have the
14241 ‘target’ attribute.
14243 Locating rule files must have the ‘.loc’ file extension. Both ITS
14244 rule files and locating rule files must be installed in the
14245 ‘$prefix/share/gettext/its’ directory. Once those files are properly
14246 installed, ‘xgettext’ can extract translatable strings from the matching
14249 15.6.6.1 Two Use-cases of Translated Strings in XML
14250 ...................................................
14252 For XML, there are two use-cases of translated strings. One is the
14253 case where the translated strings are directly consumed by programs, and
14254 the other is the case where the translated strings are merged back to
14255 the original XML document. In the former case, special characters in
14256 the extracted strings shouldn’t be escaped, while they should in the
14257 latter case. To control wheter to escape special characters, the
14258 ‘Escape Special Characters’ data category can be used.
14260 To merge the translations, the ‘msgfmt’ program can be used with the
14261 option ‘--xml’. *Note msgfmt Invocation::, for more details about how
14262 one calls the ‘msgfmt’ program. ‘msgfmt’’s ‘--xml’ option doesn’t
14263 perform character escaping, so translated strings can have arbitrary XML
14264 constructs, such as elements for markup.
14266 ---------- Footnotes ----------
14268 (1) Note that the file name matching is done after removing any ‘.in’
14269 suffix from the input file name. Thus the ‘pattern’ attribute must not
14270 include a pattern matching ‘.in’. For example, if the input file name
14271 is ‘foo.msg.in’, the pattern should be either ‘*.msg’ or just ‘*’,
14272 rather than ‘*.in’.
14275 File: gettext.info, Node: Conclusion, Next: Language Codes, Prev: Programming Languages, Up: Top
14277 16 Concluding Remarks
14278 *********************
14280 We would like to conclude this GNU ‘gettext’ manual by presenting an
14281 history of the Translation Project so far. We finally give a few
14282 pointers for those who want to do further research or readings about
14283 Native Language Support matters.
14287 * History:: History of GNU ‘gettext’
14288 * References:: Related Readings
14291 File: gettext.info, Node: History, Next: References, Prev: Conclusion, Up: Conclusion
14293 16.1 History of GNU ‘gettext’
14294 =============================
14296 Internationalization concerns and algorithms have been informally and
14297 casually discussed for years in GNU, sometimes around GNU ‘libc’, maybe
14298 around the incoming ‘Hurd’, or otherwise (nobody clearly remembers).
14299 And even then, when the work started for real, this was somewhat
14300 independently of these previous discussions.
14302 This all began in July 1994, when Patrick D’Cruze had the idea and
14303 initiative of internationalizing version 3.9.2 of GNU ‘fileutils’. He
14304 then asked Jim Meyering, the maintainer, how to get those changes folded
14305 into an official release. That first draft was full of ‘#ifdef’s and
14306 somewhat disconcerting, and Jim wanted to find nicer ways. Patrick and
14307 Jim shared some tries and experimentations in this area. Then, feeling
14308 that this might eventually have a deeper impact on GNU, Jim wanted to
14309 know what standards were, and contacted Richard Stallman, who very
14310 quickly and verbally described an overall design for what was meant to
14311 become ‘glocale’, at that time.
14313 Jim implemented ‘glocale’ and got a lot of exhausting feedback from
14314 Patrick and Richard, of course, but also from Mitchum DSouza (who wrote
14315 a ‘catgets’-like package), Roland McGrath, maybe David MacKenzie,
14316 François Pinard, and Paul Eggert, all pushing and pulling in various
14317 directions, not always compatible, to the extent that after a couple of
14318 test releases, ‘glocale’ was torn apart. In particular, Paul Eggert –
14319 always keeping an eye on developments in Solaris – advocated the use of
14320 the ‘gettext’ API over ‘glocale’’s ‘catgets’-based API.
14322 While Jim took some distance and time and became dad for a second
14323 time, Roland wanted to get GNU ‘libc’ internationalized, and got Ulrich
14324 Drepper involved in that project. Instead of starting from ‘glocale’,
14325 Ulrich rewrote something from scratch, but more conforming to the set of
14326 guidelines who emerged out of the ‘glocale’ effort. Then, Ulrich got
14327 people from the previous forum to involve themselves into this new
14328 project, and the switch from ‘glocale’ to what was first named
14329 ‘msgutils’, renamed ‘nlsutils’, and later ‘gettext’, became officially
14330 accepted by Richard in May 1995 or so.
14332 Let’s summarize by saying that Ulrich Drepper wrote GNU ‘gettext’ in
14333 April 1995. The first official release of the package, including PO
14334 mode, occurred in July 1995, and was numbered 0.7. Other people
14335 contributed to the effort by providing a discussion forum around Ulrich,
14336 writing little pieces of code, or testing. These are quoted in the
14337 ‘THANKS’ file which comes with the GNU ‘gettext’ distribution.
14339 While this was being done, François adapted half a dozen of GNU
14340 packages to ‘glocale’ first, then later to ‘gettext’, putting them in
14341 pretest, so providing along the way an effective user environment for
14342 fine tuning the evolving tools. He also took the responsibility of
14343 organizing and coordinating the Translation Project. After nearly a
14344 year of informal exchanges between people from many countries,
14345 translator teams started to exist in May 1995, through the creation and
14346 support by Patrick D’Cruze of twenty unmoderated mailing lists for that
14347 many native languages, and two moderated lists: one for reaching all
14348 teams at once, the other for reaching all willing maintainers of
14349 internationalized free software packages.
14351 François also wrote PO mode in June 1995 with the collaboration of
14352 Greg McGary, as a kind of contribution to Ulrich’s package. He also
14353 gave a hand with the GNU ‘gettext’ Texinfo manual.
14355 In 1997, Ulrich Drepper released the GNU libc 2.0, which included the
14356 ‘gettext’, ‘textdomain’ and ‘bindtextdomain’ functions.
14358 In 2000, Ulrich Drepper added plural form handling (the ‘ngettext’
14359 function) to GNU libc. Later, in 2001, he released GNU libc 2.2.x,
14360 which is the first free C library with full internationalization
14363 Ulrich being quite busy in his role of General Maintainer of GNU
14364 libc, he handed over the GNU ‘gettext’ maintenance to Bruno Haible in
14365 2000. Bruno added the plural form handling to the tools as well, added
14366 support for UTF-8 and CJK locales, and wrote a few new tools for
14367 manipulating PO files.
14370 File: gettext.info, Node: References, Prev: History, Up: Conclusion
14372 16.2 Related Readings
14373 =====================
14375 * NOTE: * This documentation section is outdated and needs to be
14378 Eugene H. Dorr (‘dorre@well.com’) maintains an interesting
14379 bibliography on internationalization matters, called
14380 ‘Internationalization Reference List’, which is available as:
14381 ftp://ftp.ora.com/pub/examples/nutshell/ujip/doc/i18n-books.txt
14383 Michael Gschwind (‘mike@vlsivie.tuwien.ac.at’) maintains a Frequently
14384 Asked Questions (FAQ) list, entitled ‘Programming for
14385 Internationalisation’. This FAQ discusses writing programs which can
14386 handle different language conventions, character sets, etc.; and is
14387 applicable to all character set encodings, with particular emphasis on
14388 ISO 8859-1. It is regularly published in Usenet groups
14389 ‘comp.unix.questions’, ‘comp.std.internat’,
14390 ‘comp.software.international’, ‘comp.lang.c’, ‘comp.windows.x’,
14391 ‘comp.std.c’, ‘comp.answers’ and ‘news.answers’. The home location of
14393 ftp://ftp.vlsivie.tuwien.ac.at/pub/8bit/ISO-programming
14395 Patrick D’Cruze (‘pdcruze@li.org’) wrote a tutorial about NLS
14396 matters, and Jochen Hein (‘Hein@student.tu-clausthal.de’) took over the
14397 responsibility of maintaining it. It may be found as:
14398 ftp://sunsite.unc.edu/pub/Linux/utils/nls/catalogs/Incoming/...
14399 ...locale-tutorial-0.8.txt.gz
14400 This site is mirrored in:
14401 ftp://ftp.ibp.fr/pub/linux/sunsite/
14403 A French version of the same tutorial should be findable at:
14404 ftp://ftp.ibp.fr/pub/linux/french/docs/
14405 together with French translations of many Linux-related documents.
14408 File: gettext.info, Node: Language Codes, Next: Country Codes, Prev: Conclusion, Up: Top
14410 Appendix A Language Codes
14411 *************************
14413 The ISO 639 standard defines two-letter codes for many languages, and
14414 three-letter codes for more rarely used languages. All abbreviations
14415 for languages used in the Translation Project should come from this
14420 * Usual Language Codes:: Two-letter ISO 639 language codes
14421 * Rare Language Codes:: Three-letter ISO 639 language codes
14424 File: gettext.info, Node: Usual Language Codes, Next: Rare Language Codes, Prev: Language Codes, Up: Language Codes
14426 A.1 Usual Language Codes
14427 ========================
14429 For the commonly used languages, the ISO 639-1 standard defines
14545 Hebrew (formerly iw).
14553 Haitian; Haitian Creole.
14563 Indonesian (formerly in).
14565 Interlingue; Occidental.
14591 Kuanyama; Kwanyama.
14595 Kalaallisut; Greenlandic.
14597 Central Khmer; Cambodian.
14617 Letzeburgesch; Luxembourgish.
14621 Limburgish; Limburger; Limburgan.
14677 Occitan; Provençal.
14719 Sinhala; Sinhalese.
14737 Sesotho; Sotho, Southern.
14793 Yiddish (formerly ji).
14804 File: gettext.info, Node: Rare Language Codes, Prev: Usual Language Codes, Up: Language Codes
14806 A.2 Rare Language Codes
14807 =======================
14809 For rarely used languages, the ISO 639-2 standard defines
14810 three-letter codes. Here is the current list, reduced to only living
14811 languages with at least one million of speakers.
14840 Filipino; Pilipino.
14846 Swiss German; Alemannic; Alsatian.
14868 Luo (Kenya and Tanzania).
14892 Pedi; Sepedi; Northern Sotho.
14900 Pampanga; Kapampangan.
14935 File: gettext.info, Node: Country Codes, Next: Licenses, Prev: Language Codes, Up: Top
14937 Appendix B Country Codes
14938 ************************
14940 The ISO 3166 standard defines two character codes for many countries
14941 and territories. All abbreviations for countries used in the
14942 Translation Project should come from this standard.
14947 United Arab Emirates.
14951 Antigua and Barbuda.
14977 Bosnia and Herzegovina.
15001 Bolivia, Plurinational State of.
15003 Bonaire, Sint Eustatius and Saba.
15021 Cocos (Keeling) Islands.
15023 Congo, The Democratic Republic of the.
15025 Central African Republic.
15065 Dominican Republic.
15087 Falkland Islands (Malvinas).
15089 Micronesia, Federated States of.
15123 South Georgia and the South Sandwich Islands.
15135 Heard Island and McDonald Islands.
15155 British Indian Ocean Territory.
15159 Iran, Islamic Republic of.
15183 Saint Kitts and Nevis.
15185 Korea, Democratic People’s Republic of.
15187 Korea, Republic of.
15195 Lao People’s Democratic Republic.
15221 Moldova, Republic of.
15225 Saint Martin (French part).
15231 Macedonia, The Former Yugoslav Republic of.
15241 Northern Mariana Islands.
15303 Saint Pierre and Miquelon.
15309 Palestine, State of.
15325 Russian Federation.
15341 Saint Helena, Ascension and Tristan da Cunha.
15345 Svalbard and Jan Mayen.
15361 Sao Tome and Principe.
15365 Sint Maarten (Dutch part).
15367 Syrian Arab Republic.
15371 Turks and Caicos Islands.
15375 French Southern Territories.
15395 Trinidad and Tobago.
15399 Taiwan, Province of China.
15401 Tanzania, United Republic of.
15407 United States Minor Outlying Islands.
15415 Holy See (Vatican City State).
15417 Saint Vincent and the Grenadines.
15419 Venezuela, Bolivarian Republic of.
15421 Virgin Islands, British.
15423 Virgin Islands, U.S..
15444 File: gettext.info, Node: Licenses, Next: Program Index, Prev: Country Codes, Up: Top
15446 Appendix C Licenses
15447 *******************
15449 The files of this package are covered by the licenses indicated in
15450 each particular file or directory. Here is a summary:
15452 • The ‘libintl’ and ‘libasprintf’ libraries are covered by the GNU
15453 Lesser General Public License (LGPL). A copy of the license is
15454 included in *note GNU LGPL::.
15456 • The executable programs of this package and the ‘libgettextpo’
15457 library are covered by the GNU General Public License (GPL). A copy
15458 of the license is included in *note GNU GPL::.
15460 • This manual is free documentation. It is dually licensed under the
15461 GNU FDL and the GNU GPL. This means that you can redistribute this
15462 manual under either of these two licenses, at your choice.
15463 This manual is covered by the GNU FDL. Permission is granted to
15464 copy, distribute and/or modify this document under the terms of the
15465 GNU Free Documentation License (FDL), either version 1.2 of the
15466 License, or (at your option) any later version published by the
15467 Free Software Foundation (FSF); with no Invariant Sections, with no
15468 Front-Cover Text, and with no Back-Cover Texts. A copy of the
15469 license is included in *note GNU FDL::.
15470 This manual is covered by the GNU GPL. You can redistribute it
15471 and/or modify it under the terms of the GNU General Public License
15472 (GPL), either version 2 of the License, or (at your option) any
15473 later version published by the Free Software Foundation (FSF). A
15474 copy of the license is included in *note GNU GPL::.
15478 * GNU GPL:: GNU General Public License
15479 * GNU LGPL:: GNU Lesser General Public License
15480 * GNU FDL:: GNU Free Documentation License
15483 File: gettext.info, Node: GNU GPL, Next: GNU LGPL, Prev: Licenses, Up: Licenses
15485 C.1 GNU GENERAL PUBLIC LICENSE
15486 ==============================
15488 Version 2, June 1991
15490 Copyright © 1989, 1991 Free Software Foundation, Inc.
15491 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
15493 Everyone is permitted to copy and distribute verbatim copies
15494 of this license document, but changing it is not allowed.
15499 The licenses for most software are designed to take away your freedom
15500 to share and change it. By contrast, the GNU General Public License is
15501 intended to guarantee your freedom to share and change free software—to
15502 make sure the software is free for all its users. This General Public
15503 License applies to most of the Free Software Foundation’s software and
15504 to any other program whose authors commit to using it. (Some other Free
15505 Software Foundation software is covered by the GNU Lesser General Public
15506 License instead.) You can apply it to your programs, too.
15508 When we speak of free software, we are referring to freedom, not
15509 price. Our General Public Licenses are designed to make sure that you
15510 have the freedom to distribute copies of free software (and charge for
15511 this service if you wish), that you receive source code or can get it if
15512 you want it, that you can change the software or use pieces of it in new
15513 free programs; and that you know you can do these things.
15515 To protect your rights, we need to make restrictions that forbid
15516 anyone to deny you these rights or to ask you to surrender the rights.
15517 These restrictions translate to certain responsibilities for you if you
15518 distribute copies of the software, or if you modify it.
15520 For example, if you distribute copies of such a program, whether
15521 gratis or for a fee, you must give the recipients all the rights that
15522 you have. You must make sure that they, too, receive or can get the
15523 source code. And you must show them these terms so they know their
15526 We protect your rights with two steps: (1) copyright the software,
15527 and (2) offer you this license which gives you legal permission to copy,
15528 distribute and/or modify the software.
15530 Also, for each author’s protection and ours, we want to make certain
15531 that everyone understands that there is no warranty for this free
15532 software. If the software is modified by someone else and passed on, we
15533 want its recipients to know that what they have is not the original, so
15534 that any problems introduced by others will not reflect on the original
15535 authors’ reputations.
15537 Finally, any free program is threatened constantly by software
15538 patents. We wish to avoid the danger that redistributors of a free
15539 program will individually obtain patent licenses, in effect making the
15540 program proprietary. To prevent this, we have made it clear that any
15541 patent must be licensed for everyone’s free use or not licensed at all.
15543 The precise terms and conditions for copying, distribution and
15544 modification follow.
15546 TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
15547 ===============================================================
15549 0. This License applies to any program or other work which contains a
15550 notice placed by the copyright holder saying it may be distributed
15551 under the terms of this General Public License. The “Program”,
15552 below, refers to any such program or work, and a “work based on the
15553 Program” means either the Program or any derivative work under
15554 copyright law: that is to say, a work containing the Program or a
15555 portion of it, either verbatim or with modifications and/or
15556 translated into another language. (Hereinafter, translation is
15557 included without limitation in the term “modification”.) Each
15558 licensee is addressed as “you”.
15560 Activities other than copying, distribution and modification are
15561 not covered by this License; they are outside its scope. The act
15562 of running the Program is not restricted, and the output from the
15563 Program is covered only if its contents constitute a work based on
15564 the Program (independent of having been made by running the
15565 Program). Whether that is true depends on what the Program does.
15567 1. You may copy and distribute verbatim copies of the Program’s source
15568 code as you receive it, in any medium, provided that you
15569 conspicuously and appropriately publish on each copy an appropriate
15570 copyright notice and disclaimer of warranty; keep intact all the
15571 notices that refer to this License and to the absence of any
15572 warranty; and give any other recipients of the Program a copy of
15573 this License along with the Program.
15575 You may charge a fee for the physical act of transferring a copy,
15576 and you may at your option offer warranty protection in exchange
15579 2. You may modify your copy or copies of the Program or any portion of
15580 it, thus forming a work based on the Program, and copy and
15581 distribute such modifications or work under the terms of Section 1
15582 above, provided that you also meet all of these conditions:
15584 a. You must cause the modified files to carry prominent notices
15585 stating that you changed the files and the date of any change.
15587 b. You must cause any work that you distribute or publish, that
15588 in whole or in part contains or is derived from the Program or
15589 any part thereof, to be licensed as a whole at no charge to
15590 all third parties under the terms of this License.
15592 c. If the modified program normally reads commands interactively
15593 when run, you must cause it, when started running for such
15594 interactive use in the most ordinary way, to print or display
15595 an announcement including an appropriate copyright notice and
15596 a notice that there is no warranty (or else, saying that you
15597 provide a warranty) and that users may redistribute the
15598 program under these conditions, and telling the user how to
15599 view a copy of this License. (Exception: if the Program
15600 itself is interactive but does not normally print such an
15601 announcement, your work based on the Program is not required
15602 to print an announcement.)
15604 These requirements apply to the modified work as a whole. If
15605 identifiable sections of that work are not derived from the
15606 Program, and can be reasonably considered independent and separate
15607 works in themselves, then this License, and its terms, do not apply
15608 to those sections when you distribute them as separate works. But
15609 when you distribute the same sections as part of a whole which is a
15610 work based on the Program, the distribution of the whole must be on
15611 the terms of this License, whose permissions for other licensees
15612 extend to the entire whole, and thus to each and every part
15613 regardless of who wrote it.
15615 Thus, it is not the intent of this section to claim rights or
15616 contest your rights to work written entirely by you; rather, the
15617 intent is to exercise the right to control the distribution of
15618 derivative or collective works based on the Program.
15620 In addition, mere aggregation of another work not based on the
15621 Program with the Program (or with a work based on the Program) on a
15622 volume of a storage or distribution medium does not bring the other
15623 work under the scope of this License.
15625 3. You may copy and distribute the Program (or a work based on it,
15626 under Section 2) in object code or executable form under the terms
15627 of Sections 1 and 2 above provided that you also do one of the
15630 a. Accompany it with the complete corresponding machine-readable
15631 source code, which must be distributed under the terms of
15632 Sections 1 and 2 above on a medium customarily used for
15633 software interchange; or,
15635 b. Accompany it with a written offer, valid for at least three
15636 years, to give any third party, for a charge no more than your
15637 cost of physically performing source distribution, a complete
15638 machine-readable copy of the corresponding source code, to be
15639 distributed under the terms of Sections 1 and 2 above on a
15640 medium customarily used for software interchange; or,
15642 c. Accompany it with the information you received as to the offer
15643 to distribute corresponding source code. (This alternative is
15644 allowed only for noncommercial distribution and only if you
15645 received the program in object code or executable form with
15646 such an offer, in accord with Subsection b above.)
15648 The source code for a work means the preferred form of the work for
15649 making modifications to it. For an executable work, complete
15650 source code means all the source code for all modules it contains,
15651 plus any associated interface definition files, plus the scripts
15652 used to control compilation and installation of the executable.
15653 However, as a special exception, the source code distributed need
15654 not include anything that is normally distributed (in either source
15655 or binary form) with the major components (compiler, kernel, and so
15656 on) of the operating system on which the executable runs, unless
15657 that component itself accompanies the executable.
15659 If distribution of executable or object code is made by offering
15660 access to copy from a designated place, then offering equivalent
15661 access to copy the source code from the same place counts as
15662 distribution of the source code, even though third parties are not
15663 compelled to copy the source along with the object code.
15665 4. You may not copy, modify, sublicense, or distribute the Program
15666 except as expressly provided under this License. Any attempt
15667 otherwise to copy, modify, sublicense or distribute the Program is
15668 void, and will automatically terminate your rights under this
15669 License. However, parties who have received copies, or rights,
15670 from you under this License will not have their licenses terminated
15671 so long as such parties remain in full compliance.
15673 5. You are not required to accept this License, since you have not
15674 signed it. However, nothing else grants you permission to modify
15675 or distribute the Program or its derivative works. These actions
15676 are prohibited by law if you do not accept this License.
15677 Therefore, by modifying or distributing the Program (or any work
15678 based on the Program), you indicate your acceptance of this License
15679 to do so, and all its terms and conditions for copying,
15680 distributing or modifying the Program or works based on it.
15682 6. Each time you redistribute the Program (or any work based on the
15683 Program), the recipient automatically receives a license from the
15684 original licensor to copy, distribute or modify the Program subject
15685 to these terms and conditions. You may not impose any further
15686 restrictions on the recipients’ exercise of the rights granted
15687 herein. You are not responsible for enforcing compliance by third
15688 parties to this License.
15690 7. If, as a consequence of a court judgment or allegation of patent
15691 infringement or for any other reason (not limited to patent
15692 issues), conditions are imposed on you (whether by court order,
15693 agreement or otherwise) that contradict the conditions of this
15694 License, they do not excuse you from the conditions of this
15695 License. If you cannot distribute so as to satisfy simultaneously
15696 your obligations under this License and any other pertinent
15697 obligations, then as a consequence you may not distribute the
15698 Program at all. For example, if a patent license would not permit
15699 royalty-free redistribution of the Program by all those who receive
15700 copies directly or indirectly through you, then the only way you
15701 could satisfy both it and this License would be to refrain entirely
15702 from distribution of the Program.
15704 If any portion of this section is held invalid or unenforceable
15705 under any particular circumstance, the balance of the section is
15706 intended to apply and the section as a whole is intended to apply
15707 in other circumstances.
15709 It is not the purpose of this section to induce you to infringe any
15710 patents or other property right claims or to contest validity of
15711 any such claims; this section has the sole purpose of protecting
15712 the integrity of the free software distribution system, which is
15713 implemented by public license practices. Many people have made
15714 generous contributions to the wide range of software distributed
15715 through that system in reliance on consistent application of that
15716 system; it is up to the author/donor to decide if he or she is
15717 willing to distribute software through any other system and a
15718 licensee cannot impose that choice.
15720 This section is intended to make thoroughly clear what is believed
15721 to be a consequence of the rest of this License.
15723 8. If the distribution and/or use of the Program is restricted in
15724 certain countries either by patents or by copyrighted interfaces,
15725 the original copyright holder who places the Program under this
15726 License may add an explicit geographical distribution limitation
15727 excluding those countries, so that distribution is permitted only
15728 in or among countries not thus excluded. In such case, this
15729 License incorporates the limitation as if written in the body of
15732 9. The Free Software Foundation may publish revised and/or new
15733 versions of the General Public License from time to time. Such new
15734 versions will be similar in spirit to the present version, but may
15735 differ in detail to address new problems or concerns.
15737 Each version is given a distinguishing version number. If the
15738 Program specifies a version number of this License which applies to
15739 it and “any later version”, you have the option of following the
15740 terms and conditions either of that version or of any later version
15741 published by the Free Software Foundation. If the Program does not
15742 specify a version number of this License, you may choose any
15743 version ever published by the Free Software Foundation.
15745 10. If you wish to incorporate parts of the Program into other free
15746 programs whose distribution conditions are different, write to the
15747 author to ask for permission. For software which is copyrighted by
15748 the Free Software Foundation, write to the Free Software
15749 Foundation; we sometimes make exceptions for this. Our decision
15750 will be guided by the two goals of preserving the free status of
15751 all derivatives of our free software and of promoting the sharing
15752 and reuse of software generally.
15756 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO
15757 WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE
15758 LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS
15759 AND/OR OTHER PARTIES PROVIDE THE PROGRAM “AS IS” WITHOUT WARRANTY
15760 OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
15761 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
15762 FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND
15763 PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE
15764 DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR
15767 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
15768 WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
15769 MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE
15770 LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
15771 INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
15772 INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
15773 DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU
15774 OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY
15775 OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
15776 ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
15778 END OF TERMS AND CONDITIONS
15780 Appendix: How to Apply These Terms to Your New Programs
15781 =======================================================
15783 If you develop a new program, and you want it to be of the greatest
15784 possible use to the public, the best way to achieve this is to make it
15785 free software which everyone can redistribute and change under these
15788 To do so, attach the following notices to the program. It is safest
15789 to attach them to the start of each source file to most effectively
15790 convey the exclusion of warranty; and each file should have at least the
15791 “copyright” line and a pointer to where the full notice is found.
15793 ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES.
15794 Copyright (C) YYYY NAME OF AUTHOR
15796 This program is free software; you can redistribute it and/or modify
15797 it under the terms of the GNU General Public License as published by
15798 the Free Software Foundation; either version 2 of the License, or
15799 (at your option) any later version.
15801 This program is distributed in the hope that it will be useful,
15802 but WITHOUT ANY WARRANTY; without even the implied warranty of
15803 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15804 GNU General Public License for more details.
15806 You should have received a copy of the GNU General Public License
15807 along with this program; if not, write to the Free Software
15808 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
15810 Also add information on how to contact you by electronic and paper
15813 If the program is interactive, make it output a short notice like
15814 this when it starts in an interactive mode:
15816 Gnomovision version 69, Copyright (C) YEAR NAME OF AUTHOR
15817 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
15818 This is free software, and you are welcome to redistribute it
15819 under certain conditions; type `show c' for details.
15821 The hypothetical commands ‘show w’ and ‘show c’ should show the
15822 appropriate parts of the General Public License. Of course, the
15823 commands you use may be called something other than ‘show w’ and ‘show
15824 c’; they could even be mouse-clicks or menu items—whatever suits your
15827 You should also get your employer (if you work as a programmer) or
15828 your school, if any, to sign a “copyright disclaimer” for the program,
15829 if necessary. Here is a sample; alter the names:
15831 Yoyodyne, Inc., hereby disclaims all copyright interest in the program
15832 `Gnomovision' (which makes passes at compilers) written by James Hacker.
15834 SIGNATURE OF TY COON, 1 April 1989
15835 Ty Coon, President of Vice
15837 This General Public License does not permit incorporating your
15838 program into proprietary programs. If your program is a subroutine
15839 library, you may consider it more useful to permit linking proprietary
15840 applications with the library. If this is what you want to do, use the
15841 GNU Lesser General Public License instead of this License.
15844 File: gettext.info, Node: GNU LGPL, Next: GNU FDL, Prev: GNU GPL, Up: Licenses
15846 C.2 GNU LESSER GENERAL PUBLIC LICENSE
15847 =====================================
15849 Version 2.1, February 1999
15851 Copyright © 1991, 1999 Free Software Foundation, Inc.
15852 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
15854 Everyone is permitted to copy and distribute verbatim copies
15855 of this license document, but changing it is not allowed.
15857 [This is the first released version of the Lesser GPL. It also counts
15858 as the successor of the GNU Library Public License, version 2, hence the
15859 version number 2.1.]
15864 The licenses for most software are designed to take away your freedom
15865 to share and change it. By contrast, the GNU General Public Licenses
15866 are intended to guarantee your freedom to share and change free
15867 software—to make sure the software is free for all its users.
15869 This license, the Lesser General Public License, applies to some
15870 specially designated software—typically libraries—of the Free Software
15871 Foundation and other authors who decide to use it. You can use it too,
15872 but we suggest you first think carefully about whether this license or
15873 the ordinary General Public License is the better strategy to use in any
15874 particular case, based on the explanations below.
15876 When we speak of free software, we are referring to freedom of use,
15877 not price. Our General Public Licenses are designed to make sure that
15878 you have the freedom to distribute copies of free software (and charge
15879 for this service if you wish); that you receive source code or can get
15880 it if you want it; that you can change the software and use pieces of it
15881 in new free programs; and that you are informed that you can do these
15884 To protect your rights, we need to make restrictions that forbid
15885 distributors to deny you these rights or to ask you to surrender these
15886 rights. These restrictions translate to certain responsibilities for
15887 you if you distribute copies of the library or if you modify it.
15889 For example, if you distribute copies of the library, whether gratis
15890 or for a fee, you must give the recipients all the rights that we gave
15891 you. You must make sure that they, too, receive or can get the source
15892 code. If you link other code with the library, you must provide
15893 complete object files to the recipients, so that they can relink them
15894 with the library after making changes to the library and recompiling it.
15895 And you must show them these terms so they know their rights.
15897 We protect your rights with a two-step method: (1) we copyright the
15898 library, and (2) we offer you this license, which gives you legal
15899 permission to copy, distribute and/or modify the library.
15901 To protect each distributor, we want to make it very clear that there
15902 is no warranty for the free library. Also, if the library is modified
15903 by someone else and passed on, the recipients should know that what they
15904 have is not the original version, so that the original author’s
15905 reputation will not be affected by problems that might be introduced by
15908 Finally, software patents pose a constant threat to the existence of
15909 any free program. We wish to make sure that a company cannot
15910 effectively restrict the users of a free program by obtaining a
15911 restrictive license from a patent holder. Therefore, we insist that any
15912 patent license obtained for a version of the library must be consistent
15913 with the full freedom of use specified in this license.
15915 Most GNU software, including some libraries, is covered by the
15916 ordinary GNU General Public License. This license, the GNU Lesser
15917 General Public License, applies to certain designated libraries, and is
15918 quite different from the ordinary General Public License. We use this
15919 license for certain libraries in order to permit linking those libraries
15920 into non-free programs.
15922 When a program is linked with a library, whether statically or using
15923 a shared library, the combination of the two is legally speaking a
15924 combined work, a derivative of the original library. The ordinary
15925 General Public License therefore permits such linking only if the entire
15926 combination fits its criteria of freedom. The Lesser General Public
15927 License permits more lax criteria for linking other code with the
15930 We call this license the "Lesser" General Public License because it
15931 does _Less_ to protect the user’s freedom than the ordinary General
15932 Public License. It also provides other free software developers Less of
15933 an advantage over competing non-free programs. These disadvantages are
15934 the reason we use the ordinary General Public License for many
15935 libraries. However, the Lesser license provides advantages in certain
15936 special circumstances.
15938 For example, on rare occasions, there may be a special need to
15939 encourage the widest possible use of a certain library, so that it
15940 becomes a de-facto standard. To achieve this, non-free programs must be
15941 allowed to use the library. A more frequent case is that a free library
15942 does the same job as widely used non-free libraries. In this case,
15943 there is little to gain by limiting the free library to free software
15944 only, so we use the Lesser General Public License.
15946 In other cases, permission to use a particular library in non-free
15947 programs enables a greater number of people to use a large body of free
15948 software. For example, permission to use the GNU C Library in non-free
15949 programs enables many more people to use the whole GNU operating system,
15950 as well as its variant, the GNU/Linux operating system.
15952 Although the Lesser General Public License is Less protective of the
15953 users’ freedom, it does ensure that the user of a program that is linked
15954 with the Library has the freedom and the wherewithal to run that program
15955 using a modified version of the Library.
15957 The precise terms and conditions for copying, distribution and
15958 modification follow. Pay close attention to the difference between a
15959 “work based on the library” and a “work that uses the library”. The
15960 former contains code derived from the library, whereas the latter must
15961 be combined with the library in order to run.
15963 TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
15964 ---------------------------------------------------------------
15966 0. This License Agreement applies to any software library or other
15967 program which contains a notice placed by the copyright holder or
15968 other authorized party saying it may be distributed under the terms
15969 of this Lesser General Public License (also called “this License”).
15970 Each licensee is addressed as “you”.
15972 A “library” means a collection of software functions and/or data
15973 prepared so as to be conveniently linked with application programs
15974 (which use some of those functions and data) to form executables.
15976 The “Library”, below, refers to any such software library or work
15977 which has been distributed under these terms. A “work based on the
15978 Library” means either the Library or any derivative work under
15979 copyright law: that is to say, a work containing the Library or a
15980 portion of it, either verbatim or with modifications and/or
15981 translated straightforwardly into another language. (Hereinafter,
15982 translation is included without limitation in the term
15985 “Source code” for a work means the preferred form of the work for
15986 making modifications to it. For a library, complete source code
15987 means all the source code for all modules it contains, plus any
15988 associated interface definition files, plus the scripts used to
15989 control compilation and installation of the library.
15991 Activities other than copying, distribution and modification are
15992 not covered by this License; they are outside its scope. The act
15993 of running a program using the Library is not restricted, and
15994 output from such a program is covered only if its contents
15995 constitute a work based on the Library (independent of the use of
15996 the Library in a tool for writing it). Whether that is true
15997 depends on what the Library does and what the program that uses the
16000 1. You may copy and distribute verbatim copies of the Library’s
16001 complete source code as you receive it, in any medium, provided
16002 that you conspicuously and appropriately publish on each copy an
16003 appropriate copyright notice and disclaimer of warranty; keep
16004 intact all the notices that refer to this License and to the
16005 absence of any warranty; and distribute a copy of this License
16006 along with the Library.
16008 You may charge a fee for the physical act of transferring a copy,
16009 and you may at your option offer warranty protection in exchange
16012 2. You may modify your copy or copies of the Library or any portion of
16013 it, thus forming a work based on the Library, and copy and
16014 distribute such modifications or work under the terms of Section 1
16015 above, provided that you also meet all of these conditions:
16017 a. The modified work must itself be a software library.
16019 b. You must cause the files modified to carry prominent notices
16020 stating that you changed the files and the date of any change.
16022 c. You must cause the whole of the work to be licensed at no
16023 charge to all third parties under the terms of this License.
16025 d. If a facility in the modified Library refers to a function or
16026 a table of data to be supplied by an application program that
16027 uses the facility, other than as an argument passed when the
16028 facility is invoked, then you must make a good faith effort to
16029 ensure that, in the event an application does not supply such
16030 function or table, the facility still operates, and performs
16031 whatever part of its purpose remains meaningful.
16033 (For example, a function in a library to compute square roots
16034 has a purpose that is entirely well-defined independent of the
16035 application. Therefore, Subsection 2d requires that any
16036 application-supplied function or table used by this function
16037 must be optional: if the application does not supply it, the
16038 square root function must still compute square roots.)
16040 These requirements apply to the modified work as a whole. If
16041 identifiable sections of that work are not derived from the
16042 Library, and can be reasonably considered independent and separate
16043 works in themselves, then this License, and its terms, do not apply
16044 to those sections when you distribute them as separate works. But
16045 when you distribute the same sections as part of a whole which is a
16046 work based on the Library, the distribution of the whole must be on
16047 the terms of this License, whose permissions for other licensees
16048 extend to the entire whole, and thus to each and every part
16049 regardless of who wrote it.
16051 Thus, it is not the intent of this section to claim rights or
16052 contest your rights to work written entirely by you; rather, the
16053 intent is to exercise the right to control the distribution of
16054 derivative or collective works based on the Library.
16056 In addition, mere aggregation of another work not based on the
16057 Library with the Library (or with a work based on the Library) on a
16058 volume of a storage or distribution medium does not bring the other
16059 work under the scope of this License.
16061 3. You may opt to apply the terms of the ordinary GNU General Public
16062 License instead of this License to a given copy of the Library. To
16063 do this, you must alter all the notices that refer to this License,
16064 so that they refer to the ordinary GNU General Public License,
16065 version 2, instead of to this License. (If a newer version than
16066 version 2 of the ordinary GNU General Public License has appeared,
16067 then you can specify that version instead if you wish.) Do not
16068 make any other change in these notices.
16070 Once this change is made in a given copy, it is irreversible for
16071 that copy, so the ordinary GNU General Public License applies to
16072 all subsequent copies and derivative works made from that copy.
16074 This option is useful when you wish to copy part of the code of the
16075 Library into a program that is not a library.
16077 4. You may copy and distribute the Library (or a portion or derivative
16078 of it, under Section 2) in object code or executable form under the
16079 terms of Sections 1 and 2 above provided that you accompany it with
16080 the complete corresponding machine-readable source code, which must
16081 be distributed under the terms of Sections 1 and 2 above on a
16082 medium customarily used for software interchange.
16084 If distribution of object code is made by offering access to copy
16085 from a designated place, then offering equivalent access to copy
16086 the source code from the same place satisfies the requirement to
16087 distribute the source code, even though third parties are not
16088 compelled to copy the source along with the object code.
16090 5. A program that contains no derivative of any portion of the
16091 Library, but is designed to work with the Library by being compiled
16092 or linked with it, is called a “work that uses the Library”. Such
16093 a work, in isolation, is not a derivative work of the Library, and
16094 therefore falls outside the scope of this License.
16096 However, linking a “work that uses the Library” with the Library
16097 creates an executable that is a derivative of the Library (because
16098 it contains portions of the Library), rather than a “work that uses
16099 the library”. The executable is therefore covered by this License.
16100 Section 6 states terms for distribution of such executables.
16102 When a “work that uses the Library” uses material from a header
16103 file that is part of the Library, the object code for the work may
16104 be a derivative work of the Library even though the source code is
16105 not. Whether this is true is especially significant if the work
16106 can be linked without the Library, or if the work is itself a
16107 library. The threshold for this to be true is not precisely
16110 If such an object file uses only numerical parameters, data
16111 structure layouts and accessors, and small macros and small inline
16112 functions (ten lines or less in length), then the use of the object
16113 file is unrestricted, regardless of whether it is legally a
16114 derivative work. (Executables containing this object code plus
16115 portions of the Library will still fall under Section 6.)
16117 Otherwise, if the work is a derivative of the Library, you may
16118 distribute the object code for the work under the terms of Section
16119 6. Any executables containing that work also fall under Section 6,
16120 whether or not they are linked directly with the Library itself.
16122 6. As an exception to the Sections above, you may also combine or link
16123 a “work that uses the Library” with the Library to produce a work
16124 containing portions of the Library, and distribute that work under
16125 terms of your choice, provided that the terms permit modification
16126 of the work for the customer’s own use and reverse engineering for
16127 debugging such modifications.
16129 You must give prominent notice with each copy of the work that the
16130 Library is used in it and that the Library and its use are covered
16131 by this License. You must supply a copy of this License. If the
16132 work during execution displays copyright notices, you must include
16133 the copyright notice for the Library among them, as well as a
16134 reference directing the user to the copy of this License. Also,
16135 you must do one of these things:
16137 a. Accompany the work with the complete corresponding
16138 machine-readable source code for the Library including
16139 whatever changes were used in the work (which must be
16140 distributed under Sections 1 and 2 above); and, if the work is
16141 an executable linked with the Library, with the complete
16142 machine-readable “work that uses the Library”, as object code
16143 and/or source code, so that the user can modify the Library
16144 and then relink to produce a modified executable containing
16145 the modified Library. (It is understood that the user who
16146 changes the contents of definitions files in the Library will
16147 not necessarily be able to recompile the application to use
16148 the modified definitions.)
16150 b. Use a suitable shared library mechanism for linking with the
16151 Library. A suitable mechanism is one that (1) uses at run
16152 time a copy of the library already present on the user’s
16153 computer system, rather than copying library functions into
16154 the executable, and (2) will operate properly with a modified
16155 version of the library, if the user installs one, as long as
16156 the modified version is interface-compatible with the version
16157 that the work was made with.
16159 c. Accompany the work with a written offer, valid for at least
16160 three years, to give the same user the materials specified in
16161 Subsection 6a, above, for a charge no more than the cost of
16162 performing this distribution.
16164 d. If distribution of the work is made by offering access to copy
16165 from a designated place, offer equivalent access to copy the
16166 above specified materials from the same place.
16168 e. Verify that the user has already received a copy of these
16169 materials or that you have already sent this user a copy.
16171 For an executable, the required form of the “work that uses the
16172 Library” must include any data and utility programs needed for
16173 reproducing the executable from it. However, as a special
16174 exception, the materials to be distributed need not include
16175 anything that is normally distributed (in either source or binary
16176 form) with the major components (compiler, kernel, and so on) of
16177 the operating system on which the executable runs, unless that
16178 component itself accompanies the executable.
16180 It may happen that this requirement contradicts the license
16181 restrictions of other proprietary libraries that do not normally
16182 accompany the operating system. Such a contradiction means you
16183 cannot use both them and the Library together in an executable that
16186 7. You may place library facilities that are a work based on the
16187 Library side-by-side in a single library together with other
16188 library facilities not covered by this License, and distribute such
16189 a combined library, provided that the separate distribution of the
16190 work based on the Library and of the other library facilities is
16191 otherwise permitted, and provided that you do these two things:
16193 a. Accompany the combined library with a copy of the same work
16194 based on the Library, uncombined with any other library
16195 facilities. This must be distributed under the terms of the
16198 b. Give prominent notice with the combined library of the fact
16199 that part of it is a work based on the Library, and explaining
16200 where to find the accompanying uncombined form of the same
16203 8. You may not copy, modify, sublicense, link with, or distribute the
16204 Library except as expressly provided under this License. Any
16205 attempt otherwise to copy, modify, sublicense, link with, or
16206 distribute the Library is void, and will automatically terminate
16207 your rights under this License. However, parties who have received
16208 copies, or rights, from you under this License will not have their
16209 licenses terminated so long as such parties remain in full
16212 9. You are not required to accept this License, since you have not
16213 signed it. However, nothing else grants you permission to modify
16214 or distribute the Library or its derivative works. These actions
16215 are prohibited by law if you do not accept this License.
16216 Therefore, by modifying or distributing the Library (or any work
16217 based on the Library), you indicate your acceptance of this License
16218 to do so, and all its terms and conditions for copying,
16219 distributing or modifying the Library or works based on it.
16221 10. Each time you redistribute the Library (or any work based on the
16222 Library), the recipient automatically receives a license from the
16223 original licensor to copy, distribute, link with or modify the
16224 Library subject to these terms and conditions. You may not impose
16225 any further restrictions on the recipients’ exercise of the rights
16226 granted herein. You are not responsible for enforcing compliance
16227 by third parties with this License.
16229 11. If, as a consequence of a court judgment or allegation of patent
16230 infringement or for any other reason (not limited to patent
16231 issues), conditions are imposed on you (whether by court order,
16232 agreement or otherwise) that contradict the conditions of this
16233 License, they do not excuse you from the conditions of this
16234 License. If you cannot distribute so as to satisfy simultaneously
16235 your obligations under this License and any other pertinent
16236 obligations, then as a consequence you may not distribute the
16237 Library at all. For example, if a patent license would not permit
16238 royalty-free redistribution of the Library by all those who receive
16239 copies directly or indirectly through you, then the only way you
16240 could satisfy both it and this License would be to refrain entirely
16241 from distribution of the Library.
16243 If any portion of this section is held invalid or unenforceable
16244 under any particular circumstance, the balance of the section is
16245 intended to apply, and the section as a whole is intended to apply
16246 in other circumstances.
16248 It is not the purpose of this section to induce you to infringe any
16249 patents or other property right claims or to contest validity of
16250 any such claims; this section has the sole purpose of protecting
16251 the integrity of the free software distribution system which is
16252 implemented by public license practices. Many people have made
16253 generous contributions to the wide range of software distributed
16254 through that system in reliance on consistent application of that
16255 system; it is up to the author/donor to decide if he or she is
16256 willing to distribute software through any other system and a
16257 licensee cannot impose that choice.
16259 This section is intended to make thoroughly clear what is believed
16260 to be a consequence of the rest of this License.
16262 12. If the distribution and/or use of the Library is restricted in
16263 certain countries either by patents or by copyrighted interfaces,
16264 the original copyright holder who places the Library under this
16265 License may add an explicit geographical distribution limitation
16266 excluding those countries, so that distribution is permitted only
16267 in or among countries not thus excluded. In such case, this
16268 License incorporates the limitation as if written in the body of
16271 13. The Free Software Foundation may publish revised and/or new
16272 versions of the Lesser General Public License from time to time.
16273 Such new versions will be similar in spirit to the present version,
16274 but may differ in detail to address new problems or concerns.
16276 Each version is given a distinguishing version number. If the
16277 Library specifies a version number of this License which applies to
16278 it and “any later version”, you have the option of following the
16279 terms and conditions either of that version or of any later version
16280 published by the Free Software Foundation. If the Library does not
16281 specify a license version number, you may choose any version ever
16282 published by the Free Software Foundation.
16284 14. If you wish to incorporate parts of the Library into other free
16285 programs whose distribution conditions are incompatible with these,
16286 write to the author to ask for permission. For software which is
16287 copyrighted by the Free Software Foundation, write to the Free
16288 Software Foundation; we sometimes make exceptions for this. Our
16289 decision will be guided by the two goals of preserving the free
16290 status of all derivatives of our free software and of promoting the
16291 sharing and reuse of software generally.
16295 15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
16296 WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE
16297 LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS
16298 AND/OR OTHER PARTIES PROVIDE THE LIBRARY “AS IS” WITHOUT WARRANTY
16299 OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
16300 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
16301 FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND
16302 PERFORMANCE OF THE LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE
16303 DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR
16306 16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
16307 WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
16308 MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE
16309 LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
16310 INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
16311 INABILITY TO USE THE LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF
16312 DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU
16313 OR THIRD PARTIES OR A FAILURE OF THE LIBRARY TO OPERATE WITH ANY
16314 OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
16315 ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
16317 END OF TERMS AND CONDITIONS
16318 ---------------------------
16320 How to Apply These Terms to Your New Libraries
16321 ----------------------------------------------
16323 If you develop a new library, and you want it to be of the greatest
16324 possible use to the public, we recommend making it free software that
16325 everyone can redistribute and change. You can do so by permitting
16326 redistribution under these terms (or, alternatively, under the terms of
16327 the ordinary General Public License).
16329 To apply these terms, attach the following notices to the library.
16330 It is safest to attach them to the start of each source file to most
16331 effectively convey the exclusion of warranty; and each file should have
16332 at least the “copyright” line and a pointer to where the full notice is
16335 ONE LINE TO GIVE THE LIBRARY'S NAME AND AN IDEA OF WHAT IT DOES.
16336 Copyright (C) YEAR NAME OF AUTHOR
16338 This library is free software; you can redistribute it and/or modify it
16339 under the terms of the GNU Lesser General Public License as published by
16340 the Free Software Foundation; either version 2.1 of the License, or (at
16341 your option) any later version.
16343 This library is distributed in the hope that it will be useful, but
16344 WITHOUT ANY WARRANTY; without even the implied warranty of
16345 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16346 Lesser General Public License for more details.
16348 You should have received a copy of the GNU Lesser General Public
16349 License along with this library; if not, write to the Free Software
16350 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
16353 Also add information on how to contact you by electronic and paper
16356 You should also get your employer (if you work as a programmer) or
16357 your school, if any, to sign a “copyright disclaimer” for the library,
16358 if necessary. Here is a sample; alter the names:
16360 Yoyodyne, Inc., hereby disclaims all copyright interest in the library
16361 `Frob' (a library for tweaking knobs) written by James Random Hacker.
16363 SIGNATURE OF TY COON, 1 April 1990
16364 Ty Coon, President of Vice
16366 That’s all there is to it!
16369 File: gettext.info, Node: GNU FDL, Prev: GNU LGPL, Up: Licenses
16371 C.3 GNU Free Documentation License
16372 ==================================
16374 Version 1.2, November 2002
16376 Copyright © 2000,2001,2002 Free Software Foundation, Inc.
16377 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
16379 Everyone is permitted to copy and distribute verbatim copies
16380 of this license document, but changing it is not allowed.
16384 The purpose of this License is to make a manual, textbook, or other
16385 functional and useful document "free" in the sense of freedom: to
16386 assure everyone the effective freedom to copy and redistribute it,
16387 with or without modifying it, either commercially or
16388 noncommercially. Secondarily, this License preserves for the
16389 author and publisher a way to get credit for their work, while not
16390 being considered responsible for modifications made by others.
16392 This License is a kind of “copyleft”, which means that derivative
16393 works of the document must themselves be free in the same sense.
16394 It complements the GNU General Public License, which is a copyleft
16395 license designed for free software.
16397 We have designed this License in order to use it for manuals for
16398 free software, because free software needs free documentation: a
16399 free program should come with manuals providing the same freedoms
16400 that the software does. But this License is not limited to
16401 software manuals; it can be used for any textual work, regardless
16402 of subject matter or whether it is published as a printed book. We
16403 recommend this License principally for works whose purpose is
16404 instruction or reference.
16406 1. APPLICABILITY AND DEFINITIONS
16408 This License applies to any manual or other work, in any medium,
16409 that contains a notice placed by the copyright holder saying it can
16410 be distributed under the terms of this License. Such a notice
16411 grants a world-wide, royalty-free license, unlimited in duration,
16412 to use that work under the conditions stated herein. The
16413 “Document”, below, refers to any such manual or work. Any member
16414 of the public is a licensee, and is addressed as “you”. You accept
16415 the license if you copy, modify or distribute the work in a way
16416 requiring permission under copyright law.
16418 A “Modified Version” of the Document means any work containing the
16419 Document or a portion of it, either copied verbatim, or with
16420 modifications and/or translated into another language.
16422 A “Secondary Section” is a named appendix or a front-matter section
16423 of the Document that deals exclusively with the relationship of the
16424 publishers or authors of the Document to the Document’s overall
16425 subject (or to related matters) and contains nothing that could
16426 fall directly within that overall subject. (Thus, if the Document
16427 is in part a textbook of mathematics, a Secondary Section may not
16428 explain any mathematics.) The relationship could be a matter of
16429 historical connection with the subject or with related matters, or
16430 of legal, commercial, philosophical, ethical or political position
16433 The “Invariant Sections” are certain Secondary Sections whose
16434 titles are designated, as being those of Invariant Sections, in the
16435 notice that says that the Document is released under this License.
16436 If a section does not fit the above definition of Secondary then it
16437 is not allowed to be designated as Invariant. The Document may
16438 contain zero Invariant Sections. If the Document does not identify
16439 any Invariant Sections then there are none.
16441 The “Cover Texts” are certain short passages of text that are
16442 listed, as Front-Cover Texts or Back-Cover Texts, in the notice
16443 that says that the Document is released under this License. A
16444 Front-Cover Text may be at most 5 words, and a Back-Cover Text may
16445 be at most 25 words.
16447 A “Transparent” copy of the Document means a machine-readable copy,
16448 represented in a format whose specification is available to the
16449 general public, that is suitable for revising the document
16450 straightforwardly with generic text editors or (for images composed
16451 of pixels) generic paint programs or (for drawings) some widely
16452 available drawing editor, and that is suitable for input to text
16453 formatters or for automatic translation to a variety of formats
16454 suitable for input to text formatters. A copy made in an otherwise
16455 Transparent file format whose markup, or absence of markup, has
16456 been arranged to thwart or discourage subsequent modification by
16457 readers is not Transparent. An image format is not Transparent if
16458 used for any substantial amount of text. A copy that is not
16459 “Transparent” is called “Opaque”.
16461 Examples of suitable formats for Transparent copies include plain
16462 ASCII without markup, Texinfo input format, LaTeX input format,
16463 SGML or XML using a publicly available DTD, and standard-conforming
16464 simple HTML, PostScript or PDF designed for human modification.
16465 Examples of transparent image formats include PNG, XCF and JPG.
16466 Opaque formats include proprietary formats that can be read and
16467 edited only by proprietary word processors, SGML or XML for which
16468 the DTD and/or processing tools are not generally available, and
16469 the machine-generated HTML, PostScript or PDF produced by some word
16470 processors for output purposes only.
16472 The “Title Page” means, for a printed book, the title page itself,
16473 plus such following pages as are needed to hold, legibly, the
16474 material this License requires to appear in the title page. For
16475 works in formats which do not have any title page as such, “Title
16476 Page” means the text near the most prominent appearance of the
16477 work’s title, preceding the beginning of the body of the text.
16479 A section “Entitled XYZ” means a named subunit of the Document
16480 whose title either is precisely XYZ or contains XYZ in parentheses
16481 following text that translates XYZ in another language. (Here XYZ
16482 stands for a specific section name mentioned below, such as
16483 “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.)
16484 To “Preserve the Title” of such a section when you modify the
16485 Document means that it remains a section “Entitled XYZ” according
16486 to this definition.
16488 The Document may include Warranty Disclaimers next to the notice
16489 which states that this License applies to the Document. These
16490 Warranty Disclaimers are considered to be included by reference in
16491 this License, but only as regards disclaiming warranties: any other
16492 implication that these Warranty Disclaimers may have is void and
16493 has no effect on the meaning of this License.
16495 2. VERBATIM COPYING
16497 You may copy and distribute the Document in any medium, either
16498 commercially or noncommercially, provided that this License, the
16499 copyright notices, and the license notice saying this License
16500 applies to the Document are reproduced in all copies, and that you
16501 add no other conditions whatsoever to those of this License. You
16502 may not use technical measures to obstruct or control the reading
16503 or further copying of the copies you make or distribute. However,
16504 you may accept compensation in exchange for copies. If you
16505 distribute a large enough number of copies you must also follow the
16506 conditions in section 3.
16508 You may also lend copies, under the same conditions stated above,
16509 and you may publicly display copies.
16511 3. COPYING IN QUANTITY
16513 If you publish printed copies (or copies in media that commonly
16514 have printed covers) of the Document, numbering more than 100, and
16515 the Document’s license notice requires Cover Texts, you must
16516 enclose the copies in covers that carry, clearly and legibly, all
16517 these Cover Texts: Front-Cover Texts on the front cover, and
16518 Back-Cover Texts on the back cover. Both covers must also clearly
16519 and legibly identify you as the publisher of these copies. The
16520 front cover must present the full title with all words of the title
16521 equally prominent and visible. You may add other material on the
16522 covers in addition. Copying with changes limited to the covers, as
16523 long as they preserve the title of the Document and satisfy these
16524 conditions, can be treated as verbatim copying in other respects.
16526 If the required texts for either cover are too voluminous to fit
16527 legibly, you should put the first ones listed (as many as fit
16528 reasonably) on the actual cover, and continue the rest onto
16531 If you publish or distribute Opaque copies of the Document
16532 numbering more than 100, you must either include a machine-readable
16533 Transparent copy along with each Opaque copy, or state in or with
16534 each Opaque copy a computer-network location from which the general
16535 network-using public has access to download using public-standard
16536 network protocols a complete Transparent copy of the Document, free
16537 of added material. If you use the latter option, you must take
16538 reasonably prudent steps, when you begin distribution of Opaque
16539 copies in quantity, to ensure that this Transparent copy will
16540 remain thus accessible at the stated location until at least one
16541 year after the last time you distribute an Opaque copy (directly or
16542 through your agents or retailers) of that edition to the public.
16544 It is requested, but not required, that you contact the authors of
16545 the Document well before redistributing any large number of copies,
16546 to give them a chance to provide you with an updated version of the
16551 You may copy and distribute a Modified Version of the Document
16552 under the conditions of sections 2 and 3 above, provided that you
16553 release the Modified Version under precisely this License, with the
16554 Modified Version filling the role of the Document, thus licensing
16555 distribution and modification of the Modified Version to whoever
16556 possesses a copy of it. In addition, you must do these things in
16557 the Modified Version:
16559 A. Use in the Title Page (and on the covers, if any) a title
16560 distinct from that of the Document, and from those of previous
16561 versions (which should, if there were any, be listed in the
16562 History section of the Document). You may use the same title
16563 as a previous version if the original publisher of that
16564 version gives permission.
16566 B. List on the Title Page, as authors, one or more persons or
16567 entities responsible for authorship of the modifications in
16568 the Modified Version, together with at least five of the
16569 principal authors of the Document (all of its principal
16570 authors, if it has fewer than five), unless they release you
16571 from this requirement.
16573 C. State on the Title page the name of the publisher of the
16574 Modified Version, as the publisher.
16576 D. Preserve all the copyright notices of the Document.
16578 E. Add an appropriate copyright notice for your modifications
16579 adjacent to the other copyright notices.
16581 F. Include, immediately after the copyright notices, a license
16582 notice giving the public permission to use the Modified
16583 Version under the terms of this License, in the form shown in
16584 the Addendum below.
16586 G. Preserve in that license notice the full lists of Invariant
16587 Sections and required Cover Texts given in the Document’s
16590 H. Include an unaltered copy of this License.
16592 I. Preserve the section Entitled “History”, Preserve its Title,
16593 and add to it an item stating at least the title, year, new
16594 authors, and publisher of the Modified Version as given on the
16595 Title Page. If there is no section Entitled “History” in the
16596 Document, create one stating the title, year, authors, and
16597 publisher of the Document as given on its Title Page, then add
16598 an item describing the Modified Version as stated in the
16601 J. Preserve the network location, if any, given in the Document
16602 for public access to a Transparent copy of the Document, and
16603 likewise the network locations given in the Document for
16604 previous versions it was based on. These may be placed in the
16605 “History” section. You may omit a network location for a work
16606 that was published at least four years before the Document
16607 itself, or if the original publisher of the version it refers
16608 to gives permission.
16610 K. For any section Entitled “Acknowledgements” or “Dedications”,
16611 Preserve the Title of the section, and preserve in the section
16612 all the substance and tone of each of the contributor
16613 acknowledgements and/or dedications given therein.
16615 L. Preserve all the Invariant Sections of the Document, unaltered
16616 in their text and in their titles. Section numbers or the
16617 equivalent are not considered part of the section titles.
16619 M. Delete any section Entitled “Endorsements”. Such a section
16620 may not be included in the Modified Version.
16622 N. Do not retitle any existing section to be Entitled
16623 “Endorsements” or to conflict in title with any Invariant
16626 O. Preserve any Warranty Disclaimers.
16628 If the Modified Version includes new front-matter sections or
16629 appendices that qualify as Secondary Sections and contain no
16630 material copied from the Document, you may at your option designate
16631 some or all of these sections as invariant. To do this, add their
16632 titles to the list of Invariant Sections in the Modified Version’s
16633 license notice. These titles must be distinct from any other
16636 You may add a section Entitled “Endorsements”, provided it contains
16637 nothing but endorsements of your Modified Version by various
16638 parties—for example, statements of peer review or that the text has
16639 been approved by an organization as the authoritative definition of
16642 You may add a passage of up to five words as a Front-Cover Text,
16643 and a passage of up to 25 words as a Back-Cover Text, to the end of
16644 the list of Cover Texts in the Modified Version. Only one passage
16645 of Front-Cover Text and one of Back-Cover Text may be added by (or
16646 through arrangements made by) any one entity. If the Document
16647 already includes a cover text for the same cover, previously added
16648 by you or by arrangement made by the same entity you are acting on
16649 behalf of, you may not add another; but you may replace the old
16650 one, on explicit permission from the previous publisher that added
16653 The author(s) and publisher(s) of the Document do not by this
16654 License give permission to use their names for publicity for or to
16655 assert or imply endorsement of any Modified Version.
16657 5. COMBINING DOCUMENTS
16659 You may combine the Document with other documents released under
16660 this License, under the terms defined in section 4 above for
16661 modified versions, provided that you include in the combination all
16662 of the Invariant Sections of all of the original documents,
16663 unmodified, and list them all as Invariant Sections of your
16664 combined work in its license notice, and that you preserve all
16665 their Warranty Disclaimers.
16667 The combined work need only contain one copy of this License, and
16668 multiple identical Invariant Sections may be replaced with a single
16669 copy. If there are multiple Invariant Sections with the same name
16670 but different contents, make the title of each such section unique
16671 by adding at the end of it, in parentheses, the name of the
16672 original author or publisher of that section if known, or else a
16673 unique number. Make the same adjustment to the section titles in
16674 the list of Invariant Sections in the license notice of the
16677 In the combination, you must combine any sections Entitled
16678 “History” in the various original documents, forming one section
16679 Entitled “History”; likewise combine any sections Entitled
16680 “Acknowledgements”, and any sections Entitled “Dedications”. You
16681 must delete all sections Entitled “Endorsements.”
16683 6. COLLECTIONS OF DOCUMENTS
16685 You may make a collection consisting of the Document and other
16686 documents released under this License, and replace the individual
16687 copies of this License in the various documents with a single copy
16688 that is included in the collection, provided that you follow the
16689 rules of this License for verbatim copying of each of the documents
16690 in all other respects.
16692 You may extract a single document from such a collection, and
16693 distribute it individually under this License, provided you insert
16694 a copy of this License into the extracted document, and follow this
16695 License in all other respects regarding verbatim copying of that
16698 7. AGGREGATION WITH INDEPENDENT WORKS
16700 A compilation of the Document or its derivatives with other
16701 separate and independent documents or works, in or on a volume of a
16702 storage or distribution medium, is called an “aggregate” if the
16703 copyright resulting from the compilation is not used to limit the
16704 legal rights of the compilation’s users beyond what the individual
16705 works permit. When the Document is included in an aggregate, this
16706 License does not apply to the other works in the aggregate which
16707 are not themselves derivative works of the Document.
16709 If the Cover Text requirement of section 3 is applicable to these
16710 copies of the Document, then if the Document is less than one half
16711 of the entire aggregate, the Document’s Cover Texts may be placed
16712 on covers that bracket the Document within the aggregate, or the
16713 electronic equivalent of covers if the Document is in electronic
16714 form. Otherwise they must appear on printed covers that bracket
16715 the whole aggregate.
16719 Translation is considered a kind of modification, so you may
16720 distribute translations of the Document under the terms of section
16721 4. Replacing Invariant Sections with translations requires special
16722 permission from their copyright holders, but you may include
16723 translations of some or all Invariant Sections in addition to the
16724 original versions of these Invariant Sections. You may include a
16725 translation of this License, and all the license notices in the
16726 Document, and any Warranty Disclaimers, provided that you also
16727 include the original English version of this License and the
16728 original versions of those notices and disclaimers. In case of a
16729 disagreement between the translation and the original version of
16730 this License or a notice or disclaimer, the original version will
16733 If a section in the Document is Entitled “Acknowledgements”,
16734 “Dedications”, or “History”, the requirement (section 4) to
16735 Preserve its Title (section 1) will typically require changing the
16740 You may not copy, modify, sublicense, or distribute the Document
16741 except as expressly provided for under this License. Any other
16742 attempt to copy, modify, sublicense or distribute the Document is
16743 void, and will automatically terminate your rights under this
16744 License. However, parties who have received copies, or rights,
16745 from you under this License will not have their licenses terminated
16746 so long as such parties remain in full compliance.
16748 10. FUTURE REVISIONS OF THIS LICENSE
16750 The Free Software Foundation may publish new, revised versions of
16751 the GNU Free Documentation License from time to time. Such new
16752 versions will be similar in spirit to the present version, but may
16753 differ in detail to address new problems or concerns. See
16754 <http://www.gnu.org/copyleft/>.
16756 Each version of the License is given a distinguishing version
16757 number. If the Document specifies that a particular numbered
16758 version of this License “or any later version” applies to it, you
16759 have the option of following the terms and conditions either of
16760 that specified version or of any later version that has been
16761 published (not as a draft) by the Free Software Foundation. If the
16762 Document does not specify a version number of this License, you may
16763 choose any version ever published (not as a draft) by the Free
16764 Software Foundation.
16766 ADDENDUM: How to use this License for your documents
16767 ====================================================
16769 To use this License in a document you have written, include a copy of
16770 the License in the document and put the following copyright and license
16771 notices just after the title page:
16773 Copyright (C) YEAR YOUR NAME.
16774 Permission is granted to copy, distribute and/or modify this document
16775 under the terms of the GNU Free Documentation License, Version 1.2
16776 or any later version published by the Free Software Foundation;
16777 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
16778 Texts. A copy of the license is included in the section entitled ``GNU
16779 Free Documentation License''.
16781 If you have Invariant Sections, Front-Cover Texts and Back-Cover
16782 Texts, replace the “with…Texts.” line with this:
16784 with the Invariant Sections being LIST THEIR TITLES, with
16785 the Front-Cover Texts being LIST, and with the Back-Cover Texts
16788 If you have Invariant Sections without Cover Texts, or some other
16789 combination of the three, merge those two alternatives to suit the
16792 If your document contains nontrivial examples of program code, we
16793 recommend releasing these examples in parallel under your choice of free
16794 software license, such as the GNU General Public License, to permit
16795 their use in free software.
16798 File: gettext.info, Node: Program Index, Next: Option Index, Prev: Licenses, Up: Top
16806 * autopoint: autopoint Invocation.
16808 * boldquot: msgfilter Invocation.
16810 * envsubst: envsubst Invocation. (line 6)
16811 * gettext: sh. (line 19)
16812 * gettext <1>: gettext Invocation. (line 6)
16813 * gettextize: gettextize Invocation.
16815 * msgattrib: msgattrib Invocation.
16817 * msgcat: msgcat Invocation. (line 6)
16818 * msgcmp: msgcmp Invocation. (line 6)
16819 * msgcomm: msgcomm Invocation. (line 6)
16820 * msgconv: msgconv Invocation. (line 6)
16821 * msgen: msgen Invocation. (line 6)
16822 * msgexec: msgexec Invocation. (line 6)
16823 * msgfilter: msgfilter Invocation.
16825 * msgfmt: msgfmt Invocation. (line 6)
16826 * msggrep: msggrep Invocation. (line 6)
16827 * msginit: msginit Invocation. (line 6)
16828 * msgmerge: msgmerge Invocation. (line 6)
16829 * msgunfmt: msgunfmt Invocation. (line 6)
16830 * msguniq: msguniq Invocation. (line 6)
16831 * ngettext: sh. (line 19)
16832 * ngettext <1>: ngettext Invocation. (line 6)
16833 * quot: msgfilter Invocation.
16835 * recode-sr-latin: msgfilter Invocation.
16837 * xgettext: xgettext Invocation. (line 6)
16840 File: gettext.info, Node: Option Index, Next: Variable Index, Prev: Program Index, Up: Top
16848 * --add-comments, ‘xgettext’ option: xgettext Invocation. (line 94)
16849 * --add-location, ‘msgattrib’ option: msgattrib Invocation.
16851 * --add-location, ‘msgcat’ option: msgcat Invocation. (line 114)
16852 * --add-location, ‘msgcomm’ option: msgcomm Invocation. (line 100)
16853 * --add-location, ‘msgconv’ option: msgconv Invocation. (line 80)
16854 * --add-location, ‘msgen’ option: msgen Invocation. (line 83)
16855 * --add-location, ‘msgfilter’ option: msgfilter Invocation.
16857 * --add-location, ‘msggrep’ option: msggrep Invocation. (line 152)
16858 * --add-location, ‘msgmerge’ option: msgmerge Invocation. (line 150)
16859 * --add-location, ‘msguniq’ option: msguniq Invocation. (line 97)
16860 * --add-location, ‘xgettext’ option: xgettext Invocation. (line 371)
16861 * --alignment, ‘msgfmt’ option: msgfmt Invocation. (line 288)
16862 * --backup, ‘msgmerge’ option: msgmerge Invocation. (line 62)
16863 * --boost, ‘xgettext’ option: xgettext Invocation. (line 329)
16864 * --c++, ‘xgettext’ option: xgettext Invocation. (line 63)
16865 * --check, ‘msgfmt’ option: msgfmt Invocation. (line 226)
16866 * --check, ‘xgettext’ option: xgettext Invocation. (line 116)
16867 * --check-accelerators, ‘msgfmt’ option: msgfmt Invocation. (line 267)
16868 * --check-compatibility, ‘msgfmt’ option: msgfmt Invocation. (line 263)
16869 * --check-domain, ‘msgfmt’ option: msgfmt Invocation. (line 258)
16870 * --check-format, ‘msgfmt’ option: msgfmt Invocation. (line 230)
16871 * --check-header, ‘msgfmt’ option: msgfmt Invocation. (line 253)
16872 * --clear-fuzzy, ‘msgattrib’ option: msgattrib Invocation.
16874 * --clear-obsolete, ‘msgattrib’ option: msgattrib Invocation.
16876 * --clear-previous, ‘msgattrib’ option: msgattrib Invocation.
16878 * --color, ‘msgattrib’ option: msgattrib Invocation.
16880 * --color, ‘msgcat’ option: msgcat Invocation. (line 95)
16881 * --color, ‘msgcat’ option <1>: The --color option. (line 6)
16882 * --color, ‘msgcomm’ option: msgcomm Invocation. (line 81)
16883 * --color, ‘msgconv’ option: msgconv Invocation. (line 61)
16884 * --color, ‘msgen’ option: msgen Invocation. (line 64)
16885 * --color, ‘msgfilter’ option: msgfilter Invocation.
16887 * --color, ‘msggrep’ option: msggrep Invocation. (line 134)
16888 * --color, ‘msginit’ option: msginit Invocation. (line 93)
16889 * --color, ‘msgmerge’ option: msgmerge Invocation. (line 131)
16890 * --color, ‘msgunfmt’ option: msgunfmt Invocation. (line 103)
16891 * --color, ‘msguniq’ option: msguniq Invocation. (line 78)
16892 * --color, ‘xgettext’ option: xgettext Invocation. (line 350)
16893 * --comment, ‘msggrep’ option: msggrep Invocation. (line 86)
16894 * --compendium, ‘msgmerge’ option: msgmerge Invocation. (line 36)
16895 * --copyright-holder, ‘xgettext’ option: xgettext Invocation. (line 435)
16896 * --csharp, ‘msgfmt’ option: msgfmt Invocation. (line 36)
16897 * --csharp, ‘msgunfmt’ option: msgunfmt Invocation. (line 19)
16898 * --csharp-resources, ‘msgfmt’ option: msgfmt Invocation. (line 40)
16899 * --csharp-resources, ‘msgunfmt’ option: msgunfmt Invocation. (line 23)
16900 * --debug, ‘xgettext’ option: xgettext Invocation. (line 333)
16901 * --default-domain, ‘xgettext’ option: xgettext Invocation. (line 35)
16902 * --desktop, ‘msgfmt’ option: msgfmt Invocation. (line 49)
16903 * --directory, ‘msgattrib’ option: msgattrib Invocation.
16905 * --directory, ‘msgcat’ option: msgcat Invocation. (line 31)
16906 * --directory, ‘msgcmp’ option: msgcmp Invocation. (line 27)
16907 * --directory, ‘msgcomm’ option: msgcomm Invocation. (line 30)
16908 * --directory, ‘msgconv’ option: msgconv Invocation. (line 19)
16909 * --directory, ‘msgen’ option: msgen Invocation. (line 25)
16910 * --directory, ‘msgexec’ option: msgexec Invocation. (line 54)
16911 * --directory, ‘msgfilter’ option: msgfilter Invocation.
16913 * --directory, ‘msgfmt’ option: msgfmt Invocation. (line 18)
16914 * --directory, ‘msggrep’ option: msggrep Invocation. (line 19)
16915 * --directory, ‘msgmerge’ option: msgmerge Invocation. (line 30)
16916 * --directory, ‘msguniq’ option: msguniq Invocation. (line 26)
16917 * --directory, ‘xgettext’ option: xgettext Invocation. (line 24)
16918 * --domain, ‘gettext’ option: gettext Invocation. (line 16)
16919 * --domain, ‘msggrep’ option: msggrep Invocation. (line 70)
16920 * --domain, ‘ngettext’ option: ngettext Invocation. (line 15)
16921 * --dry-run, ‘autopoint’ option: autopoint Invocation.
16923 * --dry-run, ‘gettextize’ option: gettextize Invocation.
16925 * --empty, ‘msgattrib’ option: msgattrib Invocation.
16927 * --endianness, ‘msgfmt’ option: msgfmt Invocation. (line 291)
16928 * --exclude-file, ‘xgettext’ option: xgettext Invocation. (line 89)
16929 * --expression, ‘msgfilter’ option: msgfilter Invocation.
16931 * --extended-regexp, ‘msggrep’ option: msggrep Invocation. (line 94)
16932 * --extract-all, ‘xgettext’ option: xgettext Invocation. (line 165)
16933 * --extracted-comment, ‘msggrep’ option: msggrep Invocation. (line 90)
16934 * --file, ‘msgfilter’ option: msgfilter Invocation.
16936 * --file, ‘msggrep’ option: msggrep Invocation. (line 106)
16937 * --files-from, ‘msgcat’ option: msgcat Invocation. (line 26)
16938 * --files-from, ‘msgcomm’ option: msgcomm Invocation. (line 25)
16939 * --files-from, ‘xgettext’ option: xgettext Invocation. (line 19)
16940 * --fixed-strings, ‘msggrep’ option: msggrep Invocation. (line 98)
16941 * --flag, ‘xgettext’ option: xgettext Invocation. (line 276)
16942 * --force, ‘autopoint’ option: autopoint Invocation.
16944 * --force, ‘gettextize’ option: gettextize Invocation.
16946 * --force-po, ‘msgattrib’ option: msgattrib Invocation.
16948 * --force-po, ‘msgcat’ option: msgcat Invocation. (line 103)
16949 * --force-po, ‘msgcomm’ option: msgcomm Invocation. (line 89)
16950 * --force-po, ‘msgconv’ option: msgconv Invocation. (line 69)
16951 * --force-po, ‘msgen’ option: msgen Invocation. (line 72)
16952 * --force-po, ‘msgfilter’ option: msgfilter Invocation.
16954 * --force-po, ‘msggrep’ option: msggrep Invocation. (line 142)
16955 * --force-po, ‘msgmerge’ option: msgmerge Invocation. (line 139)
16956 * --force-po, ‘msgunfmt’ option: msgunfmt Invocation. (line 111)
16957 * --force-po, ‘msguniq’ option: msguniq Invocation. (line 86)
16958 * --force-po, ‘xgettext’ option: xgettext Invocation. (line 358)
16959 * --foreign-user, ‘xgettext’ option: xgettext Invocation. (line 450)
16960 * --from-code, ‘xgettext’ option: xgettext Invocation. (line 72)
16961 * --fuzzy, ‘msgattrib’ option: msgattrib Invocation.
16963 * --help, ‘autopoint’ option: autopoint Invocation.
16965 * --help, ‘envsubst’ option: envsubst Invocation. (line 21)
16966 * --help, ‘gettext’ option: gettext Invocation. (line 32)
16967 * --help, ‘gettextize’ option: gettextize Invocation.
16969 * --help, ‘msgattrib’ option: msgattrib Invocation.
16971 * --help, ‘msgcat’ option: msgcat Invocation. (line 164)
16972 * --help, ‘msgcmp’ option: msgcmp Invocation. (line 69)
16973 * --help, ‘msgcomm’ option: msgcomm Invocation. (line 153)
16974 * --help, ‘msgconv’ option: msgconv Invocation. (line 130)
16975 * --help, ‘msgen’ option: msgen Invocation. (line 133)
16976 * --help, ‘msgexec’ option: msgexec Invocation. (line 77)
16977 * --help, ‘msgfilter’ option: msgfilter Invocation.
16979 * --help, ‘msgfmt’ option: msgfmt Invocation. (line 311)
16980 * --help, ‘msggrep’ option: msggrep Invocation. (line 200)
16981 * --help, ‘msginit’ option: msginit Invocation. (line 128)
16982 * --help, ‘msgmerge’ option: msgmerge Invocation. (line 200)
16983 * --help, ‘msgunfmt’ option: msgunfmt Invocation. (line 155)
16984 * --help, ‘msguniq’ option: msguniq Invocation. (line 147)
16985 * --help, ‘ngettext’ option: ngettext Invocation. (line 31)
16986 * --help, ‘xgettext’ option: xgettext Invocation. (line 497)
16987 * --ignore-case, ‘msggrep’ option: msggrep Invocation. (line 110)
16988 * --ignore-file, ‘msgattrib’ option: msgattrib Invocation.
16990 * --indent, ‘msgattrib’ option: msgattrib Invocation.
16992 * --indent, ‘msgcat’ option: msgcat Invocation. (line 107)
16993 * --indent, ‘msgcomm’ option: msgcomm Invocation. (line 93)
16994 * --indent, ‘msgconv’ option: msgconv Invocation. (line 73)
16995 * --indent, ‘msgen’ option: msgen Invocation. (line 76)
16996 * --indent, ‘msgfilter’ option: msgfilter Invocation.
16998 * --indent, ‘msggrep’ option: msggrep Invocation. (line 145)
16999 * --indent, ‘msgmerge’ option: msgmerge Invocation. (line 143)
17000 * --indent, ‘msgunfmt’ option: msgunfmt Invocation. (line 115)
17001 * --indent, ‘msguniq’ option: msguniq Invocation. (line 90)
17002 * --indent, ‘xgettext’ option: xgettext Invocation. (line 362)
17003 * --input, ‘msgexec’ option: msgexec Invocation. (line 50)
17004 * --input, ‘msgfilter’ option: msgfilter Invocation.
17006 * --input, ‘msginit’ option: msginit Invocation. (line 49)
17007 * --intl, ‘gettextize’ option: gettextize Invocation.
17009 * --invert-match, ‘msggrep’ option: msggrep Invocation. (line 114)
17010 * --its, ‘xgettext’ option: xgettext Invocation. (line 394)
17011 * --itstool, ‘xgettext’ option: xgettext Invocation. (line 398)
17012 * --java, ‘msgfmt’ option: msgfmt Invocation. (line 30)
17013 * --java, ‘msgunfmt’ option: msgunfmt Invocation. (line 16)
17014 * --java2, ‘msgfmt’ option: msgfmt Invocation. (line 33)
17015 * --join-existing, ‘xgettext’ option: xgettext Invocation. (line 85)
17016 * --kde, ‘xgettext’ option: xgettext Invocation. (line 325)
17017 * --keep-header, ‘msgfilter’ option: msgfilter Invocation.
17019 * --keyword, ‘msgfmt’ option: msgfmt Invocation. (line 140)
17020 * --keyword, ‘xgettext’ option: xgettext Invocation. (line 174)
17021 * --lang, ‘msgcat’ option: msgcat Invocation. (line 89)
17022 * --lang, ‘msgen’ option: msgen Invocation. (line 57)
17023 * --lang, ‘msgmerge’ option: msgmerge Invocation. (line 123)
17024 * --language, ‘msgfmt’ option: msgfmt Invocation. (line 180)
17025 * --language, ‘xgettext’ option: xgettext Invocation. (line 54)
17026 * --less-than, ‘msgcat’ option: msgcat Invocation. (line 52)
17027 * --less-than, ‘msgcomm’ option: msgcomm Invocation. (line 51)
17028 * --locale, ‘msgfmt’ option: msgfmt Invocation. (line 83)
17029 * --locale, ‘msgfmt’ option <1>: msgfmt Invocation. (line 106)
17030 * --locale, ‘msgfmt’ option <2>: msgfmt Invocation. (line 122)
17031 * --locale, ‘msgfmt’ option <3>: msgfmt Invocation. (line 146)
17032 * --locale, ‘msgfmt’ option <4>: msgfmt Invocation. (line 184)
17033 * --locale, ‘msginit’ option: msginit Invocation. (line 82)
17034 * --locale, ‘msgunfmt’ option: msgunfmt Invocation. (line 45)
17035 * --locale, ‘msgunfmt’ option <1>: msgunfmt Invocation. (line 62)
17036 * --locale, ‘msgunfmt’ option <2>: msgunfmt Invocation. (line 78)
17037 * --location, ‘msggrep’ option: msggrep Invocation. (line 65)
17038 * --more-than, ‘msgcat’ option: msgcat Invocation. (line 57)
17039 * --more-than, ‘msgcomm’ option: msgcomm Invocation. (line 56)
17040 * --msgctxt, ‘msggrep’ option: msggrep Invocation. (line 74)
17041 * --msgid, ‘msggrep’ option: msggrep Invocation. (line 78)
17042 * --msgid-bugs-address, ‘xgettext’ option: xgettext Invocation.
17044 * --msgstr, ‘msggrep’ option: msggrep Invocation. (line 82)
17045 * --msgstr-prefix, ‘xgettext’ option: xgettext Invocation. (line 486)
17046 * --msgstr-suffix, ‘xgettext’ option: xgettext Invocation. (line 490)
17047 * --multi-domain, ‘msgcmp’ option: msgcmp Invocation. (line 35)
17048 * --multi-domain, ‘msgmerge’ option: msgmerge Invocation. (line 96)
17049 * --newline, ‘msgfilter’ option: msgfilter Invocation.
17051 * --newline, ‘msgfilter’ option <1>: msgexec Invocation. (line 19)
17052 * --no-changelog, ‘gettextize’ option: gettextize Invocation.
17054 * --no-fuzzy, ‘msgattrib’ option: msgattrib Invocation.
17056 * --no-fuzzy-matching, ‘msgcmp’ option: msgcmp Invocation. (line 39)
17057 * --no-fuzzy-matching, ‘msgmerge’ option: msgmerge Invocation.
17059 * --no-hash, ‘msgfmt’ option: msgfmt Invocation. (line 303)
17060 * --no-location, ‘msgattrib’ option: msgattrib Invocation.
17062 * --no-location, ‘msgcat’ option: msgcat Invocation. (line 110)
17063 * --no-location, ‘msgcomm’ option: msgcomm Invocation. (line 96)
17064 * --no-location, ‘msgconv’ option: msgconv Invocation. (line 76)
17065 * --no-location, ‘msgen’ option: msgen Invocation. (line 79)
17066 * --no-location, ‘msgfilter’ option: msgfilter Invocation.
17068 * --no-location, ‘msggrep’ option: msggrep Invocation. (line 148)
17069 * --no-location, ‘msgmerge’ option: msgmerge Invocation. (line 146)
17070 * --no-location, ‘msguniq’ option: msguniq Invocation. (line 93)
17071 * --no-location, ‘xgettext’ option: xgettext Invocation. (line 365)
17072 * --no-obsolete, ‘msgattrib’ option: msgattrib Invocation.
17074 * --no-translator, ‘msginit’ option: msginit Invocation. (line 88)
17075 * --no-wrap, ‘msgattrib’ option: msgattrib Invocation.
17077 * --no-wrap, ‘msgcat’ option: msgcat Invocation. (line 145)
17078 * --no-wrap, ‘msgcomm’ option: msgcomm Invocation. (line 131)
17079 * --no-wrap, ‘msgconv’ option: msgconv Invocation. (line 111)
17080 * --no-wrap, ‘msgen’ option: msgen Invocation. (line 114)
17081 * --no-wrap, ‘msgfilter’ option: msgfilter Invocation.
17083 * --no-wrap, ‘msggrep’ option: msggrep Invocation. (line 183)
17084 * --no-wrap, ‘msginit’ option: msginit Invocation. (line 118)
17085 * --no-wrap, ‘msgmerge’ option: msgmerge Invocation. (line 181)
17086 * --no-wrap, ‘msgunfmt’ option: msgunfmt Invocation. (line 140)
17087 * --no-wrap, ‘msguniq’ option: msguniq Invocation. (line 128)
17088 * --no-wrap, ‘xgettext’ option: xgettext Invocation. (line 409)
17089 * --obsolete, ‘msgattrib’ option: msgattrib Invocation.
17091 * --omit-header, ‘msgcomm’ option: msgcomm Invocation. (line 146)
17092 * --omit-header, ‘xgettext’ option: xgettext Invocation. (line 424)
17093 * --only-file, ‘msgattrib’ option: msgattrib Invocation.
17095 * --only-fuzzy, ‘msgattrib’ option: msgattrib Invocation.
17097 * --only-obsolete, ‘msgattrib’ option: msgattrib Invocation.
17099 * --output, ‘xgettext’ option: xgettext Invocation. (line 39)
17100 * --output-dir, ‘xgettext’ option: xgettext Invocation. (line 44)
17101 * --output-file, ‘msgattrib’ option: msgattrib Invocation.
17103 * --output-file, ‘msgcat’ option: msgcat Invocation. (line 42)
17104 * --output-file, ‘msgcomm’ option: msgcomm Invocation. (line 41)
17105 * --output-file, ‘msgconv’ option: msgconv Invocation. (line 30)
17106 * --output-file, ‘msgen’ option: msgen Invocation. (line 36)
17107 * --output-file, ‘msgfilter’ option: msgfilter Invocation.
17109 * --output-file, ‘msgfmt’ option: msgfmt Invocation. (line 59)
17110 * --output-file, ‘msggrep’ option: msggrep Invocation. (line 30)
17111 * --output-file, ‘msginit’ option: msginit Invocation. (line 59)
17112 * --output-file, ‘msgmerge’ option: msgmerge Invocation. (line 51)
17113 * --output-file, ‘msgunfmt’ option: msgunfmt Invocation. (line 93)
17114 * --output-file, ‘msguniq’ option: msguniq Invocation. (line 37)
17115 * --package-name, ‘xgettext’ option: xgettext Invocation. (line 456)
17116 * --package-version, ‘xgettext’ option: xgettext Invocation. (line 459)
17117 * --po-dir, ‘gettextize’ option: gettextize Invocation.
17119 * --previous, ‘msgattrib’ option: msgattrib Invocation.
17121 * --previous, ‘msgmerge’ option: msgmerge Invocation. (line 104)
17122 * --properties-input, ‘msgattrib’ option: msgattrib Invocation.
17124 * --properties-input, ‘msgcat’ option: msgcat Invocation. (line 70)
17125 * --properties-input, ‘msgcmp’ option: msgcmp Invocation. (line 57)
17126 * --properties-input, ‘msgcomm’ option: msgcomm Invocation. (line 69)
17127 * --properties-input, ‘msgconv’ option: msgconv Invocation. (line 49)
17128 * --properties-input, ‘msgen’ option: msgen Invocation. (line 46)
17129 * --properties-input, ‘msgexec’ option: msgexec Invocation. (line 65)
17130 * --properties-input, ‘msgfilter’ option: msgfilter Invocation.
17132 * --properties-input, ‘msgfmt’ option: msgfmt Invocation. (line 214)
17133 * --properties-input, ‘msggrep’ option: msggrep Invocation. (line 122)
17134 * --properties-input, ‘msginit’ option: msginit Invocation. (line 70)
17135 * --properties-input, ‘msgmerge’ option: msgmerge Invocation. (line 112)
17136 * --properties-input, ‘msguniq’ option: msguniq Invocation. (line 58)
17137 * --properties-output, ‘msgattrib’ option: msgattrib Invocation.
17139 * --properties-output, ‘msgcat’ option: msgcat Invocation. (line 129)
17140 * --properties-output, ‘msgcomm’ option: msgcomm Invocation. (line 115)
17141 * --properties-output, ‘msgconv’ option: msgconv Invocation. (line 95)
17142 * --properties-output, ‘msgen’ option: msgen Invocation. (line 98)
17143 * --properties-output, ‘msgfilter’ option: msgfilter Invocation.
17145 * --properties-output, ‘msggrep’ option: msggrep Invocation. (line 167)
17146 * --properties-output, ‘msginit’ option: msginit Invocation. (line 102)
17147 * --properties-output, ‘msgmerge’ option: msgmerge Invocation.
17149 * --properties-output, ‘msgunfmt’ option: msgunfmt Invocation.
17151 * --properties-output, ‘msguniq’ option: msguniq Invocation. (line 112)
17152 * --properties-output, ‘xgettext’ option: xgettext Invocation.
17154 * --qt, ‘msgfmt’ option: msgfmt Invocation. (line 46)
17155 * --qt, ‘xgettext’ option: xgettext Invocation. (line 321)
17156 * --quiet, ‘msgfilter’ option: msgfilter Invocation.
17158 * --quiet, ‘msgmerge’ option: msgmerge Invocation. (line 213)
17159 * --regexp=, ‘msggrep’ option: msggrep Invocation. (line 102)
17160 * --repeated, ‘msguniq’ option: msguniq Invocation. (line 47)
17161 * --resource, ‘msgfmt’ option: msgfmt Invocation. (line 79)
17162 * --resource, ‘msgfmt’ option <1>: msgfmt Invocation. (line 102)
17163 * --resource, ‘msgunfmt’ option: msgunfmt Invocation. (line 41)
17164 * --resource, ‘msgunfmt’ option <1>: msgunfmt Invocation. (line 58)
17165 * --sentence-end, ‘xgettext’ option: xgettext Invocation. (line 152)
17166 * --set-fuzzy, ‘msgattrib’ option: msgattrib Invocation.
17168 * --set-obsolete, ‘msgattrib’ option: msgattrib Invocation.
17170 * --silent, ‘msgfilter’ option: msgfilter Invocation.
17172 * --silent, ‘msgmerge’ option: msgmerge Invocation. (line 213)
17173 * --sort-by-file, ‘msgattrib’ option: msgattrib Invocation.
17175 * --sort-by-file, ‘msgcat’ option: msgcat Invocation. (line 157)
17176 * --sort-by-file, ‘msgcomm’ option: msgcomm Invocation. (line 143)
17177 * --sort-by-file, ‘msgconv’ option: msgconv Invocation. (line 123)
17178 * --sort-by-file, ‘msgen’ option: msgen Invocation. (line 126)
17179 * --sort-by-file, ‘msgfilter’ option: msgfilter Invocation.
17181 * --sort-by-file, ‘msggrep’ option: msggrep Invocation. (line 193)
17182 * --sort-by-file, ‘msgmerge’ option: msgmerge Invocation. (line 193)
17183 * --sort-by-file, ‘msguniq’ option: msguniq Invocation. (line 140)
17184 * --sort-by-file, ‘xgettext’ option: xgettext Invocation. (line 421)
17185 * --sort-output, ‘msgattrib’ option: msgattrib Invocation.
17187 * --sort-output, ‘msgcat’ option: msgcat Invocation. (line 152)
17188 * --sort-output, ‘msgcomm’ option: msgcomm Invocation. (line 138)
17189 * --sort-output, ‘msgconv’ option: msgconv Invocation. (line 118)
17190 * --sort-output, ‘msgen’ option: msgen Invocation. (line 121)
17191 * --sort-output, ‘msgfilter’ option: msgfilter Invocation.
17193 * --sort-output, ‘msggrep’ option: msggrep Invocation. (line 189)
17194 * --sort-output, ‘msgmerge’ option: msgmerge Invocation. (line 188)
17195 * --sort-output, ‘msgunfmt’ option: msgunfmt Invocation. (line 147)
17196 * --sort-output, ‘msguniq’ option: msguniq Invocation. (line 135)
17197 * --sort-output, ‘xgettext’ option: xgettext Invocation. (line 416)
17198 * --source, ‘msgfmt’ option: msgfmt Invocation. (line 91)
17199 * --statistics, ‘msgfmt’ option: msgfmt Invocation. (line 318)
17200 * --strict, ‘msgattrib’ option: msgattrib Invocation.
17202 * --strict, ‘msgcat’ option: msgcat Invocation. (line 123)
17203 * --strict, ‘msgcomm’ option: msgcomm Invocation. (line 109)
17204 * --strict, ‘msgconv’ option: msgconv Invocation. (line 89)
17205 * --strict, ‘msgen’ option: msgen Invocation. (line 92)
17206 * --strict, ‘msgfilter’ option: msgfilter Invocation.
17208 * --strict, ‘msgfmt’ option: msgfmt Invocation. (line 62)
17209 * --strict, ‘msggrep’ option: msggrep Invocation. (line 161)
17210 * --strict, ‘msgmerge’ option: msgmerge Invocation. (line 159)
17211 * --strict, ‘msgunfmt’ option: msgunfmt Invocation. (line 118)
17212 * --strict, ‘msguniq’ option: msguniq Invocation. (line 106)
17213 * --strict, ‘xgettext’ option: xgettext Invocation. (line 380)
17214 * --stringtable-input, ‘msgattrib’ option: msgattrib Invocation.
17216 * --stringtable-input, ‘msgcat’ option: msgcat Invocation. (line 74)
17217 * --stringtable-input, ‘msgcmp’ option: msgcmp Invocation. (line 61)
17218 * --stringtable-input, ‘msgcomm’ option: msgcomm Invocation. (line 73)
17219 * --stringtable-input, ‘msgen’ option: msgen Invocation. (line 50)
17220 * --stringtable-input, ‘msgexec’ option: msgexec Invocation. (line 69)
17221 * --stringtable-input, ‘msgfilter’ option: msgfilter Invocation.
17223 * --stringtable-input, ‘msgfmt’ option: msgfmt Invocation. (line 218)
17224 * --stringtable-input, ‘msggrep’ option: msggrep Invocation. (line 126)
17225 * --stringtable-input, ‘msginit’ option: msginit Invocation. (line 74)
17226 * --stringtable-input, ‘msgmerge’ option: msgmerge Invocation.
17228 * --stringtable-input, ‘msgonv’ option: msgconv Invocation. (line 53)
17229 * --stringtable-input, ‘msguniq’ option: msguniq Invocation. (line 62)
17230 * --stringtable-output, ‘msgattrib’ option: msgattrib Invocation.
17232 * --stringtable-output, ‘msgcat’ option: msgcat Invocation. (line 134)
17233 * --stringtable-output, ‘msgcomm’ option: msgcomm Invocation. (line 120)
17234 * --stringtable-output, ‘msgconv’ option: msgconv Invocation. (line 100)
17235 * --stringtable-output, ‘msgen’ option: msgen Invocation. (line 103)
17236 * --stringtable-output, ‘msgfilter’ option: msgfilter Invocation.
17238 * --stringtable-output, ‘msggrep’ option: msggrep Invocation. (line 172)
17239 * --stringtable-output, ‘msginit’ option: msginit Invocation. (line 107)
17240 * --stringtable-output, ‘msgmerge’ option: msgmerge Invocation.
17242 * --stringtable-output, ‘msgunfmt’ option: msgunfmt Invocation.
17244 * --stringtable-output, ‘msguniq’ option: msguniq Invocation. (line 117)
17245 * --stringtable-output, ‘xgettext’ option: xgettext Invocation.
17247 * --style, ‘msgattrib’ option: msgattrib Invocation.
17249 * --style, ‘msgcat’ option: msgcat Invocation. (line 99)
17250 * --style, ‘msgcat’ option <1>: The --style option. (line 6)
17251 * --style, ‘msgcomm’ option: msgcomm Invocation. (line 85)
17252 * --style, ‘msgconv’ option: msgconv Invocation. (line 65)
17253 * --style, ‘msgen’ option: msgen Invocation. (line 68)
17254 * --style, ‘msgfilter’ option: msgfilter Invocation.
17256 * --style, ‘msggrep’ option: msggrep Invocation. (line 138)
17257 * --style, ‘msginit’ option: msginit Invocation. (line 97)
17258 * --style, ‘msgmerge’ option: msgmerge Invocation. (line 135)
17259 * --style, ‘msgunfmt’ option: msgunfmt Invocation. (line 107)
17260 * --style, ‘msguniq’ option: msguniq Invocation. (line 82)
17261 * --style, ‘xgettext’ option: xgettext Invocation. (line 354)
17262 * --suffix, ‘msgmerge’ option: msgmerge Invocation. (line 65)
17263 * --symlink, ‘gettextize’ option: gettextize Invocation.
17265 * --tcl, ‘msgfmt’ option: msgfmt Invocation. (line 43)
17266 * --tcl, ‘msgunfmt’ option: msgunfmt Invocation. (line 26)
17267 * --template, ‘msgfmt’ option: msgfmt Invocation. (line 136)
17268 * --template, ‘msgfmt’ option <1>: msgfmt Invocation. (line 176)
17269 * --to-code, ‘msgcat’ option: msgcat Invocation. (line 82)
17270 * --to-code, ‘msgconv’ option: msgconv Invocation. (line 40)
17271 * --to-code, ‘msguniq’ option: msguniq Invocation. (line 70)
17272 * --translated, ‘msgattrib’ option: msgattrib Invocation.
17274 * --trigraphs, ‘xgettext’ option: xgettext Invocation. (line 316)
17275 * --unique, ‘msgcat’ option: msgcat Invocation. (line 62)
17276 * --unique, ‘msgcomm’ option: msgcomm Invocation. (line 61)
17277 * --unique, ‘msguniq’ option: msguniq Invocation. (line 51)
17278 * --untranslated, ‘msgattrib’ option: msgattrib Invocation.
17280 * --update, ‘msgmerge’ option: msgmerge Invocation. (line 44)
17281 * --use-first, ‘msgcat’ option: msgcat Invocation. (line 85)
17282 * --use-first, ‘msguniq’ option: msguniq Invocation. (line 73)
17283 * --use-fuzzy, ‘msgcmp’ option: msgcmp Invocation. (line 43)
17284 * --use-fuzzy, ‘msgfmt’ option: msgfmt Invocation. (line 279)
17285 * --use-untranslated, ‘msgcmp’ option: msgcmp Invocation. (line 49)
17286 * --variables, ‘envsubst’ option: envsubst Invocation. (line 15)
17287 * --verbose, ‘msgfmt’ option: msgfmt Invocation. (line 324)
17288 * --verbose, ‘msgmerge’ option: msgmerge Invocation. (line 208)
17289 * --verbose, ‘msgunfmt’ option: msgunfmt Invocation. (line 163)
17290 * --version, ‘autopoint’ option: autopoint Invocation.
17292 * --version, ‘envsubst’ option: envsubst Invocation. (line 25)
17293 * --version, ‘gettext’ option: gettext Invocation. (line 40)
17294 * --version, ‘gettextize’ option: gettextize Invocation.
17296 * --version, ‘msgattrib’ option: msgattrib Invocation.
17298 * --version, ‘msgcat’ option: msgcat Invocation. (line 168)
17299 * --version, ‘msgcmp’ option: msgcmp Invocation. (line 73)
17300 * --version, ‘msgcomm’ option: msgcomm Invocation. (line 157)
17301 * --version, ‘msgconv’ option: msgconv Invocation. (line 134)
17302 * --version, ‘msgen’ option: msgen Invocation. (line 137)
17303 * --version, ‘msgexec’ option: msgexec Invocation. (line 81)
17304 * --version, ‘msgfilter’ option: msgfilter Invocation.
17306 * --version, ‘msgfmt’ option: msgfmt Invocation. (line 315)
17307 * --version, ‘msggrep’ option: msggrep Invocation. (line 204)
17308 * --version, ‘msginit’ option: msginit Invocation. (line 132)
17309 * --version, ‘msgmerge’ option: msgmerge Invocation. (line 204)
17310 * --version, ‘msgunfmt’ option: msgunfmt Invocation. (line 159)
17311 * --version, ‘msguniq’ option: msguniq Invocation. (line 151)
17312 * --version, ‘ngettext’ option: ngettext Invocation. (line 35)
17313 * --version, ‘xgettext’ option: xgettext Invocation. (line 501)
17314 * --width, ‘msgattrib’ option: msgattrib Invocation.
17316 * --width, ‘msgcat’ option: msgcat Invocation. (line 139)
17317 * --width, ‘msgcomm’ option: msgcomm Invocation. (line 125)
17318 * --width, ‘msgconv’ option: msgconv Invocation. (line 105)
17319 * --width, ‘msgen’ option: msgen Invocation. (line 108)
17320 * --width, ‘msgfilter’ option: msgfilter Invocation.
17322 * --width, ‘msggrep’ option: msggrep Invocation. (line 177)
17323 * --width, ‘msginit’ option: msginit Invocation. (line 112)
17324 * --width, ‘msgmerge’ option: msgmerge Invocation. (line 175)
17325 * --width, ‘msgunfmt’ option: msgunfmt Invocation. (line 134)
17326 * --width, ‘msguniq’ option: msguniq Invocation. (line 122)
17327 * --width, ‘xgettext’ option: xgettext Invocation. (line 403)
17328 * --xml, ‘msgfmt’ option: msgfmt Invocation. (line 52)
17329 * -<, ‘msgcat’ option: msgcat Invocation. (line 52)
17330 * -<, ‘msgcomm’ option: msgcomm Invocation. (line 51)
17331 * ->, ‘msgcat’ option: msgcat Invocation. (line 57)
17332 * ->, ‘msgcomm’ option: msgcomm Invocation. (line 56)
17333 * -a, ‘msgfmt’ option: msgfmt Invocation. (line 288)
17334 * -a, ‘xgettext’ option: xgettext Invocation. (line 165)
17335 * -c, ‘msgfmt’ option: msgfmt Invocation. (line 226)
17336 * -C, ‘msgfmt’ option: msgfmt Invocation. (line 263)
17337 * -C, ‘msggrep’ option: msggrep Invocation. (line 86)
17338 * -C, ‘msgmerge’ option: msgmerge Invocation. (line 36)
17339 * -C, ‘xgettext’ option: xgettext Invocation. (line 63)
17340 * -c, ‘xgettext’ option: xgettext Invocation. (line 94)
17341 * -d, ‘autopoint’ option: autopoint Invocation.
17343 * -d, ‘gettext’ option: gettext Invocation. (line 16)
17344 * -d, ‘gettextize’ option: gettextize Invocation.
17346 * -D, ‘msgattrib’ option: msgattrib Invocation.
17348 * -D, ‘msgcat’ option: msgcat Invocation. (line 31)
17349 * -D, ‘msgcmp’ option: msgcmp Invocation. (line 27)
17350 * -D, ‘msgcomm’ option: msgcomm Invocation. (line 30)
17351 * -D, ‘msgconv’ option: msgconv Invocation. (line 19)
17352 * -D, ‘msgen’ option: msgen Invocation. (line 25)
17353 * -D, ‘msgexec’ option: msgexec Invocation. (line 54)
17354 * -D, ‘msgfilter’ option: msgfilter Invocation.
17356 * -D, ‘msgfmt’ option: msgfmt Invocation. (line 18)
17357 * -d, ‘msgfmt’ option: msgfmt Invocation. (line 88)
17358 * -d, ‘msgfmt’ option <1>: msgfmt Invocation. (line 111)
17359 * -d, ‘msgfmt’ option <2>: msgfmt Invocation. (line 127)
17360 * -d, ‘msgfmt’ option <3>: msgfmt Invocation. (line 151)
17361 * -d, ‘msgfmt’ option <4>: msgfmt Invocation. (line 189)
17362 * -D, ‘msggrep’ option: msggrep Invocation. (line 19)
17363 * -D, ‘msgmerge’ option: msgmerge Invocation. (line 30)
17364 * -d, ‘msgunfmt’ option: msgunfmt Invocation. (line 67)
17365 * -d, ‘msgunfmt’ option <1>: msgunfmt Invocation. (line 83)
17366 * -D, ‘msguniq’ option: msguniq Invocation. (line 26)
17367 * -d, ‘msguniq’ option: msguniq Invocation. (line 47)
17368 * -d, ‘ngettext’ option: ngettext Invocation. (line 15)
17369 * -D, ‘xgettext’ option: xgettext Invocation. (line 24)
17370 * -d, ‘xgettext’ option: xgettext Invocation. (line 35)
17371 * -e, ‘gettext’ option: gettext Invocation. (line 20)
17372 * -E, ‘gettext’ option: gettext Invocation. (line 27)
17373 * -e, ‘msgfilter’ option: msgfilter Invocation.
17375 * -E, ‘msggrep’ option: msggrep Invocation. (line 94)
17376 * -e, ‘msggrep’ option: msggrep Invocation. (line 102)
17377 * -e, ‘ngettext’ option: ngettext Invocation. (line 19)
17378 * -E, ‘ngettext’ option: ngettext Invocation. (line 26)
17379 * -f, ‘autopoint’ option: autopoint Invocation.
17381 * -f, ‘gettextize’ option: gettextize Invocation.
17383 * -F, ‘msgattrib’ option: msgattrib Invocation.
17385 * -f, ‘msgcat’ option: msgcat Invocation. (line 26)
17386 * -F, ‘msgcat’ option: msgcat Invocation. (line 157)
17387 * -f, ‘msgcomm’ option: msgcomm Invocation. (line 25)
17388 * -F, ‘msgcomm’ option: msgcomm Invocation. (line 143)
17389 * -F, ‘msgconv’ option: msgconv Invocation. (line 123)
17390 * -F, ‘msgen’ option: msgen Invocation. (line 126)
17391 * -f, ‘msgfilter’ option: msgfilter Invocation.
17393 * -F, ‘msgfilter’ option: msgfilter Invocation.
17395 * -f, ‘msgfmt’ option: msgfmt Invocation. (line 279)
17396 * -F, ‘msggrep’ option: msggrep Invocation. (line 98)
17397 * -f, ‘msggrep’ option: msggrep Invocation. (line 106)
17398 * -F, ‘msgmerge’ option: msgmerge Invocation. (line 193)
17399 * -F, ‘msguniq’ option: msguniq Invocation. (line 140)
17400 * -f, ‘xgettext’ option: xgettext Invocation. (line 19)
17401 * -F, ‘xgettext’ option: xgettext Invocation. (line 421)
17402 * -h, ‘envsubst’ option: envsubst Invocation. (line 21)
17403 * -h, ‘gettext’ option: gettext Invocation. (line 32)
17404 * -h, ‘msgattrib’ option: msgattrib Invocation.
17406 * -h, ‘msgcat’ option: msgcat Invocation. (line 164)
17407 * -h, ‘msgcmp’ option: msgcmp Invocation. (line 69)
17408 * -h, ‘msgcomm’ option: msgcomm Invocation. (line 153)
17409 * -h, ‘msgconv’ option: msgconv Invocation. (line 130)
17410 * -h, ‘msgen’ option: msgen Invocation. (line 133)
17411 * -h, ‘msgexec’ option: msgexec Invocation. (line 77)
17412 * -h, ‘msgfilter’ option: msgfilter Invocation.
17414 * -h, ‘msgfmt’ option: msgfmt Invocation. (line 311)
17415 * -h, ‘msggrep’ option: msggrep Invocation. (line 200)
17416 * -h, ‘msginit’ option: msginit Invocation. (line 128)
17417 * -h, ‘msgmerge’ option: msgmerge Invocation. (line 200)
17418 * -h, ‘msgunfmt’ option: msgunfmt Invocation. (line 155)
17419 * -h, ‘msguniq’ option: msguniq Invocation. (line 147)
17420 * -h, ‘ngettext’ option: ngettext Invocation. (line 31)
17421 * -h, ‘xgettext’ option: xgettext Invocation. (line 497)
17422 * -i, ‘msgattrib’ option: msgattrib Invocation.
17424 * -i, ‘msgcat’ option: msgcat Invocation. (line 107)
17425 * -i, ‘msgcomm’ option: msgcomm Invocation. (line 93)
17426 * -i, ‘msgconv’ option: msgconv Invocation. (line 73)
17427 * -i, ‘msgen’ option: msgen Invocation. (line 76)
17428 * -i, ‘msgexec’ option: msgexec Invocation. (line 50)
17429 * -i, ‘msgfilter’ option: msgfilter Invocation.
17431 * -i, ‘msggrep’ option: msggrep Invocation. (line 110)
17432 * -i, ‘msginit’ option: msginit Invocation. (line 49)
17433 * -i, ‘msgmerge’ option: msgmerge Invocation. (line 143)
17434 * -i, ‘msgunfmt’ option: msgunfmt Invocation. (line 115)
17435 * -i, ‘msguniq’ option: msguniq Invocation. (line 90)
17436 * -i, ‘xgettext’ option: xgettext Invocation. (line 362)
17437 * -j, ‘msgfmt’ option: msgfmt Invocation. (line 30)
17438 * -J, ‘msggrep’ option: msggrep Invocation. (line 74)
17439 * -j, ‘msgunfmt’ option: msgunfmt Invocation. (line 16)
17440 * -j, ‘xgettext’ option: xgettext Invocation. (line 85)
17441 * -k, ‘msgfmt’ option: msgfmt Invocation. (line 140)
17442 * -K, ‘msggrep’ option: msggrep Invocation. (line 78)
17443 * -k, ‘xgettext’ option: xgettext Invocation. (line 174)
17444 * -l, ‘msgfmt’ option: msgfmt Invocation. (line 83)
17445 * -l, ‘msgfmt’ option <1>: msgfmt Invocation. (line 106)
17446 * -l, ‘msgfmt’ option <2>: msgfmt Invocation. (line 122)
17447 * -l, ‘msgfmt’ option <3>: msgfmt Invocation. (line 146)
17448 * -L, ‘msgfmt’ option: msgfmt Invocation. (line 180)
17449 * -l, ‘msgfmt’ option <4>: msgfmt Invocation. (line 184)
17450 * -l, ‘msginit’ option: msginit Invocation. (line 82)
17451 * -l, ‘msgunfmt’ option: msgunfmt Invocation. (line 45)
17452 * -l, ‘msgunfmt’ option <1>: msgunfmt Invocation. (line 62)
17453 * -l, ‘msgunfmt’ option <2>: msgunfmt Invocation. (line 78)
17454 * -L, ‘xgettext’ option: xgettext Invocation. (line 54)
17455 * -m, ‘msgcmp’ option: msgcmp Invocation. (line 35)
17456 * -M, ‘msggrep’ option: msggrep Invocation. (line 70)
17457 * -m, ‘msgmerge’ option: msgmerge Invocation. (line 96)
17458 * -m, ‘xgettext’ option: xgettext Invocation. (line 486)
17459 * -M, ‘xgettext’ option: xgettext Invocation. (line 490)
17460 * -n, ‘gettext’ option: gettext Invocation. (line 35)
17461 * -n, ‘msgattrib’ option: msgattrib Invocation.
17463 * -n, ‘msgcat’ option: msgcat Invocation. (line 114)
17464 * -N, ‘msgcmp’ option: msgcmp Invocation. (line 39)
17465 * -n, ‘msgcomm’ option: msgcomm Invocation. (line 100)
17466 * -n, ‘msgfilter’ option: msgfilter Invocation.
17468 * -N, ‘msggrep’ option: msggrep Invocation. (line 65)
17469 * -N, ‘msgmerge’ option: msgmerge Invocation. (line 100)
17470 * -n, ‘msguniq’ option: msguniq Invocation. (line 97)
17471 * -n, ‘xgettext’ option: xgettext Invocation. (line 371)
17472 * -o, ‘msgattrib’ option: msgattrib Invocation.
17474 * -o, ‘msgcat’ option: msgcat Invocation. (line 42)
17475 * -o, ‘msgcomm’ option: msgcomm Invocation. (line 41)
17476 * -o, ‘msgconv’ option: msgconv Invocation. (line 30)
17477 * -o, ‘msgen’ option: msgen Invocation. (line 36)
17478 * -o, ‘msgfilter’ option: msgfilter Invocation.
17480 * -o, ‘msgfmt’ option: msgfmt Invocation. (line 59)
17481 * -o, ‘msggrep’ option: msggrep Invocation. (line 30)
17482 * -o, ‘msginit’ option: msginit Invocation. (line 59)
17483 * -o, ‘msgmerge’ option: msgmerge Invocation. (line 51)
17484 * -o, ‘msgunfmt’ option: msgunfmt Invocation. (line 93)
17485 * -o, ‘msguniq’ option: msguniq Invocation. (line 37)
17486 * -o, ‘xgettext’ option: xgettext Invocation. (line 39)
17487 * -P, ‘msgattrib’ option: msgattrib Invocation.
17489 * -p, ‘msgattrib’ option: msgattrib Invocation.
17491 * -P, ‘msgcat’ option: msgcat Invocation. (line 70)
17492 * -p, ‘msgcat’ option: msgcat Invocation. (line 129)
17493 * -P, ‘msgcmp’ option: msgcmp Invocation. (line 57)
17494 * -P, ‘msgcomm’ option: msgcomm Invocation. (line 69)
17495 * -p, ‘msgcomm’ option: msgcomm Invocation. (line 115)
17496 * -P, ‘msgconv’ option: msgconv Invocation. (line 49)
17497 * -p, ‘msgconv’ option: msgconv Invocation. (line 95)
17498 * -P, ‘msgen’ option: msgen Invocation. (line 46)
17499 * -p, ‘msgen’ option: msgen Invocation. (line 98)
17500 * -P, ‘msgexec’ option: msgexec Invocation. (line 65)
17501 * -P, ‘msgfilter’ option: msgfilter Invocation.
17503 * -p, ‘msgfilter’ option: msgfilter Invocation.
17505 * -P, ‘msgfmt’ option: msgfmt Invocation. (line 214)
17506 * -P, ‘msggrep’ option: msggrep Invocation. (line 122)
17507 * -p, ‘msggrep’ option: msggrep Invocation. (line 167)
17508 * -P, ‘msginit’ option: msginit Invocation. (line 70)
17509 * -p, ‘msginit’ option: msginit Invocation. (line 102)
17510 * -P, ‘msgmerge’ option: msgmerge Invocation. (line 112)
17511 * -p, ‘msgmerge’ option: msgmerge Invocation. (line 165)
17512 * -p, ‘msgunfmt’ option: msgunfmt Invocation. (line 124)
17513 * -P, ‘msguniq’ option: msguniq Invocation. (line 58)
17514 * -p, ‘msguniq’ option: msguniq Invocation. (line 112)
17515 * -p, ‘xgettext’ option: xgettext Invocation. (line 44)
17516 * -q, ‘msgmerge’ option: msgmerge Invocation. (line 213)
17517 * -r, ‘msgfmt’ option: msgfmt Invocation. (line 79)
17518 * -r, ‘msgfmt’ option <1>: msgfmt Invocation. (line 102)
17519 * -r, ‘msgunfmt’ option: msgunfmt Invocation. (line 41)
17520 * -r, ‘msgunfmt’ option <1>: msgunfmt Invocation. (line 58)
17521 * -s, ‘msgattrib’ option: msgattrib Invocation.
17523 * -s, ‘msgcat’ option: msgcat Invocation. (line 152)
17524 * -s, ‘msgcomm’ option: msgcomm Invocation. (line 138)
17525 * -s, ‘msgconv’ option: msgconv Invocation. (line 118)
17526 * -s, ‘msgen’ option: msgen Invocation. (line 121)
17527 * -s, ‘msgfilter’ option: msgfilter Invocation.
17529 * -s, ‘msgmerge’ option: msgmerge Invocation. (line 188)
17530 * -s, ‘msgunfmt’ option: msgunfmt Invocation. (line 147)
17531 * -s, ‘msguniq’ option: msguniq Invocation. (line 135)
17532 * -s, ‘xgettext’ option: xgettext Invocation. (line 416)
17533 * -t, ‘msgcat’ option: msgcat Invocation. (line 82)
17534 * -t, ‘msgconv’ option: msgconv Invocation. (line 40)
17535 * -T, ‘msggrep’ option: msggrep Invocation. (line 82)
17536 * -t, ‘msguniq’ option: msguniq Invocation. (line 70)
17537 * -T, ‘xgettext’ option: xgettext Invocation. (line 316)
17538 * -u, ‘msgcat’ option: msgcat Invocation. (line 62)
17539 * -u, ‘msgcomm’ option: msgcomm Invocation. (line 61)
17540 * -U, ‘msgmerge’ option: msgmerge Invocation. (line 44)
17541 * -u, ‘msguniq’ option: msguniq Invocation. (line 51)
17542 * -v, ‘envsubst’ option: envsubst Invocation. (line 15)
17543 * -V, ‘envsubst’ option: envsubst Invocation. (line 25)
17544 * -V, ‘gettext’ option: gettext Invocation. (line 40)
17545 * -V, ‘msgattrib’ option: msgattrib Invocation.
17547 * -V, ‘msgcat’ option: msgcat Invocation. (line 168)
17548 * -V, ‘msgcmp’ option: msgcmp Invocation. (line 73)
17549 * -V, ‘msgcomm’ option: msgcomm Invocation. (line 157)
17550 * -V, ‘msgconv’ option: msgconv Invocation. (line 134)
17551 * -V, ‘msgen’ option: msgen Invocation. (line 137)
17552 * -V, ‘msgexec’ option: msgexec Invocation. (line 81)
17553 * -V, ‘msgfilter’ option: msgfilter Invocation.
17555 * -V, ‘msgfmt’ option: msgfmt Invocation. (line 315)
17556 * -v, ‘msgfmt’ option: msgfmt Invocation. (line 324)
17557 * -v, ‘msggrep’ option: msggrep Invocation. (line 114)
17558 * -V, ‘msggrep’ option: msggrep Invocation. (line 204)
17559 * -V, ‘msginit’ option: msginit Invocation. (line 132)
17560 * -V, ‘msgmerge’ option: msgmerge Invocation. (line 204)
17561 * -v, ‘msgmerge’ option: msgmerge Invocation. (line 208)
17562 * -V, ‘msgunfmt’ option: msgunfmt Invocation. (line 159)
17563 * -v, ‘msgunfmt’ option: msgunfmt Invocation. (line 163)
17564 * -V, ‘msguniq’ option: msguniq Invocation. (line 151)
17565 * -V, ‘ngettext’ option: ngettext Invocation. (line 35)
17566 * -V, ‘xgettext’ option: xgettext Invocation. (line 501)
17567 * -w, ‘msgattrib’ option: msgattrib Invocation.
17569 * -w, ‘msgcat’ option: msgcat Invocation. (line 139)
17570 * -w, ‘msgcomm’ option: msgcomm Invocation. (line 125)
17571 * -w, ‘msgconv’ option: msgconv Invocation. (line 105)
17572 * -w, ‘msgen’ option: msgen Invocation. (line 108)
17573 * -w, ‘msgfilter’ option: msgfilter Invocation.
17575 * -w, ‘msggrep’ option: msggrep Invocation. (line 177)
17576 * -w, ‘msginit’ option: msginit Invocation. (line 112)
17577 * -w, ‘msgmerge’ option: msgmerge Invocation. (line 175)
17578 * -w, ‘msgunfmt’ option: msgunfmt Invocation. (line 134)
17579 * -w, ‘msguniq’ option: msguniq Invocation. (line 122)
17580 * -w, ‘xgettext’ option: xgettext Invocation. (line 403)
17581 * -X, ‘msggrep’ option: msggrep Invocation. (line 90)
17582 * -x, ‘xgettext’ option: xgettext Invocation. (line 89)
17585 File: gettext.info, Node: Variable Index, Next: PO Mode Index, Prev: Option Index, Up: Top
17593 * GETTEXT_LOG_UNTRANSLATED, environment variable: Prioritizing messages.
17595 * LANG, environment variable: Locale Environment Variables.
17597 * LANG, environment variable <1>: gettext grok. (line 30)
17598 * LANGUAGE, environment variable: Locale Environment Variables.
17600 * LANGUAGE, environment variable <1>: gettext grok. (line 28)
17601 * LANGUAGE, environment variable <2>: po/Rules-*. (line 11)
17602 * LC_ALL, environment variable: Locale Environment Variables.
17604 * LC_ALL, environment variable <1>: gettext grok. (line 28)
17605 * LC_COLLATE, environment variable: Locale Environment Variables.
17607 * LC_COLLATE, environment variable <1>: gettext grok. (line 29)
17608 * LC_CTYPE, environment variable: Locale Environment Variables.
17610 * LC_CTYPE, environment variable <1>: gettext grok. (line 29)
17611 * LC_MESSAGES, environment variable: Locale Environment Variables.
17613 * LC_MESSAGES, environment variable <1>: gettext grok. (line 29)
17614 * LC_MONETARY, environment variable: Locale Environment Variables.
17616 * LC_MONETARY, environment variable <1>: gettext grok. (line 29)
17617 * LC_NUMERIC, environment variable: Locale Environment Variables.
17619 * LC_NUMERIC, environment variable <1>: gettext grok. (line 29)
17620 * LC_TIME, environment variable: Locale Environment Variables.
17622 * LC_TIME, environment variable <1>: gettext grok. (line 29)
17623 * LINGUAS, environment variable: Installers. (line 17)
17624 * MSGEXEC_LOCATION, environment variable: msgexec Invocation. (line 21)
17625 * MSGEXEC_MSGCTXT, environment variable: msgexec Invocation. (line 21)
17626 * MSGEXEC_MSGID, environment variable: msgexec Invocation. (line 21)
17627 * MSGEXEC_MSGID_PLURAL, environment variable: msgexec Invocation.
17629 * MSGEXEC_PLURAL_FORM, environment variable: msgexec Invocation.
17631 * MSGEXEC_PREV_MSGCTXT, environment variable: msgexec Invocation.
17633 * MSGEXEC_PREV_MSGID, environment variable: msgexec Invocation.
17635 * MSGEXEC_PREV_MSGID_PLURAL, environment variable: msgexec Invocation.
17637 * MSGFILTER_LOCATION, environment variable: msgfilter Invocation.
17639 * MSGFILTER_MSGCTXT, environment variable: msgfilter Invocation.
17641 * MSGFILTER_MSGID, environment variable: msgfilter Invocation. (line 11)
17642 * MSGFILTER_MSGID_PLURAL, environment variable: msgfilter Invocation.
17644 * MSGFILTER_PLURAL_FORM, environment variable: msgfilter Invocation.
17646 * MSGFILTER_PREV_MSGCTXT, environment variable: msgfilter Invocation.
17648 * MSGFILTER_PREV_MSGID, environment variable: msgfilter Invocation.
17650 * MSGFILTER_PREV_MSGID_PLURAL, environment variable: msgfilter Invocation.
17652 * PO_STYLE, environment variable: The --style option. (line 10)
17653 * TERM, environment variable: The TERM variable. (line 6)
17654 * TEXTDOMAIN, environment variable: sh. (line 23)
17655 * TEXTDOMAINDIR, environment variable: sh. (line 26)
17658 File: gettext.info, Node: PO Mode Index, Next: Autoconf Macro Index, Prev: Variable Index, Up: Top
17666 * #, PO Mode command: Modifying Comments. (line 24)
17667 * #, PO Mode command <1>: Modifying Comments. (line 45)
17668 * ,, PO Mode command: Marking. (line 43)
17669 * ., PO Mode command: Entry Positioning. (line 20)
17670 * ., PO Mode command <1>: Entry Positioning. (line 45)
17671 * ‘.emacs’ customizations: Installation. (line 13)
17672 * 0, PO Mode command: Main PO Commands. (line 40)
17673 * 0, PO Mode command <1>: Main PO Commands. (line 72)
17674 * <, PO Mode command: Entry Positioning. (line 29)
17675 * <, PO Mode command <1>: Entry Positioning. (line 73)
17676 * =, PO Mode command: Main PO Commands. (line 47)
17677 * =, PO Mode command <1>: Main PO Commands. (line 87)
17678 * >, PO Mode command: Entry Positioning. (line 32)
17679 * >, PO Mode command <1>: Entry Positioning. (line 73)
17680 * ?, PO Mode command: Main PO Commands. (line 44)
17681 * ?, PO Mode command <1>: Main PO Commands. (line 83)
17682 * _, PO Mode command: Main PO Commands. (line 30)
17683 * _, PO Mode command <1>: Main PO Commands. (line 52)
17684 * a, PO Mode command: Auxiliary. (line 21)
17685 * A, PO Mode command: Auxiliary. (line 28)
17686 * A, PO Mode command <1>: Auxiliary. (line 35)
17687 * a, PO Mode command <1>: Auxiliary. (line 39)
17688 * auxiliary PO file: Auxiliary. (line 13)
17689 * C-c C-a, PO Mode command: Subedit. (line 17)
17690 * C-c C-a, PO Mode command <1>: Subedit. (line 36)
17691 * C-c C-a, PO Mode command <2>: Auxiliary. (line 25)
17692 * C-c C-a, PO Mode command <3>: Auxiliary. (line 48)
17693 * C-c C-c, PO Mode command: Subedit. (line 11)
17694 * C-c C-c, PO Mode command <1>: Subedit. (line 19)
17695 * C-c C-k, PO Mode command: Subedit. (line 14)
17696 * C-c C-k, PO Mode command <1>: Subedit. (line 27)
17697 * C-j, PO Mode command: Modifying Translations.
17699 * C-j, PO Mode command <1>: Modifying Translations.
17701 * commands: Main PO Commands. (line 6)
17702 * comment out PO file entry: Obsolete Entries. (line 46)
17703 * consulting program sources: C Sources Context. (line 6)
17704 * consulting translations to other languages: Auxiliary. (line 6)
17705 * current entry of a PO file: Entry Positioning. (line 6)
17706 * cut and paste for translated strings: Modifying Translations.
17708 * DEL, PO Mode command: Fuzzy Entries. (line 58)
17709 * DEL, PO Mode command <1>: Obsolete Entries. (line 32)
17710 * DEL, PO Mode command <2>: Obsolete Entries. (line 46)
17711 * editing comments: Modifying Comments. (line 6)
17712 * editing multiple entries: Subedit. (line 64)
17713 * editing translations: Modifying Translations.
17715 * ‘etags’, using for marking strings: Marking. (line 17)
17716 * exiting PO subedit: Subedit. (line 19)
17717 * f, PO Mode command: Fuzzy Entries. (line 29)
17718 * F, PO Mode command: Fuzzy Entries. (line 32)
17719 * f, PO Mode command <1>: Fuzzy Entries. (line 37)
17720 * F, PO Mode command <1>: Fuzzy Entries. (line 37)
17721 * find source fragment for a PO file entry: C Sources Context.
17723 * h, PO Mode command: Main PO Commands. (line 44)
17724 * h, PO Mode command <1>: Main PO Commands. (line 83)
17725 * installing PO mode: Installation. (line 13)
17726 * k, PO Mode command: Untranslated Entries.
17728 * k, PO Mode command <1>: Untranslated Entries.
17730 * k, PO Mode command <2>: Modifying Translations.
17732 * k, PO Mode command <3>: Modifying Translations.
17734 * K, PO Mode command: Modifying Comments. (line 27)
17735 * K, PO Mode command <1>: Modifying Comments. (line 60)
17736 * LFD, PO Mode command: Modifying Translations.
17738 * LFD, PO Mode command <1>: Modifying Translations.
17740 * looking at the source to aid translation: C Sources Context.
17742 * m, PO Mode command: Entry Positioning. (line 35)
17743 * m, PO Mode command <1>: Entry Positioning. (line 91)
17744 * M-,, PO Mode command: Marking. (line 47)
17745 * M-., PO Mode command: Marking. (line 50)
17746 * M-A, PO Mode command: Auxiliary. (line 32)
17747 * M-A, PO Mode command <1>: Auxiliary. (line 35)
17748 * M-s, PO Mode command: C Sources Context. (line 41)
17749 * M-S, PO Mode command: C Sources Context. (line 49)
17750 * M-s, PO Mode command <1>: C Sources Context. (line 52)
17751 * M-S, PO Mode command <1>: C Sources Context. (line 88)
17752 * marking strings for translation: Marking. (line 6)
17753 * moving by fuzzy entries: Fuzzy Entries. (line 23)
17754 * moving by obsolete entries: Obsolete Entries. (line 22)
17755 * moving by translated entries: Translated Entries. (line 12)
17756 * moving by untranslated entries: Untranslated Entries.
17758 * moving through a PO file: Entry Positioning. (line 14)
17759 * n, PO Mode command: Entry Positioning. (line 23)
17760 * n, PO Mode command <1>: Entry Positioning. (line 68)
17761 * next-error, stepping through PO file validation results: Main PO Commands.
17763 * normalize, PO Mode command: Auxiliary. (line 63)
17764 * o, PO Mode command: Obsolete Entries. (line 26)
17765 * O, PO Mode command: Obsolete Entries. (line 29)
17766 * o, PO Mode command <1>: Obsolete Entries. (line 35)
17767 * O, PO Mode command <1>: Obsolete Entries. (line 35)
17768 * obsolete active entry: Obsolete Entries. (line 46)
17769 * p, PO Mode command: Entry Positioning. (line 26)
17770 * p, PO Mode command <1>: Entry Positioning. (line 68)
17771 * pending subedits: Subedit. (line 75)
17772 * po-auto-edit-with-msgid, PO Mode variable: Modifying Translations.
17774 * po-auto-fuzzy-on-edit, PO Mode variable: Translated Entries.
17776 * po-auto-select-on-unfuzzy, PO Mode variable: Fuzzy Entries. (line 42)
17777 * po-confirm-and-quit, PO Mode command: Main PO Commands. (line 61)
17778 * po-consider-as-auxiliary, PO Mode command: Auxiliary. (line 35)
17779 * po-consider-source-path, PO Mode command: C Sources Context.
17781 * po-current-entry, PO Mode command: Entry Positioning. (line 45)
17782 * po-cycle-auxiliary, PO Mode command: Auxiliary. (line 39)
17783 * po-cycle-source-reference, PO Mode command: C Sources Context.
17785 * po-edit-comment, PO Mode command: Modifying Comments. (line 45)
17786 * po-edit-msgstr, PO Mode command: Modifying Translations.
17788 * po-exchange-location, PO Mode command: Entry Positioning. (line 105)
17789 * po-fade-out-entry, PO Mode command: Fuzzy Entries. (line 58)
17790 * po-fade-out-entry, PO Mode command <1>: Obsolete Entries. (line 46)
17791 * po-first-entry, PO Mode command: Entry Positioning. (line 73)
17792 * po-help, PO Mode command: Main PO Commands. (line 83)
17793 * po-ignore-as-auxiliary, PO Mode command: Auxiliary. (line 35)
17794 * po-ignore-source-path, PO Mode command: C Sources Context. (line 88)
17795 * po-kill-comment, PO Mode command: Modifying Comments. (line 60)
17796 * po-kill-msgstr, PO Mode command: Untranslated Entries.
17798 * po-kill-msgstr, PO Mode command <1>: Modifying Translations.
17800 * po-kill-ring-save-comment, PO Mode command: Modifying Comments.
17802 * po-kill-ring-save-msgstr, PO Mode command: Modifying Translations.
17804 * po-last-entry, PO Mode command: Entry Positioning. (line 73)
17805 * po-mark-translatable, PO Mode command: Marking. (line 98)
17806 * po-msgid-to-msgstr, PO Mode command: Modifying Translations.
17808 * po-next-entry, PO Mode command: Entry Positioning. (line 68)
17809 * po-next-fuzzy-entry, PO Mode command: Fuzzy Entries. (line 37)
17810 * po-next-obsolete-entry, PO Mode command: Obsolete Entries. (line 35)
17811 * po-next-translated-entry, PO Mode command: Translated Entries.
17813 * po-next-untranslated-entry, PO Mode command: Untranslated Entries.
17815 * po-normalize, PO Mode command: Normalizing. (line 31)
17816 * po-other-window, PO Mode command: Main PO Commands. (line 72)
17817 * po-pop-location, PO Mode command: Entry Positioning. (line 91)
17818 * po-previous-entry, PO Mode command: Entry Positioning. (line 68)
17819 * po-previous-fuzzy-entry, PO Mode command: Fuzzy Entries. (line 37)
17820 * po-previous-obsolete-entry, PO Mode command: Obsolete Entries.
17822 * po-previous-translated-entry, PO Mode command: Translated Entries.
17824 * po-previous-untransted-entry, PO Mode command: Untranslated Entries.
17826 * po-push-location, PO Mode command: Entry Positioning. (line 91)
17827 * po-quit, PO Mode command: Main PO Commands. (line 61)
17828 * po-select-auxiliary, PO Mode command: Auxiliary. (line 48)
17829 * po-select-mark-and-mark, PO Mode command: Marking. (line 98)
17830 * po-select-source-reference, PO Mode command: C Sources Context.
17832 * po-statistics, PO Mode command: Main PO Commands. (line 87)
17833 * po-subedit-abort, PO Mode command: Subedit. (line 27)
17834 * po-subedit-cycle-auxiliary, PO Mode command: Subedit. (line 36)
17835 * po-subedit-exit, PO Mode command: Subedit. (line 19)
17836 * po-subedit-mode-hook, PO Mode variable: Modifying Comments. (line 57)
17837 * po-tags-search, PO Mode command: Marking. (line 54)
17838 * po-undo, PO Mode command: Main PO Commands. (line 52)
17839 * po-unfuzzy, PO Mode command: Fuzzy Entries. (line 42)
17840 * po-validate, PO Mode command: Main PO Commands. (line 92)
17841 * po-yank-comment, PO Mode command: Modifying Comments. (line 60)
17842 * po-yank-msgstr, PO Mode command: Modifying Translations.
17844 * Q, PO Mode command: Main PO Commands. (line 33)
17845 * q, PO Mode command: Main PO Commands. (line 36)
17846 * Q, PO Mode command <1>: Main PO Commands. (line 61)
17847 * q, PO Mode command <1>: Main PO Commands. (line 61)
17848 * r, PO Mode command: Entry Positioning. (line 39)
17849 * r, PO Mode command <1>: Entry Positioning. (line 91)
17850 * RET, PO Mode command: Modifying Translations.
17852 * RET, PO Mode command <1>: Modifying Translations.
17854 * s, PO Mode command: C Sources Context. (line 37)
17855 * S, PO Mode command: C Sources Context. (line 45)
17856 * s, PO Mode command <1>: C Sources Context. (line 52)
17857 * S, PO Mode command <1>: C Sources Context. (line 88)
17858 * starting a string translation: Modifying Translations.
17860 * string normalization in entries: Normalizing. (line 30)
17861 * subedit minor mode: Subedit. (line 6)
17862 * t, PO Mode command: Translated Entries. (line 16)
17863 * T, PO Mode command: Translated Entries. (line 19)
17864 * t, PO Mode command <1>: Translated Entries. (line 22)
17865 * T, PO Mode command <1>: Translated Entries. (line 22)
17866 * TAB, PO Mode command: Fuzzy Entries. (line 35)
17867 * TAB, PO Mode command <1>: Fuzzy Entries. (line 42)
17868 * ‘TAGS’, and marking translatable strings: Marking. (line 30)
17869 * u, PO Mode command: Untranslated Entries.
17871 * U, PO Mode command: Untranslated Entries.
17873 * u, PO Mode command <1>: Untranslated Entries.
17875 * U, PO Mode command <1>: Untranslated Entries.
17877 * use the source, Luke: C Sources Context. (line 6)
17878 * using obsolete translations to make new entries: Modifying Translations.
17880 * using translation compendia: Compendium. (line 6)
17881 * V, PO Mode command: Main PO Commands. (line 50)
17882 * V, PO Mode command <1>: Main PO Commands. (line 92)
17883 * w, PO Mode command: Modifying Translations.
17885 * w, PO Mode command <1>: Modifying Translations.
17887 * W, PO Mode command: Modifying Comments. (line 31)
17888 * W, PO Mode command <1>: Modifying Comments. (line 60)
17889 * x, PO Mode command: Entry Positioning. (line 42)
17890 * x, PO Mode command <1>: Entry Positioning. (line 105)
17891 * y, PO Mode command: Modifying Translations.
17893 * y, PO Mode command <1>: Modifying Translations.
17895 * Y, PO Mode command: Modifying Comments. (line 35)
17896 * Y, PO Mode command <1>: Modifying Comments. (line 60)
17899 File: gettext.info, Node: Autoconf Macro Index, Next: Index, Prev: PO Mode Index, Up: Top
17901 Autoconf Macro Index
17902 ********************
17907 * AM_GNU_GETTEXT: AM_GNU_GETTEXT. (line 6)
17908 * AM_GNU_GETTEXT_INTL_SUBDIR: AM_GNU_GETTEXT_INTL_SUBDIR.
17910 * AM_GNU_GETTEXT_NEED: AM_GNU_GETTEXT_NEED. (line 6)
17911 * AM_GNU_GETTEXT_VERSION: AM_GNU_GETTEXT_VERSION.
17913 * AM_ICONV: AM_ICONV. (line 6)
17914 * AM_PO_SUBDIRS: AM_PO_SUBDIRS. (line 6)
17915 * AM_XGETTEXT_OPTION: AM_XGETTEXT_OPTION. (line 6)
17918 File: gettext.info, Node: Index, Prev: Autoconf Macro Index, Up: Top
17926 * ‘_’, a macro to mark strings for translation: Mark Keywords.
17928 * ‘_nl_msg_cat_cntr’: gettext grok. (line 59)
17929 * ‘ABOUT-NLS’ file: Installing Localizations.
17931 * ‘acconfig.h’ file: acconfig. (line 6)
17932 * accumulating translations: Creating Compendia. (line 14)
17933 * ‘aclocal.m4’ file: aclocal. (line 6)
17934 * adding keywords, ‘xgettext’: xgettext Invocation. (line 178)
17935 * ambiguities: Preparing Strings. (line 41)
17936 * apply a filter to translations: msgfilter Invocation.
17938 * apply command to all translations in a catalog: msgexec Invocation.
17940 * Arabic digits: c-format. (line 28)
17941 * attribute manipulation: msgattrib Invocation.
17943 * attribute, fuzzy: Fuzzy Entries. (line 6)
17944 * attributes of a PO file entry: Fuzzy Entries. (line 6)
17945 * attributes, manipulating: Manipulating. (line 56)
17946 * autoconf macros for ‘gettext’: autoconf macros. (line 6)
17947 * ‘autopoint’ program, usage: autopoint Invocation.
17949 * auxiliary PO file: Auxiliary. (line 13)
17950 * available translations: Installing Localizations.
17952 * awk: gawk. (line 6)
17953 * awk-format flag: PO Files. (line 151)
17954 * backup old file, and ‘msgmerge’ program: msgmerge Invocation.
17956 * bash: bash. (line 6)
17957 * bibliography: References. (line 6)
17958 * big picture: Overview. (line 6)
17959 * bind_textdomain_codeset: Charset conversion. (line 26)
17960 * Boost format strings: xgettext Invocation. (line 329)
17961 * boost-format flag: PO Files. (line 200)
17962 * bug report address: Introduction. (line 24)
17963 * C and C-like languages: C. (line 6)
17964 * C trigraphs: xgettext Invocation. (line 316)
17966 * C# mode, and ‘msgfmt’ program: msgfmt Invocation. (line 36)
17967 * C# mode, and ‘msgunfmt’ program: msgunfmt Invocation. (line 19)
17968 * C# resources mode, and ‘msgfmt’ program: msgfmt Invocation. (line 40)
17969 * C# resources mode, and ‘msgunfmt’ program: msgunfmt Invocation.
17971 * C#, string concatenation: Preparing Strings. (line 168)
17972 * c-format flag: PO Files. (line 88)
17973 * c-format, and ‘xgettext’: c-format Flag. (line 47)
17974 * catalog encoding and ‘msgexec’ output: msgexec Invocation. (line 35)
17975 * ‘catclose’, a ‘catgets’ function: Interface to catgets.
17977 * ‘catgets’, a ‘catgets’ function: Interface to catgets.
17979 * ‘catgets’, X/Open specification: catgets. (line 6)
17980 * ‘catopen’, a ‘catgets’ function: Interface to catgets.
17982 * character encoding: Aspects. (line 67)
17983 * charset conversion at runtime: Charset conversion. (line 6)
17984 * charset of PO files: Header Entry. (line 101)
17985 * check format strings: msgfmt Invocation. (line 230)
17986 * checking of translations: Manipulating. (line 41)
17987 * clisp: Common Lisp. (line 6)
17988 * clisp C sources: clisp C. (line 6)
17989 * codeset: Aspects. (line 67)
17990 * comments in PO files: PO Files. (line 320)
17991 * comments, automatic: PO Files. (line 36)
17992 * comments, extracted: PO Files. (line 36)
17993 * comments, translator: PO Files. (line 36)
17994 * Common Lisp: Common Lisp. (line 6)
17995 * compare PO files: msgcmp Invocation. (line 8)
17996 * comparison of interfaces: Comparison. (line 6)
17997 * compatibility with X/Open ‘msgfmt’: msgfmt Invocation. (line 263)
17998 * compendium: Compendium. (line 6)
17999 * compendium, creating: Creating Compendia. (line 6)
18000 * concatenate PO files: msgcat Invocation. (line 8)
18001 * concatenating PO files into a compendium: Creating Compendia.
18003 * concatenation of strings: Preparing Strings. (line 117)
18004 * ‘config.h.in’ file: config.h.in. (line 6)
18005 * context: Contexts. (line 6)
18006 * context, argument specification in ‘xgettext’: xgettext Invocation.
18008 * context, in MO files: MO Files. (line 71)
18009 * context, in PO files: PO Files. (line 211)
18010 * control characters: Preparing Strings. (line 190)
18011 * convert binary message catalog into PO file: msgunfmt Invocation.
18013 * convert translations to a different encoding: msgconv Invocation.
18015 * converting a package to use ‘gettext’: Prerequisites. (line 6)
18016 * country codes: Country Codes. (line 6)
18017 * create new PO file: msginit Invocation. (line 8)
18018 * creating a new PO file: Creating. (line 6)
18019 * creating compendia: Creating Compendia. (line 6)
18020 * csharp-format flag: PO Files. (line 147)
18021 * currency symbols: Aspects. (line 80)
18022 * date format: Aspects. (line 86)
18023 * dcngettext: Plural forms. (line 158)
18024 * dcpgettext: Contexts. (line 56)
18025 * dcpgettext_expr: Contexts. (line 112)
18026 * debugging messages marked as format strings: xgettext Invocation.
18028 * Desktop Entry mode, and ‘msgfmt’ program: msgfmt Invocation.
18030 * dialect: Manipulating. (line 28)
18031 * disabling NLS: lib/gettext.h. (line 6)
18032 * distribution tarball: Release Management. (line 6)
18033 * dngettext: Plural forms. (line 151)
18034 * dollar substitution: envsubst Invocation. (line 8)
18035 * domain ambiguities: Ambiguities. (line 6)
18036 * dpgettext: Contexts. (line 56)
18037 * dpgettext_expr: Contexts. (line 112)
18038 * duplicate elimination: Manipulating. (line 45)
18039 * duplicate removal: msguniq Invocation. (line 8)
18040 * editing comments in PO files: Modifying Comments. (line 6)
18041 * Editing PO Files: Editing. (line 6)
18042 * editing translations: Modifying Translations.
18044 * elisp-format flag: PO Files. (line 127)
18045 * Emacs Lisp: Emacs Lisp. (line 6)
18046 * Emacs PO Mode: PO Mode. (line 6)
18047 * encoding: Aspects. (line 67)
18048 * encoding conversion: Manipulating. (line 17)
18049 * encoding conversion at runtime: Charset conversion. (line 6)
18050 * encoding for your language: Header Entry. (line 130)
18051 * encoding list: Header Entry. (line 114)
18052 * encoding of PO files: Header Entry. (line 101)
18053 * environment variables: envsubst Invocation. (line 8)
18054 * ‘envsubst’ program, usage: envsubst Invocation. (line 6)
18055 * ‘eval_gettext’ function, usage: eval_gettext Invocation.
18057 * ‘eval_ngettext’ function, usage: eval_ngettext Invocation.
18059 * evolution of packages: Overview. (line 127)
18060 * extracting parts of a PO file into a compendium: Creating Compendia.
18062 * FDL, GNU Free Documentation License: GNU FDL. (line 6)
18063 * file format, ‘.mo’: MO Files. (line 6)
18064 * file format, ‘.po’: PO Files. (line 6)
18065 * files, ‘.po’ and ‘.mo’: Files. (line 6)
18066 * files, ‘.pot’: Overview. (line 67)
18067 * filter messages according to attributes: msgattrib Invocation.
18069 * find common messages: msgcomm Invocation. (line 8)
18070 * force use of fuzzy entries: msgfmt Invocation. (line 279)
18071 * format strings: c-format Flag. (line 6)
18072 * Free Pascal: Pascal. (line 6)
18073 * function attribute, __format_arg__: xgettext Invocation. (line 294)
18074 * function attribute, __format__: xgettext Invocation. (line 280)
18075 * fuzzy entries: Fuzzy Entries. (line 6)
18076 * fuzzy flag: PO Files. (line 78)
18077 * gawk: gawk. (line 6)
18078 * gcc-internal-format flag: PO Files. (line 179)
18079 * GCC-source: GCC-source. (line 6)
18080 * generate binary message catalog from PO file: msgfmt Invocation.
18082 * generate translation catalog in English: msgen Invocation. (line 8)
18083 * ‘gettext’ files: Adjusting Files. (line 6)
18084 * ‘gettext’ installation: Installation. (line 6)
18085 * ‘gettext’ interface: Interface to gettext.
18087 * ‘gettext’ program, usage: gettext Invocation. (line 6)
18088 * ‘gettext’ vs ‘catgets’: Comparison. (line 6)
18089 * ‘gettext’, a programmer’s view: gettext. (line 6)
18090 * ‘gettext.h’ file: lib/gettext.h. (line 6)
18091 * ‘gettextize’ program, usage: gettextize Invocation.
18093 * gfc-internal-format flag: PO Files. (line 183)
18094 * GNOME PO file editor: Gtranslator. (line 5)
18095 * GPL, GNU General Public License: GNU GPL. (line 6)
18096 * GUI programs: Contexts. (line 6)
18097 * guile: Scheme. (line 6)
18098 * hash table, inside MO files: MO Files. (line 55)
18099 * he, she, and they: Introduction. (line 15)
18100 * header entry of a PO file: Header Entry. (line 6)
18101 * help option: Preparing Strings. (line 109)
18102 * history of GNU ‘gettext’: History. (line 6)
18103 * i18n: Concepts. (line 6)
18104 * importing PO files: Normalizing. (line 54)
18105 * include file ‘libintl.h’: Overview. (line 57)
18106 * include file ‘libintl.h’ <1>: Importing. (line 11)
18107 * include file ‘libintl.h’ <2>: Comparison. (line 33)
18108 * include file ‘libintl.h’ <3>: lib/gettext.h. (line 29)
18109 * initialization: Triggering. (line 6)
18110 * initialize new PO file: msginit Invocation. (line 8)
18111 * initialize translations from a compendium: Using Compendia. (line 12)
18112 * installing ‘gettext’: Installation. (line 6)
18113 * interface to ‘catgets’: Interface to catgets.
18115 * internationalization: Concepts. (line 16)
18116 * ‘inttypes.h’: Preparing Strings. (line 133)
18117 * ISO 3166: Country Codes. (line 6)
18118 * ISO 639: Language Codes. (line 6)
18119 * Java: Java. (line 6)
18120 * Java mode, and ‘msgfmt’ program: msgfmt Invocation. (line 30)
18121 * Java mode, and ‘msgunfmt’ program: msgunfmt Invocation. (line 16)
18122 * Java, string concatenation: Preparing Strings. (line 168)
18123 * java-format flag: PO Files. (line 143)
18124 * javascript-format flag: PO Files. (line 208)
18125 * KDE format strings: xgettext Invocation. (line 325)
18126 * KDE PO file editor: KBabel. (line 5)
18127 * kde-format flag: PO Files. (line 196)
18128 * keyboard accelerator checking: msgfmt Invocation. (line 267)
18129 * l10n: Concepts. (line 6)
18130 * language codes: Language Codes. (line 6)
18131 * language selection: Locale Environment Variables.
18133 * language selection at runtime: gettext grok. (line 14)
18134 * large package: Ambiguities. (line 6)
18135 * LGPL, GNU Lesser General Public License: GNU LGPL. (line 6)
18136 * ‘libiconv’ library: AM_ICONV. (line 20)
18137 * ‘libintl’ for C#: C#. (line 179)
18138 * ‘libintl’ for Java: Java. (line 105)
18139 * ‘libintl’ library: AM_GNU_GETTEXT. (line 53)
18140 * ‘librep’ Lisp: librep. (line 6)
18141 * librep-format flag: PO Files. (line 131)
18142 * License, GNU FDL: GNU FDL. (line 6)
18143 * License, GNU GPL: GNU GPL. (line 6)
18144 * License, GNU LGPL: GNU LGPL. (line 6)
18145 * Licenses: Licenses. (line 6)
18146 * ‘LINGUAS’ file: po/LINGUAS. (line 6)
18147 * link with ‘libintl’: Overview. (line 62)
18148 * Linux: Aspects. (line 129)
18149 * Linux <1>: Overview. (line 62)
18150 * Linux <2>: Header Entry. (line 127)
18151 * Lisp: Common Lisp. (line 6)
18152 * lisp-format flag: PO Files. (line 123)
18153 * list of translation teams, where to find: Header Entry. (line 54)
18154 * locale categories: Aspects. (line 61)
18155 * locale categories <1>: Aspects. (line 118)
18156 * locale category, LC_ALL: Triggering. (line 23)
18157 * locale category, LC_COLLATE: Triggering. (line 52)
18158 * locale category, LC_CTYPE: Aspects. (line 67)
18159 * locale category, LC_CTYPE <1>: Triggering. (line 23)
18160 * locale category, LC_CTYPE <2>: Triggering. (line 52)
18161 * locale category, LC_MESSAGES: Aspects. (line 112)
18162 * locale category, LC_MESSAGES <1>: Triggering. (line 52)
18163 * locale category, LC_MONETARY: Aspects. (line 80)
18164 * locale category, LC_MONETARY <1>: Triggering. (line 52)
18165 * locale category, LC_NUMERIC: Aspects. (line 97)
18166 * locale category, LC_NUMERIC <1>: Triggering. (line 52)
18167 * locale category, LC_RESPONSES: Triggering. (line 52)
18168 * locale category, LC_TIME: Aspects. (line 86)
18169 * locale category, LC_TIME <1>: Triggering. (line 52)
18170 * ‘locale’ program: Header Entry. (line 107)
18171 * localization: Concepts. (line 26)
18172 * lookup message translation: gettext Invocation. (line 9)
18173 * lookup message translation <1>: eval_gettext Invocation.
18175 * lookup plural message translation: ngettext Invocation. (line 8)
18176 * lookup plural message translation <1>: eval_ngettext Invocation.
18178 * lua-format flag: PO Files. (line 204)
18179 * magic signature of MO files: MO Files. (line 9)
18180 * ‘Makefile.in.in’ extensions: po/Rules-*. (line 6)
18181 * ‘Makevars’ file: po/Makevars. (line 6)
18182 * manipulating PO files: Manipulating. (line 6)
18183 * marking Perl sources: Perl. (line 92)
18184 * marking string initializers: Special cases. (line 6)
18185 * marking strings that require translation: Mark Keywords. (line 6)
18186 * marking strings, preparations: Preparing Strings. (line 6)
18187 * marking translatable strings: Overview. (line 34)
18188 * markup: Preparing Strings. (line 190)
18189 * menu entries: Contexts. (line 6)
18190 * menu, keyboard accelerator support: msgfmt Invocation. (line 267)
18191 * merge PO files: msgcat Invocation. (line 8)
18192 * merging two PO files: Manipulating. (line 10)
18193 * message catalog files location: Locating Catalogs. (line 6)
18194 * messages: Aspects. (line 112)
18195 * migration from earlier versions of ‘gettext’: Prerequisites.
18197 * ‘mkinstalldirs’ file: mkinstalldirs. (line 6)
18198 * mnemonics of menu entries: msgfmt Invocation. (line 267)
18199 * MO file’s format: MO Files. (line 6)
18200 * modify message attributes: msgattrib Invocation.
18202 * ‘msgattrib’ program, usage: msgattrib Invocation.
18204 * ‘msgcat’ program, usage: msgcat Invocation. (line 6)
18205 * ‘msgcmp’ program, usage: msgcmp Invocation. (line 6)
18206 * ‘msgcomm’ program, usage: msgcomm Invocation. (line 6)
18207 * ‘msgconv’ program, usage: msgconv Invocation. (line 6)
18208 * msgctxt: PO Files. (line 211)
18209 * ‘msgen’ program, usage: msgen Invocation. (line 6)
18210 * ‘msgexec’ program, usage: msgexec Invocation. (line 6)
18211 * ‘msgfilter’ filter and catalog encoding: msgfilter Invocation.
18213 * ‘msgfilter’ program, usage: msgfilter Invocation.
18215 * ‘msgfmt’ program, usage: msgfmt Invocation. (line 6)
18216 * ‘msggrep’ program, usage: msggrep Invocation. (line 6)
18217 * msgid: PO Files. (line 55)
18218 * msgid_plural: PO Files. (line 231)
18219 * ‘msginit’ program, usage: msginit Invocation. (line 6)
18220 * ‘msgmerge’ program, usage: msgmerge Invocation. (line 6)
18221 * msgstr: PO Files. (line 55)
18222 * ‘msgunfmt’ program, usage: msgunfmt Invocation. (line 6)
18223 * ‘msguniq’ program, usage: msguniq Invocation. (line 6)
18224 * multi-line strings: Normalizing. (line 64)
18225 * Native Language Support: Concepts. (line 51)
18226 * Natural Language Support: Concepts. (line 51)
18227 * newlines in PO files: PO Files. (line 315)
18228 * ngettext: Plural forms. (line 82)
18229 * ‘ngettext’ program, usage: ngettext Invocation. (line 6)
18230 * NLS: Concepts. (line 51)
18231 * no-awk-format flag: PO Files. (line 152)
18232 * no-boost-format flag: PO Files. (line 201)
18233 * no-c-format flag: PO Files. (line 89)
18234 * no-c-format, and ‘xgettext’: c-format Flag. (line 47)
18235 * no-csharp-format flag: PO Files. (line 148)
18236 * no-elisp-format flag: PO Files. (line 128)
18237 * no-gcc-internal-format flag: PO Files. (line 180)
18238 * no-gfc-internal-format flag: PO Files. (line 184)
18239 * no-java-format flag: PO Files. (line 144)
18240 * no-javascript-format flag: PO Files. (line 209)
18241 * no-kde-format flag: PO Files. (line 197)
18242 * no-librep-format flag: PO Files. (line 132)
18243 * no-lisp-format flag: PO Files. (line 124)
18244 * no-lua-format flag: PO Files. (line 205)
18245 * no-objc-format flag: PO Files. (line 108)
18246 * no-object-pascal-format flag: PO Files. (line 156)
18247 * no-perl-brace-format flag: PO Files. (line 172)
18248 * no-perl-format flag: PO Files. (line 168)
18249 * no-php-format flag: PO Files. (line 176)
18250 * no-python-brace-format flag: PO Files. (line 120)
18251 * no-python-format flag: PO Files. (line 116)
18252 * no-qt-format flag: PO Files. (line 189)
18253 * no-qt-plural-format flag: PO Files. (line 193)
18254 * no-scheme-format flag: PO Files. (line 136)
18255 * no-sh-format flag: PO Files. (line 112)
18256 * no-smalltalk-format flag: PO Files. (line 140)
18257 * no-tcl-format flag: PO Files. (line 164)
18258 * no-ycp-format flag: PO Files. (line 160)
18259 * nplurals, in a PO file header: Plural forms. (line 177)
18260 * number format: Aspects. (line 97)
18261 * ‘N_’, a convenience macro: Comparison. (line 41)
18262 * objc-format flag: PO Files. (line 107)
18263 * Object Pascal: Pascal. (line 6)
18264 * object-pascal-format flag: PO Files. (line 155)
18265 * obsolete entries: Obsolete Entries. (line 6)
18266 * optimization of ‘gettext’ functions: Optimized gettext. (line 6)
18267 * orthography: Manipulating. (line 28)
18268 * outdigits: c-format. (line 28)
18269 * output to stdout, ‘xgettext’: xgettext Invocation. (line 46)
18270 * overview of ‘gettext’: Overview. (line 6)
18271 * package and version declaration in ‘configure.ac’: configure.ac.
18273 * package build and installation options: Installers. (line 6)
18274 * package distributor’s view of ‘gettext’: Installers. (line 6)
18275 * package installer’s view of ‘gettext’: Installers. (line 6)
18276 * package maintainer’s view of ‘gettext’: Maintainers. (line 6)
18277 * paragraphs: Preparing Strings. (line 101)
18278 * Pascal: Pascal. (line 6)
18279 * Perl: Perl. (line 6)
18280 * Perl default keywords: Default Keywords. (line 6)
18281 * Perl invalid string interpolation: Interpolation I. (line 6)
18282 * Perl long lines: Long Lines. (line 6)
18283 * Perl parentheses: Parentheses. (line 6)
18284 * Perl pitfalls: Perl Pitfalls. (line 6)
18285 * Perl quote-like expressions: Quote-like Expressions.
18287 * Perl special keywords for hash-lookups: Special Keywords. (line 6)
18288 * Perl valid string interpolation: Interpolation II. (line 6)
18289 * perl-brace-format flag: PO Files. (line 171)
18290 * perl-format flag: PO Files. (line 167)
18291 * pgettext: Contexts. (line 33)
18292 * pgettext_expr: Contexts. (line 112)
18293 * PHP: PHP. (line 6)
18294 * php-format flag: PO Files. (line 175)
18295 * Pike: Pike. (line 6)
18296 * plural form formulas: Plural forms. (line 197)
18297 * plural forms: Plural forms. (line 6)
18298 * plural forms, in MO files: MO Files. (line 74)
18299 * plural forms, in PO files: PO Files. (line 231)
18300 * plural forms, translating: Translating plural forms.
18302 * plural, in a PO file header: Plural forms. (line 177)
18303 * PO files’ format: PO Files. (line 6)
18304 * PO mode (Emacs) commands: Main PO Commands. (line 6)
18305 * PO template file: Template. (line 6)
18306 * portability problems with ‘sed’: msgfilter Invocation.
18308 * ‘POTFILES.in’ file: po/POTFILES.in. (line 6)
18309 * po_file_domains: libgettextpo. (line 40)
18310 * po_file_free: libgettextpo. (line 35)
18311 * po_file_read: libgettextpo. (line 29)
18312 * po_message_iterator: libgettextpo. (line 48)
18313 * po_message_iterator_free: libgettextpo. (line 55)
18314 * po_message_msgid: libgettextpo. (line 69)
18315 * po_message_msgid_plural: libgettextpo. (line 73)
18316 * po_message_msgstr: libgettextpo. (line 79)
18317 * po_message_msgstr_plural: libgettextpo. (line 84)
18318 * po_next_message: libgettextpo. (line 60)
18319 * preparing programs for translation: Sources. (line 6)
18320 * preparing rules for XML translation: Preparing ITS Rules. (line 6)
18321 * preparing shell scripts for translation: Preparing Shell Scripts.
18323 * problems with ‘catgets’ interface: Problems with catgets.
18325 * programming languages: Language Implementors.
18327 * Python: Python. (line 6)
18328 * python-brace-format flag: PO Files. (line 119)
18329 * python-format flag: PO Files. (line 115)
18330 * Qt format strings: xgettext Invocation. (line 321)
18331 * Qt mode, and ‘msgfmt’ program: msgfmt Invocation. (line 46)
18332 * qt-format flag: PO Files. (line 188)
18333 * qt-plural-format flag: PO Files. (line 192)
18334 * quotation marks: Header Entry. (line 160)
18335 * quotation marks <1>: po/Rules-*. (line 11)
18336 * quote characters, use in PO files: Header Entry. (line 160)
18337 * range: flag: PO Files. (line 262)
18338 * ‘recode-sr-latin’ program: msgfilter Invocation.
18340 * related reading: References. (line 6)
18341 * release: Release Management. (line 6)
18342 * RST: RST. (line 6)
18343 * Scheme: Scheme. (line 6)
18344 * scheme-format flag: PO Files. (line 135)
18345 * scripting languages: Language Implementors.
18347 * search messages in a catalog: msggrep Invocation. (line 8)
18348 * selecting message language: Locale Environment Variables.
18350 * sentence end markers, ‘xgettext’: xgettext Invocation. (line 152)
18351 * sentences: Preparing Strings. (line 44)
18352 * setting up ‘gettext’ at build time: Installers. (line 6)
18353 * setting up ‘gettext’ at run time: Locale Environment Variables.
18355 * several domains: Ambiguities. (line 6)
18356 * sex: Introduction. (line 15)
18357 * sh-format flag: PO Files. (line 111)
18358 * she, he, and they: Introduction. (line 15)
18359 * shell format string: envsubst Invocation. (line 8)
18360 * shell scripts: sh. (line 6)
18361 * Smalltalk: Smalltalk. (line 6)
18362 * smalltalk-format flag: PO Files. (line 139)
18363 * sorting ‘msgcat’ output: msgcat Invocation. (line 152)
18364 * sorting ‘msgmerge’ output: msgmerge Invocation. (line 188)
18365 * sorting ‘msgunfmt’ output: msgunfmt Invocation. (line 147)
18366 * sorting output of ‘xgettext’: xgettext Invocation. (line 416)
18367 * specifying plural form in a PO file: Plural forms. (line 177)
18368 * standard output, and ‘msgcat’: msgcat Invocation. (line 44)
18369 * standard output, and ‘msgmerge’ program: msgmerge Invocation.
18371 * string concatenation: Preparing Strings. (line 117)
18372 * string normalization in entries: Normalizing. (line 6)
18373 * style: Preparing Strings. (line 24)
18374 * supported languages, ‘msgfmt’: msgfmt Invocation. (line 180)
18375 * supported languages, ‘xgettext’: xgettext Invocation. (line 54)
18376 * supported syntax checks, ‘xgettext’: xgettext Invocation. (line 116)
18377 * Tcl: Tcl. (line 6)
18378 * Tcl mode, and ‘msgfmt’ program: msgfmt Invocation. (line 43)
18379 * Tcl mode, and ‘msgunfmt’ program: msgunfmt Invocation. (line 26)
18380 * tcl-format flag: PO Files. (line 163)
18381 * template PO file: Overview. (line 67)
18382 * testing ‘.po’ files for equivalence: xgettext Invocation. (line 426)
18383 * Tk’s scripting language: Tcl. (line 6)
18384 * translated entries: Translated Entries. (line 6)
18385 * translating menu entries: Contexts. (line 6)
18386 * translation aspects: Aspects. (line 6)
18387 * Translation Matrix: Installing Localizations.
18389 * Translation Project: Why. (line 17)
18390 * turning off NLS support: lib/gettext.h. (line 6)
18391 * tutorial of ‘gettext’ usage: Overview. (line 6)
18392 * unify duplicate translations: msguniq Invocation. (line 8)
18393 * untranslated entries: Untranslated Entries.
18395 * update translations from a compendium: Using Compendia. (line 20)
18396 * upgrading to new versions of ‘gettext’: Prerequisites. (line 6)
18397 * version control for backup files, ‘msgmerge’: msgmerge Invocation.
18399 * ‘wxWidgets’ library: wxWidgets. (line 6)
18400 * ‘xargs’, and output from ‘msgexec’: msgexec Invocation. (line 14)
18401 * ‘xgettext’ program, usage: xgettext Invocation. (line 6)
18402 * XML mode, and ‘msgfmt’ program: msgfmt Invocation. (line 52)
18403 * ‘xmodmap’ program, and typing quotation marks: Header Entry.
18405 * YaST2 scripting language: YCP. (line 6)
18406 * YCP: YCP. (line 6)
18407 * ycp-format flag: PO Files. (line 159)
18413 Node: Introduction
\7f18345
18415 Ref: Why-Footnote-1
\7f23243
18416 Node: Concepts
\7f23399
18417 Node: Aspects
\7f26830
18418 Node: Files
\7f33438
18419 Node: Overview
\7f35388
18420 Node: Users
\7f45475
18421 Node: System Installation
\7f46390
18422 Node: Setting the GUI Locale
\7f48083
18423 Node: Setting the POSIX Locale
\7f49491
18424 Node: Locale Names
\7f50473
18425 Node: Locale Environment Variables
\7f52962
18426 Node: The LANGUAGE variable
\7f55305
18427 Node: Installing Localizations
\7f57326
18428 Node: PO Files
\7f58703
18429 Ref: PO Files-Footnote-1
\7f71841
18430 Node: Sources
\7f71976
18431 Node: Importing
\7f73218
18432 Node: Triggering
\7f73922
18433 Node: Preparing Strings
\7f77280
18434 Node: Mark Keywords
\7f86439
18435 Node: Marking
\7f91007
18436 Node: c-format Flag
\7f98964
18437 Node: Special cases
\7f103010
18438 Node: Bug Report Address
\7f105794
18439 Node: Names
\7f107773
18440 Node: Libraries
\7f112079
18441 Node: Template
\7f115169
18442 Node: xgettext Invocation
\7f115934
18443 Node: Creating
\7f136267
18444 Node: msginit Invocation
\7f137176
18445 Node: Header Entry
\7f141499
18446 Node: Updating
\7f150956
18447 Node: msgmerge Invocation
\7f151175
18448 Node: Editing
\7f157641
18449 Node: KBabel
\7f158005
18450 Node: Gtranslator
\7f158145
18451 Node: PO Mode
\7f158289
18452 Node: Installation
\7f159949
18453 Node: Main PO Commands
\7f161965
18454 Node: Entry Positioning
\7f167237
18455 Node: Normalizing
\7f172882
18456 Node: Translated Entries
\7f177443
18457 Node: Fuzzy Entries
\7f178848
18458 Node: Untranslated Entries
\7f182155
18459 Node: Obsolete Entries
\7f184154
18460 Node: Modifying Translations
\7f187453
18461 Node: Modifying Comments
\7f195595
18462 Node: Subedit
\7f200144
18463 Node: C Sources Context
\7f204162
18464 Node: Auxiliary
\7f209391
18465 Node: Compendium
\7f212711
18466 Node: Creating Compendia
\7f213326
18467 Node: Using Compendia
\7f215888
18468 Node: Manipulating
\7f216846
18469 Node: msgcat Invocation
\7f220790
18470 Node: msgconv Invocation
\7f226112
18471 Node: msggrep Invocation
\7f230103
18472 Node: msgfilter Invocation
\7f236925
18473 Node: msguniq Invocation
\7f245279
18474 Node: msgcomm Invocation
\7f250019
18475 Node: msgcmp Invocation
\7f254920
18476 Node: msgattrib Invocation
\7f257161
18477 Node: msgen Invocation
\7f262930
18478 Node: msgexec Invocation
\7f267339
18479 Node: Colorizing
\7f270663
18480 Node: The --color option
\7f271718
18481 Node: The TERM variable
\7f273447
18482 Node: The --style option
\7f275001
18483 Node: Style rules
\7f276379
18484 Node: Customizing less
\7f283392
18485 Node: libgettextpo
\7f284847
18486 Node: Binaries
\7f290097
18487 Node: msgfmt Invocation
\7f290449
18488 Node: msgunfmt Invocation
\7f301124
18489 Node: MO Files
\7f305808
18490 Node: Programmers
\7f314429
18491 Node: catgets
\7f315643
18492 Node: Interface to catgets
\7f317073
18493 Node: Problems with catgets
\7f319142
18494 Node: gettext
\7f320067
18495 Node: Interface to gettext
\7f321590
18496 Node: Ambiguities
\7f323958
18497 Node: Locating Catalogs
\7f326718
18498 Ref: Locating Catalogs-Footnote-1
\7f327983
18499 Ref: Locating Catalogs-Footnote-2
\7f328215
18500 Node: Charset conversion
\7f328368
18501 Node: Contexts
\7f330888
18502 Node: Plural forms
\7f336508
18503 Ref: Plural forms-Footnote-1
\7f353224
18504 Node: Optimized gettext
\7f353596
18505 Node: Comparison
\7f354947
18506 Node: Using libintl.a
\7f359314
18507 Node: gettext grok
\7f359769
18508 Node: Temp Programmers
\7f362478
18509 Node: Temp Implementations
\7f363010
18510 Node: Temp catgets
\7f364428
18511 Node: Temp WSI
\7f366155
18512 Node: Temp Notes
\7f368218
18513 Node: Translators
\7f368732
18514 Node: Trans Intro 0
\7f369277
18515 Node: Trans Intro 1
\7f372134
18516 Node: Discussions
\7f374107
18517 Node: Organization
\7f377825
18518 Node: Central Coordination
\7f379911
18519 Node: National Teams
\7f381059
18520 Node: Sub-Cultures
\7f383593
18521 Node: Organizational Ideas
\7f384534
18522 Node: Mailing Lists
\7f385565
18523 Node: Information Flow
\7f387402
18524 Node: Translating plural forms
\7f389669
18525 Node: Prioritizing messages
\7f393112
18526 Node: Maintainers
\7f397496
18527 Node: Flat and Non-Flat
\7f399473
18528 Node: Prerequisites
\7f401003
18529 Node: gettextize Invocation
\7f405262
18530 Node: Adjusting Files
\7f413042
18531 Node: po/POTFILES.in
\7f414890
18532 Node: po/LINGUAS
\7f416189
18533 Node: po/Makevars
\7f417996
18534 Node: po/Rules-*
\7f418986
18535 Node: configure.ac
\7f420547
18536 Node: config.guess
\7f423720
18537 Node: mkinstalldirs
\7f425186
18538 Node: aclocal
\7f425599
18539 Node: acconfig
\7f428154
18540 Node: config.h.in
\7f428698
18541 Node: Makefile
\7f430246
18542 Node: src/Makefile
\7f432978
18543 Node: lib/gettext.h
\7f437904
18544 Node: autoconf macros
\7f440237
18545 Node: AM_GNU_GETTEXT
\7f441141
18546 Node: AM_GNU_GETTEXT_VERSION
\7f445365
18547 Node: AM_GNU_GETTEXT_NEED
\7f445844
18548 Node: AM_GNU_GETTEXT_INTL_SUBDIR
\7f446777
18549 Node: AM_PO_SUBDIRS
\7f447462
18550 Node: AM_XGETTEXT_OPTION
\7f448301
18551 Node: AM_ICONV
\7f449212
18552 Node: Version Control Issues
\7f451597
18553 Node: Distributed Development
\7f452352
18554 Node: Files under Version Control
\7f454387
18555 Node: Translations under Version Control
\7f457878
18556 Ref: Translations under Version Control-Footnote-1
\7f459954
18557 Node: autopoint Invocation
\7f460044
18558 Node: Release Management
\7f462409
18559 Node: Installers
\7f462950
18560 Node: Programming Languages
\7f464213
18561 Node: Language Implementors
\7f465051
18562 Node: Programmers for other Languages
\7f470041
18563 Node: Translators for other Languages
\7f470635
18564 Node: c-format
\7f472497
18565 Node: objc-format
\7f474271
18566 Node: sh-format
\7f474630
18567 Node: python-format
\7f475479
18568 Node: lisp-format
\7f476252
18569 Node: elisp-format
\7f476581
18570 Node: librep-format
\7f477076
18571 Node: scheme-format
\7f477479
18572 Node: smalltalk-format
\7f477758
18573 Node: java-format
\7f478289
18574 Node: csharp-format
\7f478744
18575 Node: awk-format
\7f479126
18576 Node: object-pascal-format
\7f479454
18577 Node: ycp-format
\7f479840
18578 Node: tcl-format
\7f480258
18579 Node: perl-format
\7f480560
18580 Node: php-format
\7f481352
18581 Node: gcc-internal-format
\7f481728
18582 Node: gfc-internal-format
\7f482887
18583 Node: qt-format
\7f483636
18584 Node: qt-plural-format
\7f484082
18585 Node: kde-format
\7f484441
18586 Node: kde-kuit-format
\7f484873
18587 Node: boost-format
\7f485538
18588 Node: lua-format
\7f486130
18589 Node: javascript-format
\7f486469
18590 Node: Maintainers for other Languages
\7f487239
18591 Node: List of Programming Languages
\7f488527
18594 Node: Preparing Shell Scripts
\7f492736
18595 Node: gettext.sh
\7f496256
18596 Node: gettext Invocation
\7f496824
18597 Node: ngettext Invocation
\7f498875
18598 Node: envsubst Invocation
\7f500755
18599 Node: eval_gettext Invocation
\7f502234
18600 Node: eval_ngettext Invocation
\7f502699
18601 Node: bash
\7f503217
18602 Node: Python
\7f505266
18603 Node: Common Lisp
\7f507746
18604 Node: clisp C
\7f508596
18605 Node: Emacs Lisp
\7f509354
18606 Node: librep
\7f510122
18607 Node: Scheme
\7f510903
18608 Node: Smalltalk
\7f511778
18609 Node: Java
\7f512873
18611 Node: gawk
\7f528591
18612 Node: Pascal
\7f529696
18613 Node: wxWidgets
\7f531108
18616 Node: Perl
\7f534344
18617 Node: General Problems
\7f537536
18618 Node: Default Keywords
\7f543204
18619 Node: Special Keywords
\7f544232
18620 Node: Quote-like Expressions
\7f545794
18621 Node: Interpolation I
\7f548111
18622 Node: Interpolation II
\7f552055
18623 Node: Parentheses
\7f554439
18624 Node: Long Lines
\7f555964
18625 Node: Perl Pitfalls
\7f557831
18627 Node: Pike
\7f563174
18628 Node: GCC-source
\7f563875
18630 Node: JavaScript
\7f565701
18631 Node: Vala
\7f566469
18632 Node: List of Data Formats
\7f567388
18635 Node: Glade
\7f568593
18636 Node: GSettings
\7f569005
18637 Node: AppData
\7f569316
18638 Node: Preparing ITS Rules
\7f569747
18639 Ref: Preparing ITS Rules-Footnote-1
\7f575919
18640 Node: Conclusion
\7f576251
18641 Node: History
\7f576765
18642 Node: References
\7f581168
18643 Node: Language Codes
\7f582867
18644 Node: Usual Language Codes
\7f583382
18645 Node: Rare Language Codes
\7f588300
18646 Node: Country Codes
\7f590150
18647 Node: Licenses
\7f597303
18648 Node: GNU GPL
\7f599159
18649 Node: GNU LGPL
\7f618476
18650 Node: GNU FDL
\7f646713
18651 Node: Program Index
\7f669244
18652 Node: Option Index
\7f671654
18653 Node: Variable Index
\7f726872
18654 Node: PO Mode Index
\7f731543
18655 Node: Autoconf Macro Index
\7f748253
18656 Node: Index
\7f749060