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: CVS Issues,  Prev: autoconf macros,  Up: Maintainers

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'.

* Menu:

* Distributed CVS::             Avoiding version mismatch in distributed development
* Files under CVS::             Files to put under CVS version control
* autopoint Invocation::        Invoking the `autopoint' Program


File: gettext.info,  Node: Distributed CVS,  Next: Files under CVS,  Prev: CVS Issues,  Up: CVS Issues

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 *Note 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.


File: gettext.info,  Node: Files under CVS,  Next: autopoint Invocation,  Prev: Distributed CVS,  Up: CVS Issues

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
     repository 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.


File: gettext.info,  Node: autopoint Invocation,  Prev: Files under CVS,  Up: CVS Issues

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.


File: gettext.info,  Node: Programming Languages,  Next: Conclusion,  Prev: Maintainers,  Up: Top

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.

* Menu:

* Language Implementors::       The Language Implementor's View
* Programmers for other Languages::  The Programmer's View
* Translators for other Languages::  The Translator's View
* Maintainers for other Languages::  The Maintainer's View
* List of Programming Languages::  Individual Programming Languages
* List of Data Formats::        Internationalizable Data


File: gettext.info,  Node: Language Implementors,  Next: Programmers for other Languages,  Prev: Programming Languages,  Up: Programming Languages

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.  *Note 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 *Note 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).


File: gettext.info,  Node: Programmers for other Languages,  Next: Translators for other Languages,  Prev: Language Implementors,  Up: Programming Languages

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.


File: gettext.info,  Node: Translators for other Languages,  Next: Maintainers for other Languages,  Prev: Programmers for other Languages,  Up: Programming Languages

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.

* Menu:

* c-format::                    C Format Strings
* python-format::               Python Format Strings
* lisp-format::                 Lisp Format Strings
* elisp-format::                Emacs Lisp Format Strings
* librep-format::               librep Format Strings
* smalltalk-format::            Smalltalk Format Strings
* java-format::                 Java Format Strings
* awk-format::                  awk Format Strings
* object-pascal-format::        Object Pascal Format Strings
* ycp-format::                  YCP Format Strings
* tcl-format::                  Tcl Format Strings
* perl-format::                 Perl Format Strings
* php-format::                  PHP Format Strings


File: gettext.info,  Node: c-format,  Next: python-format,  Prev: Translators for other Languages,  Up: Translators for other Languages

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'.

   Although format strings with positions that reorder arguments, such
as

     "Only %2$d bytes free on '%1$s'."

which is semantically equivalent to

     "'%s' has only %d bytes free."

are a POSIX/XSI feature and not specified by ISO C 99, translators can
rely on this reordering ability: On the few platforms where `printf()',
`fprintf()' etc. don't support this feature natively, `libintl.a' or
`libintl.so' provides replacement functions, and GNU `<libintl.h>'
activates these replacement functions automatically.


File: gettext.info,  Node: python-format,  Next: lisp-format,  Prev: c-format,  Up: Translators for other Languages

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'.


File: gettext.info,  Node: lisp-format,  Next: elisp-format,  Prev: python-format,  Up: Translators for other Languages

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'.


File: gettext.info,  Node: elisp-format,  Next: librep-format,  Prev: lisp-format,  Up: Translators for other Languages

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.


File: gettext.info,  Node: librep-format,  Next: smalltalk-format,  Prev: elisp-format,  Up: Translators for other Languages

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>.


File: gettext.info,  Node: smalltalk-format,  Next: java-format,  Prev: librep-format,  Up: Translators for other Languages

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').


File: gettext.info,  Node: java-format,  Next: awk-format,  Prev: smalltalk-format,  Up: Translators for other Languages

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'.


File: gettext.info,  Node: awk-format,  Next: object-pascal-format,  Prev: java-format,  Up: Translators for other Languages

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'.


File: gettext.info,  Node: object-pascal-format,  Next: ycp-format,  Prev: awk-format,  Up: Translators for other Languages

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

   Where is this documented?


File: gettext.info,  Node: ycp-format,  Next: tcl-format,  Prev: object-pascal-format,  Up: Translators for other Languages

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').


File: gettext.info,  Node: tcl-format,  Next: perl-format,  Prev: ycp-format,  Up: Translators for other Languages

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

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


File: gettext.info,  Node: perl-format,  Next: php-format,  Prev: tcl-format,  Up: Translators for other Languages

