   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.

Integrating with CVS
====================

   Many projects use CVS for distributed development, version control
and source backup.  This section gives some advice how to manage the
uses of `cvs', `gettextize', `autopoint' and `autoconf'.

Avoiding version mismatch in distributed development
----------------------------------------------------

   In a project development with multiple developers, using CVS, there
should be a single developer who occasionally - when there is desire to
upgrade to a new `gettext' version - runs `gettextize' and performs the
changes listed in Adjusting Files, and then commits his changes
to the CVS.

   It is highly recommended that all developers on a project use the
same version of GNU `gettext' in the package.  In other words, if a
developer runs `gettextize', he should go the whole way, make the
necessary remaining changes and commit his changes to the CVS.
Otherwise the following damages will likely occur:

   * Apparent version mismatch between developers.  Since some `gettext'
     specific portions in `configure.in', `configure.ac' and
     `Makefile.am', `Makefile.in' files depend on the `gettext'
     version, the use of infrastructure files belonging to different
     `gettext' versions can easily lead to build errors.

   * Hidden version mismatch.  Such version mismatch can also lead to
     malfunctioning of the package, that may be undiscovered by the
     developers.  The worst case of hidden version mismatch is that
     internationalization of the package doesn't work at all.

   * Release risks.  All developers implicitly perform constant testing
     on a package.  This is important in the days and weeks before a
     release.  If the guy who makes the release tar files uses a
     different version of GNU `gettext' than the other developers, the
     distribution will be less well tested than if all had been using
     the same `gettext' version.  For example, it is possible that a
     platform specific bug goes undiscovered due to this constellation.

Files to put under CVS version control
--------------------------------------

   There are basically three ways to deal with generated files in the
context of a CVS repository, such as `configure' generated from
`configure.in', `PARSER.c' generated from `PARSER.y', or
`po/Makefile.in.in' autoinstalled by `gettextize' or `autopoint'.

  1. All generated files are always committed into the repository.

  2. All generated files are committed into the repository occasionally,
     for example each time a release is made.

  3. Generated files are never committed into the repository.

   Each of these three approaches has different advantages and
drawbacks.

  1. The advantage is that anyone can check out the CVS at any moment
     and gets a working build.  The drawbacks are:  1a. It requires
     some frequent "cvs commit" actions by the maintainers.  1b. The
     reposity grows in size quite fast.

  2. The advantage is that anyone can check out the CVS, and the usual
     "./configure; make" will work.  The drawbacks are:  2a. The one who
     checks out the repository needs tools like GNU `automake', GNU
     `autoconf', GNU `m4' installed in his PATH; sometimes he even
     needs particular versions of them.  2b. When a release is made and
     a commit is made on the generated files, the other developers get
     conflicts on the generated files after doing "cvs update".
     Although these conflicts are easy to resolve, they are annoying.

  3. The advantage is less work for the maintainers.  The drawback is
     that anyone who checks out the CVS not only needs tools like GNU
     `automake', GNU `autoconf', GNU `m4' installed in his PATH, but
     also that he needs to perform a package specific pre-build step
     before being able to "./configure; make".

   For the first and second approach, all files modified or brought in
by the occasional `gettextize' invocation and update should be
committed into the CVS.

   For the third approach, the maintainer can omit from the CVS
repository all the files that `gettextize' mentions as "copy".
Instead, he adds to the `configure.in' or `configure.ac' a line of the
form

     AM_GNU_GETTEXT_VERSION(0.12.1)

and adds to the package's pre-build script an invocation of
`autopoint'.  For everyone who checks out the CVS, this `autopoint'
invocation will copy into the right place the `gettext' infrastructure
files that have been omitted from the CVS.

Invoking the `autopoint' Program
--------------------------------

     autopoint [OPTION]...

   The `autopoint' program copies standard gettext infrastructure files
into a source package.  It extracts from a macro call of the form
`AM_GNU_GETTEXT_VERSION(VERSION)', found in the package's
`configure.in' or `configure.ac' file, the gettext version used by the
package, and copies the infrastructure files belonging to this version
into the package.

Options
.......

`-f'
`--force'
     Force overwriting of files that already exist.

`-n'
`--dry-run'
     Print modifications but don't perform them.  All file copying
     actions that `autopoint' would normally execute are inhibited and
     instead only listed on standard output.

Informative output
..................

`--help'
     Display this help and exit.

`--version'
     Output version information and exit.

   `autopoint' supports the GNU `gettext' versions from 0.10.35 to the
current one, 0.12.1.  In order to apply `autopoint' to a package using
a `gettext' version newer than 0.12.1, you need to install this same
version of GNU `gettext' at least.

   In packages using GNU `automake', an invocation of `autopoint'
should be followed by invocations of `aclocal' and then `autoconf' and
`autoheader'.  The reason is that `autopoint' installs some autoconf
macro files, which are used by `aclocal' to create `aclocal.m4', and
the latter is used by `autoconf' to create the package's `configure'
script and by `autoheader' to create the package's `config.h.in'
include file template.

   The name `autopoint' is an abbreviation of `auto-po-intl-m4'; the
tool copies or updates mostly files in the `po', `intl', `m4'
directories.

