@menu
* Introduction:: Introduction
* Users:: The User's View
-* Basics:: PO Files and PO Mode Basics
+* PO Files:: The Format of PO Files
* Sources:: Preparing Program Sources
* Template:: Making the PO Template File
* Creating:: Creating a New PO File
* Updating:: Updating Existing PO Files
+* Editing:: Editing PO Files
* Manipulating:: Manipulating PO Files
* Binaries:: Producing Binary MO Files
* Programmers:: The Programmer's View
* Matrix:: The Current @file{ABOUT-NLS} Matrix
* End Users:: Magic for End Users
-PO Files and PO Mode Basics
-
-* Installation:: Completing GNU @code{gettext} Installation
-* PO Files:: The Format of PO Files
-* Main PO Commands:: Main Commands
-* Entry Positioning:: Entry Positioning
-* Normalizing:: Normalizing Strings in Entries
-
Preparing Program Sources
* Triggering:: Triggering @code{gettext} Operations
Updating Existing PO Files
* msgmerge Invocation:: Invoking the @code{msgmerge} Program
+
+Editing PO Files
+
+* KBabel:: KDE's PO File Editor
+* Gtranslator:: GNOME's PO File Editor
+* PO Mode:: Emacs's PO File Editor
+
+Emacs's PO File Editor
+
+* Installation:: Completing GNU @code{gettext} Installation
+* Main PO Commands:: Main Commands
+* Entry Positioning:: Entry Positioning
+* Normalizing:: Normalizing Strings in Entries
* Translated Entries:: Translated Entries
* Fuzzy Entries:: Fuzzy Entries
* Untranslated Entries:: Untranslated Entries
The remainder of this manual has the purpose of explaining in depth the various
steps outlined above.
-@node Users, Basics, Introduction, Top
+@node Users, PO Files, Introduction, Top
@chapter The User's View
When GNU @code{gettext} will truly have reached its goal, average users
@w{@samp{export LANG; LANG=de_DE}} (in @code{sh}). They could even do
this from their @file{.login} or @file{.profile} file.
-@node Basics, Sources, Users, Top
-@chapter PO Files and PO Mode Basics
+@node PO Files, Sources, Users, Top
+@chapter The Format of PO Files
+@cindex PO files' format
+@cindex file format, @file{.po}
The GNU @code{gettext} toolset helps programmers and translators
at producing, updating and using translation files, mainly those
-PO files which are textual, editable files. This chapter stresses
-the format of PO files, and contains a PO mode starter. PO mode
-description is spread throughout this manual instead of being concentrated
-in one place. Here we present only the basics of PO mode.
-
-@menu
-* Installation:: Completing GNU @code{gettext} Installation
-* PO Files:: The Format of PO Files
-* Main PO Commands:: Main Commands
-* Entry Positioning:: Entry Positioning
-* Normalizing:: Normalizing Strings in Entries
-@end menu
-
-@node Installation, PO Files, Basics, Basics
-@section Completing GNU @code{gettext} Installation
-
-@cindex installing @code{gettext}
-@cindex @code{gettext} installation
-Once you have received, unpacked, configured and compiled the GNU
-@code{gettext} distribution, the @samp{make install} command puts in
-place the programs @code{xgettext}, @code{msgfmt}, @code{gettext}, and
-@code{msgmerge}, as well as their available message catalogs. To
-top off a comfortable installation, you might also want to make the
-PO mode available to your Emacs users.
-
-@emindex @file{.emacs} customizations
-@emindex installing PO mode
-During the installation of the PO mode, you might want to modify your
-file @file{.emacs}, once and for all, so it contains a few lines looking
-like:
-
-@example
-(setq auto-mode-alist
- (cons '("\\.po\\'\\|\\.po\\." . po-mode) auto-mode-alist))
-(autoload 'po-mode "po-mode" "Major mode for translators to edit PO files" t)
-@end example
-
-Later, whenever you edit some @file{.po}
-file, or any file having the string @samp{.po.} within its name,
-Emacs loads @file{po-mode.elc} (or @file{po-mode.el}) as needed, and
-automatically activates PO mode commands for the associated buffer.
-The string @emph{PO} appears in the mode line for any buffer for
-which PO mode is active. Many PO files may be active at once in a
-single Emacs session.
-
-If you are using Emacs version 20 or newer, and have already installed
-the appropriate international fonts on your system, you may also tell
-Emacs how to determine automatically the coding system of every PO file.
-This will often (but not always) cause the necessary fonts to be loaded
-and used for displaying the translations on your Emacs screen. For this
-to happen, add the lines:
-
-@example
-(modify-coding-system-alist 'file "\\.po\\'\\|\\.po\\."
- 'po-find-file-coding-system)
-(autoload 'po-find-file-coding-system "po-mode")
-@end example
-
-@noindent
-to your @file{.emacs} file. If, with this, you still see boxes instead
-of international characters, try a different font set (via Shift Mouse
-button 1).
-
-@node PO Files, Main PO Commands, Installation, Basics
-@section The Format of PO Files
-@cindex PO files' format
-@cindex file format, @file{.po}
+PO files which are textual, editable files. This chapter explains
+the format of PO files.
A PO file is made up of many entries, each entry holding the relation
between an original untranslated string and its corresponding
tools, and might disappear or be replaced unexpectedly when the PO
file is given to @code{msgmerge}.
-@node Main PO Commands, Entry Positioning, PO Files, Basics
-@section Main PO mode Commands
-
-@cindex PO mode (Emacs) commands
-@emindex commands
-After setting up Emacs with something similar to the lines in
-@ref{Installation}, PO mode is activated for a window when Emacs finds a
-PO file in that window. This puts the window read-only and establishes a
-po-mode-map, which is a genuine Emacs mode, in a way that is not derived
-from text mode in any way. Functions found on @code{po-mode-hook},
-if any, will be executed.
+@node Sources, Template, PO Files, Top
+@chapter Preparing Program Sources
+@cindex preparing programs for translation
-When PO mode is active in a window, the letters @samp{PO} appear
-in the mode line for that window. The mode line also displays how
-many entries of each kind are held in the PO file. For example,
-the string @samp{132t+3f+10u+2o} would tell the translator that the
-PO mode contains 132 translated entries (@pxref{Translated Entries},
-3 fuzzy entries (@pxref{Fuzzy Entries}), 10 untranslated entries
-(@pxref{Untranslated Entries}) and 2 obsolete entries (@pxref{Obsolete
-Entries}). Zero-coefficients items are not shown. So, in this example, if
-the fuzzy entries were unfuzzied, the untranslated entries were translated
-and the obsolete entries were deleted, the mode line would merely display
-@samp{145t} for the counters.
+@c FIXME: Rewrite (the whole chapter).
-The main PO commands are those which do not fit into the other categories of
-subsequent sections. These allow for quitting PO mode or for managing windows
-in special ways.
+For the programmer, changes to the C source code fall into three
+categories. First, you have to make the localization functions
+known to all modules needing message translation. Second, you should
+properly trigger the operation of GNU @code{gettext} when the program
+initializes, usually from the @code{main} function. Last, you should
+identify and especially mark all constant strings in your program
+needing translation.
-@table @kbd
-@item _
-@efindex _@r{, PO Mode command}
-Undo last modification to the PO file (@code{po-undo}).
+Presuming that your set of programs, or package, has been adjusted
+so all needed GNU @code{gettext} files are available, and your
+@file{Makefile} files are adjusted (@pxref{Maintainers}), each C module
+having translated C strings should contain the line:
-@item Q
-@efindex Q@r{, PO Mode command}
-Quit processing and save the PO file (@code{po-quit}).
+@cindex include file @file{libintl.h}
+@example
+#include <libintl.h>
+@end example
-@item q
-@efindex q@r{, PO Mode command}
-Quit processing, possibly after confirmation (@code{po-confirm-and-quit}).
+Similarly, each C module containing @code{printf()}/@code{fprintf()}/...
+calls with a format string that could be a translated C string (even if
+the C string comes from a different C module) should contain the line:
-@item 0
-@efindex 0@r{, PO Mode command}
-Temporary leave the PO file window (@code{po-other-window}).
+@example
+#include <libintl.h>
+@end example
-@item ?
-@itemx h
-@efindex ?@r{, PO Mode command}
-@efindex h@r{, PO Mode command}
-Show help about PO mode (@code{po-help}).
+The remaining changes to your C sources are discussed in the further
+sections of this chapter.
-@item =
-@efindex =@r{, PO Mode command}
-Give some PO file statistics (@code{po-statistics}).
+@menu
+* Triggering:: Triggering @code{gettext} Operations
+* Preparing Strings:: Preparing Translatable Strings
+* Mark Keywords:: How Marks Appear in Sources
+* Marking:: Marking Translatable Strings
+* c-format Flag:: Telling something about the following string
+* Special cases:: Special Cases of Translatable Strings
+* Names:: Marking Proper Names for Translation
+* Libraries:: Preparing Library Sources
+@end menu
-@item V
-@efindex V@r{, PO Mode command}
-Batch validate the format of the whole PO file (@code{po-validate}).
+@node Triggering, Preparing Strings, Sources, Sources
+@section Triggering @code{gettext} Operations
-@end table
+@cindex initialization
+The initialization of locale data should be done with more or less
+the same code in every program, as demonstrated below:
-@efindex _@r{, PO Mode command}
-@efindex po-undo@r{, PO Mode command}
-The command @kbd{_} (@code{po-undo}) interfaces to the Emacs
-@emph{undo} facility. @xref{Undo, , Undoing Changes, emacs, The Emacs
-Editor}. Each time @kbd{U} is typed, modifications which the translator
-did to the PO file are undone a little more. For the purpose of
-undoing, each PO mode command is atomic. This is especially true for
-the @kbd{@key{RET}} command: the whole edition made by using a single
-use of this command is undone at once, even if the edition itself
-implied several actions. However, while in the editing window, one
-can undo the edition work quite parsimoniously.
+@example
+@group
+int
+main (int argc, char *argv[])
+@{
+ @dots{}
+ setlocale (LC_ALL, "");
+ bindtextdomain (PACKAGE, LOCALEDIR);
+ textdomain (PACKAGE);
+ @dots{}
+@}
+@end group
+@end example
-@efindex Q@r{, PO Mode command}
-@efindex q@r{, PO Mode command}
-@efindex po-quit@r{, PO Mode command}
-@efindex po-confirm-and-quit@r{, PO Mode command}
-The commands @kbd{Q} (@code{po-quit}) and @kbd{q}
-(@code{po-confirm-and-quit}) are used when the translator is done with the
-PO file. The former is a bit less verbose than the latter. If the file
-has been modified, it is saved to disk first. In both cases, and prior to
-all this, the commands check if any untranslated messages remain in the
-PO file and, if so, the translator is asked if she really wants to leave
-off working with this PO file. This is the preferred way of getting rid
-of an Emacs PO file buffer. Merely killing it through the usual command
-@w{@kbd{C-x k}} (@code{kill-buffer}) is not the tidiest way to proceed.
+@var{PACKAGE} and @var{LOCALEDIR} should be provided either by
+@file{config.h} or by the Makefile. For now consult the @code{gettext}
+or @code{hello} sources for more information.
-@efindex 0@r{, PO Mode command}
-@efindex po-other-window@r{, PO Mode command}
-The command @kbd{0} (@code{po-other-window}) is another, softer way,
-to leave PO mode, temporarily. It just moves the cursor to some other
-Emacs window, and pops one if necessary. For example, if the translator
-just got PO mode to show some source context in some other, she might
-discover some apparent bug in the program source that needs correction.
-This command allows the translator to change sex, become a programmer,
-and have the cursor right into the window containing the program she
-(or rather @emph{he}) wants to modify. By later getting the cursor back
-in the PO file window, or by asking Emacs to edit this file once again,
-PO mode is then recovered.
+@cindex locale facet, LC_ALL
+@cindex locale facet, LC_CTYPE
+The use of @code{LC_ALL} might not be appropriate for you.
+@code{LC_ALL} includes all locale categories and especially
+@code{LC_CTYPE}. This later category is responsible for determining
+character classes with the @code{isalnum} etc. functions from
+@file{ctype.h} which could especially for programs, which process some
+kind of input language, be wrong. For example this would mean that a
+source code using the @,{c} (c-cedilla character) is runnable in
+France but not in the U.S.
-@efindex ?@r{, PO Mode command}
-@efindex h@r{, PO Mode command}
-@efindex po-help@r{, PO Mode command}
-The command @kbd{h} (@code{po-help}) displays a summary of all available PO
-mode commands. The translator should then type any character to resume
-normal PO mode operations. The command @kbd{?} has the same effect
-as @kbd{h}.
+Some systems also have problems with parsing numbers using the
+@code{scanf} functions if an other but the @code{LC_ALL} locale is used.
+The standards say that additional formats but the one known in the
+@code{"C"} locale might be recognized. But some systems seem to reject
+numbers in the @code{"C"} locale format. In some situation, it might
+also be a problem with the notation itself which makes it impossible to
+recognize whether the number is in the @code{"C"} locale or the local
+format. This can happen if thousands separator characters are used.
+Some locales define this character according to the national
+conventions to @code{'.'} which is the same character used in the
+@code{"C"} locale to denote the decimal point.
-@efindex =@r{, PO Mode command}
-@efindex po-statistics@r{, PO Mode command}
-The command @kbd{=} (@code{po-statistics}) computes the total number of
-entries in the PO file, the ordinal of the current entry (counted from
-1), the number of untranslated entries, the number of obsolete entries,
-and displays all these numbers.
+So it is sometimes necessary to replace the @code{LC_ALL} line in the
+code above by a sequence of @code{setlocale} lines
-@efindex V@r{, PO Mode command}
-@efindex po-validate@r{, PO Mode command}
-The command @kbd{V} (@code{po-validate}) launches @code{msgfmt} in
-checking and verbose
-mode over the current PO file. This command first offers to save the
-current PO file on disk. The @code{msgfmt} tool, from GNU @code{gettext},
-has the purpose of creating a MO file out of a PO file, and PO mode uses
-the features of this program for checking the overall format of a PO file,
-as well as all individual entries.
-
-@efindex next-error@r{, stepping through PO file validation results}
-The program @code{msgfmt} runs asynchronously with Emacs, so the
-translator regains control immediately while her PO file is being studied.
-Error output is collected in the Emacs @samp{*compilation*} buffer,
-displayed in another window. The regular Emacs command @kbd{C-x`}
-(@code{next-error}), as well as other usual compile commands, allow the
-translator to reposition quickly to the offending parts of the PO file.
-Once the cursor is on the line in error, the translator may decide on
-any PO mode action which would help correcting the error.
+@example
+@group
+@{
+ @dots{}
+ setlocale (LC_CTYPE, "");
+ setlocale (LC_MESSAGES, "");
+ @dots{}
+@}
+@end group
+@end example
-@node Entry Positioning, Normalizing, Main PO Commands, Basics
-@section Entry Positioning
+@cindex locale facet, LC_CTYPE
+@cindex locale facet, LC_COLLATE
+@cindex locale facet, LC_MONETARY
+@cindex locale facet, LC_NUMERIC
+@cindex locale facet, LC_TIME
+@cindex locale facet, LC_MESSAGES
+@cindex locale facet, LC_RESPONSES
+@noindent
+On all POSIX conformant systems the locale categories @code{LC_CTYPE},
+@code{LC_MESSAGES}, @code{LC_COLLATE}, @code{LC_MONETARY},
+@code{LC_NUMERIC}, and @code{LC_TIME} are available. On some systems
+which are only ISO C compliant, @code{LC_MESSAGES} is missing, but
+a substitute for it is defined in GNU gettext's @code{<libintl.h>}.
-@emindex current entry of a PO file
-The cursor in a PO file window is almost always part of
-an entry. The only exceptions are the special case when the cursor
-is after the last entry in the file, or when the PO file is
-empty. The entry where the cursor is found to be is said to be the
-current entry. Many PO mode commands operate on the current entry,
-so moving the cursor does more than allowing the translator to browse
-the PO file, this also selects on which entry commands operate.
+Note that changing the @code{LC_CTYPE} also affects the functions
+declared in the @code{<ctype.h>} standard header. If this is not
+desirable in your application (for example in a compiler's parser),
+you can use a set of substitute functions which hardwire the C locale,
+such as found in the @code{<c-ctype.h>} and @code{<c-ctype.c>} files
+in the gettext source distribution.
-@emindex moving through a PO file
-Some PO mode commands alter the position of the cursor in a specialized
-way. A few of those special purpose positioning are described here,
-the others are described in following sections (for a complete list try
-@kbd{C-h m}):
+It is also possible to switch the locale forth and back between the
+environment dependent locale and the C locale, but this approach is
+normally avoided because a @code{setlocale} call is expensive,
+because it is tedious to determine the places where a locale switch
+is needed in a large program's source, and because switching a locale
+is not multithread-safe.
-@table @kbd
+@node Preparing Strings, Mark Keywords, Triggering, Sources
+@section Preparing Translatable Strings
-@item .
-@efindex .@r{, PO Mode command}
-Redisplay the current entry (@code{po-current-entry}).
+@cindex marking strings, preparations
+Before strings can be marked for translations, they sometimes need to
+be adjusted. Usually preparing a string for translation is done right
+before marking it, during the marking phase which is described in the
+next sections. What you have to keep in mind while doing that is the
+following.
-@item n
-@efindex n@r{, PO Mode command}
-Select the entry after the current one (@code{po-next-entry}).
+@itemize @bullet
+@item
+Decent English style.
-@item p
-@efindex p@r{, PO Mode command}
-Select the entry before the current one (@code{po-previous-entry}).
+@item
+Entire sentences.
-@item <
-@efindex <@r{, PO Mode command}
-Select the first entry in the PO file (@code{po-first-entry}).
+@item
+Split at paragraphs.
-@item >
-@efindex >@r{, PO Mode command}
-Select the last entry in the PO file (@code{po-last-entry}).
+@item
+Use format strings instead of string concatenation.
+@end itemize
-@item m
-@efindex m@r{, PO Mode command}
-Record the location of the current entry for later use
-(@code{po-push-location}).
+@noindent
+Let's look at some examples of these guidelines.
-@item r
-@efindex r@r{, PO Mode command}
-Return to a previously saved entry location (@code{po-pop-location}).
+@cindex style
+Translatable strings should be in good English style. If slang language
+with abbreviations and shortcuts is used, often translators will not
+understand the message and will produce very inappropriate translations.
-@item x
-@efindex x@r{, PO Mode command}
-Exchange the current entry location with the previously saved one
-(@code{po-exchange-location}).
+@example
+"%s: is parameter\n"
+@end example
-@end table
+@noindent
+This is nearly untranslatable: Is the displayed item @emph{a} parameter or
+@emph{the} parameter?
-@efindex .@r{, PO Mode command}
-@efindex po-current-entry@r{, PO Mode command}
-Any Emacs command able to reposition the cursor may be used
-to select the current entry in PO mode, including commands which
-move by characters, lines, paragraphs, screens or pages, and search
-commands. However, there is a kind of standard way to display the
-current entry in PO mode, which usual Emacs commands moving
-the cursor do not especially try to enforce. The command @kbd{.}
-(@code{po-current-entry}) has the sole purpose of redisplaying the
-current entry properly, after the current entry has been changed by
-means external to PO mode, or the Emacs screen otherwise altered.
+@example
+"No match"
+@end example
-It is yet to be decided if PO mode helps the translator, or otherwise
-irritates her, by forcing a rigid window disposition while she
-is doing her work. We originally had quite precise ideas about
-how windows should behave, but on the other hand, anyone used to
-Emacs is often happy to keep full control. Maybe a fixed window
-disposition might be offered as a PO mode option that the translator
-might activate or deactivate at will, so it could be offered on an
-experimental basis. If nobody feels a real need for using it, or
-a compulsion for writing it, we should drop this whole idea.
-The incentive for doing it should come from translators rather than
-programmers, as opinions from an experienced translator are surely
-more worth to me than opinions from programmers @emph{thinking} about
-how @emph{others} should do translation.
+@noindent
+The ambiguity in this message makes it ununderstandable: Is the program
+attempting to set something on fire? Does it mean "The given object does
+not match the template"? Does it mean "The template does not fit for any
+of the objects"?
-@efindex n@r{, PO Mode command}
-@efindex po-next-entry@r{, PO Mode command}
-@efindex p@r{, PO Mode command}
-@efindex po-previous-entry@r{, PO Mode command}
-The commands @kbd{n} (@code{po-next-entry}) and @kbd{p}
-(@code{po-previous-entry}) move the cursor the entry following,
-or preceding, the current one. If @kbd{n} is given while the
-cursor is on the last entry of the PO file, or if @kbd{p}
-is given while the cursor is on the first entry, no move is done.
+@cindex ambiguities
+In both cases, adding more words to the message will help both the
+translator and the English speaking user.
-@efindex <@r{, PO Mode command}
-@efindex po-first-entry@r{, PO Mode command}
-@efindex >@r{, PO Mode command}
-@efindex po-last-entry@r{, PO Mode command}
-The commands @kbd{<} (@code{po-first-entry}) and @kbd{>}
-(@code{po-last-entry}) move the cursor to the first entry, or last
-entry, of the PO file. When the cursor is located past the last
-entry in a PO file, most PO mode commands will return an error saying
-@samp{After last entry}. Moreover, the commands @kbd{<} and @kbd{>}
-have the special property of being able to work even when the cursor
-is not into some PO file entry, and one may use them for nicely
-correcting this situation. But even these commands will fail on a
-truly empty PO file. There are development plans for the PO mode for it
-to interactively fill an empty PO file from sources. @xref{Marking}.
+@cindex sentences
+Translatable strings should be entire sentences. It is often not possible
+to translate single verbs or adjectives in a substitutable way.
-The translator may decide, before working at the translation of
-a particular entry, that she needs to browse the remainder of the
-PO file, maybe for finding the terminology or phraseology used
-in related entries. She can of course use the standard Emacs idioms
-for saving the current cursor location in some register, and use that
-register for getting back, or else, use the location ring.
+@example
+printf ("File %s is %s protected", filename, rw ? "write" : "read");
+@end example
-@efindex m@r{, PO Mode command}
-@efindex po-push-location@r{, PO Mode command}
-@efindex r@r{, PO Mode command}
-@efindex po-pop-location@r{, PO Mode command}
-PO mode offers another approach, by which cursor locations may be saved
-onto a special stack. The command @kbd{m} (@code{po-push-location})
-merely adds the location of current entry to the stack, pushing
-the already saved locations under the new one. The command
-@kbd{r} (@code{po-pop-location}) consumes the top stack element and
-repositions the cursor to the entry associated with that top element.
-This position is then lost, for the next @kbd{r} will move the cursor
-to the previously saved location, and so on until no locations remain
-on the stack.
+@noindent
+Most translators will not look at the source and will thus only see the
+string @code{"File %s is %s protected"}, which is unintelligible. Change
+this to
-If the translator wants the position to be kept on the location stack,
-maybe for taking a look at the entry associated with the top
-element, then go elsewhere with the intent of getting back later, she
-ought to use @kbd{m} immediately after @kbd{r}.
+@example
+printf (rw ? "File %s is write protected" : "File %s is read protected",
+ filename);
+@end example
-@efindex x@r{, PO Mode command}
-@efindex po-exchange-location@r{, PO Mode command}
-The command @kbd{x} (@code{po-exchange-location}) simultaneously
-repositions the cursor to the entry associated with the top element of
-the stack of saved locations, and replaces that top element with the
-location of the current entry before the move. Consequently, repeating
-the @kbd{x} command toggles alternatively between two entries.
-For achieving this, the translator will position the cursor on the
-first entry, use @kbd{m}, then position to the second entry, and
-merely use @kbd{x} for making the switch.
+@noindent
+This way the translator will not only understand the message, she will
+also be able to find the appropriate grammatical construction. The French
+translator for example translates "write protected" like "protected
+against writing".
-@node Normalizing, , Entry Positioning, Basics
-@section Normalizing Strings in Entries
-@cindex string normalization in entries
+Entire sentences are also important because in many languages, the
+declination of some word in a sentence depends on the gender or the
+number (singular/plural) of another part of the sentence. There are
+usually more interdependencies between words than in English. The
+consequence is that asking a translator to translate two half-sentences
+and then combining these two half-sentences through dumb string concatenation
+will not work, for many languages, even though it would work for English.
+That's why translators need to handle entire sentences.
-There are many different ways for encoding a particular string into a
-PO file entry, because there are so many different ways to split and
-quote multi-line strings, and even, to represent special characters
-by backslashed escaped sequences. Some features of PO mode rely on
-the ability for PO mode to scan an already existing PO file for a
-particular string encoded into the @code{msgid} field of some entry.
-Even if PO mode has internally all the built-in machinery for
-implementing this recognition easily, doing it fast is technically
-difficult. To facilitate a solution to this efficiency problem,
-we decided on a canonical representation for strings.
+Often sentences don't fit into a single line. If a sentence is output
+using two subsequent @code{printf} statements, like this
-A conventional representation of strings in a PO file is currently
-under discussion, and PO mode experiments with a canonical representation.
-Having both @code{xgettext} and PO mode converging towards a uniform
-way of representing equivalent strings would be useful, as the internal
-normalization needed by PO mode could be automatically satisfied
-when using @code{xgettext} from GNU @code{gettext}. An explicit
-PO mode normalization should then be only necessary for PO files
-imported from elsewhere, or for when the convention itself evolves.
+@example
+printf ("Locale charset \"%s\" is different from\n", lcharset);
+printf ("input file charset \"%s\".\n", fcharset);
+@end example
-So, for achieving normalization of at least the strings of a given
-PO file needing a canonical representation, the following PO mode
-command is available:
+@noindent
+the translator would have to translate two half sentences, but nothing
+in the POT file would tell her that the two half sentences belong together.
+It is necessary to merge the two @code{printf} statements so that the
+translator can handle the entire sentence at once and decide at which
+place to insert a line break in the translation (if at all):
-@emindex string normalization in entries
-@table @kbd
-@item M-x po-normalize
-@efindex po-normalize@r{, PO Mode command}
-Tidy the whole PO file by making entries more uniform.
+@example
+printf ("Locale charset \"%s\" is different from\n\
+input file charset \"%s\".\n", lcharset, fcharset);
+@end example
-@end table
+You may now ask: how about two or more adjacent sentences? Like in this case:
-The special command @kbd{M-x po-normalize}, which has no associated
-keys, revises all entries, ensuring that strings of both original
-and translated entries use uniform internal quoting in the PO file.
-It also removes any crumb after the last entry. This command may be
-useful for PO files freshly imported from elsewhere, or if we ever
-improve on the canonical quoting format we use. This canonical format
-is not only meant for getting cleaner PO files, but also for greatly
-speeding up @code{msgid} string lookup for some other PO mode commands.
+@example
+puts ("Apollo 13 scenario: Stack overflow handling failed.");
+puts ("On the next stack overflow we will crash!!!");
+@end example
-@kbd{M-x po-normalize} presently makes three passes over the entries.
-The first implements heuristics for converting PO files for GNU
-@code{gettext} 0.6 and earlier, in which @code{msgid} and @code{msgstr}
-fields were using K&R style C string syntax for multi-line strings.
-These heuristics may fail for comments not related to obsolete
-entries and ending with a backslash; they also depend on subsequent
-passes for finalizing the proper commenting of continued lines for
-obsolete entries. This first pass might disappear once all oldish PO
-files would have been adjusted. The second and third pass normalize
-all @code{msgid} and @code{msgstr} strings respectively. They also
-clean out those trailing backslashes used by XView's @code{msgfmt}
-for continued lines.
+@noindent
+Should these two statements merged into a single one? I would recommend to
+merge them if the two sentences are related to each other, because then it
+makes it easier for the translator to understand and translate both. On
+the other hand, if one of the two messages is a stereotypic one, occurring
+in other places as well, you will do a favour to the translator by not
+merging the two. (Identical messages occurring in several places are
+combined by xgettext, so the translator has to handle them once only.)
-@cindex importing PO files
-Having such an explicit normalizing command allows for importing PO
-files from other sources, but also eases the evolution of the current
-convention, evolution driven mostly by aesthetic concerns, as of now.
-It is easy to make suggested adjustments at a later time, as the
-normalizing command and eventually, other GNU @code{gettext} tools
-should greatly automate conformance. A description of the canonical
-string format is given below, for the particular benefit of those not
-having Emacs handy, and who would nevertheless want to handcraft
-their PO files in nice ways.
+@cindex paragraphs
+Translatable strings should be limited to one paragraph; don't let a
+single message be longer than ten lines. The reason is that when the
+translatable string changes, the translator is faced with the task of
+updating the entire translated string. Maybe only a single word will
+have changed in the English string, but the translator doesn't see that
+(with the current translation tools), therefore she has to proofread
+the entire message.
-@cindex multi-line strings
-Right now, in PO mode, strings are single line or multi-line. A string
-goes multi-line if and only if it has @emph{embedded} newlines, that
-is, if it matches @samp{[^\n]\n+[^\n]}. So, we would have:
+@cindex help option
+Many GNU programs have a @samp{--help} output that extends over several
+screen pages. It is a courtesy towards the translators to split such a
+message into several ones of five to ten lines each. While doing that,
+you can also attempt to split the documented options into groups,
+such as the input options, the output options, and the informative
+output options. This will help every user to find the option he is
+looking for.
+
+@cindex string concatenation
+@cindex concatenation of strings
+Hardcoded string concatenation is sometimes used to construct English
+strings:
@example
-msgstr "\n\nHello, world!\n\n\n"
+strcpy (s, "Replace ");
+strcat (s, object1);
+strcat (s, " with ");
+strcat (s, object2);
+strcat (s, "?");
@end example
-but, replacing the space by a newline, this becomes:
+@noindent
+In order to present to the translator only entire sentences, and also
+because in some languages the translator might want to swap the order
+of @code{object1} and @code{object2}, it is necessary to change this
+to use a format string:
@example
-msgstr ""
-"\n"
-"\n"
-"Hello,\n"
-"world!\n"
-"\n"
-"\n"
+sprintf (s, "Replace %s with %s?", object1, object2);
@end example
-We are deliberately using a caricatural example, here, to make the
-point clearer. Usually, multi-lines are not that bad looking.
-It is probable that we will implement the following suggestion.
-We might lump together all initial newlines into the empty string,
-and also all newlines introducing empty lines (that is, for @w{@var{n}
-> 1}, the @var{n}-1'th last newlines would go together on a separate
-string), so making the previous example appear:
+@cindex @code{inttypes.h}
+A similar case is compile time concatenation of strings. The ISO C 99
+include file @code{<inttypes.h>} contains a macro @code{PRId64} that
+can be used as a formatting directive for outputting an @samp{int64_t}
+integer through @code{printf}. It expands to a constant string, usually
+"d" or "ld" or "lld" or something like this, depending on the platform.
+Assume you have code like
@example
-msgstr "\n\n"
-"Hello,\n"
-"world!\n"
-"\n\n"
+printf ("The amount is %0" PRId64 "\n", number);
@end example
-There are a few yet undecided little points about string normalization,
-to be documented in this manual, once these questions settle.
-
-@node Sources, Template, Basics, Top
-@chapter Preparing Program Sources
-@cindex preparing programs for translation
+@noindent
+The @code{gettext} tools and library have special support for these
+@code{<inttypes.h>} macros. You can therefore simply write
-@c FIXME: Rewrite (the whole chapter).
+@example
+printf (gettext ("The amount is %0" PRId64 "\n"), number);
+@end example
-For the programmer, changes to the C source code fall into three
-categories. First, you have to make the localization functions
-known to all modules needing message translation. Second, you should
-properly trigger the operation of GNU @code{gettext} when the program
-initializes, usually from the @code{main} function. Last, you should
-identify and especially mark all constant strings in your program
-needing translation.
+@noindent
+The PO file will contain the string "The amount is %0<PRId64>\n".
+The translators will provide a translation containing "%0<PRId64>"
+as well, and at runtime the @code{gettext} function's result will
+contain the appropriate constant string, "d" or "ld" or "lld".
-Presuming that your set of programs, or package, has been adjusted
-so all needed GNU @code{gettext} files are available, and your
-@file{Makefile} files are adjusted (@pxref{Maintainers}), each C module
-having translated C strings should contain the line:
+This works only for the predefined @code{<inttypes.h>} macros. If
+you have defined your own similar macros, let's say @samp{MYPRId64},
+that are not known to @code{xgettext}, the solution for this problem
+is to change the code like this:
-@cindex include file @file{libintl.h}
@example
-#include <libintl.h>
+char buf1[100];
+sprintf (buf1, "%0" MYPRId64, number);
+printf (gettext ("The amount is %s\n"), buf1);
@end example
-Similarly, each C module containing @code{printf()}/@code{fprintf()}/...
-calls with a format string that could be a translated C string (even if
-the C string comes from a different C module) should contain the line:
+This means, you put the platform dependent code in one statement, and the
+internationalization code in a different statement. Note that a buffer length
+of 100 is safe, because all available hardware integer types are limited to
+128 bits, and to print a 128 bit integer one needs at most 54 characters,
+regardless whether in decimal, octal or hexadecimal.
+
+@cindex Java, string concatenation
+@cindex C#, string concatenation
+All this applies to other programming languages as well. For example, in
+Java and C#, string contenation is very frequently used, because it is a
+compiler built-in operator. Like in C, in Java, you would change
@example
-#include <libintl.h>
+System.out.println("Replace "+object1+" with "+object2+"?");
@end example
-The remaining changes to your C sources are discussed in the further
-sections of this chapter.
-
-@menu
-* Triggering:: Triggering @code{gettext} Operations
-* Preparing Strings:: Preparing Translatable Strings
-* Mark Keywords:: How Marks Appear in Sources
-* Marking:: Marking Translatable Strings
-* c-format Flag:: Telling something about the following string
-* Special cases:: Special Cases of Translatable Strings
-* Names:: Marking Proper Names for Translation
-* Libraries:: Preparing Library Sources
-@end menu
+@noindent
+into a statement involving a format string:
-@node Triggering, Preparing Strings, Sources, Sources
-@section Triggering @code{gettext} Operations
+@example
+System.out.println(
+ MessageFormat.format("Replace @{0@} with @{1@}?",
+ new Object[] @{ object1, object2 @}));
+@end example
-@cindex initialization
-The initialization of locale data should be done with more or less
-the same code in every program, as demonstrated below:
+@noindent
+Similarly, in C#, you would change
@example
-@group
-int
-main (int argc, char *argv[])
-@{
- @dots{}
- setlocale (LC_ALL, "");
- bindtextdomain (PACKAGE, LOCALEDIR);
- textdomain (PACKAGE);
- @dots{}
-@}
-@end group
+Console.WriteLine("Replace "+object1+" with "+object2+"?");
@end example
-@var{PACKAGE} and @var{LOCALEDIR} should be provided either by
-@file{config.h} or by the Makefile. For now consult the @code{gettext}
-or @code{hello} sources for more information.
+@noindent
+into a statement involving a format string:
-@cindex locale facet, LC_ALL
-@cindex locale facet, LC_CTYPE
-The use of @code{LC_ALL} might not be appropriate for you.
-@code{LC_ALL} includes all locale categories and especially
-@code{LC_CTYPE}. This later category is responsible for determining
-character classes with the @code{isalnum} etc. functions from
-@file{ctype.h} which could especially for programs, which process some
-kind of input language, be wrong. For example this would mean that a
-source code using the @,{c} (c-cedilla character) is runnable in
-France but not in the U.S.
+@example
+Console.WriteLine(
+ String.Format("Replace @{0@} with @{1@}?", object1, object2));
+@end example
-Some systems also have problems with parsing numbers using the
-@code{scanf} functions if an other but the @code{LC_ALL} locale is used.
-The standards say that additional formats but the one known in the
-@code{"C"} locale might be recognized. But some systems seem to reject
-numbers in the @code{"C"} locale format. In some situation, it might
-also be a problem with the notation itself which makes it impossible to
-recognize whether the number is in the @code{"C"} locale or the local
-format. This can happen if thousands separator characters are used.
-Some locales define this character according to the national
-conventions to @code{'.'} which is the same character used in the
-@code{"C"} locale to denote the decimal point.
-
-So it is sometimes necessary to replace the @code{LC_ALL} line in the
-code above by a sequence of @code{setlocale} lines
-
-@example
-@group
-@{
- @dots{}
- setlocale (LC_CTYPE, "");
- setlocale (LC_MESSAGES, "");
- @dots{}
-@}
-@end group
-@end example
-
-@cindex locale facet, LC_CTYPE
-@cindex locale facet, LC_COLLATE
-@cindex locale facet, LC_MONETARY
-@cindex locale facet, LC_NUMERIC
-@cindex locale facet, LC_TIME
-@cindex locale facet, LC_MESSAGES
-@cindex locale facet, LC_RESPONSES
-@noindent
-On all POSIX conformant systems the locale categories @code{LC_CTYPE},
-@code{LC_MESSAGES}, @code{LC_COLLATE}, @code{LC_MONETARY},
-@code{LC_NUMERIC}, and @code{LC_TIME} are available. On some systems
-which are only ISO C compliant, @code{LC_MESSAGES} is missing, but
-a substitute for it is defined in GNU gettext's @code{<libintl.h>}.
-
-Note that changing the @code{LC_CTYPE} also affects the functions
-declared in the @code{<ctype.h>} standard header. If this is not
-desirable in your application (for example in a compiler's parser),
-you can use a set of substitute functions which hardwire the C locale,
-such as found in the @code{<c-ctype.h>} and @code{<c-ctype.c>} files
-in the gettext source distribution.
-
-It is also possible to switch the locale forth and back between the
-environment dependent locale and the C locale, but this approach is
-normally avoided because a @code{setlocale} call is expensive,
-because it is tedious to determine the places where a locale switch
-is needed in a large program's source, and because switching a locale
-is not multithread-safe.
-
-@node Preparing Strings, Mark Keywords, Triggering, Sources
-@section Preparing Translatable Strings
-
-@cindex marking strings, preparations
-Before strings can be marked for translations, they sometimes need to
-be adjusted. Usually preparing a string for translation is done right
-before marking it, during the marking phase which is described in the
-next sections. What you have to keep in mind while doing that is the
-following.
-
-@itemize @bullet
-@item
-Decent English style.
+@node Mark Keywords, Marking, Preparing Strings, Sources
+@section How Marks Appear in Sources
+@cindex marking strings that require translation
-@item
-Entire sentences.
+All strings requiring translation should be marked in the C sources. Marking
+is done in such a way that each translatable string appears to be
+the sole argument of some function or preprocessor macro. There are
+only a few such possible functions or macros meant for translation,
+and their names are said to be marking keywords. The marking is
+attached to strings themselves, rather than to what we do with them.
+This approach has more uses. A blatant example is an error message
+produced by formatting. The format string needs translation, as
+well as some strings inserted through some @samp{%s} specification
+in the format, while the result from @code{sprintf} may have so many
+different instances that it is impractical to list them all in some
+@samp{error_string_out()} routine, say.
-@item
-Split at paragraphs.
+This marking operation has two goals. The first goal of marking
+is for triggering the retrieval of the translation, at run time.
+The keyword are possibly resolved into a routine able to dynamically
+return the proper translation, as far as possible or wanted, for the
+argument string. Most localizable strings are found in executable
+positions, that is, attached to variables or given as parameters to
+functions. But this is not universal usage, and some translatable
+strings appear in structured initializations. @xref{Special cases}.
-@item
-Use format strings instead of string concatenation.
-@end itemize
+The second goal of the marking operation is to help @code{xgettext}
+at properly extracting all translatable strings when it scans a set
+of program sources and produces PO file templates.
-@noindent
-Let's look at some examples of these guidelines.
+The canonical keyword for marking translatable strings is
+@samp{gettext}, it gave its name to the whole GNU @code{gettext}
+package. For packages making only light use of the @samp{gettext}
+keyword, macro or function, it is easily used @emph{as is}. However,
+for packages using the @code{gettext} interface more heavily, it
+is usually more convenient to give the main keyword a shorter, less
+obtrusive name. Indeed, the keyword might appear on a lot of strings
+all over the package, and programmers usually do not want nor need
+their program sources to remind them forcefully, all the time, that they
+are internationalized. Further, a long keyword has the disadvantage
+of using more horizontal space, forcing more indentation work on
+sources for those trying to keep them within 79 or 80 columns.
-@cindex style
-Translatable strings should be in good English style. If slang language
-with abbreviations and shortcuts is used, often translators will not
-understand the message and will produce very inappropriate translations.
+@cindex @code{_}, a macro to mark strings for translation
+Many packages use @samp{_} (a simple underline) as a keyword,
+and write @samp{_("Translatable string")} instead of @samp{gettext
+("Translatable string")}. Further, the coding rule, from GNU standards,
+wanting that there is a space between the keyword and the opening
+parenthesis is relaxed, in practice, for this particular usage.
+So, the textual overhead per translatable string is reduced to
+only three characters: the underline and the two parentheses.
+However, even if GNU @code{gettext} uses this convention internally,
+it does not offer it officially. The real, genuine keyword is truly
+@samp{gettext} indeed. It is fairly easy for those wanting to use
+@samp{_} instead of @samp{gettext} to declare:
@example
-"%s: is parameter\n"
+#include <libintl.h>
+#define _(String) gettext (String)
@end example
@noindent
-This is nearly untranslatable: Is the displayed item @emph{a} parameter or
-@emph{the} parameter?
+instead of merely using @samp{#include <libintl.h>}.
-@example
-"No match"
-@end example
+Later on, the maintenance is relatively easy. If, as a programmer,
+you add or modify a string, you will have to ask yourself if the
+new or altered string requires translation, and include it within
+@samp{_()} if you think it should be translated. @samp{"%s: %d"} is
+an example of string @emph{not} requiring translation!
-@noindent
-The ambiguity in this message makes it ununderstandable: Is the program
-attempting to set something on fire? Does it mean "The given object does
-not match the template"? Does it mean "The template does not fit for any
-of the objects"?
+@node Marking, c-format Flag, Mark Keywords, Sources
+@section Marking Translatable Strings
+@emindex marking strings for translation
-@cindex ambiguities
-In both cases, adding more words to the message will help both the
-translator and the English speaking user.
+In PO mode, one set of features is meant more for the programmer than
+for the translator, and allows him to interactively mark which strings,
+in a set of program sources, are translatable, and which are not.
+Even if it is a fairly easy job for a programmer to find and mark
+such strings by other means, using any editor of his choice, PO mode
+makes this work more comfortable. Further, this gives translators
+who feel a little like programmers, or programmers who feel a little
+like translators, a tool letting them work at marking translatable
+strings in the program sources, while simultaneously producing a set of
+translation in some language, for the package being internationalized.
-@cindex sentences
-Translatable strings should be entire sentences. It is often not possible
-to translate single verbs or adjectives in a substitutable way.
+@emindex @code{etags}, using for marking strings
+The set of program sources, targetted by the PO mode commands describe
+here, should have an Emacs tags table constructed for your project,
+prior to using these PO file commands. This is easy to do. In any
+shell window, change the directory to the root of your project, then
+execute a command resembling:
@example
-printf ("File %s is %s protected", filename, rw ? "write" : "read");
+etags src/*.[hc] lib/*.[hc]
@end example
@noindent
-Most translators will not look at the source and will thus only see the
-string @code{"File %s is %s protected"}, which is unintelligible. Change
-this to
-
-@example
-printf (rw ? "File %s is write protected" : "File %s is read protected",
- filename);
-@end example
+presuming here you want to process all @file{.h} and @file{.c} files
+from the @file{src/} and @file{lib/} directories. This command will
+explore all said files and create a @file{TAGS} file in your root
+directory, somewhat summarizing the contents using a special file
+format Emacs can understand.
-@noindent
-This way the translator will not only understand the message, she will
-also be able to find the appropriate grammatical construction. The French
-translator for example translates "write protected" like "protected
-against writing".
+@emindex @file{TAGS}, and marking translatable strings
+For packages following the GNU coding standards, there is
+a make goal @code{tags} or @code{TAGS} which constructs the tag files in
+all directories and for all files containing source code.
-Entire sentences are also important because in many languages, the
-declination of some word in a sentence depends on the gender or the
-number (singular/plural) of another part of the sentence. There are
-usually more interdependencies between words than in English. The
-consequence is that asking a translator to translate two half-sentences
-and then combining these two half-sentences through dumb string concatenation
-will not work, for many languages, even though it would work for English.
-That's why translators need to handle entire sentences.
+Once your @file{TAGS} file is ready, the following commands assist
+the programmer at marking translatable strings in his set of sources.
+But these commands are necessarily driven from within a PO file
+window, and it is likely that you do not even have such a PO file yet.
+This is not a problem at all, as you may safely open a new, empty PO
+file, mainly for using these commands. This empty PO file will slowly
+fill in while you mark strings as translatable in your program sources.
-Often sentences don't fit into a single line. If a sentence is output
-using two subsequent @code{printf} statements, like this
+@table @kbd
+@item ,
+@efindex ,@r{, PO Mode command}
+Search through program sources for a string which looks like a
+candidate for translation (@code{po-tags-search}).
-@example
-printf ("Locale charset \"%s\" is different from\n", lcharset);
-printf ("input file charset \"%s\".\n", fcharset);
-@end example
+@item M-,
+@efindex M-,@r{, PO Mode command}
+Mark the last string found with @samp{_()} (@code{po-mark-translatable}).
-@noindent
-the translator would have to translate two half sentences, but nothing
-in the POT file would tell her that the two half sentences belong together.
-It is necessary to merge the two @code{printf} statements so that the
-translator can handle the entire sentence at once and decide at which
-place to insert a line break in the translation (if at all):
+@item M-.
+@efindex M-.@r{, PO Mode command}
+Mark the last string found with a keyword taken from a set of possible
+keywords. This command with a prefix allows some management of these
+keywords (@code{po-select-mark-and-mark}).
-@example
-printf ("Locale charset \"%s\" is different from\n\
-input file charset \"%s\".\n", lcharset, fcharset);
-@end example
+@end table
-You may now ask: how about two or more adjacent sentences? Like in this case:
+@efindex po-tags-search@r{, PO Mode command}
+The @kbd{,} (@code{po-tags-search}) command searches for the next
+occurrence of a string which looks like a possible candidate for
+translation, and displays the program source in another Emacs window,
+positioned in such a way that the string is near the top of this other
+window. If the string is too big to fit whole in this window, it is
+positioned so only its end is shown. In any case, the cursor
+is left in the PO file window. If the shown string would be better
+presented differently in different native languages, you may mark it
+using @kbd{M-,} or @kbd{M-.}. Otherwise, you might rather ignore it
+and skip to the next string by merely repeating the @kbd{,} command.
-@example
-puts ("Apollo 13 scenario: Stack overflow handling failed.");
-puts ("On the next stack overflow we will crash!!!");
-@end example
+A string is a good candidate for translation if it contains a sequence
+of three or more letters. A string containing at most two letters in
+a row will be considered as a candidate if it has more letters than
+non-letters. The command disregards strings containing no letters,
+or isolated letters only. It also disregards strings within comments,
+or strings already marked with some keyword PO mode knows (see below).
-@noindent
-Should these two statements merged into a single one? I would recommend to
-merge them if the two sentences are related to each other, because then it
-makes it easier for the translator to understand and translate both. On
-the other hand, if one of the two messages is a stereotypic one, occurring
-in other places as well, you will do a favour to the translator by not
-merging the two. (Identical messages occurring in several places are
-combined by xgettext, so the translator has to handle them once only.)
+If you have never told Emacs about some @file{TAGS} file to use, the
+command will request that you specify one from the minibuffer, the
+first time you use the command. You may later change your @file{TAGS}
+file by using the regular Emacs command @w{@kbd{M-x visit-tags-table}},
+which will ask you to name the precise @file{TAGS} file you want
+to use. @xref{Tags, , Tag Tables, emacs, The Emacs Editor}.
-@cindex paragraphs
-Translatable strings should be limited to one paragraph; don't let a
-single message be longer than ten lines. The reason is that when the
-translatable string changes, the translator is faced with the task of
-updating the entire translated string. Maybe only a single word will
-have changed in the English string, but the translator doesn't see that
-(with the current translation tools), therefore she has to proofread
-the entire message.
+Each time you use the @kbd{,} command, the search resumes from where it was
+left by the previous search, and goes through all program sources,
+obeying the @file{TAGS} file, until all sources have been processed.
+However, by giving a prefix argument to the command @w{(@kbd{C-u
+,})}, you may request that the search be restarted all over again
+from the first program source; but in this case, strings that you
+recently marked as translatable will be automatically skipped.
-@cindex help option
-Many GNU programs have a @samp{--help} output that extends over several
-screen pages. It is a courtesy towards the translators to split such a
-message into several ones of five to ten lines each. While doing that,
-you can also attempt to split the documented options into groups,
-such as the input options, the output options, and the informative
-output options. This will help every user to find the option he is
-looking for.
+Using this @kbd{,} command does not prevent using of other regular
+Emacs tags commands. For example, regular @code{tags-search} or
+@code{tags-query-replace} commands may be used without disrupting the
+independent @kbd{,} search sequence. However, as implemented, the
+@emph{initial} @kbd{,} command (or the @kbd{,} command is used with a
+prefix) might also reinitialize the regular Emacs tags searching to the
+first tags file, this reinitialization might be considered spurious.
-@cindex string concatenation
-@cindex concatenation of strings
-Hardcoded string concatenation is sometimes used to construct English
-strings:
+@efindex po-mark-translatable@r{, PO Mode command}
+@efindex po-select-mark-and-mark@r{, PO Mode command}
+The @kbd{M-,} (@code{po-mark-translatable}) command will mark the
+recently found string with the @samp{_} keyword. The @kbd{M-.}
+(@code{po-select-mark-and-mark}) command will request that you type
+one keyword from the minibuffer and use that keyword for marking
+the string. Both commands will automatically create a new PO file
+untranslated entry for the string being marked, and make it the
+current entry (making it easy for you to immediately proceed to its
+translation, if you feel like doing it right away). It is possible
+that the modifications made to the program source by @kbd{M-,} or
+@kbd{M-.} render some source line longer than 80 columns, forcing you
+to break and re-indent this line differently. You may use the @kbd{O}
+command from PO mode, or any other window changing command from
+Emacs, to break out into the program source window, and do any
+needed adjustments. You will have to use some regular Emacs command
+to return the cursor to the PO file window, if you want command
+@kbd{,} for the next string, say.
-@example
-strcpy (s, "Replace ");
-strcat (s, object1);
-strcat (s, " with ");
-strcat (s, object2);
-strcat (s, "?");
-@end example
+The @kbd{M-.} command has a few built-in speedups, so you do not
+have to explicitly type all keywords all the time. The first such
+speedup is that you are presented with a @emph{preferred} keyword,
+which you may accept by merely typing @kbd{@key{RET}} at the prompt.
+The second speedup is that you may type any non-ambiguous prefix of the
+keyword you really mean, and the command will complete it automatically
+for you. This also means that PO mode has to @emph{know} all
+your possible keywords, and that it will not accept mistyped keywords.
-@noindent
-In order to present to the translator only entire sentences, and also
-because in some languages the translator might want to swap the order
-of @code{object1} and @code{object2}, it is necessary to change this
-to use a format string:
+If you reply @kbd{?} to the keyword request, the command gives a
+list of all known keywords, from which you may choose. When the
+command is prefixed by an argument @w{(@kbd{C-u M-.})}, it inhibits
+updating any program source or PO file buffer, and does some simple
+keyword management instead. In this case, the command asks for a
+keyword, written in full, which becomes a new allowed keyword for
+later @kbd{M-.} commands. Moreover, this new keyword automatically
+becomes the @emph{preferred} keyword for later commands. By typing
+an already known keyword in response to @w{@kbd{C-u M-.}}, one merely
+changes the @emph{preferred} keyword and does nothing more.
-@example
-sprintf (s, "Replace %s with %s?", object1, object2);
-@end example
+All keywords known for @kbd{M-.} are recognized by the @kbd{,} command
+when scanning for strings, and strings already marked by any of those
+known keywords are automatically skipped. If many PO files are opened
+simultaneously, each one has its own independent set of known keywords.
+There is no provision in PO mode, currently, for deleting a known
+keyword, you have to quit the file (maybe using @kbd{q}) and reopen
+it afresh. When a PO file is newly brought up in an Emacs window, only
+@samp{gettext} and @samp{_} are known as keywords, and @samp{gettext}
+is preferred for the @kbd{M-.} command. In fact, this is not useful to
+prefer @samp{_}, as this one is already built in the @kbd{M-,} command.
-@cindex @code{inttypes.h}
-A similar case is compile time concatenation of strings. The ISO C 99
-include file @code{<inttypes.h>} contains a macro @code{PRId64} that
-can be used as a formatting directive for outputting an @samp{int64_t}
-integer through @code{printf}. It expands to a constant string, usually
-"d" or "ld" or "lld" or something like this, depending on the platform.
-Assume you have code like
+@node c-format Flag, Special cases, Marking, Sources
+@section Special Comments preceding Keywords
-@example
-printf ("The amount is %0" PRId64 "\n", number);
-@end example
+@c FIXME document c-format and no-c-format.
-@noindent
-The @code{gettext} tools and library have special support for these
-@code{<inttypes.h>} macros. You can therefore simply write
+@cindex format strings
+In C programs strings are often used within calls of functions from the
+@code{printf} family. The special thing about these format strings is
+that they can contain format specifiers introduced with @kbd{%}. Assume
+we have the code
@example
-printf (gettext ("The amount is %0" PRId64 "\n"), number);
+printf (gettext ("String `%s' has %d characters\n"), s, strlen (s));
@end example
@noindent
-The PO file will contain the string "The amount is %0<PRId64>\n".
-The translators will provide a translation containing "%0<PRId64>"
-as well, and at runtime the @code{gettext} function's result will
-contain the appropriate constant string, "d" or "ld" or "lld".
-
-This works only for the predefined @code{<inttypes.h>} macros. If
-you have defined your own similar macros, let's say @samp{MYPRId64},
-that are not known to @code{xgettext}, the solution for this problem
-is to change the code like this:
+A possible German translation for the above string might be:
@example
-char buf1[100];
-sprintf (buf1, "%0" MYPRId64, number);
-printf (gettext ("The amount is %s\n"), buf1);
+"%d Zeichen lang ist die Zeichenkette `%s'"
@end example
-This means, you put the platform dependent code in one statement, and the
-internationalization code in a different statement. Note that a buffer length
-of 100 is safe, because all available hardware integer types are limited to
-128 bits, and to print a 128 bit integer one needs at most 54 characters,
-regardless whether in decimal, octal or hexadecimal.
-
-@cindex Java, string concatenation
-@cindex C#, string concatenation
-All this applies to other programming languages as well. For example, in
-Java and C#, string contenation is very frequently used, because it is a
-compiler built-in operator. Like in C, in Java, you would change
+A C programmer, even if he cannot speak German, will recognize that
+there is something wrong here. The order of the two format specifiers
+is changed but of course the arguments in the @code{printf} don't have.
+This will most probably lead to problems because now the length of the
+string is regarded as the address.
-@example
-System.out.println("Replace "+object1+" with "+object2+"?");
-@end example
+To prevent errors at runtime caused by translations the @code{msgfmt}
+tool can check statically whether the arguments in the original and the
+translation string match in type and number. If this is not the case
+and the @samp{-c} option has been passed to @code{msgfmt}, @code{msgfmt}
+will give an error and refuse to produce a MO file. Thus consequent
+use of @samp{msgfmt -c} will catch the error, so that it cannot cause
+cause problems at runtime.
@noindent
-into a statement involving a format string:
+If the word order in the above German translation would be correct one
+would have to write
@example
-System.out.println(
- MessageFormat.format("Replace @{0@} with @{1@}?",
- new Object[] @{ object1, object2 @}));
+"%2$d Zeichen lang ist die Zeichenkette `%1$s'"
@end example
@noindent
-Similarly, in C#, you would change
-
-@example
-Console.WriteLine("Replace "+object1+" with "+object2+"?");
-@end example
+The routines in @code{msgfmt} know about this special notation.
-@noindent
-into a statement involving a format string:
+Because not all strings in a program must be format strings it is not
+useful for @code{msgfmt} to test all the strings in the @file{.po} file.
+This might cause problems because the string might contain what looks
+like a format specifier, but the string is not used in @code{printf}.
-@example
-Console.WriteLine(
- String.Format("Replace @{0@} with @{1@}?", object1, object2));
-@end example
+Therefore the @code{xgettext} adds a special tag to those messages it
+thinks might be a format string. There is no absolute rule for this,
+only a heuristic. In the @file{.po} file the entry is marked using the
+@code{c-format} flag in the @code{#,} comment line (@pxref{PO Files}).
-@node Mark Keywords, Marking, Preparing Strings, Sources
-@section How Marks Appear in Sources
-@cindex marking strings that require translation
+@kwindex c-format@r{, and @code{xgettext}}
+@kwindex no-c-format@r{, and @code{xgettext}}
+The careful reader now might say that this again can cause problems.
+The heuristic might guess it wrong. This is true and therefore
+@code{xgettext} knows about a special kind of comment which lets
+the programmer take over the decision. If in the same line as or
+the immediately preceding line to the @code{gettext} keyword
+the @code{xgettext} program finds a comment containing the words
+@code{xgettext:c-format}, it will mark the string in any case with
+the @code{c-format} flag. This kind of comment should be used when
+@code{xgettext} does not recognize the string as a format string but
+it really is one and it should be tested. Please note that when the
+comment is in the same line as the @code{gettext} keyword, it must be
+before the string to be translated.
-All strings requiring translation should be marked in the C sources. Marking
-is done in such a way that each translatable string appears to be
-the sole argument of some function or preprocessor macro. There are
-only a few such possible functions or macros meant for translation,
-and their names are said to be marking keywords. The marking is
-attached to strings themselves, rather than to what we do with them.
-This approach has more uses. A blatant example is an error message
-produced by formatting. The format string needs translation, as
-well as some strings inserted through some @samp{%s} specification
-in the format, while the result from @code{sprintf} may have so many
-different instances that it is impractical to list them all in some
-@samp{error_string_out()} routine, say.
+This situation happens quite often. The @code{printf} function is often
+called with strings which do not contain a format specifier. Of course
+one would normally use @code{fputs} but it does happen. In this case
+@code{xgettext} does not recognize this as a format string but what
+happens if the translation introduces a valid format specifier? The
+@code{printf} function will try to access one of the parameters but none
+exists because the original code does not pass any parameters.
-This marking operation has two goals. The first goal of marking
-is for triggering the retrieval of the translation, at run time.
-The keyword are possibly resolved into a routine able to dynamically
-return the proper translation, as far as possible or wanted, for the
-argument string. Most localizable strings are found in executable
-positions, that is, attached to variables or given as parameters to
-functions. But this is not universal usage, and some translatable
-strings appear in structured initializations. @xref{Special cases}.
+@code{xgettext} of course could make a wrong decision the other way
+round, i.e. a string marked as a format string actually is not a format
+string. In this case the @code{msgfmt} might give too many warnings and
+would prevent translating the @file{.po} file. The method to prevent
+this wrong decision is similar to the one used above, only the comment
+to use must contain the string @code{xgettext:no-c-format}.
-The second goal of the marking operation is to help @code{xgettext}
-at properly extracting all translatable strings when it scans a set
-of program sources and produces PO file templates.
+If a string is marked with @code{c-format} and this is not correct the
+user can find out who is responsible for the decision. See
+@ref{xgettext Invocation} to see how the @code{--debug} option can be
+used for solving this problem.
-The canonical keyword for marking translatable strings is
-@samp{gettext}, it gave its name to the whole GNU @code{gettext}
-package. For packages making only light use of the @samp{gettext}
-keyword, macro or function, it is easily used @emph{as is}. However,
-for packages using the @code{gettext} interface more heavily, it
-is usually more convenient to give the main keyword a shorter, less
-obtrusive name. Indeed, the keyword might appear on a lot of strings
-all over the package, and programmers usually do not want nor need
-their program sources to remind them forcefully, all the time, that they
-are internationalized. Further, a long keyword has the disadvantage
-of using more horizontal space, forcing more indentation work on
-sources for those trying to keep them within 79 or 80 columns.
+@node Special cases, Names, c-format Flag, Sources
+@section Special Cases of Translatable Strings
-@cindex @code{_}, a macro to mark strings for translation
-Many packages use @samp{_} (a simple underline) as a keyword,
-and write @samp{_("Translatable string")} instead of @samp{gettext
-("Translatable string")}. Further, the coding rule, from GNU standards,
-wanting that there is a space between the keyword and the opening
-parenthesis is relaxed, in practice, for this particular usage.
-So, the textual overhead per translatable string is reduced to
-only three characters: the underline and the two parentheses.
-However, even if GNU @code{gettext} uses this convention internally,
-it does not offer it officially. The real, genuine keyword is truly
-@samp{gettext} indeed. It is fairly easy for those wanting to use
-@samp{_} instead of @samp{gettext} to declare:
+@cindex marking string initializers
+The attentive reader might now point out that it is not always possible
+to mark translatable string with @code{gettext} or something like this.
+Consider the following case:
@example
-#include <libintl.h>
-#define _(String) gettext (String)
+@group
+@{
+ static const char *messages[] = @{
+ "some very meaningful message",
+ "and another one"
+ @};
+ const char *string;
+ @dots{}
+ string
+ = index > 1 ? "a default message" : messages[index];
+
+ fputs (string);
+ @dots{}
+@}
+@end group
@end example
-@noindent
-instead of merely using @samp{#include <libintl.h>}.
+While it is no problem to mark the string @code{"a default message"} it
+is not possible to mark the string initializers for @code{messages}.
+What is to be done? We have to fulfill two tasks. First we have to mark the
+strings so that the @code{xgettext} program (@pxref{xgettext Invocation})
+can find them, and second we have to translate the string at runtime
+before printing them.
-Later on, the maintenance is relatively easy. If, as a programmer,
-you add or modify a string, you will have to ask yourself if the
-new or altered string requires translation, and include it within
-@samp{_()} if you think it should be translated. @samp{"%s: %d"} is
-an example of string @emph{not} requiring translation!
+The first task can be fulfilled by creating a new keyword, which names a
+no-op. For the second we have to mark all access points to a string
+from the array. So one solution can look like this:
-@node Marking, c-format Flag, Mark Keywords, Sources
-@section Marking Translatable Strings
-@emindex marking strings for translation
+@example
+@group
+#define gettext_noop(String) String
-In PO mode, one set of features is meant more for the programmer than
-for the translator, and allows him to interactively mark which strings,
-in a set of program sources, are translatable, and which are not.
-Even if it is a fairly easy job for a programmer to find and mark
-such strings by other means, using any editor of his choice, PO mode
-makes this work more comfortable. Further, this gives translators
-who feel a little like programmers, or programmers who feel a little
-like translators, a tool letting them work at marking translatable
-strings in the program sources, while simultaneously producing a set of
-translation in some language, for the package being internationalized.
+@{
+ static const char *messages[] = @{
+ gettext_noop ("some very meaningful message"),
+ gettext_noop ("and another one")
+ @};
+ const char *string;
+ @dots{}
+ string
+ = index > 1 ? gettext ("a default message") : gettext (messages[index]);
-@emindex @code{etags}, using for marking strings
-The set of program sources, targetted by the PO mode commands describe
-here, should have an Emacs tags table constructed for your project,
-prior to using these PO file commands. This is easy to do. In any
-shell window, change the directory to the root of your project, then
-execute a command resembling:
+ fputs (string);
+ @dots{}
+@}
+@end group
+@end example
+
+Please convince yourself that the string which is written by
+@code{fputs} is translated in any case. How to get @code{xgettext} know
+the additional keyword @code{gettext_noop} is explained in @ref{xgettext
+Invocation}.
+
+The above is of course not the only solution. You could also come along
+with the following one:
@example
-etags src/*.[hc] lib/*.[hc]
+@group
+#define gettext_noop(String) String
+
+@{
+ static const char *messages[] = @{
+ gettext_noop ("some very meaningful message",
+ gettext_noop ("and another one")
+ @};
+ const char *string;
+ @dots{}
+ string
+ = index > 1 ? gettext_noop ("a default message") : messages[index];
+
+ fputs (gettext (string));
+ @dots{}
+@}
+@end group
@end example
-@noindent
-presuming here you want to process all @file{.h} and @file{.c} files
-from the @file{src/} and @file{lib/} directories. This command will
-explore all said files and create a @file{TAGS} file in your root
-directory, somewhat summarizing the contents using a special file
-format Emacs can understand.
+But this has a drawback. The programmer has to take care that
+he uses @code{gettext_noop} for the string @code{"a default message"}.
+A use of @code{gettext} could have in rare cases unpredictable results.
-@emindex @file{TAGS}, and marking translatable strings
-For packages following the GNU coding standards, there is
-a make goal @code{tags} or @code{TAGS} which constructs the tag files in
-all directories and for all files containing source code.
+One advantage is that you need not make control flow analysis to make
+sure the output is really translated in any case. But this analysis is
+generally not very difficult. If it should be in any situation you can
+use this second method in this situation.
-Once your @file{TAGS} file is ready, the following commands assist
-the programmer at marking translatable strings in his set of sources.
-But these commands are necessarily driven from within a PO file
-window, and it is likely that you do not even have such a PO file yet.
-This is not a problem at all, as you may safely open a new, empty PO
-file, mainly for using these commands. This empty PO file will slowly
-fill in while you mark strings as translatable in your program sources.
+@node Names, Libraries, Special cases, Sources
+@section Marking Proper Names for Translation
-@table @kbd
-@item ,
-@efindex ,@r{, PO Mode command}
-Search through program sources for a string which looks like a
-candidate for translation (@code{po-tags-search}).
+Should names of persons, cities, locations etc. be marked for translation
+or not? People who only know languages that can be written with Latin
+letters (English, Spanish, French, German, etc.) are tempted to say ``no'',
+because names usually do not change when transported between these languages.
+However, in general when translating from one script to another, names
+are translated too, usually phonetically or by transliteration. For
+example, Russian or Greek names are converted to the Latin alphabet when
+being translated to English, and English or French names are converted
+to the Katakana script when being translated to Japanese. This is
+necessary because the speakers of the target language in general cannot
+read the script the name is originally written in.
-@item M-,
-@efindex M-,@r{, PO Mode command}
-Mark the last string found with @samp{_()} (@code{po-mark-translatable}).
+As a programmer, you should therefore make sure that names are marked
+for translation, with a special comment telling the translators that it
+is a proper name and how to pronounce it. Like this:
-@item M-.
-@efindex M-.@r{, PO Mode command}
-Mark the last string found with a keyword taken from a set of possible
-keywords. This command with a prefix allows some management of these
-keywords (@code{po-select-mark-and-mark}).
+@example
+@group
+printf (_("Written by %s.\n"),
+ /* TRANSLATORS: This is a proper name. See the gettext
+ manual, section Names. Note this is actually a non-ASCII
+ name: The first name is (with Unicode escapes)
+ "Fran\u00e7ois" or (with HTML entities) "François".
+ Pronounciation is like "fraa-swa pee-nar". */
+ _("Francois Pinard"));
+@end group
+@end example
-@end table
+As a translator, you should use some care when translating names, because
+it is frustrating if people see their names mutilated or distorted. If
+your language uses the Latin script, all you need to do is to reproduce
+the name as perfectly as you can within the usual character set of your
+language. In this particular case, this means to provide a translation
+containing the c-cedilla character. If your language uses a different
+script and the people speaking it don't usually read Latin words, it means
+transliteration; but you should still give, in parentheses, the original
+writing of the name -- for the sake of the people that do read the Latin
+script. Here is an example, using Greek as the target script:
-@efindex po-tags-search@r{, PO Mode command}
-The @kbd{,} (@code{po-tags-search}) command searches for the next
-occurrence of a string which looks like a possible candidate for
-translation, and displays the program source in another Emacs window,
-positioned in such a way that the string is near the top of this other
-window. If the string is too big to fit whole in this window, it is
-positioned so only its end is shown. In any case, the cursor
-is left in the PO file window. If the shown string would be better
-presented differently in different native languages, you may mark it
-using @kbd{M-,} or @kbd{M-.}. Otherwise, you might rather ignore it
-and skip to the next string by merely repeating the @kbd{,} command.
+@example
+@group
+#. This is a proper name. See the gettext
+#. manual, section Names. Note this is actually a non-ASCII
+#. name: The first name is (with Unicode escapes)
+#. "Fran\u00e7ois" or (with HTML entities) "François".
+#. Pronounciation is like "fraa-swa pee-nar".
+msgid "Francois Pinard"
+msgstr "\phi\rho\alpha\sigma\omicron\alpha \pi\iota\nu\alpha\rho"
+ " (Francois Pinard)"
+@end group
+@end example
-A string is a good candidate for translation if it contains a sequence
-of three or more letters. A string containing at most two letters in
-a row will be considered as a candidate if it has more letters than
-non-letters. The command disregards strings containing no letters,
-or isolated letters only. It also disregards strings within comments,
-or strings already marked with some keyword PO mode knows (see below).
+Because translation of names is such a sensitive domain, it is a good
+idea to test your translation before submitting it.
-If you have never told Emacs about some @file{TAGS} file to use, the
-command will request that you specify one from the minibuffer, the
-first time you use the command. You may later change your @file{TAGS}
-file by using the regular Emacs command @w{@kbd{M-x visit-tags-table}},
-which will ask you to name the precise @file{TAGS} file you want
-to use. @xref{Tags, , Tag Tables, emacs, The Emacs Editor}.
+The translation project @url{http://sourceforge.net/projects/translation}
+has set up a POT file and translation domain consisting of program author
+names, with better facilities for the translator than those presented here.
+Namely, there the original name is written directly in Unicode (rather
+than with Unicode escapes or HTML entities), and the pronounciation is
+denoted using the International Phonetic Alphabet (see
+@url{http://www.wikipedia.org/wiki/International_Phonetic_Alphabet}).
-Each time you use the @kbd{,} command, the search resumes from where it was
-left by the previous search, and goes through all program sources,
-obeying the @file{TAGS} file, until all sources have been processed.
-However, by giving a prefix argument to the command @w{(@kbd{C-u
-,})}, you may request that the search be restarted all over again
-from the first program source; but in this case, strings that you
-recently marked as translatable will be automatically skipped.
+However, we don't recommend this approach for all POT files in all packages,
+because this would force translators to use PO files in UTF-8 encoding,
+which is - in the current state of software (as of 2003) - a major hassle
+for translators using GNU Emacs or XEmacs with po-mode.
-Using this @kbd{,} command does not prevent using of other regular
-Emacs tags commands. For example, regular @code{tags-search} or
-@code{tags-query-replace} commands may be used without disrupting the
-independent @kbd{,} search sequence. However, as implemented, the
-@emph{initial} @kbd{,} command (or the @kbd{,} command is used with a
-prefix) might also reinitialize the regular Emacs tags searching to the
-first tags file, this reinitialization might be considered spurious.
-
-@efindex po-mark-translatable@r{, PO Mode command}
-@efindex po-select-mark-and-mark@r{, PO Mode command}
-The @kbd{M-,} (@code{po-mark-translatable}) command will mark the
-recently found string with the @samp{_} keyword. The @kbd{M-.}
-(@code{po-select-mark-and-mark}) command will request that you type
-one keyword from the minibuffer and use that keyword for marking
-the string. Both commands will automatically create a new PO file
-untranslated entry for the string being marked, and make it the
-current entry (making it easy for you to immediately proceed to its
-translation, if you feel like doing it right away). It is possible
-that the modifications made to the program source by @kbd{M-,} or
-@kbd{M-.} render some source line longer than 80 columns, forcing you
-to break and re-indent this line differently. You may use the @kbd{O}
-command from PO mode, or any other window changing command from
-Emacs, to break out into the program source window, and do any
-needed adjustments. You will have to use some regular Emacs command
-to return the cursor to the PO file window, if you want command
-@kbd{,} for the next string, say.
+@node Libraries, , Names, Sources
+@section Preparing Library Sources
-The @kbd{M-.} command has a few built-in speedups, so you do not
-have to explicitly type all keywords all the time. The first such
-speedup is that you are presented with a @emph{preferred} keyword,
-which you may accept by merely typing @kbd{@key{RET}} at the prompt.
-The second speedup is that you may type any non-ambiguous prefix of the
-keyword you really mean, and the command will complete it automatically
-for you. This also means that PO mode has to @emph{know} all
-your possible keywords, and that it will not accept mistyped keywords.
+When you are preparing a library, not a program, for the use of
+@code{gettext}, only a few details are different. Here we assume that
+the library has a translation domain and a POT file of its own. (If
+it uses the translation domain and POT file of the main program, then
+the previous sections apply without changes.)
-If you reply @kbd{?} to the keyword request, the command gives a
-list of all known keywords, from which you may choose. When the
-command is prefixed by an argument @w{(@kbd{C-u M-.})}, it inhibits
-updating any program source or PO file buffer, and does some simple
-keyword management instead. In this case, the command asks for a
-keyword, written in full, which becomes a new allowed keyword for
-later @kbd{M-.} commands. Moreover, this new keyword automatically
-becomes the @emph{preferred} keyword for later commands. By typing
-an already known keyword in response to @w{@kbd{C-u M-.}}, one merely
-changes the @emph{preferred} keyword and does nothing more.
+@enumerate
+@item
+The library code doesn't call @code{setlocale (LC_ALL, "")}. It's the
+responsibility of the main program to set the locale. The library's
+documentation should mention this fact, so that developers of programs
+using the library are aware of it.
-All keywords known for @kbd{M-.} are recognized by the @kbd{,} command
-when scanning for strings, and strings already marked by any of those
-known keywords are automatically skipped. If many PO files are opened
-simultaneously, each one has its own independent set of known keywords.
-There is no provision in PO mode, currently, for deleting a known
-keyword, you have to quit the file (maybe using @kbd{q}) and reopen
-it afresh. When a PO file is newly brought up in an Emacs window, only
-@samp{gettext} and @samp{_} are known as keywords, and @samp{gettext}
-is preferred for the @kbd{M-.} command. In fact, this is not useful to
-prefer @samp{_}, as this one is already built in the @kbd{M-,} command.
+@item
+The library code doesn't call @code{textdomain (PACKAGE)}, because it
+would interfere with the text domain set by the main program.
-@node c-format Flag, Special cases, Marking, Sources
-@section Special Comments preceding Keywords
+@item
+The initialization code for a program was
-@c FIXME document c-format and no-c-format.
+@smallexample
+ setlocale (LC_ALL, "");
+ bindtextdomain (PACKAGE, LOCALEDIR);
+ textdomain (PACKAGE);
+@end smallexample
-@cindex format strings
-In C programs strings are often used within calls of functions from the
-@code{printf} family. The special thing about these format strings is
-that they can contain format specifiers introduced with @kbd{%}. Assume
-we have the code
+@noindent
+For a library it is reduced to
-@example
-printf (gettext ("String `%s' has %d characters\n"), s, strlen (s));
-@end example
+@smallexample
+ bindtextdomain (PACKAGE, LOCALEDIR);
+@end smallexample
@noindent
-A possible German translation for the above string might be:
+If your library's API doesn't already have an initialization function,
+you need to create one, containing at least the @code{bindtextdomain}
+invocation. However, you usually don't need to export and document this
+initialization function: It is sufficient that all entry points of the
+library call the initialization function if it hasn't been called before.
+The typical idiom used to achieve this is a static boolean variable that
+indicates whether the initialization function has been called. Like this:
@example
-"%d Zeichen lang ist die Zeichenkette `%s'"
+@group
+static bool libfoo_initialized;
+
+static void
+libfoo_initialize (void)
+@{
+ bindtextdomain (PACKAGE, LOCALEDIR);
+ libfoo_initialized = true;
+@}
+
+/* This function is part of the exported API. */
+struct foo *
+create_foo (...)
+@{
+ /* Must ensure the initialization is performed. */
+ if (!libfoo_initialized)
+ libfoo_initialize ();
+ ...
+@}
+
+/* This function is part of the exported API. The argument must be
+ non-NULL and have been created through create_foo(). */
+int
+foo_refcount (struct foo *argument)
+@{
+ /* No need to invoke the initialization function here, because
+ create_foo() must already have been called before. */
+ ...
+@}
+@end group
@end example
-A C programmer, even if he cannot speak German, will recognize that
-there is something wrong here. The order of the two format specifiers
-is changed but of course the arguments in the @code{printf} don't have.
-This will most probably lead to problems because now the length of the
-string is regarded as the address.
+@item
+The usual declaration of the @samp{_} macro in each source file was
-To prevent errors at runtime caused by translations the @code{msgfmt}
-tool can check statically whether the arguments in the original and the
-translation string match in type and number. If this is not the case
-and the @samp{-c} option has been passed to @code{msgfmt}, @code{msgfmt}
-will give an error and refuse to produce a MO file. Thus consequent
-use of @samp{msgfmt -c} will catch the error, so that it cannot cause
-cause problems at runtime.
+@smallexample
+#include <libintl.h>
+#define _(String) gettext (String)
+@end smallexample
@noindent
-If the word order in the above German translation would be correct one
-would have to write
+for a program. For a library, which has its own translation domain,
+it reads like this:
-@example
-"%2$d Zeichen lang ist die Zeichenkette `%1$s'"
-@end example
+@smallexample
+#include <libintl.h>
+#define _(String) dgettext (PACKAGE, String)
+@end smallexample
-@noindent
-The routines in @code{msgfmt} know about this special notation.
+In other words, @code{dgettext} is used instead of @code{gettext}.
+Similary, the @code{dngettext} function should be used in place of the
+@code{ngettext} function.
+@end enumerate
-Because not all strings in a program must be format strings it is not
-useful for @code{msgfmt} to test all the strings in the @file{.po} file.
-This might cause problems because the string might contain what looks
-like a format specifier, but the string is not used in @code{printf}.
+@node Template, Creating, Sources, Top
+@chapter Making the PO Template File
+@cindex PO template file
-Therefore the @code{xgettext} adds a special tag to those messages it
-thinks might be a format string. There is no absolute rule for this,
-only a heuristic. In the @file{.po} file the entry is marked using the
-@code{c-format} flag in the @code{#,} comment line (@pxref{PO Files}).
+After preparing the sources, the programmer creates a PO template file.
+This section explains how to use @code{xgettext} for this purpose.
-@kwindex c-format@r{, and @code{xgettext}}
-@kwindex no-c-format@r{, and @code{xgettext}}
-The careful reader now might say that this again can cause problems.
-The heuristic might guess it wrong. This is true and therefore
-@code{xgettext} knows about a special kind of comment which lets
-the programmer take over the decision. If in the same line as or
-the immediately preceding line to the @code{gettext} keyword
-the @code{xgettext} program finds a comment containing the words
-@code{xgettext:c-format}, it will mark the string in any case with
-the @code{c-format} flag. This kind of comment should be used when
-@code{xgettext} does not recognize the string as a format string but
-it really is one and it should be tested. Please note that when the
-comment is in the same line as the @code{gettext} keyword, it must be
-before the string to be translated.
+@code{xgettext} creates a file named @file{@var{domainname}.po}. You
+should then rename it to @file{@var{domainname}.pot}. (Why doesn't
+@code{xgettext} create it under the name @file{@var{domainname}.pot}
+right away? The answer is: for historical reasons. When @code{xgettext}
+was specified, the distinction between a PO file and PO file template
+was fuzzy, and the suffix @samp{.pot} wasn't in use at that time.)
-This situation happens quite often. The @code{printf} function is often
-called with strings which do not contain a format specifier. Of course
-one would normally use @code{fputs} but it does happen. In this case
-@code{xgettext} does not recognize this as a format string but what
-happens if the translation introduces a valid format specifier? The
-@code{printf} function will try to access one of the parameters but none
-exists because the original code does not pass any parameters.
+@c FIXME: Rewrite.
-@code{xgettext} of course could make a wrong decision the other way
-round, i.e. a string marked as a format string actually is not a format
-string. In this case the @code{msgfmt} might give too many warnings and
-would prevent translating the @file{.po} file. The method to prevent
-this wrong decision is similar to the one used above, only the comment
-to use must contain the string @code{xgettext:no-c-format}.
+@menu
+* xgettext Invocation:: Invoking the @code{xgettext} Program
+@end menu
-If a string is marked with @code{c-format} and this is not correct the
-user can find out who is responsible for the decision. See
-@ref{xgettext Invocation} to see how the @code{--debug} option can be
-used for solving this problem.
+@node xgettext Invocation, , Template, Template
+@section Invoking the @code{xgettext} Program
-@node Special cases, Names, c-format Flag, Sources
-@section Special Cases of Translatable Strings
+@include xgettext.texi
-@cindex marking string initializers
-The attentive reader might now point out that it is not always possible
-to mark translatable string with @code{gettext} or something like this.
-Consider the following case:
+@node Creating, Updating, Template, Top
+@chapter Creating a New PO File
+@cindex creating a new PO file
-@example
-@group
-@{
- static const char *messages[] = @{
- "some very meaningful message",
- "and another one"
- @};
- const char *string;
- @dots{}
- string
- = index > 1 ? "a default message" : messages[index];
+When starting a new translation, the translator creates a file called
+@file{@var{LANG}.po}, as a copy of the @file{@var{package}.pot} template
+file with modifications in the initial comments (at the beginning of the file)
+and in the header entry (the first entry, near the beginning of the file).
- fputs (string);
- @dots{}
-@}
-@end group
-@end example
-
-While it is no problem to mark the string @code{"a default message"} it
-is not possible to mark the string initializers for @code{messages}.
-What is to be done? We have to fulfill two tasks. First we have to mark the
-strings so that the @code{xgettext} program (@pxref{xgettext Invocation})
-can find them, and second we have to translate the string at runtime
-before printing them.
-
-The first task can be fulfilled by creating a new keyword, which names a
-no-op. For the second we have to mark all access points to a string
-from the array. So one solution can look like this:
-
-@example
-@group
-#define gettext_noop(String) String
-
-@{
- static const char *messages[] = @{
- gettext_noop ("some very meaningful message"),
- gettext_noop ("and another one")
- @};
- const char *string;
- @dots{}
- string
- = index > 1 ? gettext ("a default message") : gettext (messages[index]);
-
- fputs (string);
- @dots{}
-@}
-@end group
-@end example
-
-Please convince yourself that the string which is written by
-@code{fputs} is translated in any case. How to get @code{xgettext} know
-the additional keyword @code{gettext_noop} is explained in @ref{xgettext
-Invocation}.
-
-The above is of course not the only solution. You could also come along
-with the following one:
+The easiest way to do so is by use of the @samp{msginit} program.
+For example:
@example
-@group
-#define gettext_noop(String) String
-
-@{
- static const char *messages[] = @{
- gettext_noop ("some very meaningful message",
- gettext_noop ("and another one")
- @};
- const char *string;
- @dots{}
- string
- = index > 1 ? gettext_noop ("a default message") : messages[index];
-
- fputs (gettext (string));
- @dots{}
-@}
-@end group
+$ cd @var{PACKAGE}-@var{VERSION}
+$ cd po
+$ msginit
@end example
-But this has a drawback. The programmer has to take care that
-he uses @code{gettext_noop} for the string @code{"a default message"}.
-A use of @code{gettext} could have in rare cases unpredictable results.
+The alternative way is to do the copy and modifications by hand.
+To do so, the translator copies @file{@var{package}.pot} to
+@file{@var{LANG}.po}. Then she modifies the initial comments and
+the header entry of this file.
-One advantage is that you need not make control flow analysis to make
-sure the output is really translated in any case. But this analysis is
-generally not very difficult. If it should be in any situation you can
-use this second method in this situation.
+@menu
+* msginit Invocation:: Invoking the @code{msginit} Program
+* Header Entry:: Filling in the Header Entry
+@end menu
-@node Names, Libraries, Special cases, Sources
-@section Marking Proper Names for Translation
+@node msginit Invocation, Header Entry, Creating, Creating
+@section Invoking the @code{msginit} Program
-Should names of persons, cities, locations etc. be marked for translation
-or not? People who only know languages that can be written with Latin
-letters (English, Spanish, French, German, etc.) are tempted to say ``no'',
-because names usually do not change when transported between these languages.
-However, in general when translating from one script to another, names
-are translated too, usually phonetically or by transliteration. For
-example, Russian or Greek names are converted to the Latin alphabet when
-being translated to English, and English or French names are converted
-to the Katakana script when being translated to Japanese. This is
-necessary because the speakers of the target language in general cannot
-read the script the name is originally written in.
+@include msginit.texi
-As a programmer, you should therefore make sure that names are marked
-for translation, with a special comment telling the translators that it
-is a proper name and how to pronounce it. Like this:
+@node Header Entry, , msginit Invocation, Creating
+@section Filling in the Header Entry
+@cindex header entry of a PO file
-@example
-@group
-printf (_("Written by %s.\n"),
- /* TRANSLATORS: This is a proper name. See the gettext
- manual, section Names. Note this is actually a non-ASCII
- name: The first name is (with Unicode escapes)
- "Fran\u00e7ois" or (with HTML entities) "François".
- Pronounciation is like "fraa-swa pee-nar". */
- _("Francois Pinard"));
-@end group
-@end example
+The initial comments "SOME DESCRIPTIVE TITLE", "YEAR" and
+"FIRST AUTHOR <EMAIL@@ADDRESS>, YEAR" ought to be replaced by sensible
+information. This can be done in any text editor; if Emacs is used
+and it switched to PO mode automatically (because it has recognized
+the file's suffix), you can disable it by typing @kbd{M-x fundamental-mode}.
-As a translator, you should use some care when translating names, because
-it is frustrating if people see their names mutilated or distorted. If
-your language uses the Latin script, all you need to do is to reproduce
-the name as perfectly as you can within the usual character set of your
-language. In this particular case, this means to provide a translation
-containing the c-cedilla character. If your language uses a different
-script and the people speaking it don't usually read Latin words, it means
-transliteration; but you should still give, in parentheses, the original
-writing of the name -- for the sake of the people that do read the Latin
-script. Here is an example, using Greek as the target script:
+Modifying the header entry can already be done using PO mode: in Emacs,
+type @kbd{M-x po-mode RET} and then @kbd{RET} again to start editing the
+entry. You should fill in the following fields.
-@example
-@group
-#. This is a proper name. See the gettext
-#. manual, section Names. Note this is actually a non-ASCII
-#. name: The first name is (with Unicode escapes)
-#. "Fran\u00e7ois" or (with HTML entities) "François".
-#. Pronounciation is like "fraa-swa pee-nar".
-msgid "Francois Pinard"
-msgstr "\phi\rho\alpha\sigma\omicron\alpha \pi\iota\nu\alpha\rho"
- " (Francois Pinard)"
-@end group
-@end example
+@table @asis
+@item Project-Id-Version
+This is the name and version of the package.
-Because translation of names is such a sensitive domain, it is a good
-idea to test your translation before submitting it.
+@item Report-Msgid-Bugs-To
+This has already been filled in by @code{xgettext}. It contains an email
+address or URL where you can report bugs in the untranslated strings:
-The translation project @url{http://sourceforge.net/projects/translation}
-has set up a POT file and translation domain consisting of program author
-names, with better facilities for the translator than those presented here.
-Namely, there the original name is written directly in Unicode (rather
-than with Unicode escapes or HTML entities), and the pronounciation is
-denoted using the International Phonetic Alphabet (see
-@url{http://www.wikipedia.org/wiki/International_Phonetic_Alphabet}).
+@itemize -
+@item Strings which are not entire sentences, see the maintainer guidelines
+in @ref{Preparing Strings}.
+@item Strings which use unclear terms or require additional context to be
+understood.
+@item Strings which make invalid assumptions about notation of date, time or
+money.
+@item Pluralisation problems.
+@item Incorrect English spelling.
+@item Incorrect formatting.
+@end itemize
-However, we don't recommend this approach for all POT files in all packages,
-because this would force translators to use PO files in UTF-8 encoding,
-which is - in the current state of software (as of 2003) - a major hassle
-for translators using GNU Emacs or XEmacs with po-mode.
+@item POT-Creation-Date
+This has already been filled in by @code{xgettext}.
-@node Libraries, , Names, Sources
-@section Preparing Library Sources
+@item PO-Revision-Date
+You don't need to fill this in. It will be filled by the Emacs PO mode
+when you save the file.
-When you are preparing a library, not a program, for the use of
-@code{gettext}, only a few details are different. Here we assume that
-the library has a translation domain and a POT file of its own. (If
-it uses the translation domain and POT file of the main program, then
-the previous sections apply without changes.)
+@item Last-Translator
+Fill in your name and email address (without double quotes).
-@enumerate
-@item
-The library code doesn't call @code{setlocale (LC_ALL, "")}. It's the
-responsibility of the main program to set the locale. The library's
-documentation should mention this fact, so that developers of programs
-using the library are aware of it.
+@item Language-Team
+Fill in the English name of the language, and the email address or
+homepage URL of the language team you are part of.
-@item
-The library code doesn't call @code{textdomain (PACKAGE)}, because it
-would interfere with the text domain set by the main program.
+Before starting a translation, it is a good idea to get in touch with
+your translation team, not only to make sure you don't do duplicated work,
+but also to coordinate difficult linguistic issues.
-@item
-The initialization code for a program was
+@cindex list of translation teams, where to find
+In the Free Translation Project, each translation team has its own mailing
+list. The up-to-date list of teams can be found at the Free Translation
+Project's homepage, @uref{http://www.iro.umontreal.ca/contrib/po/HTML/},
+in the "National teams" area.
-@smallexample
- setlocale (LC_ALL, "");
- bindtextdomain (PACKAGE, LOCALEDIR);
- textdomain (PACKAGE);
-@end smallexample
+@item Content-Type
+@cindex encoding of PO files
+@cindex charset of PO files
+Replace @samp{CHARSET} with the character encoding used for your language,
+in your locale, or UTF-8. This field is needed for correct operation of the
+@code{msgmerge} and @code{msgfmt} programs, as well as for users whose
+locale's character encoding differs from yours (see @ref{Charset conversion}).
-@noindent
-For a library it is reduced to
+@cindex @code{locale} program
+You get the character encoding of your locale by running the shell command
+@samp{locale charmap}. If the result is @samp{C} or @samp{ANSI_X3.4-1968},
+which is equivalent to @samp{ASCII} (= @samp{US-ASCII}), it means that your
+locale is not correctly configured. In this case, ask your translation
+team which charset to use. @samp{ASCII} is not usable for any language
+except Latin.
-@smallexample
- bindtextdomain (PACKAGE, LOCALEDIR);
-@end smallexample
+@cindex encoding list
+Because the PO files must be portable to operating systems with less advanced
+internationalization facilities, the character encodings that can be used
+are limited to those supported by both GNU @code{libc} and GNU
+@code{libiconv}. These are:
+@code{ASCII}, @code{ISO-8859-1}, @code{ISO-8859-2}, @code{ISO-8859-3},
+@code{ISO-8859-4}, @code{ISO-8859-5}, @code{ISO-8859-6}, @code{ISO-8859-7},
+@code{ISO-8859-8}, @code{ISO-8859-9}, @code{ISO-8859-13}, @code{ISO-8859-14},
+@code{ISO-8859-15},
+@code{KOI8-R}, @code{KOI8-U}, @code{KOI8-T},
+@code{CP850}, @code{CP866}, @code{CP874},
+@code{CP932}, @code{CP949}, @code{CP950}, @code{CP1250}, @code{CP1251},
+@code{CP1252}, @code{CP1253}, @code{CP1254}, @code{CP1255}, @code{CP1256},
+@code{CP1257}, @code{GB2312}, @code{EUC-JP}, @code{EUC-KR}, @code{EUC-TW},
+@code{BIG5}, @code{BIG5-HKSCS}, @code{GBK}, @code{GB18030}, @code{SHIFT_JIS},
+@code{JOHAB}, @code{TIS-620}, @code{VISCII}, @code{GEORGIAN-PS}, @code{UTF-8}.
-@noindent
-If your library's API doesn't already have an initialization function,
-you need to create one, containing at least the @code{bindtextdomain}
-invocation. However, you usually don't need to export and document this
-initialization function: It is sufficient that all entry points of the
-library call the initialization function if it hasn't been called before.
-The typical idiom used to achieve this is a static boolean variable that
-indicates whether the initialization function has been called. Like this:
-
-@example
-@group
-static bool libfoo_initialized;
-
-static void
-libfoo_initialize (void)
-@{
- bindtextdomain (PACKAGE, LOCALEDIR);
- libfoo_initialized = true;
-@}
-
-/* This function is part of the exported API. */
-struct foo *
-create_foo (...)
-@{
- /* Must ensure the initialization is performed. */
- if (!libfoo_initialized)
- libfoo_initialize ();
- ...
-@}
-
-/* This function is part of the exported API. The argument must be
- non-NULL and have been created through create_foo(). */
-int
-foo_refcount (struct foo *argument)
-@{
- /* No need to invoke the initialization function here, because
- create_foo() must already have been called before. */
- ...
-@}
-@end group
-@end example
-
-@item
-The usual declaration of the @samp{_} macro in each source file was
-
-@smallexample
-#include <libintl.h>
-#define _(String) gettext (String)
-@end smallexample
-
-@noindent
-for a program. For a library, which has its own translation domain,
-it reads like this:
-
-@smallexample
-#include <libintl.h>
-#define _(String) dgettext (PACKAGE, String)
-@end smallexample
-
-In other words, @code{dgettext} is used instead of @code{gettext}.
-Similary, the @code{dngettext} function should be used in place of the
-@code{ngettext} function.
-@end enumerate
-
-@node Template, Creating, Sources, Top
-@chapter Making the PO Template File
-@cindex PO template file
-
-After preparing the sources, the programmer creates a PO template file.
-This section explains how to use @code{xgettext} for this purpose.
-
-@code{xgettext} creates a file named @file{@var{domainname}.po}. You
-should then rename it to @file{@var{domainname}.pot}. (Why doesn't
-@code{xgettext} create it under the name @file{@var{domainname}.pot}
-right away? The answer is: for historical reasons. When @code{xgettext}
-was specified, the distinction between a PO file and PO file template
-was fuzzy, and the suffix @samp{.pot} wasn't in use at that time.)
-
-@c FIXME: Rewrite.
-
-@menu
-* xgettext Invocation:: Invoking the @code{xgettext} Program
-@end menu
-
-@node xgettext Invocation, , Template, Template
-@section Invoking the @code{xgettext} Program
-
-@include xgettext.texi
-
-@node Creating, Updating, Template, Top
-@chapter Creating a New PO File
-@cindex creating a new PO file
-
-When starting a new translation, the translator creates a file called
-@file{@var{LANG}.po}, as a copy of the @file{@var{package}.pot} template
-file with modifications in the initial comments (at the beginning of the file)
-and in the header entry (the first entry, near the beginning of the file).
-
-The easiest way to do so is by use of the @samp{msginit} program.
-For example:
-
-@example
-$ cd @var{PACKAGE}-@var{VERSION}
-$ cd po
-$ msginit
-@end example
-
-The alternative way is to do the copy and modifications by hand.
-To do so, the translator copies @file{@var{package}.pot} to
-@file{@var{LANG}.po}. Then she modifies the initial comments and
-the header entry of this file.
-
-@menu
-* msginit Invocation:: Invoking the @code{msginit} Program
-* Header Entry:: Filling in the Header Entry
-@end menu
-
-@node msginit Invocation, Header Entry, Creating, Creating
-@section Invoking the @code{msginit} Program
-
-@include msginit.texi
-
-@node Header Entry, , msginit Invocation, Creating
-@section Filling in the Header Entry
-@cindex header entry of a PO file
-
-The initial comments "SOME DESCRIPTIVE TITLE", "YEAR" and
-"FIRST AUTHOR <EMAIL@@ADDRESS>, YEAR" ought to be replaced by sensible
-information. This can be done in any text editor; if Emacs is used
-and it switched to PO mode automatically (because it has recognized
-the file's suffix), you can disable it by typing @kbd{M-x fundamental-mode}.
-
-Modifying the header entry can already be done using PO mode: in Emacs,
-type @kbd{M-x po-mode RET} and then @kbd{RET} again to start editing the
-entry. You should fill in the following fields.
-
-@table @asis
-@item Project-Id-Version
-This is the name and version of the package.
-
-@item Report-Msgid-Bugs-To
-This has already been filled in by @code{xgettext}. It contains an email
-address or URL where you can report bugs in the untranslated strings:
-
-@itemize -
-@item Strings which are not entire sentences, see the maintainer guidelines
-in @ref{Preparing Strings}.
-@item Strings which use unclear terms or require additional context to be
-understood.
-@item Strings which make invalid assumptions about notation of date, time or
-money.
-@item Pluralisation problems.
-@item Incorrect English spelling.
-@item Incorrect formatting.
-@end itemize
-
-@item POT-Creation-Date
-This has already been filled in by @code{xgettext}.
-
-@item PO-Revision-Date
-You don't need to fill this in. It will be filled by the Emacs PO mode
-when you save the file.
-
-@item Last-Translator
-Fill in your name and email address (without double quotes).
-
-@item Language-Team
-Fill in the English name of the language, and the email address or
-homepage URL of the language team you are part of.
-
-Before starting a translation, it is a good idea to get in touch with
-your translation team, not only to make sure you don't do duplicated work,
-but also to coordinate difficult linguistic issues.
-
-@cindex list of translation teams, where to find
-In the Free Translation Project, each translation team has its own mailing
-list. The up-to-date list of teams can be found at the Free Translation
-Project's homepage, @uref{http://www.iro.umontreal.ca/contrib/po/HTML/},
-in the "National teams" area.
-
-@item Content-Type
-@cindex encoding of PO files
-@cindex charset of PO files
-Replace @samp{CHARSET} with the character encoding used for your language,
-in your locale, or UTF-8. This field is needed for correct operation of the
-@code{msgmerge} and @code{msgfmt} programs, as well as for users whose
-locale's character encoding differs from yours (see @ref{Charset conversion}).
-
-@cindex @code{locale} program
-You get the character encoding of your locale by running the shell command
-@samp{locale charmap}. If the result is @samp{C} or @samp{ANSI_X3.4-1968},
-which is equivalent to @samp{ASCII} (= @samp{US-ASCII}), it means that your
-locale is not correctly configured. In this case, ask your translation
-team which charset to use. @samp{ASCII} is not usable for any language
-except Latin.
-
-@cindex encoding list
-Because the PO files must be portable to operating systems with less advanced
-internationalization facilities, the character encodings that can be used
-are limited to those supported by both GNU @code{libc} and GNU
-@code{libiconv}. These are:
-@code{ASCII}, @code{ISO-8859-1}, @code{ISO-8859-2}, @code{ISO-8859-3},
-@code{ISO-8859-4}, @code{ISO-8859-5}, @code{ISO-8859-6}, @code{ISO-8859-7},
-@code{ISO-8859-8}, @code{ISO-8859-9}, @code{ISO-8859-13}, @code{ISO-8859-14},
-@code{ISO-8859-15},
-@code{KOI8-R}, @code{KOI8-U}, @code{KOI8-T},
-@code{CP850}, @code{CP866}, @code{CP874},
-@code{CP932}, @code{CP949}, @code{CP950}, @code{CP1250}, @code{CP1251},
-@code{CP1252}, @code{CP1253}, @code{CP1254}, @code{CP1255}, @code{CP1256},
-@code{CP1257}, @code{GB2312}, @code{EUC-JP}, @code{EUC-KR}, @code{EUC-TW},
-@code{BIG5}, @code{BIG5-HKSCS}, @code{GBK}, @code{GB18030}, @code{SHIFT_JIS},
-@code{JOHAB}, @code{TIS-620}, @code{VISCII}, @code{GEORGIAN-PS}, @code{UTF-8}.
-
-@c This data is taken from glibc/localedata/SUPPORTED.
-@cindex Linux
-In the GNU system, the following encodings are frequently used for the
-corresponding languages.
+@c This data is taken from glibc/localedata/SUPPORTED.
+@cindex Linux
+In the GNU system, the following encodings are frequently used for the
+corresponding languages.
@cindex encoding for your language
@itemize
format of the plural forms field is described in @ref{Plural forms}.
@end table
-@node Updating, Manipulating, Creating, Top
+@node Updating, Editing, Creating, Top
@chapter Updating Existing PO Files
+@menu
+* msgmerge Invocation:: Invoking the @code{msgmerge} Program
+@end menu
+
+@node msgmerge Invocation, , Updating, Updating
+@section Invoking the @code{msgmerge} Program
+
+@include msgmerge.texi
+
+@node Editing, Manipulating, Updating, Top
+@chapter Editing PO Files
+@cindex Editing PO Files
+
+@menu
+* KBabel:: KDE's PO File Editor
+* Gtranslator:: GNOME's PO File Editor
+* PO Mode:: Emacs's PO File Editor
+@end menu
+
+@node KBabel, Gtranslator, Editing, Editing
+@section KDE's PO File Editor
+@cindex KDE PO file editor
+
+@node Gtranslator, PO Mode, KBabel, Editing
+@section GNOME's PO File Editor
+@cindex GNOME PO file editor
+
+@node PO Mode, , Gtranslator, Editing
+@section Emacs's PO File Editor
+@cindex Emacs PO Mode
+
@c FIXME: Rewrite.
@menu
-* msgmerge Invocation:: Invoking the @code{msgmerge} Program
+* Installation:: Completing GNU @code{gettext} Installation
+* Main PO Commands:: Main Commands
+* Entry Positioning:: Entry Positioning
+* Normalizing:: Normalizing Strings in Entries
* Translated Entries:: Translated Entries
* Fuzzy Entries:: Fuzzy Entries
* Untranslated Entries:: Untranslated Entries
* Compendium:: Using Translation Compendia
@end menu
-@node msgmerge Invocation, Translated Entries, Updating, Updating
-@section Invoking the @code{msgmerge} Program
+@node Installation, Main PO Commands, PO Mode, PO Mode
+@subsection Completing GNU @code{gettext} Installation
-@include msgmerge.texi
+@cindex installing @code{gettext}
+@cindex @code{gettext} installation
+Once you have received, unpacked, configured and compiled the GNU
+@code{gettext} distribution, the @samp{make install} command puts in
+place the programs @code{xgettext}, @code{msgfmt}, @code{gettext}, and
+@code{msgmerge}, as well as their available message catalogs. To
+top off a comfortable installation, you might also want to make the
+PO mode available to your Emacs users.
+
+@emindex @file{.emacs} customizations
+@emindex installing PO mode
+During the installation of the PO mode, you might want to modify your
+file @file{.emacs}, once and for all, so it contains a few lines looking
+like:
+
+@example
+(setq auto-mode-alist
+ (cons '("\\.po\\'\\|\\.po\\." . po-mode) auto-mode-alist))
+(autoload 'po-mode "po-mode" "Major mode for translators to edit PO files" t)
+@end example
+
+Later, whenever you edit some @file{.po}
+file, or any file having the string @samp{.po.} within its name,
+Emacs loads @file{po-mode.elc} (or @file{po-mode.el}) as needed, and
+automatically activates PO mode commands for the associated buffer.
+The string @emph{PO} appears in the mode line for any buffer for
+which PO mode is active. Many PO files may be active at once in a
+single Emacs session.
+
+If you are using Emacs version 20 or newer, and have already installed
+the appropriate international fonts on your system, you may also tell
+Emacs how to determine automatically the coding system of every PO file.
+This will often (but not always) cause the necessary fonts to be loaded
+and used for displaying the translations on your Emacs screen. For this
+to happen, add the lines:
+
+@example
+(modify-coding-system-alist 'file "\\.po\\'\\|\\.po\\."
+ 'po-find-file-coding-system)
+(autoload 'po-find-file-coding-system "po-mode")
+@end example
+
+@noindent
+to your @file{.emacs} file. If, with this, you still see boxes instead
+of international characters, try a different font set (via Shift Mouse
+button 1).
+
+@node Main PO Commands, Entry Positioning, Installation, PO Mode
+@subsection Main PO mode Commands
+
+@cindex PO mode (Emacs) commands
+@emindex commands
+After setting up Emacs with something similar to the lines in
+@ref{Installation}, PO mode is activated for a window when Emacs finds a
+PO file in that window. This puts the window read-only and establishes a
+po-mode-map, which is a genuine Emacs mode, in a way that is not derived
+from text mode in any way. Functions found on @code{po-mode-hook},
+if any, will be executed.
+
+When PO mode is active in a window, the letters @samp{PO} appear
+in the mode line for that window. The mode line also displays how
+many entries of each kind are held in the PO file. For example,
+the string @samp{132t+3f+10u+2o} would tell the translator that the
+PO mode contains 132 translated entries (@pxref{Translated Entries},
+3 fuzzy entries (@pxref{Fuzzy Entries}), 10 untranslated entries
+(@pxref{Untranslated Entries}) and 2 obsolete entries (@pxref{Obsolete
+Entries}). Zero-coefficients items are not shown. So, in this example, if
+the fuzzy entries were unfuzzied, the untranslated entries were translated
+and the obsolete entries were deleted, the mode line would merely display
+@samp{145t} for the counters.
+
+The main PO commands are those which do not fit into the other categories of
+subsequent sections. These allow for quitting PO mode or for managing windows
+in special ways.
+
+@table @kbd
+@item _
+@efindex _@r{, PO Mode command}
+Undo last modification to the PO file (@code{po-undo}).
+
+@item Q
+@efindex Q@r{, PO Mode command}
+Quit processing and save the PO file (@code{po-quit}).
+
+@item q
+@efindex q@r{, PO Mode command}
+Quit processing, possibly after confirmation (@code{po-confirm-and-quit}).
+
+@item 0
+@efindex 0@r{, PO Mode command}
+Temporary leave the PO file window (@code{po-other-window}).
+
+@item ?
+@itemx h
+@efindex ?@r{, PO Mode command}
+@efindex h@r{, PO Mode command}
+Show help about PO mode (@code{po-help}).
+
+@item =
+@efindex =@r{, PO Mode command}
+Give some PO file statistics (@code{po-statistics}).
+
+@item V
+@efindex V@r{, PO Mode command}
+Batch validate the format of the whole PO file (@code{po-validate}).
+
+@end table
+
+@efindex _@r{, PO Mode command}
+@efindex po-undo@r{, PO Mode command}
+The command @kbd{_} (@code{po-undo}) interfaces to the Emacs
+@emph{undo} facility. @xref{Undo, , Undoing Changes, emacs, The Emacs
+Editor}. Each time @kbd{U} is typed, modifications which the translator
+did to the PO file are undone a little more. For the purpose of
+undoing, each PO mode command is atomic. This is especially true for
+the @kbd{@key{RET}} command: the whole edition made by using a single
+use of this command is undone at once, even if the edition itself
+implied several actions. However, while in the editing window, one
+can undo the edition work quite parsimoniously.
+
+@efindex Q@r{, PO Mode command}
+@efindex q@r{, PO Mode command}
+@efindex po-quit@r{, PO Mode command}
+@efindex po-confirm-and-quit@r{, PO Mode command}
+The commands @kbd{Q} (@code{po-quit}) and @kbd{q}
+(@code{po-confirm-and-quit}) are used when the translator is done with the
+PO file. The former is a bit less verbose than the latter. If the file
+has been modified, it is saved to disk first. In both cases, and prior to
+all this, the commands check if any untranslated messages remain in the
+PO file and, if so, the translator is asked if she really wants to leave
+off working with this PO file. This is the preferred way of getting rid
+of an Emacs PO file buffer. Merely killing it through the usual command
+@w{@kbd{C-x k}} (@code{kill-buffer}) is not the tidiest way to proceed.
+
+@efindex 0@r{, PO Mode command}
+@efindex po-other-window@r{, PO Mode command}
+The command @kbd{0} (@code{po-other-window}) is another, softer way,
+to leave PO mode, temporarily. It just moves the cursor to some other
+Emacs window, and pops one if necessary. For example, if the translator
+just got PO mode to show some source context in some other, she might
+discover some apparent bug in the program source that needs correction.
+This command allows the translator to change sex, become a programmer,
+and have the cursor right into the window containing the program she
+(or rather @emph{he}) wants to modify. By later getting the cursor back
+in the PO file window, or by asking Emacs to edit this file once again,
+PO mode is then recovered.
+
+@efindex ?@r{, PO Mode command}
+@efindex h@r{, PO Mode command}
+@efindex po-help@r{, PO Mode command}
+The command @kbd{h} (@code{po-help}) displays a summary of all available PO
+mode commands. The translator should then type any character to resume
+normal PO mode operations. The command @kbd{?} has the same effect
+as @kbd{h}.
+
+@efindex =@r{, PO Mode command}
+@efindex po-statistics@r{, PO Mode command}
+The command @kbd{=} (@code{po-statistics}) computes the total number of
+entries in the PO file, the ordinal of the current entry (counted from
+1), the number of untranslated entries, the number of obsolete entries,
+and displays all these numbers.
+
+@efindex V@r{, PO Mode command}
+@efindex po-validate@r{, PO Mode command}
+The command @kbd{V} (@code{po-validate}) launches @code{msgfmt} in
+checking and verbose
+mode over the current PO file. This command first offers to save the
+current PO file on disk. The @code{msgfmt} tool, from GNU @code{gettext},
+has the purpose of creating a MO file out of a PO file, and PO mode uses
+the features of this program for checking the overall format of a PO file,
+as well as all individual entries.
+
+@efindex next-error@r{, stepping through PO file validation results}
+The program @code{msgfmt} runs asynchronously with Emacs, so the
+translator regains control immediately while her PO file is being studied.
+Error output is collected in the Emacs @samp{*compilation*} buffer,
+displayed in another window. The regular Emacs command @kbd{C-x`}
+(@code{next-error}), as well as other usual compile commands, allow the
+translator to reposition quickly to the offending parts of the PO file.
+Once the cursor is on the line in error, the translator may decide on
+any PO mode action which would help correcting the error.
+
+@node Entry Positioning, Normalizing, Main PO Commands, PO Mode
+@subsection Entry Positioning
+
+@emindex current entry of a PO file
+The cursor in a PO file window is almost always part of
+an entry. The only exceptions are the special case when the cursor
+is after the last entry in the file, or when the PO file is
+empty. The entry where the cursor is found to be is said to be the
+current entry. Many PO mode commands operate on the current entry,
+so moving the cursor does more than allowing the translator to browse
+the PO file, this also selects on which entry commands operate.
+
+@emindex moving through a PO file
+Some PO mode commands alter the position of the cursor in a specialized
+way. A few of those special purpose positioning are described here,
+the others are described in following sections (for a complete list try
+@kbd{C-h m}):
+
+@table @kbd
+
+@item .
+@efindex .@r{, PO Mode command}
+Redisplay the current entry (@code{po-current-entry}).
+
+@item n
+@efindex n@r{, PO Mode command}
+Select the entry after the current one (@code{po-next-entry}).
+
+@item p
+@efindex p@r{, PO Mode command}
+Select the entry before the current one (@code{po-previous-entry}).
+
+@item <
+@efindex <@r{, PO Mode command}
+Select the first entry in the PO file (@code{po-first-entry}).
+
+@item >
+@efindex >@r{, PO Mode command}
+Select the last entry in the PO file (@code{po-last-entry}).
+
+@item m
+@efindex m@r{, PO Mode command}
+Record the location of the current entry for later use
+(@code{po-push-location}).
+
+@item r
+@efindex r@r{, PO Mode command}
+Return to a previously saved entry location (@code{po-pop-location}).
+
+@item x
+@efindex x@r{, PO Mode command}
+Exchange the current entry location with the previously saved one
+(@code{po-exchange-location}).
+
+@end table
+
+@efindex .@r{, PO Mode command}
+@efindex po-current-entry@r{, PO Mode command}
+Any Emacs command able to reposition the cursor may be used
+to select the current entry in PO mode, including commands which
+move by characters, lines, paragraphs, screens or pages, and search
+commands. However, there is a kind of standard way to display the
+current entry in PO mode, which usual Emacs commands moving
+the cursor do not especially try to enforce. The command @kbd{.}
+(@code{po-current-entry}) has the sole purpose of redisplaying the
+current entry properly, after the current entry has been changed by
+means external to PO mode, or the Emacs screen otherwise altered.
+
+It is yet to be decided if PO mode helps the translator, or otherwise
+irritates her, by forcing a rigid window disposition while she
+is doing her work. We originally had quite precise ideas about
+how windows should behave, but on the other hand, anyone used to
+Emacs is often happy to keep full control. Maybe a fixed window
+disposition might be offered as a PO mode option that the translator
+might activate or deactivate at will, so it could be offered on an
+experimental basis. If nobody feels a real need for using it, or
+a compulsion for writing it, we should drop this whole idea.
+The incentive for doing it should come from translators rather than
+programmers, as opinions from an experienced translator are surely
+more worth to me than opinions from programmers @emph{thinking} about
+how @emph{others} should do translation.
+
+@efindex n@r{, PO Mode command}
+@efindex po-next-entry@r{, PO Mode command}
+@efindex p@r{, PO Mode command}
+@efindex po-previous-entry@r{, PO Mode command}
+The commands @kbd{n} (@code{po-next-entry}) and @kbd{p}
+(@code{po-previous-entry}) move the cursor the entry following,
+or preceding, the current one. If @kbd{n} is given while the
+cursor is on the last entry of the PO file, or if @kbd{p}
+is given while the cursor is on the first entry, no move is done.
+
+@efindex <@r{, PO Mode command}
+@efindex po-first-entry@r{, PO Mode command}
+@efindex >@r{, PO Mode command}
+@efindex po-last-entry@r{, PO Mode command}
+The commands @kbd{<} (@code{po-first-entry}) and @kbd{>}
+(@code{po-last-entry}) move the cursor to the first entry, or last
+entry, of the PO file. When the cursor is located past the last
+entry in a PO file, most PO mode commands will return an error saying
+@samp{After last entry}. Moreover, the commands @kbd{<} and @kbd{>}
+have the special property of being able to work even when the cursor
+is not into some PO file entry, and one may use them for nicely
+correcting this situation. But even these commands will fail on a
+truly empty PO file. There are development plans for the PO mode for it
+to interactively fill an empty PO file from sources. @xref{Marking}.
+
+The translator may decide, before working at the translation of
+a particular entry, that she needs to browse the remainder of the
+PO file, maybe for finding the terminology or phraseology used
+in related entries. She can of course use the standard Emacs idioms
+for saving the current cursor location in some register, and use that
+register for getting back, or else, use the location ring.
+
+@efindex m@r{, PO Mode command}
+@efindex po-push-location@r{, PO Mode command}
+@efindex r@r{, PO Mode command}
+@efindex po-pop-location@r{, PO Mode command}
+PO mode offers another approach, by which cursor locations may be saved
+onto a special stack. The command @kbd{m} (@code{po-push-location})
+merely adds the location of current entry to the stack, pushing
+the already saved locations under the new one. The command
+@kbd{r} (@code{po-pop-location}) consumes the top stack element and
+repositions the cursor to the entry associated with that top element.
+This position is then lost, for the next @kbd{r} will move the cursor
+to the previously saved location, and so on until no locations remain
+on the stack.
+
+If the translator wants the position to be kept on the location stack,
+maybe for taking a look at the entry associated with the top
+element, then go elsewhere with the intent of getting back later, she
+ought to use @kbd{m} immediately after @kbd{r}.
+
+@efindex x@r{, PO Mode command}
+@efindex po-exchange-location@r{, PO Mode command}
+The command @kbd{x} (@code{po-exchange-location}) simultaneously
+repositions the cursor to the entry associated with the top element of
+the stack of saved locations, and replaces that top element with the
+location of the current entry before the move. Consequently, repeating
+the @kbd{x} command toggles alternatively between two entries.
+For achieving this, the translator will position the cursor on the
+first entry, use @kbd{m}, then position to the second entry, and
+merely use @kbd{x} for making the switch.
+
+@node Normalizing, Translated Entries, Entry Positioning, PO Mode
+@subsection Normalizing Strings in Entries
+@cindex string normalization in entries
+
+There are many different ways for encoding a particular string into a
+PO file entry, because there are so many different ways to split and
+quote multi-line strings, and even, to represent special characters
+by backslashed escaped sequences. Some features of PO mode rely on
+the ability for PO mode to scan an already existing PO file for a
+particular string encoded into the @code{msgid} field of some entry.
+Even if PO mode has internally all the built-in machinery for
+implementing this recognition easily, doing it fast is technically
+difficult. To facilitate a solution to this efficiency problem,
+we decided on a canonical representation for strings.
+
+A conventional representation of strings in a PO file is currently
+under discussion, and PO mode experiments with a canonical representation.
+Having both @code{xgettext} and PO mode converging towards a uniform
+way of representing equivalent strings would be useful, as the internal
+normalization needed by PO mode could be automatically satisfied
+when using @code{xgettext} from GNU @code{gettext}. An explicit
+PO mode normalization should then be only necessary for PO files
+imported from elsewhere, or for when the convention itself evolves.
+
+So, for achieving normalization of at least the strings of a given
+PO file needing a canonical representation, the following PO mode
+command is available:
+
+@emindex string normalization in entries
+@table @kbd
+@item M-x po-normalize
+@efindex po-normalize@r{, PO Mode command}
+Tidy the whole PO file by making entries more uniform.
+
+@end table
+
+The special command @kbd{M-x po-normalize}, which has no associated
+keys, revises all entries, ensuring that strings of both original
+and translated entries use uniform internal quoting in the PO file.
+It also removes any crumb after the last entry. This command may be
+useful for PO files freshly imported from elsewhere, or if we ever
+improve on the canonical quoting format we use. This canonical format
+is not only meant for getting cleaner PO files, but also for greatly
+speeding up @code{msgid} string lookup for some other PO mode commands.
+
+@kbd{M-x po-normalize} presently makes three passes over the entries.
+The first implements heuristics for converting PO files for GNU
+@code{gettext} 0.6 and earlier, in which @code{msgid} and @code{msgstr}
+fields were using K&R style C string syntax for multi-line strings.
+These heuristics may fail for comments not related to obsolete
+entries and ending with a backslash; they also depend on subsequent
+passes for finalizing the proper commenting of continued lines for
+obsolete entries. This first pass might disappear once all oldish PO
+files would have been adjusted. The second and third pass normalize
+all @code{msgid} and @code{msgstr} strings respectively. They also
+clean out those trailing backslashes used by XView's @code{msgfmt}
+for continued lines.
+
+@cindex importing PO files
+Having such an explicit normalizing command allows for importing PO
+files from other sources, but also eases the evolution of the current
+convention, evolution driven mostly by aesthetic concerns, as of now.
+It is easy to make suggested adjustments at a later time, as the
+normalizing command and eventually, other GNU @code{gettext} tools
+should greatly automate conformance. A description of the canonical
+string format is given below, for the particular benefit of those not
+having Emacs handy, and who would nevertheless want to handcraft
+their PO files in nice ways.
+
+@cindex multi-line strings
+Right now, in PO mode, strings are single line or multi-line. A string
+goes multi-line if and only if it has @emph{embedded} newlines, that
+is, if it matches @samp{[^\n]\n+[^\n]}. So, we would have:
+
+@example
+msgstr "\n\nHello, world!\n\n\n"
+@end example
+
+but, replacing the space by a newline, this becomes:
+
+@example
+msgstr ""
+"\n"
+"\n"
+"Hello,\n"
+"world!\n"
+"\n"
+"\n"
+@end example
+
+We are deliberately using a caricatural example, here, to make the
+point clearer. Usually, multi-lines are not that bad looking.
+It is probable that we will implement the following suggestion.
+We might lump together all initial newlines into the empty string,
+and also all newlines introducing empty lines (that is, for @w{@var{n}
+> 1}, the @var{n}-1'th last newlines would go together on a separate
+string), so making the previous example appear:
+
+@example
+msgstr "\n\n"
+"Hello,\n"
+"world!\n"
+"\n\n"
+@end example
+
+There are a few yet undecided little points about string normalization,
+to be documented in this manual, once these questions settle.
-@node Translated Entries, Fuzzy Entries, msgmerge Invocation, Updating
-@section Translated Entries
+@node Translated Entries, Fuzzy Entries, Normalizing, PO Mode
+@subsection Translated Entries
@cindex translated entries
Each PO file entry for which the @code{msgstr} field has been filled with
be later unfuzzied before becoming an official, genuine translated entry.
@xref{Fuzzy Entries}.
-@node Fuzzy Entries, Untranslated Entries, Translated Entries, Updating
-@section Fuzzy Entries
+@node Fuzzy Entries, Untranslated Entries, Translated Entries, PO Mode
+@subsection Fuzzy Entries
@cindex fuzzy entries
@cindex attributes of a PO file entry
command, the translator is asked for confirmation, if fuzzy string
still exists.
-@node Untranslated Entries, Obsolete Entries, Fuzzy Entries, Updating
-@section Untranslated Entries
+@node Untranslated Entries, Obsolete Entries, Fuzzy Entries, PO Mode
+@subsection Untranslated Entries
@cindex untranslated entries
When @code{xgettext} originally creates a PO file, unless told
with the @kbd{q} command, the translator is asked for confirmation,
if some untranslated string still exists.
-@node Obsolete Entries, Modifying Translations, Untranslated Entries, Updating
-@section Obsolete Entries
+@node Obsolete Entries, Modifying Translations, Untranslated Entries, PO Mode
+@subsection Obsolete Entries
@cindex obsolete entries
By @dfn{obsolete} PO file entries, we mean those entries which are
when the time comes to find the adequate obsolete translation, it
merely tries to provide handy tools for helping her to do so.
-@node Modifying Translations, Modifying Comments, Obsolete Entries, Updating
-@section Modifying Translations
+@node Modifying Translations, Modifying Comments, Obsolete Entries, PO Mode
+@subsection Modifying Translations
@cindex editing translations
@emindex editing translations
capability of learning these sequences and playing them back under request.
@xref{Keyboard Macros, , , emacs, The Emacs Editor}.
-@node Modifying Comments, Subedit, Modifying Translations, Updating
-@section Modifying Comments
+@node Modifying Comments, Subedit, Modifying Translations, PO Mode
+@subsection Modifying Comments
@cindex editing comments in PO files
@emindex editing comments
regular Emacs commands @kbd{C-y} (@code{yank}) and @kbd{M-y}
(@code{yank-pop}) to get the previous translation where she likes.
-@node Subedit, C Sources Context, Modifying Comments, Updating
-@section Details of Sub Edition
+@node Subedit, C Sources Context, Modifying Comments, PO Mode
+@subsection Details of Sub Edition
@emindex subedit minor mode
The PO subedit minor mode has a few peculiarities worth being described
translator asks for quitting the PO file (with the @kbd{q} command), subedits
are automatically resumed one at a time, so she may decide for each of them.
-@node C Sources Context, Auxiliary, Subedit, Updating
-@section C Sources Context
+@node C Sources Context, Auxiliary, Subedit, PO Mode
+@subsection C Sources Context
@emindex consulting program sources
@emindex looking at the source to aid translation
@emindex use the source, Luke
@kbd{M-S} (@code{po-ignore-source-path}) is used to select, with completion,
one of the directories she does not want anymore on the search path.
-@node Auxiliary, Compendium, C Sources Context, Updating
-@section Consulting Auxiliary PO Files
+@node Auxiliary, Compendium, C Sources Context, PO Mode
+@subsection Consulting Auxiliary PO Files
@emindex consulting translations to other languages
PO mode is able to help the knowledgeable translator, being fluent in
discrepancies between PO mode and other GNU @code{gettext} tools get
fully resolved, the translator should stay aware of normalisation issues.
-@node Compendium, , Auxiliary, Updating
-@section Using Translation Compendia
+@node Compendium, , Auxiliary, PO Mode
+@subsection Using Translation Compendia
@emindex using translation compendia
@cindex compendium
@end menu
@node Creating Compendia, Using Compendia, Compendium, Compendium
-@subsection Creating Compendia
+@subsubsection Creating Compendia
@cindex creating compendia
@cindex compendium, creating
@end example
@node Using Compendia, , Creating Compendia, Compendium
-@subsection Using Compendia
+@subsubsection Using Compendia
You can use a compendium file to initialize a translation from scratch
or to update an already existing translation.
msgmerge update.po file.pot | sed -e '/^#~/d' > file.po
@end example
-@node Manipulating, Binaries, Updating, Top
+@node Manipulating, Binaries, Editing, Top
@chapter Manipulating PO Files
@cindex manipulating PO files
projects / thirdparty / gettext.git / commitdiff