Perl Format Strings
-------------------

   Perl format strings are described in the `Locale::TextDomain' manual
page, or in `http://let.imperia.org/howto/en/perl-i18n/'.


File: gettext.info,  Node: php-format,  Prev: perl-format,  Up: Translators for other Languages

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'.


File: gettext.info,  Node: Maintainers for other Languages,  Next: List of Programming Languages,  Prev: Translators for other Languages,  Up: Programming Languages

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' (*note 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'.


File: gettext.info,  Node: List of Programming Languages,  Next: List of Data Formats,  Prev: Maintainers for other Languages,  Up: Programming Languages

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

* Menu:

* C::                           C, C++, Objective C
* sh::                          sh - Shell Script
* bash::                        bash - Bourne-Again Shell Script
* Python::                      Python
* Common Lisp::                 GNU clisp - Common Lisp
* clisp C::                     GNU clisp C sources
* Emacs Lisp::                  Emacs Lisp
* librep::                      librep
* Smalltalk::                   GNU Smalltalk
* Java::                        Java
* gawk::                        GNU awk
* Pascal::                      Pascal - Free Pascal Compiler
* wxWindows::                   wxWindows library
* YCP::                         YCP - YaST2 scripting language
* Tcl::                         Tcl - Tk's scripting language
* Perl::                        Perl
* PHP::                         PHP Hypertext Preprocessor
* Pike::                        Pike


File: gettext.info,  Node: C,  Next: sh,  Prev: List of Programming Languages,  Up: List of 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"'
     In C++: `autosprintf "%2$d %1$d"' (*note Introduction:
     (autosprintf)Top.)

Portability
     autoconf (gettext.m4) and #if ENABLE_NLS

po-mode marking
     yes


File: gettext.info,  Node: sh,  Next: bash,  Prev: C,  Up: List of Programming Languages

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
     --


File: gettext.info,  Node: bash,  Next: Python,  Prev: sh,  Up: List of Programming Languages

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
     --


File: gettext.info,  Node: Python,  Next: Common Lisp,  Prev: bash,  Up: List of Programming Languages

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
     --


File: gettext.info,  Node: Common Lisp,  Next: clisp C,  Prev: Python,  Up: List of Programming Languages

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
     --


File: gettext.info,  Node: clisp C,  Next: Emacs Lisp,  Prev: Common Lisp,  Up: List of Programming Languages

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"'

Portability
     On platforms without gettext, no translation.

po-mode marking
     --


File: gettext.info,  Node: Emacs Lisp,  Next: librep,  Prev: clisp C,  Up: List of Programming Languages

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
     --


File: gettext.info,  Node: librep,  Next: Smalltalk,  Prev: Emacs Lisp,  Up: List of Programming Languages

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
     --


File: gettext.info,  Node: Smalltalk,  Next: Java,  Prev: librep,  Up: List of Programming Languages

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
     --


File: gettext.info,  Node: Java,  Next: gawk,  Prev: Smalltalk,  Up: List of Programming Languages

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.


File: gettext.info,  Node: gawk,  Next: Pascal,  Prev: Java,  Up: List of Programming Languages

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
     --


File: gettext.info,  Node: Pascal,  Next: wxWindows,  Prev: gawk,  Up: List of Programming Languages

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.


File: gettext.info,  Node: wxWindows,  Next: YCP,  Prev: Pascal,  Up: List of Programming Languages

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


File: gettext.info,  Node: YCP,  Next: Tcl,  Prev: wxWindows,  Up: List of Programming Languages

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
     --


File: gettext.info,  Node: Tcl,  Next: Perl,  Prev: YCP,  Up: List of Programming Languages

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.


File: gettext.info,  Node: Perl,  Next: PHP,  Prev: Tcl,  Up: List of Programming Languages

Perl
----

RPMs
     perl

File extension
     `pl', `PL', `pm', `cgi'

String syntax
        * `"abc"'

        * `'abc''

        * `qq (abc)'

        * `q (abc)'

        * `qr /abc/'

        * `qx (/bin/date)'

        * `/pattern match/'

        * `?pattern match?'

        * `s/substitution/operators/'

        * `$tied_hash{"message"}'

        * `$tied_hash_reference->{"message"}'

        * etc., issue the command `man perlsyn' for details


gettext shorthand
     `__' (double underscore)

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

textdomain
     `textdomain' function

