gettext/doc/gettext.info-4

This is gettext.info, produced by makeinfo version 4.2 from
gettext.texi.

INFO-DIR-SECTION GNU Gettext Utilities
START-INFO-DIR-ENTRY
* gettext: (gettext).                          GNU gettext utilities.
* autopoint: (gettext)autopoint Invocation.    Copy gettext infrastructure.
* gettextize: (gettext)gettextize Invocation.  Prepare a package for gettext.
* msgattrib: (gettext)msgattrib Invocation.    Select part of a PO file.
* msgcat: (gettext)msgcat Invocation.          Combine several PO files.
* msgcmp: (gettext)msgcmp Invocation.          Compare a PO file and template.
* msgcomm: (gettext)msgcomm Invocation.        Match two PO files.
* msgconv: (gettext)msgconv Invocation.        Convert PO file to encoding.
* msgen: (gettext)msgen Invocation.            Create an English PO file.
* msgexec: (gettext)msgexec Invocation.        Process a PO file.
* msgfilter: (gettext)msgfilter Invocation.    Pipe a PO file through a filter.
* msgfmt: (gettext)msgfmt Invocation.          Make MO files out of PO files.
* msggrep: (gettext)msggrep Invocation.        Select part of a PO file.
* msginit: (gettext)msginit Invocation.        Create a fresh PO file.
* msgmerge: (gettext)msgmerge Invocation.      Update a PO file from template.
* msgunfmt: (gettext)msgunfmt Invocation.      Uncompile MO file into PO file.
* msguniq: (gettext)msguniq Invocation.        Unify duplicates for PO file.
* xgettext: (gettext)xgettext Invocation.      Extract strings into a PO file.
* ISO639: (gettext)Language Codes.             ISO 639 language codes.
* ISO3166: (gettext)Country Codes.             ISO 3166 country codes.
END-INFO-DIR-ENTRY

   This file provides documentation for GNU `gettext' utilities.  It
also serves as a reference for the free Translation Project.

   Copyright (C) 1995, 1996, 1997, 1998, 2001, 2002 Free Software
Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.


File: gettext.info,  Node: C Sources Context,  Next: Auxiliary,  Prev: Subedit,  Up: Updating

C Sources Context
=================

   PO mode is particularly powerful when used with PO files created
through GNU `gettext' utilities, as those utilities insert special
comments in the PO files they generate.  Some of these special comments
relate the PO file entry to exactly where the untranslated string
appears in the program sources.

   When the translator gets to an untranslated entry, she is fairly
often faced with an original string which is not as informative as it
normally should be, being succinct, cryptic, or otherwise ambiguous.
Before choosing how to translate the string, she needs to understand
better what the string really means and how tight the translation has
to be.  Most of the time, when problems arise, the only way left to make
her judgment is looking at the true program sources from where this
string originated, searching for surrounding comments the programmer
might have put in there, and looking around for helping clues of _any_
kind.

   Surely, when looking at program sources, the translator will receive
more help if she is a fluent programmer.  However, even if she is not
versed in programming and feels a little lost in C code, the translator
should not be shy at taking a look, once in a while.  It is most
probable that she will still be able to find some of the hints she
needs.  She will learn quickly to not feel uncomfortable in program
code, paying more attention to programmer's comments, variable and
function names (if he dared choosing them well), and overall
organization, than to the program code itself.

   The following commands are meant to help the translator at getting
program source context for a PO file entry.

`s'
     Resume the display of a program source context, or cycle through
     them (`po-cycle-source-reference').

`M-s'
     Display of a program source context selected by menu
     (`po-select-source-reference').

`S'
     Add a directory to the search path for source files
     (`po-consider-source-path').

`M-S'
     Delete a directory from the search path for source files
     (`po-ignore-source-path').

   The commands `s' (`po-cycle-source-reference') and `M-s'
(`po-select-source-reference') both open another window displaying some
source program file, and already positioned in such a way that it shows
an actual use of the string to be translated.  By doing so, the command
gives source program context for the string.  But if the entry has no
source context references, or if all references are unresolved along
the search path for program sources, then the command diagnoses this as
an error.

   Even if `s' (or `M-s') opens a new window, the cursor stays in the
PO file window.  If the translator really wants to get into the program
source window, she ought to do it explicitly, maybe by using command
`O'.

   When `s' is typed for the first time, or for a PO file entry which
is different of the last one used for getting source context, then the
command reacts by giving the first context available for this entry, if
any.  If some context has already been recently displayed for the
current PO file entry, and the translator wandered off to do other
things, typing `s' again will merely resume, in another window, the
context last displayed.  In particular, if the translator moved the
cursor away from the context in the source file, the command will bring
the cursor back to the context.  By using `s' many times in a row, with
no other commands intervening, PO mode will cycle to the next available
contexts for this particular entry, getting back to the first context
once the last has been shown.

   The command `M-s' behaves differently.  Instead of cycling through
references, it lets the translator choose a particular reference among
many, and displays that reference.  It is best used with completion, if
the translator types `<TAB>' immediately after `M-s', in response to
the question, she will be offered a menu of all possible references, as
a reminder of which are the acceptable answers.  This command is useful
only where there are really many contexts available for a single string
to translate.

   Program source files are usually found relative to where the PO file
