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