Other Programming Languages
***************************

   While the presentation of `gettext' focuses mostly on C and
implicitly applies to C++ as well, its scope is far broader than that:
Many programming languages, scripting languages and other textual data
like GUI resources or package descriptions can make use of the gettext
approach.

The Language Implementor's View
===============================

   All programming and scripting languages that have the notion of
strings are eligible to supporting `gettext'.  Supporting `gettext'
means the following:

  1. You should add to the language a syntax for translatable strings.
     In principle, a function call of `gettext' would do, but a
     shorthand syntax helps keeping the legibility of internationalized
     programs.  For example, in C we use the syntax `_("string")', in
     bash we use the syntax `$"string"', and in GNU awk we use the
     shorthand `_"string"'.

  2. You should arrange that evaluation of such a translatable string at
     runtime calls the `gettext' function, or performs equivalent
     processing.

  3. Similarly, you should make the functions `ngettext', `dcgettext',
     `dcngettext' available from within the language.  These functions
     are less often used, but are nevertheless necessary for particular
     purposes: `ngettext' for correct plural handling, and `dcgettext'
     and `dcngettext' for obeying other locale environment variables
     than `LC_MESSAGES', such as `LC_TIME' or `LC_MONETARY'.  For these
     latter functions, you need to make the `LC_*' constants, available
     in the C header `<locale.h>', referenceable from within the
     language, usually either as enumeration values or as strings.

  4. You should allow the programmer to designate a message domain,
     either by making the `textdomain' function available from within
     the language, or by introducing a magic variable called
     `TEXTDOMAIN'.  Similarly, you should allow the programmer to
     designate where to search for message catalogs, by providing
     access to the `bindtextdomain' function.

  5. You should either perform a `setlocale (LC_ALL, "")' call during
     the startup of your language runtime, or allow the programmer to
     do so.  Remember that gettext will act as a no-op if the
     `LC_MESSAGES' and `LC_CTYPE' locale facets are not both set.

  6. A programmer should have a way to extract translatable strings
     from a program into a PO file.  The GNU `xgettext' program is being
     extended to support very different programming languages.  Please
     contact the GNU `gettext' maintainers to help them doing this.  If
     the string extractor is best integrated into your language's
     parser, GNU `xgettext' can function as a front end to your string
     extractor.

  7. The language's library should have a string formatting facility
     where the arguments of a format string are denoted by a positional
     number or a name.  This is needed because for some languages and
     some messages with more than one substitutable argument, the
     translation will need to output the substituted arguments in
     different order.  See c-format Flag.

  8. If the language has more than one implementation, and not all of
     the implementations use `gettext', but the programs should be
     portable across implementations, you should provide a no-i18n
     emulation, that makes the other implementations accept programs
     written for yours, without actually translating the strings.

  9. To help the programmer in the task of marking translatable strings,
     which is usually performed using the Emacs PO mode, you are
     welcome to contact the GNU `gettext' maintainers, so they can add
     support for your language to `po-mode.el'.

   On the implementation side, three approaches are possible, with
different effects on portability and copyright:

   * You may integrate the GNU `gettext''s `intl/' directory in your
     package, as described in Maintainers.  This allows you to
     have internationalization on all kinds of platforms.  Note that
     when you then distribute your package, it legally falls under the
     GNU General Public License, and the GNU project will be glad about
     your contribution to the Free Software pool.

   * You may link against GNU `gettext' functions if they are found in
     the C library.  For example, an autoconf test for `gettext()' and
     `ngettext()' will detect this situation.  For the moment, this test
     will succeed on GNU systems and not on other platforms.  No severe
     copyright restrictions apply.

   * You may emulate or reimplement the GNU `gettext' functionality.
     This has the advantage of full portability and no copyright
     restrictions, but also the drawback that you have to reimplement
     the GNU `gettext' features (such as the `LANGUAGE' environment
     variable, the locale aliases database, the automatic charset
     conversion, and plural handling).

The Programmer's View
=====================

   For the programmer, the general procedure is the same as for the C
language.  The Emacs PO mode supports other languages, and the GNU
`xgettext' string extractor recognizes other languages based on the
file extension or a command-line option.  In some languages,
`setlocale' is not needed because it is already performed by the
underlying language runtime.

The Translator's View
=====================

   The translator works exactly as in the C language case.  The only
difference is that when translating format strings, she has to be aware
of the language's particular syntax for positional arguments in format
strings.

C Format Strings
----------------

   C format strings are described in POSIX (IEEE P1003.1 2001), section
XSH 3 fprintf(),
`http://www.opengroup.org/onlinepubs/007904975/functions/fprintf.html'.
See also the fprintf(3) manual page,
`http://www.linuxvalley.it/encyclopedia/ldp/manpage/man3/printf.3.php',
`http://informatik.fh-wuerzburg.de/student/i510/man/printf.html'.

Python Format Strings
---------------------

   Python format strings are described in Python Library reference /
2. Built-in Types, Exceptions and Functions / 2.2. Built-in Types /
2.2.6. Sequence Types / 2.2.6.2. String Formatting Operations.
`http://www.python.org/doc/2.2.1/lib/typesseq-strings.html'.

Lisp Format Strings
-------------------

   Lisp format strings are described in the Common Lisp HyperSpec,