bindtextdomain
     `bindtextdomain' function

bind_textdomain_codeset
     `bind_textdomain_codeset' function

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

Prerequisite
     `use POSIX;'
     `use Locale::TextDomain;' (included in the package libintl-perl
     which is available on the Comprehensive Perl Authors Network CPAN,
     http://www.cpan.org/).

Use or emulate GNU gettext
     emulate

Extractor
     `xgettext -k__ -k\$__ -k%__ -k__x -kN__ -k'

Formatting with positions
     `__x("error opening '[file]': [err]", file => $file, err => $!);'

Portability
     The `libintl-perl' package is platform-independent but does not
     belong to the Perl core.  The programmer is responsible for
     providing a dummy implementation of the required functions if the
     package is not installed on the target system.

po-mode marking
     --

Documentation
     In-depth documentation can be found at
     http://let.imperia.org/howto/en/perl-18n/.

   The `xgettext' parser backend for Perl differs significantly from
the parser backends for other programming languages, just as Perl
itself differs significantly from other programming languages.  The
Perl parser backend offers many more string marking facilities than the
other backends but it also has some Perl-specific limitations, the
worst probably being its imperfectness.

* Menu:

* General Problems::         General Problems Parsing Perl Code
* Default Keywords::         Which Keywords Will xgettext Look For?
* Special Keywords::         How to Extract Hash Keys
* Quote-like Expressions::   What are Strings And Quote-like Expressions?
* Interpolation I::          Invalid String Interpolation
* Interpolation II::         Valid String Interpolation
* Parentheses::              When To Use Parentheses
* Long Lines::               How To Grok with Long Lines
* Perl Pitfalls::            Bugs, Pitfalls, and Things That Do Not Work


File: gettext.info,  Node: General Problems,  Next: Default Keywords,  Up: Perl

General Problems Parsing Perl Code
..................................

   It is often heard that only Perl can parse Perl.  This is not true.
Perl cannot be _parsed_ at all, it can only be _executed_.  Perl has
various built-in ambiguities that can only be resolved at runtime.

   The following example may illustrate one common problem:

     print gettext "Hello World!";

   Although this example looks like a bullet-proof case of a function
invocation, it is not:

     open gettext, ">testfile" or die;
     print gettext "Hello world!"

   In this context, the string `gettext' looks more like a file handle.
But not necessarily:

     use Locale::Messages;
     open gettext ">testfile" or die;
     print gettext "Hello world!";

   Now, the file is probably syntactically incorrect, provided that the
module `Locale::Messages' found first in the Perl include path exports a
function `gettext'.  But what if the module `Locale::Messages' really
looks like this?

     use vars qw (*gettext);
     
     1;

   In this case, the string `gettext' will be interpreted as a file
handle again, and the above example will create a file `testfile' and
write the string "Hello world!" into it.  Even advanced control flow
analysis will not really help:

     if (0.5 < rand) {
        eval "use Sane";
     } else {
        eval "use InSane";
     }
     print gettext "Hello world!";

   If the module `Sane' exports a function `gettext' that does what we
expect, and the module `InSane' opens a file for writing and associates
the _handle_ `gettext' with this output stream, we are clueless again
about what will happen at runtime.  It is completely unpredictable.
The truth is that Perl has so many ways to fill its symbol table at
runtime that it is impossible to interpret a particular piece of code
without executing it.

   Of course, `xgettext' will not execute your Perl sources while
scanning for translatable strings, but rather use heuristics in order
to guess what you meant.

   Another problem is the ambiguity of the slash and the question mark.
Their interpretation depends on the context:

     # A pattern match.
     print "OK\n" if /foobar/;
     
     # A division.
     print 1 / 2;
     
     # Another pattern match.
     print "OK\n" if ?foobar?;
     
     # Conditional.
     print $x ? "foo" : "bar";

   The slash may either act as the division operator or introduce a
pattern match, whereas the question mark may act as the ternary
conditional operator or as a pattern match, too.  Other programming
languages like `awk' present similar problems, but the consequences of a
misinterpretation are particularly nasty with Perl sources.  In `awk'
for instance, a statement can never exceed one line and the parser can
recover from a parsing error at the next newline and interpret the rest
of the input stream correctly.  Perl is different, as a pattern match
is terminated by the next appearance of the delimiter (the slash or the
question mark) in the input stream, regardless of the semantic context.
If a slash is really a division sign but mis-interpreted as a pattern
match, the rest of the input file is most probably parsed incorrectly.

   If you find that `xgettext' fails to extract strings from portions
