Dies ist gettext.info, hergestellt von Makeinfo Version 4.3 aus
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-1998, 2001-2003 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: libgettextpo, Prev: msgexec Invocation, Up: Manipulating
Writing your own programs that process PO files
===============================================
For the tasks for which a combination of `msgattrib', `msgcat' etc.
is not sufficient, a set of C functions is provided in a library, to
make it possible to process PO files in your own programs. When you
use this library, you don't need to write routines to parse the PO
file; instead, you retreive a pointer in memory to each of messages
contained in the PO file. Functions for writing PO files are not
provided at this time.
The functions are declared in the header file `<gettext-po.h>', and
are defined in a library called `libgettextpo'.
- Data Type: po_file_t
This is a pointer type that refers to the contents of a PO file,
after it has been read into memory.
- Data Type: po_message_iterator_t
This is a pointer type that refers to an iterator that produces a
sequence of messages.
- Data Type: po_message_t
This is a pointer type that refers to a message of a PO file,
including its translation.
- Funktion: po_file_t po_file_read (const char *FILENAME)
The `po_file_read' function reads a PO file into memory. The file
name is given as argument. The return value is a handle to the PO
file's contents, valid until `po_file_free' is called on it. In
case of error, the return value is `NULL', and `errno' is set.
- Funktion: void po_file_free (po_file_t FILE)
The `po_file_free' function frees a PO file's contents from memory,
including all messages that are only implicitly accessible through
iterators.
- Funktion: const char * const * po_file_domains (po_file_t FILE)
The `po_file_domains' function returns the domains for which the
given PO file has messages. The return value is a `NULL'
terminated array which is valid as long as the FILE handle is
valid. For PO files which contain no `domain' directive, the
return value contains only one domain, namely the default domain
`"messages"'.
- Funktion: po_message_iterator_t po_message_iterator (po_file_t FILE,
const char *DOMAIN)
The `po_message_iterator' returns an iterator that will produce the
messages of FILE that belong to the given DOMAIN. If DOMAIN is
`NULL', the default domain is used instead. To list the messages,
use the function `po_next_message' repeatedly.
- Funktion: void po_message_iterator_free (po_message_iterator_t
ITERATOR)
The `po_message_iterator_free' function frees an iterator
previously allocated through the `po_message_iterator' function.
- Funktion: po_message_t po_next_message (po_message_iterator_t
ITERATOR)
The `po_next_message' function returns the next message from
ITERATOR and advances the iterator. It returns `NULL' when the
iterator has reached the end of its message list.
The following functions returns details of a `po_message_t'. Recall
that the results are valid as long as the FILE handle is valid.
- Funktion: const char * po_message_msgid (po_message_t MESSAGE)
The `po_message_msgid' function returns the `msgid' (untranslated
English string) of a message. This is guaranteed to be non-`NULL'.
- Funktion: const char * po_message_msgid_plural (po_message_t MESSAGE)
The `po_message_msgid_plural' function returns the `msgid_plural'
(untranslated English plural string) of a message with plurals, or
`NULL' for a message without plural.
- Funktion: const char * po_message_msgstr (po_message_t MESSAGE)
The `po_message_msgstr' function returns the `msgstr' (translation)
of a message. For an untranslated message, the return value is an
empty string.
- Funktion: const char * po_message_msgstr_plural (po_message_t
MESSAGE, int INDEX)
The `po_message_msgstr_plural' function returns the
`msgstr[INDEX]' of a message with plurals, or `NULL' when the
INDEX is out of range or for a message without plural.
Here is an example code how these functions can be used.
const char *filename = ...;
po_file_t file = po_file_read (filename);
if (file == NULL)
error (EXIT_FAILURE, errno, "couldn't open the PO file %s", filename);
{
const char * const *domains = po_file_domains (file);
const char * const *domainp;
for (domainp = domains; *domainp; domainp++)
{
const char *domain = *domainp;
po_message_iterator_t iterator = po_message_iterator (file, domain);
for (;;)
{
po_message_t *message = po_next_message (iterator);
if (message == NULL)
break;
{
const char *msgid = po_message_msgid (message);
const char *msgstr = po_message_msgstr (message);
...
}
}
po_message_iterator_free (iterator);
}
}
po_file_free (file);
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
File: gettext.info, Node: msgfmt Invocation, Next: msgunfmt Invocation, Prev: Binaries, Up: Binaries
Invoking the `msgfmt' Program
=============================
msgfmt [OPTION] FILENAME.po ...
The `msgfmt' programs generates a binary message catalog from a
textual translation description.
Input file location
-------------------
`FILENAME.po ...'
`-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 an input file is `-', standard input is read.
Operation mode
--------------
`-j'
`--java'
Java mode: generate a Java `ResourceBundle' class.
`--java2'
Like -java, and assume Java2 (JDK 1.2 or higher).
`--tcl'
Tcl mode: generate a tcl/msgcat `.msg' file.
Output file location
--------------------
`-o FILE'
`--output-file=FILE'
Write output to specified file.
`--strict'
Direct the program to work strictly following the Uniforum/Sun
implementation. Currently this only affects the naming of the
output file. If this option is not given the name of the output
file is the same as the domain name. If the strict Uniforum mode
is enabled the suffix `.mo' is added to the file name if it is not
already present.
We find this behaviour of Sun's implementation rather silly and so
by default this mode is _not_ selected.
If the output FILE is `-', output is written to standard output.
Output file location in Java mode
---------------------------------
`-r RESOURCE'
`--resource=RESOURCE'
Specify the resource name.
`-l LOCALE'
`--locale=LOCALE'
Specify the locale name, either a language specification of the
form LL or a combined language and country specification of the
form LL_CC.
`-d DIRECTORY'
Specify the base directory of classes directory hierarchy.
The class name is determined by appending the locale name to the
resource name, separated with an underscore. The `-d' option is
mandatory. The class is written under the specified directory.
Output file location in Tcl mode
--------------------------------
`-l LOCALE'
`--locale=LOCALE'
Specify the locale name, either a language specification of the
form LL or a combined language and country specification of the
form LL_CC.
`-d DIRECTORY'
Specify the base directory of `.msg' message catalogs.
The `-l' and `-d' options are mandatory. The `.msg' file is written
in the specified directory.
Input file syntax
-----------------
`-P'
`--properties-input'
Assume the input files are Java ResourceBundles in Java
`.properties' syntax, not in PO file syntax.
Input file interpretation
-------------------------
`-c'
`--check'
Perform all the checks implied by `--check-format',
`--check-header', `--check-domain'.
`--check-format'
Check language dependent format strings.
If the string represents a format string used in a `printf'-like
function both strings should have the same number of `%' format
specifiers, with matching types. If the flag `c-format' or
`possible-c-format' appears in the special comment <#,> for this
entry a check is performed. For example, the check will diagnose
using `%.*s' against `%s', or `%d' against `%s', or `%d' against
`%x'. It can even handle positional parameters.
Normally the `xgettext' program automatically decides whether a
string is a format string or not. This algorithm is not perfect,
though. It might regard a string as a format string though it is
not used in a `printf'-like function and so `msgfmt' might report
errors where there are none.
To solve this problem the programmer can dictate the decision to
the `xgettext' program (*note c-format::). The translator should
not consider removing the flag from the <#,> line. This "fix"
would be reversed again as soon as `msgmerge' is called the next
time.
`--check-header'
Verify presence and contents of the header entry. *Note Header
Entry::, for a description of the various fields in the header
entry.
`--check-domain'
Check for conflicts between domain directives and the
`--output-file' option
`-C'
`--check-compatibility'
Check that GNU msgfmt behaves like X/Open msgfmt. This will give
an error when attempting to use the GNU extensions.
`--check-accelerators[=CHAR]'
Check presence of keyboard accelerators for menu items. This is
based on the convention used in some GUIs that a keyboard
accelerator in a menu item string is designated by an immediately
preceding `&' character. Sometimes a keyboard accelerator is also
called "keyboard mnemonic". This check verifies that if the
untranslated string has exactly one `&' character, the translated
string has exactly one `&' as well. If this option is given with
a CHAR argument, this CHAR should be a non-alphanumeric character
and is used as keyboard acceleator mark instead of `&'.
`-f'
`--use-fuzzy'
Use fuzzy entries in output. Note that using this option is
usually wrong, because fuzzy messages are exactly those which have
not been validated by a human translator.
Output details
--------------
`-a NUMBER'
`--alignment=NUMBER'
Align strings to NUMBER bytes (default: 1).
`--no-hash'
Don't include a hash table in the binary file. Lookup will be
more expensive at run time (binary search instead of hash table
lookup).
Informative output
------------------
`-h'
`--help'
Display this help and exit.
`-V'
`--version'
Output version information and exit.
`--statistics'
Print statistics about translations.
`-v'
`--verbose'
Increase verbosity level.
File: gettext.info, Node: msgunfmt Invocation, Next: MO Files, Prev: msgfmt Invocation, Up: Binaries
Invoking the `msgunfmt' Program
===============================
msgunfmt [OPTION] [FILE]...
The `msgunfmt' program converts a binary message catalog to a
Uniforum style .po file.
Operation mode
--------------
`-j'
`--java'
Java mode: input is a Java `ResourceBundle' class.
`--tcl'
Tcl mode: input is a tcl/msgcat `.msg' file.
Input file location
-------------------
`FILE ...'
Input .mo files.
If no input FILE is given or if it is `-', standard input is read.
Input file location in Java mode
--------------------------------
`-r RESOURCE'
`--resource=RESOURCE'
Specify the resource name.
`-l LOCALE'
`--locale=LOCALE'
Specify the locale name, either a language specification of the
form LL or a combined language and country specification of the
form LL_CC.
The class name is determined by appending the locale name to the
resource name, separated with an underscore. The class is located
using the `CLASSPATH'.
Input file location in Tcl mode
-------------------------------
`-l LOCALE'
`--locale=LOCALE'
Specify the locale name, either a language specification of the
form LL or a combined language and country specification of the
form LL_CC.
`-d DIRECTORY'
Specify the base directory of `.msg' message catalogs.
The `-l' and `-d' options are mandatory. The `.msg' file is located
in the specified directory.
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.
`--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.
`-p'
`--properties-output'
Write out a Java ResourceBundle in Java `.properties' syntax. Note
that this file format doesn't support plural forms and silently
drops obsolete messages.
`-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.
Informative output
------------------
`-h'
`--help'
Display this help and exit.
`-V'
`--version'
Output version information and exit.
`-v'
`--verbose'
Increase verbosity level.
File: gettext.info, Node: MO Files, Prev: msgunfmt Invocation, Up: Binaries
The Format of GNU MO Files
==========================
The format of the generated MO files is best described by a picture,
which appears below.
The first two words serve the identification of the file. The magic
number will always signal GNU MO files. The number is stored in the
byte order of the generating machine, so the magic number really is two
numbers: `0x950412de' and `0xde120495'. The second word describes the
current revision of the file format. For now the revision is 0. This
might change in future versions, and ensures that the readers of MO
files can distinguish new formats from old ones, so that both can be
handled correctly. The version is kept separate from the magic number,
instead of using different magic numbers for different formats, mainly
because `/etc/magic' is not updated often. It might be better to have
magic separated from internal format version identification.
Follow a number of pointers to later tables in the file, allowing
for the extension of the prefix part of MO files without having to
recompile programs reading them. This might become useful for later
inserting a few flag bits, indication about the charset used, new
tables, or other things.
Then, at offset O and offset T in the picture, two tables of string
descriptors can be found. In both tables, each string descriptor uses
two 32 bits integers, one for the string length, another for the offset
of the string in the MO file, counting in bytes from the start of the
file. The first table contains descriptors for the original strings,
and is sorted so the original strings are in increasing lexicographical
order. The second table contains descriptors for the translated
strings, and is parallel to the first table: to find the corresponding
translation one has to access the array slot in the second array with
the same index.
Having the original strings sorted enables the use of simple binary
search, for when the MO file does not contain an hashing table, or for
when it is not practical to use the hashing table provided in the MO
file. This also has another advantage, as the empty string in a PO
file GNU `gettext' is usually _translated_ into some system information
attached to that particular MO file, and the empty string necessarily
becomes the first in both the original and translated tables, making
the system information very easy to find.
The size S of the hash table can be zero. In this case, the hash
table itself is not contained in the MO file. Some people might prefer
this because a precomputed hashing table takes disk space, and does not
win _that_ much speed. The hash table contains indices to the sorted
array of strings in the MO file. Conflict resolution is done by double
hashing. The precise hashing algorithm used is fairly dependent on GNU
`gettext' code, and is not documented here.
As for the strings themselves, they follow the hash file, and each
is terminated with a <NUL>, and this <NUL> is not counted in the length
which appears in the string descriptor. The `msgfmt' program has an
option selecting the alignment for MO file strings. With this option,
each string is separately aligned so it starts at an offset which is a
multiple of the alignment value. On some RISC machines, a correct
alignment will speed things up.
Plural forms are stored by letting the plural of the original string
follow the singular of the original string, separated through a <NUL>
byte. The length which appears in the string descriptor includes both.
However, only the singular of the original string takes part in the
hash table lookup. The plural variants of the translation are all
stored consecutively, separated through a <NUL> byte. Here also, the
length in the string descriptor includes all of them.
Nothing prevents a MO file from having embedded <NUL>s in strings.
However, the program interface currently used already presumes that
strings are <NUL> terminated, so embedded <NUL>s are somewhat useless.
But the MO file format is general enough so other interfaces would be
later possible, if for example, we ever want to implement wide
characters right in MO files, where <NUL> bytes may accidently appear.
(No, we don't want to have wide characters in MO files. They would
make the file unnecessarily large, and the `wchar_t' type being
platform dependent, MO files would be platform dependent as well.)
This particular issue has been strongly debated in the GNU `gettext'
development forum, and it is expectable that MO file format will evolve
or change over time. It is even possible that many formats may later
be supported concurrently. But surely, we have to start somewhere, and
the MO file format described here is a good start. Nothing is cast in
concrete, and the format may later evolve fairly easily, so we should
feel comfortable with the current approach.
byte
+------------------------------------------+
0 | magic number = 0x950412de |
| |
4 | file format revision = 0 |
| |
8 | number of strings | == N
| |
12 | offset of table with original strings | == O
| |
16 | offset of table with translation strings | == T
| |
20 | size of hashing table | == S
| |
24 | offset of hashing table | == H
| |
. .
. (possibly more entries later) .
. .
| |
O | length & offset 0th string ----------------.
O + 8 | length & offset 1st string ------------------.
... ... | |
O + ((N-1)*8)| length & offset (N-1)th string | | |
| | | |
T | length & offset 0th translation ---------------.
T + 8 | length & offset 1st translation -----------------.
... ... | | | |
T + ((N-1)*8)| length & offset (N-1)th translation | | | | |
| | | | | |
H | start hash table | | | | |
... ... | | | |
H + S * 4 | end hash table | | | | |
| | | | | |
| NUL terminated 0th string <----------------' | | |
| | | | |
| NUL terminated 1st string <------------------' | |
| | | |
... ... | |
| | | |
| NUL terminated 0th translation <---------------' |
| | |
| NUL terminated 1st translation <-----------------'
| |
... ...
| |
+------------------------------------------+
File: gettext.info, Node: Users, Next: Programmers, Prev: Binaries, Up: Top
The User's View
***************
When GNU `gettext' will truly have reached its goal, average users
should feel some kind of astonished pleasure, seeing the effect of that
strange kind of magic that just makes their own native language appear
everywhere on their screens. As for naive users, they would ideally
have no special pleasure about it, merely taking their own language for
_granted_, and becoming rather unhappy otherwise.
So, let's try to describe here how we would like the magic to
operate, as we want the users' view to be the simplest, among all ways
one could look at GNU `gettext'. All other software engineers:
programmers, translators, maintainers, should work together in such a
way that the magic becomes possible. This is a long and progressive
undertaking, and information is available about the progress of the
Translation Project.
When a package is distributed, there are two kinds of users:
"installers" who fetch the distribution, unpack it, configure it,
compile it and install it for themselves or others to use; and "end
users" that call programs of the package, once these have been
installed at their site. GNU `gettext' is offering magic for both
installers and end users.
* Menu:
* Matrix:: The Current `ABOUT-NLS' Matrix
* Installers:: Magic for Installers
* End Users:: Magic for End Users
File: gettext.info, Node: Matrix, Next: Installers, Prev: Users, Up: Users
The Current `ABOUT-NLS' Matrix
==============================
Languages are not equally supported in all packages using GNU
`gettext'. To know if some package uses GNU `gettext', one may check
the distribution for the `ABOUT-NLS' information file, for some `LL.po'
files, often kept together into some `po/' directory, or for an `intl/'
directory. Internationalized packages have usually many `LL.po' files,
where LL represents the language. *Note End Users:: for a complete
description of the format for LL.
More generally, a matrix is available for showing the current state
of the Translation Project, listing which packages are prepared for
multi-lingual messages, and which languages are supported by each.
Because this information changes often, this matrix is not kept within
this GNU `gettext' manual. This information is often found in file
`ABOUT-NLS' from various distributions, but is also as old as the
distribution itself. A recent copy of this `ABOUT-NLS' file,
containing up-to-date information, should generally be found on the
Translation Project sites, and also on most GNU archive sites.
File: gettext.info, Node: Installers, Next: End Users, Prev: Matrix, Up: Users
Magic for Installers
====================
By default, packages fully using GNU `gettext', internally, are
installed in such a way that they to allow translation of messages. At
_configuration_ time, those packages should automatically detect
whether the underlying host system already provides the GNU `gettext'
functions. If not, the GNU `gettext' library should be automatically
prepared and used. Installers may use special options at configuration
time for changing this behavior. The command `./configure
--with-included-gettext' bypasses system `gettext' to use the included
GNU `gettext' instead, while `./configure --disable-nls' produces
programs totally unable to translate messages.
Internationalized packages have usually many `LL.po' files. Unless
translations are disabled, all those available are installed together
with the package. However, the environment variable `LINGUAS' may be
set, prior to configuration, to limit the installed set. `LINGUAS'
should then contain a space separated list of two-letter codes, stating
which languages are allowed.
File: gettext.info, Node: End Users, Prev: Installers, Up: Users
Magic for End Users
===================
We consider here those packages using GNU `gettext' internally, and
for which the installers did not disable translation at _configure_
time. Then, users only have to set the `LANG' environment variable to
the appropriate `LL_CC' combination prior to using the programs in the
package. *Note Matrix::. For example, let's presume a German site.
At the shell prompt, users merely have to execute `setenv LANG de_DE'
(in `csh') or `export LANG; LANG=de_DE' (in `sh'). They could even do
this from their `.login' or `.profile' file.
File: gettext.info, Node: Programmers, Next: Translators, Prev: Users, Up: Top
The Programmer's View
*********************
One aim of the current message catalog implementation provided by
GNU `gettext' was to use the system's message catalog handling, if the
installer wishes to do so. So we perhaps should first take a look at
the solutions we know about. The people in the POSIX committee did not
manage to agree on one of the semi-official standards which we'll
describe below. In fact they couldn't agree on anything, so they
decided only to include an example of an interface. The major Unix
vendors are split in the usage of the two most important
specifications: X/Open's catgets vs. Uniforum's gettext interface.
We'll describe them both and later explain our solution of this dilemma.
* Menu:
* catgets:: About `catgets'
* gettext:: About `gettext'
* Comparison:: Comparing the two interfaces
* Using libintl.a:: Using libintl.a in own programs
* gettext grok:: Being a `gettext' grok
* Temp Programmers:: Temporary Notes for the Programmers Chapter
File: gettext.info, Node: catgets, Next: gettext, Prev: Programmers, Up: Programmers
About `catgets'
===============
The `catgets' implementation is defined in the X/Open Portability
Guide, Volume 3, XSI Supplementary Definitions, Chapter 5. But the
process of creating this standard seemed to be too slow for some of the
Unix vendors so they created their implementations on preliminary
versions of the standard. Of course this leads again to problems while
writing platform independent programs: even the usage of `catgets' does
not guarantee a unique interface.
Another, personal comment on this that only a bunch of committee
members could have made this interface. They never really tried to
program using this interface. It is a fast, memory-saving
implementation, an user can happily live with it. But programmers hate
it (at least I and some others do...)
But we must not forget one point: after all the trouble with
transfering the rights on Unix(tm) they at last came to X/Open, the
very same who published this specification. This leads me to making
the prediction that this interface will be in future Unix standards
(e.g. Spec1170) and therefore part of all Unix implementation
(implementations, which are _allowed_ to wear this name).
* Menu:
* Interface to catgets:: The interface
* Problems with catgets:: Problems with the `catgets' interface?!
File: gettext.info, Node: Interface to catgets, Next: Problems with catgets, Prev: catgets, Up: catgets
The Interface
-------------
The interface to the `catgets' implementation consists of three
functions which correspond to those used in file access: `catopen' to
open the catalog for using, `catgets' for accessing the message tables,
and `catclose' for closing after work is done. Prototypes for the
functions and the needed definitions are in the `<nl_types.h>' header
file.
`catopen' is used like in this:
nl_catd catd = catopen ("catalog_name", 0);
The function takes as the argument the name of the catalog. This
usual refers to the name of the program or the package. The second
parameter is not further specified in the standard. I don't even know
whether it is implemented consistently among various systems. So the
common advice is to use `0' as the value. The return value is a handle
to the message catalog, equivalent to handles to file returned by
`open'.
This handle is of course used in the `catgets' function which can be
used like this:
char *translation = catgets (catd, set_no, msg_id, "original string");
The first parameter is this catalog descriptor. The second parameter
specifies the set of messages in this catalog, in which the message
described by `msg_id' is obtained. `catgets' therefore uses a
three-stage addressing:
catalog name => set number => message ID => translation
The fourth argument is not used to address the translation. It is
given as a default value in case when one of the addressing stages
fail. One important thing to remember is that although the return type
of catgets is `char *' the resulting string _must not_ be changed. It
should better be `const char *', but the standard is published in 1988,
one year before ANSI C.
The last of these functions is used and behaves as expected:
catclose (catd);
After this no `catgets' call using the descriptor is legal anymore.
File: gettext.info, Node: Problems with catgets, Prev: Interface to catgets, Up: catgets
Problems with the `catgets' Interface?!
---------------------------------------
Now that this description seemed to be really easy -- where are the
problems we speak of? In fact the interface could be used in a
reasonable way, but constructing the message catalogs is a pain. The
reason for this lies in the third argument of `catgets': the unique
message ID. This has to be a numeric value for all messages in a single
set. Perhaps you could imagine the problems keeping such a list while
changing the source code. Add a new message here, remove one there. Of
course there have been developed a lot of tools helping to organize this
chaos but one as the other fails in one aspect or the other. We don't
want to say that the other approach has no problems but they are far
more easy to manage.
File: gettext.info, Node: gettext, Next: Comparison, Prev: catgets, Up: Programmers
About `gettext'
===============
The definition of the `gettext' interface comes from a Uniforum
proposal and it is followed by at least one major Unix vendor (Sun) in
its last developments. It is not specified in any official standard,
though.
The main point about this solution is that it does not follow the
method of normal file handling (open-use-close) and that it does not
burden the programmer with so many tasks, especially the unique key
handling. Of course here also a unique key is needed, but this key is
the message itself (how long or short it is). See *Note Comparison::
for a more detailed comparison of the two methods.
The following section contains a rather detailed description of the
interface. We make it that detailed because this is the interface we
chose for the GNU `gettext' Library. Programmers interested in using
this library will be interested in this description.
* Menu:
* Interface to gettext:: The interface
* Ambiguities:: Solving ambiguities
* Locating Catalogs:: Locating message catalog files
* Charset conversion:: How to request conversion to Unicode
* Plural forms:: Additional functions for handling plurals
* GUI program problems:: Another technique for solving ambiguities
* Optimized gettext:: Optimization of the *gettext functions
File: gettext.info, Node: Interface to gettext, Next: Ambiguities, Prev: gettext, Up: gettext
The Interface
-------------
The minimal functionality an interface must have is a) to select a
domain the strings are coming from (a single domain for all programs is
not reasonable because its construction and maintenance is difficult,
perhaps impossible) and b) to access a string in a selected domain.
This is principally the description of the `gettext' interface. It
has a global domain which unqualified usages reference. Of course this
domain is selectable by the user.
char *textdomain (const char *domain_name);
This provides the possibility to change or query the current status
of the current global domain of the `LC_MESSAGE' category. The
argument is a null-terminated string, whose characters must be legal in
the use in filenames. If the DOMAIN_NAME argument is `NULL', the
function returns the current value. If no value has been set before,
the name of the default domain is returned: _messages_. Please note
that although the return value of `textdomain' is of type `char *' no
changing is allowed. It is also important to know that no checks of
the availability are made. If the name is not available you will see
this by the fact that no translations are provided.
To use a domain set by `textdomain' the function
char *gettext (const char *msgid);
is to be used. This is the simplest reasonable form one can imagine.
The translation of the string MSGID is returned if it is available in
the current domain. If it is not available, the argument itself is
returned. If the argument is `NULL' the result is undefined.
One thing which should come into mind is that no explicit dependency
to the used domain is given. The current value of the domain for the
`LC_MESSAGES' locale is used. If this changes between two executions
of the same `gettext' call in the program, both calls reference a
different message catalog.
For the easiest case, which is normally used in internationalized
packages, once at the beginning of execution a call to `textdomain' is
issued, setting the domain to a unique name, normally the package name.
In the following code all strings which have to be translated are
filtered through the gettext function. That's all, the package speaks
your language.
File: gettext.info, Node: Ambiguities, Next: Locating Catalogs, Prev: Interface to gettext, Up: gettext
Solving Ambiguities
-------------------
While this single name domain works well for most applications there
might be the need to get translations from more than one domain. Of
course one could switch between different domains with calls to
`textdomain', but this is really not convenient nor is it fast. A
possible situation could be one case subject to discussion during this
writing: all error messages of functions in the set of common used
functions should go into a separate domain `error'. By this mean we
would only need to translate them once. Another case are messages from
a library, as these _have_ to be independent of the current domain set
by the application.
For this reasons there are two more functions to retrieve strings:
char *dgettext (const char *domain_name, const char *msgid);
char *dcgettext (const char *domain_name, const char *msgid,
int category);
Both take an additional argument at the first place, which
corresponds to the argument of `textdomain'. The third argument of
`dcgettext' allows to use another locale but `LC_MESSAGES'. But I
really don't know where this can be useful. If the DOMAIN_NAME is
`NULL' or CATEGORY has an value beside the known ones, the result is
undefined. It should also be noted that this function is not part of
the second known implementation of this function family, the one found
in Solaris.
A second ambiguity can arise by the fact, that perhaps more than one
domain has the same name. This can be solved by specifying where the
needed message catalog files can be found.
char *bindtextdomain (const char *domain_name,
const char *dir_name);
Calling this function binds the given domain to a file in the
specified directory (how this file is determined follows below).
Especially a file in the systems default place is not favored against
the specified file anymore (as it would be by solely using
`textdomain'). A `NULL' pointer for the DIR_NAME parameter returns the
binding associated with DOMAIN_NAME. If DOMAIN_NAME itself is `NULL'
nothing happens and a `NULL' pointer is returned. Here again as for
all the other functions is true that none of the return value must be
changed!
It is important to remember that relative path names for the
DIR_NAME parameter can be trouble. Since the path is always computed
relative to the current directory different results will be achieved
when the program executes a `chdir' command. Relative paths should
always be avoided to avoid dependencies and unreliabilities.
File: gettext.info, Node: Locating Catalogs, Next: Charset conversion, Prev: Ambiguities, Up: gettext
Locating Message Catalog Files
------------------------------
Because many different languages for many different packages have to
be stored we need some way to add these information to file message
catalog files. The way usually used in Unix environments is have this
encoding in the file name. This is also done here. The directory name
given in `bindtextdomain's second argument (or the default directory),
followed by the value and name of the locale and the domain name are
concatenated:
DIR_NAME/LOCALE/LC_CATEGORY/DOMAIN_NAME.mo
The default value for DIR_NAME is system specific. For the GNU
library, and for packages adhering to its conventions, it's:
/usr/local/share/locale
LOCALE is the value of the locale whose name is this `LC_CATEGORY'.
For `gettext' and `dgettext' this `LC_CATEGORY' is always
`LC_MESSAGES'.(1) The value of the locale is determined through
`setlocale (LC_CATEGORY, NULL)'. (2) `dcgettext' specifies the locale
category by the third argument.
---------- Footnotes ----------
(1) Some system, eg Ultrix, don't have `LC_MESSAGES'. Here we use a
more or less arbitrary value for it, namely 1729, the smallest positive
integer which can be represented in two different ways as the sum of
two cubes.
(2) When the system does not support `setlocale' its behavior in
setting the locale values is simulated by looking at the environment
variables.
File: gettext.info, Node: Charset conversion, Next: Plural forms, Prev: Locating Catalogs, Up: gettext
How to specify the output character set `gettext' uses
------------------------------------------------------
`gettext' not only looks up a translation in a message catalog. It
also converts the translation on the fly to the desired output character
set. This is useful if the user is working in a different character set
than the translator who created the message catalog, because it avoids
distributing variants of message catalogs which differ only in the
character set.
The output character set is, by default, the value of `nl_langinfo
(CODESET)', which depends on the `LC_CTYPE' part of the current locale.
But programs which store strings in a locale independent way (e.g.
UTF-8) can request that `gettext' and related functions return the
translations in that encoding, by use of the `bind_textdomain_codeset'
function.
Note that the MSGID argument to `gettext' is not subject to
character set conversion. Also, when `gettext' does not find a
translation for MSGID, it returns MSGID unchanged - independently of
the current output character set. It is therefore recommended that all
MSGIDs be US-ASCII strings.
- Funktion: char * bind_textdomain_codeset (const char *DOMAINNAME,
const char *CODESET)
The `bind_textdomain_codeset' function can be used to specify the
output character set for message catalogs for domain DOMAINNAME.
The CODESET argument must be a valid codeset name which can be used
for the `iconv_open' function, or a null pointer.
If the CODESET parameter is the null pointer,
`bind_textdomain_codeset' returns the currently selected codeset
for the domain with the name DOMAINNAME. It returns `NULL' if no
codeset has yet been selected.
The `bind_textdomain_codeset' function can be used several times.
If used multiple times with the same DOMAINNAME argument, the
later call overrides the settings made by the earlier one.
The `bind_textdomain_codeset' function returns a pointer to a
string containing the name of the selected codeset. The string is
allocated internally in the function and must not be changed by the
user. If the system went out of core during the execution of
`bind_textdomain_codeset', the return value is `NULL' and the
global variable ERRNO is set accordingly.