cpython-lru_cache-weakref: Doc/lib/libgettext.tex annotate

annotate Doc/lib/libgettext.tex @ 21467:4e35fa5d5708 legacy-trunk

Add documentation for the help() built-in; contributed by Ka-Ping Yee. This is part of SF patch #494622.

author	Fred Drake <fdrake@acm.org>
date	Tue, 18 Dec 2001 16:31:08 +0000
parents	4b1615bf6eb0
children	1fe005c42836 48ecd6061e88

rev	line source
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	1 \section{\module{gettext} ---
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	2 Multilingual internationalization services}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	3
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	4 \declaremodule{standard}{gettext}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	5 \modulesynopsis{Multilingual internationalization services.}
15886 a7025f0709c5 Fixing author's email address. Barry Warsaw <barry@python.org> parents: 14541 diff changeset	6 \moduleauthor{Barry A. Warsaw}{barry@digicool.com}
a7025f0709c5 Fixing author's email address. Barry Warsaw <barry@python.org> parents: 14541 diff changeset	7 \sectionauthor{Barry A. Warsaw}{barry@digicool.com}
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	8
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	9
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	10 The \module{gettext} module provides internationalization (I18N) and
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	11 localization (L10N) services for your Python modules and applications.
14259 ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	12 It supports both the GNU \code{gettext} message catalog API and a
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	13 higher level, class-based API that may be more appropriate for Python
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	14 files. The interface described below allows you to write your
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	15 module and application messages in one natural language, and provide a
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	16 catalog of translated messages for running under different natural
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	17 languages.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	18
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	19 Some hints on localizing your Python modules and applications are also
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	20 given.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	21
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	22 \subsection{GNU \program{gettext} API}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	23
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	24 The \module{gettext} module defines the following API, which is very
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	25 similar to the GNU \program{gettext} API. If you use this API you
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	26 will affect the translation of your entire application globally. Often
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	27 this is what you want if your application is monolingual, with the choice
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	28 of language dependent on the locale of your user. If you are
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	29 localizing a Python module, or if your application needs to switch
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	30 languages on the fly, you probably want to use the class-based API
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	31 instead.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	32
14259 ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	33 \begin{funcdesc}{bindtextdomain}{domain\optional{, localedir}}
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	34 Bind the \var{domain} to the locale directory
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	35 \var{localedir}. More concretely, \module{gettext} will look for
14259 ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	36 binary \file{.mo} files for the given domain using the path (on \UNIX):
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	37 \file{\var{localedir}/\var{language}/LC_MESSAGES/\var{domain}.mo},
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	38 where \var{languages} is searched for in the environment variables
14259 ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	39 \envvar{LANGUAGE}, \envvar{LC_ALL}, \envvar{LC_MESSAGES}, and
ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	40 \envvar{LANG} respectively.
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	41
14259 ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	42 If \var{localedir} is omitted or \code{None}, then the current binding
ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	43 for \var{domain} is returned.\footnote{
18411 eeb2e77c5bad Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 16371 diff changeset	44 The default locale directory is system dependent; for example,
eeb2e77c5bad Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 16371 diff changeset	45 on RedHat Linux it is \file{/usr/share/locale}, but on Solaris
eeb2e77c5bad Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 16371 diff changeset	46 it is \file{/usr/lib/locale}. The \module{gettext} module
eeb2e77c5bad Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 16371 diff changeset	47 does not try to support these system dependent defaults;
eeb2e77c5bad Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 16371 diff changeset	48 instead its default is \file{\code{sys.prefix}/share/locale}.
eeb2e77c5bad Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 16371 diff changeset	49 For this reason, it is always best to call
14259 ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	50 \function{bindtextdomain()} with an explicit absolute path at
ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	51 the start of your application.}
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	52 \end{funcdesc}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	53
14259 ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	54 \begin{funcdesc}{textdomain}{\optional{domain}}
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	55 Change or query the current global domain. If \var{domain} is
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	56 \code{None}, then the current global domain is returned, otherwise the
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	57 global domain is set to \var{domain}, which is returned.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	58 \end{funcdesc}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	59
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	60 \begin{funcdesc}{gettext}{message}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	61 Return the localized translation of \var{message}, based on the
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	62 current global domain, language, and locale directory. This function
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	63 is usually aliased as \function{_} in the local namespace (see
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	64 examples below).
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	65 \end{funcdesc}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	66
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	67 \begin{funcdesc}{dgettext}{domain, message}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	68 Like \function{gettext()}, but look the message up in the specified
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	69 \var{domain}.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	70 \end{funcdesc}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	71
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	72 Note that GNU \program{gettext} also defines a \function{dcgettext()}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	73 method, but this was deemed not useful and so it is currently
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	74 unimplemented.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	75
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	76 Here's an example of typical usage for this API:
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	77
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	78 \begin{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	79 import gettext
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	80 gettext.bindtextdomain('myapplication', '/path/to/my/language/directory')
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	81 gettext.textdomain('myapplication')
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	82 _ = gettext.gettext
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	83 # ...
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	84 print _('This is a translatable string.')
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	85 \end{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	86
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	87 \subsection{Class-based API}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	88
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	89 The class-based API of the \module{gettext} module gives you more
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	90 flexibility and greater convenience than the GNU \program{gettext}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	91 API. It is the recommended way of localizing your Python applications and
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	92 modules. \module{gettext} defines a ``translations'' class which
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	93 implements the parsing of GNU \file{.mo} format files, and has methods
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	94 for returning either standard 8-bit strings or Unicode strings.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	95 Translations instances can also install themselves in the built-in
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	96 namespace as the function \function{_()}.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	97
14259 ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	98 \begin{funcdesc}{find}{domain\optional{, localedir\optional{, languages}}}
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	99 This function implements the standard \file{.mo} file search
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	100 algorithm. It takes a \var{domain}, identical to what
20536 4b1615bf6eb0 Some minor clarifications for find()'s arguments based on SF bug Barry Warsaw <barry@python.org> parents: 18411 diff changeset	101 \function{textdomain()} takes. Optional \var{localedir} is as in
4b1615bf6eb0 Some minor clarifications for find()'s arguments based on SF bug Barry Warsaw <barry@python.org> parents: 18411 diff changeset	102 \function{bindtextdomain()} Optional \var{languages} is a list of
4b1615bf6eb0 Some minor clarifications for find()'s arguments based on SF bug Barry Warsaw <barry@python.org> parents: 18411 diff changeset	103 strings, where each string is a language code.
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	104
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	105 If \var{localedir} is not given, then the default system locale
14259 ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	106 directory is used.\footnote{See the footnote for
ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	107 \function{bindtextdomain()} above.} If \var{languages} is not given,
ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	108 then the following environment variables are searched: \envvar{LANGUAGE},
ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	109 \envvar{LC_ALL}, \envvar{LC_MESSAGES}, and \envvar{LANG}. The first one
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	110 returning a non-empty value is used for the \var{languages} variable.
20536 4b1615bf6eb0 Some minor clarifications for find()'s arguments based on SF bug Barry Warsaw <barry@python.org> parents: 18411 diff changeset	111 The environment variables should contain a colon separated list of
4b1615bf6eb0 Some minor clarifications for find()'s arguments based on SF bug Barry Warsaw <barry@python.org> parents: 18411 diff changeset	112 languages, which will be split on the colon to produce the expected
4b1615bf6eb0 Some minor clarifications for find()'s arguments based on SF bug Barry Warsaw <barry@python.org> parents: 18411 diff changeset	113 list of language code strings.
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	114
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	115 \function{find()} then expands and normalizes the languages, and then
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	116 iterates through them, searching for an existing file built of these
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	117 components:
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	118
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	119 \file{\var{localedir}/\var{language}/LC_MESSAGES/\var{domain}.mo}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	120
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	121 The first such file name that exists is returned by \function{find()}.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	122 If no such file is found, then \code{None} is returned.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	123 \end{funcdesc}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	124
14259 ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	125 \begin{funcdesc}{translation}{domain\optional{, localedir\optional{,
ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	126 languages\optional{, class_}}}}
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	127 Return a \class{Translations} instance based on the \var{domain},
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	128 \var{localedir}, and \var{languages}, which are first passed to
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	129 \function{find()} to get the
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	130 associated \file{.mo} file path. Instances with
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	131 identical \file{.mo} file names are cached. The actual class instantiated
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	132 is either \var{class_} if provided, otherwise
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	133 \class{GNUTranslations}. The class's constructor must take a single
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	134 file object argument. If no \file{.mo} file is found, this
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	135 function raises \exception{IOError}.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	136 \end{funcdesc}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	137
14259 ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	138 \begin{funcdesc}{install}{domain\optional{, localedir\optional{, unicode}}}
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	139 This installs the function \function{_} in Python's builtin namespace,
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	140 based on \var{domain}, and \var{localedir} which are passed to the
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	141 function \function{translation()}. The \var{unicode} flag is passed to
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	142 the resulting translation object's \method{install} method.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	143
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	144 As seen below, you usually mark the strings in your application that are
18411 eeb2e77c5bad Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 16371 diff changeset	145 candidates for translation, by wrapping them in a call to the
eeb2e77c5bad Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 16371 diff changeset	146 \function{_()} function, like this:
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	147
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	148 \begin{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	149 print _('This string will be translated.')
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	150 \end{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	151
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	152 For convenience, you want the \function{_()} function to be installed in
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	153 Python's builtin namespace, so it is easily accessible in all modules
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	154 of your application.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	155 \end{funcdesc}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	156
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	157 \subsubsection{The \class{NullTranslations} class}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	158 Translation classes are what actually implement the translation of
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	159 original source file message strings to translated message strings.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	160 The base class used by all translation classes is
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	161 \class{NullTranslations}; this provides the basic interface you can use
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	162 to write your own specialized translation classes. Here are the
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	163 methods of \class{NullTranslations}:
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	164
14259 ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	165 \begin{methoddesc}[NullTranslations]{__init__}{\optional{fp}}
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	166 Takes an optional file object \var{fp}, which is ignored by the base
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	167 class. Initializes ``protected'' instance variables \var{_info} and
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	168 \var{_charset} which are set by derived classes. It then calls
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	169 \code{self._parse(fp)} if \var{fp} is not \code{None}.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	170 \end{methoddesc}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	171
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	172 \begin{methoddesc}[NullTranslations]{_parse}{fp}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	173 No-op'd in the base class, this method takes file object \var{fp}, and
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	174 reads the data from the file, initializing its message catalog. If
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	175 you have an unsupported message catalog file format, you should
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	176 override this method to parse your format.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	177 \end{methoddesc}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	178
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	179 \begin{methoddesc}[NullTranslations]{gettext}{message}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	180 Return the translated message. Overridden in derived classes.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	181 \end{methoddesc}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	182
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	183 \begin{methoddesc}[NullTranslations]{ugettext}{message}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	184 Return the translated message as a Unicode string. Overridden in
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	185 derived classes.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	186 \end{methoddesc}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	187
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	188 \begin{methoddesc}[NullTranslations]{info}{}
14259 ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	189 Return the ``protected'' \member{_info} variable.
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	190 \end{methoddesc}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	191
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	192 \begin{methoddesc}[NullTranslations]{charset}{}
14259 ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	193 Return the ``protected'' \member{_charset} variable.
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	194 \end{methoddesc}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	195
14259 ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	196 \begin{methoddesc}[NullTranslations]{install}{\optional{unicode}}
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	197 If the \var{unicode} flag is false, this method installs
14259 ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	198 \method{self.gettext()} into the built-in namespace, binding it to
ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	199 \samp{_}. If \var{unicode} is true, it binds \method{self.ugettext()}
ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	200 instead. By default, \var{unicode} is false.
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	201
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	202 Note that this is only one way, albeit the most convenient way, to
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	203 make the \function{_} function available to your application. Because it
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	204 affects the entire application globally, and specifically the built-in
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	205 namespace, localized modules should never install \function{_}.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	206 Instead, they should use this code to make \function{_} available to
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	207 their module:
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	208
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	209 \begin{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	210 import gettext
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	211 t = gettext.translation('mymodule', ...)
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	212 _ = t.gettext
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	213 \end{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	214
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	215 This puts \function{_} only in the module's global namespace and so
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	216 only affects calls within this module.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	217 \end{methoddesc}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	218
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	219 \subsubsection{The \class{GNUTranslations} class}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	220
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	221 The \module{gettext} module provides one additional class derived from
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	222 \class{NullTranslations}: \class{GNUTranslations}. This class
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	223 overrides \method{_parse()} to enable reading GNU \program{gettext}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	224 format \file{.mo} files in both big-endian and little-endian format.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	225
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	226 It also parses optional meta-data out of the translation catalog. It
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	227 is convention with GNU \program{gettext} to include meta-data as the
14259 ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	228 translation for the empty string. This meta-data is in \rfc{822}-style
ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	229 \code{key: value} pairs. If the key \code{Content-Type} is found,
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	230 then the \code{charset} property is used to initialize the
14259 ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	231 ``protected'' \member{_charset} instance variable. The entire set of
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	232 key/value pairs are placed into a dictionary and set as the
14259 ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	233 ``protected'' \member{_info} instance variable.
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	234
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	235 If the \file{.mo} file's magic number is invalid, or if other problems
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	236 occur while reading the file, instantiating a \class{GNUTranslations} class
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	237 can raise \exception{IOError}.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	238
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	239 The other usefully overridden method is \method{ugettext()}, which
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	240 returns a Unicode string by passing both the translated message string
14259 ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	241 and the value of the ``protected'' \member{_charset} variable to the
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	242 builtin \function{unicode()} function.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	243
14456 20aceb8edfa5 \file is not allowed in section titles -- converting to PDF fails due to Fred Drake <fdrake@acm.org> parents: 14259 diff changeset	244 \subsubsection{Solaris message catalog support}
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	245
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	246 The Solaris operating system defines its own binary
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	247 \file{.mo} file format, but since no documentation can be found on
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	248 this format, it is not supported at this time.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	249
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	250 \subsubsection{The Catalog constructor}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	251
14456 20aceb8edfa5 \file is not allowed in section titles -- converting to PDF fails due to Fred Drake <fdrake@acm.org> parents: 14259 diff changeset	252 GNOME\index{GNOME} uses a version of the \module{gettext} module by
20aceb8edfa5 \file is not allowed in section titles -- converting to PDF fails due to Fred Drake <fdrake@acm.org> parents: 14259 diff changeset	253 James Henstridge, but this version has a slightly different API. Its
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	254 documented usage was:
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	255
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	256 \begin{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	257 import gettext
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	258 cat = gettext.Catalog(domain, localedir)
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	259 _ = cat.gettext
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	260 print _('hello world')
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	261 \end{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	262
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	263 For compatibility with this older module, the function
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	264 \function{Catalog()} is an alias for the the \function{translation()}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	265 function described above.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	266
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	267 One difference between this module and Henstridge's: his catalog
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	268 objects supported access through a mapping API, but this appears to be
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	269 unused and so is not currently supported.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	270
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	271 \subsection{Internationalizing your programs and modules}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	272 Internationalization (I18N) refers to the operation by which a program
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	273 is made aware of multiple languages. Localization (L10N) refers to
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	274 the adaptation of your program, once internationalized, to the local
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	275 language and cultural habits. In order to provide multilingual
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	276 messages for your Python programs, you need to take the following
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	277 steps:
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	278
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	279 \begin{enumerate}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	280 \item prepare your program or module by specially marking
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	281 translatable strings
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	282 \item run a suite of tools over your marked files to generate raw
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	283 messages catalogs
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	284 \item create language specific translations of the message catalogs
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	285 \item use the \module{gettext} module so that message strings are
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	286 properly translated
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	287 \end{enumerate}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	288
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	289 In order to prepare your code for I18N, you need to look at all the
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	290 strings in your files. Any string that needs to be translated
18411 eeb2e77c5bad Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 16371 diff changeset	291 should be marked by wrapping it in \code{_('...')} --- that is, a call
eeb2e77c5bad Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 16371 diff changeset	292 to the function \function{_()}. For example:
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	293
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	294 \begin{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	295 filename = 'mylog.txt'
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	296 message = _('writing a log message')
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	297 fp = open(filename, 'w')
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	298 fp.write(message)
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	299 fp.close()
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	300 \end{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	301
14259 ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	302 In this example, the string \code{'writing a log message'} is marked as
ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	303 a candidate for translation, while the strings \code{'mylog.txt'} and
ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	304 \code{'w'} are not.
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	305
16371 3fe855526c55 Some rewriting of the "Internationalizing your programs and modules" Barry Warsaw <barry@python.org> parents: 15886 diff changeset	306 The Python distribution comes with two tools which help you generate
3fe855526c55 Some rewriting of the "Internationalizing your programs and modules" Barry Warsaw <barry@python.org> parents: 15886 diff changeset	307 the message catalogs once you've prepared your source code. These may
3fe855526c55 Some rewriting of the "Internationalizing your programs and modules" Barry Warsaw <barry@python.org> parents: 15886 diff changeset	308 or may not be available from a binary distribution, but they can be
3fe855526c55 Some rewriting of the "Internationalizing your programs and modules" Barry Warsaw <barry@python.org> parents: 15886 diff changeset	309 found in a source distribution, in the \file{Tools/i18n} directory.
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	310
16371 3fe855526c55 Some rewriting of the "Internationalizing your programs and modules" Barry Warsaw <barry@python.org> parents: 15886 diff changeset	311 The \program{pygettext}\footnote{Fran\c cois Pinard has
3fe855526c55 Some rewriting of the "Internationalizing your programs and modules" Barry Warsaw <barry@python.org> parents: 15886 diff changeset	312 written a program called
14541 561c0b1d514b Include a link to Francois's po-utils. Barry Warsaw <barry@python.org> parents: 14456 diff changeset	313 \program{xpot} which does a similar job. It is available as part of
561c0b1d514b Include a link to Francois's po-utils. Barry Warsaw <barry@python.org> parents: 14456 diff changeset	314 his \program{po-utils} package at
16371 3fe855526c55 Some rewriting of the "Internationalizing your programs and modules" Barry Warsaw <barry@python.org> parents: 15886 diff changeset	315 \url{http://www.iro.umontreal.ca/contrib/po-utils/HTML}.} program
3fe855526c55 Some rewriting of the "Internationalizing your programs and modules" Barry Warsaw <barry@python.org> parents: 15886 diff changeset	316 scans all your Python source code looking for the strings you
3fe855526c55 Some rewriting of the "Internationalizing your programs and modules" Barry Warsaw <barry@python.org> parents: 15886 diff changeset	317 previously marked as translatable. It is similar to the GNU
3fe855526c55 Some rewriting of the "Internationalizing your programs and modules" Barry Warsaw <barry@python.org> parents: 15886 diff changeset	318 \program{gettext} program except that it understands all the
3fe855526c55 Some rewriting of the "Internationalizing your programs and modules" Barry Warsaw <barry@python.org> parents: 15886 diff changeset	319 intricacies of Python source code, but knows nothing about C or C++
3fe855526c55 Some rewriting of the "Internationalizing your programs and modules" Barry Warsaw <barry@python.org> parents: 15886 diff changeset	320 source code. You don't need GNU \code{gettext} unless you're also
18411 eeb2e77c5bad Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 16371 diff changeset	321 going to be translating C code (such as C extension modules).
16371 3fe855526c55 Some rewriting of the "Internationalizing your programs and modules" Barry Warsaw <barry@python.org> parents: 15886 diff changeset	322
3fe855526c55 Some rewriting of the "Internationalizing your programs and modules" Barry Warsaw <barry@python.org> parents: 15886 diff changeset	323 \program{pygettext} generates textual Uniforum-style human readable
3fe855526c55 Some rewriting of the "Internationalizing your programs and modules" Barry Warsaw <barry@python.org> parents: 15886 diff changeset	324 message catalog \file{.pot} files, essentially structured human
3fe855526c55 Some rewriting of the "Internationalizing your programs and modules" Barry Warsaw <barry@python.org> parents: 15886 diff changeset	325 readable files which contain every marked string in the source code,
3fe855526c55 Some rewriting of the "Internationalizing your programs and modules" Barry Warsaw <barry@python.org> parents: 15886 diff changeset	326 along with a placeholder for the translation strings.
3fe855526c55 Some rewriting of the "Internationalizing your programs and modules" Barry Warsaw <barry@python.org> parents: 15886 diff changeset	327 \program{pygettext} is a command line script that supports a similar
3fe855526c55 Some rewriting of the "Internationalizing your programs and modules" Barry Warsaw <barry@python.org> parents: 15886 diff changeset	328 command line interface as \program{xgettext}; for details on its use,
3fe855526c55 Some rewriting of the "Internationalizing your programs and modules" Barry Warsaw <barry@python.org> parents: 15886 diff changeset	329 run:
3fe855526c55 Some rewriting of the "Internationalizing your programs and modules" Barry Warsaw <barry@python.org> parents: 15886 diff changeset	330
3fe855526c55 Some rewriting of the "Internationalizing your programs and modules" Barry Warsaw <barry@python.org> parents: 15886 diff changeset	331 \begin{verbatim}
3fe855526c55 Some rewriting of the "Internationalizing your programs and modules" Barry Warsaw <barry@python.org> parents: 15886 diff changeset	332 pygettext.py --help
3fe855526c55 Some rewriting of the "Internationalizing your programs and modules" Barry Warsaw <barry@python.org> parents: 15886 diff changeset	333 \end{verbatim}
3fe855526c55 Some rewriting of the "Internationalizing your programs and modules" Barry Warsaw <barry@python.org> parents: 15886 diff changeset	334
3fe855526c55 Some rewriting of the "Internationalizing your programs and modules" Barry Warsaw <barry@python.org> parents: 15886 diff changeset	335 Copies of these \file{.pot} files are then handed over to the
3fe855526c55 Some rewriting of the "Internationalizing your programs and modules" Barry Warsaw <barry@python.org> parents: 15886 diff changeset	336 individual human translators who write language-specific versions for
3fe855526c55 Some rewriting of the "Internationalizing your programs and modules" Barry Warsaw <barry@python.org> parents: 15886 diff changeset	337 every supported natural language. They send you back the filled in
3fe855526c55 Some rewriting of the "Internationalizing your programs and modules" Barry Warsaw <barry@python.org> parents: 15886 diff changeset	338 language-specific versions as a \file{.po} file. Using the
3fe855526c55 Some rewriting of the "Internationalizing your programs and modules" Barry Warsaw <barry@python.org> parents: 15886 diff changeset	339 \program{msgfmt.py}\footnote{\program{msgfmt.py} is binary
3fe855526c55 Some rewriting of the "Internationalizing your programs and modules" Barry Warsaw <barry@python.org> parents: 15886 diff changeset	340 compatible with GNU \program{msgfmt} except that it provides a
3fe855526c55 Some rewriting of the "Internationalizing your programs and modules" Barry Warsaw <barry@python.org> parents: 15886 diff changeset	341 simpler, all-Python implementation. With this and
3fe855526c55 Some rewriting of the "Internationalizing your programs and modules" Barry Warsaw <barry@python.org> parents: 15886 diff changeset	342 \program{pygettext.py}, you generally won't need to install the GNU
3fe855526c55 Some rewriting of the "Internationalizing your programs and modules" Barry Warsaw <barry@python.org> parents: 15886 diff changeset	343 \program{gettext} package to internationalize your Python
3fe855526c55 Some rewriting of the "Internationalizing your programs and modules" Barry Warsaw <barry@python.org> parents: 15886 diff changeset	344 applications.} program (in the \file{Tools/i18n} directory), you take the
3fe855526c55 Some rewriting of the "Internationalizing your programs and modules" Barry Warsaw <barry@python.org> parents: 15886 diff changeset	345 \file{.po} files from your translators and generate the
3fe855526c55 Some rewriting of the "Internationalizing your programs and modules" Barry Warsaw <barry@python.org> parents: 15886 diff changeset	346 machine-readable \file{.mo} binary catalog files. The \file{.mo}
3fe855526c55 Some rewriting of the "Internationalizing your programs and modules" Barry Warsaw <barry@python.org> parents: 15886 diff changeset	347 files are what the \module{gettext} module uses for the actual
3fe855526c55 Some rewriting of the "Internationalizing your programs and modules" Barry Warsaw <barry@python.org> parents: 15886 diff changeset	348 translation processing during run-time.
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	349
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	350 How you use the \module{gettext} module in your code depends on
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	351 whether you are internationalizing your entire application or a single
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	352 module.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	353
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	354 \subsubsection{Localizing your module}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	355
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	356 If you are localizing your module, you must take care not to make
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	357 global changes, e.g. to the built-in namespace. You should not use
14259 ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	358 the GNU \code{gettext} API but instead the class-based API.
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	359
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	360 Let's say your module is called ``spam'' and the module's various
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	361 natural language translation \file{.mo} files reside in
14259 ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	362 \file{/usr/share/locale} in GNU \program{gettext} format. Here's what
ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	363 you would put at the top of your module:
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	364
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	365 \begin{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	366 import gettext
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	367 t = gettext.translation('spam', '/usr/share/locale')
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	368 _ = t.gettext
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	369 \end{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	370
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	371 If your translators were providing you with Unicode strings in their
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	372 \file{.po} files, you'd instead do:
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	373
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	374 \begin{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	375 import gettext
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	376 t = gettext.translation('spam', '/usr/share/locale')
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	377 _ = t.ugettext
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	378 \end{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	379
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	380 \subsubsection{Localizing your application}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	381
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	382 If you are localizing your application, you can install the \function{_()}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	383 function globally into the built-in namespace, usually in the main driver file
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	384 of your application. This will let all your application-specific
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	385 files just use \code{_('...')} without having to explicitly install it in
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	386 each file.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	387
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	388 In the simple case then, you need only add the following bit of code
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	389 to the main driver file of your application:
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	390
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	391 \begin{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	392 import gettext
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	393 gettext.install('myapplication')
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	394 \end{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	395
14259 ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	396 If you need to set the locale directory or the \var{unicode} flag,
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	397 you can pass these into the \function{install()} function:
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	398
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	399 \begin{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	400 import gettext
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	401 gettext.install('myapplication', '/usr/share/locale', unicode=1)
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	402 \end{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	403
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	404 \subsubsection{Changing languages on the fly}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	405
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	406 If your program needs to support many languages at the same time, you
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	407 may want to create multiple translation instances and then switch
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	408 between them explicitly, like so:
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	409
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	410 \begin{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	411 import gettext
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	412
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	413 lang1 = gettext.translation(languages=['en'])
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	414 lang2 = gettext.translation(languages=['fr'])
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	415 lang3 = gettext.translation(languages=['de'])
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	416
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	417 # start by using language1
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	418 lang1.install()
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	419
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	420 # ... time goes by, user selects language 2
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	421 lang2.install()
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	422
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	423 # ... more time goes by, user selects language 3
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	424 lang3.install()
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	425 \end{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	426
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	427 \subsubsection{Deferred translations}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	428
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	429 In most coding situations, strings are translated were they are coded.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	430 Occasionally however, you need to mark strings for translation, but
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	431 defer actual translation until later. A classic example is:
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	432
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	433 \begin{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	434 animals = ['mollusk',
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	435 'albatross',
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	436 'rat',
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	437 'penguin',
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	438 'python',
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	439 ]
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	440 # ...
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	441 for a in animals:
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	442 print a
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	443 \end{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	444
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	445 Here, you want to mark the strings in the \code{animals} list as being
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	446 translatable, but you don't actually want to translate them until they
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	447 are printed.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	448
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	449 Here is one way you can handle this situation:
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	450
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	451 \begin{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	452 def _(message): return message
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	453
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	454 animals = [_('mollusk'),
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	455 _('albatross'),
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	456 _('rat'),
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	457 _('penguin'),
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	458 _('python'),
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	459 ]
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	460
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	461 del _
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	462
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	463 # ...
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	464 for a in animals:
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	465 print _(a)
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	466 \end{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	467
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	468 This works because the dummy definition of \function{_()} simply returns
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	469 the string unchanged. And this dummy definition will temporarily
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	470 override any definition of \function{_()} in the built-in namespace
14259 ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	471 (until the \keyword{del} command).
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	472 Take care, though if you have a previous definition of \function{_} in
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	473 the local namespace.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	474
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	475 Note that the second use of \function{_()} will not identify ``a'' as
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	476 being translatable to the \program{pygettext} program, since it is not
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	477 a string.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	478
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	479 Another way to handle this is with the following example:
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	480
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	481 \begin{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	482 def N_(message): return message
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	483
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	484 animals = [N_('mollusk'),
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	485 N_('albatross'),
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	486 N_('rat'),
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	487 N_('penguin'),
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	488 N_('python'),
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	489 ]
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	490
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	491 # ...
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	492 for a in animals:
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	493 print _(a)
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	494 \end{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	495
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	496 In this case, you are marking translatable strings with the function
14259 ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	497 \function{N_()},\footnote{The choice of \function{N_()} here is totally
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	498 arbitrary; it could have just as easily been
14259 ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	499 \function{MarkThisStringForTranslation()}.
ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	500 } which won't conflict with any definition of
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	501 \function{_()}. However, you will need to teach your message extraction
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	502 program to look for translatable strings marked with \function{N_()}.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	503 \program{pygettext} and \program{xpot} both support this through the
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	504 use of command line switches.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	505
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	506 \subsection{Acknowledgements}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	507
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	508 The following people contributed code, feedback, design suggestions,
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	509 previous implementations, and valuable experience to the creation of
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	510 this module:
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	511
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	512 \begin{itemize}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	513 \item Peter Funk
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	514 \item James Henstridge
14259 ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	515 \item Marc-Andr\'e Lemburg
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	516 \item Martin von L\"owis
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	517 \item Fran\c cois Pinard
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	518 \item Barry Warsaw
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	519 \end{itemize}

Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libgettext.tex @ 21467:4e35fa5d5708 legacy-trunk