diff options
Diffstat (limited to 'Doc/lib/libgettext.tex')
| -rw-r--r-- | Doc/lib/libgettext.tex | 773 |
1 files changed, 0 insertions, 773 deletions
diff --git a/Doc/lib/libgettext.tex b/Doc/lib/libgettext.tex deleted file mode 100644 index 6aee255..0000000 --- a/Doc/lib/libgettext.tex +++ /dev/null @@ -1,773 +0,0 @@ -\section{\module{gettext} --- - Multilingual internationalization services} - -\declaremodule{standard}{gettext} -\modulesynopsis{Multilingual internationalization services.} -\moduleauthor{Barry A. Warsaw}{barry@zope.com} -\sectionauthor{Barry A. Warsaw}{barry@zope.com} - - -The \module{gettext} module provides internationalization (I18N) and -localization (L10N) services for your Python modules and applications. -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 -catalog of translated messages for running under different natural -languages. - -Some hints on localizing your Python modules and applications are also -given. - -\subsection{GNU \program{gettext} API} - -The \module{gettext} module defines the following API, which is very -similar to the GNU \program{gettext} API. If you use this API you -will affect the translation of your entire application globally. Often -this is what you want if your application is monolingual, with the choice -of language dependent on the locale of your user. If you are -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\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): -\file{\var{localedir}/\var{language}/LC_MESSAGES/\var{domain}.mo}, -where \var{languages} is searched for in the environment variables -\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; for example, - 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}{bind_textdomain_codeset}{domain\optional{, codeset}} -Bind the \var{domain} to \var{codeset}, changing the encoding of -strings returned by the \function{gettext()} family of functions. -If \var{codeset} is omitted, then the current binding is returned. - -\versionadded{2.4} -\end{funcdesc} - -\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. -\end{funcdesc} - -\begin{funcdesc}{gettext}{message} -Return the localized translation of \var{message}, based on the -current global domain, language, and locale directory. This function -is usually aliased as \function{_} in the local namespace (see -examples below). -\end{funcdesc} - -\begin{funcdesc}{lgettext}{message} -Equivalent to \function{gettext()}, but the translation is returned -in the preferred system encoding, if no other encoding was explicitly -set with \function{bind_textdomain_codeset()}. - -\versionadded{2.4} -\end{funcdesc} - -\begin{funcdesc}{dgettext}{domain, message} -Like \function{gettext()}, but look the message up in the specified -\var{domain}. -\end{funcdesc} - -\begin{funcdesc}{ldgettext}{domain, message} -Equivalent to \function{dgettext()}, but the translation is returned -in the preferred system encoding, if no other encoding was explicitly -set with \function{bind_textdomain_codeset()}. - -\versionadded{2.4} -\end{funcdesc} - -\begin{funcdesc}{ngettext}{singular, plural, n} - -Like \function{gettext()}, but consider plural forms. If a translation -is found, apply the plural formula to \var{n}, and return the -resulting message (some languages have more than two plural forms). -If no translation is found, return \var{singular} if \var{n} is 1; -return \var{plural} otherwise. - -The Plural formula is taken from the catalog header. It is a C or -Python expression that has a free variable \var{n}; the expression evaluates -to the index of the plural in the catalog. See the GNU gettext -documentation for the precise syntax to be used in \file{.po} files and the -formulas for a variety of languages. - -\versionadded{2.3} - -\end{funcdesc} - -\begin{funcdesc}{lngettext}{singular, plural, n} -Equivalent to \function{ngettext()}, but the translation is returned -in the preferred system encoding, if no other encoding was explicitly -set with \function{bind_textdomain_codeset()}. - -\versionadded{2.4} -\end{funcdesc} - -\begin{funcdesc}{dngettext}{domain, singular, plural, n} -Like \function{ngettext()}, but look the message up in the specified -\var{domain}. - -\versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{ldngettext}{domain, singular, plural, n} -Equivalent to \function{dngettext()}, but the translation is returned -in the preferred system encoding, if no other encoding was explicitly -set with \function{bind_textdomain_codeset()}. - -\versionadded{2.4} -\end{funcdesc} - - - -Note that GNU \program{gettext} also defines a \function{dcgettext()} -method, but this was deemed not useful and so it is currently -unimplemented. - -Here's an example of typical usage for this API: - -\begin{verbatim} -import gettext -gettext.bindtextdomain('myapplication', '/path/to/my/language/directory') -gettext.textdomain('myapplication') -_ = gettext.gettext -# ... -print _('This is a translatable string.') -\end{verbatim} - -\subsection{Class-based API} - -The class-based API of the \module{gettext} module gives you more -flexibility and greater convenience than the GNU \program{gettext} -API. It is the recommended way of localizing your Python applications and -modules. \module{gettext} defines a ``translations'' class which -implements the parsing of GNU \file{.mo} format files, and has methods -for returning either standard 8-bit strings or Unicode strings. -Instances of this ``translations'' class can also install themselves -in the built-in namespace as the function \function{_()}. - -\begin{funcdesc}{find}{domain\optional{, localedir\optional{, - languages\optional{, all}}}} -This function implements the standard \file{.mo} file search -algorithm. It takes a \var{domain}, identical to what -\function{textdomain()} takes. Optional \var{localedir} is as in -\function{bindtextdomain()} Optional \var{languages} is a list of -strings, where each string is a language code. - -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: \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 should contain a colon separated list of -languages, which will be split on the colon to produce the expected -list of language code strings. - -\function{find()} then expands and normalizes the languages, and then -iterates through them, searching for an existing file built of these -components: - -\file{\var{localedir}/\var{language}/LC_MESSAGES/\var{domain}.mo} - -The first such file name that exists is returned by \function{find()}. -If no such file is found, then \code{None} is returned. If \var{all} -is given, it returns a list of all file names, in the order in which -they appear in the languages list or the environment variables. -\end{funcdesc} - -\begin{funcdesc}{translation}{domain\optional{, localedir\optional{, - languages\optional{, class_\optional{, - fallback\optional{, codeset}}}}}} -Return a \class{Translations} instance based on the \var{domain}, -\var{localedir}, and \var{languages}, which are first passed to -\function{find()} to get a list of the -associated \file{.mo} file paths. Instances with -identical \file{.mo} file names are cached. The actual class instantiated -is either \var{class_} if provided, otherwise -\class{GNUTranslations}. The class's constructor must take a single -file object argument. If provided, \var{codeset} will change the -charset used to encode translated strings. - -If multiple files are found, later files are used as fallbacks for -earlier ones. To allow setting the fallback, \function{copy.copy} -is used to clone each translation object from the cache; the actual -instance data is still shared with the cache. - -If no \file{.mo} file is found, this function raises -\exception{IOError} if \var{fallback} is false (which is the default), -and returns a \class{NullTranslations} instance if \var{fallback} is -true. - -\versionchanged[Added the \var{codeset} parameter]{2.4} -\end{funcdesc} - -\begin{funcdesc}{install}{domain\optional{, localedir\optional{, unicode - \optional{, codeset\optional{, names}}}}} -This installs the function \function{_} in Python's builtin namespace, -based on \var{domain}, \var{localedir}, and \var{codeset} which are -passed to the function \function{translation()}. The \var{unicode} -flag is passed to the resulting translation object's \method{install} -method. - -For the \var{names} parameter, please see the description of the -translation object's \method{install} method. - -As seen below, you usually mark the strings in your application that are -candidates for translation, by wrapping them in a call to the -\function{_()} function, like this: - -\begin{verbatim} -print _('This string will be translated.') -\end{verbatim} - -For convenience, you want the \function{_()} function to be installed in -Python's builtin namespace, so it is easily accessible in all modules -of your application. - -\versionchanged[Added the \var{codeset} parameter]{2.4} -\versionchanged[Added the \var{names} parameter]{2.5} -\end{funcdesc} - -\subsubsection{The \class{NullTranslations} class} -Translation classes are what actually implement the translation of -original source file message strings to translated message strings. -The base class used by all translation classes is -\class{NullTranslations}; this provides the basic interface you can use -to write your own specialized translation classes. Here are the -methods of \class{NullTranslations}: - -\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, as well as \var{_fallback}, -which is set through \method{add_fallback}. It then calls -\code{self._parse(fp)} if \var{fp} is not \code{None}. -\end{methoddesc} - -\begin{methoddesc}[NullTranslations]{_parse}{fp} -No-op'd in the base class, this method takes file object \var{fp}, and -reads the data from the file, initializing its message catalog. If -you have an unsupported message catalog file format, you should -override this method to parse your format. -\end{methoddesc} - -\begin{methoddesc}[NullTranslations]{add_fallback}{fallback} -Add \var{fallback} as the fallback object for the current translation -object. A translation object should consult the fallback if it cannot -provide a translation for a given message. -\end{methoddesc} - -\begin{methoddesc}[NullTranslations]{gettext}{message} -If a fallback has been set, forward \method{gettext()} to the fallback. -Otherwise, return the translated message. Overridden in derived classes. -\end{methoddesc} - -\begin{methoddesc}[NullTranslations]{lgettext}{message} -If a fallback has been set, forward \method{lgettext()} to the fallback. -Otherwise, return the translated message. Overridden in derived classes. - -\versionadded{2.4} -\end{methoddesc} - -\begin{methoddesc}[NullTranslations]{ugettext}{message} -If a fallback has been set, forward \method{ugettext()} to the fallback. -Otherwise, return the translated message as a Unicode string. -Overridden in derived classes. -\end{methoddesc} - -\begin{methoddesc}[NullTranslations]{ngettext}{singular, plural, n} -If a fallback has been set, forward \method{ngettext()} to the fallback. -Otherwise, return the translated message. Overridden in derived classes. - -\versionadded{2.3} -\end{methoddesc} - -\begin{methoddesc}[NullTranslations]{lngettext}{singular, plural, n} -If a fallback has been set, forward \method{ngettext()} to the fallback. -Otherwise, return the translated message. Overridden in derived classes. - -\versionadded{2.4} -\end{methoddesc} - -\begin{methoddesc}[NullTranslations]{ungettext}{singular, plural, n} -If a fallback has been set, forward \method{ungettext()} to the fallback. -Otherwise, return the translated message as a Unicode string. -Overridden in derived classes. - -\versionadded{2.3} -\end{methoddesc} - -\begin{methoddesc}[NullTranslations]{info}{} -Return the ``protected'' \member{_info} variable. -\end{methoddesc} - -\begin{methoddesc}[NullTranslations]{charset}{} -Return the ``protected'' \member{_charset} variable. -\end{methoddesc} - -\begin{methoddesc}[NullTranslations]{output_charset}{} -Return the ``protected'' \member{_output_charset} variable, which -defines the encoding used to return translated messages. - -\versionadded{2.4} -\end{methoddesc} - -\begin{methoddesc}[NullTranslations]{set_output_charset}{charset} -Change the ``protected'' \member{_output_charset} variable, which -defines the encoding used to return translated messages. - -\versionadded{2.4} -\end{methoddesc} - -\begin{methoddesc}[NullTranslations]{install}{\optional{unicode - \optional{, names}}} -If the \var{unicode} flag is false, this method installs -\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. - -If the \var{names} parameter is given, it must be a sequence containing -the names of functions you want to install in the builtin namespace in -addition to \function{_()}. Supported names are \code{'gettext'} (bound -to \method{self.gettext()} or \method{self.ugettext()} according to the -\var{unicode} flag), \code{'ngettext'} (bound to \method{self.ngettext()} -or \method{self.ungettext()} according to the \var{unicode} flag), -\code{'lgettext'} and \code{'lngettext'}. - -Note that this is only one way, albeit the most convenient way, to -make the \function{_} function available to your application. Because it -affects the entire application globally, and specifically the built-in -namespace, localized modules should never install \function{_}. -Instead, they should use this code to make \function{_} available to -their module: - -\begin{verbatim} -import gettext -t = gettext.translation('mymodule', ...) -_ = t.gettext -\end{verbatim} - -This puts \function{_} only in the module's global namespace and so -only affects calls within this module. - -\versionchanged[Added the \var{names} parameter]{2.5} -\end{methoddesc} - -\subsubsection{The \class{GNUTranslations} class} - -The \module{gettext} module provides one additional class derived from -\class{NullTranslations}: \class{GNUTranslations}. This class -overrides \method{_parse()} to enable reading GNU \program{gettext} -format \file{.mo} files in both big-endian and little-endian format. -It also coerces both message ids and message strings to Unicode. - -\class{GNUTranslations} 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 \rfc{822}-style \code{key: value} pairs, and should -contain the \code{Project-Id-Version} key. If the key -\code{Content-Type} is found, then the \code{charset} property is used -to initialize the ``protected'' \member{_charset} instance variable, -defaulting to \code{None} if not found. If the charset encoding is -specified, then all message ids and message strings read from the -catalog are converted to Unicode using this encoding. The -\method{ugettext()} method always returns a Unicode, while the -\method{gettext()} returns an encoded 8-bit string. For the message -id arguments of both methods, either Unicode strings or 8-bit strings -containing only US-ASCII characters are acceptable. Note that the -Unicode version of the methods (i.e. \method{ugettext()} and -\method{ungettext()}) are the recommended interface to use for -internationalized Python programs. - -The entire set of key/value pairs are placed into a dictionary and set -as the ``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 -can raise \exception{IOError}. - -The following methods are overridden from the base class implementation: - -\begin{methoddesc}[GNUTranslations]{gettext}{message} -Look up the \var{message} id in the catalog and return the -corresponding message string, as an 8-bit string encoded with the -catalog's charset encoding, if known. If there is no entry in the -catalog for the \var{message} id, and a fallback has been set, the -look up is forwarded to the fallback's \method{gettext()} method. -Otherwise, the \var{message} id is returned. -\end{methoddesc} - -\begin{methoddesc}[GNUTranslations]{lgettext}{message} -Equivalent to \method{gettext()}, but the translation is returned -in the preferred system encoding, if no other encoding was explicitly -set with \method{set_output_charset()}. - -\versionadded{2.4} -\end{methoddesc} - -\begin{methoddesc}[GNUTranslations]{ugettext}{message} -Look up the \var{message} id in the catalog and return the -corresponding message string, as a Unicode string. If there is no -entry in the catalog for the \var{message} id, and a fallback has been -set, the look up is forwarded to the fallback's \method{ugettext()} -method. Otherwise, the \var{message} id is returned. -\end{methoddesc} - -\begin{methoddesc}[GNUTranslations]{ngettext}{singular, plural, n} -Do a plural-forms lookup of a message id. \var{singular} is used as -the message id for purposes of lookup in the catalog, while \var{n} is -used to determine which plural form to use. The returned message -string is an 8-bit string encoded with the catalog's charset encoding, -if known. - -If the message id is not found in the catalog, and a fallback is -specified, the request is forwarded to the fallback's -\method{ngettext()} method. Otherwise, when \var{n} is 1 \var{singular} is -returned, and \var{plural} is returned in all other cases. - -\versionadded{2.3} -\end{methoddesc} - -\begin{methoddesc}[GNUTranslations]{lngettext}{singular, plural, n} -Equivalent to \method{gettext()}, but the translation is returned -in the preferred system encoding, if no other encoding was explicitly -set with \method{set_output_charset()}. - -\versionadded{2.4} -\end{methoddesc} - -\begin{methoddesc}[GNUTranslations]{ungettext}{singular, plural, n} -Do a plural-forms lookup of a message id. \var{singular} is used as -the message id for purposes of lookup in the catalog, while \var{n} is -used to determine which plural form to use. The returned message -string is a Unicode string. - -If the message id is not found in the catalog, and a fallback is -specified, the request is forwarded to the fallback's -\method{ungettext()} method. Otherwise, when \var{n} is 1 \var{singular} is -returned, and \var{plural} is returned in all other cases. - -Here is an example: - -\begin{verbatim} -n = len(os.listdir('.')) -cat = GNUTranslations(somefile) -message = cat.ungettext( - 'There is %(num)d file in this directory', - 'There are %(num)d files in this directory', - n) % {'num': n} -\end{verbatim} - -\versionadded{2.3} -\end{methoddesc} - -\subsubsection{Solaris message catalog support} - -The Solaris operating system defines its own binary -\file{.mo} file format, but since no documentation can be found on -this format, it is not supported at this time. - -\subsubsection{The Catalog constructor} - -GNOME\index{GNOME} uses a version of the \module{gettext} module by -James Henstridge, but this version has a slightly different API. Its -documented usage was: - -\begin{verbatim} -import gettext -cat = gettext.Catalog(domain, localedir) -_ = cat.gettext -print _('hello world') -\end{verbatim} - -For compatibility with this older module, the function -\function{Catalog()} is an alias for the \function{translation()} -function described above. - -One difference between this module and Henstridge's: his catalog -objects supported access through a mapping API, but this appears to be -unused and so is not currently supported. - -\subsection{Internationalizing your programs and modules} -Internationalization (I18N) refers to the operation by which a program -is made aware of multiple languages. Localization (L10N) refers to -the adaptation of your program, once internationalized, to the local -language and cultural habits. In order to provide multilingual -messages for your Python programs, you need to take the following -steps: - -\begin{enumerate} - \item prepare your program or module by specially marking - translatable strings - \item run a suite of tools over your marked files to generate raw - messages catalogs - \item create language specific translations of the message catalogs - \item use the \module{gettext} module so that message strings are - properly translated -\end{enumerate} - -In order to prepare your code for I18N, you need to look at all the -strings in your files. Any string that needs to be translated -should be marked by wrapping it in \code{_('...')} --- that is, a call -to the function \function{_()}. For example: - -\begin{verbatim} -filename = 'mylog.txt' -message = _('writing a log message') -fp = open(filename, 'w') -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. - -The Python distribution comes with two tools which help you generate -the message catalogs once you've prepared your source code. These may -or may not be available from a binary distribution, but they can be -found in a source distribution, in the \file{Tools/i18n} directory. - -The \program{pygettext}\footnote{Fran\c cois Pinard has -written a program called -\program{xpot} which does a similar job. It is available as part of -his \program{po-utils} package at -\url{http://po-utils.progiciels-bpi.ca/}.} program -scans all your Python source code looking for the strings you -previously marked as translatable. It is similar to the GNU -\program{gettext} program except that it understands all the -intricacies of Python source code, but knows nothing about C or \Cpp -source code. You don't need GNU \code{gettext} unless you're also -going to be translating C code (such as C extension modules). - -\program{pygettext} generates textual Uniforum-style human readable -message catalog \file{.pot} files, essentially structured human -readable files which contain every marked string in the source code, -along with a placeholder for the translation strings. -\program{pygettext} is a command line script that supports a similar -command line interface as \program{xgettext}; for details on its use, -run: - -\begin{verbatim} -pygettext.py --help -\end{verbatim} - -Copies of these \file{.pot} files are then handed over to the -individual human translators who write language-specific versions for -every supported natural language. They send you back the filled in -language-specific versions as a \file{.po} file. Using the -\program{msgfmt.py}\footnote{\program{msgfmt.py} is binary -compatible with GNU \program{msgfmt} except that it provides a -simpler, all-Python implementation. With this and -\program{pygettext.py}, you generally won't need to install the GNU -\program{gettext} package to internationalize your Python -applications.} program (in the \file{Tools/i18n} directory), you take the -\file{.po} files from your translators and generate the -machine-readable \file{.mo} binary catalog files. The \file{.mo} -files are what the \module{gettext} module uses for the actual -translation processing during run-time. - -How you use the \module{gettext} module in your code depends on -whether you are internationalizing a single module or your entire application. -The next two sections will discuss each case. - -\subsubsection{Localizing your 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 \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: - -\begin{verbatim} -import gettext -t = gettext.translation('spam', '/usr/share/locale') -_ = t.lgettext -\end{verbatim} - -If your translators were providing you with Unicode strings in their -\file{.po} files, you'd instead do: - -\begin{verbatim} -import gettext -t = gettext.translation('spam', '/usr/share/locale') -_ = t.ugettext -\end{verbatim} - -\subsubsection{Localizing your application} - -If you are localizing your application, you can install the \function{_()} -function globally into the built-in namespace, usually in the main driver file -of your application. This will let all your application-specific -files just use \code{_('...')} without having to explicitly install it in -each file. - -In the simple case then, you need only add the following bit of code -to the main driver file of your application: - -\begin{verbatim} -import gettext -gettext.install('myapplication') -\end{verbatim} - -If you need to set the locale directory or the \var{unicode} flag, -you can pass these into the \function{install()} function: - -\begin{verbatim} -import gettext -gettext.install('myapplication', '/usr/share/locale', unicode=1) -\end{verbatim} - -\subsubsection{Changing languages on the fly} - -If your program needs to support many languages at the same time, you -may want to create multiple translation instances and then switch -between them explicitly, like so: - -\begin{verbatim} -import gettext - -lang1 = gettext.translation('myapplication', languages=['en']) -lang2 = gettext.translation('myapplication', languages=['fr']) -lang3 = gettext.translation('myapplication', languages=['de']) - -# start by using language1 -lang1.install() - -# ... time goes by, user selects language 2 -lang2.install() - -# ... more time goes by, user selects language 3 -lang3.install() -\end{verbatim} - -\subsubsection{Deferred translations} - -In most coding situations, strings are translated where they are coded. -Occasionally however, you need to mark strings for translation, but -defer actual translation until later. A classic example is: - -\begin{verbatim} -animals = ['mollusk', - 'albatross', - 'rat', - 'penguin', - 'python', - ] -# ... -for a in animals: - print a -\end{verbatim} - -Here, you want to mark the strings in the \code{animals} list as being -translatable, but you don't actually want to translate them until they -are printed. - -Here is one way you can handle this situation: - -\begin{verbatim} -def _(message): return message - -animals = [_('mollusk'), - _('albatross'), - _('rat'), - _('penguin'), - _('python'), - ] - -del _ - -# ... -for a in animals: - print _(a) -\end{verbatim} - -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 \keyword{del} command). -Take care, though if you have a previous definition of \function{_} in -the local namespace. - -Note that the second use of \function{_()} will not identify ``a'' as -being translatable to the \program{pygettext} program, since it is not -a string. - -Another way to handle this is with the following example: - -\begin{verbatim} -def N_(message): return message - -animals = [N_('mollusk'), - N_('albatross'), - N_('rat'), - N_('penguin'), - N_('python'), - ] - -# ... -for a in animals: - print _(a) -\end{verbatim} - -In this case, you are marking translatable strings with the function -\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{_()}. 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 -use of command line switches. - -\subsubsection{\function{gettext()} vs. \function{lgettext()}} -In Python 2.4 the \function{lgettext()} family of functions were -introduced. The intention of these functions is to provide an -alternative which is more compliant with the current -implementation of GNU gettext. Unlike \function{gettext()}, which -returns strings encoded with the same codeset used in the -translation file, \function{lgettext()} will return strings -encoded with the preferred system encoding, as returned by -\function{locale.getpreferredencoding()}. Also notice that -Python 2.4 introduces new functions to explicitly choose -the codeset used in translated strings. If a codeset is explicitly -set, even \function{lgettext()} will return translated strings in -the requested codeset, as would be expected in the GNU gettext -implementation. - -\subsection{Acknowledgements} - -The following people contributed code, feedback, design suggestions, -previous implementations, and valuable experience to the creation of -this module: - -\begin{itemize} - \item Peter Funk - \item James Henstridge - \item Juan David Ib\'a\~nez Palomar - \item Marc-Andr\'e Lemburg - \item Martin von L\"owis - \item Fran\c cois Pinard - \item Barry Warsaw - \item Gustavo Niemeyer -\end{itemize} |