chapter 22.3 Formatted Output,
`http://www.lisp.org/HyperSpec/Body/sec_22-3.html'.

Emacs Lisp Format Strings
-------------------------

   Emacs Lisp format strings are documented in the Emacs Lisp reference,
section Formatting Strings,
`http://www.gnu.org/manual/elisp-manual-21-2.8/html_chapter/elisp_4.html#SEC75'.
Note that as of version 21, XEmacs supports numbered argument
specifications in format strings while FSF Emacs doesn't.

librep Format Strings
---------------------

   librep format strings are documented in the librep manual, section
Formatted Output,
<http://librep.sourceforge.net/librep-manual.html#Formatted%20Output>,
<http://www.gwinnup.org/research/docs/librep.html#SEC122>.

Smalltalk Format Strings
------------------------

   Smalltalk format strings are described in the GNU Smalltalk
documentation, class `CharArray', methods `bindWith:' and
`bindWithArguments:'.
`http://www.gnu.org/software/smalltalk/gst-manual/gst_68.html#SEC238'.
In summary, a directive starts with `%' and is followed by `%' or a
nonzero digit (`1' to `9').

Java Format Strings
-------------------

   Java format strings are described in the JDK documentation for class
`java.text.MessageFormat',
`http://java.sun.com/j2se/1.4/docs/api/java/text/MessageFormat.html'.
See also the ICU documentation
`http://oss.software.ibm.com/icu/apiref/classMessageFormat.html'.

awk Format Strings
------------------

   awk format strings are described in the gawk documentation, section
Printf, `http://www.gnu.org/manual/gawk/html_node/Printf.html#Printf'.

Object Pascal Format Strings
----------------------------

   Where is this documented?

YCP Format Strings
------------------

   YCP sformat strings are described in the libycp documentation
`file:/usr/share/doc/packages/libycp/YCP-builtins.html'.  In summary, a
directive starts with `%' and is followed by `%' or a nonzero digit
(`1' to `9').

Tcl Format Strings
------------------

   Tcl format strings are described in the `format.n' manual page,
`http://www.scriptics.com/man/tcl8.3/TclCmd/format.htm'.

PHP Format Strings
------------------

   PHP format strings are described in the documentation of the PHP
function `sprintf', in `phpdoc/manual/function.sprintf.html' or
`http://www.php.net/manual/en/function.sprintf.php'.

The Maintainer's View
=====================

   For the maintainer, the general procedure differs from the C language
case in two ways.

   * For those languages that don't use GNU gettext, the `intl/'
     directory is not needed and can be omitted.  This means that the
     maintainer calls the `gettextize' program without the `--intl'
     option, and that he invokes the `AM_GNU_GETTEXT' autoconf macro via
     `AM_GNU_GETTEXT([external])'.

   * If only a single programming language is used, the
     `XGETTEXT_OPTIONS' variable in `po/Makevars' (see po/Makevars)
     should be adjusted to match the `xgettext' options for that
     particular programming language.  If the package uses more than
     one programming language with `gettext' support, it becomes
     necessary to change the POT file construction rule in
     `po/Makefile.in.in'.  It is recommended to make one `xgettext'
     invocation per programming language, each with the options
     appropriate for that language, and to combine the resulting files
     using `msgcat'.

Individual Programming Languages
================================

C, C++, Objective C
-------------------

RPMs
     gcc, gpp, gobjc, glibc, gettext

File extension
     For C: `c', `h'.
     For C++: `C', `c++', `cc', `cxx', `cpp', `hpp'.
     For Objective C: `m'.

String syntax
     `"abc"'

gettext shorthand
     `_("abc")'

gettext/ngettext functions
     `gettext', `dgettext', `dcgettext', `ngettext', `dngettext',
     `dcngettext'

textdomain
     `textdomain' function

bindtextdomain
     `bindtextdomain' function

setlocale
     Programmer must call `setlocale (LC_ALL, "")'

Prerequisite
     `#include <libintl.h>'
     `#include <locale.h>'
     `#define _(string) gettext (string)'

Use or emulate GNU gettext
     Use

Extractor
     `xgettext -k_'

Formatting with positions
     `fprintf "%2$d %1$d"' (POSIX/XSI but not C 99)
     In C++: `autosprintf "%2$d %1$d"' (see Introduction (autosprintf))

Portability
     autoconf (gettext.m4) and #if ENABLE_NLS

po-mode marking
     yes

sh - Shell Script
-----------------

RPMs
     bash, gettext

File extension
     `sh'

String syntax
     `"abc"', `'abc'', `abc'

gettext shorthand
     `"`gettext "abc"`"'

gettext/ngettext functions
     `gettext', `ngettext' programs

textdomain
     environment variable `TEXTDOMAIN'

bindtextdomain
     environment variable `TEXTDOMAINDIR'

setlocale
     automatic

Prerequisite
     --

Use or emulate GNU gettext
     use

Extractor
     --

Formatting with positions
     --

Portability
     --

po-mode marking
     --

bash - Bourne-Again Shell Script
--------------------------------

RPMs
     bash 2.0 or newer, gettext

File extension
     `sh'

String syntax
     `"abc"', `'abc'', `abc'

gettext shorthand
     `$"abc"'

gettext/ngettext functions
     `gettext', `ngettext' programs

textdomain
     environment variable `TEXTDOMAIN'

bindtextdomain
     environment variable `TEXTDOMAINDIR'

setlocale
     automatic

Prerequisite
     --

Use or emulate GNU gettext
     use

Extractor
     `bash --dump-po-strings'

Formatting with positions
     --

Portability
     --

po-mode marking
     --

Python
------

RPMs
     python

File extension
     `py'

String syntax
     `'abc'', `u'abc'', `r'abc'', `ur'abc'',
     `"abc"', `u"abc"', `r"abc"', `ur"abc"',
     `'''abc'''', `u'''abc'''', `r'''abc'''', `ur'''abc'''',
     `"""abc"""', `u"""abc"""', `r"""abc"""', `ur"""abc"""'

gettext shorthand
     `_('abc')' etc.

gettext/ngettext functions
     `gettext.gettext', `gettext.dgettext', `gettext.ngettext',
     `gettext.dngettext', also `ugettext', `ungettext'

textdomain
     `gettext.textdomain' function, or `gettext.install(DOMAIN)'
     function

bindtextdomain
     `gettext.bindtextdomain' function, or
     `gettext.install(DOMAIN,LOCALEDIR)' function

setlocale
     not used by the gettext emulation

Prerequisite
     `import gettext'

Use or emulate GNU gettext
     emulate.  Bug: uses only the first found .mo file, not all of them

Extractor
     `xgettext'

Formatting with positions
     `'...%(ident)d...' % { 'ident': value }'

Portability
     fully portable

po-mode marking
     --

GNU clisp - Common Lisp
-----------------------

RPMs
     clisp 2.28 or newer

File extension
     `lisp'

String syntax
     `"abc"'

gettext shorthand
     `(_ "abc")', `(ENGLISH "abc")'

gettext/ngettext functions
     `i18n:gettext', `i18n:ngettext'

textdomain
     `i18n:textdomain'

bindtextdomain
     `i18n:textdomaindir'

setlocale
     automatic

Prerequisite
     --

Use or emulate GNU gettext
     use

Extractor
     `xgettext -k_ -kENGLISH'

Formatting with positions
     `format "~1@*~D ~0@*~D"'

Portability
     On platforms without gettext, no translation.

po-mode marking
     --

GNU clisp C sources
-------------------

RPMs
     clisp

File extension
     `d'

String syntax
     `"abc"'

gettext shorthand
     `ENGLISH ? "abc" : ""'
     `GETTEXT("abc")'
     `GETTEXTL("abc")'

gettext/ngettext functions
     `clgettext', `clgettextl'

textdomain
     --

bindtextdomain
     --

setlocale
     automatic

Prerequisite
     `#include "lispbibl.c"'

Use or emulate GNU gettext
     use

Extractor
     `clisp-xgettext'

Formatting with positions
     `fprintf "%2$d %1$d"' (POSIX/XSI but not C 99)

Portability
     On platforms without gettext, no translation.

po-mode marking
     --

Emacs Lisp
----------

RPMs
     emacs, xemacs

File extension
     `el'

String syntax
     `"abc"'

gettext shorthand
     `(_"abc")'

gettext/ngettext functions
     `gettext', `dgettext' (xemacs only)

textdomain
     `domain' special form (xemacs only)

bindtextdomain
     `bind-text-domain' function (xemacs only)

setlocale
     automatic

Prerequisite
     --

Use or emulate GNU gettext
     use

Extractor
     `xgettext'

Formatting with positions
     `format "%2$d %1$d"'

Portability
     Only XEmacs.  Without `I18N3' defined at build time, no
     translation.

po-mode marking
     --

librep
------

RPMs
     librep 0.15.3 or newer

File extension
     `jl'

String syntax
     `"abc"'

gettext shorthand
     `(_"abc")'

gettext/ngettext functions
     `gettext'

textdomain
     `textdomain' function

bindtextdomain
     `bindtextdomain' function

setlocale
     --

Prerequisite
     `(require 'rep.i18n.gettext)'

Use or emulate GNU gettext
     use

Extractor
     `xgettext'

Formatting with positions
     `format "%2$d %1$d"'

Portability
     On platforms without gettext, no translation.

po-mode marking
     --

GNU Smalltalk
-------------

RPMs
     smalltalk

File extension
     `st'

String syntax
     `'abc''

gettext shorthand
     `NLS ? 'abc''

gettext/ngettext functions
     `LcMessagesDomain>>#at:', `LcMessagesDomain>>#at:plural:with:'

textdomain
     `LcMessages>>#domain:localeDirectory:' (returns a
     `LcMessagesDomain' object).
     Example: `I18N Locale default messages domain: 'gettext'
     localeDirectory: /usr/local/share/locale''

bindtextdomain
     `LcMessages>>#domain:localeDirectory:', see above.

setlocale
     Automatic if you use `I18N Locale default'.

Prerequisite
     `PackageLoader fileInPackage: 'I18N'!'

Use or emulate GNU gettext
     emulate

Extractor
     `xgettext'

Formatting with positions
     `'%1 %2' bindWith: 'Hello' with: 'world''

Portability
     fully portable

po-mode marking
     --

Java
----

RPMs
     java, java2

File extension
     `java'

String syntax
     "abc"

gettext shorthand
     _("abc")

gettext/ngettext functions
     `GettextResource.gettext', `GettextResource.ngettext'

textdomain
     --, use `ResourceBundle.getResource' instead

bindtextdomain
     --, use CLASSPATH instead

setlocale
     automatic

Prerequisite
     --

Use or emulate GNU gettext
     --, uses a Java specific message catalog format

Extractor
     `xgettext -k_'

Formatting with positions
     `MessageFormat.format "{1,number} {0,number}"'

Portability
     fully portable

po-mode marking
     --

   Before marking strings as internationalizable, uses of the string
concatenation operator need to be converted to `MessageFormat'
applications.  For example, `"file "+filename+" not found"' becomes
`MessageFormat.format("file {0} not found", new Object[] { filename })'.
Only after this is done, can the strings be marked and extracted.

   GNU gettext uses the native Java internationalization mechanism,
namely `ResourceBundle's.  There are two formats of `ResourceBundle's:
`.properties' files and `.class' files.  The `.properties' format is a
text file which the translators can directly edit, like PO files, but
which doesn't support plural forms.  Whereas the `.class' format is
compiled from `.java' source code and can support plural forms
(provided it is accessed through an appropriate API, see below).

   To convert a PO file to a `.properties' file, the `msgcat' program
can be used with the option `--properties-output'.  To convert a
`.properties' file back to a PO file, the `msgcat' program can be used
with the option `--properties-input'.  All the tools that manipulate PO
files can work with `.properties' files as well, if given the
`--properties-input' and/or `--properties-output' option.

   To convert a PO file to a ResourceBundle class, the `msgfmt' program
can be used with the option `--java' or `--java2'.  To convert a
ResourceBundle back to a PO file, the `msgunfmt' program can be used
with the option `--java'.

   Two different programmatic APIs can be used to access
ResourceBundles.  Note that both APIs work with all kinds of
ResourceBundles, whether GNU gettext generated classes, or other
`.class' or `.properties' files.

  1. The `java.util.ResourceBundle' API.

     In particular, its `getString' function returns a string
     translation.  Note that a missing translation yields a
     `MissingResourceException'.

     This has the advantage of being the standard API.  And it does not
     require any additional libraries, only the `msgcat' generated
     `.properties' files or the `msgfmt' generated `.class' files.  But
     it cannot do plural handling, even if the resource was generated
     by `msgfmt' from a PO file with plural handling.

  2. The `gnu.gettext.GettextResource' API.

     Reference documentation in Javadoc 1.1 style format is in the
     javadoc1 directory (javadoc1/tree.html) and in Javadoc 2 style
     format in the javadoc2 directory (javadoc2/index.html).

     Its `gettext' function returns a string translation.  Note that
     when a translation is missing, the MSGID argument is returned
     unchanged.

     This has the advantage of having the `ngettext' function for plural
     handling.

     To use this API, one needs the `libintl.jar' file which is part of
     the GNU gettext package and distributed under the LGPL.

GNU awk
-------

RPMs
     gawk 3.1 or newer

File extension
     `awk'

String syntax
     `"abc"'

gettext shorthand
     `_"abc"'

gettext/ngettext functions
     `dcgettext', missing `dcngettext' in gawk-3.1.0

textdomain
     `TEXTDOMAIN' variable

bindtextdomain
     `bindtextdomain' function

setlocale
     automatic, but missing `setlocale (LC_MESSAGES, "")' in gawk-3.1.0

Prerequisite
     --

Use or emulate GNU gettext
     use

Extractor
     `xgettext'

Formatting with positions
     `printf "%2$d %1$d"' (GNU awk only)

Portability
     On platforms without gettext, no translation.  On non-GNU awks,
     you must define `dcgettext', `dcngettext' and `bindtextdomain'
     yourself.

po-mode marking
     --

Pascal - Free Pascal Compiler
-----------------------------

RPMs
     fpk

File extension
     `pp', `pas'

String syntax
     `'abc''

gettext shorthand
     automatic

gettext/ngettext functions
     --, use `ResourceString' data type instead

textdomain
     --, use `TranslateResourceStrings' function instead

bindtextdomain
     --, use `TranslateResourceStrings' function instead

setlocale
     automatic, but uses only LANG, not LC_MESSAGES or LC_ALL

Prerequisite
     `{$mode delphi}' or `{$mode objfpc}'
     `uses gettext;'

Use or emulate GNU gettext
     emulate partially

Extractor
     `ppc386' followed by `xgettext' or `rstconv'

Formatting with positions
     `uses sysutils;'
     `format "%1:d %0:d"'

Portability
     ?

po-mode marking
     --

   The Pascal compiler has special support for the `ResourceString' data
type.  It generates a `.rst' file.  This is then converted to a `.pot'
file by use of `xgettext' or `rstconv'.  At runtime, a `.mo' file
corresponding to translations of this `.pot' file can be loaded using
the `TranslateResourceStrings' function in the `gettext' unit.

wxWindows library
-----------------

RPMs
     wxGTK, gettext

File extension
     `cpp'

String syntax
     `"abc"'

gettext shorthand
     `_("abc")'

gettext/ngettext functions
     `wxLocale::GetString', `wxGetTranslation'

textdomain
     `wxLocale::AddCatalog'

bindtextdomain
     `wxLocale::AddCatalogLookupPathPrefix'

setlocale
     `wxLocale::Init', `wxSetLocale'

Prerequisite
     `#include <wx/intl.h>'

Use or emulate GNU gettext
     emulate, see `include/wx/intl.h' and `src/common/intl.cpp'

Extractor
     `xgettext'

Formatting with positions
     --

Portability
     fully portable

po-mode marking
     yes

YCP - YaST2 scripting language
------------------------------

RPMs
     libycp, libycp-devel, yast2-core-translator

File extension
     `ycp'

String syntax
     `"abc"'

gettext shorthand
     `_("abc")'

gettext/ngettext functions
     `_()' with 1 or 3 arguments

textdomain
     `textdomain' statement

bindtextdomain
     --

setlocale
     --

Prerequisite
     --

Use or emulate GNU gettext
     use maps instead

Extractor
     `xgettext'

Formatting with positions
     `sformat "%2 %1"'

Portability
     fully portable

po-mode marking
     --

Tcl - Tk's scripting language
-----------------------------

RPMs
     tcl

File extension
     `tcl'

String syntax
     `"abc"'

gettext shorthand
     `[_ "abc"]'

gettext/ngettext functions
     `::msgcat::mc'

textdomain
     --

bindtextdomain
     --, use `::msgcat::mcload' instead

setlocale
     automatic, uses LANG, but ignores LC_MESSAGES and LC_ALL

Prerequisite
     `package require msgcat'
     `proc _ {s} {return [::msgcat::mc $s]}'

Use or emulate GNU gettext
     --, uses a Tcl specific message catalog format

Extractor
     `xgettext -k_'

Formatting with positions
     `format "%2\$d %1\$d"'

Portability
     fully portable

po-mode marking
     --

   Before marking strings as internationalizable, substitutions of
variables into the string need to be converted to `format'
applications.  For example, `"file $filename not found"' becomes
`[format "file %s not found" $filename]'.  Only after this is done, can
the strings be marked and extracted.  After marking, this example
becomes `[format [_ "file %s not found"] $filename]' or `[msgcat::mc
"file %s not found" $filename]'.  Note that the `msgcat::mc' function
implicitly calls `format' when more than one argument is given.

Perl
----

RPMs
     perl, perl-gettext

File extension
     `pl', `PL'

String syntax
     `"abc"'

gettext shorthand
     --

gettext/ngettext functions
     `gettext', `dgettext', `dcgettext'

textdomain
     `textdomain' function

bindtextdomain
     `bindtextdomain' function

setlocale
     Use `setlocale (LC_ALL, "");'

Prerequisite
     `use POSIX;'
     `use Locale::gettext;'

Use or emulate GNU gettext
     use

Extractor
     ?

Formatting with positions
     --

Portability
     ?

po-mode marking
     --

PHP Hypertext Preprocessor
--------------------------

RPMs
     mod_php4, mod_php4-core, phplib, phpdoc

File extension
     `php', `php3', `php4'

String syntax
     `"abc"', `'abc''

gettext shorthand
     `_("abc")'

gettext/ngettext functions
     `gettext', `dgettext', `dcgettext'

textdomain
     `textdomain' function

bindtextdomain
     `bindtextdomain' function

setlocale
     Programmer must call `setlocale (LC_ALL, "")'

Prerequisite
     --

Use or emulate GNU gettext
     use

Extractor
     `xgettext'

Formatting with positions
     `printf "%2\$d %1\$d"'

Portability
     On platforms without gettext, the functions are not available.

po-mode marking
     --

Pike
----

RPMs
     roxen

File extension
     `pike'

String syntax
     `"abc"'

gettext shorthand
     --

gettext/ngettext functions
     `gettext', `dgettext', `dcgettext'

textdomain
     `textdomain' function

bindtextdomain
     `bindtextdomain' function

setlocale
     `setlocale' function

Prerequisite
     `import Locale.Gettext;'

Use or emulate GNU gettext
     use

Extractor
     --

Formatting with positions
     --

Portability
     On platforms without gettext, the functions are not available.

po-mode marking
     --

Internationalizable Data
========================

   Here is a list of other data formats which can be internationalized
using GNU gettext.

POT - Portable Object Template
------------------------------

RPMs
     gettext

File extension
     `pot', `po'

Extractor
     `xgettext'

Resource String Table
---------------------

RPMs
     fpk

File extension
     `rst'

Extractor
     `xgettext', `rstconv'

Glade - GNOME user interface description
----------------------------------------

RPMs
     glade, libglade, xml-i18n-tools

File extension
     `glade'

Extractor
     `xgettext', `libglade-xgettext'

Concluding Remarks
******************

   We would like to conclude this GNU `gettext' manual by presenting an
history of the Translation Project so far.  We finally give a few
pointers for those who want to do further research or readings about
Native Language Support matters.

History of GNU `gettext'
========================

   Internationalization concerns and algorithms have been informally
and casually discussed for years in GNU, sometimes around GNU `libc',
maybe around the incoming `Hurd', or otherwise (nobody clearly
remembers).  And even then, when the work started for real, this was
somewhat independently of these previous discussions.

   This all began in July 1994, when Patrick D'Cruze had the idea and
initiative of internationalizing version 3.9.2 of GNU `fileutils'.  He
then asked Jim Meyering, the maintainer, how to get those changes
folded into an official release.  That first draft was full of
`#ifdef's and somewhat disconcerting, and Jim wanted to find nicer
ways.  Patrick and Jim shared some tries and experimentations in this
area.  Then, feeling that this might eventually have a deeper impact on
GNU, Jim wanted to know what standards were, and contacted Richard
Stallman, who very quickly and verbally described an overall design for
what was meant to become `glocale', at that time.

   Jim implemented `glocale' and got a lot of exhausting feedback from
Patrick and Richard, of course, but also from Mitchum DSouza (who wrote
a `catgets'-like package), Roland McGrath, maybe David MacKenzie,
Franc,ois Pinard, and Paul Eggert, all pushing and pulling in various
directions, not always compatible, to the extent that after a couple of
test releases, `glocale' was torn apart.

   While Jim took some distance and time and became dad for a second
time, Roland wanted to get GNU `libc' internationalized, and got Ulrich
Drepper involved in that project.  Instead of starting from `glocale',
Ulrich rewrote something from scratch, but more conformant to the set
of guidelines who emerged out of the `glocale' effort.  Then, Ulrich
got people from the previous forum to involve themselves into this new
project, and the switch from `glocale' to what was first named
`msgutils', renamed `nlsutils', and later `gettext', became officially
accepted by Richard in May 1995 or so.

   Let's summarize by saying that Ulrich Drepper wrote GNU `gettext' in
April 1995.  The first official release of the package, including PO
mode, occurred in July 1995, and was numbered 0.7.  Other people
contributed to the effort by providing a discussion forum around
Ulrich, writing little pieces of code, or testing.  These are quoted in
the `THANKS' file which comes with the GNU `gettext' distribution.

   While this was being done, Franc,ois adapted half a dozen of GNU
packages to `glocale' first, then later to `gettext', putting them in
pretest, so providing along the way an effective user environment for
fine tuning the evolving tools.  He also took the responsibility of
organizing and coordinating the Translation Project.  After nearly a
year of informal exchanges between people from many countries,
translator teams started to exist in May 1995, through the creation and
support by Patrick D'Cruze of twenty unmoderated mailing lists for that
many native languages, and two moderated lists: one for reaching all
teams at once, the other for reaching all willing maintainers of
internationalized free software packages.

   Franc,ois also wrote PO mode in June 1995 with the collaboration of
Greg McGary, as a kind of contribution to Ulrich's package.  He also
gave a hand with the GNU `gettext' Texinfo manual.

   In 1997, Ulrich Drepper released the GNU libc 2.0, which included the
`gettext', `textdomain' and `bindtextdomain' functions.

   In 2000, Ulrich Drepper added plural form handling (the `ngettext'
function) to GNU libc.  Later, in 2001, he released GNU libc 2.2.x,
which is the first free C library with full internationalization
support.

   Ulrich being quite busy in his role of General Maintainer of GNU
libc, he handed over the GNU `gettext' maintenance to Bruno Haible in
2000.  Bruno added the plural form handling to the tools as well, added
support for UTF-8 and CJK locales, and wrote a few new tools for
manipulating PO files.

Related Readings
================

   Eugene H. Dorr (`dorre@well.com') maintains an interesting
bibliography on internationalization matters, called
`Internationalization Reference List', which is available as:
     ftp://ftp.ora.com/pub/examples/nutshell/ujip/doc/i18n-books.txt

   Michael Gschwind (`mike@vlsivie.tuwien.ac.at') maintains a
Frequently Asked Questions (FAQ) list, entitled `Programming for
Internationalisation'.  This FAQ discusses writing programs which can
handle different language conventions, character sets, etc.; and is
applicable to all character set encodings, with particular emphasis on
ISO 8859-1.  It is regularly published in Usenet groups
`comp.unix.questions', `comp.std.internat',
`comp.software.international', `comp.lang.c', `comp.windows.x',
`comp.std.c', `comp.answers' and `news.answers'.  The home location of
this document is:
     ftp://ftp.vlsivie.tuwien.ac.at/pub/8bit/ISO-programming

   Patrick D'Cruze (`pdcruze@li.org') wrote a tutorial about NLS
matters, and Jochen Hein (`Hein@student.tu-clausthal.de') took over the
responsibility of maintaining it.  It may be found as:
     ftp://sunsite.unc.edu/pub/Linux/utils/nls/catalogs/Incoming/...
          ...locale-tutorial-0.8.txt.gz

This site is mirrored in:
     ftp://ftp.ibp.fr/pub/linux/sunsite/

   A French version of the same tutorial should be findable at:
     ftp://ftp.ibp.fr/pub/linux/french/docs/

together with French translations of many Linux-related documents.

Language Codes
**************

   The ISO 639 standard defines two character codes for many languages.
All abbreviations for languages used in the Translation Project should
come from this standard.

`aa'
     Afar.

`ab'
     Abkhazian.

`ae'
     Avestan.

`af'
     Afrikaans.

`am'
     Amharic.

`ar'
     Arabic.

`as'
     Assamese.

`ay'
     Aymara.

`az'
     Azerbaijani.

`ba'
     Bashkir.

`be'
     Byelorussian; Belarusian.

`bg'
     Bulgarian.

`bh'
     Bihari.

`bi'
     Bislama.

`bn'
     Bengali; Bangla.

`bo'
     Tibetan.

`br'
     Breton.

`bs'
     Bosnian.

`ca'
     Catalan.

`ce'
     Chechen.

`ch'
     Chamorro.

`co'
     Corsican.

`cs'
     Czech.

`cu'
     Church Slavic.

`cv'
     Chuvash.

`cy'
     Welsh.

`da'
     Danish.

`de'
     German.

`dz'
     Dzongkha; Bhutani.

`el'
     Greek.

`en'
     English.

`eo'
     Esperanto.

`es'
     Spanish.

`et'
     Estonian.

`eu'
     Basque.

`fa'
     Persian.

`fi'
     Finnish.

`fj'
     Fijian; Fiji.

`fo'
     Faroese.

`fr'
     French.

`fy'
     Frisian.

`ga'
     Irish.

`gd'
     Scots; Gaelic.

`gl'
     Gallegan; Galician.

`gn'
     Guarani.

`gu'
     Gujarati.

`gv'
     Manx.

`ha'
     Hausa (?).

`he'
     Hebrew (formerly iw).

`hi'
     Hindi.

`ho'
     Hiri Motu.

`hr'
     Croatian.

`hu'
     Hungarian.

`hy'
     Armenian.

`hz'
     Herero.

`ia'
     Interlingua.

`id'
     Indonesian (formerly in).

`ie'
     Interlingue.

`ik'
     Inupiak.

`io'
     Ido.

`is'
     Icelandic.

`it'
     Italian.

`iu'
     Inuktitut.

`ja'
     Japanese.

`jv'
     Javanese.

`ka'
     Georgian.

`ki'
     Kikuyu.

`kj'
     Kuanyama.

`kk'
     Kazakh.

`kl'
     Kalaallisut; Greenlandic.

`km'
     Khmer; Cambodian.

`kn'
     Kannada.

`ko'
     Korean.

`ks'
     Kashmiri.

`ku'
     Kurdish.

`kv'
     Komi.

`kw'
     Cornish.

`ky'
     Kirghiz.

`la'
     Latin.

`lb'
     Letzeburgesch.

`ln'
     Lingala.

`lo'
     Lao; Laotian.

`lt'
     Lithuanian.

`lv'
     Latvian; Lettish.

`mg'
     Malagasy.

`mh'
     Marshall.

`mi'
     Maori.

`mk'
     Macedonian.

`ml'
     Malayalam.

`mn'
     Mongolian.

`mo'
     Moldavian.

`mr'
     Marathi.

`ms'
     Malay.

`mt'
     Maltese.

`my'
     Burmese.

`na'
     Nauru.

`nb'
     Norwegian Bokmaal.

`nd'
     Ndebele, North.

`ne'
     Nepali.

`ng'
     Ndonga.

`nl'
     Dutch.

`nn'
     Norwegian Nynorsk.

`no'
     Norwegian.

`nr'
     Ndebele, South.

`nv'
     Navajo.

`ny'
     Chichewa; Nyanja.

`oc'
     Occitan; Provenc,al.

`om'
     (Afan) Oromo.

`or'
     Oriya.

`os'
     Ossetian; Ossetic.

`pa'
     Panjabi; Punjabi.

`pi'
     Pali.

`pl'
     Polish.

`ps'
     Pashto, Pushto.

`pt'
     Portuguese.

`qu'
     Quechua.

`rm'
     Rhaeto-Romance.

`rn'
     Rundi; Kirundi.

`ro'
     Romanian.

`ru'
     Russian.

`rw'
     Kinyarwanda.

`sa'
     Sanskrit.

`sc'
     Sardinian.

`sd'
     Sindhi.

`se'
     Northern Sami.

`sg'
     Sango; Sangro.

`si'
     Sinhalese.

`sk'
     Slovak.

`sl'
     Slovenian.

`sm'
     Samoan.

`sn'
     Shona.

`so'
     Somali.

`sq'
     Albanian.

`sr'
     Serbian.

`ss'
     Swati; Siswati.

`st'
     Sesotho; Sotho, Southern.

`su'
     Sundanese.

`sv'
     Swedish.

`sw'
     Swahili.

`ta'
     Tamil.

`te'
     Telugu.

`tg'
     Tajik.

`th'
     Thai.

`ti'
     Tigrinya.

`tk'
     Turkmen.

`tl'
     Tagalog.

`tn'
     Tswana; Setswana.

`to'
     Tonga (?).

`tr'
     Turkish.

`ts'
     Tsonga.

`tt'
     Tatar.

`tw'
     Twi.

`ty'
     Tahitian.

`ug'
     Uighur.

`uk'
     Ukrainian.

`ur'
     Urdu.

`uz'
     Uzbek.

`vi'
     Vietnamese.

`vo'
     Volapu"k; Volapuk.

`wa'
     Walloon.

`wo'
     Wolof.

`xh'
     Xhosa.

`yi'
     Yiddish (formerly ji).

`yo'
     Yoruba.

`za'
     Zhuang.

`zh'
     Chinese.

`zu'
     Zulu.