stands.  As a special provision, when this fails, the file is also
looked for, but relative to the directory immediately above it.  Those
two cases take proper care of most PO files.  However, it might happen
that a PO file has been moved, or is edited in a different place than
its normal location.  When this happens, the translator should tell PO
mode in which directory normally sits the genuine PO file.  Many such
directories may be specified, and all together, they constitute what is
called the "search path" for program sources.  The command `S'
(`po-consider-source-path') is used to interactively enter a new
directory at the front of the search path, and the command `M-S'
(`po-ignore-source-path') is used to select, with completion, one of
the directories she does not want anymore on the search path.


File: gettext.info,  Node: Auxiliary,  Next: Compendium,  Prev: C Sources Context,  Up: Updating

Consulting Auxiliary PO Files
=============================

   PO mode is able to help the knowledgeable translator, being fluent in
many languages, at taking advantage of translations already achieved in
other languages she just happens to know.  It provides these other
language translations as additional context for her own work.  Moreover,
it has features to ease the production of translations for many
languages at once, for translators preferring to work in this way.

   An "auxiliary" PO file is an existing PO file meant for the same
package the translator is working on, but targeted to a different mother
tongue language.  Commands exist for declaring and handling auxiliary
PO files, and also for showing contexts for the entry under work.

   Here are the auxiliary file commands available in PO mode.

`a'
     Seek auxiliary files for another translation for the same entry
     (`po-cycle-auxiliary').

`C-c C-a'
     Switch to a particular auxiliary file (`po-select-auxiliary').

`A'
     Declare this PO file as an auxiliary file
     (`po-consider-as-auxiliary').

`M-A'
     Remove this PO file from the list of auxiliary files
     (`po-ignore-as-auxiliary').

   Command `A' (`po-consider-as-auxiliary') adds the current PO file to
the list of auxiliary files, while command `M-A'
(`po-ignore-as-auxiliary' just removes it.

   The command `a' (`po-cycle-auxiliary') seeks all auxiliary PO files,
round-robin, searching for a translated entry in some other language
having an `msgid' field identical as the one for the current entry.
The found PO file, if any, takes the place of the current PO file in
the display (its window gets on top).  Before doing so, the current PO
file is also made into an auxiliary file, if not already.  So, `a' in
this newly displayed PO file will seek another PO file, and so on, so
repeating `a' will eventually yield back the original PO file.

   The command `C-c C-a' (`po-select-auxiliary') asks the translator
for her choice of a particular auxiliary file, with completion, and
then switches to that selected PO file.  The command also checks if the
selected file has an `msgid' field identical as the one for the current
entry, and if yes, this entry becomes current.  Otherwise, the cursor
of the selected file is left undisturbed.

   For all this to work fully, auxiliary PO files will have to be
normalized, in that way that `msgid' fields should be written _exactly_
the same way.  It is possible to write `msgid' fields in various ways
for representing the same string, different writing would break the
proper behaviour of the auxiliary file commands of PO mode.  This is not
expected to be much a problem in practice, as most existing PO files
have their `msgid' entries written by the same GNU `gettext' tools.

   However, PO files initially created by PO mode itself, while marking
strings in source files, are normalised differently.  So are PO files
resulting of the the `M-x normalize' command.  Until these
discrepancies between PO mode and other GNU `gettext' tools get fully
resolved, the translator should stay aware of normalisation issues.


File: gettext.info,  Node: Compendium,  Prev: Auxiliary,  Up: Updating

Using Translation Compendia
===========================

   A "compendium" is a special PO file containing a set of translations
recurring in many different packages.  The translator can use gettext
tools to build a new compendium, to add entries to her compendium, and
to initialize untranslated entries, or to update already translated
entries, from translations kept in the compendium.

* Menu:

* Creating Compendia::          Merging translations for later use
* Using Compendia::             Using older translations if they fit


File: gettext.info,  Node: Creating Compendia,  Next: Using Compendia,  Prev: Compendium,  Up: Compendium

Creating Compendia
------------------

   Basically every PO file consisting of translated entries only can be
declared as a valid compendium.  Often the translator wants to have
special compendia; let's consider two cases: `concatenating PO files'
and `extracting a message subset from a PO file'.

Concatenate PO Files
....................

   To concatenate several valid PO files into one compendium file you
can use `msgcomm' or `msgcat' (the latter preferred):

     msgcat -o compendium.po file1.po file2.po

   By default, `msgcat' will accumulate divergent translations for the
same string.  Those occurences will be marked as `fuzzy' and highly
visible decorated; calling `msgcat' on `file1.po':

     #: src/hello.c:200
     #, c-format
     msgid "Report bugs to <%s>.\n"
     msgstr "Comunicar `bugs' a <%s>.\n"

and `file2.po':

     #: src/bye.c:100
     #, c-format
     msgid "Report bugs to <%s>.\n"
     msgstr "Comunicar \"bugs\" a <%s>.\n"

will result in:

     #: src/hello.c:200 src/bye.c:100
     #, fuzzy, c-format
     msgid "Report bugs to <%s>.\n"
     msgstr ""
     "#-#-#-#-#  file1.po  #-#-#-#-#\n"
     "Comunicar `bugs' a <%s>.\n"
     "#-#-#-#-#  file2.po  #-#-#-#-#\n"
     "Comunicar \"bugs\" a <%s>.\n"

