1 \input texinfo @c -*-texinfo-*-
3 @setfilename gettext.info
4 @c The @ifset makeinfo ... @end ifset conditional evaluates to true in makeinfo
5 @c for info and html output, but to false in texi2html.
11 @c The @documentencoding is needed for makeinfo; texi2html 1.52
12 @c doesn't recognize it.
14 @documentencoding UTF-8
16 @settitle GNU @code{gettext} utilities
19 @c am = autoconf macro @amindex
20 @c cp = concept @cindex
21 @c ef = emacs function @efindex
22 @c em = emacs mode @emindex
23 @c ev = emacs variable @evindex
24 @c fn = function @findex
25 @c kw = keyword @kwindex
26 @c op = option @opindex
27 @c pg = program @pindex
28 @c vr = variable @vindex
29 @c Unused predefined indices:
31 @c ky = keystroke @kindex
43 @firstparagraphindent insert
50 @dircategory GNU Gettext Utilities
52 * gettext: (gettext). GNU gettext utilities.
53 * autopoint: (gettext)autopoint Invocation. Copy gettext infrastructure.
54 * envsubst: (gettext)envsubst Invocation. Expand environment variables.
55 * gettextize: (gettext)gettextize Invocation. Prepare a package for gettext.
56 * msgattrib: (gettext)msgattrib Invocation. Select part of a PO file.
57 * msgcat: (gettext)msgcat Invocation. Combine several PO files.
58 * msgcmp: (gettext)msgcmp Invocation. Compare a PO file and template.
59 * msgcomm: (gettext)msgcomm Invocation. Match two PO files.
60 * msgconv: (gettext)msgconv Invocation. Convert PO file to encoding.
61 * msgen: (gettext)msgen Invocation. Create an English PO file.
62 * msgexec: (gettext)msgexec Invocation. Process a PO file.
63 * msgfilter: (gettext)msgfilter Invocation. Pipe a PO file through a filter.
64 * msgfmt: (gettext)msgfmt Invocation. Make MO files out of PO files.
65 * msggrep: (gettext)msggrep Invocation. Select part of a PO file.
66 * msginit: (gettext)msginit Invocation. Create a fresh PO file.
67 * msgmerge: (gettext)msgmerge Invocation. Update a PO file from template.
68 * msgunfmt: (gettext)msgunfmt Invocation. Uncompile MO file into PO file.
69 * msguniq: (gettext)msguniq Invocation. Unify duplicates for PO file.
70 * ngettext: (gettext)ngettext Invocation. Translate a message with plural.
71 * xgettext: (gettext)xgettext Invocation. Extract strings into a PO file.
72 * ISO639: (gettext)Language Codes. ISO 639 language codes.
73 * ISO3166: (gettext)Country Codes. ISO 3166 country codes.
78 This file provides documentation for GNU @code{gettext} utilities.
79 It also serves as a reference for the free Translation Project.
82 Copyright (C) 1995-1998, 2001-2015 Free Software Foundation, Inc.
84 This manual is free documentation. It is dually licensed under the
85 GNU FDL and the GNU GPL. This means that you can redistribute this
86 manual under either of these two licenses, at your choice.
88 This manual is covered by the GNU FDL. Permission is granted to copy,
89 distribute and/or modify this document under the terms of the
90 GNU Free Documentation License (FDL), either version 1.2 of the
91 License, or (at your option) any later version published by the
92 Free Software Foundation (FSF); with no Invariant Sections, with no
93 Front-Cover Text, and with no Back-Cover Texts.
94 A copy of the license is included in @ref{GNU FDL}.
96 This manual is covered by the GNU GPL. You can redistribute it and/or
97 modify it under the terms of the GNU General Public License (GPL), either
98 version 2 of the License, or (at your option) any later version published
99 by the Free Software Foundation (FSF).
100 A copy of the license is included in @ref{GNU GPL}.
105 @title GNU gettext tools, version @value{VERSION}
106 @subtitle Native Language Support Library and Tools
107 @subtitle Edition @value{EDITION}, @value{UPDATED}
108 @author Ulrich Drepper
110 @author Fran@,{c}ois Pinard
115 @vskip 0pt plus 1filll
117 Copyright (C) 1995-1998, 2001-2012 Free Software Foundation, Inc.
119 This manual is free documentation. It is dually licensed under the
120 GNU FDL and the GNU GPL. This means that you can redistribute this
121 manual under either of these two licenses, at your choice.
123 This manual is covered by the GNU FDL. Permission is granted to copy,
124 distribute and/or modify this document under the terms of the
125 GNU Free Documentation License (FDL), either version 1.2 of the
126 License, or (at your option) any later version published by the
127 Free Software Foundation (FSF); with no Invariant Sections, with no
128 Front-Cover Text, and with no Back-Cover Texts.
129 A copy of the license is included in @ref{GNU FDL}.
131 This manual is covered by the GNU GPL. You can redistribute it and/or
132 modify it under the terms of the GNU General Public License (GPL), either
133 version 2 of the License, or (at your option) any later version published
134 by the Free Software Foundation (FSF).
135 A copy of the license is included in @ref{GNU GPL}.
143 @node Top, Introduction, (dir), (dir)
144 @top GNU @code{gettext} utilities
146 This manual documents the GNU gettext tools and the GNU libintl library,
147 version @value{VERSION}.
150 * Introduction:: Introduction
151 * Users:: The User's View
152 * PO Files:: The Format of PO Files
153 * Sources:: Preparing Program Sources
154 * Template:: Making the PO Template File
155 * Creating:: Creating a New PO File
156 * Updating:: Updating Existing PO Files
157 * Editing:: Editing PO Files
158 * Manipulating:: Manipulating PO Files
159 * Binaries:: Producing Binary MO Files
160 * Programmers:: The Programmer's View
161 * Translators:: The Translator's View
162 * Maintainers:: The Maintainer's View
163 * Installers:: The Installer's and Distributor's View
164 * Programming Languages:: Other Programming Languages
165 * Conclusion:: Concluding Remarks
167 * Language Codes:: ISO 639 language codes
168 * Country Codes:: ISO 3166 country codes
169 * Licenses:: Licenses
171 * Program Index:: Index of Programs
172 * Option Index:: Index of Command-Line Options
173 * Variable Index:: Index of Environment Variables
174 * PO Mode Index:: Index of Emacs PO Mode Commands
175 * Autoconf Macro Index:: Index of Autoconf Macros
176 * Index:: General Index
179 --- The Detailed Node Listing ---
183 * Why:: The Purpose of GNU @code{gettext}
184 * Concepts:: I18n, L10n, and Such
185 * Aspects:: Aspects in Native Language Support
186 * Files:: Files Conveying Translations
187 * Overview:: Overview of GNU @code{gettext}
191 * System Installation:: Questions During Operating System Installation
192 * Setting the GUI Locale:: How to Specify the Locale Used by GUI Programs
193 * Setting the POSIX Locale:: How to Specify the Locale According to POSIX
194 * Installing Localizations:: How to Install Additional Translations
196 Setting the Locale through Environment Variables
198 * Locale Names:: How a Locale Specification Looks Like
199 * Locale Environment Variables:: Which Environment Variable Specfies What
200 * The LANGUAGE variable:: How to Specify a Priority List of Languages
202 Preparing Program Sources
204 * Importing:: Importing the @code{gettext} declaration
205 * Triggering:: Triggering @code{gettext} Operations
206 * Preparing Strings:: Preparing Translatable Strings
207 * Mark Keywords:: How Marks Appear in Sources
208 * Marking:: Marking Translatable Strings
209 * c-format Flag:: Telling something about the following string
210 * Special cases:: Special Cases of Translatable Strings
211 * Bug Report Address:: Letting Users Report Translation Bugs
212 * Names:: Marking Proper Names for Translation
213 * Libraries:: Preparing Library Sources
215 Making the PO Template File
217 * xgettext Invocation:: Invoking the @code{xgettext} Program
219 Creating a New PO File
221 * msginit Invocation:: Invoking the @code{msginit} Program
222 * Header Entry:: Filling in the Header Entry
224 Updating Existing PO Files
226 * msgmerge Invocation:: Invoking the @code{msgmerge} Program
230 * KBabel:: KDE's PO File Editor
231 * Gtranslator:: GNOME's PO File Editor
232 * PO Mode:: Emacs's PO File Editor
233 * Compendium:: Using Translation Compendia
235 Emacs's PO File Editor
237 * Installation:: Completing GNU @code{gettext} Installation
238 * Main PO Commands:: Main Commands
239 * Entry Positioning:: Entry Positioning
240 * Normalizing:: Normalizing Strings in Entries
241 * Translated Entries:: Translated Entries
242 * Fuzzy Entries:: Fuzzy Entries
243 * Untranslated Entries:: Untranslated Entries
244 * Obsolete Entries:: Obsolete Entries
245 * Modifying Translations:: Modifying Translations
246 * Modifying Comments:: Modifying Comments
247 * Subedit:: Mode for Editing Translations
248 * C Sources Context:: C Sources Context
249 * Auxiliary:: Consulting Auxiliary PO Files
251 Using Translation Compendia
253 * Creating Compendia:: Merging translations for later use
254 * Using Compendia:: Using older translations if they fit
256 Manipulating PO Files
258 * msgcat Invocation:: Invoking the @code{msgcat} Program
259 * msgconv Invocation:: Invoking the @code{msgconv} Program
260 * msggrep Invocation:: Invoking the @code{msggrep} Program
261 * msgfilter Invocation:: Invoking the @code{msgfilter} Program
262 * msguniq Invocation:: Invoking the @code{msguniq} Program
263 * msgcomm Invocation:: Invoking the @code{msgcomm} Program
264 * msgcmp Invocation:: Invoking the @code{msgcmp} Program
265 * msgattrib Invocation:: Invoking the @code{msgattrib} Program
266 * msgen Invocation:: Invoking the @code{msgen} Program
267 * msgexec Invocation:: Invoking the @code{msgexec} Program
268 * Colorizing:: Highlighting parts of PO files
269 * libgettextpo:: Writing your own programs that process PO files
271 Highlighting parts of PO files
273 * The --color option:: Triggering colorized output
274 * The TERM variable:: The environment variable @code{TERM}
275 * The --style option:: The @code{--style} option
276 * Style rules:: Style rules for PO files
277 * Customizing less:: Customizing @code{less} for viewing PO files
279 Producing Binary MO Files
281 * msgfmt Invocation:: Invoking the @code{msgfmt} Program
282 * msgunfmt Invocation:: Invoking the @code{msgunfmt} Program
283 * MO Files:: The Format of GNU MO Files
285 The Programmer's View
287 * catgets:: About @code{catgets}
288 * gettext:: About @code{gettext}
289 * Comparison:: Comparing the two interfaces
290 * Using libintl.a:: Using libintl.a in own programs
291 * gettext grok:: Being a @code{gettext} grok
292 * Temp Programmers:: Temporary Notes for the Programmers Chapter
296 * Interface to catgets:: The interface
297 * Problems with catgets:: Problems with the @code{catgets} interface?!
301 * Interface to gettext:: The interface
302 * Ambiguities:: Solving ambiguities
303 * Locating Catalogs:: Locating message catalog files
304 * Charset conversion:: How to request conversion to Unicode
305 * Contexts:: Solving ambiguities in GUI programs
306 * Plural forms:: Additional functions for handling plurals
307 * Optimized gettext:: Optimization of the *gettext functions
309 Temporary Notes for the Programmers Chapter
311 * Temp Implementations:: Temporary - Two Possible Implementations
312 * Temp catgets:: Temporary - About @code{catgets}
313 * Temp WSI:: Temporary - Why a single implementation
314 * Temp Notes:: Temporary - Notes
316 The Translator's View
318 * Trans Intro 0:: Introduction 0
319 * Trans Intro 1:: Introduction 1
320 * Discussions:: Discussions
321 * Organization:: Organization
322 * Information Flow:: Information Flow
323 * Translating plural forms:: How to fill in @code{msgstr[0]}, @code{msgstr[1]}
324 * Prioritizing messages:: How to find which messages to translate first
328 * Central Coordination:: Central Coordination
329 * National Teams:: National Teams
330 * Mailing Lists:: Mailing Lists
334 * Sub-Cultures:: Sub-Cultures
335 * Organizational Ideas:: Organizational Ideas
337 The Maintainer's View
339 * Flat and Non-Flat:: Flat or Non-Flat Directory Structures
340 * Prerequisites:: Prerequisite Works
341 * gettextize Invocation:: Invoking the @code{gettextize} Program
342 * Adjusting Files:: Files You Must Create or Alter
343 * autoconf macros:: Autoconf macros for use in @file{configure.ac}
344 * Version Control Issues::
345 * Release Management:: Creating a Distribution Tarball
347 Files You Must Create or Alter
349 * po/POTFILES.in:: @file{POTFILES.in} in @file{po/}
350 * po/LINGUAS:: @file{LINGUAS} in @file{po/}
351 * po/Makevars:: @file{Makevars} in @file{po/}
352 * po/Rules-*:: Extending @file{Makefile} in @file{po/}
353 * configure.ac:: @file{configure.ac} at top level
354 * config.guess:: @file{config.guess}, @file{config.sub} at top level
355 * mkinstalldirs:: @file{mkinstalldirs} at top level
356 * aclocal:: @file{aclocal.m4} at top level
357 * acconfig:: @file{acconfig.h} at top level
358 * config.h.in:: @file{config.h.in} at top level
359 * Makefile:: @file{Makefile.in} at top level
360 * src/Makefile:: @file{Makefile.in} in @file{src/}
361 * lib/gettext.h:: @file{gettext.h} in @file{lib/}
363 Autoconf macros for use in @file{configure.ac}
365 * AM_GNU_GETTEXT:: AM_GNU_GETTEXT in @file{gettext.m4}
366 * AM_GNU_GETTEXT_VERSION:: AM_GNU_GETTEXT_VERSION in @file{gettext.m4}
367 * AM_GNU_GETTEXT_NEED:: AM_GNU_GETTEXT_NEED in @file{gettext.m4}
368 * AM_GNU_GETTEXT_INTL_SUBDIR:: AM_GNU_GETTEXT_INTL_SUBDIR in @file{intldir.m4}
369 * AM_PO_SUBDIRS:: AM_PO_SUBDIRS in @file{po.m4}
370 * AM_XGETTEXT_OPTION:: AM_XGETTEXT_OPTION in @file{po.m4}
371 * AM_ICONV:: AM_ICONV in @file{iconv.m4}
373 Integrating with Version Control Systems
375 * Distributed Development:: Avoiding version mismatch in distributed development
376 * Files under Version Control:: Files to put under version control
377 * Translations under Version Control:: Put PO Files under Version Control
378 * autopoint Invocation:: Invoking the @code{autopoint} Program
380 Other Programming Languages
382 * Language Implementors:: The Language Implementor's View
383 * Programmers for other Languages:: The Programmer's View
384 * Translators for other Languages:: The Translator's View
385 * Maintainers for other Languages:: The Maintainer's View
386 * List of Programming Languages:: Individual Programming Languages
387 * List of Data Formats:: Internationalizable Data
389 The Translator's View
391 * c-format:: C Format Strings
392 * objc-format:: Objective C Format Strings
393 * sh-format:: Shell Format Strings
394 * python-format:: Python Format Strings
395 * lisp-format:: Lisp Format Strings
396 * elisp-format:: Emacs Lisp Format Strings
397 * librep-format:: librep Format Strings
398 * scheme-format:: Scheme Format Strings
399 * smalltalk-format:: Smalltalk Format Strings
400 * java-format:: Java Format Strings
401 * csharp-format:: C# Format Strings
402 * awk-format:: awk Format Strings
403 * object-pascal-format:: Object Pascal Format Strings
404 * ycp-format:: YCP Format Strings
405 * tcl-format:: Tcl Format Strings
406 * perl-format:: Perl Format Strings
407 * php-format:: PHP Format Strings
408 * gcc-internal-format:: GCC internal Format Strings
409 * gfc-internal-format:: GFC internal Format Strings
410 * qt-format:: Qt Format Strings
411 * qt-plural-format:: Qt Plural Format Strings
412 * kde-format:: KDE Format Strings
413 * boost-format:: Boost Format Strings
414 * lua-format:: Lua Format Strings
415 * javascript-format:: JavaScript Format Strings
417 Individual Programming Languages
419 * C:: C, C++, Objective C
420 * sh:: sh - Shell Script
421 * bash:: bash - Bourne-Again Shell Script
423 * Common Lisp:: GNU clisp - Common Lisp
424 * clisp C:: GNU clisp C sources
425 * Emacs Lisp:: Emacs Lisp
427 * Scheme:: GNU guile - Scheme
428 * Smalltalk:: GNU Smalltalk
432 * Pascal:: Pascal - Free Pascal Compiler
433 * wxWidgets:: wxWidgets library
434 * YCP:: YCP - YaST2 scripting language
435 * Tcl:: Tcl - Tk's scripting language
437 * PHP:: PHP Hypertext Preprocessor
439 * GCC-source:: GNU Compiler Collection sources
441 * JavaScript:: JavaScript
446 * Preparing Shell Scripts:: Preparing Shell Scripts for Internationalization
447 * gettext.sh:: Contents of @code{gettext.sh}
448 * gettext Invocation:: Invoking the @code{gettext} program
449 * ngettext Invocation:: Invoking the @code{ngettext} program
450 * envsubst Invocation:: Invoking the @code{envsubst} program
451 * eval_gettext Invocation:: Invoking the @code{eval_gettext} function
452 * eval_ngettext Invocation:: Invoking the @code{eval_ngettext} function
456 * General Problems:: General Problems Parsing Perl Code
457 * Default Keywords:: Which Keywords Will xgettext Look For?
458 * Special Keywords:: How to Extract Hash Keys
459 * Quote-like Expressions:: What are Strings And Quote-like Expressions?
460 * Interpolation I:: Invalid String Interpolation
461 * Interpolation II:: Valid String Interpolation
462 * Parentheses:: When To Use Parentheses
463 * Long Lines:: How To Grok with Long Lines
464 * Perl Pitfalls:: Bugs, Pitfalls, and Things That Do Not Work
466 Internationalizable Data
468 * POT:: POT - Portable Object Template
469 * RST:: Resource String Table
470 * Glade:: Glade - GNOME user interface description
471 * GSettings:: GSettings - GNOME user configuration schema
472 * AppData:: AppData - freedesktop.org application description
473 * Preparing ITS Rules:: Preparing Rules for XML Internationalization
477 * History:: History of GNU @code{gettext}
478 * References:: Related Readings
482 * Usual Language Codes:: Two-letter ISO 639 language codes
483 * Rare Language Codes:: Three-letter ISO 639 language codes
487 * GNU GPL:: GNU General Public License
488 * GNU LGPL:: GNU Lesser General Public License
489 * GNU FDL:: GNU Free Documentation License
496 @node Introduction, Users, Top, Top
497 @chapter Introduction
499 This chapter explains the goals sought in the creation
500 of GNU @code{gettext} and the free Translation Project.
501 Then, it explains a few broad concepts around
502 Native Language Support, and positions message translation with regard
503 to other aspects of national and cultural variance, as they apply
504 to programs. It also surveys those files used to convey the
505 translations. It explains how the various tools interact in the
506 initial generation of these files, and later, how the maintenance
507 cycle should usually operate.
510 @cindex he, she, and they
511 @cindex she, he, and they
512 In this manual, we use @emph{he} when speaking of the programmer or
513 maintainer, @emph{she} when speaking of the translator, and @emph{they}
514 when speaking of the installers or end users of the translated program.
515 This is only a convenience for clarifying the documentation. It is
516 @emph{absolutely} not meant to imply that some roles are more appropriate
517 to males or females. Besides, as you might guess, GNU @code{gettext}
518 is meant to be useful for people using computers, whatever their sex,
519 race, religion or nationality!
521 @cindex bug report address
522 Please send suggestions and corrections to:
526 @r{Internet address:}
527 bug-gnu-gettext@@gnu.org
532 Please include the manual's edition number and update date in your messages.
535 * Why:: The Purpose of GNU @code{gettext}
536 * Concepts:: I18n, L10n, and Such
537 * Aspects:: Aspects in Native Language Support
538 * Files:: Files Conveying Translations
539 * Overview:: Overview of GNU @code{gettext}
542 @node Why, Concepts, Introduction, Introduction
543 @section The Purpose of GNU @code{gettext}
545 Usually, programs are written and documented in English, and use
546 English at execution time to interact with users. This is true
547 not only of GNU software, but also of a great deal of proprietary
548 and free software. Using a common language is quite handy for
549 communication between developers, maintainers and users from all
550 countries. On the other hand, most people are less comfortable with
551 English than with their own native language, and would prefer to
552 use their mother tongue for day to day's work, as far as possible.
553 Many would simply @emph{love} to see their computer screen showing
554 a lot less of English, and far more of their own language.
556 @cindex Translation Project
557 However, to many people, this dream might appear so far fetched that
558 they may believe it is not even worth spending time thinking about
559 it. They have no confidence at all that the dream might ever
560 become true. Yet some have not lost hope, and have organized themselves.
561 The Translation Project is a formalization of this hope into a
562 workable structure, which has a good chance to get all of us nearer
563 the achievement of a truly multi-lingual set of programs.
565 GNU @code{gettext} is an important step for the Translation Project,
566 as it is an asset on which we may build many other steps. This package
567 offers to programmers, translators and even users, a well integrated
568 set of tools and documentation. Specifically, the GNU @code{gettext}
569 utilities are a set of tools that provides a framework within which
570 other free packages may produce multi-lingual messages. These tools
575 A set of conventions about how programs should be written to support
579 A directory and file naming organization for the message catalogs
583 A runtime library supporting the retrieval of translated messages.
586 A few stand-alone programs to massage in various ways the sets of
587 translatable strings, or already translated strings.
590 A library supporting the parsing and creation of files containing
594 A special mode for Emacs@footnote{In this manual, all mentions of Emacs
595 refers to either GNU Emacs or to XEmacs, which people sometimes call FSF
596 Emacs and Lucid Emacs, respectively.} which helps preparing these sets
597 and bringing them up to date.
600 GNU @code{gettext} is designed to minimize the impact of
601 internationalization on program sources, keeping this impact as small
602 and hardly noticeable as possible. Internationalization has better
603 chances of succeeding if it is very light weighted, or at least,
604 appear to be so, when looking at program sources.
606 The Translation Project also uses the GNU @code{gettext} distribution
607 as a vehicle for documenting its structure and methods. This goes
608 beyond the strict technicalities of documenting the GNU @code{gettext}
609 proper. By so doing, translators will find in a single place, as
610 far as possible, all they need to know for properly doing their
611 translating work. Also, this supplemental documentation might also
612 help programmers, and even curious users, in understanding how GNU
613 @code{gettext} is related to the remainder of the Translation
614 Project, and consequently, have a glimpse at the @emph{big picture}.
616 @node Concepts, Aspects, Why, Introduction
617 @section I18n, L10n, and Such
621 Two long words appear all the time when we discuss support of native
622 language in programs, and these words have a precise meaning, worth
623 being explained here, once and for all in this document. The words are
624 @emph{internationalization} and @emph{localization}. Many people,
625 tired of writing these long words over and over again, took the
626 habit of writing @dfn{i18n} and @dfn{l10n} instead, quoting the first
627 and last letter of each word, and replacing the run of intermediate
628 letters by a number merely telling how many such letters there are.
629 But in this manual, in the sake of clarity, we will patiently write
630 the names in full, each time@dots{}
632 @cindex internationalization
633 By @dfn{internationalization}, one refers to the operation by which a
634 program, or a set of programs turned into a package, is made aware of and
635 able to support multiple languages. This is a generalization process,
636 by which the programs are untied from calling only English strings or
637 other English specific habits, and connected to generic ways of doing
638 the same, instead. Program developers may use various techniques to
639 internationalize their programs. Some of these have been standardized.
640 GNU @code{gettext} offers one of these standards. @xref{Programmers}.
643 By @dfn{localization}, one means the operation by which, in a set
644 of programs already internationalized, one gives the program all
645 needed information so that it can adapt itself to handle its input
646 and output in a fashion which is correct for some native language and
647 cultural habits. This is a particularisation process, by which generic
648 methods already implemented in an internationalized program are used
649 in specific ways. The programming environment puts several functions
650 to the programmers disposal which allow this runtime configuration.
651 The formal description of specific set of cultural habits for some
652 country, together with all associated translations targeted to the
653 same native language, is called the @dfn{locale} for this language
654 or country. Users achieve localization of programs by setting proper
655 values to special environment variables, prior to executing those
656 programs, identifying which locale should be used.
658 In fact, locale message support is only one component of the cultural
659 data that makes up a particular locale. There are a whole host of
660 routines and functions provided to aid programmers in developing
661 internationalized software and which allow them to access the data
662 stored in a particular locale. When someone presently refers to a
663 particular locale, they are obviously referring to the data stored
664 within that particular locale. Similarly, if a programmer is referring
665 to ``accessing the locale routines'', they are referring to the
666 complete suite of routines that access all of the locale's information.
669 @cindex Native Language Support
670 @cindex Natural Language Support
671 One uses the expression @dfn{Native Language Support}, or merely NLS,
672 for speaking of the overall activity or feature encompassing both
673 internationalization and localization, allowing for multi-lingual
674 interactions in a program. In a nutshell, one could say that
675 internationalization is the operation by which further localizations
678 Also, very roughly said, when it comes to multi-lingual messages,
679 internationalization is usually taken care of by programmers, and
680 localization is usually taken care of by translators.
682 @node Aspects, Files, Concepts, Introduction
683 @section Aspects in Native Language Support
685 @cindex translation aspects
686 For a totally multi-lingual distribution, there are many things to
687 translate beyond output messages.
691 As of today, GNU @code{gettext} offers a complete toolset for
692 translating messages output by C programs. Perl scripts and shell
693 scripts will also need to be translated. Even if there are today some hooks
694 by which this can be done, these hooks are not integrated as well as they
698 Some programs, like @code{autoconf} or @code{bison}, are able
699 to produce other programs (or scripts). Even if the generating
700 programs themselves are internationalized, the generated programs they
701 produce may need internationalization on their own, and this indirect
702 internationalization could be automated right from the generating
703 program. In fact, quite usually, generating and generated programs
704 could be internationalized independently, as the effort needed is
708 A few programs include textual tables which might need translation
709 themselves, independently of the strings contained in the program
710 itself. For example, @w{RFC 1345} gives an English description for each
711 character which the @code{recode} program is able to reconstruct at execution.
712 Since these descriptions are extracted from the RFC by mechanical means,
713 translating them properly would require a prior translation of the RFC
717 Almost all programs accept options, which are often worded out so to
718 be descriptive for the English readers; one might want to consider
719 offering translated versions for program options as well.
722 Many programs read, interpret, compile, or are somewhat driven by
723 input files which are texts containing keywords, identifiers, or
724 replies which are inherently translatable. For example, one may want
725 @code{gcc} to allow diacriticized characters in identifiers or use
726 translated keywords; @samp{rm -i} might accept something else than
727 @samp{y} or @samp{n} for replies, etc. Even if the program will
728 eventually make most of its output in the foreign languages, one has
729 to decide whether the input syntax, option values, etc., are to be
733 The manual accompanying a package, as well as all documentation files
734 in the distribution, could surely be translated, too. Translating a
735 manual, with the intent of later keeping up with updates, is a major
736 undertaking in itself, generally.
740 As we already stressed, translation is only one aspect of locales.
741 Other internationalization aspects are system services and are handled
742 in GNU @code{libc}. There
743 are many attributes that are needed to define a country's cultural
744 conventions. These attributes include beside the country's native
745 language, the formatting of the date and time, the representation of
746 numbers, the symbols for currency, etc. These local @dfn{rules} are
747 termed the country's locale. The locale represents the knowledge
748 needed to support the country's native attributes.
750 @cindex locale categories
751 There are a few major areas which may vary between countries and
752 hence, define what a locale must describe. The following list helps
753 putting multi-lingual messages into the proper context of other tasks
754 related to locales. See the GNU @code{libc} manual for details.
758 @item Characters and Codesets
761 @cindex character encoding
762 @cindex locale category, LC_CTYPE
764 The codeset most commonly used through out the USA and most English
765 speaking parts of the world is the ASCII codeset. However, there are
766 many characters needed by various locales that are not found within
767 this codeset. The 8-bit @w{ISO 8859-1} code set has most of the special
768 characters needed to handle the major European languages. However, in
769 many cases, choosing @w{ISO 8859-1} is nevertheless not adequate: it
770 doesn't even handle the major European currency. Hence each locale
771 will need to specify which codeset they need to use and will need
772 to have the appropriate character handling routines to cope with
776 @cindex currency symbols
777 @cindex locale category, LC_MONETARY
779 The symbols used vary from country to country as does the position
780 used by the symbol. Software needs to be able to transparently
781 display currency figures in the native mode for each locale.
785 @cindex locale category, LC_TIME
787 The format of date varies between locales. For example, Christmas day
788 in 1994 is written as 12/25/94 in the USA and as 25/12/94 in Australia.
789 Other countries might use @w{ISO 8601} dates, etc.
791 Time of the day may be noted as @var{hh}:@var{mm}, @var{hh}.@var{mm},
792 or otherwise. Some locales require time to be specified in 24-hour
793 mode rather than as AM or PM. Further, the nature and yearly extent
794 of the Daylight Saving correction vary widely between countries.
797 @cindex number format
798 @cindex locale category, LC_NUMERIC
800 Numbers can be represented differently in different locales.
801 For example, the following numbers are all written correctly for
802 their respective locales:
811 Some programs could go further and use different unit systems, like
812 English units or Metric units, or even take into account variants
813 about how numbers are spelled in full.
817 @cindex locale category, LC_MESSAGES
819 The most obvious area is the language support within a locale. This is
820 where GNU @code{gettext} provides the means for developers and users to
821 easily change the language that the software uses to communicate to
826 @cindex locale categories
827 These areas of cultural conventions are called @emph{locale categories}.
828 It is an unfortunate term; @emph{locale aspects} or @emph{locale feature
829 categories} would be a better term, because each ``locale category''
830 describes an area or task that requires localization. The concrete data
831 that describes the cultural conventions for such an area and for a particular
832 culture is also called a @emph{locale category}. In this sense, a locale
833 is composed of several locale categories: the locale category describing
834 the codeset, the locale category describing the formatting of numbers,
835 the locale category containing the translated messages, and so on.
838 Components of locale outside of message handling are standardized in
839 the ISO C standard and the POSIX:2001 standard (also known as the SUSV3
840 specification). GNU @code{libc}
841 fully implements this, and most other modern systems provide a more
842 or less reasonable support for at least some of the missing components.
844 @node Files, Overview, Aspects, Introduction
845 @section Files Conveying Translations
847 @cindex files, @file{.po} and @file{.mo}
848 The letters PO in @file{.po} files means Portable Object, to
849 distinguish it from @file{.mo} files, where MO stands for Machine
850 Object. This paradigm, as well as the PO file format, is inspired
851 by the NLS standard developed by Uniforum, and first implemented by
852 Sun in their Solaris system.
854 PO files are meant to be read and edited by humans, and associate each
855 original, translatable string of a given package with its translation
856 in a particular target language. A single PO file is dedicated to
857 a single target language. If a package supports many languages,
858 there is one such PO file per language supported, and each package
859 has its own set of PO files. These PO files are best created by
860 the @code{xgettext} program, and later updated or refreshed through
861 the @code{msgmerge} program. Program @code{xgettext} extracts all
862 marked messages from a set of C files and initializes a PO file with
863 empty translations. Program @code{msgmerge} takes care of adjusting
864 PO files between releases of the corresponding sources, commenting
865 obsolete entries, initializing new ones, and updating all source
866 line references. Files ending with @file{.pot} are kind of base
867 translation files found in distributions, in PO file format.
869 MO files are meant to be read by programs, and are binary in nature.
870 A few systems already offer tools for creating and handling MO files
871 as part of the Native Language Support coming with the system, but the
872 format of these MO files is often different from system to system,
873 and non-portable. The tools already provided with these systems don't
874 support all the features of GNU @code{gettext}. Therefore GNU
875 @code{gettext} uses its own format for MO files. Files ending with
876 @file{.gmo} are really MO files, when it is known that these files use
879 @node Overview, , Files, Introduction
880 @section Overview of GNU @code{gettext}
882 @cindex overview of @code{gettext}
884 @cindex tutorial of @code{gettext} usage
885 The following diagram summarizes the relation between the files
886 handled by GNU @code{gettext} and the tools acting on these files.
887 It is followed by somewhat detailed explanations, which you should
888 read while keeping an eye on the diagram. Having a clear understanding
889 of these interrelations will surely help programmers, translators
895 Original C Sources ───> Preparation ───> Marked C Sources ───╮
897 â•â”€â”€â”€â”€â”€â”€â”€â”€â”€<─── GNU gettext Library │
898 â•â”€â”€â”€ make <───┤ │
899 │ ╰─────────<────────────────────┬───────────────╯
901 │ â•â”€â”€â”€â”€â”€<─── PACKAGE.pot <─── xgettext <───╯ â•â”€â”€â”€<─── PO Compendium
903 │ │ ╰───╮ │
904 │ ╰───╮ ├───> PO editor ───╮
905 │ ├────> msgmerge ──────> LANG.po ────>────────╯ │
906 │ â•â”€â”€â”€â•¯ │
908 │ ╰─────────────<───────────────╮ │
909 │ ├─── New LANG.po <────────────────────╯
910 │ â•â”€â”€â”€ LANG.gmo <─── msgfmt <───╯
912 │ ╰───> install ───> /.../LANG/PACKAGE.mo ───╮
913 │ ├───> "Hello world!"
914 ╰───────> install ───> /.../bin/PROGRAM ───────╯
921 Original C Sources ---> Preparation ---> Marked C Sources ---.
923 .---------<--- GNU gettext Library |
925 | `---------<--------------------+---------------'
927 | .-----<--- PACKAGE.pot <--- xgettext <---' .---<--- PO Compendium
930 | `---. +---> PO editor ---.
931 | +----> msgmerge ------> LANG.po ---->--------' |
934 | `-------------<---------------. |
935 | +--- New LANG.po <--------------------'
936 | .--- LANG.gmo <--- msgfmt <---'
938 | `---> install ---> /.../LANG/PACKAGE.mo ---.
939 | +---> "Hello world!"
940 `-------> install ---> /.../bin/PROGRAM -------'
945 @cindex marking translatable strings
946 As a programmer, the first step to bringing GNU @code{gettext}
947 into your package is identifying, right in the C sources, those strings
948 which are meant to be translatable, and those which are untranslatable.
949 This tedious job can be done a little more comfortably using emacs PO
950 mode, but you can use any means familiar to you for modifying your
951 C sources. Beside this some other simple, standard changes are needed to
952 properly initialize the translation library. @xref{Sources}, for
953 more information about all this.
955 For newly written software the strings of course can and should be
956 marked while writing it. The @code{gettext} approach makes this
957 very easy. Simply put the following lines at the beginning of each file
958 or in a central header file:
962 #define _(String) (String)
963 #define N_(String) String
964 #define textdomain(Domain)
965 #define bindtextdomain(Package, Directory)
970 Doing this allows you to prepare the sources for internationalization.
971 Later when you feel ready for the step to use the @code{gettext} library
972 simply replace these definitions by the following:
974 @cindex include file @file{libintl.h}
978 #define _(String) gettext (String)
979 #define gettext_noop(String) String
980 #define N_(String) gettext_noop (String)
984 @cindex link with @file{libintl}
987 and link against @file{libintl.a} or @file{libintl.so}. Note that on
988 GNU systems, you don't need to link with @code{libintl} because the
989 @code{gettext} library functions are already contained in GNU libc.
990 That is all you have to change.
992 @cindex template PO file
993 @cindex files, @file{.pot}
994 Once the C sources have been modified, the @code{xgettext} program
995 is used to find and extract all translatable strings, and create a
996 PO template file out of all these. This @file{@var{package}.pot} file
997 contains all original program strings. It has sets of pointers to
998 exactly where in C sources each string is used. All translations
999 are set to empty. The letter @code{t} in @file{.pot} marks this as
1000 a Template PO file, not yet oriented towards any particular language.
1001 @xref{xgettext Invocation}, for more details about how one calls the
1002 @code{xgettext} program. If you are @emph{really} lazy, you might
1003 be interested at working a lot more right away, and preparing the
1004 whole distribution setup (@pxref{Maintainers}). By doing so, you
1005 spare yourself typing the @code{xgettext} command, as @code{make}
1006 should now generate the proper things automatically for you!
1008 The first time through, there is no @file{@var{lang}.po} yet, so the
1009 @code{msgmerge} step may be skipped and replaced by a mere copy of
1010 @file{@var{package}.pot} to @file{@var{lang}.po}, where @var{lang}
1011 represents the target language. See @ref{Creating} for details.
1013 Then comes the initial translation of messages. Translation in
1014 itself is a whole matter, still exclusively meant for humans,
1015 and whose complexity far overwhelms the level of this manual.
1016 Nevertheless, a few hints are given in some other chapter of this
1017 manual (@pxref{Translators}). You will also find there indications
1018 about how to contact translating teams, or becoming part of them,
1019 for sharing your translating concerns with others who target the same
1022 While adding the translated messages into the @file{@var{lang}.po}
1023 PO file, if you are not using one of the dedicated PO file editors
1024 (@pxref{Editing}), you are on your own
1025 for ensuring that your efforts fully respect the PO file format, and quoting
1026 conventions (@pxref{PO Files}). This is surely not an impossible task,
1027 as this is the way many people have handled PO files around 1995.
1028 On the other hand, by using a PO file editor, most details
1029 of PO file format are taken care of for you, but you have to acquire
1030 some familiarity with PO file editor itself.
1032 If some common translations have already been saved into a compendium
1033 PO file, translators may use PO mode for initializing untranslated
1034 entries from the compendium, and also save selected translations into
1035 the compendium, updating it (@pxref{Compendium}). Compendium files
1036 are meant to be exchanged between members of a given translation team.
1038 Programs, or packages of programs, are dynamic in nature: users write
1039 bug reports and suggestion for improvements, maintainers react by
1040 modifying programs in various ways. The fact that a package has
1041 already been internationalized should not make maintainers shy
1042 of adding new strings, or modifying strings already translated.
1043 They just do their job the best they can. For the Translation
1044 Project to work smoothly, it is important that maintainers do not
1045 carry translation concerns on their already loaded shoulders, and that
1046 translators be kept as free as possible of programming concerns.
1048 The only concern maintainers should have is carefully marking new
1049 strings as translatable, when they should be, and do not otherwise
1050 worry about them being translated, as this will come in proper time.
1051 Consequently, when programs and their strings are adjusted in various
1052 ways by maintainers, and for matters usually unrelated to translation,
1053 @code{xgettext} would construct @file{@var{package}.pot} files which are
1054 evolving over time, so the translations carried by @file{@var{lang}.po}
1055 are slowly fading out of date.
1057 @cindex evolution of packages
1058 It is important for translators (and even maintainers) to understand
1059 that package translation is a continuous process in the lifetime of a
1060 package, and not something which is done once and for all at the start.
1061 After an initial burst of translation activity for a given package,
1062 interventions are needed once in a while, because here and there,
1063 translated entries become obsolete, and new untranslated entries
1064 appear, needing translation.
1066 The @code{msgmerge} program has the purpose of refreshing an already
1067 existing @file{@var{lang}.po} file, by comparing it with a newer
1068 @file{@var{package}.pot} template file, extracted by @code{xgettext}
1069 out of recent C sources. The refreshing operation adjusts all
1070 references to C source locations for strings, since these strings
1071 move as programs are modified. Also, @code{msgmerge} comments out as
1072 obsolete, in @file{@var{lang}.po}, those already translated entries
1073 which are no longer used in the program sources (@pxref{Obsolete
1074 Entries}). It finally discovers new strings and inserts them in
1075 the resulting PO file as untranslated entries (@pxref{Untranslated
1076 Entries}). @xref{msgmerge Invocation}, for more information about what
1077 @code{msgmerge} really does.
1079 Whatever route or means taken, the goal is to obtain an updated
1080 @file{@var{lang}.po} file offering translations for all strings.
1082 The temporal mobility, or fluidity of PO files, is an integral part of
1083 the translation game, and should be well understood, and accepted.
1084 People resisting it will have a hard time participating in the
1085 Translation Project, or will give a hard time to other participants! In
1086 particular, maintainers should relax and include all available official
1087 PO files in their distributions, even if these have not recently been
1088 updated, without exerting pressure on the translator teams to get the
1089 job done. The pressure should rather come
1090 from the community of users speaking a particular language, and
1091 maintainers should consider themselves fairly relieved of any concern
1092 about the adequacy of translation files. On the other hand, translators
1093 should reasonably try updating the PO files they are responsible for,
1094 while the package is undergoing pretest, prior to an official
1097 Once the PO file is complete and dependable, the @code{msgfmt} program
1098 is used for turning the PO file into a machine-oriented format, which
1099 may yield efficient retrieval of translations by the programs of the
1100 package, whenever needed at runtime (@pxref{MO Files}). @xref{msgfmt
1101 Invocation}, for more information about all modes of execution
1102 for the @code{msgfmt} program.
1104 Finally, the modified and marked C sources are compiled and linked
1105 with the GNU @code{gettext} library, usually through the operation of
1106 @code{make}, given a suitable @file{Makefile} exists for the project,
1107 and the resulting executable is installed somewhere users will find it.
1108 The MO files themselves should also be properly installed. Given the
1109 appropriate environment variables are set (@pxref{Setting the POSIX Locale}),
1110 the program should localize itself automatically, whenever it executes.
1112 The remainder of this manual has the purpose of explaining in depth the various
1113 steps outlined above.
1115 @node Users, PO Files, Introduction, Top
1116 @chapter The User's View
1118 Nowadays, when users log into a computer, they usually find that all
1119 their programs show messages in their native language -- at least for
1120 users of languages with an active free software community, like French or
1121 German; to a lesser extent for languages with a smaller participation in
1122 free software and the GNU project, like Hindi and Filipino.
1124 How does this work? How can the user influence the language that is used
1125 by the programs? This chapter will answer it.
1128 * System Installation:: Questions During Operating System Installation
1129 * Setting the GUI Locale:: How to Specify the Locale Used by GUI Programs
1130 * Setting the POSIX Locale:: How to Specify the Locale According to POSIX
1131 * Installing Localizations:: How to Install Additional Translations
1134 @node System Installation, Setting the GUI Locale, Users, Users
1135 @section Operating System Installation
1137 The default language is often already specified during operating system
1138 installation. When the operating system is installed, the installer
1139 typically asks for the language used for the installation process and,
1140 separately, for the language to use in the installed system. Some OS
1141 installers only ask for the language once.
1143 This determines the system-wide default language for all users. But the
1144 installers often give the possibility to install extra localizations for
1145 additional languages. For example, the localizations of KDE (the K
1146 Desktop Environment) and OpenOffice.org are often bundled separately,
1147 as one installable package per language.
1149 At this point it is good to consider the intended use of the machine: If
1150 it is a machine designated for personal use, additional localizations are
1151 probably not necessary. If, however, the machine is in use in an
1152 organization or company that has international relationships, one can
1153 consider the needs of guest users. If you have a guest from abroad, for
1154 a week, what could be his preferred locales? It may be worth installing
1155 these additional localizations ahead of time, since they cost only a bit
1156 of disk space at this point.
1158 The system-wide default language is the locale configuration that is used
1159 when a new user account is created. But the user can have his own locale
1160 configuration that is different from the one of the other users of the
1161 same machine. He can specify it, typically after the first login, as
1162 described in the next section.
1164 @node Setting the GUI Locale, Setting the POSIX Locale, System Installation, Users
1165 @section Setting the Locale Used by GUI Programs
1167 The immediately available programs in a user's desktop come from a group
1168 of programs called a ``desktop environment''; it usually includes the window
1169 manager, a web browser, a text editor, and more. The most common free
1170 desktop environments are KDE, GNOME, and Xfce.
1172 The locale used by GUI programs of the desktop environment can be specified
1173 in a configuration screen called ``control center'', ``language settings''
1174 or ``country settings''.
1176 Individual GUI programs that are not part of the desktop environment can
1177 have their locale specified either in a settings panel, or through environment
1180 For some programs, it is possible to specify the locale through environment
1181 variables, possibly even to a different locale than the desktop's locale.
1182 This means, instead of starting a program through a menu or from the file
1183 system, you can start it from the command-line, after having set some
1184 environment variables. The environment variables can be those specified
1185 in the next section (@ref{Setting the POSIX Locale}); for some versions of
1186 KDE, however, the locale is specified through a variable @code{KDE_LANG},
1187 rather than @code{LANG} or @code{LC_ALL}.
1189 @node Setting the POSIX Locale, Installing Localizations, Setting the GUI Locale, Users
1190 @section Setting the Locale through Environment Variables
1192 As a user, if your language has been installed for this package, in the
1193 simplest case, you only have to set the @code{LANG} environment variable
1194 to the appropriate @samp{@var{ll}_@var{CC}} combination. For example,
1195 let's suppose that you speak German and live in Germany. At the shell
1196 prompt, merely execute
1197 @w{@samp{setenv LANG de_DE}} (in @code{csh}),
1198 @w{@samp{export LANG; LANG=de_DE}} (in @code{sh}) or
1199 @w{@samp{export LANG=de_DE}} (in @code{bash}). This can be done from your
1200 @file{.login} or @file{.profile} file, once and for all.
1203 * Locale Names:: How a Locale Specification Looks Like
1204 * Locale Environment Variables:: Which Environment Variable Specfies What
1205 * The LANGUAGE variable:: How to Specify a Priority List of Languages
1208 @node Locale Names, Locale Environment Variables, Setting the POSIX Locale, Setting the POSIX Locale
1209 @subsection Locale Names
1211 A locale name usually has the form @samp{@var{ll}_@var{CC}}. Here
1212 @samp{@var{ll}} is an @w{ISO 639} two-letter language code, and
1213 @samp{@var{CC}} is an @w{ISO 3166} two-letter country code. For example,
1214 for German in Germany, @var{ll} is @code{de}, and @var{CC} is @code{DE}.
1215 You find a list of the language codes in appendix @ref{Language Codes} and
1216 a list of the country codes in appendix @ref{Country Codes}.
1218 You might think that the country code specification is redundant. But in
1219 fact, some languages have dialects in different countries. For example,
1220 @samp{de_AT} is used for Austria, and @samp{pt_BR} for Brazil. The country
1221 code serves to distinguish the dialects.
1223 Many locale names have an extended syntax
1224 @samp{@var{ll}_@var{CC}.@var{encoding}} that also specifies the character
1225 encoding. These are in use because between 2000 and 2005, most users have
1226 switched to locales in UTF-8 encoding. For example, the German locale on
1227 glibc systems is nowadays @samp{de_DE.UTF-8}. The older name @samp{de_DE}
1228 still refers to the German locale as of 2000 that stores characters in
1229 ISO-8859-1 encoding -- a text encoding that cannot even accommodate the Euro
1232 Some locale names use @samp{@var{ll}_@var{CC}.@@@var{variant}} instead of
1233 @samp{@var{ll}_@var{CC}}. The @samp{@@@var{variant}} can denote any kind of
1234 characteristics that is not already implied by the language @var{ll} and
1235 the country @var{CC}. It can denote a particular monetary unit. For example,
1236 on glibc systems, @samp{de_DE@@euro} denotes the locale that uses the Euro
1237 currency, in contrast to the older locale @samp{de_DE} which implies the use
1238 of the currency before 2002. It can also denote a dialect of the language,
1239 or the script used to write text (for example, @samp{sr_RS@@latin} uses the
1240 Latin script, whereas @samp{sr_RS} uses the Cyrillic script to write Serbian),
1241 or the orthography rules, or similar.
1243 On other systems, some variations of this scheme are used, such as
1244 @samp{@var{ll}}. You can get the list of locales supported by your system
1245 for your language by running the command @samp{locale -a | grep '^@var{ll}'}.
1247 There is also a special locale, called @samp{C}.
1248 @c Don't mention that this locale also has the name "POSIX". When we talk about
1249 @c the "POSIX locale", we mean the "locale as specified in the POSIX way", and
1250 @c mentioning a locale called "POSIX" would bring total confusion.
1251 When it is used, it disables all localization: in this locale, all programs
1252 standardized by POSIX use English messages and an unspecified character
1253 encoding (often US-ASCII, but sometimes also ISO-8859-1 or UTF-8, depending on
1254 the operating system).
1256 @node Locale Environment Variables, The LANGUAGE variable, Locale Names, Setting the POSIX Locale
1257 @subsection Locale Environment Variables
1258 @cindex setting up @code{gettext} at run time
1259 @cindex selecting message language
1260 @cindex language selection
1262 A locale is composed of several @emph{locale categories}, see @ref{Aspects}.
1263 When a program looks up locale dependent values, it does this according to
1264 the following environment variables, in priority order:
1267 @vindex LANGUAGE@r{, environment variable}
1268 @item @code{LANGUAGE}
1269 @vindex LC_ALL@r{, environment variable}
1271 @vindex LC_CTYPE@r{, environment variable}
1272 @vindex LC_NUMERIC@r{, environment variable}
1273 @vindex LC_TIME@r{, environment variable}
1274 @vindex LC_COLLATE@r{, environment variable}
1275 @vindex LC_MONETARY@r{, environment variable}
1276 @vindex LC_MESSAGES@r{, environment variable}
1277 @item @code{LC_xxx}, according to selected locale category:
1278 @code{LC_CTYPE}, @code{LC_NUMERIC}, @code{LC_TIME}, @code{LC_COLLATE},
1279 @code{LC_MONETARY}, @code{LC_MESSAGES}, ...
1280 @vindex LANG@r{, environment variable}
1284 Variables whose value is set but is empty are ignored in this lookup.
1286 @code{LANG} is the normal environment variable for specifying a locale.
1287 As a user, you normally set this variable (unless some of the other variables
1288 have already been set by the system, in @file{/etc/profile} or similar
1289 initialization files).
1291 @code{LC_CTYPE}, @code{LC_NUMERIC}, @code{LC_TIME}, @code{LC_COLLATE},
1292 @code{LC_MONETARY}, @code{LC_MESSAGES}, and so on, are the environment
1293 variables meant to override @code{LANG} and affecting a single locale
1294 category only. For example, assume you are a Swedish user in Spain, and you
1295 want your programs to handle numbers and dates according to Spanish
1296 conventions, and only the messages should be in Swedish. Then you could
1297 create a locale named @samp{sv_ES} or @samp{sv_ES.UTF-8} by use of the
1298 @code{localedef} program. But it is simpler, and achieves the same effect,
1299 to set the @code{LANG} variable to @code{es_ES.UTF-8} and the
1300 @code{LC_MESSAGES} variable to @code{sv_SE.UTF-8}; these two locales come
1301 already preinstalled with the operating system.
1303 @code{LC_ALL} is an environment variable that overrides all of these.
1304 It is typically used in scripts that run particular programs. For example,
1305 @code{configure} scripts generated by GNU autoconf use @code{LC_ALL} to make
1306 sure that the configuration tests don't operate in locale dependent ways.
1308 Some systems, unfortunately, set @code{LC_ALL} in @file{/etc/profile} or in
1309 similar initialization files. As a user, you therefore have to unset this
1310 variable if you want to set @code{LANG} and optionally some of the other
1311 @code{LC_xxx} variables.
1313 The @code{LANGUAGE} variable is described in the next subsection.
1315 @node The LANGUAGE variable, , Locale Environment Variables, Setting the POSIX Locale
1316 @subsection Specifying a Priority List of Languages
1318 Not all programs have translations for all languages. By default, an
1319 English message is shown in place of a nonexistent translation. If you
1320 understand other languages, you can set up a priority list of languages.
1321 This is done through a different environment variable, called
1322 @code{LANGUAGE}. GNU @code{gettext} gives preference to @code{LANGUAGE}
1323 over @code{LC_ALL} and @code{LANG} for the purpose of message handling,
1324 but you still need to have @code{LANG} (or @code{LC_ALL}) set to the primary
1325 language; this is required by other parts of the system libraries.
1326 For example, some Swedish users who would rather read translations in
1327 German than English for when Swedish is not available, set @code{LANGUAGE}
1328 to @samp{sv:de} while leaving @code{LANG} to @samp{sv_SE}.
1330 Special advice for Norwegian users: The language code for Norwegian
1331 bokm@ringaccent{a}l changed from @samp{no} to @samp{nb} recently (in 2003).
1332 During the transition period, while some message catalogs for this language
1333 are installed under @samp{nb} and some older ones under @samp{no}, it is
1334 recommended for Norwegian users to set @code{LANGUAGE} to @samp{nb:no} so that
1335 both newer and older translations are used.
1337 In the @code{LANGUAGE} environment variable, but not in the other
1338 environment variables, @samp{@var{ll}_@var{CC}} combinations can be
1339 abbreviated as @samp{@var{ll}} to denote the language's main dialect.
1340 For example, @samp{de} is equivalent to @samp{de_DE} (German as spoken in
1341 Germany), and @samp{pt} to @samp{pt_PT} (Portuguese as spoken in Portugal)
1344 Note: The variable @code{LANGUAGE} is ignored if the locale is set to
1345 @samp{C}. In other words, you have to first enable localization, by setting
1346 @code{LANG} (or @code{LC_ALL}) to a value other than @samp{C}, before you can
1347 use a language priority list through the @code{LANGUAGE} variable.
1349 @node Installing Localizations, , Setting the POSIX Locale, Users
1350 @section Installing Translations for Particular Programs
1351 @cindex Translation Matrix
1352 @cindex available translations
1354 Languages are not equally well supported in all packages using GNU
1355 @code{gettext}, and more translations are added over time. Usually, you
1356 use the translations that are shipped with the operating system
1357 or with particular packages that you install afterwards. But you can also
1358 install newer localizations directly. For doing this, you will need an
1359 understanding where each localization file is stored on the file system.
1361 @cindex @file{ABOUT-NLS} file
1362 For programs that participate in the Translation Project, you can start
1363 looking for translations here:
1364 @url{http://translationproject.org/team/index.html}.
1365 A snapshot of this information is also found in the @file{ABOUT-NLS} file
1366 that is shipped with GNU gettext.
1368 For programs that are part of the KDE project, the starting point is:
1369 @url{http://i18n.kde.org/}.
1371 For programs that are part of the GNOME project, the starting point is:
1372 @url{http://www.gnome.org/i18n/}.
1374 For other programs, you may check whether the program's source code package
1375 contains some @file{@var{ll}.po} files; often they are kept together in a
1376 directory called @file{po/}. Each @file{@var{ll}.po} file contains the
1377 message translations for the language whose abbreviation of @var{ll}.
1379 @node PO Files, Sources, Users, Top
1380 @chapter The Format of PO Files
1381 @cindex PO files' format
1382 @cindex file format, @file{.po}
1384 The GNU @code{gettext} toolset helps programmers and translators
1385 at producing, updating and using translation files, mainly those
1386 PO files which are textual, editable files. This chapter explains
1387 the format of PO files.
1389 A PO file is made up of many entries, each entry holding the relation
1390 between an original untranslated string and its corresponding
1391 translation. All entries in a given PO file usually pertain
1392 to a single project, and all translations are expressed in a single
1393 target language. One PO file @dfn{entry} has the following schematic
1398 # @var{translator-comments}
1399 #. @var{extracted-comments}
1400 #: @var{reference}@dots{}
1401 #, @var{flag}@dots{}
1402 #| msgid @var{previous-untranslated-string}
1403 msgid @var{untranslated-string}
1404 msgstr @var{translated-string}
1407 The general structure of a PO file should be well understood by
1408 the translator. When using PO mode, very little has to be known
1409 about the format details, as PO mode takes care of them for her.
1411 A simple entry can look like this:
1415 msgid "Unknown system error"
1416 msgstr "Error desconegut del sistema"
1419 @cindex comments, translator
1420 @cindex comments, automatic
1421 @cindex comments, extracted
1422 Entries begin with some optional white space. Usually, when generated
1423 through GNU @code{gettext} tools, there is exactly one blank line
1424 between entries. Then comments follow, on lines all starting with the
1425 character @code{#}. There are two kinds of comments: those which have
1426 some white space immediately following the @code{#} - the @var{translator
1427 comments} -, which comments are created and maintained exclusively by the
1428 translator, and those which have some non-white character just after the
1429 @code{#} - the @var{automatic comments} -, which comments are created and
1430 maintained automatically by GNU @code{gettext} tools. Comment lines
1431 starting with @code{#.} contain comments given by the programmer, directed
1432 at the translator; these comments are called @var{extracted comments}
1433 because the @code{xgettext} program extracts them from the program's
1434 source code. Comment lines starting with @code{#:} contain references to
1435 the program's source code. Comment lines starting with @code{#,} contain
1436 flags; more about these below. Comment lines starting with @code{#|}
1437 contain the previous untranslated string for which the translator gave
1440 All comments, of either kind, are optional.
1444 After white space and comments, entries show two strings, namely
1445 first the untranslated string as it appears in the original program
1446 sources, and then, the translation of this string. The original
1447 string is introduced by the keyword @code{msgid}, and the translation,
1448 by @code{msgstr}. The two strings, untranslated and translated,
1449 are quoted in various ways in the PO file, using @code{"}
1450 delimiters and @code{\} escapes, but the translator does not really
1451 have to pay attention to the precise quoting format, as PO mode fully
1452 takes care of quoting for her.
1454 The @code{msgid} strings, as well as automatic comments, are produced
1455 and managed by other GNU @code{gettext} tools, and PO mode does not
1456 provide means for the translator to alter these. The most she can
1457 do is merely deleting them, and only by deleting the whole entry.
1458 On the other hand, the @code{msgstr} string, as well as translator
1459 comments, are really meant for the translator, and PO mode gives her
1460 the full control she needs.
1462 The comment lines beginning with @code{#,} are special because they are
1463 not completely ignored by the programs as comments generally are. The
1464 comma separated list of @var{flag}s is used by the @code{msgfmt}
1465 program to give the user some better diagnostic messages. Currently
1466 there are two forms of flags defined:
1470 @kwindex fuzzy@r{ flag}
1471 This flag can be generated by the @code{msgmerge} program or it can be
1472 inserted by the translator herself. It shows that the @code{msgstr}
1473 string might not be a correct translation (anymore). Only the translator
1474 can judge if the translation requires further modification, or is
1475 acceptable as is. Once satisfied with the translation, she then removes
1476 this @code{fuzzy} attribute. The @code{msgmerge} program inserts this
1477 when it combined the @code{msgid} and @code{msgstr} entries after fuzzy
1478 search only. @xref{Fuzzy Entries}.
1481 @kwindex c-format@r{ flag}
1483 @kwindex no-c-format@r{ flag}
1484 These flags should not be added by a human. Instead only the
1485 @code{xgettext} program adds them. In an automated PO file processing
1486 system as proposed here, the user's changes would be thrown away again as
1487 soon as the @code{xgettext} program generates a new template file.
1489 The @code{c-format} flag indicates that the untranslated string and the
1490 translation are supposed to be C format strings. The @code{no-c-format}
1491 flag indicates that they are not C format strings, even though the untranslated
1492 string happens to look like a C format string (with @samp{%} directives).
1494 When the @code{c-format} flag is given for a string the @code{msgfmt}
1495 program does some more tests to check the validity of the translation.
1496 @xref{msgfmt Invocation}, @ref{c-format Flag} and @ref{c-format}.
1499 @kwindex objc-format@r{ flag}
1500 @itemx no-objc-format
1501 @kwindex no-objc-format@r{ flag}
1502 Likewise for Objective C, see @ref{objc-format}.
1505 @kwindex sh-format@r{ flag}
1507 @kwindex no-sh-format@r{ flag}
1508 Likewise for Shell, see @ref{sh-format}.
1511 @kwindex python-format@r{ flag}
1512 @itemx no-python-format
1513 @kwindex no-python-format@r{ flag}
1514 Likewise for Python, see @ref{python-format}.
1516 @item python-brace-format
1517 @kwindex python-brace-format@r{ flag}
1518 @itemx no-python-brace-format
1519 @kwindex no-python-brace-format@r{ flag}
1520 Likewise for Python brace, see @ref{python-format}.
1523 @kwindex lisp-format@r{ flag}
1524 @itemx no-lisp-format
1525 @kwindex no-lisp-format@r{ flag}
1526 Likewise for Lisp, see @ref{lisp-format}.
1529 @kwindex elisp-format@r{ flag}
1530 @itemx no-elisp-format
1531 @kwindex no-elisp-format@r{ flag}
1532 Likewise for Emacs Lisp, see @ref{elisp-format}.
1535 @kwindex librep-format@r{ flag}
1536 @itemx no-librep-format
1537 @kwindex no-librep-format@r{ flag}
1538 Likewise for librep, see @ref{librep-format}.
1541 @kwindex scheme-format@r{ flag}
1542 @itemx no-scheme-format
1543 @kwindex no-scheme-format@r{ flag}
1544 Likewise for Scheme, see @ref{scheme-format}.
1546 @item smalltalk-format
1547 @kwindex smalltalk-format@r{ flag}
1548 @itemx no-smalltalk-format
1549 @kwindex no-smalltalk-format@r{ flag}
1550 Likewise for Smalltalk, see @ref{smalltalk-format}.
1553 @kwindex java-format@r{ flag}
1554 @itemx no-java-format
1555 @kwindex no-java-format@r{ flag}
1556 Likewise for Java, see @ref{java-format}.
1559 @kwindex csharp-format@r{ flag}
1560 @itemx no-csharp-format
1561 @kwindex no-csharp-format@r{ flag}
1562 Likewise for C#, see @ref{csharp-format}.
1565 @kwindex awk-format@r{ flag}
1566 @itemx no-awk-format
1567 @kwindex no-awk-format@r{ flag}
1568 Likewise for awk, see @ref{awk-format}.
1570 @item object-pascal-format
1571 @kwindex object-pascal-format@r{ flag}
1572 @itemx no-object-pascal-format
1573 @kwindex no-object-pascal-format@r{ flag}
1574 Likewise for Object Pascal, see @ref{object-pascal-format}.
1577 @kwindex ycp-format@r{ flag}
1578 @itemx no-ycp-format
1579 @kwindex no-ycp-format@r{ flag}
1580 Likewise for YCP, see @ref{ycp-format}.
1583 @kwindex tcl-format@r{ flag}
1584 @itemx no-tcl-format
1585 @kwindex no-tcl-format@r{ flag}
1586 Likewise for Tcl, see @ref{tcl-format}.
1589 @kwindex perl-format@r{ flag}
1590 @itemx no-perl-format
1591 @kwindex no-perl-format@r{ flag}
1592 Likewise for Perl, see @ref{perl-format}.
1594 @item perl-brace-format
1595 @kwindex perl-brace-format@r{ flag}
1596 @itemx no-perl-brace-format
1597 @kwindex no-perl-brace-format@r{ flag}
1598 Likewise for Perl brace, see @ref{perl-format}.
1601 @kwindex php-format@r{ flag}
1602 @itemx no-php-format
1603 @kwindex no-php-format@r{ flag}
1604 Likewise for PHP, see @ref{php-format}.
1606 @item gcc-internal-format
1607 @kwindex gcc-internal-format@r{ flag}
1608 @itemx no-gcc-internal-format
1609 @kwindex no-gcc-internal-format@r{ flag}
1610 Likewise for the GCC sources, see @ref{gcc-internal-format}.
1612 @item gfc-internal-format
1613 @kwindex gfc-internal-format@r{ flag}
1614 @itemx no-gfc-internal-format
1615 @kwindex no-gfc-internal-format@r{ flag}
1616 Likewise for the GNU Fortran Compiler sources, see @ref{gfc-internal-format}.
1619 @kwindex qt-format@r{ flag}
1621 @kwindex no-qt-format@r{ flag}
1622 Likewise for Qt, see @ref{qt-format}.
1624 @item qt-plural-format
1625 @kwindex qt-plural-format@r{ flag}
1626 @itemx no-qt-plural-format
1627 @kwindex no-qt-plural-format@r{ flag}
1628 Likewise for Qt plural forms, see @ref{qt-plural-format}.
1631 @kwindex kde-format@r{ flag}
1632 @itemx no-kde-format
1633 @kwindex no-kde-format@r{ flag}
1634 Likewise for KDE, see @ref{kde-format}.
1637 @kwindex boost-format@r{ flag}
1638 @itemx no-boost-format
1639 @kwindex no-boost-format@r{ flag}
1640 Likewise for Boost, see @ref{boost-format}.
1643 @kwindex lua-format@r{ flag}
1644 @itemx no-lua-format
1645 @kwindex no-lua-format@r{ flag}
1646 Likewise for Lua, see @ref{lua-format}.
1648 @item javascript-format
1649 @kwindex javascript-format@r{ flag}
1650 @itemx no-javascript-format
1651 @kwindex no-javascript-format@r{ flag}
1652 Likewise for JavaScript, see @ref{javascript-format}.
1657 @cindex context, in PO files
1658 It is also possible to have entries with a context specifier. They look like
1663 # @var{translator-comments}
1664 #. @var{extracted-comments}
1665 #: @var{reference}@dots{}
1666 #, @var{flag}@dots{}
1667 #| msgctxt @var{previous-context}
1668 #| msgid @var{previous-untranslated-string}
1669 msgctxt @var{context}
1670 msgid @var{untranslated-string}
1671 msgstr @var{translated-string}
1674 The context serves to disambiguate messages with the same
1675 @var{untranslated-string}. It is possible to have several entries with
1676 the same @var{untranslated-string} in a PO file, provided that they each
1677 have a different @var{context}. Note that an empty @var{context} string
1678 and an absent @code{msgctxt} line do not mean the same thing.
1680 @kwindex msgid_plural
1681 @cindex plural forms, in PO files
1682 A different kind of entries is used for translations which involve
1687 # @var{translator-comments}
1688 #. @var{extracted-comments}
1689 #: @var{reference}@dots{}
1690 #, @var{flag}@dots{}
1691 #| msgid @var{previous-untranslated-string-singular}
1692 #| msgid_plural @var{previous-untranslated-string-plural}
1693 msgid @var{untranslated-string-singular}
1694 msgid_plural @var{untranslated-string-plural}
1695 msgstr[0] @var{translated-string-case-0}
1697 msgstr[N] @var{translated-string-case-n}
1700 Such an entry can look like this:
1703 #: src/msgcmp.c:338 src/po-lex.c:699
1705 msgid "found %d fatal error"
1706 msgid_plural "found %d fatal errors"
1707 msgstr[0] "s'ha trobat %d error fatal"
1708 msgstr[1] "s'han trobat %d errors fatals"
1711 Here also, a @code{msgctxt} context can be specified before @code{msgid},
1714 Here, additional kinds of flags can be used:
1718 @kwindex range:@r{ flag}
1719 This flag is followed by a range of non-negative numbers, using the syntax
1720 @code{range: @var{minimum-value}..@var{maximum-value}}. It designates the
1721 possible values that the numeric parameter of the message can take. In some
1722 languages, translators may produce slightly better translations if they know
1723 that the value can only take on values between 0 and 10, for example.
1726 The @var{previous-untranslated-string} is optionally inserted by the
1727 @code{msgmerge} program, at the same time when it marks a message fuzzy.
1728 It helps the translator to see which changes were done by the developers
1729 on the @var{untranslated-string}.
1731 It happens that some lines, usually whitespace or comments, follow the
1732 very last entry of a PO file. Such lines are not part of any entry,
1733 and will be dropped when the PO file is processed by the tools, or may
1734 disturb some PO file editors.
1736 The remainder of this section may be safely skipped by those using
1737 a PO file editor, yet it may be interesting for everybody to have a better
1738 idea of the precise format of a PO file. On the other hand, those
1739 wishing to modify PO files by hand should carefully continue reading on.
1741 An empty @var{untranslated-string} is reserved to contain the header
1742 entry with the meta information (@pxref{Header Entry}). This header
1743 entry should be the first entry of the file. The empty
1744 @var{untranslated-string} is reserved for this purpose and must
1745 not be used anywhere else.
1747 Each of @var{untranslated-string} and @var{translated-string} respects
1748 the C syntax for a character string, including the surrounding quotes
1749 and embedded backslashed escape sequences. When the time comes
1750 to write multi-line strings, one should not use escaped newlines.
1751 Instead, a closing quote should follow the last character on the
1752 line to be continued, and an opening quote should resume the string
1753 at the beginning of the following PO file line. For example:
1757 "Here is an example of how one might continue a very long string\n"
1758 "for the common case the string represents multi-line output.\n"
1762 In this example, the empty string is used on the first line, to
1763 allow better alignment of the @code{H} from the word @samp{Here}
1764 over the @code{f} from the word @samp{for}. In this example, the
1765 @code{msgid} keyword is followed by three strings, which are meant
1766 to be concatenated. Concatenating the empty string does not change
1767 the resulting overall string, but it is a way for us to comply with
1768 the necessity of @code{msgid} to be followed by a string on the same
1769 line, while keeping the multi-line presentation left-justified, as
1770 we find this to be a cleaner disposition. The empty string could have
1771 been omitted, but only if the string starting with @samp{Here} was
1772 promoted on the first line, right after @code{msgid}.@footnote{This
1773 limitation is not imposed by GNU @code{gettext}, but is for compatibility
1774 with the @code{msgfmt} implementation on Solaris.} It was not really necessary
1775 either to switch between the two last quoted strings immediately after
1776 the newline @samp{\n}, the switch could have occurred after @emph{any}
1777 other character, we just did it this way because it is neater.
1779 @cindex newlines in PO files
1780 One should carefully distinguish between end of lines marked as
1781 @samp{\n} @emph{inside} quotes, which are part of the represented
1782 string, and end of lines in the PO file itself, outside string quotes,
1783 which have no incidence on the represented string.
1785 @cindex comments in PO files
1786 Outside strings, white lines and comments may be used freely.
1787 Comments start at the beginning of a line with @samp{#} and extend
1788 until the end of the PO file line. Comments written by translators
1789 should have the initial @samp{#} immediately followed by some white
1790 space. If the @samp{#} is not immediately followed by white space,
1791 this comment is most likely generated and managed by specialized GNU
1792 tools, and might disappear or be replaced unexpectedly when the PO
1793 file is given to @code{msgmerge}.
1795 @node Sources, Template, PO Files, Top
1796 @chapter Preparing Program Sources
1797 @cindex preparing programs for translation
1799 @c FIXME: Rewrite (the whole chapter).
1801 For the programmer, changes to the C source code fall into three
1802 categories. First, you have to make the localization functions
1803 known to all modules needing message translation. Second, you should
1804 properly trigger the operation of GNU @code{gettext} when the program
1805 initializes, usually from the @code{main} function. Last, you should
1806 identify, adjust and mark all constant strings in your program
1807 needing translation.
1810 * Importing:: Importing the @code{gettext} declaration
1811 * Triggering:: Triggering @code{gettext} Operations
1812 * Preparing Strings:: Preparing Translatable Strings
1813 * Mark Keywords:: How Marks Appear in Sources
1814 * Marking:: Marking Translatable Strings
1815 * c-format Flag:: Telling something about the following string
1816 * Special cases:: Special Cases of Translatable Strings
1817 * Bug Report Address:: Letting Users Report Translation Bugs
1818 * Names:: Marking Proper Names for Translation
1819 * Libraries:: Preparing Library Sources
1822 @node Importing, Triggering, Sources, Sources
1823 @section Importing the @code{gettext} declaration
1825 Presuming that your set of programs, or package, has been adjusted
1826 so all needed GNU @code{gettext} files are available, and your
1827 @file{Makefile} files are adjusted (@pxref{Maintainers}), each C module
1828 having translated C strings should contain the line:
1830 @cindex include file @file{libintl.h}
1832 #include <libintl.h>
1835 Similarly, each C module containing @code{printf()}/@code{fprintf()}/...
1836 calls with a format string that could be a translated C string (even if
1837 the C string comes from a different C module) should contain the line:
1840 #include <libintl.h>
1843 @node Triggering, Preparing Strings, Importing, Sources
1844 @section Triggering @code{gettext} Operations
1846 @cindex initialization
1847 The initialization of locale data should be done with more or less
1848 the same code in every program, as demonstrated below:
1853 main (int argc, char *argv[])
1856 setlocale (LC_ALL, "");
1857 bindtextdomain (PACKAGE, LOCALEDIR);
1858 textdomain (PACKAGE);
1864 @var{PACKAGE} and @var{LOCALEDIR} should be provided either by
1865 @file{config.h} or by the Makefile. For now consult the @code{gettext}
1866 or @code{hello} sources for more information.
1868 @cindex locale category, LC_ALL
1869 @cindex locale category, LC_CTYPE
1870 The use of @code{LC_ALL} might not be appropriate for you.
1871 @code{LC_ALL} includes all locale categories and especially
1872 @code{LC_CTYPE}. This latter category is responsible for determining
1873 character classes with the @code{isalnum} etc. functions from
1874 @file{ctype.h} which could especially for programs, which process some
1875 kind of input language, be wrong. For example this would mean that a
1876 source code using the @,{c} (c-cedilla character) is runnable in
1877 France but not in the U.S.
1879 Some systems also have problems with parsing numbers using the
1880 @code{scanf} functions if an other but the @code{LC_ALL} locale category is
1881 used. The standards say that additional formats but the one known in the
1882 @code{"C"} locale might be recognized. But some systems seem to reject
1883 numbers in the @code{"C"} locale format. In some situation, it might
1884 also be a problem with the notation itself which makes it impossible to
1885 recognize whether the number is in the @code{"C"} locale or the local
1886 format. This can happen if thousands separator characters are used.
1887 Some locales define this character according to the national
1888 conventions to @code{'.'} which is the same character used in the
1889 @code{"C"} locale to denote the decimal point.
1891 So it is sometimes necessary to replace the @code{LC_ALL} line in the
1892 code above by a sequence of @code{setlocale} lines
1898 setlocale (LC_CTYPE, "");
1899 setlocale (LC_MESSAGES, "");
1905 @cindex locale category, LC_CTYPE
1906 @cindex locale category, LC_COLLATE
1907 @cindex locale category, LC_MONETARY
1908 @cindex locale category, LC_NUMERIC
1909 @cindex locale category, LC_TIME
1910 @cindex locale category, LC_MESSAGES
1911 @cindex locale category, LC_RESPONSES
1913 On all POSIX conformant systems the locale categories @code{LC_CTYPE},
1914 @code{LC_MESSAGES}, @code{LC_COLLATE}, @code{LC_MONETARY},
1915 @code{LC_NUMERIC}, and @code{LC_TIME} are available. On some systems
1916 which are only ISO C compliant, @code{LC_MESSAGES} is missing, but
1917 a substitute for it is defined in GNU gettext's @code{<libintl.h>} and
1918 in GNU gnulib's @code{<locale.h>}.
1920 Note that changing the @code{LC_CTYPE} also affects the functions
1921 declared in the @code{<ctype.h>} standard header and some functions
1922 declared in the @code{<string.h>} and @code{<stdlib.h>} standard headers.
1924 desirable in your application (for example in a compiler's parser),
1925 you can use a set of substitute functions which hardwire the C locale,
1926 such as found in the modules @samp{c-ctype}, @samp{c-strcase},
1927 @samp{c-strcasestr}, @samp{c-strtod}, @samp{c-strtold} in the GNU gnulib
1928 source distribution.
1930 It is also possible to switch the locale forth and back between the
1931 environment dependent locale and the C locale, but this approach is
1932 normally avoided because a @code{setlocale} call is expensive,
1933 because it is tedious to determine the places where a locale switch
1934 is needed in a large program's source, and because switching a locale
1935 is not multithread-safe.
1937 @node Preparing Strings, Mark Keywords, Triggering, Sources
1938 @section Preparing Translatable Strings
1940 @cindex marking strings, preparations
1941 Before strings can be marked for translations, they sometimes need to
1942 be adjusted. Usually preparing a string for translation is done right
1943 before marking it, during the marking phase which is described in the
1944 next sections. What you have to keep in mind while doing that is the
1949 Decent English style.
1955 Split at paragraphs.
1958 Use format strings instead of string concatenation.
1961 Avoid unusual markup and unusual control characters.
1965 Let's look at some examples of these guidelines.
1968 Translatable strings should be in good English style. If slang language
1969 with abbreviations and shortcuts is used, often translators will not
1970 understand the message and will produce very inappropriate translations.
1973 "%s: is parameter\n"
1977 This is nearly untranslatable: Is the displayed item @emph{a} parameter or
1978 @emph{the} parameter?
1985 The ambiguity in this message makes it unintelligible: Is the program
1986 attempting to set something on fire? Does it mean "The given object does
1987 not match the template"? Does it mean "The template does not fit for any
1991 In both cases, adding more words to the message will help both the
1992 translator and the English speaking user.
1995 Translatable strings should be entire sentences. It is often not possible
1996 to translate single verbs or adjectives in a substitutable way.
1999 printf ("File %s is %s protected", filename, rw ? "write" : "read");
2003 Most translators will not look at the source and will thus only see the
2004 string @code{"File %s is %s protected"}, which is unintelligible. Change
2008 printf (rw ? "File %s is write protected" : "File %s is read protected",
2013 This way the translator will not only understand the message, she will
2014 also be able to find the appropriate grammatical construction. A French
2015 translator for example translates "write protected" like "protected
2018 Entire sentences are also important because in many languages, the
2019 declination of some word in a sentence depends on the gender or the
2020 number (singular/plural) of another part of the sentence. There are
2021 usually more interdependencies between words than in English. The
2022 consequence is that asking a translator to translate two half-sentences
2023 and then combining these two half-sentences through dumb string concatenation
2024 will not work, for many languages, even though it would work for English.
2025 That's why translators need to handle entire sentences.
2027 Often sentences don't fit into a single line. If a sentence is output
2028 using two subsequent @code{printf} statements, like this
2031 printf ("Locale charset \"%s\" is different from\n", lcharset);
2032 printf ("input file charset \"%s\".\n", fcharset);
2036 the translator would have to translate two half sentences, but nothing
2037 in the POT file would tell her that the two half sentences belong together.
2038 It is necessary to merge the two @code{printf} statements so that the
2039 translator can handle the entire sentence at once and decide at which
2040 place to insert a line break in the translation (if at all):
2043 printf ("Locale charset \"%s\" is different from\n\
2044 input file charset \"%s\".\n", lcharset, fcharset);
2047 You may now ask: how about two or more adjacent sentences? Like in this case:
2050 puts ("Apollo 13 scenario: Stack overflow handling failed.");
2051 puts ("On the next stack overflow we will crash!!!");
2055 Should these two statements merged into a single one? I would recommend to
2056 merge them if the two sentences are related to each other, because then it
2057 makes it easier for the translator to understand and translate both. On
2058 the other hand, if one of the two messages is a stereotypic one, occurring
2059 in other places as well, you will do a favour to the translator by not
2060 merging the two. (Identical messages occurring in several places are
2061 combined by xgettext, so the translator has to handle them once only.)
2064 Translatable strings should be limited to one paragraph; don't let a
2065 single message be longer than ten lines. The reason is that when the
2066 translatable string changes, the translator is faced with the task of
2067 updating the entire translated string. Maybe only a single word will
2068 have changed in the English string, but the translator doesn't see that
2069 (with the current translation tools), therefore she has to proofread
2073 Many GNU programs have a @samp{--help} output that extends over several
2074 screen pages. It is a courtesy towards the translators to split such a
2075 message into several ones of five to ten lines each. While doing that,
2076 you can also attempt to split the documented options into groups,
2077 such as the input options, the output options, and the informative
2078 output options. This will help every user to find the option he is
2081 @cindex string concatenation
2082 @cindex concatenation of strings
2083 Hardcoded string concatenation is sometimes used to construct English
2087 strcpy (s, "Replace ");
2088 strcat (s, object1);
2089 strcat (s, " with ");
2090 strcat (s, object2);
2095 In order to present to the translator only entire sentences, and also
2096 because in some languages the translator might want to swap the order
2097 of @code{object1} and @code{object2}, it is necessary to change this
2098 to use a format string:
2101 sprintf (s, "Replace %s with %s?", object1, object2);
2104 @cindex @code{inttypes.h}
2105 A similar case is compile time concatenation of strings. The ISO C 99
2106 include file @code{<inttypes.h>} contains a macro @code{PRId64} that
2107 can be used as a formatting directive for outputting an @samp{int64_t}
2108 integer through @code{printf}. It expands to a constant string, usually
2109 "d" or "ld" or "lld" or something like this, depending on the platform.
2110 Assume you have code like
2113 printf ("The amount is %0" PRId64 "\n", number);
2117 The @code{gettext} tools and library have special support for these
2118 @code{<inttypes.h>} macros. You can therefore simply write
2121 printf (gettext ("The amount is %0" PRId64 "\n"), number);
2125 The PO file will contain the string "The amount is %0<PRId64>\n".
2126 The translators will provide a translation containing "%0<PRId64>"
2127 as well, and at runtime the @code{gettext} function's result will
2128 contain the appropriate constant string, "d" or "ld" or "lld".
2130 This works only for the predefined @code{<inttypes.h>} macros. If
2131 you have defined your own similar macros, let's say @samp{MYPRId64},
2132 that are not known to @code{xgettext}, the solution for this problem
2133 is to change the code like this:
2137 sprintf (buf1, "%0" MYPRId64, number);
2138 printf (gettext ("The amount is %s\n"), buf1);
2141 This means, you put the platform dependent code in one statement, and the
2142 internationalization code in a different statement. Note that a buffer length
2143 of 100 is safe, because all available hardware integer types are limited to
2144 128 bits, and to print a 128 bit integer one needs at most 54 characters,
2145 regardless whether in decimal, octal or hexadecimal.
2147 @cindex Java, string concatenation
2148 @cindex C#, string concatenation
2149 All this applies to other programming languages as well. For example, in
2150 Java and C#, string concatenation is very frequently used, because it is a
2151 compiler built-in operator. Like in C, in Java, you would change
2154 System.out.println("Replace "+object1+" with "+object2+"?");
2158 into a statement involving a format string:
2162 MessageFormat.format("Replace @{0@} with @{1@}?",
2163 new Object[] @{ object1, object2 @}));
2167 Similarly, in C#, you would change
2170 Console.WriteLine("Replace "+object1+" with "+object2+"?");
2174 into a statement involving a format string:
2178 String.Format("Replace @{0@} with @{1@}?", object1, object2));
2182 @cindex control characters
2183 Unusual markup or control characters should not be used in translatable
2184 strings. Translators will likely not understand the particular meaning
2185 of the markup or control characters.
2187 For example, if you have a convention that @samp{|} delimits the
2188 left-hand and right-hand part of some GUI elements, translators will
2189 often not understand it without specific comments. It might be
2190 better to have the translator translate the left-hand and right-hand
2193 Another example is the @samp{argp} convention to use a single @samp{\v}
2194 (vertical tab) control character to delimit two sections inside a
2195 string. This is flawed. Some translators may convert it to a simple
2196 newline, some to blank lines. With some PO file editors it may not be
2197 easy to even enter a vertical tab control character. So, you cannot
2198 be sure that the translation will contain a @samp{\v} character, at the
2199 corresponding position. The solution is, again, to let the translator
2200 translate two separate strings and combine at run-time the two translated
2201 strings with the @samp{\v} required by the convention.
2203 HTML markup, however, is common enough that it's probably ok to use in
2204 translatable strings. But please bear in mind that the GNU gettext tools
2205 don't verify that the translations are well-formed HTML.
2207 @node Mark Keywords, Marking, Preparing Strings, Sources
2208 @section How Marks Appear in Sources
2209 @cindex marking strings that require translation
2211 All strings requiring translation should be marked in the C sources. Marking
2212 is done in such a way that each translatable string appears to be
2213 the sole argument of some function or preprocessor macro. There are
2214 only a few such possible functions or macros meant for translation,
2215 and their names are said to be marking keywords. The marking is
2216 attached to strings themselves, rather than to what we do with them.
2217 This approach has more uses. A blatant example is an error message
2218 produced by formatting. The format string needs translation, as
2219 well as some strings inserted through some @samp{%s} specification
2220 in the format, while the result from @code{sprintf} may have so many
2221 different instances that it is impractical to list them all in some
2222 @samp{error_string_out()} routine, say.
2224 This marking operation has two goals. The first goal of marking
2225 is for triggering the retrieval of the translation, at run time.
2226 The keyword is possibly resolved into a routine able to dynamically
2227 return the proper translation, as far as possible or wanted, for the
2228 argument string. Most localizable strings are found in executable
2229 positions, that is, attached to variables or given as parameters to
2230 functions. But this is not universal usage, and some translatable
2231 strings appear in structured initializations. @xref{Special cases}.
2233 The second goal of the marking operation is to help @code{xgettext}
2234 at properly extracting all translatable strings when it scans a set
2235 of program sources and produces PO file templates.
2237 The canonical keyword for marking translatable strings is
2238 @samp{gettext}, it gave its name to the whole GNU @code{gettext}
2239 package. For packages making only light use of the @samp{gettext}
2240 keyword, macro or function, it is easily used @emph{as is}. However,
2241 for packages using the @code{gettext} interface more heavily, it
2242 is usually more convenient to give the main keyword a shorter, less
2243 obtrusive name. Indeed, the keyword might appear on a lot of strings
2244 all over the package, and programmers usually do not want nor need
2245 their program sources to remind them forcefully, all the time, that they
2246 are internationalized. Further, a long keyword has the disadvantage
2247 of using more horizontal space, forcing more indentation work on
2248 sources for those trying to keep them within 79 or 80 columns.
2250 @cindex @code{_}, a macro to mark strings for translation
2251 Many packages use @samp{_} (a simple underline) as a keyword,
2252 and write @samp{_("Translatable string")} instead of @samp{gettext
2253 ("Translatable string")}. Further, the coding rule, from GNU standards,
2254 wanting that there is a space between the keyword and the opening
2255 parenthesis is relaxed, in practice, for this particular usage.
2256 So, the textual overhead per translatable string is reduced to
2257 only three characters: the underline and the two parentheses.
2258 However, even if GNU @code{gettext} uses this convention internally,
2259 it does not offer it officially. The real, genuine keyword is truly
2260 @samp{gettext} indeed. It is fairly easy for those wanting to use
2261 @samp{_} instead of @samp{gettext} to declare:
2264 #include <libintl.h>
2265 #define _(String) gettext (String)
2269 instead of merely using @samp{#include <libintl.h>}.
2271 The marking keywords @samp{gettext} and @samp{_} take the translatable
2272 string as sole argument. It is also possible to define marking functions
2273 that take it at another argument position. It is even possible to make
2274 the marked argument position depend on the total number of arguments of
2275 the function call; this is useful in C++. All this is achieved using
2276 @code{xgettext}'s @samp{--keyword} option. How to pass such an option
2277 to @code{xgettext}, assuming that @code{gettextize} is used, is described
2278 in @ref{po/Makevars} and @ref{AM_XGETTEXT_OPTION}.
2280 Note also that long strings can be split across lines, into multiple
2281 adjacent string tokens. Automatic string concatenation is performed
2282 at compile time according to ISO C and ISO C++; @code{xgettext} also
2283 supports this syntax.
2285 Later on, the maintenance is relatively easy. If, as a programmer,
2286 you add or modify a string, you will have to ask yourself if the
2287 new or altered string requires translation, and include it within
2288 @samp{_()} if you think it should be translated. For example, @samp{"%s"}
2289 is an example of string @emph{not} requiring translation. But
2290 @samp{"%s: %d"} @emph{does} require translation, because in French, unlike
2291 in English, it's customary to put a space before a colon.
2293 @node Marking, c-format Flag, Mark Keywords, Sources
2294 @section Marking Translatable Strings
2295 @emindex marking strings for translation
2297 In PO mode, one set of features is meant more for the programmer than
2298 for the translator, and allows him to interactively mark which strings,
2299 in a set of program sources, are translatable, and which are not.
2300 Even if it is a fairly easy job for a programmer to find and mark
2301 such strings by other means, using any editor of his choice, PO mode
2302 makes this work more comfortable. Further, this gives translators
2303 who feel a little like programmers, or programmers who feel a little
2304 like translators, a tool letting them work at marking translatable
2305 strings in the program sources, while simultaneously producing a set of
2306 translation in some language, for the package being internationalized.
2308 @emindex @code{etags}, using for marking strings
2309 The set of program sources, targeted by the PO mode commands describe
2310 here, should have an Emacs tags table constructed for your project,
2311 prior to using these PO file commands. This is easy to do. In any
2312 shell window, change the directory to the root of your project, then
2313 execute a command resembling:
2316 etags src/*.[hc] lib/*.[hc]
2320 presuming here you want to process all @file{.h} and @file{.c} files
2321 from the @file{src/} and @file{lib/} directories. This command will
2322 explore all said files and create a @file{TAGS} file in your root
2323 directory, somewhat summarizing the contents using a special file
2324 format Emacs can understand.
2326 @emindex @file{TAGS}, and marking translatable strings
2327 For packages following the GNU coding standards, there is
2328 a make goal @code{tags} or @code{TAGS} which constructs the tag files in
2329 all directories and for all files containing source code.
2331 Once your @file{TAGS} file is ready, the following commands assist
2332 the programmer at marking translatable strings in his set of sources.
2333 But these commands are necessarily driven from within a PO file
2334 window, and it is likely that you do not even have such a PO file yet.
2335 This is not a problem at all, as you may safely open a new, empty PO
2336 file, mainly for using these commands. This empty PO file will slowly
2337 fill in while you mark strings as translatable in your program sources.
2341 @efindex ,@r{, PO Mode command}
2342 Search through program sources for a string which looks like a
2343 candidate for translation (@code{po-tags-search}).
2346 @efindex M-,@r{, PO Mode command}
2347 Mark the last string found with @samp{_()} (@code{po-mark-translatable}).
2350 @efindex M-.@r{, PO Mode command}
2351 Mark the last string found with a keyword taken from a set of possible
2352 keywords. This command with a prefix allows some management of these
2353 keywords (@code{po-select-mark-and-mark}).
2357 @efindex po-tags-search@r{, PO Mode command}
2358 The @kbd{,} (@code{po-tags-search}) command searches for the next
2359 occurrence of a string which looks like a possible candidate for
2360 translation, and displays the program source in another Emacs window,
2361 positioned in such a way that the string is near the top of this other
2362 window. If the string is too big to fit whole in this window, it is
2363 positioned so only its end is shown. In any case, the cursor
2364 is left in the PO file window. If the shown string would be better
2365 presented differently in different native languages, you may mark it
2366 using @kbd{M-,} or @kbd{M-.}. Otherwise, you might rather ignore it
2367 and skip to the next string by merely repeating the @kbd{,} command.
2369 A string is a good candidate for translation if it contains a sequence
2370 of three or more letters. A string containing at most two letters in
2371 a row will be considered as a candidate if it has more letters than
2372 non-letters. The command disregards strings containing no letters,
2373 or isolated letters only. It also disregards strings within comments,
2374 or strings already marked with some keyword PO mode knows (see below).
2376 If you have never told Emacs about some @file{TAGS} file to use, the
2377 command will request that you specify one from the minibuffer, the
2378 first time you use the command. You may later change your @file{TAGS}
2379 file by using the regular Emacs command @w{@kbd{M-x visit-tags-table}},
2380 which will ask you to name the precise @file{TAGS} file you want
2381 to use. @xref{Tags, , Tag Tables, emacs, The Emacs Editor}.
2383 Each time you use the @kbd{,} command, the search resumes from where it was
2384 left by the previous search, and goes through all program sources,
2385 obeying the @file{TAGS} file, until all sources have been processed.
2386 However, by giving a prefix argument to the command @w{(@kbd{C-u
2387 ,})}, you may request that the search be restarted all over again
2388 from the first program source; but in this case, strings that you
2389 recently marked as translatable will be automatically skipped.
2391 Using this @kbd{,} command does not prevent using of other regular
2392 Emacs tags commands. For example, regular @code{tags-search} or
2393 @code{tags-query-replace} commands may be used without disrupting the
2394 independent @kbd{,} search sequence. However, as implemented, the
2395 @emph{initial} @kbd{,} command (or the @kbd{,} command is used with a
2396 prefix) might also reinitialize the regular Emacs tags searching to the
2397 first tags file, this reinitialization might be considered spurious.
2399 @efindex po-mark-translatable@r{, PO Mode command}
2400 @efindex po-select-mark-and-mark@r{, PO Mode command}
2401 The @kbd{M-,} (@code{po-mark-translatable}) command will mark the
2402 recently found string with the @samp{_} keyword. The @kbd{M-.}
2403 (@code{po-select-mark-and-mark}) command will request that you type
2404 one keyword from the minibuffer and use that keyword for marking
2405 the string. Both commands will automatically create a new PO file
2406 untranslated entry for the string being marked, and make it the
2407 current entry (making it easy for you to immediately proceed to its
2408 translation, if you feel like doing it right away). It is possible
2409 that the modifications made to the program source by @kbd{M-,} or
2410 @kbd{M-.} render some source line longer than 80 columns, forcing you
2411 to break and re-indent this line differently. You may use the @kbd{O}
2412 command from PO mode, or any other window changing command from
2413 Emacs, to break out into the program source window, and do any
2414 needed adjustments. You will have to use some regular Emacs command
2415 to return the cursor to the PO file window, if you want command
2416 @kbd{,} for the next string, say.
2418 The @kbd{M-.} command has a few built-in speedups, so you do not
2419 have to explicitly type all keywords all the time. The first such
2420 speedup is that you are presented with a @emph{preferred} keyword,
2421 which you may accept by merely typing @kbd{@key{RET}} at the prompt.
2422 The second speedup is that you may type any non-ambiguous prefix of the
2423 keyword you really mean, and the command will complete it automatically
2424 for you. This also means that PO mode has to @emph{know} all
2425 your possible keywords, and that it will not accept mistyped keywords.
2427 If you reply @kbd{?} to the keyword request, the command gives a
2428 list of all known keywords, from which you may choose. When the
2429 command is prefixed by an argument @w{(@kbd{C-u M-.})}, it inhibits
2430 updating any program source or PO file buffer, and does some simple
2431 keyword management instead. In this case, the command asks for a
2432 keyword, written in full, which becomes a new allowed keyword for
2433 later @kbd{M-.} commands. Moreover, this new keyword automatically
2434 becomes the @emph{preferred} keyword for later commands. By typing
2435 an already known keyword in response to @w{@kbd{C-u M-.}}, one merely
2436 changes the @emph{preferred} keyword and does nothing more.
2438 All keywords known for @kbd{M-.} are recognized by the @kbd{,} command
2439 when scanning for strings, and strings already marked by any of those
2440 known keywords are automatically skipped. If many PO files are opened
2441 simultaneously, each one has its own independent set of known keywords.
2442 There is no provision in PO mode, currently, for deleting a known
2443 keyword, you have to quit the file (maybe using @kbd{q}) and reopen
2444 it afresh. When a PO file is newly brought up in an Emacs window, only
2445 @samp{gettext} and @samp{_} are known as keywords, and @samp{gettext}
2446 is preferred for the @kbd{M-.} command. In fact, this is not useful to
2447 prefer @samp{_}, as this one is already built in the @kbd{M-,} command.
2449 @node c-format Flag, Special cases, Marking, Sources
2450 @section Special Comments preceding Keywords
2452 @c FIXME document c-format and no-c-format.
2454 @cindex format strings
2455 In C programs strings are often used within calls of functions from the
2456 @code{printf} family. The special thing about these format strings is
2457 that they can contain format specifiers introduced with @kbd{%}. Assume
2461 printf (gettext ("String `%s' has %d characters\n"), s, strlen (s));
2465 A possible German translation for the above string might be:
2468 "%d Zeichen lang ist die Zeichenkette `%s'"
2471 A C programmer, even if he cannot speak German, will recognize that
2472 there is something wrong here. The order of the two format specifiers
2473 is changed but of course the arguments in the @code{printf} don't have.
2474 This will most probably lead to problems because now the length of the
2475 string is regarded as the address.
2477 To prevent errors at runtime caused by translations, the @code{msgfmt}
2478 tool can check statically whether the arguments in the original and the
2479 translation string match in type and number. If this is not the case
2480 and the @samp{-c} option has been passed to @code{msgfmt}, @code{msgfmt}
2481 will give an error and refuse to produce a MO file. Thus consistent
2482 use of @samp{msgfmt -c} will catch the error, so that it cannot cause
2483 problems at runtime.
2486 If the word order in the above German translation would be correct one
2490 "%2$d Zeichen lang ist die Zeichenkette `%1$s'"
2494 The routines in @code{msgfmt} know about this special notation.
2496 Because not all strings in a program will be format strings, it is not
2497 useful for @code{msgfmt} to test all the strings in the @file{.po} file.
2498 This might cause problems because the string might contain what looks
2499 like a format specifier, but the string is not used in @code{printf}.
2501 Therefore @code{xgettext} adds a special tag to those messages it
2502 thinks might be a format string. There is no absolute rule for this,
2503 only a heuristic. In the @file{.po} file the entry is marked using the
2504 @code{c-format} flag in the @code{#,} comment line (@pxref{PO Files}).
2506 @kwindex c-format@r{, and @code{xgettext}}
2507 @kwindex no-c-format@r{, and @code{xgettext}}
2508 The careful reader now might say that this again can cause problems.
2509 The heuristic might guess it wrong. This is true and therefore
2510 @code{xgettext} knows about a special kind of comment which lets
2511 the programmer take over the decision. If in the same line as or
2512 the immediately preceding line to the @code{gettext} keyword
2513 the @code{xgettext} program finds a comment containing the words
2514 @code{xgettext:c-format}, it will mark the string in any case with
2515 the @code{c-format} flag. This kind of comment should be used when
2516 @code{xgettext} does not recognize the string as a format string but
2517 it really is one and it should be tested. Please note that when the
2518 comment is in the same line as the @code{gettext} keyword, it must be
2519 before the string to be translated.
2521 This situation happens quite often. The @code{printf} function is often
2522 called with strings which do not contain a format specifier. Of course
2523 one would normally use @code{fputs} but it does happen. In this case
2524 @code{xgettext} does not recognize this as a format string but what
2525 happens if the translation introduces a valid format specifier? The
2526 @code{printf} function will try to access one of the parameters but none
2527 exists because the original code does not pass any parameters.
2529 @code{xgettext} of course could make a wrong decision the other way
2530 round, i.e.@: a string marked as a format string actually is not a format
2531 string. In this case the @code{msgfmt} might give too many warnings and
2532 would prevent translating the @file{.po} file. The method to prevent
2533 this wrong decision is similar to the one used above, only the comment
2534 to use must contain the string @code{xgettext:no-c-format}.
2536 If a string is marked with @code{c-format} and this is not correct the
2537 user can find out who is responsible for the decision. See
2538 @ref{xgettext Invocation} to see how the @code{--debug} option can be
2539 used for solving this problem.
2541 @node Special cases, Bug Report Address, c-format Flag, Sources
2542 @section Special Cases of Translatable Strings
2544 @cindex marking string initializers
2545 The attentive reader might now point out that it is not always possible
2546 to mark translatable string with @code{gettext} or something like this.
2547 Consider the following case:
2552 static const char *messages[] = @{
2553 "some very meaningful message",
2559 = index > 1 ? "a default message" : messages[index];
2567 While it is no problem to mark the string @code{"a default message"} it
2568 is not possible to mark the string initializers for @code{messages}.
2569 What is to be done? We have to fulfill two tasks. First we have to mark the
2570 strings so that the @code{xgettext} program (@pxref{xgettext Invocation})
2571 can find them, and second we have to translate the string at runtime
2572 before printing them.
2574 The first task can be fulfilled by creating a new keyword, which names a
2575 no-op. For the second we have to mark all access points to a string
2576 from the array. So one solution can look like this:
2580 #define gettext_noop(String) String
2583 static const char *messages[] = @{
2584 gettext_noop ("some very meaningful message"),
2585 gettext_noop ("and another one")
2590 = index > 1 ? gettext ("a default message") : gettext (messages[index]);
2598 Please convince yourself that the string which is written by
2599 @code{fputs} is translated in any case. How to get @code{xgettext} know
2600 the additional keyword @code{gettext_noop} is explained in @ref{xgettext
2603 The above is of course not the only solution. You could also come along
2604 with the following one:
2608 #define gettext_noop(String) String
2611 static const char *messages[] = @{
2612 gettext_noop ("some very meaningful message"),
2613 gettext_noop ("and another one")
2618 = index > 1 ? gettext_noop ("a default message") : messages[index];
2620 fputs (gettext (string));
2626 But this has a drawback. The programmer has to take care that
2627 he uses @code{gettext_noop} for the string @code{"a default message"}.
2628 A use of @code{gettext} could have in rare cases unpredictable results.
2630 One advantage is that you need not make control flow analysis to make
2631 sure the output is really translated in any case. But this analysis is
2632 generally not very difficult. If it should be in any situation you can
2633 use this second method in this situation.
2635 @node Bug Report Address, Names, Special cases, Sources
2636 @section Letting Users Report Translation Bugs
2638 Code sometimes has bugs, but translations sometimes have bugs too. The
2639 users need to be able to report them. Reporting translation bugs to the
2640 programmer or maintainer of a package is not very useful, since the
2641 maintainer must never change a translation, except on behalf of the
2642 translator. Hence the translation bugs must be reported to the
2645 Here is a way to organize this so that the maintainer does not need to
2646 forward translation bug reports, nor even keep a list of the addresses of
2647 the translators or their translation teams.
2649 Every program has a place where is shows the bug report address. For
2650 GNU programs, it is the code which handles the ``--help'' option,
2651 typically in a function called ``usage''. In this place, instruct the
2652 translator to add her own bug reporting address. For example, if that
2653 code has a statement
2657 printf (_("Report bugs to <%s>.\n"), PACKAGE_BUGREPORT);
2661 you can add some translator instructions like this:
2665 /* TRANSLATORS: The placeholder indicates the bug-reporting address
2666 for this package. Please add _another line_ saying
2667 "Report translation bugs to <...>\n" with the address for translation
2668 bugs (typically your translation team's web or email address). */
2669 printf (_("Report bugs to <%s>.\n"), PACKAGE_BUGREPORT);
2673 These will be extracted by @samp{xgettext}, leading to a .pot file that
2678 #. TRANSLATORS: The placeholder indicates the bug-reporting address
2679 #. for this package. Please add _another line_ saying
2680 #. "Report translation bugs to <...>\n" with the address for translation
2681 #. bugs (typically your translation team's web or email address).
2684 msgid "Report bugs to <%s>.\n"
2689 @node Names, Libraries, Bug Report Address, Sources
2690 @section Marking Proper Names for Translation
2692 Should names of persons, cities, locations etc. be marked for translation
2693 or not? People who only know languages that can be written with Latin
2694 letters (English, Spanish, French, German, etc.) are tempted to say ``no'',
2695 because names usually do not change when transported between these languages.
2696 However, in general when translating from one script to another, names
2697 are translated too, usually phonetically or by transliteration. For
2698 example, Russian or Greek names are converted to the Latin alphabet when
2699 being translated to English, and English or French names are converted
2700 to the Katakana script when being translated to Japanese. This is
2701 necessary because the speakers of the target language in general cannot
2702 read the script the name is originally written in.
2704 As a programmer, you should therefore make sure that names are marked
2705 for translation, with a special comment telling the translators that it
2706 is a proper name and how to pronounce it. In its simple form, it looks
2711 printf (_("Written by %s.\n"),
2712 /* TRANSLATORS: This is a proper name. See the gettext
2713 manual, section Names. Note this is actually a non-ASCII
2714 name: The first name is (with Unicode escapes)
2715 "Fran\u00e7ois" or (with HTML entities) "François".
2716 Pronunciation is like "fraa-swa pee-nar". */
2717 _("Francois Pinard"));
2722 The GNU gnulib library offers a module @samp{propername}
2723 (@url{http://www.gnu.org/software/gnulib/MODULES.html#module=propername})
2724 which takes care to automatically append the original name, in parentheses,
2725 to the translated name. For names that cannot be written in ASCII, it
2726 also frees the translator from the task of entering the appropriate non-ASCII
2727 characters if no script change is needed. In this more comfortable form,
2732 printf (_("Written by %s and %s.\n"),
2733 proper_name ("Ulrich Drepper"),
2734 /* TRANSLATORS: This is a proper name. See the gettext
2735 manual, section Names. Note this is actually a non-ASCII
2736 name: The first name is (with Unicode escapes)
2737 "Fran\u00e7ois" or (with HTML entities) "François".
2738 Pronunciation is like "fraa-swa pee-nar". */
2739 proper_name_utf8 ("Francois Pinard", "Fran\303\247ois Pinard"));
2744 You can also write the original name directly in Unicode (rather than with
2745 Unicode escapes or HTML entities) and denote the pronunciation using the
2746 International Phonetic Alphabet (see
2747 @url{http://www.wikipedia.org/wiki/International_Phonetic_Alphabet}).
2749 As a translator, you should use some care when translating names, because
2750 it is frustrating if people see their names mutilated or distorted.
2752 If your language uses the Latin script, all you need to do is to reproduce
2753 the name as perfectly as you can within the usual character set of your
2754 language. In this particular case, this means to provide a translation
2755 containing the c-cedilla character. If your language uses a different
2756 script and the people speaking it don't usually read Latin words, it means
2757 transliteration. If the programmer used the simple case, you should still
2758 give, in parentheses, the original writing of the name -- for the sake of
2759 the people that do read the Latin script. If the programmer used the
2760 @samp{propername} module mentioned above, you don't need to give the original
2761 writing of the name in parentheses, because the program will already do so.
2762 Here is an example, using Greek as the target script:
2766 #. This is a proper name. See the gettext
2767 #. manual, section Names. Note this is actually a non-ASCII
2768 #. name: The first name is (with Unicode escapes)
2769 #. "Fran\u00e7ois" or (with HTML entities) "François".
2770 #. Pronunciation is like "fraa-swa pee-nar".
2771 msgid "Francois Pinard"
2772 msgstr "\phi\rho\alpha\sigma\omicron\alpha \pi\iota\nu\alpha\rho"
2773 " (Francois Pinard)"
2777 Because translation of names is such a sensitive domain, it is a good
2778 idea to test your translation before submitting it.
2780 @node Libraries, , Names, Sources
2781 @section Preparing Library Sources
2783 When you are preparing a library, not a program, for the use of
2784 @code{gettext}, only a few details are different. Here we assume that
2785 the library has a translation domain and a POT file of its own. (If
2786 it uses the translation domain and POT file of the main program, then
2787 the previous sections apply without changes.)
2791 The library code doesn't call @code{setlocale (LC_ALL, "")}. It's the
2792 responsibility of the main program to set the locale. The library's
2793 documentation should mention this fact, so that developers of programs
2794 using the library are aware of it.
2797 The library code doesn't call @code{textdomain (PACKAGE)}, because it
2798 would interfere with the text domain set by the main program.
2801 The initialization code for a program was
2804 setlocale (LC_ALL, "");
2805 bindtextdomain (PACKAGE, LOCALEDIR);
2806 textdomain (PACKAGE);
2810 For a library it is reduced to
2813 bindtextdomain (PACKAGE, LOCALEDIR);
2817 If your library's API doesn't already have an initialization function,
2818 you need to create one, containing at least the @code{bindtextdomain}
2819 invocation. However, you usually don't need to export and document this
2820 initialization function: It is sufficient that all entry points of the
2821 library call the initialization function if it hasn't been called before.
2822 The typical idiom used to achieve this is a static boolean variable that
2823 indicates whether the initialization function has been called. Like this:
2827 static bool libfoo_initialized;
2830 libfoo_initialize (void)
2832 bindtextdomain (PACKAGE, LOCALEDIR);
2833 libfoo_initialized = true;
2836 /* This function is part of the exported API. */
2840 /* Must ensure the initialization is performed. */
2841 if (!libfoo_initialized)
2842 libfoo_initialize ();
2846 /* This function is part of the exported API. The argument must be
2847 non-NULL and have been created through create_foo(). */
2849 foo_refcount (struct foo *argument)
2851 /* No need to invoke the initialization function here, because
2852 create_foo() must already have been called before. */
2859 The usual declaration of the @samp{_} macro in each source file was
2862 #include <libintl.h>
2863 #define _(String) gettext (String)
2867 for a program. For a library, which has its own translation domain,
2871 #include <libintl.h>
2872 #define _(String) dgettext (PACKAGE, String)
2875 In other words, @code{dgettext} is used instead of @code{gettext}.
2876 Similarly, the @code{dngettext} function should be used in place of the
2877 @code{ngettext} function.
2880 @node Template, Creating, Sources, Top
2881 @chapter Making the PO Template File
2882 @cindex PO template file
2884 After preparing the sources, the programmer creates a PO template file.
2885 This section explains how to use @code{xgettext} for this purpose.
2887 @code{xgettext} creates a file named @file{@var{domainname}.po}. You
2888 should then rename it to @file{@var{domainname}.pot}. (Why doesn't
2889 @code{xgettext} create it under the name @file{@var{domainname}.pot}
2890 right away? The answer is: for historical reasons. When @code{xgettext}
2891 was specified, the distinction between a PO file and PO file template
2892 was fuzzy, and the suffix @samp{.pot} wasn't in use at that time.)
2897 * xgettext Invocation:: Invoking the @code{xgettext} Program
2900 @node xgettext Invocation, , Template, Template
2901 @section Invoking the @code{xgettext} Program
2903 @include xgettext.texi
2905 @node Creating, Updating, Template, Top
2906 @chapter Creating a New PO File
2907 @cindex creating a new PO file
2909 When starting a new translation, the translator creates a file called
2910 @file{@var{LANG}.po}, as a copy of the @file{@var{package}.pot} template
2911 file with modifications in the initial comments (at the beginning of the file)
2912 and in the header entry (the first entry, near the beginning of the file).
2914 The easiest way to do so is by use of the @samp{msginit} program.
2918 $ cd @var{PACKAGE}-@var{VERSION}
2923 The alternative way is to do the copy and modifications by hand.
2924 To do so, the translator copies @file{@var{package}.pot} to
2925 @file{@var{LANG}.po}. Then she modifies the initial comments and
2926 the header entry of this file.
2929 * msginit Invocation:: Invoking the @code{msginit} Program
2930 * Header Entry:: Filling in the Header Entry
2933 @node msginit Invocation, Header Entry, Creating, Creating
2934 @section Invoking the @code{msginit} Program
2936 @include msginit.texi
2938 @node Header Entry, , msginit Invocation, Creating
2939 @section Filling in the Header Entry
2940 @cindex header entry of a PO file
2942 The initial comments "SOME DESCRIPTIVE TITLE", "YEAR" and
2943 "FIRST AUTHOR <EMAIL@@ADDRESS>, YEAR" ought to be replaced by sensible
2944 information. This can be done in any text editor; if Emacs is used
2945 and it switched to PO mode automatically (because it has recognized
2946 the file's suffix), you can disable it by typing @kbd{M-x fundamental-mode}.
2948 Modifying the header entry can already be done using PO mode: in Emacs,
2949 type @kbd{M-x po-mode RET} and then @kbd{RET} again to start editing the
2950 entry. You should fill in the following fields.
2953 @item Project-Id-Version
2954 This is the name and version of the package. Fill it in if it has not
2955 already been filled in by @code{xgettext}.
2957 @item Report-Msgid-Bugs-To
2958 This has already been filled in by @code{xgettext}. It contains an email
2959 address or URL where you can report bugs in the untranslated strings:
2962 @item Strings which are not entire sentences, see the maintainer guidelines
2963 in @ref{Preparing Strings}.
2964 @item Strings which use unclear terms or require additional context to be
2966 @item Strings which make invalid assumptions about notation of date, time or
2968 @item Pluralisation problems.
2969 @item Incorrect English spelling.
2970 @item Incorrect formatting.
2973 @item POT-Creation-Date
2974 This has already been filled in by @code{xgettext}.
2976 @item PO-Revision-Date
2977 You don't need to fill this in. It will be filled by the PO file editor
2978 when you save the file.
2980 @item Last-Translator
2981 Fill in your name and email address (without double quotes).
2984 Fill in the English name of the language, and the email address or
2985 homepage URL of the language team you are part of.
2987 Before starting a translation, it is a good idea to get in touch with
2988 your translation team, not only to make sure you don't do duplicated work,
2989 but also to coordinate difficult linguistic issues.
2991 @cindex list of translation teams, where to find
2992 In the Free Translation Project, each translation team has its own mailing
2993 list. The up-to-date list of teams can be found at the Free Translation
2994 Project's homepage, @uref{http://translationproject.org/}, in the "Teams"
2998 @c The purpose of this field is to make it possible to automatically
2999 @c - convert PO files to translation memory,
3000 @c - initialize a spell checker based on the PO file,
3001 @c - perform language specific checks.
3002 Fill in the language code of the language. This can be in one of three
3007 @samp{@var{ll}}, an @w{ISO 639} two-letter language code (lowercase).
3008 See @ref{Language Codes} for the list of codes.
3011 @samp{@var{ll}_@var{CC}}, where @samp{@var{ll}} is an @w{ISO 639} two-letter
3012 language code (lowercase) and @samp{@var{CC}} is an @w{ISO 3166} two-letter
3013 country code (uppercase). The country code specification is not redundant:
3014 Some languages have dialects in different countries. For example,
3015 @samp{de_AT} is used for Austria, and @samp{pt_BR} for Brazil. The country
3016 code serves to distinguish the dialects. See @ref{Language Codes} and
3017 @ref{Country Codes} for the lists of codes.
3020 @samp{@var{ll}_@var{CC}@@@var{variant}}, where @samp{@var{ll}} is an
3021 @w{ISO 639} two-letter language code (lowercase), @samp{@var{CC}} is an
3022 @w{ISO 3166} two-letter country code (uppercase), and @samp{@var{variant}} is
3023 a variant designator. The variant designator (lowercase) can be a script
3024 designator, such as @samp{latin} or @samp{cyrillic}.
3027 The naming convention @samp{@var{ll}_@var{CC}} is also the way locales are
3028 named on systems based on GNU libc. But there are three important differences:
3032 In this PO file field, but not in locale names, @samp{@var{ll}_@var{CC}}
3033 combinations denoting a language's main dialect are abbreviated as
3034 @samp{@var{ll}}. For example, @samp{de} is equivalent to @samp{de_DE}
3035 (German as spoken in Germany), and @samp{pt} to @samp{pt_PT} (Portuguese as
3036 spoken in Portugal) in this context.
3039 In this PO file field, suffixes like @samp{.@var{encoding}} are not used.
3042 In this PO file field, variant designators that are not relevant to message
3043 translation, such as @samp{@@euro}, are not used.
3046 So, if your locale name is @samp{de_DE.UTF-8}, the language specification in
3047 PO files is just @samp{de}.
3050 @cindex encoding of PO files
3051 @cindex charset of PO files
3052 Replace @samp{CHARSET} with the character encoding used for your language,
3053 in your locale, or UTF-8. This field is needed for correct operation of the
3054 @code{msgmerge} and @code{msgfmt} programs, as well as for users whose
3055 locale's character encoding differs from yours (see @ref{Charset conversion}).
3057 @cindex @code{locale} program
3058 You get the character encoding of your locale by running the shell command
3059 @samp{locale charmap}. If the result is @samp{C} or @samp{ANSI_X3.4-1968},
3060 which is equivalent to @samp{ASCII} (= @samp{US-ASCII}), it means that your
3061 locale is not correctly configured. In this case, ask your translation
3062 team which charset to use. @samp{ASCII} is not usable for any language
3065 @cindex encoding list
3066 Because the PO files must be portable to operating systems with less advanced
3067 internationalization facilities, the character encodings that can be used
3068 are limited to those supported by both GNU @code{libc} and GNU
3069 @code{libiconv}. These are:
3070 @code{ASCII}, @code{ISO-8859-1}, @code{ISO-8859-2}, @code{ISO-8859-3},
3071 @code{ISO-8859-4}, @code{ISO-8859-5}, @code{ISO-8859-6}, @code{ISO-8859-7},
3072 @code{ISO-8859-8}, @code{ISO-8859-9}, @code{ISO-8859-13}, @code{ISO-8859-14},
3074 @code{KOI8-R}, @code{KOI8-U}, @code{KOI8-T},
3075 @code{CP850}, @code{CP866}, @code{CP874},
3076 @code{CP932}, @code{CP949}, @code{CP950}, @code{CP1250}, @code{CP1251},
3077 @code{CP1252}, @code{CP1253}, @code{CP1254}, @code{CP1255}, @code{CP1256},
3078 @code{CP1257}, @code{GB2312}, @code{EUC-JP}, @code{EUC-KR}, @code{EUC-TW},
3079 @code{BIG5}, @code{BIG5-HKSCS}, @code{GBK}, @code{GB18030}, @code{SHIFT_JIS},
3080 @code{JOHAB}, @code{TIS-620}, @code{VISCII}, @code{GEORGIAN-PS}, @code{UTF-8}.
3082 @c This data is taken from glibc/localedata/SUPPORTED.
3084 In the GNU system, the following encodings are frequently used for the
3085 corresponding languages.
3087 @cindex encoding for your language
3089 @item @code{ISO-8859-1} for
3090 Afrikaans, Albanian, Basque, Breton, Catalan, Cornish, Danish, Dutch,
3091 English, Estonian, Faroese, Finnish, French, Galician, German,
3092 Greenlandic, Icelandic, Indonesian, Irish, Italian, Malay, Manx,
3093 Norwegian, Occitan, Portuguese, Spanish, Swedish, Tagalog, Uzbek,
3095 @item @code{ISO-8859-2} for
3096 Bosnian, Croatian, Czech, Hungarian, Polish, Romanian, Serbian, Slovak,
3098 @item @code{ISO-8859-3} for Maltese,
3099 @item @code{ISO-8859-5} for Macedonian, Serbian,
3100 @item @code{ISO-8859-6} for Arabic,
3101 @item @code{ISO-8859-7} for Greek,
3102 @item @code{ISO-8859-8} for Hebrew,
3103 @item @code{ISO-8859-9} for Turkish,
3104 @item @code{ISO-8859-13} for Latvian, Lithuanian, Maori,
3105 @item @code{ISO-8859-14} for Welsh,
3106 @item @code{ISO-8859-15} for
3107 Basque, Catalan, Dutch, English, Finnish, French, Galician, German, Irish,
3108 Italian, Portuguese, Spanish, Swedish, Walloon,
3109 @item @code{KOI8-R} for Russian,
3110 @item @code{KOI8-U} for Ukrainian,
3111 @item @code{KOI8-T} for Tajik,
3112 @item @code{CP1251} for Bulgarian, Belarusian,
3113 @item @code{GB2312}, @code{GBK}, @code{GB18030}
3114 for simplified writing of Chinese,
3115 @item @code{BIG5}, @code{BIG5-HKSCS}
3116 for traditional writing of Chinese,
3117 @item @code{EUC-JP} for Japanese,
3118 @item @code{EUC-KR} for Korean,
3119 @item @code{TIS-620} for Thai,
3120 @item @code{GEORGIAN-PS} for Georgian,
3121 @item @code{UTF-8} for any language, including those listed above.
3124 @cindex quote characters, use in PO files
3125 @cindex quotation marks
3126 When single quote characters or double quote characters are used in
3127 translations for your language, and your locale's encoding is one of the
3128 ISO-8859-* charsets, it is best if you create your PO files in UTF-8
3129 encoding, instead of your locale's encoding. This is because in UTF-8
3130 the real quote characters can be represented (single quote characters:
3131 U+2018, U+2019, double quote characters: U+201C, U+201D), whereas none of
3132 ISO-8859-* charsets has them all. Users in UTF-8 locales will see the
3133 real quote characters, whereas users in ISO-8859-* locales will see the
3134 vertical apostrophe and the vertical double quote instead (because that's
3135 what the character set conversion will transliterate them to).
3137 @cindex @code{xmodmap} program, and typing quotation marks
3138 To enter such quote characters under X11, you can change your keyboard
3139 mapping using the @code{xmodmap} program. The X11 names of the quote
3140 characters are "leftsinglequotemark", "rightsinglequotemark",
3141 "leftdoublequotemark", "rightdoublequotemark", "singlelowquotemark",
3142 "doublelowquotemark".
3144 Note that only recent versions of GNU Emacs support the UTF-8 encoding:
3145 Emacs 20 with Mule-UCS, and Emacs 21. As of January 2001, XEmacs doesn't
3146 support the UTF-8 encoding.
3148 The character encoding name can be written in either upper or lower case.
3149 Usually upper case is preferred.
3151 @item Content-Transfer-Encoding
3152 Set this to @code{8bit}.
3155 This field is optional. It is only needed if the PO file has plural forms.
3156 You can find them by searching for the @samp{msgid_plural} keyword. The
3157 format of the plural forms field is described in @ref{Plural forms} and
3158 @ref{Translating plural forms}.
3161 @node Updating, Editing, Creating, Top
3162 @chapter Updating Existing PO Files
3165 * msgmerge Invocation:: Invoking the @code{msgmerge} Program
3168 @node msgmerge Invocation, , Updating, Updating
3169 @section Invoking the @code{msgmerge} Program
3171 @include msgmerge.texi
3173 @node Editing, Manipulating, Updating, Top
3174 @chapter Editing PO Files
3175 @cindex Editing PO Files
3178 * KBabel:: KDE's PO File Editor
3179 * Gtranslator:: GNOME's PO File Editor
3180 * PO Mode:: Emacs's PO File Editor
3181 * Compendium:: Using Translation Compendia
3184 @node KBabel, Gtranslator, Editing, Editing
3185 @section KDE's PO File Editor
3186 @cindex KDE PO file editor
3188 @node Gtranslator, PO Mode, KBabel, Editing
3189 @section GNOME's PO File Editor
3190 @cindex GNOME PO file editor
3192 @node PO Mode, Compendium, Gtranslator, Editing
3193 @section Emacs's PO File Editor
3194 @cindex Emacs PO Mode
3198 For those of you being
3199 the lucky users of Emacs, PO mode has been specifically created
3200 for providing a cozy environment for editing or modifying PO files.
3201 While editing a PO file, PO mode allows for the easy browsing of
3202 auxiliary and compendium PO files, as well as for following references into
3203 the set of C program sources from which PO files have been derived.
3204 It has a few special features, among which are the interactive marking
3205 of program strings as translatable, and the validation of PO files
3206 with easy repositioning to PO file lines showing errors.
3208 For the beginning, besides main PO mode commands
3209 (@pxref{Main PO Commands}), you should know how to move between entries
3210 (@pxref{Entry Positioning}), and how to handle untranslated entries
3211 (@pxref{Untranslated Entries}).
3214 * Installation:: Completing GNU @code{gettext} Installation
3215 * Main PO Commands:: Main Commands
3216 * Entry Positioning:: Entry Positioning
3217 * Normalizing:: Normalizing Strings in Entries
3218 * Translated Entries:: Translated Entries
3219 * Fuzzy Entries:: Fuzzy Entries
3220 * Untranslated Entries:: Untranslated Entries
3221 * Obsolete Entries:: Obsolete Entries
3222 * Modifying Translations:: Modifying Translations
3223 * Modifying Comments:: Modifying Comments
3224 * Subedit:: Mode for Editing Translations
3225 * C Sources Context:: C Sources Context
3226 * Auxiliary:: Consulting Auxiliary PO Files
3229 @node Installation, Main PO Commands, PO Mode, PO Mode
3230 @subsection Completing GNU @code{gettext} Installation
3232 @cindex installing @code{gettext}
3233 @cindex @code{gettext} installation
3234 Once you have received, unpacked, configured and compiled the GNU
3235 @code{gettext} distribution, the @samp{make install} command puts in
3236 place the programs @code{xgettext}, @code{msgfmt}, @code{gettext}, and
3237 @code{msgmerge}, as well as their available message catalogs. To
3238 top off a comfortable installation, you might also want to make the
3239 PO mode available to your Emacs users.
3241 @emindex @file{.emacs} customizations
3242 @emindex installing PO mode
3243 During the installation of the PO mode, you might want to modify your
3244 file @file{.emacs}, once and for all, so it contains a few lines looking
3248 (setq auto-mode-alist
3249 (cons '("\\.po\\'\\|\\.po\\." . po-mode) auto-mode-alist))
3250 (autoload 'po-mode "po-mode" "Major mode for translators to edit PO files" t)
3253 Later, whenever you edit some @file{.po}
3254 file, or any file having the string @samp{.po.} within its name,
3255 Emacs loads @file{po-mode.elc} (or @file{po-mode.el}) as needed, and
3256 automatically activates PO mode commands for the associated buffer.
3257 The string @emph{PO} appears in the mode line for any buffer for
3258 which PO mode is active. Many PO files may be active at once in a
3259 single Emacs session.
3261 If you are using Emacs version 20 or newer, and have already installed
3262 the appropriate international fonts on your system, you may also tell
3263 Emacs how to determine automatically the coding system of every PO file.
3264 This will often (but not always) cause the necessary fonts to be loaded
3265 and used for displaying the translations on your Emacs screen. For this
3266 to happen, add the lines:
3269 (modify-coding-system-alist 'file "\\.po\\'\\|\\.po\\."
3270 'po-find-file-coding-system)
3271 (autoload 'po-find-file-coding-system "po-mode")
3275 to your @file{.emacs} file. If, with this, you still see boxes instead
3276 of international characters, try a different font set (via Shift Mouse
3279 @node Main PO Commands, Entry Positioning, Installation, PO Mode
3280 @subsection Main PO mode Commands
3282 @cindex PO mode (Emacs) commands
3284 After setting up Emacs with something similar to the lines in
3285 @ref{Installation}, PO mode is activated for a window when Emacs finds a
3286 PO file in that window. This puts the window read-only and establishes a
3287 po-mode-map, which is a genuine Emacs mode, in a way that is not derived
3288 from text mode in any way. Functions found on @code{po-mode-hook},
3289 if any, will be executed.
3291 When PO mode is active in a window, the letters @samp{PO} appear
3292 in the mode line for that window. The mode line also displays how
3293 many entries of each kind are held in the PO file. For example,
3294 the string @samp{132t+3f+10u+2o} would tell the translator that the
3295 PO mode contains 132 translated entries (@pxref{Translated Entries},
3296 3 fuzzy entries (@pxref{Fuzzy Entries}), 10 untranslated entries
3297 (@pxref{Untranslated Entries}) and 2 obsolete entries (@pxref{Obsolete
3298 Entries}). Zero-coefficients items are not shown. So, in this example, if
3299 the fuzzy entries were unfuzzied, the untranslated entries were translated
3300 and the obsolete entries were deleted, the mode line would merely display
3301 @samp{145t} for the counters.
3303 The main PO commands are those which do not fit into the other categories of
3304 subsequent sections. These allow for quitting PO mode or for managing windows
3309 @efindex _@r{, PO Mode command}
3310 Undo last modification to the PO file (@code{po-undo}).
3313 @efindex Q@r{, PO Mode command}
3314 Quit processing and save the PO file (@code{po-quit}).
3317 @efindex q@r{, PO Mode command}
3318 Quit processing, possibly after confirmation (@code{po-confirm-and-quit}).
3321 @efindex 0@r{, PO Mode command}
3322 Temporary leave the PO file window (@code{po-other-window}).
3326 @efindex ?@r{, PO Mode command}
3327 @efindex h@r{, PO Mode command}
3328 Show help about PO mode (@code{po-help}).
3331 @efindex =@r{, PO Mode command}
3332 Give some PO file statistics (@code{po-statistics}).
3335 @efindex V@r{, PO Mode command}
3336 Batch validate the format of the whole PO file (@code{po-validate}).
3340 @efindex _@r{, PO Mode command}
3341 @efindex po-undo@r{, PO Mode command}
3342 The command @kbd{_} (@code{po-undo}) interfaces to the Emacs
3343 @emph{undo} facility. @xref{Undo, , Undoing Changes, emacs, The Emacs
3344 Editor}. Each time @kbd{_} is typed, modifications which the translator
3345 did to the PO file are undone a little more. For the purpose of
3346 undoing, each PO mode command is atomic. This is especially true for
3347 the @kbd{@key{RET}} command: the whole edition made by using a single
3348 use of this command is undone at once, even if the edition itself
3349 implied several actions. However, while in the editing window, one
3350 can undo the edition work quite parsimoniously.
3352 @efindex Q@r{, PO Mode command}
3353 @efindex q@r{, PO Mode command}
3354 @efindex po-quit@r{, PO Mode command}
3355 @efindex po-confirm-and-quit@r{, PO Mode command}
3356 The commands @kbd{Q} (@code{po-quit}) and @kbd{q}
3357 (@code{po-confirm-and-quit}) are used when the translator is done with the
3358 PO file. The former is a bit less verbose than the latter. If the file
3359 has been modified, it is saved to disk first. In both cases, and prior to
3360 all this, the commands check if any untranslated messages remain in the
3361 PO file and, if so, the translator is asked if she really wants to leave
3362 off working with this PO file. This is the preferred way of getting rid
3363 of an Emacs PO file buffer. Merely killing it through the usual command
3364 @w{@kbd{C-x k}} (@code{kill-buffer}) is not the tidiest way to proceed.
3366 @efindex 0@r{, PO Mode command}
3367 @efindex po-other-window@r{, PO Mode command}
3368 The command @kbd{0} (@code{po-other-window}) is another, softer way,
3369 to leave PO mode, temporarily. It just moves the cursor to some other
3370 Emacs window, and pops one if necessary. For example, if the translator
3371 just got PO mode to show some source context in some other, she might
3372 discover some apparent bug in the program source that needs correction.
3373 This command allows the translator to change sex, become a programmer,
3374 and have the cursor right into the window containing the program she
3375 (or rather @emph{he}) wants to modify. By later getting the cursor back
3376 in the PO file window, or by asking Emacs to edit this file once again,
3377 PO mode is then recovered.
3379 @efindex ?@r{, PO Mode command}
3380 @efindex h@r{, PO Mode command}
3381 @efindex po-help@r{, PO Mode command}
3382 The command @kbd{h} (@code{po-help}) displays a summary of all available PO
3383 mode commands. The translator should then type any character to resume
3384 normal PO mode operations. The command @kbd{?} has the same effect
3387 @efindex =@r{, PO Mode command}
3388 @efindex po-statistics@r{, PO Mode command}
3389 The command @kbd{=} (@code{po-statistics}) computes the total number of
3390 entries in the PO file, the ordinal of the current entry (counted from
3391 1), the number of untranslated entries, the number of obsolete entries,
3392 and displays all these numbers.
3394 @efindex V@r{, PO Mode command}
3395 @efindex po-validate@r{, PO Mode command}
3396 The command @kbd{V} (@code{po-validate}) launches @code{msgfmt} in
3397 checking and verbose
3398 mode over the current PO file. This command first offers to save the
3399 current PO file on disk. The @code{msgfmt} tool, from GNU @code{gettext},
3400 has the purpose of creating a MO file out of a PO file, and PO mode uses
3401 the features of this program for checking the overall format of a PO file,
3402 as well as all individual entries.
3404 @efindex next-error@r{, stepping through PO file validation results}
3405 The program @code{msgfmt} runs asynchronously with Emacs, so the
3406 translator regains control immediately while her PO file is being studied.
3407 Error output is collected in the Emacs @samp{*compilation*} buffer,
3408 displayed in another window. The regular Emacs command @kbd{C-x`}
3409 (@code{next-error}), as well as other usual compile commands, allow the
3410 translator to reposition quickly to the offending parts of the PO file.
3411 Once the cursor is on the line in error, the translator may decide on
3412 any PO mode action which would help correcting the error.
3414 @node Entry Positioning, Normalizing, Main PO Commands, PO Mode
3415 @subsection Entry Positioning
3417 @emindex current entry of a PO file
3418 The cursor in a PO file window is almost always part of
3419 an entry. The only exceptions are the special case when the cursor
3420 is after the last entry in the file, or when the PO file is
3421 empty. The entry where the cursor is found to be is said to be the
3422 current entry. Many PO mode commands operate on the current entry,
3423 so moving the cursor does more than allowing the translator to browse
3424 the PO file, this also selects on which entry commands operate.
3426 @emindex moving through a PO file
3427 Some PO mode commands alter the position of the cursor in a specialized
3428 way. A few of those special purpose positioning are described here,
3429 the others are described in following sections (for a complete list try
3435 @efindex .@r{, PO Mode command}
3436 Redisplay the current entry (@code{po-current-entry}).
3439 @efindex n@r{, PO Mode command}
3440 Select the entry after the current one (@code{po-next-entry}).
3443 @efindex p@r{, PO Mode command}
3444 Select the entry before the current one (@code{po-previous-entry}).
3447 @efindex <@r{, PO Mode command}
3448 Select the first entry in the PO file (@code{po-first-entry}).
3451 @efindex >@r{, PO Mode command}
3452 Select the last entry in the PO file (@code{po-last-entry}).
3455 @efindex m@r{, PO Mode command}
3456 Record the location of the current entry for later use
3457 (@code{po-push-location}).
3460 @efindex r@r{, PO Mode command}
3461 Return to a previously saved entry location (@code{po-pop-location}).
3464 @efindex x@r{, PO Mode command}
3465 Exchange the current entry location with the previously saved one
3466 (@code{po-exchange-location}).
3470 @efindex .@r{, PO Mode command}
3471 @efindex po-current-entry@r{, PO Mode command}
3472 Any Emacs command able to reposition the cursor may be used
3473 to select the current entry in PO mode, including commands which
3474 move by characters, lines, paragraphs, screens or pages, and search
3475 commands. However, there is a kind of standard way to display the
3476 current entry in PO mode, which usual Emacs commands moving
3477 the cursor do not especially try to enforce. The command @kbd{.}
3478 (@code{po-current-entry}) has the sole purpose of redisplaying the
3479 current entry properly, after the current entry has been changed by
3480 means external to PO mode, or the Emacs screen otherwise altered.
3482 It is yet to be decided if PO mode helps the translator, or otherwise
3483 irritates her, by forcing a rigid window disposition while she
3484 is doing her work. We originally had quite precise ideas about
3485 how windows should behave, but on the other hand, anyone used to
3486 Emacs is often happy to keep full control. Maybe a fixed window
3487 disposition might be offered as a PO mode option that the translator
3488 might activate or deactivate at will, so it could be offered on an
3489 experimental basis. If nobody feels a real need for using it, or
3490 a compulsion for writing it, we should drop this whole idea.
3491 The incentive for doing it should come from translators rather than
3492 programmers, as opinions from an experienced translator are surely
3493 more worth to me than opinions from programmers @emph{thinking} about
3494 how @emph{others} should do translation.
3496 @efindex n@r{, PO Mode command}
3497 @efindex po-next-entry@r{, PO Mode command}
3498 @efindex p@r{, PO Mode command}
3499 @efindex po-previous-entry@r{, PO Mode command}
3500 The commands @kbd{n} (@code{po-next-entry}) and @kbd{p}
3501 (@code{po-previous-entry}) move the cursor the entry following,
3502 or preceding, the current one. If @kbd{n} is given while the
3503 cursor is on the last entry of the PO file, or if @kbd{p}
3504 is given while the cursor is on the first entry, no move is done.
3506 @efindex <@r{, PO Mode command}
3507 @efindex po-first-entry@r{, PO Mode command}
3508 @efindex >@r{, PO Mode command}
3509 @efindex po-last-entry@r{, PO Mode command}
3510 The commands @kbd{<} (@code{po-first-entry}) and @kbd{>}
3511 (@code{po-last-entry}) move the cursor to the first entry, or last
3512 entry, of the PO file. When the cursor is located past the last
3513 entry in a PO file, most PO mode commands will return an error saying
3514 @samp{After last entry}. Moreover, the commands @kbd{<} and @kbd{>}
3515 have the special property of being able to work even when the cursor
3516 is not into some PO file entry, and one may use them for nicely
3517 correcting this situation. But even these commands will fail on a
3518 truly empty PO file. There are development plans for the PO mode for it
3519 to interactively fill an empty PO file from sources. @xref{Marking}.
3521 The translator may decide, before working at the translation of
3522 a particular entry, that she needs to browse the remainder of the
3523 PO file, maybe for finding the terminology or phraseology used
3524 in related entries. She can of course use the standard Emacs idioms
3525 for saving the current cursor location in some register, and use that
3526 register for getting back, or else, use the location ring.
3528 @efindex m@r{, PO Mode command}
3529 @efindex po-push-location@r{, PO Mode command}
3530 @efindex r@r{, PO Mode command}
3531 @efindex po-pop-location@r{, PO Mode command}
3532 PO mode offers another approach, by which cursor locations may be saved
3533 onto a special stack. The command @kbd{m} (@code{po-push-location})
3534 merely adds the location of current entry to the stack, pushing
3535 the already saved locations under the new one. The command
3536 @kbd{r} (@code{po-pop-location}) consumes the top stack element and
3537 repositions the cursor to the entry associated with that top element.
3538 This position is then lost, for the next @kbd{r} will move the cursor
3539 to the previously saved location, and so on until no locations remain
3542 If the translator wants the position to be kept on the location stack,
3543 maybe for taking a look at the entry associated with the top
3544 element, then go elsewhere with the intent of getting back later, she
3545 ought to use @kbd{m} immediately after @kbd{r}.
3547 @efindex x@r{, PO Mode command}
3548 @efindex po-exchange-location@r{, PO Mode command}
3549 The command @kbd{x} (@code{po-exchange-location}) simultaneously
3550 repositions the cursor to the entry associated with the top element of
3551 the stack of saved locations, and replaces that top element with the
3552 location of the current entry before the move. Consequently, repeating
3553 the @kbd{x} command toggles alternatively between two entries.
3554 For achieving this, the translator will position the cursor on the
3555 first entry, use @kbd{m}, then position to the second entry, and
3556 merely use @kbd{x} for making the switch.
3558 @node Normalizing, Translated Entries, Entry Positioning, PO Mode
3559 @subsection Normalizing Strings in Entries
3560 @cindex string normalization in entries
3562 There are many different ways for encoding a particular string into a
3563 PO file entry, because there are so many different ways to split and
3564 quote multi-line strings, and even, to represent special characters
3565 by backslashed escaped sequences. Some features of PO mode rely on
3566 the ability for PO mode to scan an already existing PO file for a
3567 particular string encoded into the @code{msgid} field of some entry.
3568 Even if PO mode has internally all the built-in machinery for
3569 implementing this recognition easily, doing it fast is technically
3570 difficult. To facilitate a solution to this efficiency problem,
3571 we decided on a canonical representation for strings.
3573 A conventional representation of strings in a PO file is currently
3574 under discussion, and PO mode experiments with a canonical representation.
3575 Having both @code{xgettext} and PO mode converging towards a uniform
3576 way of representing equivalent strings would be useful, as the internal
3577 normalization needed by PO mode could be automatically satisfied
3578 when using @code{xgettext} from GNU @code{gettext}. An explicit
3579 PO mode normalization should then be only necessary for PO files
3580 imported from elsewhere, or for when the convention itself evolves.
3582 So, for achieving normalization of at least the strings of a given
3583 PO file needing a canonical representation, the following PO mode
3584 command is available:
3586 @emindex string normalization in entries
3588 @item M-x po-normalize
3589 @efindex po-normalize@r{, PO Mode command}
3590 Tidy the whole PO file by making entries more uniform.
3594 The special command @kbd{M-x po-normalize}, which has no associated
3595 keys, revises all entries, ensuring that strings of both original
3596 and translated entries use uniform internal quoting in the PO file.
3597 It also removes any crumb after the last entry. This command may be
3598 useful for PO files freshly imported from elsewhere, or if we ever
3599 improve on the canonical quoting format we use. This canonical format
3600 is not only meant for getting cleaner PO files, but also for greatly
3601 speeding up @code{msgid} string lookup for some other PO mode commands.
3603 @kbd{M-x po-normalize} presently makes three passes over the entries.
3604 The first implements heuristics for converting PO files for GNU
3605 @code{gettext} 0.6 and earlier, in which @code{msgid} and @code{msgstr}
3606 fields were using K&R style C string syntax for multi-line strings.
3607 These heuristics may fail for comments not related to obsolete
3608 entries and ending with a backslash; they also depend on subsequent
3609 passes for finalizing the proper commenting of continued lines for
3610 obsolete entries. This first pass might disappear once all oldish PO
3611 files would have been adjusted. The second and third pass normalize
3612 all @code{msgid} and @code{msgstr} strings respectively. They also
3613 clean out those trailing backslashes used by XView's @code{msgfmt}
3614 for continued lines.
3616 @cindex importing PO files
3617 Having such an explicit normalizing command allows for importing PO
3618 files from other sources, but also eases the evolution of the current
3619 convention, evolution driven mostly by aesthetic concerns, as of now.
3620 It is easy to make suggested adjustments at a later time, as the
3621 normalizing command and eventually, other GNU @code{gettext} tools
3622 should greatly automate conformance. A description of the canonical
3623 string format is given below, for the particular benefit of those not
3624 having Emacs handy, and who would nevertheless want to handcraft
3625 their PO files in nice ways.
3627 @cindex multi-line strings
3628 Right now, in PO mode, strings are single line or multi-line. A string
3629 goes multi-line if and only if it has @emph{embedded} newlines, that
3630 is, if it matches @samp{[^\n]\n+[^\n]}. So, we would have:
3633 msgstr "\n\nHello, world!\n\n\n"
3636 but, replacing the space by a newline, this becomes:
3648 We are deliberately using a caricatural example, here, to make the
3649 point clearer. Usually, multi-lines are not that bad looking.
3650 It is probable that we will implement the following suggestion.
3651 We might lump together all initial newlines into the empty string,
3652 and also all newlines introducing empty lines (that is, for @w{@var{n}
3653 > 1}, the @var{n}-1'th last newlines would go together on a separate
3654 string), so making the previous example appear:
3663 There are a few yet undecided little points about string normalization,
3664 to be documented in this manual, once these questions settle.
3666 @node Translated Entries, Fuzzy Entries, Normalizing, PO Mode
3667 @subsection Translated Entries
3668 @cindex translated entries
3670 Each PO file entry for which the @code{msgstr} field has been filled with
3671 a translation, and which is not marked as fuzzy (@pxref{Fuzzy Entries}),
3672 is said to be a @dfn{translated} entry. Only translated entries will
3673 later be compiled by GNU @code{msgfmt} and become usable in programs.
3674 Other entry types will be excluded; translation will not occur for them.
3676 @emindex moving by translated entries
3677 Some commands are more specifically related to translated entry processing.
3681 @efindex t@r{, PO Mode command}
3682 Find the next translated entry (@code{po-next-translated-entry}).
3685 @efindex T@r{, PO Mode command}
3686 Find the previous translated entry (@code{po-previous-translated-entry}).
3690 @efindex t@r{, PO Mode command}
3691 @efindex po-next-translated-entry@r{, PO Mode command}
3692 @efindex T@r{, PO Mode command}
3693 @efindex po-previous-translated-entry@r{, PO Mode command}
3694 The commands @kbd{t} (@code{po-next-translated-entry}) and @kbd{T}
3695 (@code{po-previous-translated-entry}) move forwards or backwards, chasing
3696 for an translated entry. If none is found, the search is extended and
3697 wraps around in the PO file buffer.
3699 @evindex po-auto-fuzzy-on-edit@r{, PO Mode variable}
3700 Translated entries usually result from the translator having edited in
3701 a translation for them, @ref{Modifying Translations}. However, if the
3702 variable @code{po-auto-fuzzy-on-edit} is not @code{nil}, the entry having
3703 received a new translation first becomes a fuzzy entry, which ought to
3704 be later unfuzzied before becoming an official, genuine translated entry.
3705 @xref{Fuzzy Entries}.
3707 @node Fuzzy Entries, Untranslated Entries, Translated Entries, PO Mode
3708 @subsection Fuzzy Entries
3709 @cindex fuzzy entries
3711 @cindex attributes of a PO file entry
3712 @cindex attribute, fuzzy
3713 Each PO file entry may have a set of @dfn{attributes}, which are
3714 qualities given a name and explicitly associated with the translation,
3715 using a special system comment. One of these attributes
3716 has the name @code{fuzzy}, and entries having this attribute are said
3717 to have a fuzzy translation. They are called fuzzy entries, for short.
3719 Fuzzy entries, even if they account for translated entries for
3720 most other purposes, usually call for revision by the translator.
3721 Those may be produced by applying the program @code{msgmerge} to
3722 update an older translated PO files according to a new PO template
3723 file, when this tool hypothesises that some new @code{msgid} has
3724 been modified only slightly out of an older one, and chooses to pair
3725 what it thinks to be the old translation for the new modified entry.
3726 The slight alteration in the original string (the @code{msgid} string)
3727 should often be reflected in the translated string, and this requires
3728 the intervention of the translator. For this reason, @code{msgmerge}
3729 might mark some entries as being fuzzy.
3731 @emindex moving by fuzzy entries
3732 Also, the translator may decide herself to mark an entry as fuzzy
3733 for her own convenience, when she wants to remember that the entry
3734 has to be later revisited. So, some commands are more specifically
3735 related to fuzzy entry processing.
3739 @efindex f@r{, PO Mode command}
3740 @c better append "-entry" all the time. -ke-
3741 Find the next fuzzy entry (@code{po-next-fuzzy-entry}).
3744 @efindex F@r{, PO Mode command}
3745 Find the previous fuzzy entry (@code{po-previous-fuzzy-entry}).
3748 @efindex TAB@r{, PO Mode command}
3749 Remove the fuzzy attribute of the current entry (@code{po-unfuzzy}).
3753 @efindex f@r{, PO Mode command}
3754 @efindex po-next-fuzzy-entry@r{, PO Mode command}
3755 @efindex F@r{, PO Mode command}
3756 @efindex po-previous-fuzzy-entry@r{, PO Mode command}
3757 The commands @kbd{f} (@code{po-next-fuzzy-entry}) and @kbd{F}
3758 (@code{po-previous-fuzzy-entry}) move forwards or backwards, chasing for
3759 a fuzzy entry. If none is found, the search is extended and wraps
3760 around in the PO file buffer.
3762 @efindex TAB@r{, PO Mode command}
3763 @efindex po-unfuzzy@r{, PO Mode command}
3764 @evindex po-auto-select-on-unfuzzy@r{, PO Mode variable}
3765 The command @kbd{@key{TAB}} (@code{po-unfuzzy}) removes the fuzzy
3766 attribute associated with an entry, usually leaving it translated.
3767 Further, if the variable @code{po-auto-select-on-unfuzzy} has not
3768 the @code{nil} value, the @kbd{@key{TAB}} command will automatically chase
3769 for another interesting entry to work on. The initial value of
3770 @code{po-auto-select-on-unfuzzy} is @code{nil}.
3772 The initial value of @code{po-auto-fuzzy-on-edit} is @code{nil}. However,
3773 if the variable @code{po-auto-fuzzy-on-edit} is set to @code{t}, any entry
3774 edited through the @kbd{@key{RET}} command is marked fuzzy, as a way to
3775 ensure some kind of double check, later. In this case, the usual paradigm
3776 is that an entry becomes fuzzy (if not already) whenever the translator
3777 modifies it. If she is satisfied with the translation, she then uses
3778 @kbd{@key{TAB}} to pick another entry to work on, clearing the fuzzy attribute
3779 on the same blow. If she is not satisfied yet, she merely uses @kbd{@key{SPC}}
3780 to chase another entry, leaving the entry fuzzy.
3782 @efindex DEL@r{, PO Mode command}
3783 @efindex po-fade-out-entry@r{, PO Mode command}
3784 The translator may also use the @kbd{@key{DEL}} command
3785 (@code{po-fade-out-entry}) over any translated entry to mark it as being
3786 fuzzy, when she wants to easily leave a trace she wants to later return
3787 working at this entry.
3789 Also, when time comes to quit working on a PO file buffer with the @kbd{q}
3790 command, the translator is asked for confirmation, if fuzzy string
3793 @node Untranslated Entries, Obsolete Entries, Fuzzy Entries, PO Mode
3794 @subsection Untranslated Entries
3795 @cindex untranslated entries
3797 When @code{xgettext} originally creates a PO file, unless told
3798 otherwise, it initializes the @code{msgid} field with the untranslated
3799 string, and leaves the @code{msgstr} string to be empty. Such entries,
3800 having an empty translation, are said to be @dfn{untranslated} entries.
3801 Later, when the programmer slightly modifies some string right in
3802 the program, this change is later reflected in the PO file
3803 by the appearance of a new untranslated entry for the modified string.
3805 The usual commands moving from entry to entry consider untranslated
3806 entries on the same level as active entries. Untranslated entries
3807 are easily recognizable by the fact they end with @w{@samp{msgstr ""}}.
3809 @emindex moving by untranslated entries
3810 The work of the translator might be (quite naively) seen as the process
3811 of seeking for an untranslated entry, editing a translation for
3812 it, and repeating these actions until no untranslated entries remain.
3813 Some commands are more specifically related to untranslated entry
3818 @efindex u@r{, PO Mode command}
3819 Find the next untranslated entry (@code{po-next-untranslated-entry}).
3822 @efindex U@r{, PO Mode command}
3823 Find the previous untranslated entry (@code{po-previous-untransted-entry}).
3826 @efindex k@r{, PO Mode command}
3827 Turn the current entry into an untranslated one (@code{po-kill-msgstr}).
3831 @efindex u@r{, PO Mode command}
3832 @efindex po-next-untranslated-entry@r{, PO Mode command}
3833 @efindex U@r{, PO Mode command}
3834 @efindex po-previous-untransted-entry@r{, PO Mode command}
3835 The commands @kbd{u} (@code{po-next-untranslated-entry}) and @kbd{U}
3836 (@code{po-previous-untransted-entry}) move forwards or backwards,
3837 chasing for an untranslated entry. If none is found, the search is
3838 extended and wraps around in the PO file buffer.
3840 @efindex k@r{, PO Mode command}
3841 @efindex po-kill-msgstr@r{, PO Mode command}
3842 An entry can be turned back into an untranslated entry by
3843 merely emptying its translation, using the command @kbd{k}
3844 (@code{po-kill-msgstr}). @xref{Modifying Translations}.
3846 Also, when time comes to quit working on a PO file buffer
3847 with the @kbd{q} command, the translator is asked for confirmation,
3848 if some untranslated string still exists.
3850 @node Obsolete Entries, Modifying Translations, Untranslated Entries, PO Mode
3851 @subsection Obsolete Entries
3852 @cindex obsolete entries
3854 By @dfn{obsolete} PO file entries, we mean those entries which are
3855 commented out, usually by @code{msgmerge} when it found that the
3856 translation is not needed anymore by the package being localized.
3858 The usual commands moving from entry to entry consider obsolete
3859 entries on the same level as active entries. Obsolete entries are
3860 easily recognizable by the fact that all their lines start with
3861 @code{#}, even those lines containing @code{msgid} or @code{msgstr}.
3863 Commands exist for emptying the translation or reinitializing it
3864 to the original untranslated string. Commands interfacing with the
3865 kill ring may force some previously saved text into the translation.
3866 The user may interactively edit the translation. All these commands
3867 may apply to obsolete entries, carefully leaving the entry obsolete
3870 @emindex moving by obsolete entries
3871 Moreover, some commands are more specifically related to obsolete
3876 @efindex o@r{, PO Mode command}
3877 Find the next obsolete entry (@code{po-next-obsolete-entry}).
3880 @efindex O@r{, PO Mode command}
3881 Find the previous obsolete entry (@code{po-previous-obsolete-entry}).
3884 @efindex DEL@r{, PO Mode command}
3885 Make an active entry obsolete, or zap out an obsolete entry
3886 (@code{po-fade-out-entry}).
3890 @efindex o@r{, PO Mode command}
3891 @efindex po-next-obsolete-entry@r{, PO Mode command}
3892 @efindex O@r{, PO Mode command}
3893 @efindex po-previous-obsolete-entry@r{, PO Mode command}
3894 The commands @kbd{o} (@code{po-next-obsolete-entry}) and @kbd{O}
3895 (@code{po-previous-obsolete-entry}) move forwards or backwards,
3896 chasing for an obsolete entry. If none is found, the search is
3897 extended and wraps around in the PO file buffer.
3899 PO mode does not provide ways for un-commenting an obsolete entry
3900 and making it active, because this would reintroduce an original
3901 untranslated string which does not correspond to any marked string
3902 in the program sources. This goes with the philosophy of never
3903 introducing useless @code{msgid} values.
3905 @efindex DEL@r{, PO Mode command}
3906 @efindex po-fade-out-entry@r{, PO Mode command}
3907 @emindex obsolete active entry
3908 @emindex comment out PO file entry
3909 However, it is possible to comment out an active entry, so making
3910 it obsolete. GNU @code{gettext} utilities will later react to the
3911 disappearance of a translation by using the untranslated string.
3912 The command @kbd{@key{DEL}} (@code{po-fade-out-entry}) pushes the current entry
3913 a little further towards annihilation. If the entry is active (it is a
3914 translated entry), then it is first made fuzzy. If it is already fuzzy,
3915 then the entry is merely commented out, with confirmation. If the entry
3916 is already obsolete, then it is completely deleted from the PO file.
3917 It is easy to recycle the translation so deleted into some other PO file
3918 entry, usually one which is untranslated. @xref{Modifying Translations}.
3920 Here is a quite interesting problem to solve for later development of
3921 PO mode, for those nights you are not sleepy. The idea would be that
3922 PO mode might become bright enough, one of these days, to make good
3923 guesses at retrieving the most probable candidate, among all obsolete
3924 entries, for initializing the translation of a newly appeared string.
3925 I think it might be a quite hard problem to do this algorithmically, as
3926 we have to develop good and efficient measures of string similarity.
3927 Right now, PO mode completely lets the decision to the translator,
3928 when the time comes to find the adequate obsolete translation, it
3929 merely tries to provide handy tools for helping her to do so.
3931 @node Modifying Translations, Modifying Comments, Obsolete Entries, PO Mode
3932 @subsection Modifying Translations
3933 @cindex editing translations
3934 @emindex editing translations
3936 PO mode prevents direct modification of the PO file, by the usual
3937 means Emacs gives for altering a buffer's contents. By doing so,
3938 it pretends helping the translator to avoid little clerical errors
3939 about the overall file format, or the proper quoting of strings,
3940 as those errors would be easily made. Other kinds of errors are
3941 still possible, but some may be caught and diagnosed by the batch
3942 validation process, which the translator may always trigger by the
3943 @kbd{V} command. For all other errors, the translator has to rely on
3944 her own judgment, and also on the linguistic reports submitted to her
3945 by the users of the translated package, having the same mother tongue.
3947 When the time comes to create a translation, correct an error diagnosed
3948 mechanically or reported by a user, the translators have to resort to
3949 using the following commands for modifying the translations.
3953 @efindex RET@r{, PO Mode command}
3954 Interactively edit the translation (@code{po-edit-msgstr}).
3958 @efindex LFD@r{, PO Mode command}
3959 @efindex C-j@r{, PO Mode command}
3960 Reinitialize the translation with the original, untranslated string
3961 (@code{po-msgid-to-msgstr}).
3964 @efindex k@r{, PO Mode command}
3965 Save the translation on the kill ring, and delete it (@code{po-kill-msgstr}).
3968 @efindex w@r{, PO Mode command}
3969 Save the translation on the kill ring, without deleting it
3970 (@code{po-kill-ring-save-msgstr}).
3973 @efindex y@r{, PO Mode command}
3974 Replace the translation, taking the new from the kill ring
3975 (@code{po-yank-msgstr}).
3979 @efindex RET@r{, PO Mode command}
3980 @efindex po-edit-msgstr@r{, PO Mode command}
3981 The command @kbd{@key{RET}} (@code{po-edit-msgstr}) opens a new Emacs
3982 window meant to edit in a new translation, or to modify an already existing
3983 translation. The new window contains a copy of the translation taken from
3984 the current PO file entry, all ready for edition, expunged of all quoting
3985 marks, fully modifiable and with the complete extent of Emacs modifying
3986 commands. When the translator is done with her modifications, she may use
3987 @w{@kbd{C-c C-c}} to close the subedit window with the automatically requoted
3988 results, or @w{@kbd{C-c C-k}} to abort her modifications. @xref{Subedit},
3989 for more information.
3991 @efindex LFD@r{, PO Mode command}
3992 @efindex C-j@r{, PO Mode command}
3993 @efindex po-msgid-to-msgstr@r{, PO Mode command}
3994 The command @kbd{@key{LFD}} (@code{po-msgid-to-msgstr}) initializes, or
3995 reinitializes the translation with the original string. This command is
3996 normally used when the translator wants to redo a fresh translation of
3997 the original string, disregarding any previous work.
3999 @evindex po-auto-edit-with-msgid@r{, PO Mode variable}
4000 It is possible to arrange so, whenever editing an untranslated
4001 entry, the @kbd{@key{LFD}} command be automatically executed. If you set
4002 @code{po-auto-edit-with-msgid} to @code{t}, the translation gets
4003 initialised with the original string, in case none exists already.
4004 The default value for @code{po-auto-edit-with-msgid} is @code{nil}.
4006 @emindex starting a string translation
4007 In fact, whether it is best to start a translation with an empty
4008 string, or rather with a copy of the original string, is a matter of
4009 taste or habit. Sometimes, the source language and the
4010 target language are so different that is simply best to start writing
4011 on an empty page. At other times, the source and target languages
4012 are so close that it would be a waste to retype a number of words
4013 already being written in the original string. A translator may also
4014 like having the original string right under her eyes, as she will
4015 progressively overwrite the original text with the translation, even
4016 if this requires some extra editing work to get rid of the original.
4018 @emindex cut and paste for translated strings
4019 @efindex k@r{, PO Mode command}
4020 @efindex po-kill-msgstr@r{, PO Mode command}
4021 @efindex w@r{, PO Mode command}
4022 @efindex po-kill-ring-save-msgstr@r{, PO Mode command}
4023 The command @kbd{k} (@code{po-kill-msgstr}) merely empties the
4024 translation string, so turning the entry into an untranslated
4025 one. But while doing so, its previous contents is put apart in
4026 a special place, known as the kill ring. The command @kbd{w}
4027 (@code{po-kill-ring-save-msgstr}) has also the effect of taking a
4028 copy of the translation onto the kill ring, but it otherwise leaves
4029 the entry alone, and does @emph{not} remove the translation from the
4030 entry. Both commands use exactly the Emacs kill ring, which is shared
4031 between buffers, and which is well known already to Emacs lovers.
4033 The translator may use @kbd{k} or @kbd{w} many times in the course
4034 of her work, as the kill ring may hold several saved translations.
4035 From the kill ring, strings may later be reinserted in various
4036 Emacs buffers. In particular, the kill ring may be used for moving
4037 translation strings between different entries of a single PO file
4038 buffer, or if the translator is handling many such buffers at once,
4039 even between PO files.
4041 To facilitate exchanges with buffers which are not in PO mode, the
4042 translation string put on the kill ring by the @kbd{k} command is fully
4043 unquoted before being saved: external quotes are removed, multi-line
4044 strings are concatenated, and backslash escaped sequences are turned
4045 into their corresponding characters. In the special case of obsolete
4046 entries, the translation is also uncommented prior to saving.
4048 @efindex y@r{, PO Mode command}
4049 @efindex po-yank-msgstr@r{, PO Mode command}
4050 The command @kbd{y} (@code{po-yank-msgstr}) completely replaces the
4051 translation of the current entry by a string taken from the kill ring.
4052 Following Emacs terminology, we then say that the replacement
4053 string is @dfn{yanked} into the PO file buffer.
4054 @xref{Yanking, , , emacs, The Emacs Editor}.
4055 The first time @kbd{y} is used, the translation receives the value of
4056 the most recent addition to the kill ring. If @kbd{y} is typed once
4057 again, immediately, without intervening keystrokes, the translation
4058 just inserted is taken away and replaced by the second most recent
4059 addition to the kill ring. By repeating @kbd{y} many times in a row,
4060 the translator may travel along the kill ring for saved strings,
4061 until she finds the string she really wanted.
4063 When a string is yanked into a PO file entry, it is fully and
4064 automatically requoted for complying with the format PO files should
4065 have. Further, if the entry is obsolete, PO mode then appropriately
4066 push the inserted string inside comments. Once again, translators
4067 should not burden themselves with quoting considerations besides, of
4068 course, the necessity of the translated string itself respective to
4069 the program using it.
4071 Note that @kbd{k} or @kbd{w} are not the only commands pushing strings
4072 on the kill ring, as almost any PO mode command replacing translation
4073 strings (or the translator comments) automatically saves the old string
4074 on the kill ring. The main exceptions to this general rule are the
4075 yanking commands themselves.
4077 @emindex using obsolete translations to make new entries
4078 To better illustrate the operation of killing and yanking, let's
4079 use an actual example, taken from a common situation. When the
4080 programmer slightly modifies some string right in the program, his
4081 change is later reflected in the PO file by the appearance
4082 of a new untranslated entry for the modified string, and the fact
4083 that the entry translating the original or unmodified string becomes
4084 obsolete. In many cases, the translator might spare herself some work
4085 by retrieving the unmodified translation from the obsolete entry,
4086 then initializing the untranslated entry @code{msgstr} field with
4087 this retrieved translation. Once this done, the obsolete entry is
4088 not wanted anymore, and may be safely deleted.
4090 When the translator finds an untranslated entry and suspects that a
4091 slight variant of the translation exists, she immediately uses @kbd{m}
4092 to mark the current entry location, then starts chasing obsolete
4093 entries with @kbd{o}, hoping to find some translation corresponding
4094 to the unmodified string. Once found, she uses the @kbd{@key{DEL}} command
4095 for deleting the obsolete entry, knowing that @kbd{@key{DEL}} also @emph{kills}
4096 the translation, that is, pushes the translation on the kill ring.
4097 Then, @kbd{r} returns to the initial untranslated entry, and @kbd{y}
4098 then @emph{yanks} the saved translation right into the @code{msgstr}
4099 field. The translator is then free to use @kbd{@key{RET}} for fine
4100 tuning the translation contents, and maybe to later use @kbd{u},
4101 then @kbd{m} again, for going on with the next untranslated string.
4103 When some sequence of keys has to be typed over and over again, the
4104 translator may find it useful to become better acquainted with the Emacs
4105 capability of learning these sequences and playing them back under request.
4106 @xref{Keyboard Macros, , , emacs, The Emacs Editor}.
4108 @node Modifying Comments, Subedit, Modifying Translations, PO Mode
4109 @subsection Modifying Comments
4110 @cindex editing comments in PO files
4111 @emindex editing comments
4113 Any translation work done seriously will raise many linguistic
4114 difficulties, for which decisions have to be made, and the choices
4115 further documented. These documents may be saved within the
4116 PO file in form of translator comments, which the translator
4117 is free to create, delete, or modify at will. These comments may
4118 be useful to herself when she returns to this PO file after a while.
4120 Comments not having whitespace after the initial @samp{#}, for example,
4121 those beginning with @samp{#.} or @samp{#:}, are @emph{not} translator
4122 comments, they are exclusively created by other @code{gettext} tools.
4123 So, the commands below will never alter such system added comments,
4124 they are not meant for the translator to modify. @xref{PO Files}.
4126 The following commands are somewhat similar to those modifying translations,
4127 so the general indications given for those apply here. @xref{Modifying
4133 @efindex #@r{, PO Mode command}
4134 Interactively edit the translator comments (@code{po-edit-comment}).
4137 @efindex K@r{, PO Mode command}
4138 Save the translator comments on the kill ring, and delete it
4139 (@code{po-kill-comment}).
4142 @efindex W@r{, PO Mode command}
4143 Save the translator comments on the kill ring, without deleting it
4144 (@code{po-kill-ring-save-comment}).
4147 @efindex Y@r{, PO Mode command}
4148 Replace the translator comments, taking the new from the kill ring
4149 (@code{po-yank-comment}).
4153 These commands parallel PO mode commands for modifying the translation
4154 strings, and behave much the same way as they do, except that they handle
4155 this part of PO file comments meant for translator usage, rather
4156 than the translation strings. So, if the descriptions given below are
4157 slightly succinct, it is because the full details have already been given.
4158 @xref{Modifying Translations}.
4160 @efindex #@r{, PO Mode command}
4161 @efindex po-edit-comment@r{, PO Mode command}
4162 The command @kbd{#} (@code{po-edit-comment}) opens a new Emacs window
4163 containing a copy of the translator comments on the current PO file entry.
4164 If there are no such comments, PO mode understands that the translator wants
4165 to add a comment to the entry, and she is presented with an empty screen.
4166 Comment marks (@code{#}) and the space following them are automatically
4167 removed before edition, and reinstated after. For translator comments
4168 pertaining to obsolete entries, the uncommenting and recommenting operations
4169 are done twice. Once in the editing window, the keys @w{@kbd{C-c C-c}}
4170 allow the translator to tell she is finished with editing the comment.
4171 @xref{Subedit}, for further details.
4173 @evindex po-subedit-mode-hook@r{, PO Mode variable}
4174 Functions found on @code{po-subedit-mode-hook}, if any, are executed after
4175 the string has been inserted in the edit buffer.
4177 @efindex K@r{, PO Mode command}
4178 @efindex po-kill-comment@r{, PO Mode command}
4179 @efindex W@r{, PO Mode command}
4180 @efindex po-kill-ring-save-comment@r{, PO Mode command}
4181 @efindex Y@r{, PO Mode command}
4182 @efindex po-yank-comment@r{, PO Mode command}
4183 The command @kbd{K} (@code{po-kill-comment}) gets rid of all
4184 translator comments, while saving those comments on the kill ring.
4185 The command @kbd{W} (@code{po-kill-ring-save-comment}) takes
4186 a copy of the translator comments on the kill ring, but leaves
4187 them undisturbed in the current entry. The command @kbd{Y}
4188 (@code{po-yank-comment}) completely replaces the translator comments
4189 by a string taken at the front of the kill ring. When this command
4190 is immediately repeated, the comments just inserted are withdrawn,
4191 and replaced by other strings taken along the kill ring.
4193 On the kill ring, all strings have the same nature. There is no
4194 distinction between @emph{translation} strings and @emph{translator
4195 comments} strings. So, for example, let's presume the translator
4196 has just finished editing a translation, and wants to create a new
4197 translator comment to document why the previous translation was
4198 not good, just to remember what was the problem. Foreseeing that she
4199 will do that in her documentation, the translator may want to quote
4200 the previous translation in her translator comments. To do so, she
4201 may initialize the translator comments with the previous translation,
4202 still at the head of the kill ring. Because editing already pushed the
4203 previous translation on the kill ring, she merely has to type @kbd{M-w}
4204 prior to @kbd{#}, and the previous translation will be right there,
4205 all ready for being introduced by some explanatory text.
4207 On the other hand, presume there are some translator comments already
4208 and that the translator wants to add to those comments, instead
4209 of wholly replacing them. Then, she should edit the comment right
4210 away with @kbd{#}. Once inside the editing window, she can use the
4211 regular Emacs commands @kbd{C-y} (@code{yank}) and @kbd{M-y}
4212 (@code{yank-pop}) to get the previous translation where she likes.
4214 @node Subedit, C Sources Context, Modifying Comments, PO Mode
4215 @subsection Details of Sub Edition
4216 @emindex subedit minor mode
4218 The PO subedit minor mode has a few peculiarities worth being described
4219 in fuller detail. It installs a few commands over the usual editing set
4220 of Emacs, which are described below.
4224 @efindex C-c C-c@r{, PO Mode command}
4225 Complete edition (@code{po-subedit-exit}).
4228 @efindex C-c C-k@r{, PO Mode command}
4229 Abort edition (@code{po-subedit-abort}).
4232 @efindex C-c C-a@r{, PO Mode command}
4233 Consult auxiliary PO files (@code{po-subedit-cycle-auxiliary}).
4237 @emindex exiting PO subedit
4238 @efindex C-c C-c@r{, PO Mode command}
4239 @efindex po-subedit-exit@r{, PO Mode command}
4240 The window's contents represents a translation for a given message,
4241 or a translator comment. The translator may modify this window to
4242 her heart's content. Once this is done, the command @w{@kbd{C-c C-c}}
4243 (@code{po-subedit-exit}) may be used to return the edited translation into
4244 the PO file, replacing the original translation, even if it moved out of
4245 sight or if buffers were switched.
4247 @efindex C-c C-k@r{, PO Mode command}
4248 @efindex po-subedit-abort@r{, PO Mode command}
4249 If the translator becomes unsatisfied with her translation or comment,
4250 to the extent she prefers keeping what was existent prior to the
4251 @kbd{@key{RET}} or @kbd{#} command, she may use the command @w{@kbd{C-c C-k}}
4252 (@code{po-subedit-abort}) to merely get rid of edition, while preserving
4253 the original translation or comment. Another way would be for her to exit
4254 normally with @w{@kbd{C-c C-c}}, then type @code{U} once for undoing the
4255 whole effect of last edition.
4257 @efindex C-c C-a@r{, PO Mode command}
4258 @efindex po-subedit-cycle-auxiliary@r{, PO Mode command}
4259 The command @w{@kbd{C-c C-a}} (@code{po-subedit-cycle-auxiliary})
4260 allows for glancing through translations
4261 already achieved in other languages, directly while editing the current
4262 translation. This may be quite convenient when the translator is fluent
4263 at many languages, but of course, only makes sense when such completed
4264 auxiliary PO files are already available to her (@pxref{Auxiliary}).
4266 Functions found on @code{po-subedit-mode-hook}, if any, are executed after
4267 the string has been inserted in the edit buffer.
4269 While editing her translation, the translator should pay attention to not
4270 inserting unwanted @kbd{@key{RET}} (newline) characters at the end of
4271 the translated string if those are not meant to be there, or to removing
4272 such characters when they are required. Since these characters are not
4273 visible in the editing buffer, they are easily introduced by mistake.
4274 To help her, @kbd{@key{RET}} automatically puts the character @code{<}
4275 at the end of the string being edited, but this @code{<} is not really
4276 part of the string. On exiting the editing window with @w{@kbd{C-c C-c}},
4277 PO mode automatically removes such @kbd{<} and all whitespace added after
4278 it. If the translator adds characters after the terminating @code{<}, it
4279 looses its delimiting property and integrally becomes part of the string.
4280 If she removes the delimiting @code{<}, then the edited string is taken
4281 @emph{as is}, with all trailing newlines, even if invisible. Also, if
4282 the translated string ought to end itself with a genuine @code{<}, then
4283 the delimiting @code{<} may not be removed; so the string should appear,
4284 in the editing window, as ending with two @code{<} in a row.
4286 @emindex editing multiple entries
4287 When a translation (or a comment) is being edited, the translator may move
4288 the cursor back into the PO file buffer and freely move to other entries,
4289 browsing at will. If, with an edition pending, the translator wanders in the
4290 PO file buffer, she may decide to start modifying another entry. Each entry
4291 being edited has its own subedit buffer. It is possible to simultaneously
4292 edit the translation @emph{and} the comment of a single entry, or to
4293 edit entries in different PO files, all at once. Typing @kbd{@key{RET}}
4294 on a field already being edited merely resumes that particular edit. Yet,
4295 the translator should better be comfortable at handling many Emacs windows!
4297 @emindex pending subedits
4298 Pending subedits may be completed or aborted in any order, regardless
4299 of how or when they were started. When many subedits are pending and the
4300 translator asks for quitting the PO file (with the @kbd{q} command), subedits
4301 are automatically resumed one at a time, so she may decide for each of them.
4303 @node C Sources Context, Auxiliary, Subedit, PO Mode
4304 @subsection C Sources Context
4305 @emindex consulting program sources
4306 @emindex looking at the source to aid translation
4307 @emindex use the source, Luke
4309 PO mode is particularly powerful when used with PO files
4310 created through GNU @code{gettext} utilities, as those utilities
4311 insert special comments in the PO files they generate.
4312 Some of these special comments relate the PO file entry to
4313 exactly where the untranslated string appears in the program sources.
4315 When the translator gets to an untranslated entry, she is fairly
4316 often faced with an original string which is not as informative as
4317 it normally should be, being succinct, cryptic, or otherwise ambiguous.
4318 Before choosing how to translate the string, she needs to understand
4319 better what the string really means and how tight the translation has
4320 to be. Most of the time, when problems arise, the only way left to make
4321 her judgment is looking at the true program sources from where this
4322 string originated, searching for surrounding comments the programmer
4323 might have put in there, and looking around for helping clues of
4326 Surely, when looking at program sources, the translator will receive
4327 more help if she is a fluent programmer. However, even if she is
4328 not versed in programming and feels a little lost in C code, the
4329 translator should not be shy at taking a look, once in a while.
4330 It is most probable that she will still be able to find some of the
4331 hints she needs. She will learn quickly to not feel uncomfortable
4332 in program code, paying more attention to programmer's comments,
4333 variable and function names (if he dared choosing them well), and
4334 overall organization, than to the program code itself.
4336 @emindex find source fragment for a PO file entry
4337 The following commands are meant to help the translator at getting
4338 program source context for a PO file entry.
4342 @efindex s@r{, PO Mode command}
4343 Resume the display of a program source context, or cycle through them
4344 (@code{po-cycle-source-reference}).
4347 @efindex M-s@r{, PO Mode command}
4348 Display of a program source context selected by menu
4349 (@code{po-select-source-reference}).
4352 @efindex S@r{, PO Mode command}
4353 Add a directory to the search path for source files
4354 (@code{po-consider-source-path}).
4357 @efindex M-S@r{, PO Mode command}
4358 Delete a directory from the search path for source files
4359 (@code{po-ignore-source-path}).
4363 @efindex s@r{, PO Mode command}
4364 @efindex po-cycle-source-reference@r{, PO Mode command}
4365 @efindex M-s@r{, PO Mode command}
4366 @efindex po-select-source-reference@r{, PO Mode command}
4367 The commands @kbd{s} (@code{po-cycle-source-reference}) and @kbd{M-s}
4368 (@code{po-select-source-reference}) both open another window displaying
4369 some source program file, and already positioned in such a way that
4370 it shows an actual use of the string to be translated. By doing
4371 so, the command gives source program context for the string. But if
4372 the entry has no source context references, or if all references
4373 are unresolved along the search path for program sources, then the
4374 command diagnoses this as an error.
4376 Even if @kbd{s} (or @kbd{M-s}) opens a new window, the cursor stays
4377 in the PO file window. If the translator really wants to
4378 get into the program source window, she ought to do it explicitly,
4379 maybe by using command @kbd{O}.
4381 When @kbd{s} is typed for the first time, or for a PO file entry which
4382 is different of the last one used for getting source context, then the
4383 command reacts by giving the first context available for this entry,
4384 if any. If some context has already been recently displayed for the
4385 current PO file entry, and the translator wandered off to do other
4386 things, typing @kbd{s} again will merely resume, in another window,
4387 the context last displayed. In particular, if the translator moved
4388 the cursor away from the context in the source file, the command will
4389 bring the cursor back to the context. By using @kbd{s} many times
4390 in a row, with no other commands intervening, PO mode will cycle to
4391 the next available contexts for this particular entry, getting back
4392 to the first context once the last has been shown.
4394 The command @kbd{M-s} behaves differently. Instead of cycling through
4395 references, it lets the translator choose a particular reference among
4396 many, and displays that reference. It is best used with completion,
4397 if the translator types @kbd{@key{TAB}} immediately after @kbd{M-s}, in
4398 response to the question, she will be offered a menu of all possible
4399 references, as a reminder of which are the acceptable answers.
4400 This command is useful only where there are really many contexts
4401 available for a single string to translate.
4403 @efindex S@r{, PO Mode command}
4404 @efindex po-consider-source-path@r{, PO Mode command}
4405 @efindex M-S@r{, PO Mode command}
4406 @efindex po-ignore-source-path@r{, PO Mode command}
4407 Program source files are usually found relative to where the PO
4408 file stands. As a special provision, when this fails, the file is
4409 also looked for, but relative to the directory immediately above it.
4410 Those two cases take proper care of most PO files. However, it might
4411 happen that a PO file has been moved, or is edited in a different
4412 place than its normal location. When this happens, the translator
4413 should tell PO mode in which directory normally sits the genuine PO
4414 file. Many such directories may be specified, and all together, they
4415 constitute what is called the @dfn{search path} for program sources.
4416 The command @kbd{S} (@code{po-consider-source-path}) is used to interactively
4417 enter a new directory at the front of the search path, and the command
4418 @kbd{M-S} (@code{po-ignore-source-path}) is used to select, with completion,
4419 one of the directories she does not want anymore on the search path.
4421 @node Auxiliary, , C Sources Context, PO Mode
4422 @subsection Consulting Auxiliary PO Files
4423 @emindex consulting translations to other languages
4425 PO mode is able to help the knowledgeable translator, being fluent in
4426 many languages, at taking advantage of translations already achieved
4427 in other languages she just happens to know. It provides these other
4428 language translations as additional context for her own work. Moreover,
4429 it has features to ease the production of translations for many languages
4430 at once, for translators preferring to work in this way.
4432 @cindex auxiliary PO file
4433 @emindex auxiliary PO file
4434 An @dfn{auxiliary} PO file is an existing PO file meant for the same
4435 package the translator is working on, but targeted to a different mother
4436 tongue language. Commands exist for declaring and handling auxiliary
4437 PO files, and also for showing contexts for the entry under work.
4439 Here are the auxiliary file commands available in PO mode.
4443 @efindex a@r{, PO Mode command}
4444 Seek auxiliary files for another translation for the same entry
4445 (@code{po-cycle-auxiliary}).
4448 @efindex C-c C-a@r{, PO Mode command}
4449 Switch to a particular auxiliary file (@code{po-select-auxiliary}).
4452 @efindex A@r{, PO Mode command}
4453 Declare this PO file as an auxiliary file (@code{po-consider-as-auxiliary}).
4456 @efindex M-A@r{, PO Mode command}
4457 Remove this PO file from the list of auxiliary files
4458 (@code{po-ignore-as-auxiliary}).
4462 @efindex A@r{, PO Mode command}
4463 @efindex po-consider-as-auxiliary@r{, PO Mode command}
4464 @efindex M-A@r{, PO Mode command}
4465 @efindex po-ignore-as-auxiliary@r{, PO Mode command}
4466 Command @kbd{A} (@code{po-consider-as-auxiliary}) adds the current
4467 PO file to the list of auxiliary files, while command @kbd{M-A}
4468 (@code{po-ignore-as-auxiliary} just removes it.
4470 @efindex a@r{, PO Mode command}
4471 @efindex po-cycle-auxiliary@r{, PO Mode command}
4472 The command @kbd{a} (@code{po-cycle-auxiliary}) seeks all auxiliary PO
4473 files, round-robin, searching for a translated entry in some other language
4474 having an @code{msgid} field identical as the one for the current entry.
4475 The found PO file, if any, takes the place of the current PO file in
4476 the display (its window gets on top). Before doing so, the current PO
4477 file is also made into an auxiliary file, if not already. So, @kbd{a}
4478 in this newly displayed PO file will seek another PO file, and so on,
4479 so repeating @kbd{a} will eventually yield back the original PO file.
4481 @efindex C-c C-a@r{, PO Mode command}
4482 @efindex po-select-auxiliary@r{, PO Mode command}
4483 The command @kbd{C-c C-a} (@code{po-select-auxiliary}) asks the translator
4484 for her choice of a particular auxiliary file, with completion, and
4485 then switches to that selected PO file. The command also checks if
4486 the selected file has an @code{msgid} field identical as the one for
4487 the current entry, and if yes, this entry becomes current. Otherwise,
4488 the cursor of the selected file is left undisturbed.
4490 For all this to work fully, auxiliary PO files will have to be normalized,
4491 in that way that @code{msgid} fields should be written @emph{exactly}
4492 the same way. It is possible to write @code{msgid} fields in various
4493 ways for representing the same string, different writing would break the
4494 proper behaviour of the auxiliary file commands of PO mode. This is not
4495 expected to be much a problem in practice, as most existing PO files have
4496 their @code{msgid} entries written by the same GNU @code{gettext} tools.
4498 @efindex normalize@r{, PO Mode command}
4499 However, PO files initially created by PO mode itself, while marking
4500 strings in source files, are normalised differently. So are PO
4501 files resulting of the @samp{M-x normalize} command. Until these
4502 discrepancies between PO mode and other GNU @code{gettext} tools get
4503 fully resolved, the translator should stay aware of normalisation issues.
4505 @node Compendium, , PO Mode, Editing
4506 @section Using Translation Compendia
4507 @emindex using translation compendia
4510 A @dfn{compendium} is a special PO file containing a set of
4511 translations recurring in many different packages. The translator can
4512 use gettext tools to build a new compendium, to add entries to her
4513 compendium, and to initialize untranslated entries, or to update
4514 already translated entries, from translations kept in the compendium.
4517 * Creating Compendia:: Merging translations for later use
4518 * Using Compendia:: Using older translations if they fit
4521 @node Creating Compendia, Using Compendia, Compendium, Compendium
4522 @subsection Creating Compendia
4523 @cindex creating compendia
4524 @cindex compendium, creating
4526 Basically every PO file consisting of translated entries only can be
4527 declared as a valid compendium. Often the translator wants to have
4528 special compendia; let's consider two cases: @cite{concatenating PO
4529 files} and @cite{extracting a message subset from a PO file}.
4531 @subsubsection Concatenate PO Files
4533 @cindex concatenating PO files into a compendium
4534 @cindex accumulating translations
4535 To concatenate several valid PO files into one compendium file you can
4536 use @samp{msgcomm} or @samp{msgcat} (the latter preferred):
4539 msgcat -o compendium.po file1.po file2.po
4542 By default, @code{msgcat} will accumulate divergent translations
4543 for the same string. Those occurrences will be marked as @code{fuzzy}
4544 and highly visible decorated; calling @code{msgcat} on
4550 msgid "Report bugs to <%s>.\n"
4551 msgstr "Comunicar `bugs' a <%s>.\n"
4555 and @file{file2.po}:
4560 msgid "Report bugs to <%s>.\n"
4561 msgstr "Comunicar \"bugs\" a <%s>.\n"
4568 #: src/hello.c:200 src/bye.c:100
4570 msgid "Report bugs to <%s>.\n"
4572 "#-#-#-#-# file1.po #-#-#-#-#\n"
4573 "Comunicar `bugs' a <%s>.\n"
4574 "#-#-#-#-# file2.po #-#-#-#-#\n"
4575 "Comunicar \"bugs\" a <%s>.\n"
4579 The translator will have to resolve this ``conflict'' manually; she
4580 has to decide whether the first or the second version is appropriate
4581 (or provide a new translation), to delete the ``marker lines'', and
4582 finally to remove the @code{fuzzy} mark.
4584 If the translator knows in advance the first found translation of a
4585 message is always the best translation she can make use to the
4586 @samp{--use-first} switch:
4589 msgcat --use-first -o compendium.po file1.po file2.po
4592 A good compendium file must not contain @code{fuzzy} or untranslated
4593 entries. If input files are ``dirty'' you must preprocess the input
4594 files or postprocess the result using @samp{msgattrib --translated --no-fuzzy}.
4596 @subsubsection Extract a Message Subset from a PO File
4597 @cindex extracting parts of a PO file into a compendium
4599 Nobody wants to translate the same messages again and again; thus you
4600 may wish to have a compendium file containing @file{getopt.c} messages.
4602 To extract a message subset (e.g., all @file{getopt.c} messages) from an
4603 existing PO file into one compendium file you can use @samp{msggrep}:
4606 msggrep --location src/getopt.c -o compendium.po file.po
4609 @node Using Compendia, , Creating Compendia, Compendium
4610 @subsection Using Compendia
4612 You can use a compendium file to initialize a translation from scratch
4613 or to update an already existing translation.
4615 @subsubsection Initialize a New Translation File
4616 @cindex initialize translations from a compendium
4618 Since a PO file with translations does not exist the translator can
4619 merely use @file{/dev/null} to fake the ``old'' translation file.
4622 msgmerge --compendium compendium.po -o file.po /dev/null file.pot
4625 @subsubsection Update an Existing Translation File
4626 @cindex update translations from a compendium
4628 Concatenate the compendium file(s) and the existing PO, merge the
4629 result with the POT file and remove the obsolete entries (optional,
4630 here done using @samp{msgattrib}):
4633 msgcat --use-first -o update.po compendium1.po compendium2.po file.po
4634 msgmerge update.po file.pot | msgattrib --no-obsolete > file.po
4637 @node Manipulating, Binaries, Editing, Top
4638 @chapter Manipulating PO Files
4639 @cindex manipulating PO files
4641 Sometimes it is necessary to manipulate PO files in a way that is better
4642 performed automatically than by hand. GNU @code{gettext} includes a
4643 complete set of tools for this purpose.
4645 @cindex merging two PO files
4646 When merging two packages into a single package, the resulting POT file
4647 will be the concatenation of the two packages' POT files. Thus the
4648 maintainer must concatenate the two existing package translations into
4649 a single translation catalog, for each language. This is best performed
4650 using @samp{msgcat}. It is then the translators' duty to deal with any
4651 possible conflicts that arose during the merge.
4653 @cindex encoding conversion
4654 When a translator takes over the translation job from another translator,
4655 but she uses a different character encoding in her locale, she will
4656 convert the catalog to her character encoding. This is best done through
4657 the @samp{msgconv} program.
4659 When a maintainer takes a source file with tagged messages from another
4660 package, he should also take the existing translations for this source
4661 file (and not let the translators do the same job twice). One way to do
4662 this is through @samp{msggrep}, another is to create a POT file for
4663 that source file and use @samp{msgmerge}.
4667 When a translator wants to adjust some translation catalog for a special
4668 dialect or orthography --- for example, German as written in Switzerland
4669 versus German as written in Germany --- she needs to apply some text
4670 processing to every message in the catalog. The tool for doing this is
4673 Another use of @code{msgfilter} is to produce approximately the POT file for
4674 which a given PO file was made. This can be done through a filter command
4675 like @samp{msgfilter sed -e d | sed -e '/^# /d'}. Note that the original
4676 POT file may have had different comments and different plural message counts,
4677 that's why it's better to use the original POT file if available.
4679 @cindex checking of translations
4680 When a translator wants to check her translations, for example according
4681 to orthography rules or using a non-interactive spell checker, she can do
4682 so using the @samp{msgexec} program.
4684 @cindex duplicate elimination
4685 When third party tools create PO or POT files, sometimes duplicates cannot
4686 be avoided. But the GNU @code{gettext} tools give an error when they
4687 encounter duplicate msgids in the same file and in the same domain.
4688 To merge duplicates, the @samp{msguniq} program can be used.
4690 @samp{msgcomm} is a more general tool for keeping or throwing away
4691 duplicates, occurring in different files.
4693 @samp{msgcmp} can be used to check whether a translation catalog is
4694 completely translated.
4696 @cindex attributes, manipulating
4697 @samp{msgattrib} can be used to select and extract only the fuzzy
4698 or untranslated messages of a translation catalog.
4700 @samp{msgen} is useful as a first step for preparing English translation
4701 catalogs. It copies each message's msgid to its msgstr.
4703 Finally, for those applications where all these various programs are not
4704 sufficient, a library @samp{libgettextpo} is provided that can be used to
4705 write other specialized programs that process PO files.
4708 * msgcat Invocation:: Invoking the @code{msgcat} Program
4709 * msgconv Invocation:: Invoking the @code{msgconv} Program
4710 * msggrep Invocation:: Invoking the @code{msggrep} Program
4711 * msgfilter Invocation:: Invoking the @code{msgfilter} Program
4712 * msguniq Invocation:: Invoking the @code{msguniq} Program
4713 * msgcomm Invocation:: Invoking the @code{msgcomm} Program
4714 * msgcmp Invocation:: Invoking the @code{msgcmp} Program
4715 * msgattrib Invocation:: Invoking the @code{msgattrib} Program
4716 * msgen Invocation:: Invoking the @code{msgen} Program
4717 * msgexec Invocation:: Invoking the @code{msgexec} Program
4718 * Colorizing:: Highlighting parts of PO files
4719 * libgettextpo:: Writing your own programs that process PO files
4722 @node msgcat Invocation, msgconv Invocation, Manipulating, Manipulating
4723 @section Invoking the @code{msgcat} Program
4725 @include msgcat.texi
4727 @node msgconv Invocation, msggrep Invocation, msgcat Invocation, Manipulating
4728 @section Invoking the @code{msgconv} Program
4730 @include msgconv.texi
4732 @node msggrep Invocation, msgfilter Invocation, msgconv Invocation, Manipulating
4733 @section Invoking the @code{msggrep} Program
4735 @include msggrep.texi
4737 @node msgfilter Invocation, msguniq Invocation, msggrep Invocation, Manipulating
4738 @section Invoking the @code{msgfilter} Program
4740 @include msgfilter.texi
4742 @node msguniq Invocation, msgcomm Invocation, msgfilter Invocation, Manipulating
4743 @section Invoking the @code{msguniq} Program
4745 @include msguniq.texi
4747 @node msgcomm Invocation, msgcmp Invocation, msguniq Invocation, Manipulating
4748 @section Invoking the @code{msgcomm} Program
4750 @include msgcomm.texi
4752 @node msgcmp Invocation, msgattrib Invocation, msgcomm Invocation, Manipulating
4753 @section Invoking the @code{msgcmp} Program
4755 @include msgcmp.texi
4757 @node msgattrib Invocation, msgen Invocation, msgcmp Invocation, Manipulating
4758 @section Invoking the @code{msgattrib} Program
4760 @include msgattrib.texi
4762 @node msgen Invocation, msgexec Invocation, msgattrib Invocation, Manipulating
4763 @section Invoking the @code{msgen} Program
4767 @node msgexec Invocation, Colorizing, msgen Invocation, Manipulating
4768 @section Invoking the @code{msgexec} Program
4770 @include msgexec.texi
4772 @node Colorizing, libgettextpo, msgexec Invocation, Manipulating
4773 @section Highlighting parts of PO files
4775 Translators are usually only interested in seeing the untranslated and
4776 fuzzy messages of a PO file. Also, when a message is set fuzzy because
4777 the msgid changed, they want to see the differences between the previous
4778 msgid and the current one (especially if the msgid is long and only few
4779 words in it have changed). Finally, it's always welcome to highlight the
4780 different sections of a message in a PO file (comments, msgid, msgstr, etc.).
4782 Such highlighting is possible through the @code{msgcat} options
4783 @samp{--color} and @samp{--style}.
4786 * The --color option:: Triggering colorized output
4787 * The TERM variable:: The environment variable @code{TERM}
4788 * The --style option:: The @code{--style} option
4789 * Style rules:: Style rules for PO files
4790 * Customizing less:: Customizing @code{less} for viewing PO files
4793 @node The --color option, The TERM variable, Colorizing, Colorizing
4794 @subsection The @code{--color} option
4796 @opindex --color@r{, @code{msgcat} option}
4797 The @samp{--color=@var{when}} option specifies under which conditions
4798 colorized output should be generated. The @var{when} part can be one of
4804 The output will be colorized.
4808 The output will not be colorized.
4812 The output will be colorized if the output device is a tty, i.e.@: when the
4813 output goes directly to a text screen or terminal emulator window.
4816 The output will be colorized and be in HTML format.
4820 @samp{--color} is equivalent to @samp{--color=yes}. The default is
4821 @samp{--color=auto}.
4823 Thus, a command like @samp{msgcat vi.po} will produce colorized output
4824 when called by itself in a command window. Whereas in a pipe, such as
4825 @samp{msgcat vi.po | less -R}, it will not produce colorized output. To
4826 get colorized output in this situation nevertheless, use the command
4827 @samp{msgcat --color vi.po | less -R}.
4829 The @samp{--color=html} option will produce output that can be viewed in
4830 a browser. This can be useful, for example, for Indic languages,
4831 because the renderic of Indic scripts in browser is usually better than
4832 in terminal emulators.
4834 Note that the output produced with the @code{--color} option is @emph{not}
4835 a valid PO file in itself. It contains additional terminal-specific escape
4836 sequences or HTML tags. A PO file reader will give a syntax error when
4837 confronted with such content. Except for the @samp{--color=html} case,
4838 you therefore normally don't need to save output produced with the
4839 @code{--color} option in a file.
4841 @node The TERM variable, The --style option, The --color option, Colorizing
4842 @subsection The environment variable @code{TERM}
4844 @vindex TERM@r{, environment variable}
4845 The environment variable @code{TERM} contains a identifier for the text
4846 window's capabilities. You can get a detailed list of these cababilities
4847 by using the @samp{infocmp} command, using @samp{man 5 terminfo} as a
4850 When producing text with embedded color directives, @code{msgcat} looks
4851 at the @code{TERM} variable. Text windows today typically support at least
4852 8 colors. Often, however, the text window supports 16 or more colors,
4853 even though the @code{TERM} variable is set to a identifier denoting only
4854 8 supported colors. It can be worth setting the @code{TERM} variable to
4855 a different value in these cases:
4859 @code{xterm} is in most cases built with support for 16 colors. It can also
4860 be built with support for 88 or 256 colors (but not both). You can try to
4861 set @code{TERM} to either @code{xterm-16color}, @code{xterm-88color}, or
4862 @code{xterm-256color}.
4865 @code{rxvt} is often built with support for 16 colors. You can try to set
4866 @code{TERM} to @code{rxvt-16color}.
4869 @code{konsole} too is often built with support for 16 colors. You can try to
4870 set @code{TERM} to @code{konsole-16color} or @code{xterm-16color}.
4873 After setting @code{TERM}, you can verify it by invoking
4874 @samp{msgcat --color=test} and seeing whether the output looks like a
4875 reasonable color map.
4877 @node The --style option, Style rules, The TERM variable, Colorizing
4878 @subsection The @code{--style} option
4880 @opindex --style@r{, @code{msgcat} option}
4881 The @samp{--style=@var{style_file}} option specifies the style file to use
4882 when colorizing. It has an effect only when the @code{--color} option is
4885 @vindex PO_STYLE@r{, environment variable}
4886 If the @code{--style} option is not specified, the environment variable
4887 @code{PO_STYLE} is considered. It is meant to point to the user's
4888 preferred style for PO files.
4890 The default style file is @file{$prefix/share/gettext/styles/po-default.css},
4891 where @code{$prefix} is the installation location.
4893 A few style files are predefined:
4896 This style imitates the look used by vim 7.
4898 @item po-emacs-x.css
4899 This style imitates the look used by GNU Emacs 21 and 22 in an X11 window.
4901 @item po-emacs-xterm.css
4902 @itemx po-emacs-xterm16.css
4903 @itemx po-emacs-xterm256.css
4904 This style imitates the look used by GNU Emacs 22 in a terminal of type
4905 @samp{xterm} (8 colors) or @samp{xterm-16color} (16 colors) or
4906 @samp{xterm-256color} (256 colors), respectively.
4910 You can use these styles without specifying a directory. They are actually
4911 located in @file{$prefix/share/gettext/styles/}, where @code{$prefix} is the
4912 installation location.
4914 You can also design your own styles. This is described in the next section.
4917 @node Style rules, Customizing less, The --style option, Colorizing
4918 @subsection Style rules for PO files
4920 The same style file can be used for styling of a PO file, for terminal
4921 output and for HTML output. It is written in CSS (Cascading Style Sheet)
4922 syntax. See @url{http://www.w3.org/TR/css2/cover.html} for a formal
4923 definition of CSS. Many HTML authoring tutorials also contain explanations
4926 In the case of HTML output, the style file is embedded in the HTML output.
4927 In the case of text output, the style file is interpreted by the
4928 @code{msgcat} program. This means, in particular, that when
4929 @code{@@import} is used with relative file names, the file names are
4933 relative to the resulting HTML file, in the case of HTML output,
4936 relative to the style sheet containing the @code{@@import}, in the case of
4937 text output. (Actually, @code{@@import}s are not yet supported in this case,
4938 due to a limitation in @code{libcroco}.)
4941 CSS rules are built up from selectors and declarations. The declarations
4942 specify graphical properties; the selectors specify specify when they apply.
4944 In PO files, the following simple selectors (based on "CSS classes", see
4945 the CSS2 spec, section 5.8.3) are supported.
4949 Selectors that apply to entire messages:
4953 This matches the header entry of a PO file.
4956 This matches a translated message.
4959 This matches an untranslated message (i.e.@: a message with empty translation).
4962 This matches a fuzzy message (i.e.@: a message which has a translation that
4963 needs review by the translator).
4966 This matches an obsolete message (i.e.@: a message that was translated but is
4967 not needed by the current POT file any more).
4971 Selectors that apply to parts of a message in PO syntax. Recall the general
4972 structure of a message in PO syntax:
4976 # @var{translator-comments}
4977 #. @var{extracted-comments}
4978 #: @var{reference}@dots{}
4979 #, @var{flag}@dots{}
4980 #| msgid @var{previous-untranslated-string}
4981 msgid @var{untranslated-string}
4982 msgstr @var{translated-string}
4987 This matches all comments (translator comments, extracted comments,
4988 source file reference comments, flag comments, previous message comments,
4989 as well as the entire obsolete messages).
4991 @item .translator-comment
4992 This matches the translator comments.
4994 @item .extracted-comment
4995 This matches the extracted comments, i.e.@: the comments placed by the
4996 programmer at the attention of the translator.
4998 @item .reference-comment
4999 This matches the source file reference comments (entire lines).
5002 This matches the individual source file references inside the source file
5003 reference comment lines.
5006 This matches the flag comment lines (entire lines).
5009 This matches the individual flags inside flag comment lines.
5012 This matches the `fuzzy' flag inside flag comment lines.
5014 @item .previous-comment
5015 This matches the comments containing the previous untranslated string (entire
5019 This matches the previous untranslated string including the string delimiters,
5020 the associated keywords (@code{msgid} etc.) and the spaces between them.
5023 This matches the untranslated string including the string delimiters,
5024 the associated keywords (@code{msgid} etc.) and the spaces between them.
5027 This matches the translated string including the string delimiters,
5028 the associated keywords (@code{msgstr} etc.) and the spaces between them.
5031 This matches the keywords (@code{msgid}, @code{msgstr}, etc.).
5034 This matches strings, including the string delimiters (double quotes).
5038 Selectors that apply to parts of strings:
5042 This matches the entire contents of a string (excluding the string delimiters,
5043 i.e.@: the double quotes).
5045 @item .escape-sequence
5046 This matches an escape sequence (starting with a backslash).
5048 @item .format-directive
5049 This matches a format string directive (starting with a @samp{%} sign in the
5050 case of most programming languages, with a @samp{@{} in the case of
5051 @code{java-format} and @code{csharp-format}, with a @samp{~} in the case of
5052 @code{lisp-format} and @code{scheme-format}, or with @samp{$} in the case of
5055 @item .invalid-format-directive
5056 This matches an invalid format string directive.
5059 In an untranslated string, this matches a part of the string that was not
5060 present in the previous untranslated string. (Not yet implemented in this
5064 In an untranslated string or in a previous untranslated string, this matches
5065 a part of the string that is changed or replaced. (Not yet implemented in
5069 In a previous untranslated string, this matches a part of the string that
5070 is not present in the current untranslated string. (Not yet implemented in
5075 These selectors can be combined to hierarchical selectors. For example,
5078 .msgstr .invalid-format-directive @{ color: red; @}
5082 will highlight the invalid format directives in the translated strings.
5084 In text mode, pseudo-classes (CSS2 spec, section 5.11) and pseudo-elements
5085 (CSS2 spec, section 5.12) are not supported.
5087 The declarations in HTML mode are not limited; any graphical attribute
5088 supported by the browsers can be used.
5090 The declarations in text mode are limited to the following properties. Other
5091 properties will be silently ignored.
5094 @item @code{color} (CSS2 spec, section 14.1)
5095 @itemx @code{background-color} (CSS2 spec, section 14.2.1)
5096 These properties is supported. Colors will be adjusted to match the terminal's
5097 capabilities. Note that many terminals support only 8 colors.
5099 @item @code{font-weight} (CSS2 spec, section 15.2.3)
5100 This property is supported, but most terminals can only render two different
5101 weights: @code{normal} and @code{bold}. Values >= 600 are rendered as
5104 @item @code{font-style} (CSS2 spec, section 15.2.3)
5105 This property is supported. The values @code{italic} and @code{oblique} are
5106 rendered the same way.
5108 @item @code{text-decoration} (CSS2 spec, section 16.3.1)
5109 This property is supported, limited to the values @code{none} and
5113 @node Customizing less, , Style rules, Colorizing
5114 @subsection Customizing @code{less} for viewing PO files
5116 The @samp{less} program is a popular text file browser for use in a text
5117 screen or terminal emulator. It also supports text with embedded escape
5118 sequences for colors and text decorations.
5120 You can use @code{less} to view a PO file like this (assuming an UTF-8
5124 msgcat --to-code=UTF-8 --color xyz.po | less -R
5127 You can simplify this to this simple command:
5134 after these three preparations:
5138 Add the options @samp{-R} and @samp{-f} to the @code{LESS} environment
5139 variable. In sh shells:
5141 $ LESS="$LESS -R -f"
5146 If your system does not already have the @file{lessopen.sh} and
5147 @file{lessclose.sh} scripts, create them and set the @code{LESSOPEN} and
5148 @code{LESSCLOSE} environment variables, as indicated in the manual page
5152 Add to @file{lessopen.sh} a piece of script that recognizes PO files
5153 through their file extension and invokes @code{msgcat} on them, producing
5154 a temporary file. Like this:
5159 tmpfile=`mktemp "$@{TMPDIR-/tmp@}/less.XXXXXX"`
5160 msgcat --to-code=UTF-8 --color "$1" > "$tmpfile"
5168 @node libgettextpo, , Colorizing, Manipulating
5169 @section Writing your own programs that process PO files
5171 For the tasks for which a combination of @samp{msgattrib}, @samp{msgcat} etc.
5172 is not sufficient, a set of C functions is provided in a library, to make it
5173 possible to process PO files in your own programs. When you use this library,
5174 you don't need to write routines to parse the PO file; instead, you retrieve
5175 a pointer in memory to each of messages contained in the PO file. Functions
5176 for writing PO files are not provided at this time.
5178 The functions are declared in the header file @samp{<gettext-po.h>}, and are
5179 defined in a library called @samp{libgettextpo}.
5181 @deftp {Data Type} po_file_t
5182 This is a pointer type that refers to the contents of a PO file, after it has
5183 been read into memory.
5186 @deftp {Data Type} po_message_iterator_t
5187 This is a pointer type that refers to an iterator that produces a sequence of
5191 @deftp {Data Type} po_message_t
5192 This is a pointer type that refers to a message of a PO file, including its
5196 @deftypefun po_file_t po_file_read (const char *@var{filename})
5197 The @code{po_file_read} function reads a PO file into memory. The file name
5198 is given as argument. The return value is a handle to the PO file's contents,
5199 valid until @code{po_file_free} is called on it. In case of error, the return
5200 value is @code{NULL}, and @code{errno} is set.
5203 @deftypefun void po_file_free (po_file_t @var{file})
5204 The @code{po_file_free} function frees a PO file's contents from memory,
5205 including all messages that are only implicitly accessible through iterators.
5208 @deftypefun {const char * const *} po_file_domains (po_file_t @var{file})
5209 The @code{po_file_domains} function returns the domains for which the given
5210 PO file has messages. The return value is a @code{NULL} terminated array
5211 which is valid as long as the @var{file} handle is valid. For PO files which
5212 contain no @samp{domain} directive, the return value contains only one domain,
5213 namely the default domain @code{"messages"}.
5216 @deftypefun po_message_iterator_t po_message_iterator (po_file_t @var{file}, const char *@var{domain})
5217 The @code{po_message_iterator} returns an iterator that will produce the
5218 messages of @var{file} that belong to the given @var{domain}. If @var{domain}
5219 is @code{NULL}, the default domain is used instead. To list the messages,
5220 use the function @code{po_next_message} repeatedly.
5223 @deftypefun void po_message_iterator_free (po_message_iterator_t @var{iterator})
5224 The @code{po_message_iterator_free} function frees an iterator previously
5225 allocated through the @code{po_message_iterator} function.
5228 @deftypefun po_message_t po_next_message (po_message_iterator_t @var{iterator})
5229 The @code{po_next_message} function returns the next message from
5230 @var{iterator} and advances the iterator. It returns @code{NULL} when the
5231 iterator has reached the end of its message list.
5234 The following functions returns details of a @code{po_message_t}. Recall
5235 that the results are valid as long as the @var{file} handle is valid.
5237 @deftypefun {const char *} po_message_msgid (po_message_t @var{message})
5238 The @code{po_message_msgid} function returns the @code{msgid} (untranslated
5239 English string) of a message. This is guaranteed to be non-@code{NULL}.
5242 @deftypefun {const char *} po_message_msgid_plural (po_message_t @var{message})
5243 The @code{po_message_msgid_plural} function returns the @code{msgid_plural}
5244 (untranslated English plural string) of a message with plurals, or @code{NULL}
5245 for a message without plural.
5248 @deftypefun {const char *} po_message_msgstr (po_message_t @var{message})
5249 The @code{po_message_msgstr} function returns the @code{msgstr} (translation)
5250 of a message. For an untranslated message, the return value is an empty
5254 @deftypefun {const char *} po_message_msgstr_plural (po_message_t @var{message}, int @var{index})
5255 The @code{po_message_msgstr_plural} function returns the
5256 @code{msgstr[@var{index}]} of a message with plurals, or @code{NULL} when
5257 the @var{index} is out of range or for a message without plural.
5260 Here is an example code how these functions can be used.
5263 const char *filename = @dots{};
5264 po_file_t file = po_file_read (filename);
5267 error (EXIT_FAILURE, errno, "couldn't open the PO file %s", filename);
5269 const char * const *domains = po_file_domains (file);
5270 const char * const *domainp;
5272 for (domainp = domains; *domainp; domainp++)
5274 const char *domain = *domainp;
5275 po_message_iterator_t iterator = po_message_iterator (file, domain);
5279 po_message_t *message = po_next_message (iterator);
5281 if (message == NULL)
5284 const char *msgid = po_message_msgid (message);
5285 const char *msgstr = po_message_msgstr (message);
5290 po_message_iterator_free (iterator);
5293 po_file_free (file);
5296 @node Binaries, Programmers, Manipulating, Top
5297 @chapter Producing Binary MO Files
5302 * msgfmt Invocation:: Invoking the @code{msgfmt} Program
5303 * msgunfmt Invocation:: Invoking the @code{msgunfmt} Program
5304 * MO Files:: The Format of GNU MO Files
5307 @node msgfmt Invocation, msgunfmt Invocation, Binaries, Binaries
5308 @section Invoking the @code{msgfmt} Program
5310 @include msgfmt.texi
5312 @node msgunfmt Invocation, MO Files, msgfmt Invocation, Binaries
5313 @section Invoking the @code{msgunfmt} Program
5315 @include msgunfmt.texi
5317 @node MO Files, , msgunfmt Invocation, Binaries
5318 @section The Format of GNU MO Files
5319 @cindex MO file's format
5320 @cindex file format, @file{.mo}
5322 The format of the generated MO files is best described by a picture,
5323 which appears below.
5325 @cindex magic signature of MO files
5326 The first two words serve the identification of the file. The magic
5327 number will always signal GNU MO files. The number is stored in the
5328 byte order of the generating machine, so the magic number really is
5329 two numbers: @code{0x950412de} and @code{0xde120495}.
5331 The second word describes the current revision of the file format,
5332 composed of a major and a minor revision number. The revision numbers
5333 ensure that the readers of MO files can distinguish new formats from
5334 old ones and handle their contents, as far as possible. For now the
5335 major revision is 0 or 1, and the minor revision is also 0 or 1. More
5336 revisions might be added in the future. A program seeing an unexpected
5337 major revision number should stop reading the MO file entirely; whereas
5338 an unexpected minor revision number means that the file can be read but
5339 will not reveal its full contents, when parsed by a program that
5340 supports only smaller minor revision numbers.
5343 separate from the magic number, instead of using different magic
5344 numbers for different formats, mainly because @file{/etc/magic} is
5347 Follow a number of pointers to later tables in the file, allowing
5348 for the extension of the prefix part of MO files without having to
5349 recompile programs reading them. This might become useful for later
5350 inserting a few flag bits, indication about the charset used, new
5351 tables, or other things.
5353 Then, at offset @var{O} and offset @var{T} in the picture, two tables
5354 of string descriptors can be found. In both tables, each string
5355 descriptor uses two 32 bits integers, one for the string length,
5356 another for the offset of the string in the MO file, counting in bytes
5357 from the start of the file. The first table contains descriptors
5358 for the original strings, and is sorted so the original strings
5359 are in increasing lexicographical order. The second table contains
5360 descriptors for the translated strings, and is parallel to the first
5361 table: to find the corresponding translation one has to access the
5362 array slot in the second array with the same index.
5364 Having the original strings sorted enables the use of simple binary
5365 search, for when the MO file does not contain an hashing table, or
5366 for when it is not practical to use the hashing table provided in
5367 the MO file. This also has another advantage, as the empty string
5368 in a PO file GNU @code{gettext} is usually @emph{translated} into
5369 some system information attached to that particular MO file, and the
5370 empty string necessarily becomes the first in both the original and
5371 translated tables, making the system information very easy to find.
5373 @cindex hash table, inside MO files
5374 The size @var{S} of the hash table can be zero. In this case, the
5375 hash table itself is not contained in the MO file. Some people might
5376 prefer this because a precomputed hashing table takes disk space, and
5377 does not win @emph{that} much speed. The hash table contains indices
5378 to the sorted array of strings in the MO file. Conflict resolution is
5379 done by double hashing. The precise hashing algorithm used is fairly
5380 dependent on GNU @code{gettext} code, and is not documented here.
5382 As for the strings themselves, they follow the hash file, and each
5383 is terminated with a @key{NUL}, and this @key{NUL} is not counted in
5384 the length which appears in the string descriptor. The @code{msgfmt}
5385 program has an option selecting the alignment for MO file strings.
5386 With this option, each string is separately aligned so it starts at
5387 an offset which is a multiple of the alignment value. On some RISC
5388 machines, a correct alignment will speed things up.
5390 @cindex context, in MO files
5391 Contexts are stored by storing the concatenation of the context, a
5392 @key{EOT} byte, and the original string, instead of the original string.
5394 @cindex plural forms, in MO files
5395 Plural forms are stored by letting the plural of the original string
5396 follow the singular of the original string, separated through a
5397 @key{NUL} byte. The length which appears in the string descriptor
5398 includes both. However, only the singular of the original string
5399 takes part in the hash table lookup. The plural variants of the
5400 translation are all stored consecutively, separated through a
5401 @key{NUL} byte. Here also, the length in the string descriptor
5402 includes all of them.
5404 Nothing prevents a MO file from having embedded @key{NUL}s in strings.
5405 However, the program interface currently used already presumes
5406 that strings are @key{NUL} terminated, so embedded @key{NUL}s are
5407 somewhat useless. But the MO file format is general enough so other
5408 interfaces would be later possible, if for example, we ever want to
5409 implement wide characters right in MO files, where @key{NUL} bytes may
5410 accidentally appear. (No, we don't want to have wide characters in MO
5411 files. They would make the file unnecessarily large, and the
5412 @samp{wchar_t} type being platform dependent, MO files would be
5413 platform dependent as well.)
5415 This particular issue has been strongly debated in the GNU
5416 @code{gettext} development forum, and it is expectable that MO file
5417 format will evolve or change over time. It is even possible that many
5418 formats may later be supported concurrently. But surely, we have to
5419 start somewhere, and the MO file format described here is a good start.
5420 Nothing is cast in concrete, and the format may later evolve fairly
5421 easily, so we should feel comfortable with the current approach.
5426 +------------------------------------------+
5427 0 | magic number = 0x950412de |
5429 4 | file format revision = 0 |
5431 8 | number of strings | == N
5433 12 | offset of table with original strings | == O
5435 16 | offset of table with translation strings | == T
5437 20 | size of hashing table | == S
5439 24 | offset of hashing table | == H
5442 . (possibly more entries later) .
5445 O | length & offset 0th string ----------------.
5446 O + 8 | length & offset 1st string ------------------.
5448 O + ((N-1)*8)| length & offset (N-1)th string | | |
5450 T | length & offset 0th translation ---------------.
5451 T + 8 | length & offset 1st translation -----------------.
5453 T + ((N-1)*8)| length & offset (N-1)th translation | | | | |
5455 H | start hash table | | | | |
5457 H + S * 4 | end hash table | | | | |
5459 | NUL terminated 0th string <----------------' | | |
5461 | NUL terminated 1st string <------------------' | |
5465 | NUL terminated 0th translation <---------------' |
5467 | NUL terminated 1st translation <-----------------'
5471 +------------------------------------------+
5475 @node Programmers, Translators, Binaries, Top
5476 @chapter The Programmer's View
5478 @c FIXME: Reorganize whole chapter.
5480 One aim of the current message catalog implementation provided by
5481 GNU @code{gettext} was to use the system's message catalog handling, if the
5482 installer wishes to do so. So we perhaps should first take a look at
5483 the solutions we know about. The people in the POSIX committee did not
5484 manage to agree on one of the semi-official standards which we'll
5485 describe below. In fact they couldn't agree on anything, so they decided
5486 only to include an example of an interface. The major Unix vendors
5487 are split in the usage of the two most important specifications: X/Open's
5488 catgets vs. Uniforum's gettext interface. We'll describe them both and
5489 later explain our solution of this dilemma.
5492 * catgets:: About @code{catgets}
5493 * gettext:: About @code{gettext}
5494 * Comparison:: Comparing the two interfaces
5495 * Using libintl.a:: Using libintl.a in own programs
5496 * gettext grok:: Being a @code{gettext} grok
5497 * Temp Programmers:: Temporary Notes for the Programmers Chapter
5500 @node catgets, gettext, Programmers, Programmers
5501 @section About @code{catgets}
5502 @cindex @code{catgets}, X/Open specification
5504 The @code{catgets} implementation is defined in the X/Open Portability
5505 Guide, Volume 3, XSI Supplementary Definitions, Chapter 5. But the
5506 process of creating this standard seemed to be too slow for some of
5507 the Unix vendors so they created their implementations on preliminary
5508 versions of the standard. Of course this leads again to problems while
5509 writing platform independent programs: even the usage of @code{catgets}
5510 does not guarantee a unique interface.
5512 Another, personal comment on this that only a bunch of committee members
5513 could have made this interface. They never really tried to program
5514 using this interface. It is a fast, memory-saving implementation, an
5515 user can happily live with it. But programmers hate it (at least I and
5516 some others do@dots{})
5518 But we must not forget one point: after all the trouble with transferring
5519 the rights on Unix(tm) they at last came to X/Open, the very same who
5520 published this specification. This leads me to making the prediction
5521 that this interface will be in future Unix standards (e.g.@: Spec1170) and
5522 therefore part of all Unix implementation (implementations, which are
5523 @emph{allowed} to wear this name).
5526 * Interface to catgets:: The interface
5527 * Problems with catgets:: Problems with the @code{catgets} interface?!
5530 @node Interface to catgets, Problems with catgets, catgets, catgets
5531 @subsection The Interface
5532 @cindex interface to @code{catgets}
5534 The interface to the @code{catgets} implementation consists of three
5535 functions which correspond to those used in file access: @code{catopen}
5536 to open the catalog for using, @code{catgets} for accessing the message
5537 tables, and @code{catclose} for closing after work is done. Prototypes
5538 for the functions and the needed definitions are in the
5539 @code{<nl_types.h>} header file.
5541 @cindex @code{catopen}, a @code{catgets} function
5542 @code{catopen} is used like in this:
5545 nl_catd catd = catopen ("catalog_name", 0);
5548 The function takes as the argument the name of the catalog. This usual
5549 refers to the name of the program or the package. The second parameter
5550 is not further specified in the standard. I don't even know whether it
5551 is implemented consistently among various systems. So the common advice
5552 is to use @code{0} as the value. The return value is a handle to the
5553 message catalog, equivalent to handles to file returned by @code{open}.
5555 @cindex @code{catgets}, a @code{catgets} function
5556 This handle is of course used in the @code{catgets} function which can
5560 char *translation = catgets (catd, set_no, msg_id, "original string");
5563 The first parameter is this catalog descriptor. The second parameter
5564 specifies the set of messages in this catalog, in which the message
5565 described by @code{msg_id} is obtained. @code{catgets} therefore uses a
5566 three-stage addressing:
5569 catalog name @result{} set number @result{} message ID @result{} translation
5572 @c Anybody else loving Haskell??? :-) -- Uli
5574 The fourth argument is not used to address the translation. It is given
5575 as a default value in case when one of the addressing stages fail. One
5576 important thing to remember is that although the return type of catgets
5577 is @code{char *} the resulting string @emph{must not} be changed. It
5578 should better be @code{const char *}, but the standard is published in
5579 1988, one year before ANSI C.
5582 @cindex @code{catclose}, a @code{catgets} function
5583 The last of these functions is used and behaves as expected:
5589 After this no @code{catgets} call using the descriptor is legal anymore.
5591 @node Problems with catgets, , Interface to catgets, catgets
5592 @subsection Problems with the @code{catgets} Interface?!
5593 @cindex problems with @code{catgets} interface
5595 Now that this description seemed to be really easy --- where are the
5596 problems we speak of? In fact the interface could be used in a
5597 reasonable way, but constructing the message catalogs is a pain. The
5598 reason for this lies in the third argument of @code{catgets}: the unique
5599 message ID. This has to be a numeric value for all messages in a single
5600 set. Perhaps you could imagine the problems keeping such a list while
5601 changing the source code. Add a new message here, remove one there. Of
5602 course there have been developed a lot of tools helping to organize this
5603 chaos but one as the other fails in one aspect or the other. We don't
5604 want to say that the other approach has no problems but they are far
5605 more easy to manage.
5607 @node gettext, Comparison, catgets, Programmers
5608 @section About @code{gettext}
5609 @cindex @code{gettext}, a programmer's view
5611 The definition of the @code{gettext} interface comes from a Uniforum
5612 proposal. It was submitted there by Sun, who had implemented the
5613 @code{gettext} function in SunOS 4, around 1990. Nowadays, the
5614 @code{gettext} interface is specified by the OpenI18N standard.
5616 The main point about this solution is that it does not follow the
5617 method of normal file handling (open-use-close) and that it does not
5618 burden the programmer with so many tasks, especially the unique key handling.
5619 Of course here also a unique key is needed, but this key is the message
5620 itself (how long or short it is). See @ref{Comparison} for a more
5621 detailed comparison of the two methods.
5623 The following section contains a rather detailed description of the
5624 interface. We make it that detailed because this is the interface
5625 we chose for the GNU @code{gettext} Library. Programmers interested
5626 in using this library will be interested in this description.
5629 * Interface to gettext:: The interface
5630 * Ambiguities:: Solving ambiguities
5631 * Locating Catalogs:: Locating message catalog files
5632 * Charset conversion:: How to request conversion to Unicode
5633 * Contexts:: Solving ambiguities in GUI programs
5634 * Plural forms:: Additional functions for handling plurals
5635 * Optimized gettext:: Optimization of the *gettext functions
5638 @node Interface to gettext, Ambiguities, gettext, gettext
5639 @subsection The Interface
5640 @cindex @code{gettext} interface
5642 The minimal functionality an interface must have is a) to select a
5643 domain the strings are coming from (a single domain for all programs is
5644 not reasonable because its construction and maintenance is difficult,
5645 perhaps impossible) and b) to access a string in a selected domain.
5647 This is principally the description of the @code{gettext} interface. It
5648 has a global domain which unqualified usages reference. Of course this
5649 domain is selectable by the user.
5652 char *textdomain (const char *domain_name);
5655 This provides the possibility to change or query the current status of
5656 the current global domain of the @code{LC_MESSAGE} category. The
5657 argument is a null-terminated string, whose characters must be legal in
5658 the use in filenames. If the @var{domain_name} argument is @code{NULL},
5659 the function returns the current value. If no value has been set
5660 before, the name of the default domain is returned: @emph{messages}.
5661 Please note that although the return value of @code{textdomain} is of
5662 type @code{char *} no changing is allowed. It is also important to know
5663 that no checks of the availability are made. If the name is not
5664 available you will see this by the fact that no translations are provided.
5667 To use a domain set by @code{textdomain} the function
5670 char *gettext (const char *msgid);
5674 is to be used. This is the simplest reasonable form one can imagine.
5675 The translation of the string @var{msgid} is returned if it is available
5676 in the current domain. If it is not available, the argument itself is
5677 returned. If the argument is @code{NULL} the result is undefined.
5679 One thing which should come into mind is that no explicit dependency to
5680 the used domain is given. The current value of the domain is used.
5681 If this changes between two
5682 executions of the same @code{gettext} call in the program, both calls
5683 reference a different message catalog.
5685 For the easiest case, which is normally used in internationalized
5686 packages, once at the beginning of execution a call to @code{textdomain}
5687 is issued, setting the domain to a unique name, normally the package
5688 name. In the following code all strings which have to be translated are
5689 filtered through the gettext function. That's all, the package speaks
5692 @node Ambiguities, Locating Catalogs, Interface to gettext, gettext
5693 @subsection Solving Ambiguities
5694 @cindex several domains
5695 @cindex domain ambiguities
5696 @cindex large package
5698 While this single name domain works well for most applications there
5699 might be the need to get translations from more than one domain. Of
5700 course one could switch between different domains with calls to
5701 @code{textdomain}, but this is really not convenient nor is it fast. A
5702 possible situation could be one case subject to discussion during this
5704 error messages of functions in the set of common used functions should
5705 go into a separate domain @code{error}. By this mean we would only need
5706 to translate them once.
5707 Another case are messages from a library, as these @emph{have} to be
5708 independent of the current domain set by the application.
5711 For this reasons there are two more functions to retrieve strings:
5714 char *dgettext (const char *domain_name, const char *msgid);
5715 char *dcgettext (const char *domain_name, const char *msgid,
5719 Both take an additional argument at the first place, which corresponds
5720 to the argument of @code{textdomain}. The third argument of
5721 @code{dcgettext} allows to use another locale category but @code{LC_MESSAGES}.
5722 But I really don't know where this can be useful. If the
5723 @var{domain_name} is @code{NULL} or @var{category} has an value beside
5724 the known ones, the result is undefined. It should also be noted that
5725 this function is not part of the second known implementation of this
5726 function family, the one found in Solaris.
5728 A second ambiguity can arise by the fact, that perhaps more than one
5729 domain has the same name. This can be solved by specifying where the
5730 needed message catalog files can be found.
5733 char *bindtextdomain (const char *domain_name,
5734 const char *dir_name);
5737 Calling this function binds the given domain to a file in the specified
5738 directory (how this file is determined follows below). Especially a
5739 file in the systems default place is not favored against the specified
5740 file anymore (as it would be by solely using @code{textdomain}). A
5741 @code{NULL} pointer for the @var{dir_name} parameter returns the binding
5742 associated with @var{domain_name}. If @var{domain_name} itself is
5743 @code{NULL} nothing happens and a @code{NULL} pointer is returned. Here
5744 again as for all the other functions is true that none of the return
5745 value must be changed!
5747 It is important to remember that relative path names for the
5748 @var{dir_name} parameter can be trouble. Since the path is always
5749 computed relative to the current directory different results will be
5750 achieved when the program executes a @code{chdir} command. Relative
5751 paths should always be avoided to avoid dependencies and
5754 @node Locating Catalogs, Charset conversion, Ambiguities, gettext
5755 @subsection Locating Message Catalog Files
5756 @cindex message catalog files location
5758 Because many different languages for many different packages have to be
5759 stored we need some way to add these information to file message catalog
5760 files. The way usually used in Unix environments is have this encoding
5761 in the file name. This is also done here. The directory name given in
5762 @code{bindtextdomain}s second argument (or the default directory),
5763 followed by the name of the locale, the locale category, and the domain name
5767 @var{dir_name}/@var{locale}/LC_@var{category}/@var{domain_name}.mo
5770 The default value for @var{dir_name} is system specific. For the GNU
5771 library, and for packages adhering to its conventions, it's:
5773 /usr/local/share/locale
5777 @var{locale} is the name of the locale category which is designated by
5778 @code{LC_@var{category}}. For @code{gettext} and @code{dgettext} this
5779 @code{LC_@var{category}} is always @code{LC_MESSAGES}.@footnote{Some
5780 system, e.g.@: mingw, don't have @code{LC_MESSAGES}. Here we use a more or
5781 less arbitrary value for it, namely 1729, the smallest positive integer
5782 which can be represented in two different ways as the sum of two cubes.}
5783 The name of the locale category is determined through
5784 @code{setlocale (LC_@var{category}, NULL)}.
5785 @footnote{When the system does not support @code{setlocale} its behavior
5786 in setting the locale values is simulated by looking at the environment
5788 When using the function @code{dcgettext}, you can specify the locale category
5789 through the third argument.
5791 @node Charset conversion, Contexts, Locating Catalogs, gettext
5792 @subsection How to specify the output character set @code{gettext} uses
5793 @cindex charset conversion at runtime
5794 @cindex encoding conversion at runtime
5796 @code{gettext} not only looks up a translation in a message catalog. It
5797 also converts the translation on the fly to the desired output character
5798 set. This is useful if the user is working in a different character set
5799 than the translator who created the message catalog, because it avoids
5800 distributing variants of message catalogs which differ only in the
5803 The output character set is, by default, the value of @code{nl_langinfo
5804 (CODESET)}, which depends on the @code{LC_CTYPE} part of the current
5805 locale. But programs which store strings in a locale independent way
5806 (e.g.@: UTF-8) can request that @code{gettext} and related functions
5807 return the translations in that encoding, by use of the
5808 @code{bind_textdomain_codeset} function.
5810 Note that the @var{msgid} argument to @code{gettext} is not subject to
5811 character set conversion. Also, when @code{gettext} does not find a
5812 translation for @var{msgid}, it returns @var{msgid} unchanged --
5813 independently of the current output character set. It is therefore
5814 recommended that all @var{msgid}s be US-ASCII strings.
5816 @deftypefun {char *} bind_textdomain_codeset (const char *@var{domainname}, const char *@var{codeset})
5817 The @code{bind_textdomain_codeset} function can be used to specify the
5818 output character set for message catalogs for domain @var{domainname}.
5819 The @var{codeset} argument must be a valid codeset name which can be used
5820 for the @code{iconv_open} function, or a null pointer.
5822 If the @var{codeset} parameter is the null pointer,
5823 @code{bind_textdomain_codeset} returns the currently selected codeset
5824 for the domain with the name @var{domainname}. It returns @code{NULL} if
5825 no codeset has yet been selected.
5827 The @code{bind_textdomain_codeset} function can be used several times.
5828 If used multiple times with the same @var{domainname} argument, the
5829 later call overrides the settings made by the earlier one.
5831 The @code{bind_textdomain_codeset} function returns a pointer to a
5832 string containing the name of the selected codeset. The string is
5833 allocated internally in the function and must not be changed by the
5834 user. If the system went out of core during the execution of
5835 @code{bind_textdomain_codeset}, the return value is @code{NULL} and the
5836 global variable @var{errno} is set accordingly.
5839 @node Contexts, Plural forms, Charset conversion, gettext
5840 @subsection Using contexts for solving ambiguities
5842 @cindex GUI programs
5843 @cindex translating menu entries
5844 @cindex menu entries
5846 One place where the @code{gettext} functions, if used normally, have big
5847 problems is within programs with graphical user interfaces (GUIs). The
5848 problem is that many of the strings which have to be translated are very
5849 short. They have to appear in pull-down menus which restricts the
5850 length. But strings which are not containing entire sentences or at
5851 least large fragments of a sentence may appear in more than one
5852 situation in the program but might have different translations. This is
5853 especially true for the one-word strings which are frequently used in
5856 As a consequence many people say that the @code{gettext} approach is
5857 wrong and instead @code{catgets} should be used which indeed does not
5858 have this problem. But there is a very simple and powerful method to
5859 handle this kind of problems with the @code{gettext} functions.
5861 Contexts can be added to strings to be translated. A context dependent
5862 translation lookup is when a translation for a given string is searched,
5863 that is limited to a given context. The translation for the same string
5864 in a different context can be different. The different translations of
5865 the same string in different contexts can be stored in the in the same
5866 MO file, and can be edited by the translator in the same PO file.
5868 The @file{gettext.h} include file contains the lookup macros for strings
5869 with contexts. They are implemented as thin macros and inline functions
5870 over the functions from @code{<libintl.h>}.
5874 const char *pgettext (const char *msgctxt, const char *msgid);
5877 In a call of this macro, @var{msgctxt} and @var{msgid} must be string
5878 literals. The macro returns the translation of @var{msgid}, restricted
5879 to the context given by @var{msgctxt}.
5881 The @var{msgctxt} string is visible in the PO file to the translator.
5882 You should try to make it somehow canonical and never changing. Because
5883 every time you change an @var{msgctxt}, the translator will have to review
5884 the translation of @var{msgid}.
5886 Finding a canonical @var{msgctxt} string that doesn't change over time can
5887 be hard. But you shouldn't use the file name or class name containing the
5888 @code{pgettext} call -- because it is a common development task to rename
5889 a file or a class, and it shouldn't cause translator work. Also you shouldn't
5890 use a comment in the form of a complete English sentence as @var{msgctxt} --
5891 because orthography or grammar changes are often applied to such sentences,
5892 and again, it shouldn't force the translator to do a review.
5894 The @samp{p} in @samp{pgettext} stands for ``particular'': @code{pgettext}
5895 fetches a particular translation of the @var{msgid}.
5900 const char *dpgettext (const char *domain_name,
5901 const char *msgctxt, const char *msgid);
5902 const char *dcpgettext (const char *domain_name,
5903 const char *msgctxt, const char *msgid,
5907 These are generalizations of @code{pgettext}. They behave similarly to
5908 @code{dgettext} and @code{dcgettext}, respectively. The @var{domain_name}
5909 argument defines the translation domain. The @var{category} argument
5910 allows to use another locale category than @code{LC_MESSAGES}.
5912 As as example consider the following fictional situation. A GUI program
5913 has a menu bar with the following entries:
5916 +------------+------------+--------------------------------------+
5917 | File | Printer | |
5918 +------------+------------+--------------------------------------+
5921 +----------+ | Connect |
5925 To have the strings @code{File}, @code{Printer}, @code{Open},
5926 @code{New}, @code{Select}, and @code{Connect} translated there has to be
5927 at some point in the code a call to a function of the @code{gettext}
5928 family. But in two places the string passed into the function would be
5929 @code{Open}. The translations might not be the same and therefore we
5930 are in the dilemma described above.
5932 What distinguishes the two places is the menu path from the menu root to
5933 the particular menu entries:
5942 Menu|Printer|Connect
5945 The context is thus the menu path without its last part. So, the calls
5949 pgettext ("Menu|", "File")
5950 pgettext ("Menu|", "Printer")
5951 pgettext ("Menu|File|", "Open")
5952 pgettext ("Menu|File|", "New")
5953 pgettext ("Menu|Printer|", "Select")
5954 pgettext ("Menu|Printer|", "Open")
5955 pgettext ("Menu|Printer|", "Connect")
5958 Whether or not to use the @samp{|} character at the end of the context is a
5961 For more complex cases, where the @var{msgctxt} or @var{msgid} are not
5962 string literals, more general macros are available:
5964 @findex pgettext_expr
5965 @findex dpgettext_expr
5966 @findex dcpgettext_expr
5968 const char *pgettext_expr (const char *msgctxt, const char *msgid);
5969 const char *dpgettext_expr (const char *domain_name,
5970 const char *msgctxt, const char *msgid);
5971 const char *dcpgettext_expr (const char *domain_name,
5972 const char *msgctxt, const char *msgid,
5976 Here @var{msgctxt} and @var{msgid} can be arbitrary string-valued expressions.
5977 These macros are more general. But in the case that both argument expressions
5978 are string literals, the macros without the @samp{_expr} suffix are more
5981 @node Plural forms, Optimized gettext, Contexts, gettext
5982 @subsection Additional functions for plural forms
5983 @cindex plural forms
5985 The functions of the @code{gettext} family described so far (and all the
5986 @code{catgets} functions as well) have one problem in the real world
5987 which have been neglected completely in all existing approaches. What
5988 is meant here is the handling of plural forms.
5990 Looking through Unix source code before the time anybody thought about
5991 internationalization (and, sadly, even afterwards) one can often find
5992 code similar to the following:
5995 printf ("%d file%s deleted", n, n == 1 ? "" : "s");
5999 After the first complaints from people internationalizing the code people
6000 either completely avoided formulations like this or used strings like
6001 @code{"file(s)"}. Both look unnatural and should be avoided. First
6002 tries to solve the problem correctly looked like this:
6006 printf ("%d file deleted", n);
6008 printf ("%d files deleted", n);
6011 But this does not solve the problem. It helps languages where the
6012 plural form of a noun is not simply constructed by adding an
6019 but that is all. Once again people fell into the trap of believing the
6020 rules their language is using are universal. But the handling of plural
6021 forms differs widely between the language families. For example,
6022 Rafal Maszkowski @code{<rzm@@mat.uni.torun.pl>} reports:
6025 In Polish we use e.g.@: plik (file) this way:
6033 and so on (o' means 8859-2 oacute which should be rather okreska,
6034 similar to aogonek).
6037 There are two things which can differ between languages (and even inside
6042 The form how plural forms are built differs. This is a problem with
6043 languages which have many irregularities. German, for instance, is a
6044 drastic case. Though English and German are part of the same language
6045 family (Germanic), the almost regular forming of plural noun forms
6053 is hardly found in German.
6056 The number of plural forms differ. This is somewhat surprising for
6057 those who only have experiences with Romanic and Germanic languages
6058 since here the number is the same (there are two).
6060 But other language families have only one form or many forms. More
6061 information on this in an extra section.
6064 The consequence of this is that application writers should not try to
6065 solve the problem in their code. This would be localization since it is
6066 only usable for certain, hardcoded language environments. Instead the
6067 extended @code{gettext} interface should be used.
6069 These extra functions are taking instead of the one key string two
6070 strings and a numerical argument. The idea behind this is that using
6071 the numerical argument and the first string as a key, the implementation
6072 can select using rules specified by the translator the right plural
6073 form. The two string arguments then will be used to provide a return
6074 value in case no message catalog is found (similar to the normal
6075 @code{gettext} behavior). In this case the rules for Germanic language
6076 is used and it is assumed that the first string argument is the singular
6077 form, the second the plural form.
6079 This has the consequence that programs without language catalogs can
6080 display the correct strings only if the program itself is written using
6081 a Germanic language. This is a limitation but since the GNU C library
6082 (as well as the GNU @code{gettext} package) are written as part of the
6083 GNU package and the coding standards for the GNU project require program
6084 being written in English, this solution nevertheless fulfills its
6087 @deftypefun {char *} ngettext (const char *@var{msgid1}, const char *@var{msgid2}, unsigned long int @var{n})
6088 The @code{ngettext} function is similar to the @code{gettext} function
6089 as it finds the message catalogs in the same way. But it takes two
6090 extra arguments. The @var{msgid1} parameter must contain the singular
6091 form of the string to be converted. It is also used as the key for the
6092 search in the catalog. The @var{msgid2} parameter is the plural form.
6093 The parameter @var{n} is used to determine the plural form. If no
6094 message catalog is found @var{msgid1} is returned if @code{n == 1},
6095 otherwise @code{msgid2}.
6097 An example for the use of this function is:
6100 printf (ngettext ("%d file removed", "%d files removed", n), n);
6103 Please note that the numeric value @var{n} has to be passed to the
6104 @code{printf} function as well. It is not sufficient to pass it only to
6107 In the English singular case, the number -- always 1 -- can be replaced with
6111 printf (ngettext ("One file removed", "%d files removed", n), n);
6115 This works because the @samp{printf} function discards excess arguments that
6116 are not consumed by the format string.
6118 If this function is meant to yield a format string that takes two or more
6119 arguments, you can not use it like this:
6122 printf (ngettext ("%d file removed from directory %s",
6123 "%d files removed from directory %s",
6129 because in many languages the translators want to replace the @samp{%d}
6130 with an explicit word in the singular case, just like ``one'' in English,
6131 and C format strings cannot consume the second argument but skip the first
6132 argument. Instead, you have to reorder the arguments so that @samp{n}
6136 printf (ngettext ("%$2d file removed from directory %$1s",
6137 "%$2d files removed from directory %$1s",
6143 See @ref{c-format} for details about this argument reordering syntax.
6145 When you know that the value of @code{n} is within a given range, you can
6146 specify it as a comment directed to the @code{xgettext} tool. This
6147 information may help translators to use more adequate translations. Like
6151 if (days > 7 && days < 14)
6152 /* xgettext: range: 1..6 */
6153 printf (ngettext ("one week and one day", "one week and %d days",
6158 It is also possible to use this function when the strings don't contain a
6162 puts (ngettext ("Delete the selected file?",
6163 "Delete the selected files?",
6167 In this case the number @var{n} is only used to choose the plural form.
6170 @deftypefun {char *} dngettext (const char *@var{domain}, const char *@var{msgid1}, const char *@var{msgid2}, unsigned long int @var{n})
6171 The @code{dngettext} is similar to the @code{dgettext} function in the
6172 way the message catalog is selected. The difference is that it takes
6173 two extra parameter to provide the correct plural form. These two
6174 parameters are handled in the same way @code{ngettext} handles them.
6177 @deftypefun {char *} dcngettext (const char *@var{domain}, const char *@var{msgid1}, const char *@var{msgid2}, unsigned long int @var{n}, int @var{category})
6178 The @code{dcngettext} is similar to the @code{dcgettext} function in the
6179 way the message catalog is selected. The difference is that it takes
6180 two extra parameter to provide the correct plural form. These two
6181 parameters are handled in the same way @code{ngettext} handles them.
6184 Now, how do these functions solve the problem of the plural forms?
6185 Without the input of linguists (which was not available) it was not
6186 possible to determine whether there are only a few different forms in
6187 which plural forms are formed or whether the number can increase with
6188 every new supported language.
6190 Therefore the solution implemented is to allow the translator to specify
6191 the rules of how to select the plural form. Since the formula varies
6192 with every language this is the only viable solution except for
6193 hardcoding the information in the code (which still would require the
6194 possibility of extensions to not prevent the use of new languages).
6196 @cindex specifying plural form in a PO file
6197 @kwindex nplurals@r{, in a PO file header}
6198 @kwindex plural@r{, in a PO file header}
6199 The information about the plural form selection has to be stored in the
6200 header entry of the PO file (the one with the empty @code{msgid} string).
6201 The plural form information looks like this:
6204 Plural-Forms: nplurals=2; plural=n == 1 ? 0 : 1;
6207 The @code{nplurals} value must be a decimal number which specifies how
6208 many different plural forms exist for this language. The string
6209 following @code{plural} is an expression which is using the C language
6210 syntax. Exceptions are that no negative numbers are allowed, numbers
6211 must be decimal, and the only variable allowed is @code{n}. Spaces are
6212 allowed in the expression, but backslash-newlines are not; in the
6213 examples below the backslash-newlines are present for formatting purposes
6214 only. This expression will be evaluated whenever one of the functions
6215 @code{ngettext}, @code{dngettext}, or @code{dcngettext} is called. The
6216 numeric value passed to these functions is then substituted for all uses
6217 of the variable @code{n} in the expression. The resulting value then
6218 must be greater or equal to zero and smaller than the value given as the
6219 value of @code{nplurals}.
6222 @cindex plural form formulas
6223 The following rules are known at this point. The language with families
6224 are listed. But this does not necessarily mean the information can be
6225 generalized for the whole family (as can be easily seen in the table
6226 below).@footnote{Additions are welcome. Send appropriate information to
6227 @email{bug-gnu-gettext@@gnu.org} and @email{bug-glibc-manual@@gnu.org}.
6228 The Unicode CLDR Project (@uref{http://cldr.unicode.org}) provides a
6229 comprehensive set of plural forms in a different format. The
6230 @code{msginit} program has preliminary support for the format so you can
6231 use it as a baseline (@pxref{msginit Invocation}).}
6234 @item Only one form:
6235 Some languages only require one single form. There is no distinction
6236 between the singular and plural form. An appropriate header entry
6237 would look like this:
6240 Plural-Forms: nplurals=1; plural=0;
6244 Languages with this property include:
6248 Japanese, @c 122.1 million speakers
6249 Vietnamese, @c 68.6 million speakers
6250 Korean @c 66.3 million speakers
6251 @item Tai-Kadai family
6252 Thai @c 20.4 million speakers
6255 @item Two forms, singular used for one only
6256 This is the form used in most existing programs since it is what English
6257 is using. A header entry would look like this:
6260 Plural-Forms: nplurals=2; plural=n != 1;
6263 (Note: this uses the feature of C expressions that boolean expressions
6264 have to value zero or one.)
6267 Languages with this property include:
6270 @item Germanic family
6271 English, @c 328.0 million speakers
6272 German, @c 96.9 million speakers
6273 Dutch, @c 21.7 million speakers
6274 Swedish, @c 8.3 million speakers
6275 Danish, @c 5.6 million speakers
6276 Norwegian, @c 4.6 million speakers
6277 Faroese @c 0.05 million speakers
6278 @item Romanic family
6279 Spanish, @c 328.5 million speakers
6280 Portuguese, @c 178.0 million speakers - 163 million Brazilian Portuguese
6281 Italian, @c 61.7 million speakers
6282 Bulgarian @c 9.1 million speakers
6283 @item Latin/Greek family
6284 Greek @c 13.1 million speakers
6285 @item Finno-Ugric family
6286 Finnish, @c 5.0 million speakers
6287 Estonian @c 1.0 million speakers
6288 @item Semitic family
6289 Hebrew @c 5.3 million speakers
6290 @item Austronesian family
6291 Bahasa Indonesian @c 23.2 million speakers
6293 Esperanto @c 2 million speakers
6297 Other languages using the same header entry are:
6300 @item Finno-Ugric family
6301 Hungarian @c 12.5 million speakers
6302 @item Turkic/Altaic family
6303 Turkish @c 50.8 million speakers
6306 Hungarian does not appear to have a plural if you look at sentences involving
6307 cardinal numbers. For example, ``1 apple'' is ``1 alma'', and ``123 apples'' is
6308 ``123 alma''. But when the number is not explicit, the distinction between
6309 singular and plural exists: ``the apple'' is ``az alma'', and ``the apples'' is
6310 ``az alm@'{a}k''. Since @code{ngettext} has to support both types of sentences,
6311 it is classified here, under ``two forms''.
6313 The same holds for Turkish: ``1 apple'' is ``1 elma'', and ``123 apples'' is
6314 ``123 elma''. But when the number is omitted, the distinction between singular
6315 and plural exists: ``the apple'' is ``elma'', and ``the apples'' is
6318 @item Two forms, singular used for zero and one
6319 Exceptional case in the language family. The header entry would be:
6322 Plural-Forms: nplurals=2; plural=n>1;
6326 Languages with this property include:
6329 @item Romanic family
6330 Brazilian Portuguese, @c 163 million speakers
6331 French @c 67.8 million speakers
6334 @item Three forms, special case for zero
6335 The header entry would be:
6338 Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n != 0 ? 1 : 2;
6342 Languages with this property include:
6346 Latvian @c 1.5 million speakers
6349 @item Three forms, special cases for one and two
6350 The header entry would be:
6353 Plural-Forms: nplurals=3; plural=n==1 ? 0 : n==2 ? 1 : 2;
6357 Languages with this property include:
6361 Gaeilge (Irish) @c 0.4 million speakers
6364 @item Three forms, special case for numbers ending in 00 or [2-9][0-9]
6365 The header entry would be:
6368 Plural-Forms: nplurals=3; \
6369 plural=n==1 ? 0 : (n==0 || (n%100 > 0 && n%100 < 20)) ? 1 : 2;
6373 Languages with this property include:
6376 @item Romanic family
6377 Romanian @c 23.4 million speakers
6380 @item Three forms, special case for numbers ending in 1[2-9]
6381 The header entry would look like this:
6384 Plural-Forms: nplurals=3; \
6385 plural=n%10==1 && n%100!=11 ? 0 : \
6386 n%10>=2 && (n%100<10 || n%100>=20) ? 1 : 2;
6390 Languages with this property include:
6394 Lithuanian @c 3.2 million speakers
6397 @item Three forms, special cases for numbers ending in 1 and 2, 3, 4, except those ending in 1[1-4]
6398 The header entry would look like this:
6401 Plural-Forms: nplurals=3; \
6402 plural=n%10==1 && n%100!=11 ? 0 : \
6403 n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;
6407 Languages with this property include:
6411 Russian, @c 143.6 million speakers
6412 Ukrainian, @c 37.0 million speakers
6413 Belarusian, @c 8.6 million speakers
6414 Serbian, @c 7.0 million speakers
6415 Croatian @c 5.5 million speakers
6418 @item Three forms, special cases for 1 and 2, 3, 4
6419 The header entry would look like this:
6422 Plural-Forms: nplurals=3; \
6423 plural=(n==1) ? 0 : (n>=2 && n<=4) ? 1 : 2;
6427 Languages with this property include:
6431 Czech, @c 9.5 million speakers
6432 Slovak @c 5.0 million speakers
6435 @item Three forms, special case for one and some numbers ending in 2, 3, or 4
6436 The header entry would look like this:
6439 Plural-Forms: nplurals=3; \
6441 n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;
6445 Languages with this property include:
6449 Polish @c 40.0 million speakers
6452 @item Four forms, special case for one and all numbers ending in 02, 03, or 04
6453 The header entry would look like this:
6456 Plural-Forms: nplurals=4; \
6457 plural=n%100==1 ? 0 : n%100==2 ? 1 : n%100==3 || n%100==4 ? 2 : 3;
6461 Languages with this property include:
6465 Slovenian @c 1.9 million speakers
6468 @item Six forms, special cases for one, two, all numbers ending in 02, 03, @dots{} 10, all numbers ending in 11 @dots{} 99, and others
6469 The header entry would look like this:
6472 Plural-Forms: nplurals=6; \
6473 plural=n==0 ? 0 : n==1 ? 1 : n==2 ? 2 : n%100>=3 && n%100<=10 ? 3 \
6474 : n%100>=11 ? 4 : 5;
6478 Languages with this property include:
6481 @item Afroasiatic family
6482 Arabic @c 246.0 million speakers
6486 You might now ask, @code{ngettext} handles only numbers @var{n} of type
6487 @samp{unsigned long}. What about larger integer types? What about negative
6488 numbers? What about floating-point numbers?
6490 About larger integer types, such as @samp{uintmax_t} or
6491 @samp{unsigned long long}: they can be handled by reducing the value to a
6492 range that fits in an @samp{unsigned long}. Simply casting the value to
6493 @samp{unsigned long} would not do the right thing, since it would treat
6494 @code{ULONG_MAX + 1} like zero, @code{ULONG_MAX + 2} like singular, and
6495 the like. Here you can exploit the fact that all mentioned plural form
6496 formulas eventually become periodic, with a period that is a divisor of 100
6497 (or 1000 or 1000000). So, when you reduce a large value to another one in
6498 the range [1000000, 1999999] that ends in the same 6 decimal digits, you
6499 can assume that it will lead to the same plural form selection. This code
6503 #include <inttypes.h>
6504 uintmax_t nbytes = ...;
6505 printf (ngettext ("The file has %"PRIuMAX" byte.",
6506 "The file has %"PRIuMAX" bytes.",
6508 ? (nbytes % 1000000) + 1000000
6513 Negative and floating-point values usually represent physical entities for
6514 which singular and plural don't clearly apply. In such cases, there is no
6515 need to use @code{ngettext}; a simple @code{gettext} call with a form suitable
6516 for all values will do. For example:
6519 printf (gettext ("Time elapsed: %.3f seconds"),
6520 num_milliseconds * 0.001);
6524 Even if @var{num_milliseconds} happens to be a multiple of 1000, the output
6526 Time elapsed: 1.000 seconds
6529 is acceptable in English, and similarly for other languages.
6531 The translators' perspective regarding plural forms is explained in
6532 @ref{Translating plural forms}.
6534 @node Optimized gettext, , Plural forms, gettext
6535 @subsection Optimization of the *gettext functions
6536 @cindex optimization of @code{gettext} functions
6538 At this point of the discussion we should talk about an advantage of the
6539 GNU @code{gettext} implementation. Some readers might have pointed out
6540 that an internationalized program might have a poor performance if some
6541 string has to be translated in an inner loop. While this is unavoidable
6542 when the string varies from one run of the loop to the other it is
6543 simply a waste of time when the string is always the same. Take the
6551 puts (gettext ("Hello world"));
6558 When the locale selection does not change between two runs the resulting
6559 string is always the same. One way to use this is:
6564 str = gettext ("Hello world");
6574 But this solution is not usable in all situation (e.g.@: when the locale
6575 selection changes) nor does it lead to legible code.
6577 For this reason, GNU @code{gettext} caches previous translation results.
6578 When the same translation is requested twice, with no new message
6579 catalogs being loaded in between, @code{gettext} will, the second time,
6580 find the result through a single cache lookup.
6582 @node Comparison, Using libintl.a, gettext, Programmers
6583 @section Comparing the Two Interfaces
6584 @cindex @code{gettext} vs @code{catgets}
6585 @cindex comparison of interfaces
6587 @c FIXME: arguments to catgets vs. gettext
6588 @c Partly done 950718 -- drepper
6590 The following discussion is perhaps a little bit colored. As said
6591 above we implemented GNU @code{gettext} following the Uniforum
6592 proposal and this surely has its reasons. But it should show how we
6593 came to this decision.
6595 First we take a look at the developing process. When we write an
6596 application using NLS provided by @code{gettext} we proceed as always.
6597 Only when we come to a string which might be seen by the users and thus
6598 has to be translated we use @code{gettext("@dots{}")} instead of
6599 @code{"@dots{}"}. At the beginning of each source file (or in a central
6600 header file) we define
6603 #define gettext(String) (String)
6606 Even this definition can be avoided when the system supports the
6607 @code{gettext} function in its C library. When we compile this code the
6608 result is the same as if no NLS code is used. When you take a look at
6609 the GNU @code{gettext} code you will see that we use @code{_("@dots{}")}
6610 instead of @code{gettext("@dots{}")}. This reduces the number of
6611 additional characters per translatable string to @emph{3} (in words:
6614 When now a production version of the program is needed we simply replace
6618 #define _(String) (String)
6624 @cindex include file @file{libintl.h}
6626 #include <libintl.h>
6627 #define _(String) gettext (String)
6631 Additionally we run the program @file{xgettext} on all source code file
6632 which contain translatable strings and that's it: we have a running
6633 program which does not depend on translations to be available, but which
6634 can use any that becomes available.
6636 @cindex @code{N_}, a convenience macro
6637 The same procedure can be done for the @code{gettext_noop} invocations
6638 (@pxref{Special cases}). One usually defines @code{gettext_noop} as a
6639 no-op macro. So you should consider the following code for your project:
6642 #define gettext_noop(String) String
6643 #define N_(String) gettext_noop (String)
6646 @code{N_} is a short form similar to @code{_}. The @file{Makefile} in
6647 the @file{po/} directory of GNU @code{gettext} knows by default both of the
6648 mentioned short forms so you are invited to follow this proposal for
6651 Now to @code{catgets}. The main problem is the work for the
6652 programmer. Every time he comes to a translatable string he has to
6653 define a number (or a symbolic constant) which has also be defined in
6654 the message catalog file. He also has to take care for duplicate
6655 entries, duplicate message IDs etc. If he wants to have the same
6656 quality in the message catalog as the GNU @code{gettext} program
6657 provides he also has to put the descriptive comments for the strings and
6658 the location in all source code files in the message catalog. This is
6659 nearly a Mission: Impossible.
6661 But there are also some points people might call advantages speaking for
6662 @code{catgets}. If you have a single word in a string and this string
6663 is used in different contexts it is likely that in one or the other
6664 language the word has different translations. Example:
6667 printf ("%s: %d", gettext ("number"), number_of_errors)
6669 printf ("you should see %d %s", number_count,
6670 number_count == 1 ? gettext ("number") : gettext ("numbers"))
6673 Here we have to translate two times the string @code{"number"}. Even
6674 if you do not speak a language beside English it might be possible to
6675 recognize that the two words have a different meaning. In German the
6676 first appearance has to be translated to @code{"Anzahl"} and the second
6679 Now you can say that this example is really esoteric. And you are
6680 right! This is exactly how we felt about this problem and decide that
6681 it does not weight that much. The solution for the above problem could
6685 printf ("%s %d", gettext ("number:"), number_of_errors)
6687 printf (number_count == 1 ? gettext ("you should see %d number")
6688 : gettext ("you should see %d numbers"),
6692 We believe that we can solve all conflicts with this method. If it is
6693 difficult one can also consider changing one of the conflicting string a
6694 little bit. But it is not impossible to overcome.
6696 @code{catgets} allows same original entry to have different translations,
6697 but @code{gettext} has another, scalable approach for solving ambiguities
6698 of this kind: @xref{Ambiguities}.
6700 @node Using libintl.a, gettext grok, Comparison, Programmers
6701 @section Using libintl.a in own programs
6703 Starting with version 0.9.4 the library @code{libintl.h} should be
6704 self-contained. I.e., you can use it in your own programs without
6705 providing additional functions. The @file{Makefile} will put the header
6706 and the library in directories selected using the @code{$(prefix)}.
6708 @node gettext grok, Temp Programmers, Using libintl.a, Programmers
6709 @section Being a @code{gettext} grok
6711 @strong{ NOTE: } This documentation section is outdated and needs to be
6714 To fully exploit the functionality of the GNU @code{gettext} library it
6715 is surely helpful to read the source code. But for those who don't want
6716 to spend that much time in reading the (sometimes complicated) code here
6720 @item Changing the language at runtime
6721 @cindex language selection at runtime
6723 For interactive programs it might be useful to offer a selection of the
6724 used language at runtime. To understand how to do this one need to know
6725 how the used language is determined while executing the @code{gettext}
6726 function. The method which is presented here only works correctly
6727 with the GNU implementation of the @code{gettext} functions.
6729 In the function @code{dcgettext} at every call the current setting of
6730 the highest priority environment variable is determined and used.
6731 Highest priority means here the following list with decreasing
6735 @vindex LANGUAGE@r{, environment variable}
6736 @item @code{LANGUAGE}
6737 @vindex LC_ALL@r{, environment variable}
6739 @vindex LC_CTYPE@r{, environment variable}
6740 @vindex LC_NUMERIC@r{, environment variable}
6741 @vindex LC_TIME@r{, environment variable}
6742 @vindex LC_COLLATE@r{, environment variable}
6743 @vindex LC_MONETARY@r{, environment variable}
6744 @vindex LC_MESSAGES@r{, environment variable}
6745 @item @code{LC_xxx}, according to selected locale category
6746 @vindex LANG@r{, environment variable}
6750 Afterwards the path is constructed using the found value and the
6751 translation file is loaded if available.
6753 What happens now when the value for, say, @code{LANGUAGE} changes? According
6754 to the process explained above the new value of this variable is found
6755 as soon as the @code{dcgettext} function is called. But this also means
6756 the (perhaps) different message catalog file is loaded. In other
6757 words: the used language is changed.
6759 But there is one little hook. The code for gcc-2.7.0 and up provides
6760 some optimization. This optimization normally prevents the calling of
6761 the @code{dcgettext} function as long as no new catalog is loaded. But
6762 if @code{dcgettext} is not called the program also cannot find the
6763 @code{LANGUAGE} variable be changed (@pxref{Optimized gettext}). A
6764 solution for this is very easy. Include the following code in the
6765 language switching function.
6768 /* Change language. */
6769 setenv ("LANGUAGE", "fr", 1);
6771 /* Make change known. */
6773 extern int _nl_msg_cat_cntr;
6778 @cindex @code{_nl_msg_cat_cntr}
6779 The variable @code{_nl_msg_cat_cntr} is defined in @file{loadmsgcat.c}.
6780 You don't need to know what this is for. But it can be used to detect
6781 whether a @code{gettext} implementation is GNU gettext and not non-GNU
6782 system's native gettext implementation.
6786 @node Temp Programmers, , gettext grok, Programmers
6787 @section Temporary Notes for the Programmers Chapter
6789 @strong{ NOTE: } This documentation section is outdated and needs to be
6793 * Temp Implementations:: Temporary - Two Possible Implementations
6794 * Temp catgets:: Temporary - About @code{catgets}
6795 * Temp WSI:: Temporary - Why a single implementation
6796 * Temp Notes:: Temporary - Notes
6799 @node Temp Implementations, Temp catgets, Temp Programmers, Temp Programmers
6800 @subsection Temporary - Two Possible Implementations
6802 There are two competing methods for language independent messages:
6803 the X/Open @code{catgets} method, and the Uniforum @code{gettext}
6804 method. The @code{catgets} method indexes messages by integers; the
6805 @code{gettext} method indexes them by their English translations.
6806 The @code{catgets} method has been around longer and is supported
6807 by more vendors. The @code{gettext} method is supported by Sun,
6808 and it has been heard that the COSE multi-vendor initiative is
6809 supporting it. Neither method is a POSIX standard; the POSIX.1
6810 committee had a lot of disagreement in this area.
6812 Neither one is in the POSIX standard. There was much disagreement
6813 in the POSIX.1 committee about using the @code{gettext} routines
6814 vs. @code{catgets} (XPG). In the end the committee couldn't
6815 agree on anything, so no messaging system was included as part
6816 of the standard. I believe the informative annex of the standard
6817 includes the XPG3 messaging interfaces, ``@dots{}as an example of
6818 a messaging system that has been implemented@dots{}''
6820 They were very careful not to say anywhere that you should use one
6821 set of interfaces over the other. For more on this topic please
6822 see the Programming for Internationalization FAQ.
6824 @node Temp catgets, Temp WSI, Temp Implementations, Temp Programmers
6825 @subsection Temporary - About @code{catgets}
6827 There have been a few discussions of late on the use of
6828 @code{catgets} as a base. I think it important to present both
6829 sides of the argument and hence am opting to play devil's advocate
6832 I'll not deny the fact that @code{catgets} could have been designed
6833 a lot better. It currently has quite a number of limitations and
6834 these have already been pointed out.
6836 However there is a great deal to be said for consistency and
6837 standardization. A common recurring problem when writing Unix
6838 software is the myriad portability problems across Unix platforms.
6839 It seems as if every Unix vendor had a look at the operating system
6840 and found parts they could improve upon. Undoubtedly, these
6841 modifications are probably innovative and solve real problems.
6842 However, software developers have a hard time keeping up with all
6843 these changes across so many platforms.
6845 And this has prompted the Unix vendors to begin to standardize their
6846 systems. Hence the impetus for Spec1170. Every major Unix vendor
6847 has committed to supporting this standard and every Unix software
6848 developer waits with glee the day they can write software to this
6849 standard and simply recompile (without having to use autoconf)
6850 across different platforms.
6852 As I understand it, Spec1170 is roughly based upon version 4 of the
6853 X/Open Portability Guidelines (XPG4). Because @code{catgets} and
6854 friends are defined in XPG4, I'm led to believe that @code{catgets}
6855 is a part of Spec1170 and hence will become a standardized component
6856 of all Unix systems.
6858 @node Temp WSI, Temp Notes, Temp catgets, Temp Programmers
6859 @subsection Temporary - Why a single implementation
6861 Now it seems kind of wasteful to me to have two different systems
6862 installed for accessing message catalogs. If we do want to remedy
6863 @code{catgets} deficiencies why don't we try to expand @code{catgets}
6864 (in a compatible manner) rather than implement an entirely new system.
6865 Otherwise, we'll end up with two message catalog access systems installed
6866 with an operating system - one set of routines for packages using GNU
6867 @code{gettext} for their internationalization, and another set of routines
6868 (catgets) for all other software. Bloated?
6870 Supposing another catalog access system is implemented. Which do
6871 we recommend? At least for Linux, we need to attract as many
6872 software developers as possible. Hence we need to make it as easy
6873 for them to port their software as possible. Which means supporting
6874 @code{catgets}. We will be implementing the @code{libintl} code
6875 within our @code{libc}, but does this mean we also have to incorporate
6876 another message catalog access scheme within our @code{libc} as well?
6877 And what about people who are going to be using the @code{libintl}
6878 + non-@code{catgets} routines. When they port their software to
6879 other platforms, they're now going to have to include the front-end
6880 (@code{libintl}) code plus the back-end code (the non-@code{catgets}
6881 access routines) with their software instead of just including the
6882 @code{libintl} code with their software.
6884 Message catalog support is however only the tip of the iceberg.
6885 What about the data for the other locale categories? They also have
6886 a number of deficiencies. Are we going to abandon them as well and
6887 develop another duplicate set of routines (should @code{libintl}
6888 expand beyond message catalog support)?
6890 Like many parts of Unix that can be improved upon, we're stuck with balancing
6891 compatibility with the past with useful improvements and innovations for
6894 @node Temp Notes, , Temp WSI, Temp Programmers
6895 @subsection Temporary - Notes
6897 X/Open agreed very late on the standard form so that many
6898 implementations differ from the final form. Both of my system (old
6899 Linux catgets and Ultrix-4) have a strange variation.
6901 OK. After incorporating the last changes I have to spend some time on
6902 making the GNU/Linux @code{libc} @code{gettext} functions. So in future
6903 Solaris is not the only system having @code{gettext}.
6905 @node Translators, Maintainers, Programmers, Top
6906 @chapter The Translator's View
6908 @c FIXME: Reorganize whole chapter.
6911 * Trans Intro 0:: Introduction 0
6912 * Trans Intro 1:: Introduction 1
6913 * Discussions:: Discussions
6914 * Organization:: Organization
6915 * Information Flow:: Information Flow
6916 * Translating plural forms:: How to fill in @code{msgstr[0]}, @code{msgstr[1]}
6917 * Prioritizing messages:: How to find which messages to translate first
6920 @node Trans Intro 0, Trans Intro 1, Translators, Translators
6921 @section Introduction 0
6923 @strong{ NOTE: } This documentation section is outdated and needs to be
6926 Free software is going international! The Translation Project is a way
6927 to get maintainers, translators and users all together, so free software
6928 will gradually become able to speak many native languages.
6930 The GNU @code{gettext} tool set contains @emph{everything} maintainers
6931 need for internationalizing their packages for messages. It also
6932 contains quite useful tools for helping translators at localizing
6933 messages to their native language, once a package has already been
6936 To achieve the Translation Project, we need many interested
6937 people who like their own language and write it well, and who are also
6938 able to synergize with other translators speaking the same language.
6939 If you'd like to volunteer to @emph{work} at translating messages,
6940 please send mail to your translating team.
6942 Each team has its own mailing list, courtesy of Linux
6943 International. You may reach your translating team at the address
6944 @file{@var{ll}@@li.org}, replacing @var{ll} by the two-letter @w{ISO 639}
6945 code for your language. Language codes are @emph{not} the same as
6946 country codes given in @w{ISO 3166}. The following translating teams
6950 Chinese @code{zh}, Czech @code{cs}, Danish @code{da}, Dutch @code{nl},
6951 Esperanto @code{eo}, Finnish @code{fi}, French @code{fr}, Irish
6952 @code{ga}, German @code{de}, Greek @code{el}, Italian @code{it},
6953 Japanese @code{ja}, Indonesian @code{in}, Norwegian @code{no}, Polish
6954 @code{pl}, Portuguese @code{pt}, Russian @code{ru}, Spanish @code{es},
6955 Swedish @code{sv} and Turkish @code{tr}.
6959 For example, you may reach the Chinese translating team by writing to
6960 @file{zh@@li.org}. When you become a member of the translating team
6961 for your own language, you may subscribe to its list. For example,
6962 Swedish people can send a message to @w{@file{sv-request@@li.org}},
6963 having this message body:
6969 Keep in mind that team members should be interested in @emph{working}
6970 at translations, or at solving translational difficulties, rather than
6971 merely lurking around. If your team does not exist yet and you want to
6972 start one, please write to @w{@file{coordinator@@translationproject.org}};
6973 you will then reach the coordinator for all translator teams.
6975 A handful of GNU packages have already been adapted and provided
6976 with message translations for several languages. Translation
6977 teams have begun to organize, using these packages as a starting
6978 point. But there are many more packages and many languages for
6979 which we have no volunteer translators. If you would like to
6980 volunteer to work at translating messages, please send mail to
6981 @file{coordinator@@translationproject.org} indicating what language(s)
6984 @node Trans Intro 1, Discussions, Trans Intro 0, Translators
6985 @section Introduction 1
6987 @strong{ NOTE: } This documentation section is outdated and needs to be
6990 This is now official, GNU is going international! Here is the
6991 announcement submitted for the January 1995 GNU Bulletin:
6994 A handful of GNU packages have already been adapted and provided
6995 with message translations for several languages. Translation
6996 teams have begun to organize, using these packages as a starting
6997 point. But there are many more packages and many languages
6998 for which we have no volunteer translators. If you'd like to
6999 volunteer to work at translating messages, please send mail to
7000 @samp{coordinator@@translationproject.org} indicating what language(s)
7004 This document should answer many questions for those who are curious about
7005 the process or would like to contribute. Please at least skim over it,
7006 hoping to cut down a little of the high volume of e-mail generated by this
7007 collective effort towards internationalization of free software.
7009 Most free programming which is widely shared is done in English, and
7010 currently, English is used as the main communicating language between
7011 national communities collaborating to free software. This very document
7012 is written in English. This will not change in the foreseeable future.
7014 However, there is a strong appetite from national communities for
7015 having more software able to write using national language and habits,
7016 and there is an on-going effort to modify free software in such a way
7017 that it becomes able to do so. The experiments driven so far raised
7018 an enthusiastic response from pretesters, so we believe that
7019 internationalization of free software is dedicated to succeed.
7021 For suggestion clarifications, additions or corrections to this
7022 document, please e-mail to @file{coordinator@@translationproject.org}.
7024 @node Discussions, Organization, Trans Intro 1, Translators
7025 @section Discussions
7027 @strong{ NOTE: } This documentation section is outdated and needs to be
7030 Facing this internationalization effort, a few users expressed their
7031 concerns. Some of these doubts are presented and discussed, here.
7034 @item Smaller groups
7036 Some languages are not spoken by a very large number of people, so people
7037 speaking them sometimes consider that there may not be all that much
7038 demand such versions of free software packages. Moreover, many people
7039 being @emph{into computers}, in some countries, generally seem to prefer
7040 English versions of their software.
7042 On the other end, people might enjoy their own language a lot, and be
7043 very motivated at providing to themselves the pleasure of having their
7044 beloved free software speaking their mother tongue. They do themselves
7045 a personal favor, and do not pay that much attention to the number of
7046 people benefiting of their work.
7048 @item Misinterpretation
7050 Other users are shy to push forward their own language, seeing in this
7051 some kind of misplaced propaganda. Someone thought there must be some
7052 users of the language over the networks pestering other people with it.
7054 But any spoken language is worth localization, because there are
7055 people behind the language for whom the language is important and
7056 dear to their hearts.
7058 @item Odd translations
7060 The biggest problem is to find the right translations so that
7061 everybody can understand the messages. Translations are usually a
7062 little odd. Some people get used to English, to the extent they may
7063 find translations into their own language ``rather pushy, obnoxious
7064 and sometimes even hilarious.'' As a French speaking man, I have
7065 the experience of those instruction manuals for goods, so poorly
7066 translated in French in Korea or Taiwan@dots{}
7068 The fact is that we sometimes have to create a kind of national
7069 computer culture, and this is not easy without the collaboration of
7070 many people liking their mother tongue. This is why translations are
7071 better achieved by people knowing and loving their own language, and
7072 ready to work together at improving the results they obtain.
7074 @item Dependencies over the GPL or LGPL
7076 Some people wonder if using GNU @code{gettext} necessarily brings their
7077 package under the protective wing of the GNU General Public License or
7078 the GNU Lesser General Public License, when they do not want to make
7079 their program free, or want other kinds of freedom. The simplest
7080 answer is ``normally not''.
7082 The @code{gettext-runtime} part of GNU @code{gettext}, i.e.@: the
7083 contents of @code{libintl}, is covered by the GNU Lesser General Public
7084 License. The @code{gettext-tools} part of GNU @code{gettext}, i.e.@: the
7085 rest of the GNU @code{gettext} package, is covered by the GNU General
7088 The mere marking of localizable strings in a package, or conditional
7089 inclusion of a few lines for initialization, is not really including
7090 GPL'ed or LGPL'ed code. However, since the localization routines in
7091 @code{libintl} are under the LGPL, the LGPL needs to be considered.
7092 It gives the right to distribute the complete unmodified source of
7093 @code{libintl} even with non-free programs. It also gives the right
7094 to use @code{libintl} as a shared library, even for non-free programs.
7095 But it gives the right to use @code{libintl} as a static library or
7096 to incorporate @code{libintl} into another library only to free
7101 @node Organization, Information Flow, Discussions, Translators
7102 @section Organization
7104 @strong{ NOTE: } This documentation section is outdated and needs to be
7107 On a larger scale, the true solution would be to organize some kind of
7108 fairly precise set up in which volunteers could participate. I gave
7109 some thought to this idea lately, and realize there will be some
7110 touchy points. I thought of writing to Richard Stallman to launch
7111 such a project, but feel it might be good to shake out the ideas
7112 between ourselves first. Most probably that Linux International has
7113 some experience in the field already, or would like to orchestrate
7114 the volunteer work, maybe. Food for thought, in any case!
7116 I guess we have to setup something early, somehow, that will help
7117 many possible contributors of the same language to interlock and avoid
7118 work duplication, and further be put in contact for solving together
7119 problems particular to their tongue (in most languages, there are many
7120 difficulties peculiar to translating technical English). My Swedish
7121 contributor acknowledged these difficulties, and I'm well aware of
7124 This is surely not a technical issue, but we should manage so the
7125 effort of locale contributors be maximally useful, despite the national
7126 team layer interface between contributors and maintainers.
7128 The Translation Project needs some setup for coordinating language
7129 coordinators. Localizing evolving programs will surely
7130 become a permanent and continuous activity in the free software community,
7132 The setup should be minimally completed and tested before GNU
7133 @code{gettext} becomes an official reality. The e-mail address
7134 @file{coordinator@@translationproject.org} has been set up for receiving
7135 offers from volunteers and general e-mail on these topics. This address
7136 reaches the Translation Project coordinator.
7139 * Central Coordination:: Central Coordination
7140 * National Teams:: National Teams
7141 * Mailing Lists:: Mailing Lists
7144 @node Central Coordination, National Teams, Organization, Organization
7145 @subsection Central Coordination
7147 I also think GNU will need sooner than it thinks, that someone set up
7148 a way to organize and coordinate these groups. Some kind of group
7149 of groups. My opinion is that it would be good that GNU delegates
7150 this task to a small group of collaborating volunteers, shortly.
7151 Perhaps in @file{gnu.announce} a list of this national committee's
7154 My role as coordinator would simply be to refer to Ulrich any German
7155 speaking volunteer interested to localization of free software packages, and
7156 maybe helping national groups to initially organize, while maintaining
7157 national registries for until national groups are ready to take over.
7158 In fact, the coordinator should ease volunteers to get in contact with
7159 one another for creating national teams, which should then select
7160 one coordinator per language, or country (regionalized language).
7161 If well done, the coordination should be useful without being an
7162 overwhelming task, the time to put delegations in place.
7164 @node National Teams, Mailing Lists, Central Coordination, Organization
7165 @subsection National Teams
7167 I suggest we look for volunteer coordinators/editors for individual
7168 languages. These people will scan contributions of translation files
7169 for various programs, for their own languages, and will ensure high
7170 and uniform standards of diction.
7172 From my current experience with other people in these days, those who
7173 provide localizations are very enthusiastic about the process, and are
7174 more interested in the localization process than in the program they
7175 localize, and want to do many programs, not just one. This seems
7176 to confirm that having a coordinator/editor for each language is a
7179 We need to choose someone who is good at writing clear and concise
7180 prose in the language in question. That is hard---we can't check
7181 it ourselves. So we need to ask a few people to judge each others'
7182 writing and select the one who is best.
7184 I announce my prerelease to a few dozen people, and you would not
7185 believe all the discussions it generated already. I shudder to think
7186 what will happen when this will be launched, for true, officially,
7187 world wide. Who am I to arbitrate between two Czekolsovak users
7188 contradicting each other, for example?
7190 I assume that your German is not much better than my French so that
7191 I would not be able to judge about these formulations. What I would
7192 suggest is that for each language there is a group for people who
7193 maintain the PO files and judge about changes. I suspect there will
7194 be cultural differences between how such groups of people will behave.
7195 Some will have relaxed ways, reach consensus easily, and have anyone
7196 of the group relate to the maintainers, while others will fight to
7197 death, organize heavy administrations up to national standards, and
7198 use strict channels.
7200 The German team is putting out a good example. Right now, they are
7201 maybe half a dozen people revising translations of each other and
7202 discussing the linguistic issues. I do not even have all the names.
7203 Ulrich Drepper is taking care of coordinating the German team.
7204 He subscribed to all my pretest lists, so I do not even have to warn
7205 him specifically of incoming releases.
7207 I'm sure, that is a good idea to get teams for each language working
7208 on translations. That will make the translations better and more
7212 * Sub-Cultures:: Sub-Cultures
7213 * Organizational Ideas:: Organizational Ideas
7216 @node Sub-Cultures, Organizational Ideas, National Teams, National Teams
7217 @subsubsection Sub-Cultures
7219 Taking French for example, there are a few sub-cultures around computers
7220 which developed diverging vocabularies. Picking volunteers here and
7221 there without addressing this problem in an organized way, soon in the
7222 project, might produce a distasteful mix of internationalized programs,
7223 and possibly trigger endless quarrels among those who really care.
7225 Keeping some kind of unity in the way French localization of
7226 internationalized programs is achieved is a difficult (and delicate) job.
7227 Knowing the latin character of French people (:-), if we take this
7228 the wrong way, we could end up nowhere, or spoil a lot of energies.
7229 Maybe we should begin to address this problem seriously @emph{before}
7230 GNU @code{gettext} become officially published. And I suspect that this
7233 @node Organizational Ideas, , Sub-Cultures, National Teams
7234 @subsubsection Organizational Ideas
7236 I expect the next big changes after the official release. Please note
7237 that I use the German translation of the short GPL message. We need
7238 to set a few good examples before the localization goes out for true
7239 in the free software community. Here are a few points to discuss:
7243 Each group should have one FTP server (at least one master).
7246 The files on the server should reflect the latest version (of
7247 course!) and it should also contain a RCS directory with the
7248 corresponding archives (I don't have this now).
7251 There should also be a ChangeLog file (this is more useful than the
7252 RCS archive but can be generated automatically from the later by
7256 A @dfn{core group} should judge about questionable changes (for now
7257 this group consists solely by me but I ask some others occasionally;
7258 this also seems to work).
7262 @node Mailing Lists, , National Teams, Organization
7263 @subsection Mailing Lists
7265 If we get any inquiries about GNU @code{gettext}, send them on to:
7268 @file{coordinator@@translationproject.org}
7271 The @file{*-pretest} lists are quite useful to me, maybe the idea could
7272 be generalized to many GNU, and non-GNU packages. But each maintainer
7275 Fran@,{c}ois, we have a mechanism in place here at
7276 @file{gnu.ai.mit.edu} to track teams, support mailing lists for
7277 them and log members. We have a slight preference that you use it.
7278 If this is OK with you, I can get you clued in.
7280 Things are changing! A few years ago, when Daniel Fekete and I
7281 asked for a mailing list for GNU localization, nested at the FSF, we
7282 were politely invited to organize it anywhere else, and so did we.
7283 For communicating with my pretesters, I later made a handful of
7284 mailing lists located at iro.umontreal.ca and administrated by
7285 @code{majordomo}. These lists have been @emph{very} dependable
7288 I suspect that the German team will organize itself a mailing list
7289 located in Germany, and so forth for other countries. But before they
7290 organize for true, it could surely be useful to offer mailing lists
7291 located at the FSF to each national team. So yes, please explain me
7292 how I should proceed to create and handle them.
7294 We should create temporary mailing lists, one per country, to help
7295 people organize. Temporary, because once regrouped and structured, it
7296 would be fair the volunteers from country bring back @emph{their} list
7297 in there and manage it as they want. My feeling is that, in the long
7298 run, each team should run its own list, from within their country.
7299 There also should be some central list to which all teams could
7300 subscribe as they see fit, as long as each team is represented in it.
7302 @node Information Flow, Translating plural forms, Organization, Translators
7303 @section Information Flow
7305 @strong{ NOTE: } This documentation section is outdated and needs to be
7308 There will surely be some discussion about this messages after the
7309 packages are finally released. If people now send you some proposals
7310 for better messages, how do you proceed? Jim, please note that
7311 right now, as I put forward nearly a dozen of localizable programs, I
7312 receive both the translations and the coordination concerns about them.
7314 If I put one of my things to pretest, Ulrich receives the announcement
7315 and passes it on to the German team, who make last minute revisions.
7316 Then he submits the translation files to me @emph{as the maintainer}.
7317 For free packages I do not maintain, I would not even hear about it.
7318 This scheme could be made to work for the whole Translation Project,
7319 I think. For security reasons, maybe Ulrich (national coordinators,
7320 in fact) should update central registry kept at the Translation Project
7321 (Jim, me, or Len's recruits) once in a while.
7323 In December/January, I was aggressively ready to internationalize
7324 all of GNU, giving myself the duty of one small GNU package per week
7325 or so, taking many weeks or months for bigger packages. But it does
7326 not work this way. I first did all the things I'm responsible for.
7327 I've nothing against some missionary work on other maintainers, but
7328 I'm also losing a lot of energy over it---same debates over again.
7330 And when the first localized packages are released we'll get a lot of
7331 responses about ugly translations :-). Surely, and we need to have
7332 beforehand a fairly good idea about how to handle the information
7333 flow between the national teams and the package maintainers.
7335 Please start saving somewhere a quick history of each PO file. I know
7336 for sure that the file format will change, allowing for comments.
7337 It would be nice that each file has a kind of log, and references for
7338 those who want to submit comments or gripes, or otherwise contribute.
7339 I sent a proposal for a fast and flexible format, but it is not
7340 receiving acceptance yet by the GNU deciders. I'll tell you when I
7341 have more information about this.
7343 @node Translating plural forms, Prioritizing messages, Information Flow, Translators
7344 @section Translating plural forms
7346 @cindex plural forms, translating
7347 Suppose you are translating a PO file, and it contains an entry like this:
7351 msgid "One file removed"
7352 msgid_plural "%d files removed"
7358 What does this mean? How do you fill it in?
7360 Such an entry denotes a message with plural forms, that is, a message where
7361 the text depends on a cardinal number. The general form of the message,
7362 in English, is the @code{msgid_plural} line. The @code{msgid} line is the
7363 English singular form, that is, the form for when the number is equal to 1.
7364 More details about plural forms are explained in @ref{Plural forms}.
7366 The first thing you need to look at is the @code{Plural-Forms} line in the
7367 header entry of the PO file. It contains the number of plural forms and a
7368 formula. If the PO file does not yet have such a line, you have to add it.
7369 It only depends on the language into which you are translating. You can
7370 get this info by using the @code{msginit} command (see @ref{Creating}) --
7371 it contains a database of known plural formulas -- or by asking other
7372 members of your translation team.
7374 Suppose the line looks as follows:
7377 "Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n%10>=2 && n"
7378 "%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;\n"
7381 It's logically one line; recall that the PO file formatting is allowed to
7382 break long lines so that each physical line fits in 80 monospaced columns.
7384 The value of @code{nplurals} here tells you that there are three plural
7385 forms. The first thing you need to do is to ensure that the entry contains
7386 an @code{msgstr} line for each of the forms:
7390 msgid "One file removed"
7391 msgid_plural "%d files removed"
7397 Then translate the @code{msgid_plural} line and fill it in into each
7402 msgid "One file removed"
7403 msgid_plural "%d files removed"
7404 msgstr[0] "%d slika uklonjenih"
7405 msgstr[1] "%d slika uklonjenih"
7406 msgstr[2] "%d slika uklonjenih"
7409 Now you can refine the translation so that it matches the plural form.
7410 According to the formula above, @code{msgstr[0]} is used when the number
7411 ends in 1 but does not end in 11; @code{msgstr[1]} is used when the number
7412 ends in 2, 3, 4, but not in 12, 13, 14; and @code{msgstr[2]} is used in
7413 all other cases. With this knowledge, you can refine the translations:
7417 msgid "One file removed"
7418 msgid_plural "%d files removed"
7419 msgstr[0] "%d slika je uklonjena"
7420 msgstr[1] "%d datoteke uklonjenih"
7421 msgstr[2] "%d slika uklonjenih"
7424 You noticed that in the English singular form (@code{msgid}) the number
7425 placeholder could be omitted and replaced by the numeral word ``one''.
7426 Can you do this in your translation as well?
7429 msgstr[0] "jednom datotekom je uklonjen"
7433 Well, it depends on whether @code{msgstr[0]} applies only to the number 1,
7434 or to other numbers as well. If, according to the plural formula,
7435 @code{msgstr[0]} applies only to @code{n == 1}, then you can use the
7436 specialized translation without the number placeholder. In our case,
7437 however, @code{msgstr[0]} also applies to the numbers 21, 31, 41, etc.,
7438 and therefore you cannot omit the placeholder.
7440 @node Prioritizing messages, , Translating plural forms, Translators
7441 @section Prioritizing messages: How to determine which messages to translate first
7443 A translator sometimes has only a limited amount of time per week to
7444 spend on a package, and some packages have quite large message catalogs
7445 (over 1000 messages). Therefore she wishes to translate the messages
7446 first that are the most visible to the user, or that occur most frequently.
7447 This section describes how to determine these "most urgent" messages.
7448 It also applies to determine the "next most urgent" messages after the
7449 message catalog has already been partially translated.
7451 In a first step, she uses the programs like a user would do. While she
7452 does this, the GNU @code{gettext} library logs into a file the not yet
7453 translated messages for which a translation was requested from the program.
7455 In a second step, she uses the PO mode to translate precisely this set
7458 @vindex GETTEXT_LOG_UNTRANSLATED@r{, environment variable}
7459 Here a more details. The GNU @code{libintl} library (but not the
7460 corresponding functions in GNU @code{libc}) supports an environment variable
7461 @code{GETTEXT_LOG_UNTRANSLATED}. The GNU @code{libintl} library will
7462 log into this file the messages for which @code{gettext()} and related
7463 functions couldn't find the translation. If the file doesn't exist, it
7464 will be created as needed. On systems with GNU @code{libc} a shared library
7465 @samp{preloadable_libintl.so} is provided that can be used with the ELF
7466 @samp{LD_PRELOAD} mechanism.
7468 So, in the first step, the translator uses these commands on systems with
7472 $ LD_PRELOAD=/usr/local/lib/preloadable_libintl.so
7474 $ GETTEXT_LOG_UNTRANSLATED=$HOME/gettextlogused
7475 $ export GETTEXT_LOG_UNTRANSLATED
7479 and these commands on other systems:
7482 $ GETTEXT_LOG_UNTRANSLATED=$HOME/gettextlogused
7483 $ export GETTEXT_LOG_UNTRANSLATED
7486 Then she uses and peruses the programs. (It is a good and recommended
7487 practice to use the programs for which you provide translations: it
7488 gives you the needed context.) When done, she removes the environment
7493 $ unset GETTEXT_LOG_UNTRANSLATED
7496 The second step starts with removing duplicates:
7499 $ msguniq $HOME/gettextlogused > missing.po
7502 The result is a PO file, but needs some preprocessing before a PO file editor
7503 can be used with it. First, it is a multi-domain PO file, containing
7504 messages from many translation domains. Second, it lacks all translator
7505 comments and source references. Here is how to get a list of the affected
7506 translation domains:
7509 $ sed -n -e 's,^domain "\(.*\)"$,\1,p' < missing.po | sort | uniq
7512 Then the translator can handle the domains one by one. For simplicity,
7513 let's use environment variables to denote the language, domain and source
7517 $ lang=nl # your language
7518 $ domain=coreutils # the name of the domain to be handled
7519 $ package=/usr/src/gnu/coreutils-4.5.4 # the package where it comes from
7522 She takes the latest copy of @file{$lang.po} from the Translation Project,
7523 or from the package (in most cases, @file{$package/po/$lang.po}), or
7524 creates a fresh one if she's the first translator (see @ref{Creating}).
7525 She then uses the following commands to mark the not urgent messages as
7526 "obsolete". (This doesn't mean that these messages - translated and
7527 untranslated ones - will go away. It simply means that the PO file editor
7528 will ignore them in the following editing session.)
7531 $ msggrep --domain=$domain missing.po | grep -v '^domain' \
7532 > $domain-missing.po
7533 $ msgattrib --set-obsolete --ignore-file $domain-missing.po $domain.$lang.po \
7534 > $domain.$lang-urgent.po
7537 The she translates @file{$domain.$lang-urgent.po} by use of a PO file editor
7539 (FIXME: I don't know whether @code{KBabel} and @code{gtranslator} also
7540 preserve obsolete messages, as they should.)
7541 Finally she restores the not urgent messages (with their earlier
7542 translations, for those which were already translated) through this command:
7545 $ msgmerge --no-fuzzy-matching $domain.$lang-urgent.po $package/po/$domain.pot \
7549 Then she can submit @file{$domain.$lang.po} and proceed to the next domain.
7551 @node Maintainers, Installers, Translators, Top
7552 @chapter The Maintainer's View
7553 @cindex package maintainer's view of @code{gettext}
7555 The maintainer of a package has many responsibilities. One of them
7556 is ensuring that the package will install easily on many platforms,
7557 and that the magic we described earlier (@pxref{Users}) will work
7558 for installers and end users.
7560 Of course, there are many possible ways by which GNU @code{gettext}
7561 might be integrated in a distribution, and this chapter does not cover
7562 them in all generality. Instead, it details one possible approach which
7563 is especially adequate for many free software distributions following GNU
7564 standards, or even better, Gnits standards, because GNU @code{gettext}
7565 is purposely for helping the internationalization of the whole GNU
7566 project, and as many other good free packages as possible. So, the
7567 maintainer's view presented here presumes that the package already has
7568 a @file{configure.ac} file and uses GNU Autoconf.
7570 Nevertheless, GNU @code{gettext} may surely be useful for free packages
7571 not following GNU standards and conventions, but the maintainers of such
7572 packages might have to show imagination and initiative in organizing
7573 their distributions so @code{gettext} work for them in all situations.
7574 There are surely many, out there.
7576 Even if @code{gettext} methods are now stabilizing, slight adjustments
7577 might be needed between successive @code{gettext} versions, so you
7578 should ideally revise this chapter in subsequent releases, looking
7582 * Flat and Non-Flat:: Flat or Non-Flat Directory Structures
7583 * Prerequisites:: Prerequisite Works
7584 * gettextize Invocation:: Invoking the @code{gettextize} Program
7585 * Adjusting Files:: Files You Must Create or Alter
7586 * autoconf macros:: Autoconf macros for use in @file{configure.ac}
7587 * Version Control Issues::
7588 * Release Management:: Creating a Distribution Tarball
7591 @node Flat and Non-Flat, Prerequisites, Maintainers, Maintainers
7592 @section Flat or Non-Flat Directory Structures
7594 Some free software packages are distributed as @code{tar} files which unpack
7595 in a single directory, these are said to be @dfn{flat} distributions.
7596 Other free software packages have a one level hierarchy of subdirectories, using
7597 for example a subdirectory named @file{doc/} for the Texinfo manual and
7598 man pages, another called @file{lib/} for holding functions meant to
7599 replace or complement C libraries, and a subdirectory @file{src/} for
7600 holding the proper sources for the package. These other distributions
7601 are said to be @dfn{non-flat}.
7603 We cannot say much about flat distributions. A flat
7604 directory structure has the disadvantage of increasing the difficulty
7605 of updating to a new version of GNU @code{gettext}. Also, if you have
7606 many PO files, this could somewhat pollute your single directory.
7607 Also, GNU @code{gettext}'s libintl sources consist of C sources, shell
7608 scripts, @code{sed} scripts and complicated Makefile rules, which don't
7609 fit well into an existing flat structure. For these reasons, we
7610 recommend to use non-flat approach in this case as well.
7612 Maybe because GNU @code{gettext} itself has a non-flat structure,
7613 we have more experience with this approach, and this is what will be
7614 described in the remaining of this chapter. Some maintainers might
7615 use this as an opportunity to unflatten their package structure.
7617 @node Prerequisites, gettextize Invocation, Flat and Non-Flat, Maintainers
7618 @section Prerequisite Works
7619 @cindex converting a package to use @code{gettext}
7620 @cindex migration from earlier versions of @code{gettext}
7621 @cindex upgrading to new versions of @code{gettext}
7623 There are some works which are required for using GNU @code{gettext}
7624 in one of your package. These works have some kind of generality
7625 that escape the point by point descriptions used in the remainder
7626 of this chapter. So, we describe them here.
7630 Before attempting to use @code{gettextize} you should install some
7631 other packages first.
7632 Ensure that recent versions of GNU @code{m4}, GNU Autoconf and GNU
7633 @code{gettext} are already installed at your site, and if not, proceed
7634 to do this first. If you get to install these things, beware that
7635 GNU @code{m4} must be fully installed before GNU Autoconf is even
7638 To further ease the task of a package maintainer the @code{automake}
7639 package was designed and implemented. GNU @code{gettext} now uses this
7640 tool and the @file{Makefile}s in the @file{intl/} and @file{po/}
7641 therefore know about all the goals necessary for using @code{automake}
7642 and @file{libintl} in one project.
7644 Those four packages are only needed by you, as a maintainer; the
7645 installers of your own package and end users do not really need any of
7646 GNU @code{m4}, GNU Autoconf, GNU @code{gettext}, or GNU @code{automake}
7647 for successfully installing and running your package, with messages
7648 properly translated. But this is not completely true if you provide
7649 internationalized shell scripts within your own package: GNU
7650 @code{gettext} shall then be installed at the user site if the end users
7651 want to see the translation of shell script messages.
7654 Your package should use Autoconf and have a @file{configure.ac} or
7655 @file{configure.in} file.
7656 If it does not, you have to learn how. The Autoconf documentation
7657 is quite well written, it is a good idea that you print it and get
7661 Your C sources should have already been modified according to
7662 instructions given earlier in this manual. @xref{Sources}.
7665 Your @file{po/} directory should receive all PO files submitted to you
7666 by the translator teams, each having @file{@var{ll}.po} as a name.
7667 This is not usually easy to get translation
7668 work done before your package gets internationalized and available!
7669 Since the cycle has to start somewhere, the easiest for the maintainer
7670 is to start with absolutely no PO files, and wait until various
7671 translator teams get interested in your package, and submit PO files.
7675 It is worth adding here a few words about how the maintainer should
7676 ideally behave with PO files submissions. As a maintainer, your role is
7677 to authenticate the origin of the submission as being the representative
7678 of the appropriate translating teams of the Translation Project (forward
7679 the submission to @file{coordinator@@translationproject.org} in case of doubt),
7680 to ensure that the PO file format is not severely broken and does not
7681 prevent successful installation, and for the rest, to merely put these
7682 PO files in @file{po/} for distribution.
7684 As a maintainer, you do not have to take on your shoulders the
7685 responsibility of checking if the translations are adequate or
7686 complete, and should avoid diving into linguistic matters. Translation
7687 teams drive themselves and are fully responsible of their linguistic
7688 choices for the Translation Project. Keep in mind that translator teams are @emph{not}
7689 driven by maintainers. You can help by carefully redirecting all
7690 communications and reports from users about linguistic matters to the
7691 appropriate translation team, or explain users how to reach or join
7692 their team. The simplest might be to send them the @file{ABOUT-NLS} file.
7694 Maintainers should @emph{never ever} apply PO file bug reports
7695 themselves, short-cutting translation teams. If some translator has
7696 difficulty to get some of her points through her team, it should not be
7697 an option for her to directly negotiate translations with maintainers.
7698 Teams ought to settle their problems themselves, if any. If you, as
7699 a maintainer, ever think there is a real problem with a team, please
7700 never try to @emph{solve} a team's problem on your own.
7702 @node gettextize Invocation, Adjusting Files, Prerequisites, Maintainers
7703 @section Invoking the @code{gettextize} Program
7705 @include gettextize.texi
7707 @node Adjusting Files, autoconf macros, gettextize Invocation, Maintainers
7708 @section Files You Must Create or Alter
7709 @cindex @code{gettext} files
7711 Besides files which are automatically added through @code{gettextize},
7712 there are many files needing revision for properly interacting with
7713 GNU @code{gettext}. If you are closely following GNU standards for
7714 Makefile engineering and auto-configuration, the adaptations should
7715 be easier to achieve. Here is a point by point description of the
7716 changes needed in each.
7718 So, here comes a list of files, each one followed by a description of
7719 all alterations it needs. Many examples are taken out from the GNU
7720 @code{gettext} @value{VERSION} distribution itself, or from the GNU
7721 @code{hello} distribution (@uref{http://www.gnu.org/software/hello}).
7722 You may indeed refer to the source code of the GNU @code{gettext} and
7723 GNU @code{hello} packages, as they are intended to be good examples for
7724 using GNU gettext functionality.
7727 * po/POTFILES.in:: @file{POTFILES.in} in @file{po/}
7728 * po/LINGUAS:: @file{LINGUAS} in @file{po/}
7729 * po/Makevars:: @file{Makevars} in @file{po/}
7730 * po/Rules-*:: Extending @file{Makefile} in @file{po/}
7731 * configure.ac:: @file{configure.ac} at top level
7732 * config.guess:: @file{config.guess}, @file{config.sub} at top level
7733 * mkinstalldirs:: @file{mkinstalldirs} at top level
7734 * aclocal:: @file{aclocal.m4} at top level
7735 * acconfig:: @file{acconfig.h} at top level
7736 * config.h.in:: @file{config.h.in} at top level
7737 * Makefile:: @file{Makefile.in} at top level
7738 * src/Makefile:: @file{Makefile.in} in @file{src/}
7739 * lib/gettext.h:: @file{gettext.h} in @file{lib/}
7742 @node po/POTFILES.in, po/LINGUAS, Adjusting Files, Adjusting Files
7743 @subsection @file{POTFILES.in} in @file{po/}
7744 @cindex @file{POTFILES.in} file
7746 The @file{po/} directory should receive a file named
7747 @file{POTFILES.in}. This file tells which files, among all program
7748 sources, have marked strings needing translation. Here is an example
7753 # List of source files containing translatable strings.
7754 # Copyright (C) 1995 Free Software Foundation, Inc.
7756 # Common library files
7761 # Package source files
7769 Hash-marked comments and white lines are ignored. All other lines
7770 list those source files containing strings marked for translation
7771 (@pxref{Mark Keywords}), in a notation relative to the top level
7772 of your whole distribution, rather than the location of the
7773 @file{POTFILES.in} file itself.
7775 When a C file is automatically generated by a tool, like @code{flex} or
7776 @code{bison}, that doesn't introduce translatable strings by itself,
7777 it is recommended to list in @file{po/POTFILES.in} the real source file
7778 (ending in @file{.l} in the case of @code{flex}, or in @file{.y} in the
7779 case of @code{bison}), not the generated C file.
7781 @node po/LINGUAS, po/Makevars, po/POTFILES.in, Adjusting Files
7782 @subsection @file{LINGUAS} in @file{po/}
7783 @cindex @file{LINGUAS} file
7785 The @file{po/} directory should also receive a file named
7786 @file{LINGUAS}. This file contains the list of available translations.
7787 It is a whitespace separated list. Hash-marked comments and white lines
7788 are ignored. Here is an example file:
7792 # Set of available languages.
7798 This example means that German and French PO files are available, so
7799 that these languages are currently supported by your package. If you
7800 want to further restrict, at installation time, the set of installed
7801 languages, this should not be done by modifying the @file{LINGUAS} file,
7802 but rather by using the @code{LINGUAS} environment variable
7803 (@pxref{Installers}).
7805 It is recommended that you add the "languages" @samp{en@@quot} and
7806 @samp{en@@boldquot} to the @code{LINGUAS} file. @code{en@@quot} is a
7807 variant of English message catalogs (@code{en}) which uses real quotation
7808 marks instead of the ugly looking asymmetric ASCII substitutes @samp{`}
7809 and @samp{'}. @code{en@@boldquot} is a variant of @code{en@@quot} that
7810 additionally outputs quoted pieces of text in a bold font, when used in
7811 a terminal emulator which supports the VT100 escape sequences (such as
7812 @code{xterm} or the Linux console, but not Emacs in @kbd{M-x shell} mode).
7814 These extra message catalogs @samp{en@@quot} and @samp{en@@boldquot}
7815 are constructed automatically, not by translators; to support them, you
7816 need the files @file{Rules-quot}, @file{quot.sed}, @file{boldquot.sed},
7817 @file{en@@quot.header}, @file{en@@boldquot.header}, @file{insert-header.sin}
7818 in the @file{po/} directory. You can copy them from GNU gettext's @file{po/}
7819 directory; they are also installed by running @code{gettextize}.
7821 @node po/Makevars, po/Rules-*, po/LINGUAS, Adjusting Files
7822 @subsection @file{Makevars} in @file{po/}
7823 @cindex @file{Makevars} file
7825 The @file{po/} directory also has a file named @file{Makevars}. It
7826 contains variables that are specific to your project. @file{po/Makevars}
7827 gets inserted into the @file{po/Makefile} when the latter is created.
7828 The variables thus take effect when the POT file is created or updated,
7829 and when the message catalogs get installed.
7831 The first three variables can be left unmodified if your package has a
7832 single message domain and, accordingly, a single @file{po/} directory.
7833 Only packages which have multiple @file{po/} directories at different
7834 locations need to adjust the three first variables defined in
7837 As an alternative to the @code{XGETTEXT_OPTIONS} variables, it is also
7838 possible to specify @code{xgettext} options through the
7839 @code{AM_XGETTEXT_OPTION} autoconf macro. See @ref{AM_XGETTEXT_OPTION}.
7841 @node po/Rules-*, configure.ac, po/Makevars, Adjusting Files
7842 @subsection Extending @file{Makefile} in @file{po/}
7843 @cindex @file{Makefile.in.in} extensions
7845 All files called @file{Rules-*} in the @file{po/} directory get appended to
7846 the @file{po/Makefile} when it is created. They present an opportunity to
7847 add rules for special PO files to the Makefile, without needing to mess
7848 with @file{po/Makefile.in.in}.
7850 @cindex quotation marks
7851 @vindex LANGUAGE@r{, environment variable}
7852 GNU gettext comes with a @file{Rules-quot} file, containing rules for
7853 building catalogs @file{en@@quot.po} and @file{en@@boldquot.po}. The
7854 effect of @file{en@@quot.po} is that people who set their @code{LANGUAGE}
7855 environment variable to @samp{en@@quot} will get messages with proper
7856 looking symmetric Unicode quotation marks instead of abusing the ASCII
7857 grave accent and the ASCII apostrophe for indicating quotations. To
7858 enable this catalog, simply add @code{en@@quot} to the @file{po/LINGUAS}
7859 file. The effect of @file{en@@boldquot.po} is that people who set
7860 @code{LANGUAGE} to @samp{en@@boldquot} will get not only proper quotation
7861 marks, but also the quoted text will be shown in a bold font on terminals
7862 and consoles. This catalog is useful only for command-line programs, not
7863 GUI programs. To enable it, similarly add @code{en@@boldquot} to the
7864 @file{po/LINGUAS} file.
7866 Similarly, you can create rules for building message catalogs for the
7867 @file{sr@@latin} locale -- Serbian written with the Latin alphabet --
7868 from those for the @file{sr} locale -- Serbian written with Cyrillic
7869 letters. See @ref{msgfilter Invocation}.
7871 @node configure.ac, config.guess, po/Rules-*, Adjusting Files
7872 @subsection @file{configure.ac} at top level
7874 @file{configure.ac} or @file{configure.in} - this is the source from which
7875 @code{autoconf} generates the @file{configure} script.
7878 @item Declare the package and version.
7879 @cindex package and version declaration in @file{configure.ac}
7881 This is done by a set of lines like these:
7885 VERSION=@value{VERSION}
7886 AC_DEFINE_UNQUOTED(PACKAGE, "$PACKAGE")
7887 AC_DEFINE_UNQUOTED(VERSION, "$VERSION")
7893 or, if you are using GNU @code{automake}, by a line like this:
7896 AM_INIT_AUTOMAKE(gettext, @value{VERSION})
7900 Of course, you replace @samp{gettext} with the name of your package,
7901 and @samp{@value{VERSION}} by its version numbers, exactly as they
7902 should appear in the packaged @code{tar} file name of your distribution
7903 (@file{gettext-@value{VERSION}.tar.gz}, here).
7905 @item Check for internationalization support.
7907 Here is the main @code{m4} macro for triggering internationalization
7908 support. Just add this line to @file{configure.ac}:
7915 This call is purposely simple, even if it generates a lot of configure
7916 time checking and actions.
7918 If you have suppressed the @file{intl/} subdirectory by calling
7919 @code{gettextize} without @samp{--intl} option, this call should read
7922 AM_GNU_GETTEXT([external])
7925 @item Have output files created.
7927 The @code{AC_OUTPUT} directive, at the end of your @file{configure.ac}
7928 file, needs to be modified in two ways:
7931 AC_OUTPUT([@var{existing configuration files} intl/Makefile po/Makefile.in],
7932 [@var{existing additional actions}])
7935 The modification to the first argument to @code{AC_OUTPUT} asks
7936 for substitution in the @file{intl/} and @file{po/} directories.
7937 Note the @samp{.in} suffix used for @file{po/} only. This is because
7938 the distributed file is really @file{po/Makefile.in.in}.
7940 If you have suppressed the @file{intl/} subdirectory by calling
7941 @code{gettextize} without @samp{--intl} option, then you don't need to
7942 add @code{intl/Makefile} to the @code{AC_OUTPUT} line.
7946 If, after doing the recommended modifications, a command like
7947 @samp{aclocal -I m4} or @samp{autoconf} or @samp{autoreconf} fails with
7948 a trace similar to this:
7951 configure.ac:44: warning: AC_COMPILE_IFELSE was called before AC_GNU_SOURCE
7952 ../../lib/autoconf/specific.m4:335: AC_GNU_SOURCE is expanded from...
7953 m4/lock.m4:224: gl_LOCK is expanded from...
7954 m4/gettext.m4:571: gt_INTL_SUBDIR_CORE is expanded from...
7955 m4/gettext.m4:472: AM_INTL_SUBDIR is expanded from...
7956 m4/gettext.m4:347: AM_GNU_GETTEXT is expanded from...
7957 configure.ac:44: the top level
7958 configure.ac:44: warning: AC_RUN_IFELSE was called before AC_GNU_SOURCE
7962 you need to add an explicit invocation of @samp{AC_GNU_SOURCE} in the
7963 @file{configure.ac} file - after @samp{AC_PROG_CC} but before
7964 @samp{AM_GNU_GETTEXT}, most likely very close to the @samp{AC_PROG_CC}
7965 invocation. This is necessary because of ordering restrictions imposed
7968 @node config.guess, mkinstalldirs, configure.ac, Adjusting Files
7969 @subsection @file{config.guess}, @file{config.sub} at top level
7971 If you haven't suppressed the @file{intl/} subdirectory,
7972 you need to add the GNU @file{config.guess} and @file{config.sub} files
7973 to your distribution. They are needed because the @file{intl/} directory
7974 has platform dependent support for determining the locale's character
7975 encoding and therefore needs to identify the platform.
7977 You can obtain the newest version of @file{config.guess} and
7978 @file{config.sub} from the @samp{config} project at
7979 @file{http://savannah.gnu.org/}. The commands to fetch them are
7981 $ wget -O config.guess 'http://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.guess;hb=HEAD'
7982 $ wget -O config.sub 'http://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.sub;hb=HEAD'
7985 Less recent versions are also contained in the GNU @code{automake} and
7986 GNU @code{libtool} packages.
7988 Normally, @file{config.guess} and @file{config.sub} are put at the
7989 top level of a distribution. But it is also possible to put them in a
7990 subdirectory, altogether with other configuration support files like
7991 @file{install-sh}, @file{ltconfig}, @file{ltmain.sh} or @file{missing}.
7992 All you need to do, other than moving the files, is to add the following line
7993 to your @file{configure.ac}.
7996 AC_CONFIG_AUX_DIR([@var{subdir}])
7999 @node mkinstalldirs, aclocal, config.guess, Adjusting Files
8000 @subsection @file{mkinstalldirs} at top level
8001 @cindex @file{mkinstalldirs} file
8003 With earlier versions of GNU gettext, you needed to add the GNU
8004 @file{mkinstalldirs} script to your distribution. This is not needed any
8005 more. You can remove it if you not also using an automake version older than
8008 @node aclocal, acconfig, mkinstalldirs, Adjusting Files
8009 @subsection @file{aclocal.m4} at top level
8010 @cindex @file{aclocal.m4} file
8012 If you do not have an @file{aclocal.m4} file in your distribution,
8013 the simplest is to concatenate the files @file{codeset.m4}, @file{fcntl-o.m4},
8014 @file{gettext.m4}, @file{glibc2.m4}, @file{glibc21.m4}, @file{iconv.m4},
8015 @file{intdiv0.m4}, @file{intl.m4}, @file{intldir.m4}, @file{intlmacosx.m4},
8016 @file{intmax.m4}, @file{inttypes_h.m4}, @file{inttypes-pri.m4},
8017 @file{lcmessage.m4}, @file{lib-ld.m4}, @file{lib-link.m4},
8018 @file{lib-prefix.m4}, @file{lock.m4}, @file{longlong.m4}, @file{nls.m4},
8019 @file{po.m4}, @file{printf-posix.m4}, @file{progtest.m4}, @file{size_max.m4},
8020 @file{stdint_h.m4}, @file{threadlib.m4}, @file{uintmax_t.m4},
8021 @file{visibility.m4}, @file{wchar_t.m4}, @file{wint_t.m4}, @file{xsize.m4}
8022 from GNU @code{gettext}'s
8023 @file{m4/} directory into a single file. If you have suppressed the
8024 @file{intl/} directory, only @file{gettext.m4}, @file{iconv.m4},
8025 @file{lib-ld.m4}, @file{lib-link.m4}, @file{lib-prefix.m4},
8026 @file{nls.m4}, @file{po.m4}, @file{progtest.m4} need to be concatenated.
8028 If you are not using GNU @code{automake} 1.8 or newer, you will need to
8029 add a file @file{mkdirp.m4} from a newer automake distribution to the
8030 list of files above.
8032 If you already have an @file{aclocal.m4} file, then you will have
8033 to merge the said macro files into your @file{aclocal.m4}. Note that if
8034 you are upgrading from a previous release of GNU @code{gettext}, you
8035 should most probably @emph{replace} the macros (@code{AM_GNU_GETTEXT},
8036 etc.), as they usually
8037 change a little from one release of GNU @code{gettext} to the next.
8038 Their contents may vary as we get more experience with strange systems
8041 If you are using GNU @code{automake} 1.5 or newer, it is enough to put
8042 these macro files into a subdirectory named @file{m4/} and add the line
8045 ACLOCAL_AMFLAGS = -I m4
8049 to your top level @file{Makefile.am}.
8051 If you are using GNU @code{automake} 1.10 or newer, it is even easier:
8055 ACLOCAL_AMFLAGS = --install -I m4
8059 to your top level @file{Makefile.am}, and run @samp{aclocal --install -I m4}.
8060 This will copy the needed files to the @file{m4/} subdirectory automatically,
8061 before updating @file{aclocal.m4}.
8063 These macros check for the internationalization support functions
8064 and related informations. Hopefully, once stabilized, these macros
8065 might be integrated in the standard Autoconf set, because this
8066 piece of @code{m4} code will be the same for all projects using GNU
8069 @node acconfig, config.h.in, aclocal, Adjusting Files
8070 @subsection @file{acconfig.h} at top level
8071 @cindex @file{acconfig.h} file
8073 Earlier GNU @code{gettext} releases required to put definitions for
8074 @code{ENABLE_NLS}, @code{HAVE_GETTEXT} and @code{HAVE_LC_MESSAGES},
8075 @code{HAVE_STPCPY}, @code{PACKAGE} and @code{VERSION} into an
8076 @file{acconfig.h} file. This is not needed any more; you can remove
8077 them from your @file{acconfig.h} file unless your package uses them
8078 independently from the @file{intl/} directory.
8080 @node config.h.in, Makefile, acconfig, Adjusting Files
8081 @subsection @file{config.h.in} at top level
8082 @cindex @file{config.h.in} file
8084 The include file template that holds the C macros to be defined by
8085 @code{configure} is usually called @file{config.h.in} and may be
8086 maintained either manually or automatically.
8088 If @code{gettextize} has created an @file{intl/} directory, this file
8089 must be called @file{config.h.in} and must be at the top level. If,
8090 however, you have suppressed the @file{intl/} directory by calling
8091 @code{gettextize} without @samp{--intl} option, then you can choose the
8092 name of this file and its location freely.
8094 If it is maintained automatically, by use of the @samp{autoheader}
8095 program, you need to do nothing about it. This is the case in particular
8096 if you are using GNU @code{automake}.
8098 If it is maintained manually, and if @code{gettextize} has created an
8099 @file{intl/} directory, you should switch to using @samp{autoheader}.
8100 The list of C macros to be added for the sake of the @file{intl/}
8101 directory is just too long to be maintained manually; it also changes
8102 between different versions of GNU @code{gettext}.
8104 If it is maintained manually, and if on the other hand you have
8105 suppressed the @file{intl/} directory by calling @code{gettextize}
8106 without @samp{--intl} option, then you can get away by adding the
8107 following lines to @file{config.h.in}:
8110 /* Define to 1 if translation of program messages to the user's
8111 native language is requested. */
8115 @node Makefile, src/Makefile, config.h.in, Adjusting Files
8116 @subsection @file{Makefile.in} at top level
8118 Here are a few modifications you need to make to your main, top-level
8119 @file{Makefile.in} file.
8123 Add the following lines near the beginning of your @file{Makefile.in},
8124 so the @samp{dist:} goal will work properly (as explained further down):
8127 PACKAGE = @@PACKAGE@@
8128 VERSION = @@VERSION@@
8132 Add file @file{ABOUT-NLS} to the @code{DISTFILES} definition, so the file gets
8136 Wherever you process subdirectories in your @file{Makefile.in}, be sure
8137 you also process the subdirectories @samp{intl} and @samp{po}. Special
8138 rules in the @file{Makefiles} take care for the case where no
8139 internationalization is wanted.
8141 If you are using Makefiles, either generated by automake, or hand-written
8142 so they carefully follow the GNU coding standards, the effected goals for
8143 which the new subdirectories must be handled include @samp{installdirs},
8144 @samp{install}, @samp{uninstall}, @samp{clean}, @samp{distclean}.
8146 Here is an example of a canonical order of processing. In this
8147 example, we also define @code{SUBDIRS} in @code{Makefile.in} for it
8148 to be further used in the @samp{dist:} goal.
8151 SUBDIRS = doc intl lib src po
8154 Note that you must arrange for @samp{make} to descend into the
8155 @code{intl} directory before descending into other directories containing
8156 code which make use of the @code{libintl.h} header file. For this
8157 reason, here we mention @code{intl} before @code{lib} and @code{src}.
8160 A delicate point is the @samp{dist:} goal, as both
8161 @file{intl/Makefile} and @file{po/Makefile} will later assume that the
8162 proper directory has been set up from the main @file{Makefile}. Here is
8163 an example at what the @samp{dist:} goal might look like:
8166 distdir = $(PACKAGE)-$(VERSION)
8170 chmod 777 $(distdir)
8171 for file in $(DISTFILES); do \
8172 ln $$file $(distdir) 2>/dev/null || cp -p $$file $(distdir); \
8174 for subdir in $(SUBDIRS); do \
8175 mkdir $(distdir)/$$subdir || exit 1; \
8176 chmod 777 $(distdir)/$$subdir; \
8177 (cd $$subdir && $(MAKE) $@@) || exit 1; \
8179 tar chozf $(distdir).tar.gz $(distdir)
8185 Note that if you are using GNU @code{automake}, @file{Makefile.in} is
8186 automatically generated from @file{Makefile.am}, and all needed changes
8187 to @file{Makefile.am} are already made by running @samp{gettextize}.
8189 @node src/Makefile, lib/gettext.h, Makefile, Adjusting Files
8190 @subsection @file{Makefile.in} in @file{src/}
8192 Some of the modifications made in the main @file{Makefile.in} will
8193 also be needed in the @file{Makefile.in} from your package sources,
8194 which we assume here to be in the @file{src/} subdirectory. Here are
8195 all the modifications needed in @file{src/Makefile.in}:
8199 In view of the @samp{dist:} goal, you should have these lines near the
8200 beginning of @file{src/Makefile.in}:
8203 PACKAGE = @@PACKAGE@@
8204 VERSION = @@VERSION@@
8208 If not done already, you should guarantee that @code{top_srcdir}
8209 gets defined. This will serve for @code{cpp} include files. Just add
8213 top_srcdir = @@top_srcdir@@
8217 You might also want to define @code{subdir} as @samp{src}, later
8218 allowing for almost uniform @samp{dist:} goals in all your
8219 @file{Makefile.in}. At list, the @samp{dist:} goal below assume that
8227 The @code{main} function of your program will normally call
8228 @code{bindtextdomain} (see @pxref{Triggering}), like this:
8231 bindtextdomain (@var{PACKAGE}, LOCALEDIR);
8232 textdomain (@var{PACKAGE});
8235 To make LOCALEDIR known to the program, add the following lines to
8236 @file{Makefile.in} if you are using Autoconf version 2.60 or newer:
8239 datadir = @@datadir@@
8240 datarootdir= @@datarootdir@@
8241 localedir = @@localedir@@
8242 DEFS = -DLOCALEDIR=\"$(localedir)\" @@DEFS@@
8245 or these lines if your version of Autoconf is older than 2.60:
8248 datadir = @@datadir@@
8249 localedir = $(datadir)/locale
8250 DEFS = -DLOCALEDIR=\"$(localedir)\" @@DEFS@@
8253 Note that @code{@@datadir@@} defaults to @samp{$(prefix)/share}, thus
8254 @code{$(localedir)} defaults to @samp{$(prefix)/share/locale}.
8257 You should ensure that the final linking will use @code{@@LIBINTL@@} or
8258 @code{@@LTLIBINTL@@} as a library. @code{@@LIBINTL@@} is for use without
8259 @code{libtool}, @code{@@LTLIBINTL@@} is for use with @code{libtool}. An
8260 easy way to achieve this is to manage that it gets into @code{LIBS}, like
8264 LIBS = @@LIBINTL@@ @@LIBS@@
8267 In most packages internationalized with GNU @code{gettext}, one will
8268 find a directory @file{lib/} in which a library containing some helper
8269 functions will be build. (You need at least the few functions which the
8270 GNU @code{gettext} Library itself needs.) However some of the functions
8271 in the @file{lib/} also give messages to the user which of course should be
8272 translated, too. Taking care of this, the support library (say
8273 @file{libsupport.a}) should be placed before @code{@@LIBINTL@@} and
8274 @code{@@LIBS@@} in the above example. So one has to write this:
8277 LIBS = ../lib/libsupport.a @@LIBINTL@@ @@LIBS@@
8281 You should also ensure that directory @file{intl/} will be searched for
8282 C preprocessor include files in all circumstances. So, you have to
8283 manage so both @samp{-I../intl} and @samp{-I$(top_srcdir)/intl} will
8284 be given to the C compiler.
8287 Your @samp{dist:} goal has to conform with others. Here is a
8288 reasonable definition for it:
8291 distdir = ../$(PACKAGE)-$(VERSION)/$(subdir)
8292 dist: Makefile $(DISTFILES)
8293 for file in $(DISTFILES); do \
8294 ln $$file $(distdir) 2>/dev/null || cp -p $$file $(distdir) || exit 1; \
8300 Note that if you are using GNU @code{automake}, @file{Makefile.in} is
8301 automatically generated from @file{Makefile.am}, and the first three
8302 changes and the last change are not necessary. The remaining needed
8303 @file{Makefile.am} modifications are the following:
8307 To make LOCALEDIR known to the program, add the following to
8311 <module>_CPPFLAGS = -DLOCALEDIR=\"$(localedir)\"
8315 for each specific module or compilation unit, or
8318 AM_CPPFLAGS = -DLOCALEDIR=\"$(localedir)\"
8321 for all modules and compilation units together. Furthermore, if you are
8322 using an Autoconf version older then 2.60, add this line to define
8326 localedir = $(datadir)/locale
8330 To ensure that the final linking will use @code{@@LIBINTL@@} or
8331 @code{@@LTLIBINTL@@} as a library, add the following to
8335 <program>_LDADD = @@LIBINTL@@
8339 for each specific program, or
8345 for all programs together. Remember that when you use @code{libtool}
8346 to link a program, you need to use @@LTLIBINTL@@ instead of @@LIBINTL@@
8350 If you have an @file{intl/} directory, whose contents is created by
8351 @code{gettextize}, then to ensure that it will be searched for
8352 C preprocessor include files in all circumstances, add something like
8353 this to @file{Makefile.am}:
8356 AM_CPPFLAGS = -I../intl -I$(top_srcdir)/intl
8361 @node lib/gettext.h, , src/Makefile, Adjusting Files
8362 @subsection @file{gettext.h} in @file{lib/}
8363 @cindex @file{gettext.h} file
8364 @cindex turning off NLS support
8365 @cindex disabling NLS
8367 Internationalization of packages, as provided by GNU @code{gettext}, is
8368 optional. It can be turned off in two situations:
8372 When the installer has specified @samp{./configure --disable-nls}. This
8373 can be useful when small binaries are more important than features, for
8374 example when building utilities for boot diskettes. It can also be useful
8375 in order to get some specific C compiler warnings about code quality with
8376 some older versions of GCC (older than 3.0).
8379 When the package does not include the @code{intl/} subdirectory, and the
8380 libintl.h header (with its associated libintl library, if any) is not
8381 already installed on the system, it is preferable that the package builds
8382 without internationalization support, rather than to give a compilation
8386 A C preprocessor macro can be used to detect these two cases. Usually,
8387 when @code{libintl.h} was found and not explicitly disabled, the
8388 @code{ENABLE_NLS} macro will be defined to 1 in the autoconf generated
8389 configuration file (usually called @file{config.h}). In the two negative
8390 situations, however, this macro will not be defined, thus it will evaluate
8391 to 0 in C preprocessor expressions.
8393 @cindex include file @file{libintl.h}
8394 @file{gettext.h} is a convenience header file for conditional use of
8395 @file{<libintl.h>}, depending on the @code{ENABLE_NLS} macro. If
8396 @code{ENABLE_NLS} is set, it includes @file{<libintl.h>}; otherwise it
8397 defines no-op substitutes for the libintl.h functions. We recommend
8398 the use of @code{"gettext.h"} over direct use of @file{<libintl.h>},
8399 so that portability to older systems is guaranteed and installers can
8400 turn off internationalization if they want to. In the C code, you will
8404 #include "gettext.h"
8411 #include <libintl.h>
8414 The location of @code{gettext.h} is usually in a directory containing
8415 auxiliary include files. In many GNU packages, there is a directory
8416 @file{lib/} containing helper functions; @file{gettext.h} fits there.
8417 In other packages, it can go into the @file{src} directory.
8419 Do not install the @code{gettext.h} file in public locations. Every
8420 package that needs it should contain a copy of it on its own.
8422 @node autoconf macros, Version Control Issues, Adjusting Files, Maintainers
8423 @section Autoconf macros for use in @file{configure.ac}
8424 @cindex autoconf macros for @code{gettext}
8426 GNU @code{gettext} installs macros for use in a package's
8427 @file{configure.ac} or @file{configure.in}.
8428 @xref{Top, , Introduction, autoconf, The Autoconf Manual}.
8429 The primary macro is, of course, @code{AM_GNU_GETTEXT}.
8432 * AM_GNU_GETTEXT:: AM_GNU_GETTEXT in @file{gettext.m4}
8433 * AM_GNU_GETTEXT_VERSION:: AM_GNU_GETTEXT_VERSION in @file{gettext.m4}
8434 * AM_GNU_GETTEXT_NEED:: AM_GNU_GETTEXT_NEED in @file{gettext.m4}
8435 * AM_GNU_GETTEXT_INTL_SUBDIR:: AM_GNU_GETTEXT_INTL_SUBDIR in @file{intldir.m4}
8436 * AM_PO_SUBDIRS:: AM_PO_SUBDIRS in @file{po.m4}
8437 * AM_XGETTEXT_OPTION:: AM_XGETTEXT_OPTION in @file{po.m4}
8438 * AM_ICONV:: AM_ICONV in @file{iconv.m4}
8441 @node AM_GNU_GETTEXT, AM_GNU_GETTEXT_VERSION, autoconf macros, autoconf macros
8442 @subsection AM_GNU_GETTEXT in @file{gettext.m4}
8444 @amindex AM_GNU_GETTEXT
8445 The @code{AM_GNU_GETTEXT} macro tests for the presence of the GNU gettext
8446 function family in either the C library or a separate @code{libintl}
8447 library (shared or static libraries are both supported) or in the package's
8448 @file{intl/} directory. It also invokes @code{AM_PO_SUBDIRS}, thus preparing
8449 the @file{po/} directories of the package for building.
8451 @code{AM_GNU_GETTEXT} accepts up to three optional arguments. The general
8455 AM_GNU_GETTEXT([@var{intlsymbol}], [@var{needsymbol}], [@var{intldir}])
8458 @c We don't document @var{intlsymbol} = @samp{use-libtool} here, because
8459 @c it is of no use for packages other than GNU gettext itself. (Such packages
8460 @c are not allowed to install the shared libintl. But if they use libtool,
8461 @c then it is in order to install shared libraries that depend on libintl.)
8462 @var{intlsymbol} can be @samp{external} or @samp{no-libtool}. The default
8463 (if it is not specified or empty) is @samp{no-libtool}. @var{intlsymbol}
8464 should be @samp{external} for packages with no @file{intl/} directory.
8465 For packages with an @file{intl/} directory, you can either use an
8466 @var{intlsymbol} equal to @samp{no-libtool}, or you can use @samp{external}
8467 and override by using the macro @code{AM_GNU_GETTEXT_INTL_SUBDIR} elsewhere.
8468 The two ways to specify the existence of an @file{intl/} directory are
8469 equivalent. At build time, a static library
8470 @code{$(top_builddir)/intl/libintl.a} will then be created.
8472 If @var{needsymbol} is specified and is @samp{need-ngettext}, then GNU
8473 gettext implementations (in libc or libintl) without the @code{ngettext()}
8474 function will be ignored. If @var{needsymbol} is specified and is
8475 @samp{need-formatstring-macros}, then GNU gettext implementations that don't
8476 support the ISO C 99 @file{<inttypes.h>} formatstring macros will be ignored.
8477 Only one @var{needsymbol} can be specified. These requirements can also be
8478 specified by using the macro @code{AM_GNU_GETTEXT_NEED} elsewhere. To specify
8479 more than one requirement, just specify the strongest one among them, or
8480 invoke the @code{AM_GNU_GETTEXT_NEED} macro several times. The hierarchy
8481 among the various alternatives is as follows: @samp{need-formatstring-macros}
8482 implies @samp{need-ngettext}.
8484 @var{intldir} is used to find the intl libraries. If empty, the value
8485 @samp{$(top_builddir)/intl/} is used.
8487 The @code{AM_GNU_GETTEXT} macro determines whether GNU gettext is
8488 available and should be used. If so, it sets the @code{USE_NLS} variable
8489 to @samp{yes}; it defines @code{ENABLE_NLS} to 1 in the autoconf
8490 generated configuration file (usually called @file{config.h}); it sets
8491 the variables @code{LIBINTL} and @code{LTLIBINTL} to the linker options
8492 for use in a Makefile (@code{LIBINTL} for use without libtool,
8493 @code{LTLIBINTL} for use with libtool); it adds an @samp{-I} option to
8494 @code{CPPFLAGS} if necessary. In the negative case, it sets
8495 @code{USE_NLS} to @samp{no}; it sets @code{LIBINTL} and @code{LTLIBINTL}
8496 to empty and doesn't change @code{CPPFLAGS}.
8498 The complexities that @code{AM_GNU_GETTEXT} deals with are the following:
8502 @cindex @code{libintl} library
8503 Some operating systems have @code{gettext} in the C library, for example
8504 glibc. Some have it in a separate library @code{libintl}. GNU @code{libintl}
8505 might have been installed as part of the GNU @code{gettext} package.
8508 GNU @code{libintl}, if installed, is not necessarily already in the search
8509 path (@code{CPPFLAGS} for the include file search path, @code{LDFLAGS} for
8510 the library search path).
8513 Except for glibc, the operating system's native @code{gettext} cannot
8514 exploit the GNU mo files, doesn't have the necessary locale dependency
8515 features, and cannot convert messages from the catalog's text encoding
8516 to the user's locale encoding.
8519 GNU @code{libintl}, if installed, is not necessarily already in the
8520 run time library search path. To avoid the need for setting an environment
8521 variable like @code{LD_LIBRARY_PATH}, the macro adds the appropriate
8522 run time search path options to the @code{LIBINTL} and @code{LTLIBINTL}
8523 variables. This works on most systems, but not on some operating systems
8524 with limited shared library support, like SCO.
8527 GNU @code{libintl} relies on POSIX/XSI @code{iconv}. The macro checks for
8528 linker options needed to use iconv and appends them to the @code{LIBINTL}
8529 and @code{LTLIBINTL} variables.
8532 @node AM_GNU_GETTEXT_VERSION, AM_GNU_GETTEXT_NEED, AM_GNU_GETTEXT, autoconf macros
8533 @subsection AM_GNU_GETTEXT_VERSION in @file{gettext.m4}
8535 @amindex AM_GNU_GETTEXT_VERSION
8536 The @code{AM_GNU_GETTEXT_VERSION} macro declares the version number of
8537 the GNU gettext infrastructure that is used by the package.
8539 The use of this macro is optional; only the @code{autopoint} program makes
8540 use of it (@pxref{Version Control Issues}).
8542 @node AM_GNU_GETTEXT_NEED, AM_GNU_GETTEXT_INTL_SUBDIR, AM_GNU_GETTEXT_VERSION, autoconf macros
8543 @subsection AM_GNU_GETTEXT_NEED in @file{gettext.m4}
8545 @amindex AM_GNU_GETTEXT_NEED
8546 The @code{AM_GNU_GETTEXT_NEED} macro declares a constraint regarding the
8547 GNU gettext implementation. The syntax is
8550 AM_GNU_GETTEXT_NEED([@var{needsymbol}])
8553 If @var{needsymbol} is @samp{need-ngettext}, then GNU gettext implementations
8554 (in libc or libintl) without the @code{ngettext()} function will be ignored.
8555 If @var{needsymbol} is @samp{need-formatstring-macros}, then GNU gettext
8556 implementations that don't support the ISO C 99 @file{<inttypes.h>}
8557 formatstring macros will be ignored.
8559 The optional second argument of @code{AM_GNU_GETTEXT} is also taken into
8562 The @code{AM_GNU_GETTEXT_NEED} invocations can occur before or after
8563 the @code{AM_GNU_GETTEXT} invocation; the order doesn't matter.
8565 @node AM_GNU_GETTEXT_INTL_SUBDIR, AM_PO_SUBDIRS, AM_GNU_GETTEXT_NEED, autoconf macros
8566 @subsection AM_GNU_GETTEXT_INTL_SUBDIR in @file{intldir.m4}
8568 @amindex AM_GNU_GETTEXT_INTL_SUBDIR
8569 The @code{AM_GNU_GETTEXT_INTL_SUBDIR} macro specifies that the
8570 @code{AM_GNU_GETTEXT} macro, although invoked with the first argument
8571 @samp{external}, should also prepare for building the @file{intl/}
8574 The @code{AM_GNU_GETTEXT_INTL_SUBDIR} invocation can occur before or after
8575 the @code{AM_GNU_GETTEXT} invocation; the order doesn't matter.
8577 The use of this macro requires GNU automake 1.10 or newer and
8578 GNU autoconf 2.61 or newer.
8580 @node AM_PO_SUBDIRS, AM_XGETTEXT_OPTION, AM_GNU_GETTEXT_INTL_SUBDIR, autoconf macros
8581 @subsection AM_PO_SUBDIRS in @file{po.m4}
8583 @amindex AM_PO_SUBDIRS
8584 The @code{AM_PO_SUBDIRS} macro prepares the @file{po/} directories of the
8585 package for building. This macro should be used in internationalized
8586 programs written in other programming languages than C, C++, Objective C,
8587 for example @code{sh}, @code{Python}, @code{Lisp}. See @ref{Programming
8588 Languages} for a list of programming languages that support localization
8591 The @code{AM_PO_SUBDIRS} macro determines whether internationalization
8592 should be used. If so, it sets the @code{USE_NLS} variable to @samp{yes},
8593 otherwise to @samp{no}. It also determines the right values for Makefile
8594 variables in each @file{po/} directory.
8596 @node AM_XGETTEXT_OPTION, AM_ICONV, AM_PO_SUBDIRS, autoconf macros
8597 @subsection AM_XGETTEXT_OPTION in @file{po.m4}
8599 @amindex AM_XGETTEXT_OPTION
8600 The @code{AM_XGETTEXT_OPTION} macro registers a command-line option to be
8601 used in the invocations of @code{xgettext} in the @file{po/} directories
8604 For example, if you have a source file that defines a function
8605 @samp{error_at_line} whose fifth argument is a format string, you can use
8607 AM_XGETTEXT_OPTION([--flag=error_at_line:5:c-format])
8610 to instruct @code{xgettext} to mark all translatable strings in @samp{gettext}
8611 invocations that occur as fifth argument to this function as @samp{c-format}.
8613 See @ref{xgettext Invocation} for the list of options that @code{xgettext}
8616 The use of this macro is an alternative to the use of the
8617 @samp{XGETTEXT_OPTIONS} variable in @file{po/Makevars}.
8619 @node AM_ICONV, , AM_XGETTEXT_OPTION, autoconf macros
8620 @subsection AM_ICONV in @file{iconv.m4}
8623 The @code{AM_ICONV} macro tests for the presence of the POSIX/XSI
8624 @code{iconv} function family in either the C library or a separate
8625 @code{libiconv} library. If found, it sets the @code{am_cv_func_iconv}
8626 variable to @samp{yes}; it defines @code{HAVE_ICONV} to 1 in the autoconf
8627 generated configuration file (usually called @file{config.h}); it defines
8628 @code{ICONV_CONST} to @samp{const} or to empty, depending on whether the
8629 second argument of @code{iconv()} is of type @samp{const char **} or
8630 @samp{char **}; it sets the variables @code{LIBICONV} and
8631 @code{LTLIBICONV} to the linker options for use in a Makefile
8632 (@code{LIBICONV} for use without libtool, @code{LTLIBICONV} for use with
8633 libtool); it adds an @samp{-I} option to @code{CPPFLAGS} if
8634 necessary. If not found, it sets @code{LIBICONV} and @code{LTLIBICONV} to
8635 empty and doesn't change @code{CPPFLAGS}.
8637 The complexities that @code{AM_ICONV} deals with are the following:
8641 @cindex @code{libiconv} library
8642 Some operating systems have @code{iconv} in the C library, for example
8643 glibc. Some have it in a separate library @code{libiconv}, for example
8644 OSF/1 or FreeBSD. Regardless of the operating system, GNU @code{libiconv}
8645 might have been installed. In that case, it should be used instead of the
8646 operating system's native @code{iconv}.
8649 GNU @code{libiconv}, if installed, is not necessarily already in the search
8650 path (@code{CPPFLAGS} for the include file search path, @code{LDFLAGS} for
8651 the library search path).
8654 GNU @code{libiconv} is binary incompatible with some operating system's
8655 native @code{iconv}, for example on FreeBSD. Use of an @file{iconv.h}
8656 and @file{libiconv.so} that don't fit together would produce program
8660 GNU @code{libiconv}, if installed, is not necessarily already in the
8661 run time library search path. To avoid the need for setting an environment
8662 variable like @code{LD_LIBRARY_PATH}, the macro adds the appropriate
8663 run time search path options to the @code{LIBICONV} variable. This works
8664 on most systems, but not on some operating systems with limited shared
8665 library support, like SCO.
8668 @file{iconv.m4} is distributed with the GNU gettext package because
8669 @file{gettext.m4} relies on it.
8671 @node Version Control Issues, Release Management, autoconf macros, Maintainers
8672 @section Integrating with Version Control Systems
8674 Many projects use version control systems for distributed development
8675 and source backup. This section gives some advice how to manage the
8676 uses of @code{gettextize}, @code{autopoint} and @code{autoconf} on
8677 version controlled files.
8680 * Distributed Development:: Avoiding version mismatch in distributed development
8681 * Files under Version Control:: Files to put under version control
8682 * Translations under Version Control:: Put PO Files under Version Control
8683 * autopoint Invocation:: Invoking the @code{autopoint} Program
8686 @node Distributed Development, Files under Version Control, Version Control Issues, Version Control Issues
8687 @subsection Avoiding version mismatch in distributed development
8689 In a project development with multiple developers, there should be a
8690 single developer who occasionally - when there is desire to upgrade to
8691 a new @code{gettext} version - runs @code{gettextize} and performs the
8692 changes listed in @ref{Adjusting Files}, and then commits his changes
8695 It is highly recommended that all developers on a project use the same
8696 version of GNU @code{gettext} in the package. In other words, if a
8697 developer runs @code{gettextize}, he should go the whole way, make the
8698 necessary remaining changes and commit his changes to the repository.
8699 Otherwise the following damages will likely occur:
8703 Apparent version mismatch between developers. Since some @code{gettext}
8704 specific portions in @file{configure.ac}, @file{configure.in} and
8705 @code{Makefile.am}, @code{Makefile.in} files depend on the @code{gettext}
8706 version, the use of infrastructure files belonging to different
8707 @code{gettext} versions can easily lead to build errors.
8710 Hidden version mismatch. Such version mismatch can also lead to
8711 malfunctioning of the package, that may be undiscovered by the developers.
8712 The worst case of hidden version mismatch is that internationalization
8713 of the package doesn't work at all.
8716 Release risks. All developers implicitly perform constant testing on
8717 a package. This is important in the days and weeks before a release.
8718 If the guy who makes the release tar files uses a different version
8719 of GNU @code{gettext} than the other developers, the distribution will
8720 be less well tested than if all had been using the same @code{gettext}
8721 version. For example, it is possible that a platform specific bug goes
8722 undiscovered due to this constellation.
8725 @node Files under Version Control, Translations under Version Control, Distributed Development, Version Control Issues
8726 @subsection Files to put under version control
8728 There are basically three ways to deal with generated files in the
8729 context of a version controlled repository, such as @file{configure}
8730 generated from @file{configure.ac}, @code{@var{parser}.c} generated
8731 from @code{@var{parser}.y}, or @code{po/Makefile.in.in} autoinstalled
8732 by @code{gettextize} or @code{autopoint}.
8736 All generated files are always committed into the repository.
8739 All generated files are committed into the repository occasionally,
8740 for example each time a release is made.
8743 Generated files are never committed into the repository.
8746 Each of these three approaches has different advantages and drawbacks.
8750 The advantage is that anyone can check out the source at any moment and
8751 gets a working build. The drawbacks are: 1a. It requires some frequent
8752 "push" actions by the maintainers. 1b. The repository grows in size
8756 The advantage is that anyone can check out the source, and the usual
8757 "./configure; make" will work. The drawbacks are: 2a. The one who
8758 checks out the repository needs tools like GNU @code{automake}, GNU
8759 @code{autoconf}, GNU @code{m4} installed in his PATH; sometimes he
8760 even needs particular versions of them. 2b. When a release is made
8761 and a commit is made on the generated files, the other developers get
8762 conflicts on the generated files when merging the local work back to
8763 the repository. Although these conflicts are easy to resolve, they
8767 The advantage is less work for the maintainers. The drawback is that
8768 anyone who checks out the source not only needs tools like GNU
8769 @code{automake}, GNU @code{autoconf}, GNU @code{m4} installed in his
8770 PATH, but also that he needs to perform a package specific pre-build
8771 step before being able to "./configure; make".
8774 For the first and second approach, all files modified or brought in
8775 by the occasional @code{gettextize} invocation and update should be
8776 committed into the repository.
8778 For the third approach, the maintainer can omit from the repository
8779 all the files that @code{gettextize} mentions as "copy". Instead, he
8780 adds to the @file{configure.ac} or @file{configure.in} a line of the
8784 AM_GNU_GETTEXT_VERSION(@value{ARCHIVE-VERSION})
8788 and adds to the package's pre-build script an invocation of
8789 @samp{autopoint}. For everyone who checks out the source, this
8790 @code{autopoint} invocation will copy into the right place the
8791 @code{gettext} infrastructure files that have been omitted from the repository.
8793 The version number used as argument to @code{AM_GNU_GETTEXT_VERSION} is
8794 the version of the @code{gettext} infrastructure that the package wants
8795 to use. It is also the minimum version number of the @samp{autopoint}
8796 program. So, if you write @code{AM_GNU_GETTEXT_VERSION(0.11.5)} then the
8797 developers can have any version >= 0.11.5 installed; the package will work
8798 with the 0.11.5 infrastructure in all developers' builds. When the
8799 maintainer then runs gettextize from, say, version 0.12.1 on the package,
8800 the occurrence of @code{AM_GNU_GETTEXT_VERSION(0.11.5)} will be changed
8801 into @code{AM_GNU_GETTEXT_VERSION(0.12.1)}, and all other developers that
8802 use the CVS will henceforth need to have GNU @code{gettext} 0.12.1 or newer
8805 @node Translations under Version Control, autopoint Invocation, Files under Version Control, Version Control Issues
8806 @subsection Put PO Files under Version Control
8808 Since translations are valuable assets as well as the source code, it
8809 would make sense to put them under version control. The GNU gettext
8810 infrastructure supports two ways to deal with translations in the
8811 context of a version controlled repository.
8815 Both POT file and PO files are committed into the repository.
8818 Only PO files are committed into the repository.
8822 If a POT file is absent when building, it will be generated by
8823 scanning the source files with @code{xgettext}, and then the PO files
8824 are regenerated as a dependency. On the other hand, some maintainers
8825 want to keep the POT file unchanged during the development phase. So,
8826 even if a POT file is present and older than the source code, it won't
8827 be updated automatically. You can manually update it with @code{make
8828 $(DOMAIN).pot-update}, and commit it at certain point.
8830 Special advices for particular version control systems:
8834 Recent version control systems, Git for instance, ignore file's
8835 timestamp. In that case, PO files can be accidentally updated even if
8836 a POT file is not updated. To prevent this, you can set
8837 @samp{PO_DEPENDS_ON_POT} variable to @code{no} in the @file{Makevars}
8838 file and do @code{make update-po} manually.
8841 Location comments such as @code{#: lib/error.c:116} are sometimes
8842 annoying, since these comments are volatile and may introduce unwanted
8843 change to the working copy when building. To mitigate this, you can
8844 decide to omit those comments from the PO files in the repository.
8846 This is possible with the @code{--no-location} option of the
8847 @code{msgmerge} command @footnote{you can also use it through the
8848 @samp{MSGMERGE_OPTIONS} option from @file{Makevars}}. The drawback is
8849 that, if the location information is needed, translators have to
8850 recover the location comments by running @code{msgmerge} again.
8854 @node autopoint Invocation, , Translations under Version Control, Version Control Issues
8855 @subsection Invoking the @code{autopoint} Program
8857 @include autopoint.texi
8859 @node Release Management, , Version Control Issues, Maintainers
8860 @section Creating a Distribution Tarball
8863 @cindex distribution tarball
8864 In projects that use GNU @code{automake}, the usual commands for creating
8865 a distribution tarball, @samp{make dist} or @samp{make distcheck},
8866 automatically update the PO files as needed.
8868 If GNU @code{automake} is not used, the maintainer needs to perform this
8869 update before making a release:
8873 $ (cd po; make update-po)
8877 @node Installers, Programming Languages, Maintainers, Top
8878 @chapter The Installer's and Distributor's View
8879 @cindex package installer's view of @code{gettext}
8880 @cindex package distributor's view of @code{gettext}
8881 @cindex package build and installation options
8882 @cindex setting up @code{gettext} at build time
8884 By default, packages fully using GNU @code{gettext}, internally,
8885 are installed in such a way as to allow translation of
8886 messages. At @emph{configuration} time, those packages should
8887 automatically detect whether the underlying host system already provides
8888 the GNU @code{gettext} functions. If not,
8889 the GNU @code{gettext} library should be automatically prepared
8890 and used. Installers may use special options at configuration
8891 time for changing this behavior. The command @samp{./configure
8892 --with-included-gettext} bypasses system @code{gettext} to
8893 use the included GNU @code{gettext} instead,
8894 while @samp{./configure --disable-nls}
8895 produces programs totally unable to translate messages.
8897 @vindex LINGUAS@r{, environment variable}
8898 Internationalized packages have usually many @file{@var{ll}.po}
8900 translations are disabled, all those available are installed together
8901 with the package. However, the environment variable @code{LINGUAS}
8902 may be set, prior to configuration, to limit the installed set.
8903 @code{LINGUAS} should then contain a space separated list of two-letter
8904 codes, stating which languages are allowed.
8906 @node Programming Languages, Conclusion, Installers, Top
8907 @chapter Other Programming Languages
8909 While the presentation of @code{gettext} focuses mostly on C and
8910 implicitly applies to C++ as well, its scope is far broader than that:
8911 Many programming languages, scripting languages and other textual data
8912 like GUI resources or package descriptions can make use of the gettext
8916 * Language Implementors:: The Language Implementor's View
8917 * Programmers for other Languages:: The Programmer's View
8918 * Translators for other Languages:: The Translator's View
8919 * Maintainers for other Languages:: The Maintainer's View
8920 * List of Programming Languages:: Individual Programming Languages
8921 * List of Data Formats:: Internationalizable Data
8924 @node Language Implementors, Programmers for other Languages, Programming Languages, Programming Languages
8925 @section The Language Implementor's View
8926 @cindex programming languages
8927 @cindex scripting languages
8929 All programming and scripting languages that have the notion of strings
8930 are eligible to supporting @code{gettext}. Supporting @code{gettext}
8931 means the following:
8935 You should add to the language a syntax for translatable strings. In
8936 principle, a function call of @code{gettext} would do, but a shorthand
8937 syntax helps keeping the legibility of internationalized programs. For
8938 example, in C we use the syntax @code{_("string")}, and in GNU awk we use
8939 the shorthand @code{_"string"}.
8942 You should arrange that evaluation of such a translatable string at
8943 runtime calls the @code{gettext} function, or performs equivalent
8947 Similarly, you should make the functions @code{ngettext},
8948 @code{dcgettext}, @code{dcngettext} available from within the language.
8949 These functions are less often used, but are nevertheless necessary for
8950 particular purposes: @code{ngettext} for correct plural handling, and
8951 @code{dcgettext} and @code{dcngettext} for obeying other locale-related
8952 environment variables than @code{LC_MESSAGES}, such as @code{LC_TIME} or
8953 @code{LC_MONETARY}. For these latter functions, you need to make the
8954 @code{LC_*} constants, available in the C header @code{<locale.h>},
8955 referenceable from within the language, usually either as enumeration
8956 values or as strings.
8959 You should allow the programmer to designate a message domain, either by
8960 making the @code{textdomain} function available from within the
8961 language, or by introducing a magic variable called @code{TEXTDOMAIN}.
8962 Similarly, you should allow the programmer to designate where to search
8963 for message catalogs, by providing access to the @code{bindtextdomain}
8967 You should either perform a @code{setlocale (LC_ALL, "")} call during
8968 the startup of your language runtime, or allow the programmer to do so.
8969 Remember that gettext will act as a no-op if the @code{LC_MESSAGES} and
8970 @code{LC_CTYPE} locale categories are not both set.
8973 A programmer should have a way to extract translatable strings from a
8974 program into a PO file. The GNU @code{xgettext} program is being
8975 extended to support very different programming languages. Please
8976 contact the GNU @code{gettext} maintainers to help them doing this. If
8977 the string extractor is best integrated into your language's parser, GNU
8978 @code{xgettext} can function as a front end to your string extractor.
8981 The language's library should have a string formatting facility where
8982 the arguments of a format string are denoted by a positional number or a
8983 name. This is needed because for some languages and some messages with
8984 more than one substitutable argument, the translation will need to
8985 output the substituted arguments in different order. @xref{c-format Flag}.
8988 If the language has more than one implementation, and not all of the
8989 implementations use @code{gettext}, but the programs should be portable
8990 across implementations, you should provide a no-i18n emulation, that
8991 makes the other implementations accept programs written for yours,
8992 without actually translating the strings.
8995 To help the programmer in the task of marking translatable strings,
8996 which is sometimes performed using the Emacs PO mode (@pxref{Marking}),
8998 contact the GNU @code{gettext} maintainers, so they can add support for
8999 your language to @file{po-mode.el}.
9002 On the implementation side, three approaches are possible, with
9003 different effects on portability and copyright:
9007 You may integrate the GNU @code{gettext}'s @file{intl/} directory in
9008 your package, as described in @ref{Maintainers}. This allows you to
9009 have internationalization on all kinds of platforms. Note that when you
9010 then distribute your package, it legally falls under the GNU General
9011 Public License, and the GNU project will be glad about your contribution
9012 to the Free Software pool.
9015 You may link against GNU @code{gettext} functions if they are found in
9016 the C library. For example, an autoconf test for @code{gettext()} and
9017 @code{ngettext()} will detect this situation. For the moment, this test
9018 will succeed on GNU systems and not on other platforms. No severe
9019 copyright restrictions apply.
9022 You may emulate or reimplement the GNU @code{gettext} functionality.
9023 This has the advantage of full portability and no copyright
9024 restrictions, but also the drawback that you have to reimplement the GNU
9025 @code{gettext} features (such as the @code{LANGUAGE} environment
9026 variable, the locale aliases database, the automatic charset conversion,
9027 and plural handling).
9030 @node Programmers for other Languages, Translators for other Languages, Language Implementors, Programming Languages
9031 @section The Programmer's View
9033 For the programmer, the general procedure is the same as for the C
9034 language. The Emacs PO mode marking supports other languages, and the GNU
9035 @code{xgettext} string extractor recognizes other languages based on the
9036 file extension or a command-line option. In some languages,
9037 @code{setlocale} is not needed because it is already performed by the
9038 underlying language runtime.
9040 @node Translators for other Languages, Maintainers for other Languages, Programmers for other Languages, Programming Languages
9041 @section The Translator's View
9043 The translator works exactly as in the C language case. The only
9044 difference is that when translating format strings, she has to be aware
9045 of the language's particular syntax for positional arguments in format
9049 * c-format:: C Format Strings
9050 * objc-format:: Objective C Format Strings
9051 * sh-format:: Shell Format Strings
9052 * python-format:: Python Format Strings
9053 * lisp-format:: Lisp Format Strings
9054 * elisp-format:: Emacs Lisp Format Strings
9055 * librep-format:: librep Format Strings
9056 * scheme-format:: Scheme Format Strings
9057 * smalltalk-format:: Smalltalk Format Strings
9058 * java-format:: Java Format Strings
9059 * csharp-format:: C# Format Strings
9060 * awk-format:: awk Format Strings
9061 * object-pascal-format:: Object Pascal Format Strings
9062 * ycp-format:: YCP Format Strings
9063 * tcl-format:: Tcl Format Strings
9064 * perl-format:: Perl Format Strings
9065 * php-format:: PHP Format Strings
9066 * gcc-internal-format:: GCC internal Format Strings
9067 * gfc-internal-format:: GFC internal Format Strings
9068 * qt-format:: Qt Format Strings
9069 * qt-plural-format:: Qt Plural Format Strings
9070 * kde-format:: KDE Format Strings
9071 * kde-kuit-format:: KUIT Format Strings
9072 * boost-format:: Boost Format Strings
9073 * lua-format:: Lua Format Strings
9074 * javascript-format:: JavaScript Format Strings
9077 @node c-format, objc-format, Translators for other Languages, Translators for other Languages
9078 @subsection C Format Strings
9080 C format strings are described in POSIX (IEEE P1003.1 2001), section
9082 @uref{http://www.opengroup.org/onlinepubs/007904975/functions/fprintf.html}.
9083 See also the fprintf() manual page,
9084 @uref{http://www.linuxvalley.it/encyclopedia/ldp/manpage/man3/printf.3.php},
9085 @uref{http://informatik.fh-wuerzburg.de/student/i510/man/printf.html}.
9087 Although format strings with positions that reorder arguments, such as
9090 "Only %2$d bytes free on '%1$s'."
9094 which is semantically equivalent to
9097 "'%s' has only %d bytes free."
9101 are a POSIX/XSI feature and not specified by ISO C 99, translators can rely
9102 on this reordering ability: On the few platforms where @code{printf()},
9103 @code{fprintf()} etc. don't support this feature natively, @file{libintl.a}
9104 or @file{libintl.so} provides replacement functions, and GNU @code{<libintl.h>}
9105 activates these replacement functions automatically.
9108 @cindex Arabic digits
9109 As a special feature for Farsi (Persian) and maybe Arabic, translators can
9110 insert an @samp{I} flag into numeric format directives. For example, the
9111 translation of @code{"%d"} can be @code{"%Id"}. The effect of this flag,
9112 on systems with GNU @code{libc}, is that in the output, the ASCII digits are
9113 replaced with the @samp{outdigits} defined in the @code{LC_CTYPE} locale
9114 category. On other systems, the @code{gettext} function removes this flag,
9115 so that it has no effect.
9117 Note that the programmer should @emph{not} put this flag into the
9118 untranslated string. (Putting the @samp{I} format directive flag into an
9119 @var{msgid} string would lead to undefined behaviour on platforms without
9120 glibc when NLS is disabled.)
9122 @node objc-format, sh-format, c-format, Translators for other Languages
9123 @subsection Objective C Format Strings
9125 Objective C format strings are like C format strings. They support an
9126 additional format directive: "%@@", which when executed consumes an argument
9127 of type @code{Object *}.
9129 @node sh-format, python-format, objc-format, Translators for other Languages
9130 @subsection Shell Format Strings
9132 Shell format strings, as supported by GNU gettext and the @samp{envsubst}
9133 program, are strings with references to shell variables in the form
9134 @code{$@var{variable}} or @code{$@{@var{variable}@}}. References of the form
9135 @code{$@{@var{variable}-@var{default}@}},
9136 @code{$@{@var{variable}:-@var{default}@}},
9137 @code{$@{@var{variable}=@var{default}@}},
9138 @code{$@{@var{variable}:=@var{default}@}},
9139 @code{$@{@var{variable}+@var{replacement}@}},
9140 @code{$@{@var{variable}:+@var{replacement}@}},
9141 @code{$@{@var{variable}?@var{ignored}@}},
9142 @code{$@{@var{variable}:?@var{ignored}@}},
9143 that would be valid inside shell scripts, are not supported. The
9144 @var{variable} names must consist solely of alphanumeric or underscore
9145 ASCII characters, not start with a digit and be nonempty; otherwise such
9146 a variable reference is ignored.
9148 @node python-format, lisp-format, sh-format, Translators for other Languages
9149 @subsection Python Format Strings
9151 There are two kinds of format strings in Python: those acceptable to
9152 the Python built-in format operator @code{%}, labelled as
9153 @samp{python-format}, and those acceptable to the @code{format} method
9154 of the @samp{str} object.
9156 Python @code{%} format strings are described in
9157 @w{Python Library reference} /
9158 @w{5. Built-in Types} /
9159 @w{5.6. Sequence Types} /
9160 @w{5.6.2. String Formatting Operations}.
9161 @uref{http://docs.python.org/2/library/stdtypes.html#string-formatting-operations}.
9163 Python brace format strings are described in @w{PEP 3101 -- Advanced
9164 String Formatting}, @uref{http://www.python.org/dev/peps/pep-3101/}.
9166 @node lisp-format, elisp-format, python-format, Translators for other Languages
9167 @subsection Lisp Format Strings
9169 Lisp format strings are described in the Common Lisp HyperSpec,
9170 chapter 22.3 @w{Formatted Output},
9171 @uref{http://www.lisp.org/HyperSpec/Body/sec_22-3.html}.
9173 @node elisp-format, librep-format, lisp-format, Translators for other Languages
9174 @subsection Emacs Lisp Format Strings
9176 Emacs Lisp format strings are documented in the Emacs Lisp reference,
9177 section @w{Formatting Strings},
9178 @uref{http://www.gnu.org/manual/elisp-manual-21-2.8/html_chapter/elisp_4.html#SEC75}.
9179 Note that as of version 21, XEmacs supports numbered argument specifications
9180 in format strings while FSF Emacs doesn't.
9182 @node librep-format, scheme-format, elisp-format, Translators for other Languages
9183 @subsection librep Format Strings
9185 librep format strings are documented in the librep manual, section
9186 @w{Formatted Output},
9187 @url{http://librep.sourceforge.net/librep-manual.html#Formatted%20Output},
9188 @url{http://www.gwinnup.org/research/docs/librep.html#SEC122}.
9190 @node scheme-format, smalltalk-format, librep-format, Translators for other Languages
9191 @subsection Scheme Format Strings
9193 Scheme format strings are documented in the SLIB manual, section
9194 @w{Format Specification}.
9196 @node smalltalk-format, java-format, scheme-format, Translators for other Languages
9197 @subsection Smalltalk Format Strings
9199 Smalltalk format strings are described in the GNU Smalltalk documentation,
9200 class @code{CharArray}, methods @samp{bindWith:} and
9201 @samp{bindWithArguments:}.
9202 @uref{http://www.gnu.org/software/smalltalk/gst-manual/gst_68.html#SEC238}.
9203 In summary, a directive starts with @samp{%} and is followed by @samp{%}
9204 or a nonzero digit (@samp{1} to @samp{9}).
9206 @node java-format, csharp-format, smalltalk-format, Translators for other Languages
9207 @subsection Java Format Strings
9209 Java format strings are described in the JDK documentation for class
9210 @code{java.text.MessageFormat},
9211 @uref{http://java.sun.com/j2se/1.4/docs/api/java/text/MessageFormat.html}.
9212 See also the ICU documentation
9213 @uref{http://oss.software.ibm.com/icu/apiref/classMessageFormat.html}.
9215 @node csharp-format, awk-format, java-format, Translators for other Languages
9216 @subsection C# Format Strings
9218 C# format strings are described in the .NET documentation for class
9219 @code{System.String} and in
9220 @uref{http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpConFormattingOverview.asp}.
9222 @node awk-format, object-pascal-format, csharp-format, Translators for other Languages
9223 @subsection awk Format Strings
9225 awk format strings are described in the gawk documentation, section
9227 @uref{http://www.gnu.org/manual/gawk/html_node/Printf.html#Printf}.
9229 @node object-pascal-format, ycp-format, awk-format, Translators for other Languages
9230 @subsection Object Pascal Format Strings
9232 Object Pascal format strings are described in the documentation of the
9233 Free Pascal runtime library, section Format,
9234 @uref{http://www.freepascal.org/docs-html/rtl/sysutils/format.html}.
9236 @node ycp-format, tcl-format, object-pascal-format, Translators for other Languages
9237 @subsection YCP Format Strings
9239 YCP sformat strings are described in the libycp documentation
9240 @uref{file:/usr/share/doc/packages/libycp/YCP-builtins.html}.
9241 In summary, a directive starts with @samp{%} and is followed by @samp{%}
9242 or a nonzero digit (@samp{1} to @samp{9}).
9244 @node tcl-format, perl-format, ycp-format, Translators for other Languages
9245 @subsection Tcl Format Strings
9247 Tcl format strings are described in the @file{format.n} manual page,
9248 @uref{http://www.scriptics.com/man/tcl8.3/TclCmd/format.htm}.
9250 @node perl-format, php-format, tcl-format, Translators for other Languages
9251 @subsection Perl Format Strings
9253 There are two kinds format strings in Perl: those acceptable to the
9254 Perl built-in function @code{printf}, labelled as @samp{perl-format},
9255 and those acceptable to the @code{libintl-perl} function @code{__x},
9256 labelled as @samp{perl-brace-format}.
9258 Perl @code{printf} format strings are described in the @code{sprintf}
9259 section of @samp{man perlfunc}.
9261 Perl brace format strings are described in the
9262 @file{Locale::TextDomain(3pm)} manual page of the CPAN package
9263 libintl-perl. In brief, Perl format uses placeholders put between
9264 braces (@samp{@{} and @samp{@}}). The placeholder must have the syntax
9265 of simple identifiers.
9267 @node php-format, gcc-internal-format, perl-format, Translators for other Languages
9268 @subsection PHP Format Strings
9270 PHP format strings are described in the documentation of the PHP function
9271 @code{sprintf}, in @file{phpdoc/manual/function.sprintf.html} or
9272 @uref{http://www.php.net/manual/en/function.sprintf.php}.
9274 @node gcc-internal-format, gfc-internal-format, php-format, Translators for other Languages
9275 @subsection GCC internal Format Strings
9277 These format strings are used inside the GCC sources. In such a format
9278 string, a directive starts with @samp{%}, is optionally followed by a
9279 size specifier @samp{l}, an optional flag @samp{+}, another optional flag
9280 @samp{#}, and is finished by a specifier: @samp{%} denotes a literal
9281 percent sign, @samp{c} denotes a character, @samp{s} denotes a string,
9282 @samp{i} and @samp{d} denote an integer, @samp{o}, @samp{u}, @samp{x}
9283 denote an unsigned integer, @samp{.*s} denotes a string preceded by a
9284 width specification, @samp{H} denotes a @samp{location_t *} pointer,
9285 @samp{D} denotes a general declaration, @samp{F} denotes a function
9286 declaration, @samp{T} denotes a type, @samp{A} denotes a function argument,
9287 @samp{C} denotes a tree code, @samp{E} denotes an expression, @samp{L}
9288 denotes a programming language, @samp{O} denotes a binary operator,
9289 @samp{P} denotes a function parameter, @samp{Q} denotes an assignment
9290 operator, @samp{V} denotes a const/volatile qualifier.
9292 @node gfc-internal-format, qt-format, gcc-internal-format, Translators for other Languages
9293 @subsection GFC internal Format Strings
9295 These format strings are used inside the GNU Fortran Compiler sources,
9296 that is, the Fortran frontend in the GCC sources. In such a format
9297 string, a directive starts with @samp{%} and is finished by a
9298 specifier: @samp{%} denotes a literal percent sign, @samp{C} denotes the
9299 current source location, @samp{L} denotes a source location, @samp{c}
9300 denotes a character, @samp{s} denotes a string, @samp{i} and @samp{d}
9301 denote an integer, @samp{u} denotes an unsigned integer. @samp{i},
9302 @samp{d}, and @samp{u} may be preceded by a size specifier @samp{l}.
9304 @node qt-format, qt-plural-format, gfc-internal-format, Translators for other Languages
9305 @subsection Qt Format Strings
9307 Qt format strings are described in the documentation of the QString class
9308 @uref{file:/usr/lib/qt-4.3.0/doc/html/qstring.html}.
9309 In summary, a directive consists of a @samp{%} followed by a digit. The same
9310 directive cannot occur more than once in a format string.
9312 @node qt-plural-format, kde-format, qt-format, Translators for other Languages
9313 @subsection Qt Format Strings
9315 Qt format strings are described in the documentation of the QObject::tr method
9316 @uref{file:/usr/lib/qt-4.3.0/doc/html/qobject.html}.
9317 In summary, the only allowed directive is @samp{%n}.
9319 @node kde-format, kde-kuit-format, qt-plural-format, Translators for other Languages
9320 @subsection KDE Format Strings
9322 KDE 4 format strings are defined as follows:
9323 A directive consists of a @samp{%} followed by a non-zero decimal number.
9324 If a @samp{%n} occurs in a format strings, all of @samp{%1}, ..., @samp{%(n-1)}
9325 must occur as well, except possibly one of them.
9327 @node kde-kuit-format, boost-format, kde-format, Translators for other Languages
9328 @subsection KUIT Format Strings
9330 KUIT (KDE User Interface Text) is compatible with KDE 4 format strings,
9331 while it also allows programmers to add semantic information to a format
9332 string, through XML markup tags. For example, if the first format
9333 directive in a string is a filename, programmers could indicate that
9334 with a @samp{filename} tag, like @samp{<filename>%1</filename>}.
9336 KUIT format strings are described in
9337 @uref{http://api.kde.org/frameworks-api/frameworks5-apidocs/ki18n/html/prg_guide.html#kuit_markup}.
9339 @node boost-format, lua-format, kde-kuit-format, Translators for other Languages
9340 @subsection Boost Format Strings
9342 Boost format strings are described in the documentation of the
9343 @code{boost::format} class, at
9344 @uref{http://www.boost.org/libs/format/doc/format.html}.
9345 In summary, a directive has either the same syntax as in a C format string,
9346 such as @samp{%1$+5d}, or may be surrounded by vertical bars, such as
9347 @samp{%|1$+5d|} or @samp{%|1$+5|}, or consists of just an argument number
9348 between percent signs, such as @samp{%1%}.
9350 @node lua-format, javascript-format, boost-format, Translators for other Languages
9351 @subsection Lua Format Strings
9353 Lua format strings are described in the Lua reference manual, section @w{String Manipulation},
9354 @uref{http://www.lua.org/manual/5.1/manual.html#pdf-string.format}.
9356 @node javascript-format, , lua-format, Translators for other Languages
9357 @subsection JavaScript Format Strings
9359 Although JavaScript specification itself does not define any format
9360 strings, many JavaScript implementations provide printf-like
9361 functions. @code{xgettext} understands a set of common format strings
9362 used in popular JavaScript implementations including Gjs, Seed, and
9363 Node.JS. In such a format string, a directive starts with @samp{%}
9364 and is finished by a specifier: @samp{%} denotes a literal percent
9365 sign, @samp{c} denotes a character, @samp{s} denotes a string,
9366 @samp{b}, @samp{d}, @samp{o}, @samp{x}, @samp{X} denote an integer,
9367 @samp{f} denotes floating-point number, @samp{j} denotes a JSON
9371 @node Maintainers for other Languages, List of Programming Languages, Translators for other Languages, Programming Languages
9372 @section The Maintainer's View
9374 For the maintainer, the general procedure differs from the C language
9379 For those languages that don't use GNU gettext, the @file{intl/} directory
9380 is not needed and can be omitted. This means that the maintainer calls the
9381 @code{gettextize} program without the @samp{--intl} option, and that he
9382 invokes the @code{AM_GNU_GETTEXT} autoconf macro via
9383 @samp{AM_GNU_GETTEXT([external])}.
9386 If only a single programming language is used, the @code{XGETTEXT_OPTIONS}
9387 variable in @file{po/Makevars} (@pxref{po/Makevars}) should be adjusted to
9388 match the @code{xgettext} options for that particular programming language.
9389 If the package uses more than one programming language with @code{gettext}
9390 support, it becomes necessary to change the POT file construction rule
9391 in @file{po/Makefile.in.in}. It is recommended to make one @code{xgettext}
9392 invocation per programming language, each with the options appropriate for
9393 that language, and to combine the resulting files using @code{msgcat}.
9396 @node List of Programming Languages, List of Data Formats, Maintainers for other Languages, Programming Languages
9397 @section Individual Programming Languages
9399 @c Here is a list of programming languages, as used for Free Software projects
9400 @c on SourceForge/Freshmeat, as of February 2002. Those supported by gettext
9401 @c are marked with a star.
9437 @c Object Pascal 5 *
9449 @c Other Scripting Engines 49
9453 * C:: C, C++, Objective C
9454 * sh:: sh - Shell Script
9455 * bash:: bash - Bourne-Again Shell Script
9457 * Common Lisp:: GNU clisp - Common Lisp
9458 * clisp C:: GNU clisp C sources
9459 * Emacs Lisp:: Emacs Lisp
9461 * Scheme:: GNU guile - Scheme
9462 * Smalltalk:: GNU Smalltalk
9466 * Pascal:: Pascal - Free Pascal Compiler
9467 * wxWidgets:: wxWidgets library
9468 * YCP:: YCP - YaST2 scripting language
9469 * Tcl:: Tcl - Tk's scripting language
9471 * PHP:: PHP Hypertext Preprocessor
9473 * GCC-source:: GNU Compiler Collection sources
9475 * JavaScript:: JavaScript
9479 @node C, sh, List of Programming Languages, List of Programming Languages
9480 @subsection C, C++, Objective C
9481 @cindex C and C-like languages
9485 gcc, gpp, gobjc, glibc, gettext
9487 @item File extension
9488 For C: @code{c}, @code{h}.
9489 @*For C++: @code{C}, @code{c++}, @code{cc}, @code{cxx}, @code{cpp}, @code{hpp}.
9490 @*For Objective C: @code{m}.
9495 @item gettext shorthand
9498 @item gettext/ngettext functions
9499 @code{gettext}, @code{dgettext}, @code{dcgettext}, @code{ngettext},
9500 @code{dngettext}, @code{dcngettext}
9503 @code{textdomain} function
9505 @item bindtextdomain
9506 @code{bindtextdomain} function
9509 Programmer must call @code{setlocale (LC_ALL, "")}
9512 @code{#include <libintl.h>}
9513 @*@code{#include <locale.h>}
9514 @*@code{#define _(string) gettext (string)}
9516 @item Use or emulate GNU gettext
9522 @item Formatting with positions
9523 @code{fprintf "%2$d %1$d"}
9524 @*In C++: @code{autosprintf "%2$d %1$d"}
9525 (@pxref{Top, , Introduction, autosprintf, GNU autosprintf})
9528 autoconf (gettext.m4) and #if ENABLE_NLS
9530 @item po-mode marking
9534 The following examples are available in the @file{examples} directory:
9535 @code{hello-c}, @code{hello-c-gnome}, @code{hello-c++}, @code{hello-c++-qt},
9536 @code{hello-c++-kde}, @code{hello-c++-gnome}, @code{hello-c++-wxwidgets},
9537 @code{hello-objc}, @code{hello-objc-gnustep}, @code{hello-objc-gnome}.
9539 @node sh, bash, C, List of Programming Languages
9540 @subsection sh - Shell Script
9541 @cindex shell scripts
9547 @item File extension
9551 @code{"abc"}, @code{'abc'}, @code{abc}
9553 @item gettext shorthand
9554 @code{"`gettext \"abc\"`"}
9556 @item gettext/ngettext functions
9559 @code{gettext}, @code{ngettext} programs
9560 @*@code{eval_gettext}, @code{eval_ngettext} shell functions
9563 @vindex TEXTDOMAIN@r{, environment variable}
9564 environment variable @code{TEXTDOMAIN}
9566 @item bindtextdomain
9567 @vindex TEXTDOMAINDIR@r{, environment variable}
9568 environment variable @code{TEXTDOMAINDIR}
9576 @item Use or emulate GNU gettext
9582 @item Formatting with positions
9588 @item po-mode marking
9592 An example is available in the @file{examples} directory: @code{hello-sh}.
9595 * Preparing Shell Scripts:: Preparing Shell Scripts for Internationalization
9596 * gettext.sh:: Contents of @code{gettext.sh}
9597 * gettext Invocation:: Invoking the @code{gettext} program
9598 * ngettext Invocation:: Invoking the @code{ngettext} program
9599 * envsubst Invocation:: Invoking the @code{envsubst} program
9600 * eval_gettext Invocation:: Invoking the @code{eval_gettext} function
9601 * eval_ngettext Invocation:: Invoking the @code{eval_ngettext} function
9604 @node Preparing Shell Scripts, gettext.sh, sh, sh
9605 @subsubsection Preparing Shell Scripts for Internationalization
9606 @cindex preparing shell scripts for translation
9608 Preparing a shell script for internationalization is conceptually similar
9609 to the steps described in @ref{Sources}. The concrete steps for shell
9610 scripts are as follows.
9620 near the top of the script. @code{gettext.sh} is a shell function library
9621 that provides the functions
9622 @code{eval_gettext} (see @ref{eval_gettext Invocation}) and
9623 @code{eval_ngettext} (see @ref{eval_ngettext Invocation}).
9624 You have to ensure that @code{gettext.sh} can be found in the @code{PATH}.
9627 Set and export the @code{TEXTDOMAIN} and @code{TEXTDOMAINDIR} environment
9628 variables. Usually @code{TEXTDOMAIN} is the package or program name, and
9629 @code{TEXTDOMAINDIR} is the absolute pathname corresponding to
9630 @code{$prefix/share/locale}, where @code{$prefix} is the installation location.
9633 TEXTDOMAIN=@@PACKAGE@@
9635 TEXTDOMAINDIR=@@LOCALEDIR@@
9636 export TEXTDOMAINDIR
9640 Prepare the strings for translation, as described in @ref{Preparing Strings}.
9643 Simplify translatable strings so that they don't contain command substitution
9644 (@code{"`...`"} or @code{"$(...)"}), variable access with defaulting (like
9645 @code{$@{@var{variable}-@var{default}@}}), access to positional arguments
9646 (like @code{$0}, @code{$1}, ...) or highly volatile shell variables (like
9647 @code{$?}). This can always be done through simple local code restructuring.
9651 echo "Usage: $0 [OPTION] FILE..."
9658 echo "Usage: $program_name [OPTION] FILE..."
9664 echo "Remaining files: `ls | wc -l`"
9670 filecount="`ls | wc -l`"
9671 echo "Remaining files: $filecount"
9675 For each translatable string, change the output command @samp{echo} or
9676 @samp{$echo} to @samp{gettext} (if the string contains no references to
9677 shell variables) or to @samp{eval_gettext} (if it refers to shell variables),
9678 followed by a no-argument @samp{echo} command (to account for the terminating
9679 newline). Similarly, for cases with plural handling, replace a conditional
9680 @samp{echo} command with an invocation of @samp{ngettext} or
9681 @samp{eval_ngettext}, followed by a no-argument @samp{echo} command.
9683 When doing this, you also need to add an extra backslash before the dollar
9684 sign in references to shell variables, so that the @samp{eval_gettext}
9685 function receives the translatable string before the variable values are
9686 substituted into it. For example,
9689 echo "Remaining files: $filecount"
9695 eval_gettext "Remaining files: \$filecount"; echo
9698 If the output command is not @samp{echo}, you can make it use @samp{echo}
9699 nevertheless, through the use of backquotes. However, note that inside
9700 backquotes, backslashes must be doubled to be effective (because the
9701 backquoting eats one level of backslashes). For example, assuming that
9702 @samp{error} is a shell function that signals an error,
9705 error "file not found: $filename"
9708 is first transformed into
9711 error "`echo \"file not found: \$filename\"`"
9717 error "`eval_gettext \"file not found: \\\$filename\"`"
9721 @node gettext.sh, gettext Invocation, Preparing Shell Scripts, sh
9722 @subsubsection Contents of @code{gettext.sh}
9724 @code{gettext.sh}, contained in the run-time package of GNU gettext, provides
9729 The variable @code{echo} is set to a command that outputs its first argument
9730 and a newline, without interpreting backslashes in the argument string.
9733 See @ref{eval_gettext Invocation}.
9736 See @ref{eval_ngettext Invocation}.
9739 @node gettext Invocation, ngettext Invocation, gettext.sh, sh
9740 @subsubsection Invoking the @code{gettext} program
9742 @include rt-gettext.texi
9744 Note: @code{xgettext} supports only the one-argument form of the
9745 @code{gettext} invocation, where no options are present and the
9746 @var{textdomain} is implicit, from the environment.
9748 @node ngettext Invocation, envsubst Invocation, gettext Invocation, sh
9749 @subsubsection Invoking the @code{ngettext} program
9751 @include rt-ngettext.texi
9753 Note: @code{xgettext} supports only the three-arguments form of the
9754 @code{ngettext} invocation, where no options are present and the
9755 @var{textdomain} is implicit, from the environment.
9757 @node envsubst Invocation, eval_gettext Invocation, ngettext Invocation, sh
9758 @subsubsection Invoking the @code{envsubst} program
9760 @include rt-envsubst.texi
9762 @node eval_gettext Invocation, eval_ngettext Invocation, envsubst Invocation, sh
9763 @subsubsection Invoking the @code{eval_gettext} function
9765 @cindex @code{eval_gettext} function, usage
9767 eval_gettext @var{msgid}
9770 @cindex lookup message translation
9771 This function outputs the native language translation of a textual message,
9772 performing dollar-substitution on the result. Note that only shell variables
9773 mentioned in @var{msgid} will be dollar-substituted in the result.
9775 @node eval_ngettext Invocation, , eval_gettext Invocation, sh
9776 @subsubsection Invoking the @code{eval_ngettext} function
9778 @cindex @code{eval_ngettext} function, usage
9780 eval_ngettext @var{msgid} @var{msgid-plural} @var{count}
9783 @cindex lookup plural message translation
9784 This function outputs the native language translation of a textual message
9785 whose grammatical form depends on a number, performing dollar-substitution
9786 on the result. Note that only shell variables mentioned in @var{msgid} or
9787 @var{msgid-plural} will be dollar-substituted in the result.
9789 @node bash, Python, sh, List of Programming Languages
9790 @subsection bash - Bourne-Again Shell Script
9793 GNU @code{bash} 2.0 or newer has a special shorthand for translating a
9794 string and substituting variable values in it: @code{$"msgid"}. But
9795 the use of this construct is @strong{discouraged}, due to the security
9796 holes it opens and due to its portability problems.
9798 The security holes of @code{$"..."} come from the fact that after looking up
9799 the translation of the string, @code{bash} processes it like it processes
9800 any double-quoted string: dollar and backquote processing, like @samp{eval}
9805 In a locale whose encoding is one of BIG5, BIG5-HKSCS, GBK, GB18030, SHIFT_JIS,
9806 JOHAB, some double-byte characters have a second byte whose value is
9807 @code{0x60}. For example, the byte sequence @code{\xe0\x60} is a single
9808 character in these locales. Many versions of @code{bash} (all versions
9809 up to bash-2.05, and newer versions on platforms without @code{mbsrtowcs()}
9810 function) don't know about character boundaries and see a backquote character
9811 where there is only a particular Chinese character. Thus it can start
9812 executing part of the translation as a command list. This situation can occur
9813 even without the translator being aware of it: if the translator provides
9814 translations in the UTF-8 encoding, it is the @code{gettext()} function which
9815 will, during its conversion from the translator's encoding to the user's
9816 locale's encoding, produce the dangerous @code{\x60} bytes.
9819 A translator could - voluntarily or inadvertently - use backquotes
9820 @code{"`...`"} or dollar-parentheses @code{"$(...)"} in her translations.
9821 The enclosed strings would be executed as command lists by the shell.
9824 The portability problem is that @code{bash} must be built with
9825 internationalization support; this is normally not the case on systems
9826 that don't have the @code{gettext()} function in libc.
9828 @node Python, Common Lisp, bash, List of Programming Languages
9836 @item File extension
9840 @code{'abc'}, @code{u'abc'}, @code{r'abc'}, @code{ur'abc'},
9841 @*@code{"abc"}, @code{u"abc"}, @code{r"abc"}, @code{ur"abc"},
9842 @*@code{'''abc'''}, @code{u'''abc'''}, @code{r'''abc'''}, @code{ur'''abc'''},
9843 @*@code{"""abc"""}, @code{u"""abc"""}, @code{r"""abc"""}, @code{ur"""abc"""}
9845 @item gettext shorthand
9846 @code{_('abc')} etc.
9848 @item gettext/ngettext functions
9849 @code{gettext.gettext}, @code{gettext.dgettext},
9850 @code{gettext.ngettext}, @code{gettext.dngettext},
9851 also @code{ugettext}, @code{ungettext}
9854 @code{gettext.textdomain} function, or
9855 @code{gettext.install(@var{domain})} function
9857 @item bindtextdomain
9858 @code{gettext.bindtextdomain} function, or
9859 @code{gettext.install(@var{domain},@var{localedir})} function
9862 not used by the gettext emulation
9865 @code{import gettext}
9867 @item Use or emulate GNU gettext
9873 @item Formatting with positions
9874 @code{'...%(ident)d...' % @{ 'ident': value @}}
9879 @item po-mode marking
9883 An example is available in the @file{examples} directory: @code{hello-python}.
9885 A note about format strings: Python supports format strings with unnamed
9886 arguments, such as @code{'...%d...'}, and format strings with named arguments,
9887 such as @code{'...%(ident)d...'}. The latter are preferable for
9888 internationalized programs, for two reasons:
9892 When a format string takes more than one argument, the translator can provide
9893 a translation that uses the arguments in a different order, if the format
9894 string uses named arguments. For example, the translator can reformulate
9896 "'%(volume)s' has only %(freespace)d bytes free."
9901 "Only %(freespace)d bytes free on '%(volume)s'."
9904 Additionally, the identifiers also provide some context to the translator.
9907 In the context of plural forms, the format string used for the singular form
9908 does not use the numeric argument in many languages. Even in English, one
9909 prefers to write @code{"one hour"} instead of @code{"1 hour"}. Omitting
9910 individual arguments from format strings like this is only possible with
9911 the named argument syntax. (With unnamed arguments, Python -- unlike C --
9912 verifies that the format string uses all supplied arguments.)
9915 @node Common Lisp, clisp C, Python, List of Programming Languages
9916 @subsection GNU clisp - Common Lisp
9925 @item File extension
9931 @item gettext shorthand
9932 @code{(_ "abc")}, @code{(ENGLISH "abc")}
9934 @item gettext/ngettext functions
9935 @code{i18n:gettext}, @code{i18n:ngettext}
9938 @code{i18n:textdomain}
9940 @item bindtextdomain
9941 @code{i18n:textdomaindir}
9949 @item Use or emulate GNU gettext
9953 @code{xgettext -k_ -kENGLISH}
9955 @item Formatting with positions
9956 @code{format "~1@@*~D ~0@@*~D"}
9959 On platforms without gettext, no translation.
9961 @item po-mode marking
9965 An example is available in the @file{examples} directory: @code{hello-clisp}.
9967 @node clisp C, Emacs Lisp, Common Lisp, List of Programming Languages
9968 @subsection GNU clisp C sources
9969 @cindex clisp C sources
9975 @item File extension
9981 @item gettext shorthand
9982 @code{ENGLISH ? "abc" : ""}
9983 @*@code{GETTEXT("abc")}
9984 @*@code{GETTEXTL("abc")}
9986 @item gettext/ngettext functions
9987 @code{clgettext}, @code{clgettextl}
9992 @item bindtextdomain
9999 @code{#include "lispbibl.c"}
10001 @item Use or emulate GNU gettext
10005 @code{clisp-xgettext}
10007 @item Formatting with positions
10008 @code{fprintf "%2$d %1$d"}
10011 On platforms without gettext, no translation.
10013 @item po-mode marking
10017 @node Emacs Lisp, librep, clisp C, List of Programming Languages
10018 @subsection Emacs Lisp
10025 @item File extension
10028 @item String syntax
10031 @item gettext shorthand
10034 @item gettext/ngettext functions
10035 @code{gettext}, @code{dgettext} (xemacs only)
10038 @code{domain} special form (xemacs only)
10040 @item bindtextdomain
10041 @code{bind-text-domain} function (xemacs only)
10049 @item Use or emulate GNU gettext
10055 @item Formatting with positions
10056 @code{format "%2$d %1$d"}
10059 Only XEmacs. Without @code{I18N3} defined at build time, no translation.
10061 @item po-mode marking
10065 @node librep, Scheme, Emacs Lisp, List of Programming Languages
10067 @cindex @code{librep} Lisp
10071 librep 0.15.3 or newer
10073 @item File extension
10076 @item String syntax
10079 @item gettext shorthand
10082 @item gettext/ngettext functions
10086 @code{textdomain} function
10088 @item bindtextdomain
10089 @code{bindtextdomain} function
10095 @code{(require 'rep.i18n.gettext)}
10097 @item Use or emulate GNU gettext
10103 @item Formatting with positions
10104 @code{format "%2$d %1$d"}
10107 On platforms without gettext, no translation.
10109 @item po-mode marking
10113 An example is available in the @file{examples} directory: @code{hello-librep}.
10115 @node Scheme, Smalltalk, librep, List of Programming Languages
10116 @subsection GNU guile - Scheme
10124 @item File extension
10127 @item String syntax
10130 @item gettext shorthand
10131 @code{(_ "abc")}, @code{_"abc"} (GIMP script-fu extension)
10133 @item gettext/ngettext functions
10134 @code{gettext}, @code{ngettext}
10139 @item bindtextdomain
10140 @code{bindtextdomain}
10143 @code{(catch #t (lambda () (setlocale LC_ALL "")) (lambda args #f))}
10146 @code{(use-modules (ice-9 format))}
10148 @item Use or emulate GNU gettext
10152 @code{xgettext -k_}
10154 @item Formatting with positions
10155 @c @code{format "~1@@*~D ~0@@*~D~2@@*"}, requires @code{(use-modules (ice-9 format))}
10156 @c not yet supported
10160 On platforms without gettext, no translation.
10162 @item po-mode marking
10166 An example is available in the @file{examples} directory: @code{hello-guile}.
10168 @node Smalltalk, Java, Scheme, List of Programming Languages
10169 @subsection GNU Smalltalk
10176 @item File extension
10179 @item String syntax
10182 @item gettext shorthand
10185 @item gettext/ngettext functions
10186 @code{LcMessagesDomain>>#at:}, @code{LcMessagesDomain>>#at:plural:with:}
10189 @code{LcMessages>>#domain:localeDirectory:} (returns a @code{LcMessagesDomain}
10191 Example: @code{I18N Locale default messages domain: 'gettext' localeDirectory: /usr/local/share/locale'}
10193 @item bindtextdomain
10194 @code{LcMessages>>#domain:localeDirectory:}, see above.
10197 Automatic if you use @code{I18N Locale default}.
10200 @code{PackageLoader fileInPackage: 'I18N'!}
10202 @item Use or emulate GNU gettext
10208 @item Formatting with positions
10209 @code{'%1 %2' bindWith: 'Hello' with: 'world'}
10214 @item po-mode marking
10218 An example is available in the @file{examples} directory:
10219 @code{hello-smalltalk}.
10221 @node Java, C#, Smalltalk, List of Programming Languages
10229 @item File extension
10232 @item String syntax
10235 @item gettext shorthand
10238 @item gettext/ngettext functions
10239 @code{GettextResource.gettext}, @code{GettextResource.ngettext},
10240 @code{GettextResource.pgettext}, @code{GettextResource.npgettext}
10243 ---, use @code{ResourceBundle.getResource} instead
10245 @item bindtextdomain
10246 ---, use CLASSPATH instead
10254 @item Use or emulate GNU gettext
10255 ---, uses a Java specific message catalog format
10258 @code{xgettext -k_}
10260 @item Formatting with positions
10261 @code{MessageFormat.format "@{1,number@} @{0,number@}"}
10266 @item po-mode marking
10270 Before marking strings as internationalizable, uses of the string
10271 concatenation operator need to be converted to @code{MessageFormat}
10272 applications. For example, @code{"file "+filename+" not found"} becomes
10273 @code{MessageFormat.format("file @{0@} not found", new Object[] @{ filename @})}.
10274 Only after this is done, can the strings be marked and extracted.
10276 GNU gettext uses the native Java internationalization mechanism, namely
10277 @code{ResourceBundle}s. There are two formats of @code{ResourceBundle}s:
10278 @code{.properties} files and @code{.class} files. The @code{.properties}
10279 format is a text file which the translators can directly edit, like PO
10280 files, but which doesn't support plural forms. Whereas the @code{.class}
10281 format is compiled from @code{.java} source code and can support plural
10282 forms (provided it is accessed through an appropriate API, see below).
10284 To convert a PO file to a @code{.properties} file, the @code{msgcat}
10285 program can be used with the option @code{--properties-output}. To convert
10286 a @code{.properties} file back to a PO file, the @code{msgcat} program
10287 can be used with the option @code{--properties-input}. All the tools
10288 that manipulate PO files can work with @code{.properties} files as well,
10289 if given the @code{--properties-input} and/or @code{--properties-output}
10292 To convert a PO file to a ResourceBundle class, the @code{msgfmt} program
10293 can be used with the option @code{--java} or @code{--java2}. To convert a
10294 ResourceBundle back to a PO file, the @code{msgunfmt} program can be used
10295 with the option @code{--java}.
10297 Two different programmatic APIs can be used to access ResourceBundles.
10298 Note that both APIs work with all kinds of ResourceBundles, whether
10299 GNU gettext generated classes, or other @code{.class} or @code{.properties}
10304 The @code{java.util.ResourceBundle} API.
10306 In particular, its @code{getString} function returns a string translation.
10307 Note that a missing translation yields a @code{MissingResourceException}.
10309 This has the advantage of being the standard API. And it does not require
10310 any additional libraries, only the @code{msgcat} generated @code{.properties}
10311 files or the @code{msgfmt} generated @code{.class} files. But it cannot do
10312 plural handling, even if the resource was generated by @code{msgfmt} from
10313 a PO file with plural handling.
10316 The @code{gnu.gettext.GettextResource} API.
10318 Reference documentation in Javadoc 1.1 style format is in the
10319 @uref{javadoc2/index.html,javadoc2 directory}.
10321 Its @code{gettext} function returns a string translation. Note that when
10322 a translation is missing, the @var{msgid} argument is returned unchanged.
10324 This has the advantage of having the @code{ngettext} function for plural
10325 handling and the @code{pgettext} and @code{npgettext} for strings constraint
10326 to a particular context.
10328 @cindex @code{libintl} for Java
10329 To use this API, one needs the @code{libintl.jar} file which is part of
10330 the GNU gettext package and distributed under the LGPL.
10333 Four examples, using the second API, are available in the @file{examples}
10334 directory: @code{hello-java}, @code{hello-java-awt}, @code{hello-java-swing},
10335 @code{hello-java-qtjambi}.
10337 Now, to make use of the API and define a shorthand for @samp{getString},
10338 there are three idioms that you can choose from:
10342 (This one assumes Java 1.5 or newer.)
10343 In a unique class of your project, say @samp{Util}, define a static variable
10344 holding the @code{ResourceBundle} instance and the shorthand:
10347 private static ResourceBundle myResources =
10348 ResourceBundle.getBundle("domain-name");
10349 public static String _(String s) @{
10350 return myResources.getString(s);
10354 All classes containing internationalized strings then contain
10357 import static Util._;
10361 and the shorthand is used like this:
10364 System.out.println(_("Operation completed."));
10368 In a unique class of your project, say @samp{Util}, define a static variable
10369 holding the @code{ResourceBundle} instance:
10372 public static ResourceBundle myResources =
10373 ResourceBundle.getBundle("domain-name");
10376 All classes containing internationalized strings then contain
10379 private static ResourceBundle res = Util.myResources;
10380 private static String _(String s) @{ return res.getString(s); @}
10384 and the shorthand is used like this:
10387 System.out.println(_("Operation completed."));
10391 You add a class with a very short name, say @samp{S}, containing just the
10392 definition of the resource bundle and of the shorthand:
10396 public static ResourceBundle myResources =
10397 ResourceBundle.getBundle("domain-name");
10398 public static String _(String s) @{
10399 return myResources.getString(s);
10405 and the shorthand is used like this:
10408 System.out.println(S._("Operation completed."));
10412 Which of the three idioms you choose, will depend on whether your project
10413 requires portability to Java versions prior to Java 1.5 and, if so, whether
10414 copying two lines of codes into every class is more acceptable in your project
10415 than a class with a single-letter name.
10417 @node C#, gawk, Java, List of Programming Languages
10423 pnet, pnetlib 0.6.2 or newer, or mono 0.29 or newer
10425 @item File extension
10428 @item String syntax
10429 @code{"abc"}, @code{@@"abc"}
10431 @item gettext shorthand
10434 @item gettext/ngettext functions
10435 @code{GettextResourceManager.GetString},
10436 @code{GettextResourceManager.GetPluralString}
10437 @code{GettextResourceManager.GetParticularString}
10438 @code{GettextResourceManager.GetParticularPluralString}
10441 @code{new GettextResourceManager(domain)}
10443 @item bindtextdomain
10444 ---, compiled message catalogs are located in subdirectories of the directory
10445 containing the executable
10453 @item Use or emulate GNU gettext
10454 ---, uses a C# specific message catalog format
10457 @code{xgettext -k_}
10459 @item Formatting with positions
10460 @code{String.Format "@{1@} @{0@}"}
10465 @item po-mode marking
10469 Before marking strings as internationalizable, uses of the string
10470 concatenation operator need to be converted to @code{String.Format}
10471 invocations. For example, @code{"file "+filename+" not found"} becomes
10472 @code{String.Format("file @{0@} not found", filename)}.
10473 Only after this is done, can the strings be marked and extracted.
10475 GNU gettext uses the native C#/.NET internationalization mechanism, namely
10476 the classes @code{ResourceManager} and @code{ResourceSet}. Applications
10477 use the @code{ResourceManager} methods to retrieve the native language
10478 translation of strings. An instance of @code{ResourceSet} is the in-memory
10479 representation of a message catalog file. The @code{ResourceManager} loads
10480 and accesses @code{ResourceSet} instances as needed to look up the
10483 There are two formats of @code{ResourceSet}s that can be directly loaded by
10484 the C# runtime: @code{.resources} files and @code{.dll} files.
10488 The @code{.resources} format is a binary file usually generated through the
10489 @code{resgen} or @code{monoresgen} utility, but which doesn't support plural
10490 forms. @code{.resources} files can also be embedded in .NET @code{.exe} files.
10491 This only affects whether a file system access is performed to load the message
10492 catalog; it doesn't affect the contents of the message catalog.
10495 On the other hand, the @code{.dll} format is a binary file that is compiled
10496 from @code{.cs} source code and can support plural forms (provided it is
10497 accessed through the GNU gettext API, see below).
10500 Note that these .NET @code{.dll} and @code{.exe} files are not tied to a
10501 particular platform; their file format and GNU gettext for C# can be used
10504 To convert a PO file to a @code{.resources} file, the @code{msgfmt} program
10505 can be used with the option @samp{--csharp-resources}. To convert a
10506 @code{.resources} file back to a PO file, the @code{msgunfmt} program can be
10507 used with the option @samp{--csharp-resources}. You can also, in some cases,
10508 use the @code{resgen} program (from the @code{pnet} package) or the
10509 @code{monoresgen} program (from the @code{mono}/@code{mcs} package). These
10510 programs can also convert a @code{.resources} file back to a PO file. But
10511 beware: as of this writing (January 2004), the @code{monoresgen} converter is
10512 quite buggy and the @code{resgen} converter ignores the encoding of the PO
10515 To convert a PO file to a @code{.dll} file, the @code{msgfmt} program can be
10516 used with the option @code{--csharp}. The result will be a @code{.dll} file
10517 containing a subclass of @code{GettextResourceSet}, which itself is a subclass
10518 of @code{ResourceSet}. To convert a @code{.dll} file containing a
10519 @code{GettextResourceSet} subclass back to a PO file, the @code{msgunfmt}
10520 program can be used with the option @code{--csharp}.
10522 The advantages of the @code{.dll} format over the @code{.resources} format
10527 Freedom to localize: Users can add their own translations to an application
10528 after it has been built and distributed. Whereas when the programmer uses
10529 a @code{ResourceManager} constructor provided by the system, the set of
10530 @code{.resources} files for an application must be specified when the
10531 application is built and cannot be extended afterwards.
10532 @c If this were the only issue with the @code{.resources} format, one could
10533 @c use the @code{ResourceManager.CreateFileBasedResourceManager} function.
10536 Plural handling: A message catalog in @code{.dll} format supports the plural
10537 handling function @code{GetPluralString}. Whereas @code{.resources} files can
10538 only contain data and only support lookups that depend on a single string.
10541 Context handling: A message catalog in @code{.dll} format supports the
10542 query-with-context functions @code{GetParticularString} and
10543 @code{GetParticularPluralString}. Whereas @code{.resources} files can
10544 only contain data and only support lookups that depend on a single string.
10547 The @code{GettextResourceManager} that loads the message catalogs in
10548 @code{.dll} format also provides for inheritance on a per-message basis.
10549 For example, in Austrian (@code{de_AT}) locale, translations from the German
10550 (@code{de}) message catalog will be used for messages not found in the
10551 Austrian message catalog. This has the consequence that the Austrian
10552 translators need only translate those few messages for which the translation
10553 into Austrian differs from the German one. Whereas when working with
10554 @code{.resources} files, each message catalog must provide the translations
10555 of all messages by itself.
10558 The @code{GettextResourceManager} that loads the message catalogs in
10559 @code{.dll} format also provides for a fallback: The English @var{msgid} is
10560 returned when no translation can be found. Whereas when working with
10561 @code{.resources} files, a language-neutral @code{.resources} file must
10562 explicitly be provided as a fallback.
10565 On the side of the programmatic APIs, the programmer can use either the
10566 standard @code{ResourceManager} API and the GNU @code{GettextResourceManager}
10567 API. The latter is an extension of the former, because
10568 @code{GettextResourceManager} is a subclass of @code{ResourceManager}.
10572 The @code{System.Resources.ResourceManager} API.
10574 This API works with resources in @code{.resources} format.
10576 The creation of the @code{ResourceManager} is done through
10578 new ResourceManager(domainname, Assembly.GetExecutingAssembly())
10582 The @code{GetString} function returns a string's translation. Note that this
10583 function returns null when a translation is missing (i.e.@: not even found in
10584 the fallback resource file).
10587 The @code{GNU.Gettext.GettextResourceManager} API.
10589 This API works with resources in @code{.dll} format.
10591 Reference documentation is in the
10592 @uref{csharpdoc/index.html,csharpdoc directory}.
10594 The creation of the @code{ResourceManager} is done through
10596 new GettextResourceManager(domainname)
10599 The @code{GetString} function returns a string's translation. Note that when
10600 a translation is missing, the @var{msgid} argument is returned unchanged.
10602 The @code{GetPluralString} function returns a string translation with plural
10603 handling, like the @code{ngettext} function in C.
10605 The @code{GetParticularString} function returns a string's translation,
10606 specific to a particular context, like the @code{pgettext} function in C.
10607 Note that when a translation is missing, the @var{msgid} argument is returned
10610 The @code{GetParticularPluralString} function returns a string translation,
10611 specific to a particular context, with plural handling, like the
10612 @code{npgettext} function in C.
10614 @cindex @code{libintl} for C#
10615 To use this API, one needs the @code{GNU.Gettext.dll} file which is part of
10616 the GNU gettext package and distributed under the LGPL.
10619 You can also mix both approaches: use the
10620 @code{GNU.Gettext.GettextResourceManager} constructor, but otherwise use
10621 only the @code{ResourceManager} type and only the @code{GetString} method.
10622 This is appropriate when you want to profit from the tools for PO files,
10623 but don't want to change an existing source code that uses
10624 @code{ResourceManager} and don't (yet) need the @code{GetPluralString} method.
10626 Two examples, using the second API, are available in the @file{examples}
10627 directory: @code{hello-csharp}, @code{hello-csharp-forms}.
10629 Now, to make use of the API and define a shorthand for @samp{GetString},
10630 there are two idioms that you can choose from:
10634 In a unique class of your project, say @samp{Util}, define a static variable
10635 holding the @code{ResourceManager} instance:
10638 public static GettextResourceManager MyResourceManager =
10639 new GettextResourceManager("domain-name");
10642 All classes containing internationalized strings then contain
10645 private static GettextResourceManager Res = Util.MyResourceManager;
10646 private static String _(String s) @{ return Res.GetString(s); @}
10650 and the shorthand is used like this:
10653 Console.WriteLine(_("Operation completed."));
10657 You add a class with a very short name, say @samp{S}, containing just the
10658 definition of the resource manager and of the shorthand:
10662 public static GettextResourceManager MyResourceManager =
10663 new GettextResourceManager("domain-name");
10664 public static String _(String s) @{
10665 return MyResourceManager.GetString(s);
10671 and the shorthand is used like this:
10674 Console.WriteLine(S._("Operation completed."));
10678 Which of the two idioms you choose, will depend on whether copying two lines
10679 of codes into every class is more acceptable in your project than a class
10680 with a single-letter name.
10682 @node gawk, Pascal, C#, List of Programming Languages
10683 @subsection GNU awk
10691 @item File extension
10692 @code{awk}, @code{gawk}, @code{twjr}.
10693 The file extension @code{twjr} is used by TexiWeb Jr
10694 (@uref{https://github.com/arnoldrobbins/texiwebjr}).
10696 @item String syntax
10699 @item gettext shorthand
10702 @item gettext/ngettext functions
10703 @code{dcgettext}, missing @code{dcngettext} in gawk-3.1.0
10706 @code{TEXTDOMAIN} variable
10708 @item bindtextdomain
10709 @code{bindtextdomain} function
10712 automatic, but missing @code{setlocale (LC_MESSAGES, "")} in gawk-3.1.0
10717 @item Use or emulate GNU gettext
10723 @item Formatting with positions
10724 @code{printf "%2$d %1$d"} (GNU awk only)
10727 On platforms without gettext, no translation. On non-GNU awks, you must
10728 define @code{dcgettext}, @code{dcngettext} and @code{bindtextdomain}
10731 @item po-mode marking
10735 An example is available in the @file{examples} directory: @code{hello-gawk}.
10737 @node Pascal, wxWidgets, gawk, List of Programming Languages
10738 @subsection Pascal - Free Pascal Compiler
10740 @cindex Free Pascal
10741 @cindex Object Pascal
10747 @item File extension
10748 @code{pp}, @code{pas}
10750 @item String syntax
10753 @item gettext shorthand
10756 @item gettext/ngettext functions
10757 ---, use @code{ResourceString} data type instead
10760 ---, use @code{TranslateResourceStrings} function instead
10762 @item bindtextdomain
10763 ---, use @code{TranslateResourceStrings} function instead
10766 automatic, but uses only LANG, not LC_MESSAGES or LC_ALL
10769 @code{@{$mode delphi@}} or @code{@{$mode objfpc@}}@*@code{uses gettext;}
10771 @item Use or emulate GNU gettext
10775 @code{ppc386} followed by @code{xgettext} or @code{rstconv}
10777 @item Formatting with positions
10778 @code{uses sysutils;}@*@code{format "%1:d %0:d"}
10783 @item po-mode marking
10787 The Pascal compiler has special support for the @code{ResourceString} data
10788 type. It generates a @code{.rst} file. This is then converted to a
10789 @code{.pot} file by use of @code{xgettext} or @code{rstconv}. At runtime,
10790 a @code{.mo} file corresponding to translations of this @code{.pot} file
10791 can be loaded using the @code{TranslateResourceStrings} function in the
10792 @code{gettext} unit.
10794 An example is available in the @file{examples} directory: @code{hello-pascal}.
10796 @node wxWidgets, YCP, Pascal, List of Programming Languages
10797 @subsection wxWidgets library
10798 @cindex @code{wxWidgets} library
10804 @item File extension
10807 @item String syntax
10810 @item gettext shorthand
10813 @item gettext/ngettext functions
10814 @code{wxLocale::GetString}, @code{wxGetTranslation}
10817 @code{wxLocale::AddCatalog}
10819 @item bindtextdomain
10820 @code{wxLocale::AddCatalogLookupPathPrefix}
10823 @code{wxLocale::Init}, @code{wxSetLocale}
10826 @code{#include <wx/intl.h>}
10828 @item Use or emulate GNU gettext
10829 emulate, see @code{include/wx/intl.h} and @code{src/common/intl.cpp}
10834 @item Formatting with positions
10835 wxString::Format supports positions if and only if the system has
10836 @code{wprintf()}, @code{vswprintf()} functions and they support positions
10837 according to POSIX.
10842 @item po-mode marking
10846 @node YCP, Tcl, wxWidgets, List of Programming Languages
10847 @subsection YCP - YaST2 scripting language
10849 @cindex YaST2 scripting language
10853 libycp, libycp-devel, yast2-core, yast2-core-devel
10855 @item File extension
10858 @item String syntax
10861 @item gettext shorthand
10864 @item gettext/ngettext functions
10865 @code{_()} with 1 or 3 arguments
10868 @code{textdomain} statement
10870 @item bindtextdomain
10879 @item Use or emulate GNU gettext
10885 @item Formatting with positions
10886 @code{sformat "%2 %1"}
10891 @item po-mode marking
10895 An example is available in the @file{examples} directory: @code{hello-ycp}.
10897 @node Tcl, Perl, YCP, List of Programming Languages
10898 @subsection Tcl - Tk's scripting language
10900 @cindex Tk's scripting language
10906 @item File extension
10909 @item String syntax
10912 @item gettext shorthand
10915 @item gettext/ngettext functions
10916 @code{::msgcat::mc}
10921 @item bindtextdomain
10922 ---, use @code{::msgcat::mcload} instead
10925 automatic, uses LANG, but ignores LC_MESSAGES and LC_ALL
10928 @code{package require msgcat}
10929 @*@code{proc _ @{s@} @{return [::msgcat::mc $s]@}}
10931 @item Use or emulate GNU gettext
10932 ---, uses a Tcl specific message catalog format
10935 @code{xgettext -k_}
10937 @item Formatting with positions
10938 @code{format "%2\$d %1\$d"}
10943 @item po-mode marking
10947 Two examples are available in the @file{examples} directory:
10948 @code{hello-tcl}, @code{hello-tcl-tk}.
10950 Before marking strings as internationalizable, substitutions of variables
10951 into the string need to be converted to @code{format} applications. For
10952 example, @code{"file $filename not found"} becomes
10953 @code{[format "file %s not found" $filename]}.
10954 Only after this is done, can the strings be marked and extracted.
10955 After marking, this example becomes
10956 @code{[format [_ "file %s not found"] $filename]} or
10957 @code{[msgcat::mc "file %s not found" $filename]}. Note that the
10958 @code{msgcat::mc} function implicitly calls @code{format} when more than one
10961 @node Perl, PHP, Tcl, List of Programming Languages
10969 @item File extension
10970 @code{pl}, @code{PL}, @code{pm}, @code{perl}, @code{cgi}
10972 @item String syntax
10979 @item @code{qq (abc)}
10981 @item @code{q (abc)}
10983 @item @code{qr /abc/}
10985 @item @code{qx (/bin/date)}
10987 @item @code{/pattern match/}
10989 @item @code{?pattern match?}
10991 @item @code{s/substitution/operators/}
10993 @item @code{$tied_hash@{"message"@}}
10995 @item @code{$tied_hash_reference->@{"message"@}}
10997 @item etc., issue the command @samp{man perlsyn} for details
11001 @item gettext shorthand
11002 @code{__} (double underscore)
11004 @item gettext/ngettext functions
11005 @code{gettext}, @code{dgettext}, @code{dcgettext}, @code{ngettext},
11006 @code{dngettext}, @code{dcngettext}
11009 @code{textdomain} function
11011 @item bindtextdomain
11012 @code{bindtextdomain} function
11014 @item bind_textdomain_codeset
11015 @code{bind_textdomain_codeset} function
11018 Use @code{setlocale (LC_ALL, "");}
11022 @*@code{use Locale::TextDomain;} (included in the package libintl-perl
11023 which is available on the Comprehensive Perl Archive Network CPAN,
11024 http://www.cpan.org/).
11026 @item Use or emulate GNU gettext
11027 platform dependent: gettext_pp emulates, gettext_xs uses GNU gettext
11030 @code{xgettext -k__ -k\$__ -k%__ -k__x -k__n:1,2 -k__nx:1,2 -k__xn:1,2 -kN__ -k}
11032 @item Formatting with positions
11033 Both kinds of format strings support formatting with positions.
11034 @*@code{printf "%2\$d %1\$d", ...} (requires Perl 5.8.0 or newer)
11035 @*@code{__expand("[new] replaces [old]", old => $oldvalue, new => $newvalue)}
11038 The @code{libintl-perl} package is platform independent but is not
11039 part of the Perl core. The programmer is responsible for
11040 providing a dummy implementation of the required functions if the
11041 package is not installed on the target system.
11043 @item po-mode marking
11046 @item Documentation
11047 Included in @code{libintl-perl}, available on CPAN
11048 (http://www.cpan.org/).
11052 An example is available in the @file{examples} directory: @code{hello-perl}.
11054 @cindex marking Perl sources
11056 The @code{xgettext} parser backend for Perl differs significantly from
11057 the parser backends for other programming languages, just as Perl
11058 itself differs significantly from other programming languages. The
11059 Perl parser backend offers many more string marking facilities than
11060 the other backends but it also has some Perl specific limitations, the
11061 worst probably being its imperfectness.
11064 * General Problems:: General Problems Parsing Perl Code
11065 * Default Keywords:: Which Keywords Will xgettext Look For?
11066 * Special Keywords:: How to Extract Hash Keys
11067 * Quote-like Expressions:: What are Strings And Quote-like Expressions?
11068 * Interpolation I:: Invalid String Interpolation
11069 * Interpolation II:: Valid String Interpolation
11070 * Parentheses:: When To Use Parentheses
11071 * Long Lines:: How To Grok with Long Lines
11072 * Perl Pitfalls:: Bugs, Pitfalls, and Things That Do Not Work
11075 @node General Problems, Default Keywords, Perl, Perl
11076 @subsubsection General Problems Parsing Perl Code
11078 It is often heard that only Perl can parse Perl. This is not true.
11079 Perl cannot be @emph{parsed} at all, it can only be @emph{executed}.
11080 Perl has various built-in ambiguities that can only be resolved at runtime.
11082 The following example may illustrate one common problem:
11085 print gettext "Hello World!";
11088 Although this example looks like a bullet-proof case of a function
11089 invocation, it is not:
11092 open gettext, ">testfile" or die;
11093 print gettext "Hello world!"
11096 In this context, the string @code{gettext} looks more like a
11097 file handle. But not necessarily:
11100 use Locale::Messages qw (:libintl_h);
11101 open gettext ">testfile" or die;
11102 print gettext "Hello world!";
11105 Now, the file is probably syntactically incorrect, provided that the module
11106 @code{Locale::Messages} found first in the Perl include path exports a
11107 function @code{gettext}. But what if the module
11108 @code{Locale::Messages} really looks like this?
11111 use vars qw (*gettext);
11116 In this case, the string @code{gettext} will be interpreted as a file
11117 handle again, and the above example will create a file @file{testfile}
11118 and write the string ``Hello world!'' into it. Even advanced
11119 control flow analysis will not really help:
11127 print gettext "Hello world!";
11130 If the module @code{Sane} exports a function @code{gettext} that does
11131 what we expect, and the module @code{InSane} opens a file for writing
11132 and associates the @emph{handle} @code{gettext} with this output
11133 stream, we are clueless again about what will happen at runtime. It is
11134 completely unpredictable. The truth is that Perl has so many ways to
11135 fill its symbol table at runtime that it is impossible to interpret a
11136 particular piece of code without executing it.
11138 Of course, @code{xgettext} will not execute your Perl sources while
11139 scanning for translatable strings, but rather use heuristics in order
11140 to guess what you meant.
11142 Another problem is the ambiguity of the slash and the question mark.
11143 Their interpretation depends on the context:
11147 print "OK\n" if /foobar/;
11152 # Another pattern match.
11153 print "OK\n" if ?foobar?;
11156 print $x ? "foo" : "bar";
11159 The slash may either act as the division operator or introduce a
11160 pattern match, whereas the question mark may act as the ternary
11161 conditional operator or as a pattern match, too. Other programming
11162 languages like @code{awk} present similar problems, but the consequences of a
11163 misinterpretation are particularly nasty with Perl sources. In @code{awk}
11164 for instance, a statement can never exceed one line and the parser
11165 can recover from a parsing error at the next newline and interpret
11166 the rest of the input stream correctly. Perl is different, as a
11167 pattern match is terminated by the next appearance of the delimiter
11168 (the slash or the question mark) in the input stream, regardless of
11169 the semantic context. If a slash is really a division sign but
11170 mis-interpreted as a pattern match, the rest of the input file is most
11171 probably parsed incorrectly.
11173 There are certain cases, where the ambiguity cannot be resolved at all:
11176 $x = wantarray ? 1 : 0;
11179 The Perl built-in function @code{wantarray} does not accept any arguments.
11180 The Perl parser therefore knows that the question mark does not start
11181 a regular expression but is the ternary conditional operator.
11184 sub wantarrays @{@}
11185 $x = wantarrays ? 1 : 0;
11188 Now the situation is different. The function @code{wantarrays} takes
11189 a variable number of arguments (like any non-prototyped Perl function).
11190 The question mark is now the delimiter of a pattern match, and hence
11191 the piece of code does not compile.
11194 sub wantarrays() @{@}
11195 $x = wantarrays ? 1 : 0;
11198 Now the function is prototyped, Perl knows that it does not accept any
11199 arguments, and the question mark is therefore interpreted as the
11200 ternaray operator again. But that unfortunately outsmarts @code{xgettext}.
11202 The Perl parser in @code{xgettext} cannot know whether a function has
11203 a prototype and what that prototype would look like. It therefore makes
11204 an educated guess. If a function is known to be a Perl built-in and
11205 this function does not accept any arguments, a following question mark
11206 or slash is treated as an operator, otherwise as the delimiter of a
11207 following regular expression. The Perl built-ins that do not accept
11208 arguments are @code{wantarray}, @code{fork}, @code{time}, @code{times},
11209 @code{getlogin}, @code{getppid}, @code{getpwent}, @code{getgrent},
11210 @code{gethostent}, @code{getnetent}, @code{getprotoent}, @code{getservent},
11211 @code{setpwent}, @code{setgrent}, @code{endpwent}, @code{endgrent},
11212 @code{endhostent}, @code{endnetent}, @code{endprotoent}, and
11215 If you find that @code{xgettext} fails to extract strings from
11216 portions of your sources, you should therefore look out for slashes
11217 and/or question marks preceding these sections. You may have come
11218 across a bug in @code{xgettext}'s Perl parser (and of course you
11219 should report that bug). In the meantime you should consider to
11220 reformulate your code in a manner less challenging to @code{xgettext}.
11222 In particular, if the parser is too dumb to see that a function
11223 does not accept arguments, use parentheses:
11226 $x = somefunc() ? 1 : 0;
11227 $y = (somefunc) ? 1 : 0;
11230 In fact the Perl parser itself has similar problems and warns you
11231 about such constructs.
11233 @node Default Keywords, Special Keywords, General Problems, Perl
11234 @subsubsection Which keywords will xgettext look for?
11235 @cindex Perl default keywords
11237 Unless you instruct @code{xgettext} otherwise by invoking it with one
11238 of the options @code{--keyword} or @code{-k}, it will recognize the
11239 following keywords in your Perl sources:
11243 @item @code{gettext}
11245 @item @code{dgettext}
11247 @item @code{dcgettext}
11249 @item @code{ngettext:1,2}
11251 The first (singular) and the second (plural) argument will be
11254 @item @code{dngettext:1,2}
11256 The first (singular) and the second (plural) argument will be
11259 @item @code{dcngettext:1,2}
11261 The first (singular) and the second (plural) argument will be
11264 @item @code{gettext_noop}
11266 @item @code{%gettext}
11268 The keys of lookups into the hash @code{%gettext} will be extracted.
11270 @item @code{$gettext}
11272 The keys of lookups into the hash reference @code{$gettext} will be extracted.
11276 @node Special Keywords, Quote-like Expressions, Default Keywords, Perl
11277 @subsubsection How to Extract Hash Keys
11278 @cindex Perl special keywords for hash-lookups
11280 Translating messages at runtime is normally performed by looking up the
11281 original string in the translation database and returning the
11282 translated version. The ``natural'' Perl implementation is a hash
11283 lookup, and, of course, @code{xgettext} supports such practice.
11286 print __"Hello world!";
11287 print $__@{"Hello world!"@};
11288 print $__->@{"Hello world!"@};
11289 print $$__@{"Hello world!"@};
11292 The above four lines all do the same thing. The Perl module
11293 @code{Locale::TextDomain} exports by default a hash @code{%__} that
11294 is tied to the function @code{__()}. It also exports a reference
11295 @code{$__} to @code{%__}.
11297 If an argument to the @code{xgettext} option @code{--keyword},
11298 resp. @code{-k} starts with a percent sign, the rest of the keyword is
11299 interpreted as the name of a hash. If it starts with a dollar
11300 sign, the rest of the keyword is interpreted as a reference to a
11303 Note that you can omit the quotation marks (single or double) around
11304 the hash key (almost) whenever Perl itself allows it:
11307 print $gettext@{Error@};
11310 The exact rule is: You can omit the surrounding quotes, when the hash
11311 key is a valid C (!) identifier, i.e.@: when it starts with an
11312 underscore or an ASCII letter and is followed by an arbitrary number
11313 of underscores, ASCII letters or digits. Other Unicode characters
11314 are @emph{not} allowed, regardless of the @code{use utf8} pragma.
11316 @node Quote-like Expressions, Interpolation I, Special Keywords, Perl
11317 @subsubsection What are Strings And Quote-like Expressions?
11318 @cindex Perl quote-like expressions
11320 Perl offers a plethora of different string constructs. Those that can
11321 be used either as arguments to functions or inside braces for hash
11322 lookups are generally supported by @code{xgettext}.
11325 @item @strong{double-quoted strings}
11328 print gettext "Hello World!";
11331 @item @strong{single-quoted strings}
11334 print gettext 'Hello World!';
11337 @item @strong{the operator qq}
11340 print gettext qq |Hello World!|;
11341 print gettext qq <E-mail: <guido\@@imperia.net>>;
11344 The operator @code{qq} is fully supported. You can use arbitrary
11345 delimiters, including the four bracketing delimiters (round, angle,
11346 square, curly) that nest.
11348 @item @strong{the operator q}
11351 print gettext q |Hello World!|;
11352 print gettext q <E-mail: <guido@@imperia.net>>;
11355 The operator @code{q} is fully supported. You can use arbitrary
11356 delimiters, including the four bracketing delimiters (round, angle,
11357 square, curly) that nest.
11359 @item @strong{the operator qx}
11362 print gettext qx ;LANGUAGE=C /bin/date;
11363 print gettext qx [/usr/bin/ls | grep '^[A-Z]*'];
11366 The operator @code{qx} is fully supported. You can use arbitrary
11367 delimiters, including the four bracketing delimiters (round, angle,
11368 square, curly) that nest.
11370 The example is actually a useless use of @code{gettext}. It will
11371 invoke the @code{gettext} function on the output of the command
11372 specified with the @code{qx} operator. The feature was included
11373 in order to make the interface consistent (the parser will extract
11374 all strings and quote-like expressions).
11376 @item @strong{here documents}
11380 print gettext <<'EOF';
11381 program not found in $PATH
11384 print ngettext <<EOF, <<"EOF";
11387 several files deleted
11392 Here-documents are recognized. If the delimiter is enclosed in single
11393 quotes, the string is not interpolated. If it is enclosed in double
11394 quotes or has no quotes at all, the string is interpolated.
11396 Delimiters that start with a digit are not supported!
11400 @node Interpolation I, Interpolation II, Quote-like Expressions, Perl
11401 @subsubsection Invalid Uses Of String Interpolation
11402 @cindex Perl invalid string interpolation
11404 Perl is capable of interpolating variables into strings. This offers
11405 some nice features in localized programs but can also lead to
11408 A common error is a construct like the following:
11411 print gettext "This is the program $0!\n";
11414 Perl will interpolate at runtime the value of the variable @code{$0}
11415 into the argument of the @code{gettext()} function. Hence, this
11416 argument is not a string constant but a variable argument (@code{$0}
11417 is a global variable that holds the name of the Perl script being
11418 executed). The interpolation is performed by Perl before the string
11419 argument is passed to @code{gettext()} and will therefore depend on
11420 the name of the script which can only be determined at runtime.
11421 Consequently, it is almost impossible that a translation can be looked
11422 up at runtime (except if, by accident, the interpolated string is found
11423 in the message catalog).
11425 The @code{xgettext} program will therefore terminate parsing with a fatal
11426 error if it encounters a variable inside of an extracted string. In
11427 general, this will happen for all kinds of string interpolations that
11428 cannot be safely performed at compile time. If you absolutely know
11429 what you are doing, you can always circumvent this behavior:
11432 my $know_what_i_am_doing = "This is program $0!\n";
11433 print gettext $know_what_i_am_doing;
11436 Since the parser only recognizes strings and quote-like expressions,
11437 but not variables or other terms, the above construct will be
11438 accepted. You will have to find another way, however, to let your
11439 original string make it into your message catalog.
11441 If invoked with the option @code{--extract-all}, resp. @code{-a},
11442 variable interpolation will be accepted. Rationale: You will
11443 generally use this option in order to prepare your sources for
11444 internationalization.
11446 Please see the manual page @samp{man perlop} for details of strings and
11447 quote-like expressions that are subject to interpolation and those
11448 that are not. Safe interpolations (that will not lead to a fatal
11453 @item the escape sequences @code{\t} (tab, HT, TAB), @code{\n}
11454 (newline, NL), @code{\r} (return, CR), @code{\f} (form feed, FF),
11455 @code{\b} (backspace, BS), @code{\a} (alarm, bell, BEL), and @code{\e}
11458 @item octal chars, like @code{\033}
11460 Note that octal escapes in the range of 400-777 are translated into a
11461 UTF-8 representation, regardless of the presence of the @code{use utf8} pragma.
11463 @item hex chars, like @code{\x1b}
11465 @item wide hex chars, like @code{\x@{263a@}}
11467 Note that this escape is translated into a UTF-8 representation,
11468 regardless of the presence of the @code{use utf8} pragma.
11470 @item control chars, like @code{\c[} (CTRL-[)
11472 @item named Unicode chars, like @code{\N@{LATIN CAPITAL LETTER C WITH CEDILLA@}}
11474 Note that this escape is translated into a UTF-8 representation,
11475 regardless of the presence of the @code{use utf8} pragma.
11478 The following escapes are considered partially safe:
11482 @item @code{\l} lowercase next char
11484 @item @code{\u} uppercase next char
11486 @item @code{\L} lowercase till \E
11488 @item @code{\U} uppercase till \E
11490 @item @code{\E} end case modification
11492 @item @code{\Q} quote non-word characters till \E
11496 These escapes are only considered safe if the string consists of
11497 ASCII characters only. Translation of characters outside the range
11498 defined by ASCII is locale-dependent and can actually only be performed
11499 at runtime; @code{xgettext} doesn't do these locale-dependent translations
11500 at extraction time.
11502 Except for the modifier @code{\Q}, these translations, albeit valid,
11503 are generally useless and only obfuscate your sources. If a
11504 translation can be safely performed at compile time you can just as
11505 well write what you mean.
11507 @node Interpolation II, Parentheses, Interpolation I, Perl
11508 @subsubsection Valid Uses Of String Interpolation
11509 @cindex Perl valid string interpolation
11511 Perl is often used to generate sources for other programming languages
11512 or arbitrary file formats. Web applications that output HTML code
11513 make a prominent example for such usage.
11515 You will often come across situations where you want to intersperse
11516 code written in the target (programming) language with translatable
11517 messages, like in the following HTML example:
11520 print gettext <<EOF;
11521 <h1>My Homepage</h1>
11522 <script language="JavaScript"><!--
11523 for (i = 0; i < 100; ++i) @{
11524 alert ("Thank you so much for visiting my homepage!");
11530 The parser will extract the entire here document, and it will appear
11531 entirely in the resulting PO file, including the JavaScript snippet
11532 embedded in the HTML code. If you exaggerate with constructs like
11533 the above, you will run the risk that the translators of your package
11534 will look out for a less challenging project. You should consider an
11535 alternative expression here:
11539 <h1>$gettext@{"My Homepage"@}</h1>
11540 <script language="JavaScript"><!--
11541 for (i = 0; i < 100; ++i) @{
11542 alert ("$gettext@{'Thank you so much for visiting my homepage!'@}");
11548 Only the translatable portions of the code will be extracted here, and
11549 the resulting PO file will begrudgingly improve in terms of readability.
11551 You can interpolate hash lookups in all strings or quote-like
11552 expressions that are subject to interpolation (see the manual page
11553 @samp{man perlop} for details). Double interpolation is invalid, however:
11556 # TRANSLATORS: Replace "the earth" with the name of your planet.
11557 print gettext qq@{Welcome to $gettext->@{"the earth"@}@};
11560 The @code{qq}-quoted string is recognized as an argument to @code{xgettext} in
11561 the first place, and checked for invalid variable interpolation. The
11562 dollar sign of hash-dereferencing will therefore terminate the parser
11563 with an ``invalid interpolation'' error.
11565 It is valid to interpolate hash lookups in regular expressions:
11568 if ($var =~ /$gettext@{"the earth"@}/) @{
11569 print gettext "Match!\n";
11571 s/$gettext@{"U. S. A."@}/$gettext@{"U. S. A."@} $gettext@{"(dial +0)"@}/g;
11574 @node Parentheses, Long Lines, Interpolation II, Perl
11575 @subsubsection When To Use Parentheses
11576 @cindex Perl parentheses
11578 In Perl, parentheses around function arguments are mostly optional.
11579 @code{xgettext} will always assume that all
11580 recognized keywords (except for hashes and hash references) are names
11581 of properly prototyped functions, and will (hopefully) only require
11582 parentheses where Perl itself requires them. All constructs in the
11583 following example are therefore ok to use:
11587 print gettext ("Hello World!\n");
11588 print gettext "Hello World!\n";
11589 print dgettext ($package => "Hello World!\n");
11590 print dgettext $package, "Hello World!\n";
11592 # The "fat comma" => turns the left-hand side argument into a
11593 # single-quoted string!
11594 print dgettext smellovision => "Hello World!\n";
11596 # The following assignment only works with prototyped functions.
11597 # Otherwise, the functions will act as "greedy" list operators and
11598 # eat up all following arguments.
11599 my $anonymous_hash = @{
11600 planet => gettext "earth",
11601 cakes => ngettext "one cake", "several cakes", $n,
11604 # The same without fat comma:
11605 my $other_hash = @{
11606 'planet', gettext "earth",
11607 'cakes', ngettext "one cake", "several cakes", $n,
11611 # Parentheses are only significant for the first argument.
11612 print dngettext 'package', ("one cake", "several cakes", $n), $discarded;
11616 @node Long Lines, Perl Pitfalls, Parentheses, Perl
11617 @subsubsection How To Grok with Long Lines
11618 @cindex Perl long lines
11620 The necessity of long messages can often lead to a cumbersome or
11621 unreadable coding style. Perl has several options that may prevent
11622 you from writing unreadable code, and
11623 @code{xgettext} does its best to do likewise. This is where the dot
11624 operator (the string concatenation operator) may come in handy:
11628 print gettext ("This is a very long"
11629 . " message that is still"
11630 . " readable, because"
11631 . " it is split into"
11632 . " multiple lines.\n");
11636 Perl is smart enough to concatenate these constant string fragments
11637 into one long string at compile time, and so is
11638 @code{xgettext}. You will only find one long message in the resulting
11641 Note that the future Perl 6 will probably use the underscore
11642 (@samp{_}) as the string concatenation operator, and the dot
11643 (@samp{.}) for dereferencing. This new syntax is not yet supported by
11646 If embedded newline characters are not an issue, or even desired, you
11647 may also insert newline characters inside quoted strings wherever you
11652 print gettext ("<em>In HTML output
11653 embedded newlines are generally no
11654 problem, since adjacent whitespace
11655 is always rendered into a single
11656 space character.</em>");
11660 You may also consider to use here documents:
11664 print gettext <<EOF;
11666 embedded newlines are generally no
11667 problem, since adjacent whitespace
11668 is always rendered into a single
11669 space character.</em>
11674 Please do not forget that the line breaks are real, i.e.@: they
11675 translate into newline characters that will consequently show up in
11676 the resulting POT file.
11678 @node Perl Pitfalls, , Long Lines, Perl
11679 @subsubsection Bugs, Pitfalls, And Things That Do Not Work
11680 @cindex Perl pitfalls
11682 The foregoing sections should have proven that
11683 @code{xgettext} is quite smart in extracting translatable strings from
11684 Perl sources. Yet, some more or less exotic constructs that could be
11685 expected to work, actually do not work.
11687 One of the more relevant limitations can be found in the
11688 implementation of variable interpolation inside quoted strings. Only
11689 simple hash lookups can be used there:
11693 $gettext@{"The dot operator"
11696 Likewise, you cannot @@@{[ gettext ("interpolate function calls") ]@}
11697 inside quoted strings or quote-like expressions.
11701 This is valid Perl code and will actually trigger invocations of the
11702 @code{gettext} function at runtime. Yet, the Perl parser in
11703 @code{xgettext} will fail to recognize the strings. A less obvious
11704 example can be found in the interpolation of regular expressions:
11707 s/<!--START_OF_WEEK-->/gettext ("Sunday")/e;
11710 The modifier @code{e} will cause the substitution to be interpreted as
11711 an evaluable statement. Consequently, at runtime the function
11712 @code{gettext()} is called, but again, the parser fails to extract the
11713 string ``Sunday''. Use a temporary variable as a simple workaround if
11714 you really happen to need this feature:
11717 my $sunday = gettext "Sunday";
11718 s/<!--START_OF_WEEK-->/$sunday/;
11721 Hash slices would also be handy but are not recognized:
11724 my @@weekdays = @@gettext@{'Sunday', 'Monday', 'Tuesday', 'Wednesday',
11725 'Thursday', 'Friday', 'Saturday'@};
11727 @@weekdays = @@gettext@{qw (Sunday Monday Tuesday Wednesday Thursday
11728 Friday Saturday) @};
11731 This is perfectly valid usage of the tied hash @code{%gettext} but the
11732 strings are not recognized and therefore will not be extracted.
11734 Another caveat of the current version is its rudimentary support for
11735 non-ASCII characters in identifiers. You may encounter serious
11736 problems if you use identifiers with characters outside the range of
11737 'A'-'Z', 'a'-'z', '0'-'9' and the underscore '_'.
11739 Maybe some of these missing features will be implemented in future
11740 versions, but since you can always make do without them at minimal effort,
11741 these todos have very low priority.
11743 A nasty problem are brace format strings that already contain braces
11744 as part of the normal text, for example the usage strings typically
11745 encountered in programs:
11748 die "usage: $0 @{OPTIONS@} FILENAME...\n";
11751 If you want to internationalize this code with Perl brace format strings,
11752 you will run into a problem:
11755 die __x ("usage: @{program@} @{OPTIONS@} FILENAME...\n", program => $0);
11758 Whereas @samp{@{program@}} is a placeholder, @samp{@{OPTIONS@}}
11759 is not and should probably be translated. Yet, there is no way to teach
11760 the Perl parser in @code{xgettext} to recognize the first one, and leave
11761 the other one alone.
11763 There are two possible work-arounds for this problem. If you are
11764 sure that your program will run under Perl 5.8.0 or newer (these
11765 Perl versions handle positional parameters in @code{printf()}) or
11766 if you are sure that the translator will not have to reorder the arguments
11767 in her translation -- for example if you have only one brace placeholder
11768 in your string, or if it describes a syntax, like in this one --, you can
11769 mark the string as @code{no-perl-brace-format} and use @code{printf()}:
11772 # xgettext: no-perl-brace-format
11773 die sprintf ("usage: %s @{OPTIONS@} FILENAME...\n", $0);
11776 If you want to use the more portable Perl brace format, you will have to do
11777 put placeholders in place of the literal braces:
11780 die __x ("usage: @{program@} @{[@}OPTIONS@{]@} FILENAME...\n",
11781 program => $0, '[' => '@{', ']' => '@}');
11784 Perl brace format strings know no escaping mechanism. No matter how this
11785 escaping mechanism looked like, it would either give the programmer a
11786 hard time, make translating Perl brace format strings heavy-going, or
11787 result in a performance penalty at runtime, when the format directives
11788 get executed. Most of the time you will happily get along with
11789 @code{printf()} for this special case.
11791 @node PHP, Pike, Perl, List of Programming Languages
11792 @subsection PHP Hypertext Preprocessor
11797 mod_php4, mod_php4-core, phpdoc
11799 @item File extension
11800 @code{php}, @code{php3}, @code{php4}
11802 @item String syntax
11803 @code{"abc"}, @code{'abc'}
11805 @item gettext shorthand
11808 @item gettext/ngettext functions
11809 @code{gettext}, @code{dgettext}, @code{dcgettext}; starting with PHP 4.2.0
11810 also @code{ngettext}, @code{dngettext}, @code{dcngettext}
11813 @code{textdomain} function
11815 @item bindtextdomain
11816 @code{bindtextdomain} function
11819 Programmer must call @code{setlocale (LC_ALL, "")}
11824 @item Use or emulate GNU gettext
11830 @item Formatting with positions
11831 @code{printf "%2\$d %1\$d"}
11834 On platforms without gettext, the functions are not available.
11836 @item po-mode marking
11840 An example is available in the @file{examples} directory: @code{hello-php}.
11842 @node Pike, GCC-source, PHP, List of Programming Languages
11850 @item File extension
11853 @item String syntax
11856 @item gettext shorthand
11859 @item gettext/ngettext functions
11860 @code{gettext}, @code{dgettext}, @code{dcgettext}
11863 @code{textdomain} function
11865 @item bindtextdomain
11866 @code{bindtextdomain} function
11869 @code{setlocale} function
11872 @code{import Locale.Gettext;}
11874 @item Use or emulate GNU gettext
11880 @item Formatting with positions
11884 On platforms without gettext, the functions are not available.
11886 @item po-mode marking
11890 @node GCC-source, Lua, Pike, List of Programming Languages
11891 @subsection GNU Compiler Collection sources
11898 @item File extension
11899 @code{c}, @code{h}.
11901 @item String syntax
11904 @item gettext shorthand
11907 @item gettext/ngettext functions
11908 @code{gettext}, @code{dgettext}, @code{dcgettext}, @code{ngettext},
11909 @code{dngettext}, @code{dcngettext}
11912 @code{textdomain} function
11914 @item bindtextdomain
11915 @code{bindtextdomain} function
11918 Programmer must call @code{setlocale (LC_ALL, "")}
11921 @code{#include "intl.h"}
11923 @item Use or emulate GNU gettext
11927 @code{xgettext -k_}
11929 @item Formatting with positions
11933 Uses autoconf macros
11935 @item po-mode marking
11939 @node Lua, JavaScript, GCC-source, List of Programming Languages
11946 @item File extension
11949 @item String syntax
11956 @item @code{[[abc]]}
11958 @item @code{[=[abc]=]}
11960 @item @code{[==[abc]==]}
11966 @item gettext shorthand
11969 @item gettext/ngettext functions
11970 @code{gettext.gettext}, @code{gettext.dgettext}, @code{gettext.dcgettext},
11971 @code{gettext.ngettext}, @code{gettext.dngettext}, @code{gettext.dcngettext}
11974 @code{textdomain} function
11976 @item bindtextdomain
11977 @code{bindtextdomain} function
11983 @code{require 'gettext'} or running lua interpreter with @code{-l gettext} option
11985 @item Use or emulate GNU gettext
11991 @item Formatting with positions
11995 On platforms without gettext, the functions are not available.
11997 @item po-mode marking
12001 @node JavaScript, Vala, Lua, List of Programming Languages
12002 @subsection JavaScript
12008 @item File extension
12011 @item String syntax
12020 @item gettext shorthand
12023 @item gettext/ngettext functions
12024 @code{gettext}, @code{dgettext}, @code{dcgettext}, @code{ngettext},
12028 @code{textdomain} function
12030 @item bindtextdomain
12031 @code{bindtextdomain} function
12039 @item Use or emulate GNU gettext
12045 @item Formatting with positions
12049 On platforms without gettext, the functions are not available.
12051 @item po-mode marking
12055 @node Vala, , JavaScript, List of Programming Languages
12062 @item File extension
12065 @item String syntax
12070 @item @code{"""abc"""}
12074 @item gettext shorthand
12077 @item gettext/ngettext functions
12078 @code{gettext}, @code{dgettext}, @code{dcgettext}, @code{ngettext},
12079 @code{dngettext}, @code{dpgettext}, @code{dpgettext2}
12082 @code{textdomain} function, defined under the @code{Intl} namespace
12084 @item bindtextdomain
12085 @code{bindtextdomain} function, defined under the @code{Intl} namespace
12088 Programmer must call @code{Intl.setlocale (LocaleCategory.ALL, "")}
12093 @item Use or emulate GNU gettext
12099 @item Formatting with positions
12100 Same as for the C language.
12103 autoconf (gettext.m4) and #if ENABLE_NLS
12105 @item po-mode marking
12109 @c This is the template for new languages.
12118 @item File extension
12120 @item String syntax
12122 @item gettext shorthand
12124 @item gettext/ngettext functions
12128 @item bindtextdomain
12134 @item Use or emulate GNU gettext
12138 @item Formatting with positions
12142 @item po-mode marking
12147 @node List of Data Formats, , List of Programming Languages, Programming Languages
12148 @section Internationalizable Data
12150 Here is a list of other data formats which can be internationalized
12154 * POT:: POT - Portable Object Template
12155 * RST:: Resource String Table
12156 * Glade:: Glade - GNOME user interface description
12157 * GSettings:: GSettings - GNOME user configuration schema
12158 * AppData:: AppData - freedesktop.org application description
12159 * Preparing ITS Rules:: Preparing Rules for XML Internationalization
12162 @node POT, RST, List of Data Formats, List of Data Formats
12163 @subsection POT - Portable Object Template
12169 @item File extension
12170 @code{pot}, @code{po}
12176 @node RST, Glade, POT, List of Data Formats
12177 @subsection Resource String Table
12184 @item File extension
12188 @code{xgettext}, @code{rstconv}
12191 @node Glade, GSettings, RST, List of Data Formats
12192 @subsection Glade - GNOME user interface description
12196 glade, libglade, glade2, libglade2, intltool
12198 @item File extension
12199 @code{glade}, @code{glade2}, @code{ui}
12202 @code{xgettext}, @code{libglade-xgettext}, @code{xml-i18n-extract}, @code{intltool-extract}
12205 @node GSettings, AppData, Glade, List of Data Formats
12206 @subsection GSettings - GNOME user configuration schema
12212 @item File extension
12216 @code{xgettext}, @code{intltool-extract}
12219 @node AppData, Preparing ITS Rules, GSettings, List of Data Formats
12220 @subsection AppData - freedesktop.org application description
12224 appdata-tools, appstream, libappstream-glib, libappstream-glib-builder
12226 @item File extension
12230 @code{xgettext}, @code{intltool-extract}, @code{itstool}
12236 @node Preparing ITS Rules, , AppData, List of Data Formats
12237 @subsection Preparing Rules for XML Internationalization
12238 @cindex preparing rules for XML translation
12240 Marking translatable strings in an XML file is done through a separate
12241 "rule" file, making use of the Internationalization Tag Set standard
12242 (ITS, @uref{http://www.w3.org/TR/its20/}). The currently supported ITS
12243 data categories are: @samp{Translate}, @samp{Localization Note},
12244 @samp{Elements Within Text}, and @samp{Preserve Space}. In addition to
12245 them, @code{xgettext} also recognizes the following extended data
12251 This data category associates @code{msgctxt} to the extracted text. In
12252 the global rule, the @code{contextRule} element contains the following:
12256 A required @code{selector} attribute. It contains an absolute selector
12257 that selects the nodes to which this rule applies.
12260 A required @code{contextPointer} attribute that contains a relative
12261 selector pointing to a node that holds the @code{msgctxt} value.
12264 An optional @code{textPointer} attribute that contains a relative
12265 selector pointing to a node that holds the @code{msgid} value.
12268 @item Escape Special Characters
12270 This data category indicates whether the special XML characters
12271 (@code{<}, @code{>}, @code{&}, @code{"}) are escaped with entity
12272 reference. In the global rule, the @code{escapeRule} element contains
12277 A required @code{selector} attribute. It contains an absolute selector
12278 that selects the nodes to which this rule applies.
12281 A required @code{escape} attribute with the value @code{yes} or @code{no}.
12284 @item Extended Preserve Space
12286 This data category extends the standard @samp{Preserve Space} data
12287 category with the additional value @samp{trim}. The value means to
12288 remove the leading and trailing whitespaces of the content, but not to
12289 normalize whitespaces in the middle. In the global rule, the
12290 @code{preserveSpaceRule} element contains the following:
12294 A required @code{selector} attribute. It contains an absolute selector
12295 that selects the nodes to which this rule applies.
12298 A required @code{space} attribute with the value @code{default},
12299 @code{preserve}, or @code{trim}.
12304 All those extended data categories can only be expressed with global
12305 rules, and the rule elements have to have the
12306 @code{https://www.gnu.org/s/gettext/ns/its/extensions/1.0} namespace.
12308 Given the following XML document in a file @file{messages.xml}:
12311 <?xml version="1.0"?>
12314 <p>A translatable string</p>
12317 <p translatable="no">A non-translatable string</p>
12322 To extract the first text content ("A translatable string"), but not the
12323 second ("A non-translatable string"), the following ITS rules can be used:
12326 <?xml version="1.0"?>
12327 <its:rules xmlns:its="http://www.w3.org/2005/11/its" version="1.0">
12328 <its:translateRule selector="/messages" translate="no"/>
12329 <its:translateRule selector="//message/p" translate="yes"/>
12331 <!-- If 'p' has an attribute 'translatable' with the value 'no', then
12332 the content is not translatable. -->
12333 <its:translateRule selector="//message/p[@@translatable = 'no']"
12338 @samp{xgettext} needs another file called "locating rule" to associate
12339 an ITS rule with an XML file. If the above ITS file is saved as
12340 @file{messages.its}, the locating rule would look like:
12343 <?xml version="1.0"?>
12345 <locatingRule name="Messages" pattern="*.xml">
12346 <documentRule localName="messages" target="messages.its"/>
12348 <locatingRule name="Messages" pattern="*.msg" target="messages.its"/>
12352 The @code{locatingRule} element must have a @code{pattern} attribute,
12353 which denotes either a literal file name or a wildcard pattern of the
12354 XML file. The @code{locatingRule} element can have child
12355 @code{documentRule} element, which adds checks on the content of the XML
12358 The first rule matches any file with the @file{.xml} file extension, but
12359 it only applies to XML files whose root element is @samp{<messages>}.
12361 The second rule indicates that the same ITS rule file are also
12362 applicable to any file with the @file{.msg} file extension. The
12363 optional @code{name} attribute of @code{locatingRule} allows to choose
12364 rules by name, typically with @code{xgettext}'s @code{-L} option.
12366 The associated ITS rule file is indicated by the @code{target} attribute
12367 of @code{locatingRule} or @code{documentRule}. If it is specified in a
12368 @code{documentRule} element, the parent @code{locatingRule} shouldn't
12369 have the @code{target} attribute.
12371 Locating rule files must have the @file{.loc} file extension. Both ITS
12372 rule files and locating rule files must be installed in the
12373 @file{$prefix/share/gettext/its} directory. Once those files are
12374 properly installed, @code{xgettext} can extract translatable strings
12375 from the matching XML files.
12377 @subsubsection Two Use-cases of Translated Strings in XML
12379 For XML, there are two use-cases of translated strings. One is the case
12380 where the translated strings are directly consumed by programs, and the
12381 other is the case where the translated strings are merged back to the
12382 original XML document. In the former case, special characters in the
12383 extracted strings shouldn't be escaped, while they should in the latter
12384 case. To control wheter to escape special characters, the @samp{Escape
12385 Special Characters} data category can be used.
12387 To merge the translations, the @samp{msgfmt} program can be used with
12388 the option @code{--xml}. @xref{msgfmt Invocation}, for more details
12389 about how one calls the @samp{msgfmt} program. @samp{msgfmt}'s
12390 @code{--xml} option doesn't perform character escaping, so translated
12391 strings can have arbitrary XML constructs, such as elements for markup.
12393 @c This is the template for new data formats.
12402 @item File extension
12409 @node Conclusion, Language Codes, Programming Languages, Top
12410 @chapter Concluding Remarks
12412 We would like to conclude this GNU @code{gettext} manual by presenting
12413 an history of the Translation Project so far. We finally give
12414 a few pointers for those who want to do further research or readings
12415 about Native Language Support matters.
12418 * History:: History of GNU @code{gettext}
12419 * References:: Related Readings
12422 @node History, References, Conclusion, Conclusion
12423 @section History of GNU @code{gettext}
12424 @cindex history of GNU @code{gettext}
12426 Internationalization concerns and algorithms have been informally
12427 and casually discussed for years in GNU, sometimes around GNU
12428 @code{libc}, maybe around the incoming @code{Hurd}, or otherwise
12429 (nobody clearly remembers). And even then, when the work started for
12430 real, this was somewhat independently of these previous discussions.
12432 This all began in July 1994, when Patrick D'Cruze had the idea and
12433 initiative of internationalizing version 3.9.2 of GNU @code{fileutils}.
12434 He then asked Jim Meyering, the maintainer, how to get those changes
12435 folded into an official release. That first draft was full of
12436 @code{#ifdef}s and somewhat disconcerting, and Jim wanted to find
12437 nicer ways. Patrick and Jim shared some tries and experimentations
12438 in this area. Then, feeling that this might eventually have a deeper
12439 impact on GNU, Jim wanted to know what standards were, and contacted
12440 Richard Stallman, who very quickly and verbally described an overall
12441 design for what was meant to become @code{glocale}, at that time.
12443 Jim implemented @code{glocale} and got a lot of exhausting feedback
12444 from Patrick and Richard, of course, but also from Mitchum DSouza
12445 (who wrote a @code{catgets}-like package), Roland McGrath, maybe David
12446 MacKenzie, Fran@,{c}ois Pinard, and Paul Eggert, all pushing and
12447 pulling in various directions, not always compatible, to the extent
12448 that after a couple of test releases, @code{glocale} was torn apart.
12449 In particular, Paul Eggert -- always keeping an eye on developments
12450 in Solaris -- advocated the use of the @code{gettext} API over
12451 @code{glocale}'s @code{catgets}-based API.
12453 While Jim took some distance and time and became dad for a second
12454 time, Roland wanted to get GNU @code{libc} internationalized, and
12455 got Ulrich Drepper involved in that project. Instead of starting
12456 from @code{glocale}, Ulrich rewrote something from scratch, but
12457 more conforming to the set of guidelines who emerged out of the
12458 @code{glocale} effort. Then, Ulrich got people from the previous
12459 forum to involve themselves into this new project, and the switch
12460 from @code{glocale} to what was first named @code{msgutils}, renamed
12461 @code{nlsutils}, and later @code{gettext}, became officially accepted
12462 by Richard in May 1995 or so.
12464 Let's summarize by saying that Ulrich Drepper wrote GNU @code{gettext}
12465 in April 1995. The first official release of the package, including
12466 PO mode, occurred in July 1995, and was numbered 0.7. Other people
12467 contributed to the effort by providing a discussion forum around
12468 Ulrich, writing little pieces of code, or testing. These are quoted
12469 in the @code{THANKS} file which comes with the GNU @code{gettext}
12472 While this was being done, Fran@,{c}ois adapted half a dozen of
12473 GNU packages to @code{glocale} first, then later to @code{gettext},
12474 putting them in pretest, so providing along the way an effective
12475 user environment for fine tuning the evolving tools. He also took
12476 the responsibility of organizing and coordinating the Translation
12477 Project. After nearly a year of informal exchanges between people from
12478 many countries, translator teams started to exist in May 1995, through
12479 the creation and support by Patrick D'Cruze of twenty unmoderated
12480 mailing lists for that many native languages, and two moderated
12481 lists: one for reaching all teams at once, the other for reaching
12482 all willing maintainers of internationalized free software packages.
12484 Fran@,{c}ois also wrote PO mode in June 1995 with the collaboration
12485 of Greg McGary, as a kind of contribution to Ulrich's package.
12486 He also gave a hand with the GNU @code{gettext} Texinfo manual.
12488 In 1997, Ulrich Drepper released the GNU libc 2.0, which included the
12489 @code{gettext}, @code{textdomain} and @code{bindtextdomain} functions.
12491 In 2000, Ulrich Drepper added plural form handling (the @code{ngettext}
12492 function) to GNU libc. Later, in 2001, he released GNU libc 2.2.x,
12493 which is the first free C library with full internationalization support.
12495 Ulrich being quite busy in his role of General Maintainer of GNU libc,
12496 he handed over the GNU @code{gettext} maintenance to Bruno Haible in
12497 2000. Bruno added the plural form handling to the tools as well, added
12498 support for UTF-8 and CJK locales, and wrote a few new tools for
12499 manipulating PO files.
12501 @node References, , History, Conclusion
12502 @section Related Readings
12503 @cindex related reading
12504 @cindex bibliography
12506 @strong{ NOTE: } This documentation section is outdated and needs to be
12509 Eugene H. Dorr (@file{dorre@@well.com}) maintains an interesting
12510 bibliography on internationalization matters, called
12511 @cite{Internationalization Reference List}, which is available as:
12513 ftp://ftp.ora.com/pub/examples/nutshell/ujip/doc/i18n-books.txt
12516 Michael Gschwind (@file{mike@@vlsivie.tuwien.ac.at}) maintains a
12517 Frequently Asked Questions (FAQ) list, entitled @cite{Programming for
12518 Internationalisation}. This FAQ discusses writing programs which
12519 can handle different language conventions, character sets, etc.;
12520 and is applicable to all character set encodings, with particular
12521 emphasis on @w{ISO 8859-1}. It is regularly published in Usenet
12522 groups @file{comp.unix.questions}, @file{comp.std.internat},
12523 @file{comp.software.international}, @file{comp.lang.c},
12524 @file{comp.windows.x}, @file{comp.std.c}, @file{comp.answers}
12525 and @file{news.answers}. The home location of this document is:
12527 ftp://ftp.vlsivie.tuwien.ac.at/pub/8bit/ISO-programming
12530 Patrick D'Cruze (@file{pdcruze@@li.org}) wrote a tutorial about NLS
12531 matters, and Jochen Hein (@file{Hein@@student.tu-clausthal.de}) took
12532 over the responsibility of maintaining it. It may be found as:
12534 ftp://sunsite.unc.edu/pub/Linux/utils/nls/catalogs/Incoming/...
12535 ...locale-tutorial-0.8.txt.gz
12538 This site is mirrored in:
12540 ftp://ftp.ibp.fr/pub/linux/sunsite/
12543 A French version of the same tutorial should be findable at:
12545 ftp://ftp.ibp.fr/pub/linux/french/docs/
12548 together with French translations of many Linux-related documents.
12550 @node Language Codes, Country Codes, Conclusion, Top
12551 @appendix Language Codes
12552 @cindex language codes
12555 The @w{ISO 639} standard defines two-letter codes for many languages, and
12556 three-letter codes for more rarely used languages.
12557 All abbreviations for languages used in the Translation Project should
12558 come from this standard.
12561 * Usual Language Codes:: Two-letter ISO 639 language codes
12562 * Rare Language Codes:: Three-letter ISO 639 language codes
12565 @node Usual Language Codes, Rare Language Codes, Language Codes, Language Codes
12566 @appendixsec Usual Language Codes
12568 For the commonly used languages, the @w{ISO 639-1} standard defines two-letter
12572 @include iso-639.texi
12575 @node Rare Language Codes, , Usual Language Codes, Language Codes
12576 @appendixsec Rare Language Codes
12578 For rarely used languages, the @w{ISO 639-2} standard defines three-letter
12579 codes. Here is the current list, reduced to only living languages with at least
12580 one million of speakers.
12583 @include iso-639-2.texi
12586 @node Country Codes, Licenses, Language Codes, Top
12587 @appendix Country Codes
12588 @cindex country codes
12591 The @w{ISO 3166} standard defines two character codes for many countries
12592 and territories. All abbreviations for countries used in the Translation
12593 Project should come from this standard.
12596 @include iso-3166.texi
12599 @node Licenses, Program Index, Country Codes, Top
12603 The files of this package are covered by the licenses indicated in each
12604 particular file or directory. Here is a summary:
12608 The @code{libintl} and @code{libasprintf} libraries are covered by the
12609 GNU Lesser General Public License (LGPL).
12610 A copy of the license is included in @ref{GNU LGPL}.
12613 The executable programs of this package and the @code{libgettextpo} library
12614 are covered by the GNU General Public License (GPL).
12615 A copy of the license is included in @ref{GNU GPL}.
12618 This manual is free documentation. It is dually licensed under the
12619 GNU FDL and the GNU GPL. This means that you can redistribute this
12620 manual under either of these two licenses, at your choice.
12622 This manual is covered by the GNU FDL. Permission is granted to copy,
12623 distribute and/or modify this document under the terms of the
12624 GNU Free Documentation License (FDL), either version 1.2 of the
12625 License, or (at your option) any later version published by the
12626 Free Software Foundation (FSF); with no Invariant Sections, with no
12627 Front-Cover Text, and with no Back-Cover Texts.
12628 A copy of the license is included in @ref{GNU FDL}.
12630 This manual is covered by the GNU GPL. You can redistribute it and/or
12631 modify it under the terms of the GNU General Public License (GPL), either
12632 version 2 of the License, or (at your option) any later version published
12633 by the Free Software Foundation (FSF).
12634 A copy of the license is included in @ref{GNU GPL}.
12638 * GNU GPL:: GNU General Public License
12639 * GNU LGPL:: GNU Lesser General Public License
12640 * GNU FDL:: GNU Free Documentation License
12644 @node GNU GPL, GNU LGPL, Licenses, Licenses
12645 @appendixsec GNU GENERAL PUBLIC LICENSE
12646 @cindex GPL, GNU General Public License
12647 @cindex License, GNU GPL
12650 @node GNU LGPL, GNU FDL, GNU GPL, Licenses
12651 @appendixsec GNU LESSER GENERAL PUBLIC LICENSE
12652 @cindex LGPL, GNU Lesser General Public License
12653 @cindex License, GNU LGPL
12656 @node GNU FDL, , GNU LGPL, Licenses
12657 @appendixsec GNU Free Documentation License
12658 @cindex FDL, GNU Free Documentation License
12659 @cindex License, GNU FDL
12662 @node Program Index, Option Index, Licenses, Top
12663 @unnumbered Program Index
12667 @node Option Index, Variable Index, Program Index, Top
12668 @unnumbered Option Index
12672 @node Variable Index, PO Mode Index, Option Index, Top
12673 @unnumbered Variable Index
12677 @node PO Mode Index, Autoconf Macro Index, Variable Index, Top
12678 @unnumbered PO Mode Index
12682 @node Autoconf Macro Index, Index, PO Mode Index, Top
12683 @unnumbered Autoconf Macro Index
12687 @node Index, , Autoconf Macro Index, Top
12688 @unnumbered General Index
12694 @c Local variables:
12695 @c texinfo-column-for-description: 32