of your sources, you should therefore look out for slashes and/or
question marks preceding these sections.  You may have come across a
bug in the `xgettext''s Perl parser (and of course you should report
that bug).


File: gettext.info,  Node: Default Keywords,  Next: Special Keywords,  Prev: General Problems,  Up: Perl

Which keywords will xgettext look for?
......................................

   Unless you instruct `xgettext' otherwise by invoking it with one of
the options `--keyword' or `-k', it will recognize the following
keywords in your Perl sources:

   * `gettext'

   * `dgettext'

   * `dcgettext'

   * `ngettext:1,2'

     The first (singular) and the second (plural) argument will be
     extracted.

   * `dngettext:1,2'

     The first (singular) and the second (plural) argument will be
     extracted.

   * `dcngettext:1,2'

     The first (singular) and the second (plural) argument will be
     extracted.

   * `gettext_noop'

   * `%gettext'

     The keys of lookups into the hash `%gettext' will be extracted.

   * `$gettext'

     The keys of lookups into the hash reference `$gettext' will be
     extracted.



File: gettext.info,  Node: Special Keywords,  Next: Quote-like Expressions,  Prev: Default Keywords,  Up: Perl

How to Extract Hash Keys
........................

   Translating messages at runtime is normally performed by looking up
the original string in the translation database and returning the
translated version.  The "natural" Perl implementation is a hash
lookup, and, of course, `xgettext' supports such practice.

     print __"Hello world!";
     print $__{"Hello world!"};
     print $__->{"Hello world!"};
     print $$__{"Hello world!"};

   The above four lines all do the same thing.  The Perl module
`Locale::TextDomain' exports by default a hash `%__' that is tied to
the function `__()'.  It also exports a reference `$__' to `%__'.

   If an argument to the `xgettext' option `--keyword', resp. `-k'
starts with a percent sign, the rest of the keyword is interpreted as
the name of a hash.  If it starts with a dollar sign, the rest of the
keyword is interpreted as a reference to a hash.

   Note that you can omit the quotation marks (single or double) around
the hash key (almost) whenever Perl itself allows it:

     print $gettext{Error};

   The exact rule is: You can omit the surrounding quotes, when the hash
key is a valid C (!) identifier, i. e. when it starts with an
underscore or a ASCII letter and is followed by an arbitrary number of
underscores, ASCII letters or digits.  Other Unicode characters are
_not_ allowed, regardless of the `use utf8' pragma.


File: gettext.info,  Node: Quote-like Expressions,  Next: Interpolation I,  Prev: Special Keywords,  Up: Perl

What are Strings And Quote-like Expressions?
............................................

   Perl offers a plethora of different string constructs.  Those that
can be used either as arguments to functions or inside braces for hash
lookups are generally supported by `xgettext'.

   * *double-quoted strings*
          print gettext "Hello World!";

   * *single-quoted strings*
          print gettext 'Hello World!';

   * *the operator qq*
          print gettext qq |Hello World!|;
          print gettext qq <E-mail: <guido\@imperia.net>>;

     The operator `qq' is fully supported.  You can use arbitrary
     delimiters, including the four bracketing delimiters (round, angle,
     square, curly) that nest.

   * *the operator q*
          print gettext q |Hello World!|;
          print gettext q <E-mail: <guido@imperia.net>>;

     The operator `q' is fully supported.  You can use arbitrary
     delimiters, including the four bracketing delimiters (round, angle,
     square, curly) that nest.

   * *the operator qx*
          print gettext qx ;LANGUAGE=C /bin/date;
          print gettext qx [/usr/bin/ls | grep '^[A-Z]*'];

     The operator `qx' is fully supported.  You can use arbitrary
     delimiters, including the four bracketing delimiters (round, angle,
     square, curly) that nest.

     Use this feature with care!  If you use it, you lose control of the
     external code executed from within your Perl script to your
     translator!

   * *here documents*
          print gettext <<'EOF';
          program not found in $PATH
          EOF
          
          print ngettext <<EOF, <<"EOF";
          one file deleted
          EOF
          several files deleted
          EOF

     Here-documents are recognized.  If the delimiter is enclosed in
     single quotes, the string is not interpolated.  If it is enclosed
     in double quotes or has no quotes at all, the string is
     interpolated.

     Delimiters that start with a digit are not supported!