The translator will have to resolve this "conflict" manually; she has
to decide whether the first or the second version is appropriate (or
provide a new translation), to delete the "marker lines", and finally
to remove the `fuzzy' mark.

   If the translator knows in advance the first found translation of a
message is always the best translation she can make use to the
`--use-first' switch:

     msgcat --use-first -o compendium.po file1.po file2.po

   A good compendium file must not contain `fuzzy' or untranslated
entries.  If input files are "dirty" you must preprocess the input
files or postprocess the result using `msgattrib --translated
--no-fuzzy'.

Extract a Message Subset from a PO File
.......................................

   Nobody wants to translate the same messages again and again; thus you
may wish to have a compendium file containing `getopt.c' messages.

   To extract a message subset (e.g., all `getopt.c' messages) from an
existing PO file into one compendium file you can use `msggrep':

     msggrep --location src/getopt.c -o compendium.po file.po


File: gettext.info,  Node: Using Compendia,  Prev: Creating Compendia,  Up: Compendium

Using Compendia
---------------

   You can use a compendium file to initialize a translation from
scratch or to update an already existing translation.

Initialize a New Translation File
.................................

   Since a PO file with translations does not exist the translator can
merely use `/dev/null' to fake the "old" translation file.

     msgmerge --compendium compendium.po -o file.po /dev/null file.pot

Update an Existing Translation File
...................................

   Concatenate the compendium file(s) and the existing PO, merge the
