traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Markup revisions. Nothing was actually required to be able to format it, 

but many conventions were broken.
This commit is contained in:
Fred Drake 2000-08-30 04:19:20 +00:00
parent 64dab4602e
commit d576e9df5f
1 changed files with 54 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

107
Doc/lib/libgettext.tex
View File

@ -9,7 +9,7 @@
The \module{gettext} module provides internationalization (I18N) and
localization (L10N) services for your Python modules and applications.
It supports both the GNU \program{gettext} message catalog API and a
It supports both the GNU \code{gettext} message catalog API and a
higher level, class-based API that may be more appropriate for Python
files. The interface described below allows you to write your
module and application messages in one natural language, and provide a
@ -30,27 +30,28 @@ localizing a Python module, or if your application needs to switch
languages on the fly, you probably want to use the class-based API
instead.
\begin{funcdesc}{bindtextdomain}{domain, localedir\code{=None}}
\begin{funcdesc}{bindtextdomain}{domain\optional{, localedir}}
Bind the \var{domain} to the locale directory
\var{localedir}. More concretely, \module{gettext} will look for
binary \file{.mo} files for the given domain using the path (on Unix):
binary \file{.mo} files for the given domain using the path (on \UNIX):
\file{\var{localedir}/\var{language}/LC_MESSAGES/\var{domain}.mo},
where \var{languages} is searched for in the environment variables
\code{LANGUAGE}, \code{LC_ALL}, \code{LC_MESSAGES}, and \code{LANG}
respectively.
\envvar{LANGUAGE}, \envvar{LC_ALL}, \envvar{LC_MESSAGES}, and
\envvar{LANG} respectively.
If \var{localedir} is \code{None}, then the current binding for
\var{domain} is returned\footnote{The default locale directory is system
dependent; e.g. on standard RedHat Linux it is
\file{/usr/share/locale}, but on Solaris it is
\file{/usr/lib/locale}. The \module{gettext} module does not try to
support these system dependent defaults; instead its default is
\file{\code{sys.prefix}/share/locale}. For this reason, it is always
best to call \code{gettext.bindtextdomain()} with an explicit absolute
path at the start of your application.}.
If \var{localedir} is omitted or \code{None}, then the current binding
for \var{domain} is returned.\footnote{
The default locale directory is system dependent; e.g.\ on
RedHat Linux it is \file{/usr/share/locale}, but on Solaris it
is \file{/usr/lib/locale}. The \module{gettext} module does
not try to support these system dependent defaults; instead
its default is \file{\code{sys.prefix}/share/locale}. For
this reason, it is always best to call
\function{bindtextdomain()} with an explicit absolute path at
the start of your application.}
\end{funcdesc}
\begin{funcdesc}{textdomain}{domain\code{=None}}
\begin{funcdesc}{textdomain}{\optional{domain}}
Change or query the current global domain. If \var{domain} is
\code{None}, then the current global domain is returned, otherwise the
global domain is set to \var{domain}, which is returned.
@ -94,7 +95,7 @@ for returning either standard 8-bit strings or Unicode strings.
Translations instances can also install themselves in the built-in
namespace as the function \function{_()}.
\begin{funcdesc}{find}{domain, localedir\code{=None}, languages\code{=None}}
\begin{funcdesc}{find}{domain\optional{, localedir\optional{, languages}}}
This function implements the standard \file{.mo} file search
algorithm. It takes a \var{domain}, identical to what
\function{textdomain()} takes, and optionally a \var{localedir} (as in
@ -102,10 +103,10 @@ algorithm. It takes a \var{domain}, identical to what
are strings.
If \var{localedir} is not given, then the default system locale
directory is used\footnote{See the footnote for
\function{bindtextdomain()} above.}. If \var{languages} is not given,
then the following environment variables are searched: \code{LANGUAGE},
\code{LC_ALL}, \code{LC_MESSAGES}, and \code{LANG}. The first one
directory is used.\footnote{See the footnote for
\function{bindtextdomain()} above.} If \var{languages} is not given,
then the following environment variables are searched: \envvar{LANGUAGE},
\envvar{LC_ALL}, \envvar{LC_MESSAGES}, and \envvar{LANG}. The first one
returning a non-empty value is used for the \var{languages} variable.
The environment variables can contain a colon separated list of
languages, which will be split.
@ -120,8 +121,8 @@ The first such file name that exists is returned by \function{find()}.
If no such file is found, then \code{None} is returned.
\end{funcdesc}
\begin{funcdesc}{translation}{domain, localedir\code{=None},
languages\code{=None}, class_\code{=None}}
\begin{funcdesc}{translation}{domain\optional{, localedir\optional{,
languages\optional{, class_}}}}
Return a \class{Translations} instance based on the \var{domain},
\var{localedir}, and \var{languages}, which are first passed to
\function{find()} to get the
@ -133,7 +134,7 @@ file object argument. If no \file{.mo} file is found, this
function raises \exception{IOError}.
\end{funcdesc}
\begin{funcdesc}{install}{domain, localedir\code{=None}, unicode\code{=0}}
\begin{funcdesc}{install}{domain\optional{, localedir\optional{, unicode}}}
This installs the function \function{_} in Python's builtin namespace,
based on \var{domain}, and \var{localedir} which are passed to the
function \function{translation()}. The \var{unicode} flag is passed to
@ -160,7 +161,7 @@ The base class used by all translation classes is
to write your own specialized translation classes. Here are the
methods of \class{NullTranslations}:
\begin{methoddesc}[NullTranslations]{__init__}{fp\code{=None}}
\begin{methoddesc}[NullTranslations]{__init__}{\optional{fp}}
Takes an optional file object \var{fp}, which is ignored by the base
class. Initializes ``protected'' instance variables \var{_info} and
\var{_charset} which are set by derived classes. It then calls
@ -184,18 +185,18 @@ derived classes.
\end{methoddesc}
\begin{methoddesc}[NullTranslations]{info}{}
Return the ``protected'' \var{_info} variable.
Return the ``protected'' \member{_info} variable.
\end{methoddesc}
\begin{methoddesc}[NullTranslations]{charset}{}
Return the ``protected'' \var{_charset} variable.
Return the ``protected'' \member{_charset} variable.
\end{methoddesc}
\begin{methoddesc}[NullTranslations]{install}{unicode\code{=0}}
\begin{methoddesc}[NullTranslations]{install}{\optional{unicode}}
If the \var{unicode} flag is false, this method installs
\code{self.gettext} into the built-in namespace, binding it to
\function{_}. If \var{unicode} is true, it binds \code{self.ugettext}
instead.
\method{self.gettext()} into the built-in namespace, binding it to
\samp{_}. If \var{unicode} is true, it binds \method{self.ugettext()}
instead. By default, \var{unicode} is false.
Note that this is only one way, albeit the most convenient way, to
make the \function{_} function available to your application. Because it
@ -223,12 +224,12 @@ format \file{.mo} files in both big-endian and little-endian format.
It also parses optional meta-data out of the translation catalog. It
is convention with GNU \program{gettext} to include meta-data as the
translation for the empty string. This meta-data is in RFC822-style
\code{key: value} pairs. If the key \code{Content-Type:} is found,
translation for the empty string. This meta-data is in \rfc{822}-style
\code{key: value} pairs. If the key \code{Content-Type} is found,
then the \code{charset} property is used to initialize the
``protected'' \code{_charset} instance variable. The entire set of
``protected'' \member{_charset} instance variable. The entire set of
key/value pairs are placed into a dictionary and set as the
``protected'' \code{_info} instance variable.
``protected'' \member{_info} instance variable.
If the \file{.mo} file's magic number is invalid, or if other problems
occur while reading the file, instantiating a \class{GNUTranslations} class
@ -236,7 +237,7 @@ can raise \exception{IOError}.
The other usefully overridden method is \method{ugettext()}, which
returns a Unicode string by passing both the translated message string
and the value of the ``protected'' \code{_charset} variable to the
and the value of the ``protected'' \member{_charset} variable to the
builtin \function{unicode()} function.
\subsubsection{Solaris \file{.mo} file support}
@ -297,12 +298,12 @@ fp.write(message)
fp.close()
\end{verbatim}
In this example, the string ``\code{writing a log message}'' is marked as
a candidate for translation, while the strings ``\code{mylog.txt}'' and
``\code{w}'' are not.
In this example, the string \code{'writing a log message'} is marked as
a candidate for translation, while the strings \code{'mylog.txt'} and
\code{'w'} are not.
The GNU \program{gettext} package provides a tool, called
\program{xgettext}, that scans C and C++ source code looking for these
The GNU \code{gettext} package provides a tool, called
\program{xgettext}, that scans C and \Cpp{} source code looking for these
specially marked strings. \program{xgettext} generates what are
called \file{.pot} files, essentially structured human readable files
which contain every marked string in the source code. These
@ -312,10 +313,11 @@ language-specific versions for every supported natural language.
For I18N Python programs however, \program{xgettext} won't work; it
doesn't understand the myriad of string types support by Python. The
standard Python distribution provides a tool called
\program{pygettext} that does though (found in the \file{Tools/i18n}
directory)\footnote{Fran\c cois Pinard has written a program called
\program{pygettext} that does though (found in the \file{Tools/i18n/}
directory).\footnote{Fran\c cois Pinard has written a program called
\program{xpot} which does a similar job. It is distributed separately
from the Python distribution.}. This is a command line script that
from the Python distribution.
} This is a command line script that
supports a similar interface as \program{xgettext}; see its
documentation for details. Once you've used \program{pygettext} to
create your \file{.pot} files, you can use the standard GNU
@ -330,13 +332,12 @@ module.
If you are localizing your module, you must take care not to make
global changes, e.g. to the built-in namespace. You should not use
the GNU \program{gettext} API but instead the class-based API.
the GNU \code{gettext} API but instead the class-based API.
Let's say your module is called ``spam'' and the module's various
natural language translation \file{.mo} files reside in
\file{/usr/share/locale} in GNU
\program{gettext} format. Here's what you would put at the top of
your module:
\file{/usr/share/locale} in GNU \program{gettext} format. Here's what
you would put at the top of your module:
\begin{verbatim}
import gettext
@ -369,7 +370,7 @@ import gettext
gettext.install('myapplication')
\end{verbatim}
If you need to set the locale directory or the \code{unicode} flag,
If you need to set the locale directory or the \var{unicode} flag,
you can pass these into the \function{install()} function:
\begin{verbatim}
@ -444,7 +445,7 @@ for a in animals:
This works because the dummy definition of \function{_()} simply returns
the string unchanged. And this dummy definition will temporarily
override any definition of \function{_()} in the built-in namespace
(until the \code{del} command).
(until the \keyword{del} command).
Take care, though if you have a previous definition of \function{_} in
the local namespace.
@ -470,10 +471,10 @@ for a in animals:
\end{verbatim}
In this case, you are marking translatable strings with the function
\function{N_()}\footnote{The choice of \function{N_()} here is totally
\function{N_()},\footnote{The choice of \function{N_()} here is totally
arbitrary; it could have just as easily been
\function{MarkThisStringForTranslation()}.},
which won't conflict with any definition of
\function{MarkThisStringForTranslation()}.
} which won't conflict with any definition of
\function{_()}. However, you will need to teach your message extraction
program to look for translatable strings marked with \function{N_()}.
\program{pygettext} and \program{xpot} both support this through the
@ -488,7 +489,7 @@ this module:
\begin{itemize}
\item Peter Funk
\item James Henstridge
\item Marc-Andre Lemburg
\item Marc-Andr\'e Lemburg
\item Martin von L\"owis
\item Fran\c cois Pinard
\item Barry Warsaw