diff options
Diffstat (limited to 'Doc/lib/libgettext.tex')
| -rw-r--r-- | Doc/lib/libgettext.tex | 109 |
1 files changed, 55 insertions, 54 deletions
diff --git a/Doc/lib/libgettext.tex b/Doc/lib/libgettext.tex index 5f56d04..e1a6c47 100644 --- a/Doc/lib/libgettext.tex +++ b/Doc/lib/libgettext.tex @@ -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. - -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.}. +\envvar{LANGUAGE}, \envvar{LC_ALL}, \envvar{LC_MESSAGES}, and +\envvar{LANG} respectively. + +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 |