result with the POT file and remove the obsolete entries (optional,
here done using `sed'):

     msgcat --use-first -o update.po compendium1.po compendium2.po file.po
     msgmerge update.po file.pot | sed -e '/^#~/d' > file.po


File: gettext.info,  Node: Manipulating,  Next: Binaries,  Prev: Updating,  Up: Top

Manipulating PO Files
*********************

   Sometimes it is necessary to manipulate PO files in a way that is
better performed automatically than by hand.  GNU `gettext' includes a
complete set of tools for this purpose.

   When merging two packages into a single package, the resulting POT
file will be the concatenation of the two packages' POT files.  Thus the
maintainer must concatenate the two existing package translations into
a single translation catalog, for each language.  This is best performed
using `msgcat'.  It is then the translators' duty to deal with any
possible conflicts that arose during the merge.

   When a translator takes over the translation job from another
translator, but she uses a different character encoding in her locale,
she will convert the catalog to her character encoding.  This is best
done through the `msgconv' program.

   When a maintainer takes a source file with tagged messages from
another package, he should also take the existing translations for this
source file (and not let the translators do the same job twice).  One
way to do this is through `msggrep', another is to create a POT file for
that source file and use `msgmerge'.

   When a translator wants to adjust some translation catalog for a
special dialect or orthography -- for example, German as written in
Switzerland versus German as written in Germany -- she needs to apply
some text processing to every message in the catalog.  The tool for
doing this is `msgfilter'.

   Another use of `msgfilter' is to produce approximately the POT file
for which a given PO file was made.  This can be done through a filter
command like `msgfilter sed -e d | sed -e '/^# /d''.  Note that the
original POT file may have had different comments and different plural
message counts, that's why it's better to use the original POT file if
available.

   When a translator wants to check her translations, for example
according to orthography rules or using a non-interactive spell
checker, she can do so using the `msgexec' program.

   When third party tools create PO or POT files, sometimes duplicates
cannot be avoided.  But the GNU `gettext' tools give an error when they
encounter duplicate msgids in the same file and in the same domain.  To
merge duplicates, the `msguniq' program can be used.

   `msgcomm' is a more general tool for keeping or throwing away
duplicates, occurring in different files.

   `msgcmp' can be used to check whether a translation catalog is
completely translated.

   `msgattrib' can be used to select and extract only the fuzzy or
untranslated messages of a translation catalog.

   `msgen' is useful as a first step for preparing English translation
catalogs.  It copies each message's msgid to its msgstr.

* Menu:

* msgcat Invocation::           Invoking the `msgcat' Program
* msgconv Invocation::          Invoking the `msgconv' Program
* msggrep Invocation::          Invoking the `msggrep' Program
* msgfilter Invocation::        Invoking the `msgfilter' Program
* msguniq Invocation::          Invoking the `msguniq' Program
* msgcomm Invocation::          Invoking the `msgcomm' Program
* msgcmp Invocation::           Invoking the `msgcmp' Program
* msgattrib Invocation::        Invoking the `msgattrib' Program
* msgen Invocation::            Invoking the `msgen' Program
* msgexec Invocation::          Invoking the `msgexec' Program


File: gettext.info,  Node: msgcat Invocation,  Next: msgconv Invocation,  Prev: Manipulating,  Up: Manipulating

Invoking the `msgcat' Program
=============================

     msgcat [OPTION] [INPUTFILE]...

   The `msgcat' program concatenates and merges the specified PO files.
It finds messages which are common to two or more of the specified PO
files.  By using the `--more-than' option, greater commonality may be
requested before messages are printed.  Conversely, the `--less-than'
option may be used to specify less commonality before messages are
printed (i.e.  `--less-than=2' will only print the unique messages).
Translations, comments and extract comments will be cumulated, except
that if `--use-first' is specified, they will be taken from the first
PO file to define them.  File positions from all PO files will be
cumulated.

Input file location
-------------------

`INPUTFILE ...'
     Input files.

`-f FILE'
`--files-from=FILE'
     Read the names of the input files from FILE instead of getting
     them from the command line.

`-D DIRECTORY'
`--directory=DIRECTORY'
     Add DIRECTORY to the list of directories.  Source files are
     searched relative to this list of directories.  The resulting `.po'
     file will be written relative to the current directory, though.

   If INPUTFILE is `-', standard input is read.

Output file location
--------------------

`-o FILE'
`--output-file=FILE'
     Write output to specified file.

   The results are written to standard output if no output file is
specified or if it is `-'.

Message selection
-----------------

`-< NUMBER'
`--less-than=NUMBER'
     Print messages with less than NUMBER definitions, defaults to
     infinite if not set.

`-> NUMBER'
`--more-than=NUMBER'
     Print messages with more than NUMBER definitions, defaults to 0 if
     not set.

`-u'
`--unique'
     Shorthand for `--less-than=2'.  Requests that only unique messages
     be printed.

Output details
--------------

`-t'
`--to-code=NAME'
     Specify encoding for output.

`--use-first'
     Use first available translation for each message.  Don't merge
     several translations into one.

`--force-po'
     Always write an output file even if it contains no message.

`-i'
`--indent'
     Write the .po file using indented style.

`--no-location'
     Do not write `#: FILENAME:LINE' lines.

`-n'
`--add-location'
     Generate `#: FILENAME:LINE' lines (default).

`--strict'
     Write out a strict Uniforum conforming PO file.  Note that this
     Uniforum format should be avoided because it doesn't support the
     GNU extensions.

`-w NUMBER'
`--width=NUMBER'
     Set the output page width.  Long strings in the output files will
     be split across multiple lines in order to ensure that each line's
     width (= number of screen columns) is less or equal to the given
     NUMBER.

`--no-wrap'
     Do not break long message lines.  Message lines whose width
     exceeds the output page width will not be split into several
     lines.  Only file reference lines which are wider than the output
     page width will be split.

`-s'
`--sort-output'
     Generate sorted output.  Note that using this option makes it much
     harder for the translator to understand each message's context.

`-F'
`--sort-by-file'
     Sort output by file location.

Informative output
------------------

`-h'
`--help'
     Display this help and exit.

`-V'
`--version'
     Output version information and exit.


File: gettext.info,  Node: msgconv Invocation,  Next: msggrep Invocation,  Prev: msgcat Invocation,  Up: Manipulating

Invoking the `msgconv' Program
==============================

     msgconv [OPTION] [INPUTFILE]

   The `msgconv' program converts a translation catalog to a different
character encoding.

Input file location
-------------------

`INPUTFILE'
     Input PO file.

`-D DIRECTORY'
`--directory=DIRECTORY'
     Add DIRECTORY to the list of directories.  Source files are
     searched relative to this list of directories.  The resulting `.po'
     file will be written relative to the current directory, though.

   If no INPUTFILE is given or if it is `-', standard input is read.

Output file location
--------------------

`-o FILE'
`--output-file=FILE'
     Write output to specified file.

   The results are written to standard output if no output file is
specified or if it is `-'.

Conversion target
-----------------

`-t'
`--to-code=NAME'
     Specify encoding for output.

   The default encoding is the current locale's encoding.

Output details
--------------

`--force-po'
     Always write an output file even if it contains no message.

`-i'
`--indent'
     Write the .po file using indented style.

`--no-location'
     Do not write `#: FILENAME:LINE' lines.

`--add-location'
     Generate `#: FILENAME:LINE' lines (default).

`--strict'
     Write out a strict Uniforum conforming PO file.  Note that this
     Uniforum format should be avoided because it doesn't support the
     GNU extensions.

`-w NUMBER'
`--width=NUMBER'
     Set the output page width.  Long strings in the output files will
     be split across multiple lines in order to ensure that each line's
     width (= number of screen columns) is less or equal to the given
     NUMBER.

`--no-wrap'
     Do not break long message lines.  Message lines whose width
     exceeds the output page width will not be split into several
     lines.  Only file reference lines which are wider than the output
     page width will be split.

`-s'
`--sort-output'
     Generate sorted output.  Note that using this option makes it much
     harder for the translator to understand each message's context.

`-F'
`--sort-by-file'
     Sort output by file location.

Informative output
------------------

`-h'
`--help'
     Display this help and exit.

`-V'
`--version'
     Output version information and exit.


File: gettext.info,  Node: msggrep Invocation,  Next: msgfilter Invocation,  Prev: msgconv Invocation,  Up: Manipulating

Invoking the `msggrep' Program
==============================

     msggrep [OPTION] [INPUTFILE]

   The `msggrep' program extracts all messages of a translation catalog
that match a given pattern or belong to some given source files.

Input file location
-------------------

`INPUTFILE'
     Input PO file.

`-D DIRECTORY'
`--directory=DIRECTORY'
     Add DIRECTORY to the list of directories.  Source files are
     searched relative to this list of directories.  The resulting `.po'
     file will be written relative to the current directory, though.

   If no INPUTFILE is given or if it is `-', standard input is read.

Output file location
--------------------

`-o FILE'
`--output-file=FILE'
     Write output to specified file.

   The results are written to standard output if no output file is
specified or if it is `-'.

Message selection
-----------------

       [-N SOURCEFILE]... [-M DOMAINNAME]...
       [-K MSGID-PATTERN] [-T MSGSTR-PATTERN] [-C COMMENT-PATTERN]

   A message is selected if
   * it comes from one of the specified source files,

   * or if it comes from one of the specified domains,

   * or if `-K' is given and its key (msgid or msgid_plural) matches
       MSGID-PATTERN,

   * or if `-T' is given and its translation (msgstr) matches
     MSGSTR-PATTERN,

   * or if `-C' is given and the translator's comment matches
     COMMENT-PATTERN.

   When more than one selection criterion is specified, the set of
selected messages is the union of the selected messages of each
criterion.

   MSGID-PATTERN or MSGSTR-PATTERN syntax:
       [-E | -F] [-e PATTERN | -f FILE]...
   PATTERNs are basic regular expressions by default, or extended
regular expressions if -E is given, or fixed strings if -F is given.

`-N SOURCEFILE'
`--location=SOURCEFILE'
     Select messages extracted from SOURCEFILE.  SOURCEFILE can be
     either a literal file name or a wildcard pattern.

`-M DOMAINNAME'
`--domain=DOMAINNAME'
     Select messages belonging to domain DOMAINNAME.

`-K'
`--msgid'
     Start of patterns for the msgid.

`-T'
`--msgstr'
     Start of patterns for the msgstr.

`-E'
`--extended-regexp'
     Specify that PATTERN is an extended regular expression.

`-F'
`--fixed-strings'
     Specify that PATTERN is a set of newline-separated strings.

`-e PATTERN'
`--regexp=PATTERN'
     Use PATTERN as a regular expression.

`-f FILE'
`--file=FILE'
     Obtain PATTERN from FILE.

`-i'
`--ignore-case'
     Ignore case distinctions.

Output details
--------------

`--force-po'
     Always write an output file even if it contains no message.

`--indent'
     Write the .po file using indented style.

`--no-location'
     Do not write `#: FILENAME:LINE' lines.

`--add-location'
     Generate `#: FILENAME:LINE' lines (default).

`--strict'
     Write out a strict Uniforum conforming PO file.  Note that this
     Uniforum format should be avoided because it doesn't support the
     GNU extensions.

`-w NUMBER'
`--width=NUMBER'
     Set the output page width.  Long strings in the output files will
     be split across multiple lines in order to ensure that each line's
     width (= number of screen columns) is less or equal to the given
     NUMBER.

`--no-wrap'
     Do not break long message lines.  Message lines whose width
     exceeds the output page width will not be split into several
     lines.  Only file reference lines which are wider than the output
     page width will be split.

`--sort-output'
     Generate sorted output.  Note that using this option makes it much
     harder for the translator to understand each message's context.

`--sort-by-file'
     Sort output by file location.

Informative output
------------------

`-h'
`--help'
     Display this help and exit.

`-V'
`--version'
     Output version information and exit.


File: gettext.info,  Node: msgfilter Invocation,  Next: msguniq Invocation,  Prev: msggrep Invocation,  Up: Manipulating

Invoking the `msgfilter' Program
================================

     msgfilter [OPTION] FILTER [FILTER-OPTION]

   The `msgfilter' program applies a filter to all translations of a
translation catalog.

Input file location
-------------------

`-i INPUTFILE'
`--input=INPUTFILE'
     Input PO file.

`-D DIRECTORY'
`--directory=DIRECTORY'
     Add DIRECTORY to the list of directories.  Source files are
     searched relative to this list of directories.  The resulting `.po'
     file will be written relative to the current directory, though.

   If no INPUTFILE is given or if it is `-', standard input is read.

Output file location
--------------------

`-o FILE'
`--output-file=FILE'
     Write output to specified file.

   The results are written to standard output if no output file is
specified or if it is `-'.

The filter
----------

   The FILTER can be any program that reads a translation from standard
input and writes a modified translation to standard output.  A
frequently used filter is `sed'.

   Note: It is your responsibility to ensure that the FILTER can cope
with input encoded in the translation catalog's encoding.  If the
FILTER wants input in a particular encoding, you can in a first step
convert the translation catalog to that encoding using the `msgconv'
program, before invoking `msgfilter'.  If the FILTER wants input in the
locale's encoding, but you want to avoid the locale's encoding, then
you can first convert the translation catalog to UTF-8 using the
`msgconv' program and then make `msgfilter' work in an UTF-8 locale, by
using the `LC_ALL' environment variable.

   Note: Most translations in a translation catalog don't end with a
newline character. For this reason, it is important that the FILTER
recognizes its last input line even if it ends without a newline, and
that it doesn't add an undesired trailing newline at the end. The `sed'
program on some platforms is known to ignore the last line of input if
it is not terminated with a newline. You can use GNU `sed' instead; it
does not have this limitation.

Useful FILTER-OPTIONs when the FILTER is `sed'
----------------------------------------------

`-e SCRIPT'
`--expression=SCRIPT'
     Add SCRIPT to the commands to be executed.

`-f SCRIPTFILE'
`--file=SCRIPTFILE'
     Add the contents of SCRIPTFILE to the commands to be executed.

`-n'
`--quiet'
`--silent'
     Suppress automatic printing of pattern space.

Output details
--------------

`--force-po'
     Always write an output file even if it contains no message.

`--indent'
     Write the .po file using indented style.

`--keep-header'
     Keep the header entry, i.e. the message with `msgid ""',
     unmodified, instead of filtering it.  By default, the header entry
     is subject to filtering like any other message.

`--no-location'
     Do not write `#: FILENAME:LINE' lines.

`--add-location'
     Generate `#: FILENAME:LINE' lines (default).

`--strict'
     Write out a strict Uniforum conforming PO file.  Note that this
     Uniforum format should be avoided because it doesn't support the
     GNU extensions.

`-w NUMBER'
`--width=NUMBER'
     Set the output page width.  Long strings in the output files will
     be split across multiple lines in order to ensure that each line's
     width (= number of screen columns) is less or equal to the given
     NUMBER.

`--no-wrap'
     Do not break long message lines.  Message lines whose width
     exceeds the output page width will not be split into several
     lines.  Only file reference lines which are wider than the output
     page width will be split.

`-s'
`--sort-output'
     Generate sorted output.  Note that using this option makes it much
     harder for the translator to understand each message's context.

`-F'
`--sort-by-file'
     Sort output by file location.

Informative output
------------------

`-h'
`--help'
     Display this help and exit.

`-V'
`--version'
     Output version information and exit.


File: gettext.info,  Node: msguniq Invocation,  Next: msgcomm Invocation,  Prev: msgfilter Invocation,  Up: Manipulating

Invoking the `msguniq' Program
==============================

     msguniq [OPTION] [INPUTFILE]

   The `msguniq' program unifies duplicate translations in a translation
catalog.  It finds duplicate translations of the same message ID.  Such
duplicates are invalid input for other programs like `msgfmt',
`msgmerge' or `msgcat'.  By default, duplicates are merged together.
When using the `--repeated' option, only duplicates are output, and all
other messages are discarded.  Comments and extracted comments will be
cumulated, except that if `--use-first' is specified, they will be
taken from the first translation.  File positions will be cumulated.
When using the `--unique' option, duplicates are discarded.

Input file location
-------------------

`INPUTFILE'
     Input PO file.

`-D DIRECTORY'
`--directory=DIRECTORY'
     Add DIRECTORY to the list of directories.  Source files are
     searched relative to this list of directories.  The resulting `.po'
     file will be written relative to the current directory, though.

   If no INPUTFILE is given or if it is `-', standard input is read.

Output file location
--------------------

`-o FILE'
`--output-file=FILE'
     Write output to specified file.

   The results are written to standard output if no output file is
specified or if it is `-'.

Message selection
-----------------

`-d'
`--repeated'
     Print only duplicates.

`-u'
`--unique'
     Print only unique messages, discard duplicates.

Output details
--------------

`-t'
`--to-code=NAME'
     Specify encoding for output.

`--use-first'
     Use first available translation for each message.  Don't merge
     several translations into one.

`--force-po'
     Always write an output file even if it contains no message.

`-i'
`--indent'
     Write the .po file using indented style.

`--no-location'
     Do not write `#: FILENAME:LINE' lines.

`-n'
`--add-location'
     Generate `#: FILENAME:LINE' lines (default).

`--strict'
     Write out a strict Uniforum conforming PO file.  Note that this
     Uniforum format should be avoided because it doesn't support the
     GNU extensions.

`-w NUMBER'
`--width=NUMBER'
     Set the output page width.  Long strings in the output files will
     be split across multiple lines in order to ensure that each line's
     width (= number of screen columns) is less or equal to the given
     NUMBER.

`--no-wrap'
     Do not break long message lines.  Message lines whose width
     exceeds the output page width will not be split into several
     lines.  Only file reference lines which are wider than the output
     page width will be split.

`-s'
`--sort-output'
     Generate sorted output.  Note that using this option makes it much
     harder for the translator to understand each message's context.

`-F'
`--sort-by-file'
     Sort output by file location.

Informative output
------------------

`-h'
`--help'
     Display this help and exit.

`-V'
`--version'
     Output version information and exit.


File: gettext.info,  Node: msgcomm Invocation,  Next: msgcmp Invocation,  Prev: msguniq Invocation,  Up: Manipulating

Invoking the `msgcomm' Program
==============================

     msgcomm [OPTION] [INPUTFILE]...

   The `msgcomm' program finds messages which are common to two or more
of the specified PO files.  By using the `--more-than' option, greater
commonality may be requested before messages are printed.  Conversely,
the `--less-than' option may be used to specify less commonality before
messages are printed (i.e.  `--less-than=2' will only print the unique
messages).  Translations, comments and extract comments will be
preserved, but only from the first PO file to define them.  File
positions from all PO files will be cumulated.

Input file location
-------------------

`INPUTFILE ...'
     Input files.

`-f FILE'
`--files-from=FILE'
     Read the names of the input files from FILE instead of getting
     them from the command line.

`-D DIRECTORY'
`--directory=DIRECTORY'
     Add DIRECTORY to the list of directories.  Source files are
     searched relative to this list of directories.  The resulting `.po'
     file will be written relative to the current directory, though.

   If INPUTFILE is `-', standard input is read.

Output file location
--------------------

`-o FILE'
`--output-file=FILE'
     Write output to specified file.

   The results are written to standard output if no output file is
specified or if it is `-'.

Message selection
-----------------

`-< NUMBER'
`--less-than=NUMBER'
     Print messages with less than NUMBER definitions, defaults to
     infinite if not set.

`-> NUMBER'
`--more-than=NUMBER'
     Print messages with more than NUMBER definitions, defaults to 1 if
     not set.

`-u'
`--unique'
     Shorthand for `--less-than=2'.  Requests that only unique messages
     be printed.

Output details
--------------

`--force-po'
     Always write an output file even if it contains no message.

`-i'
`--indent'
     Write the .po file using indented style.

`--no-location'
     Do not write `#: FILENAME:LINE' lines.

`-n'
`--add-location'
     Generate `#: FILENAME:LINE' lines (default).

`--strict'
     Write out a strict Uniforum conforming PO file.  Note that this
     Uniforum format should be avoided because it doesn't support the
     GNU extensions.

`-w NUMBER'
`--width=NUMBER'
     Set the output page width.  Long strings in the output files will
     be split across multiple lines in order to ensure that each line's
     width (= number of screen columns) is less or equal to the given
     NUMBER.

`--no-wrap'
     Do not break long message lines.  Message lines whose width
     exceeds the output page width will not be split into several
     lines.  Only file reference lines which are wider than the output
     page width will be split.

`-s'
`--sort-output'
     Generate sorted output.  Note that using this option makes it much
     harder for the translator to understand each message's context.

`-F'
`--sort-by-file'
     Sort output by file location.

`--omit-header'
     Don't write header with `msgid ""' entry.

Informative output
------------------

`-h'
`--help'
     Display this help and exit.

`-V'
`--version'
     Output version information and exit.


File: gettext.info,  Node: msgcmp Invocation,  Next: msgattrib Invocation,  Prev: msgcomm Invocation,  Up: Manipulating

Invoking the `msgcmp' Program
=============================

     msgcmp [OPTION] DEF.po REF.pot

   The `msgcmp' program compares two Uniforum style .po files to check
that both contain the same set of msgid strings.  The DEF.po file is an
existing PO file with the translations.  The REF.pot file is the last
created PO file, or a PO Template file (generally created by
`xgettext').  This is useful for checking that you have translated each
and every message in your program.  Where an exact match cannot be
found, fuzzy matching is used to produce better diagnostics.

Input file location
-------------------

`DEF.po'
     Translations.

`REF.pot'
     References to the sources.

`-D DIRECTORY'
`--directory=DIRECTORY'
     Add DIRECTORY to the list of directories.  Source files are
     searched relative to this list of directories.

Operation modifiers
-------------------

`-m'
`--multi-domain'
     Apply REF.pot to each of the domains in DEF.po.

Informative output
------------------

`-h'
`--help'
     Display this help and exit.

`-V'
`--version'
     Output version information and exit.


File: gettext.info,  Node: msgattrib Invocation,  Next: msgen Invocation,  Prev: msgcmp Invocation,  Up: Manipulating

Invoking the `msgattrib' Program
================================

     msgattrib [OPTION] [INPUTFILE]

   The `msgattrib' program filters the messages of a translation catalog
according to their attributes, and manipulates the attributes.

Input file location
-------------------

`INPUTFILE'
     Input PO file.

`-D DIRECTORY'
`--directory=DIRECTORY'
     Add DIRECTORY to the list of directories.  Source files are
     searched relative to this list of directories.  The resulting `.po'
     file will be written relative to the current directory, though.

   If no INPUTFILE is given or if it is `-', standard input is read.

Output file location
--------------------

`-o FILE'
`--output-file=FILE'
     Write output to specified file.

   The results are written to standard output if no output file is
specified or if it is `-'.

Message selection
-----------------

`--translated'
     Keep translated messages, remove untranslated messages.

`--untranslated'
     Keep untranslated messages, remove translated messages.

`--no-fuzzy'
     Remove `fuzzy' marked messages.

`--only-fuzzy'
     Keep `fuzzy' marked messages, remove all other messsages.

`--no-obsolete'
     Remove obsolete #~ messages.

`--only-obsolete'
     Keep obsolete #~ messages, remove all other messages.

Attribute manipulation
----------------------

   Attributes are modified after the message selection/removal has been
performed.

`--set-fuzzy'
     Set all messages `fuzzy'.

`--clear-fuzzy'
     Set all messages non-`fuzzy'.

`--set-obsolete'
     Set all messages obsolete.

`--clear-obsolete'
     Set all messages non-obsolete.

`--fuzzy'
     Synonym for `--only-fuzzy --clear-fuzzy': It keeps only the fuzzy
     messages and removes their `fuzzy' mark.

`--obsolete'
     Synonym for `--only-obsolete --clear-obsolete': It keeps only the
     obsolete messages and makes them non-obsolete.

Output details
--------------

`--force-po'
     Always write an output file even if it contains no message.

`-i'
`--indent'
     Write the .po file using indented style.

`--no-location'
     Do not write `#: FILENAME:LINE' lines.

`-n'
`--add-location'
     Generate `#: FILENAME:LINE' lines (default).

`--strict'
     Write out a strict Uniforum conforming PO file.  Note that this
     Uniforum format should be avoided because it doesn't support the
     GNU extensions.

`-w NUMBER'
`--width=NUMBER'
     Set the output page width.  Long strings in the output files will
     be split across multiple lines in order to ensure that each line's
     width (= number of screen columns) is less or equal to the given
     NUMBER.

`--no-wrap'
     Do not break long message lines.  Message lines whose width
     exceeds the output page width will not be split into several
     lines.  Only file reference lines which are wider than the output
     page width will be split.

`-s'
`--sort-output'
     Generate sorted output.  Note that using this option makes it much
     harder for the translator to understand each message's context.

`-F'
`--sort-by-file'
     Sort output by file location.

Informative output
------------------

`-h'
`--help'
     Display this help and exit.

`-V'
`--version'
     Output version information and exit.


File: gettext.info,  Node: msgen Invocation,  Next: msgexec Invocation,  Prev: msgattrib Invocation,  Up: Manipulating

Invoking the `msgen' Program
============================

     msgen [OPTION] INPUTFILE

   The `msgen' program creates an English translation catalog.  The
input file is the last created English PO file, or a PO Template file
(generally created by xgettext).  Untranslated entries are assigned a
translation that is identical to the msgid, and are marked fuzzy.

   Note: `msginit --no-translator --locale=en' performs a very similar
task. The main difference is that `msginit' cares specially about the
header entry, whereas `msgen' doesn't.

Input file location
-------------------

`INPUTFILE'
     Input PO or POT file.

`-D DIRECTORY'
`--directory=DIRECTORY'
     Add DIRECTORY to the list of directories.  Source files are
     searched relative to this list of directories.  The resulting `.po'
     file will be written relative to the current directory, though.

   If INPUTFILE is `-', standard input is read.

Output file location
--------------------

`-o FILE'
`--output-file=FILE'
     Write output to specified file.

   The results are written to standard output if no output file is
specified or if it is `-'.

Output details
--------------

`--force-po'
     Always write an output file even if it contains no message.

`-i'
`--indent'
     Write the .po file using indented style.

`--no-location'
     Do not write `#: FILENAME:LINE' lines.

`--add-location'
     Generate `#: FILENAME:LINE' lines (default).

`--strict'
     Write out a strict Uniforum conforming PO file.  Note that this
     Uniforum format should be avoided because it doesn't support the
     GNU extensions.

`-w NUMBER'
`--width=NUMBER'
     Set the output page width.  Long strings in the output files will
     be split across multiple lines in order to ensure that each line's
     width (= number of screen columns) is less or equal to the given
     NUMBER.

`--no-wrap'
     Do not break long message lines.  Message lines whose width
     exceeds the output page width will not be split into several
     lines.  Only file reference lines which are wider than the output
     page width will be split.

`-s'
`--sort-output'
     Generate sorted output.  Note that using this option makes it much
     harder for the translator to understand each message's context.

`-F'
`--sort-by-file'
     Sort output by file location.

Informative output
------------------

`-h'
`--help'
     Display this help and exit.

`-V'
`--version'
     Output version information and exit.


File: gettext.info,  Node: msgexec Invocation,  Prev: msgen Invocation,  Up: Manipulating

Invoking the `msgexec' Program
==============================

     msgexec [OPTION] COMMAND [COMMAND-OPTION]

   The `msgexec' program applies a command to all translations of a
translation catalog.  The COMMAND can be any program that reads a
translation from standard input.  It is invoked once for each
translation.  Its output becomes msgexec's output.  `msgexec''s return
code is the maximum return code across all invocations.

   A special builtin command called `0' outputs the translation,
followed by a null byte.  The output of `msgexec 0' is suitable as
input for `xargs -0'.

   During each COMMAND invocation, the environment variable
`MSGEXEC_MSGID' is bound to the message's msgid, and the environment
variable `MSGEXEC_LOCATION' is bound to the location in the PO file of
the message.

   Note: It is your responsibility to ensure that the COMMAND can cope
with input encoded in the translation catalog's encoding.  If the
COMMAND wants input in a particular encoding, you can in a first step
convert the translation catalog to that encoding using the `msgconv'
program, before invoking `msgexec'.  If the COMMAND wants input in the
locale's encoding, but you want to avoid the locale's encoding, then
you can first convert the translation catalog to UTF-8 using the
`msgconv' program and then make `msgexec' work in an UTF-8 locale, by
using the `LC_ALL' environment variable.

Input file location
-------------------

`-i INPUTFILE'
`--input=INPUTFILE'
     Input PO file.

`-D DIRECTORY'
`--directory=DIRECTORY'
     Add DIRECTORY to the list of directories.  Source files are
     searched relative to this list of directories.  The resulting `.po'
     file will be written relative to the current directory, though.

   If no INPUTFILE is given or if it is `-', standard input is read.

Informative output
------------------

`-h'
`--help'
     Display this help and exit.

`-V'
`--version'
     Output version information and exit.


File: gettext.info,  Node: Binaries,  Next: Users,  Prev: Manipulating,  Up: Top

Producing Binary MO Files
*************************

* Menu:

* msgfmt Invocation::           Invoking the `msgfmt' Program
* msgunfmt Invocation::         Invoking the `msgunfmt' Program
* MO Files::                    The Format of GNU MO Files