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!