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

annotate Doc/lib/libgettext.tex @ 27998:e27f58a50737 legacy-trunk

SF bug #690377: Dud footnote reference in distutils docs

author	Raymond Hettinger <python@rcn.com>
date	Fri, 21 Feb 2003 02:47:09 +0000
parents	46bb9ad8318f
children	03bb0c408d57

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
26327 ea1d2050d7da Patch #633547: Support plural forms. Do TODOs in test suite. Martin v. Löwis <martin@v.loewis.de> parents: 23964 diff changeset	72 \begin{funcdesc}{ngettext}{singular, plural, n}
ea1d2050d7da Patch #633547: Support plural forms. Do TODOs in test suite. Martin v. Löwis <martin@v.loewis.de> parents: 23964 diff changeset	73
ea1d2050d7da Patch #633547: Support plural forms. Do TODOs in test suite. Martin v. Löwis <martin@v.loewis.de> parents: 23964 diff changeset	74 Like \function{gettext()}, but consider plural forms. If a translation
ea1d2050d7da Patch #633547: Support plural forms. Do TODOs in test suite. Martin v. Löwis <martin@v.loewis.de> parents: 23964 diff changeset	75 is found, apply the plural formula to \var{n}, and return the
ea1d2050d7da Patch #633547: Support plural forms. Do TODOs in test suite. Martin v. Löwis <martin@v.loewis.de> parents: 23964 diff changeset	76 resulting message (some languages have more than two plural forms).
ea1d2050d7da Patch #633547: Support plural forms. Do TODOs in test suite. Martin v. Löwis <martin@v.loewis.de> parents: 23964 diff changeset	77 If no translation is found, return \var{singular} if \var{n} is 1;
ea1d2050d7da Patch #633547: Support plural forms. Do TODOs in test suite. Martin v. Löwis <martin@v.loewis.de> parents: 23964 diff changeset	78 return \var{plural} otherwise.
ea1d2050d7da Patch #633547: Support plural forms. Do TODOs in test suite. Martin v. Löwis <martin@v.loewis.de> parents: 23964 diff changeset	79
ea1d2050d7da Patch #633547: Support plural forms. Do TODOs in test suite. Martin v. Löwis <martin@v.loewis.de> parents: 23964 diff changeset	80 The Plural formula is taken from the catalog header. It is a C or
ea1d2050d7da Patch #633547: Support plural forms. Do TODOs in test suite. Martin v. Löwis <martin@v.loewis.de> parents: 23964 diff changeset	81 Python expression that has a free variable n; the expression evaluates
ea1d2050d7da Patch #633547: Support plural forms. Do TODOs in test suite. Martin v. Löwis <martin@v.loewis.de> parents: 23964 diff changeset	82 to the index of the plural in the catalog. See the GNU gettext
ea1d2050d7da Patch #633547: Support plural forms. Do TODOs in test suite. Martin v. Löwis <martin@v.loewis.de> parents: 23964 diff changeset	83 documentation for the precise syntax to be used in .po files, and the
ea1d2050d7da Patch #633547: Support plural forms. Do TODOs in test suite. Martin v. Löwis <martin@v.loewis.de> parents: 23964 diff changeset	84 formulas for a variety of languages.
ea1d2050d7da Patch #633547: Support plural forms. Do TODOs in test suite. Martin v. Löwis <martin@v.loewis.de> parents: 23964 diff changeset	85
ea1d2050d7da Patch #633547: Support plural forms. Do TODOs in test suite. Martin v. Löwis <martin@v.loewis.de> parents: 23964 diff changeset	86 \versionadded{2.3}
ea1d2050d7da Patch #633547: Support plural forms. Do TODOs in test suite. Martin v. Löwis <martin@v.loewis.de> parents: 23964 diff changeset	87
ea1d2050d7da Patch #633547: Support plural forms. Do TODOs in test suite. Martin v. Löwis <martin@v.loewis.de> parents: 23964 diff changeset	88 \end{funcdesc}
ea1d2050d7da Patch #633547: Support plural forms. Do TODOs in test suite. Martin v. Löwis <martin@v.loewis.de> parents: 23964 diff changeset	89
ea1d2050d7da Patch #633547: Support plural forms. Do TODOs in test suite. Martin v. Löwis <martin@v.loewis.de> parents: 23964 diff changeset	90 \begin{funcdesc}{dngettext}{domain, singular, plural, n}
ea1d2050d7da Patch #633547: Support plural forms. Do TODOs in test suite. Martin v. Löwis <martin@v.loewis.de> parents: 23964 diff changeset	91 Like \function{ngettext()}, but look the message up in the specified
ea1d2050d7da Patch #633547: Support plural forms. Do TODOs in test suite. Martin v. Löwis <martin@v.loewis.de> parents: 23964 diff changeset	92 \var{domain}.
ea1d2050d7da Patch #633547: Support plural forms. Do TODOs in test suite. Martin v. Löwis <martin@v.loewis.de> parents: 23964 diff changeset	93
ea1d2050d7da Patch #633547: Support plural forms. Do TODOs in test suite. Martin v. Löwis <martin@v.loewis.de> parents: 23964 diff changeset	94 \versionadded{2.3}
ea1d2050d7da Patch #633547: Support plural forms. Do TODOs in test suite. Martin v. Löwis <martin@v.loewis.de> parents: 23964 diff changeset	95 \end{funcdesc}
ea1d2050d7da Patch #633547: Support plural forms. Do TODOs in test suite. Martin v. Löwis <martin@v.loewis.de> parents: 23964 diff changeset	96
ea1d2050d7da Patch #633547: Support plural forms. Do TODOs in test suite. Martin v. Löwis <martin@v.loewis.de> parents: 23964 diff changeset	97
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	98 Note that GNU \program{gettext} also defines a \function{dcgettext()}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	99 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	100 unimplemented.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	101
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	102 Here's an example of typical usage for this API:
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	103
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	104 \begin{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	105 import gettext
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	106 gettext.bindtextdomain('myapplication', '/path/to/my/language/directory')
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	107 gettext.textdomain('myapplication')
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	108 _ = gettext.gettext
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	109 # ...
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	110 print _('This is a translatable string.')
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	111 \end{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	112
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	113 \subsection{Class-based API}
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 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	116 flexibility and greater convenience than the GNU \program{gettext}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	117 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	118 modules. \module{gettext} defines a ``translations'' class which
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	119 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	120 for returning either standard 8-bit strings or Unicode strings.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	121 Translations instances can also install themselves in the built-in
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	122 namespace as the function \function{_()}.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	123
21704 7531cc592e46 Add a per-message fallback mechanism for translations. Martin v. Löwis <martin@v.loewis.de> parents: 21702 diff changeset	124 \begin{funcdesc}{find}{domain\optional{, localedir\optional{,
7531cc592e46 Add a per-message fallback mechanism for translations. Martin v. Löwis <martin@v.loewis.de> parents: 21702 diff changeset	125 languages\optional{, all}}}}
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	126 This function implements the standard \file{.mo} file search
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	127 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	128 \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	129 \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	130 strings, where each string is a language code.
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	131
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	132 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	133 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	134 \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	135 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	136 \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	137 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	138 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	139 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	140 list of language code strings.
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	141
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	142 \function{find()} then expands and normalizes the languages, and then
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	143 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	144 components:
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	145
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	146 \file{\var{localedir}/\var{language}/LC_MESSAGES/\var{domain}.mo}
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 The first such file name that exists is returned by \function{find()}.
21704 7531cc592e46 Add a per-message fallback mechanism for translations. Martin v. Löwis <martin@v.loewis.de> parents: 21702 diff changeset	149 If no such file is found, then \code{None} is returned. If \var{all}
7531cc592e46 Add a per-message fallback mechanism for translations. Martin v. Löwis <martin@v.loewis.de> parents: 21702 diff changeset	150 is given, it returns a list of all file names, in the order in which
7531cc592e46 Add a per-message fallback mechanism for translations. Martin v. Löwis <martin@v.loewis.de> parents: 21702 diff changeset	151 they appear in the languages list or the environment variables.
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	152 \end{funcdesc}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	153
14259 ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	154 \begin{funcdesc}{translation}{domain\optional{, localedir\optional{,
21702 48ecd6061e88 Add fallback argument to translation(). Request fallbacks on install. Martin v. Löwis <martin@v.loewis.de> parents: 20536 diff changeset	155 languages\optional{,
48ecd6061e88 Add fallback argument to translation(). Request fallbacks on install. Martin v. Löwis <martin@v.loewis.de> parents: 20536 diff changeset	156 class_,\optional{fallback}}}}}
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	157 Return a \class{Translations} instance based on the \var{domain},
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	158 \var{localedir}, and \var{languages}, which are first passed to
21704 7531cc592e46 Add a per-message fallback mechanism for translations. Martin v. Löwis <martin@v.loewis.de> parents: 21702 diff changeset	159 \function{find()} to get a list of the
7531cc592e46 Add a per-message fallback mechanism for translations. Martin v. Löwis <martin@v.loewis.de> parents: 21702 diff changeset	160 associated \file{.mo} file paths. Instances with
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	161 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	162 is either \var{class_} if provided, otherwise
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	163 \class{GNUTranslations}. The class's constructor must take a single
21704 7531cc592e46 Add a per-message fallback mechanism for translations. Martin v. Löwis <martin@v.loewis.de> parents: 21702 diff changeset	164 file object argument.
7531cc592e46 Add a per-message fallback mechanism for translations. Martin v. Löwis <martin@v.loewis.de> parents: 21702 diff changeset	165
7531cc592e46 Add a per-message fallback mechanism for translations. Martin v. Löwis <martin@v.loewis.de> parents: 21702 diff changeset	166 If multiple files are found, later files are used as fallbacks for
7531cc592e46 Add a per-message fallback mechanism for translations. Martin v. Löwis <martin@v.loewis.de> parents: 21702 diff changeset	167 earlier ones. To allow setting the fallback, \function{copy.copy}
7531cc592e46 Add a per-message fallback mechanism for translations. Martin v. Löwis <martin@v.loewis.de> parents: 21702 diff changeset	168 is used to clone each translation object from the cache; the actual
7531cc592e46 Add a per-message fallback mechanism for translations. Martin v. Löwis <martin@v.loewis.de> parents: 21702 diff changeset	169 instance data is still shared with the cache.
7531cc592e46 Add a per-message fallback mechanism for translations. Martin v. Löwis <martin@v.loewis.de> parents: 21702 diff changeset	170
7531cc592e46 Add a per-message fallback mechanism for translations. Martin v. Löwis <martin@v.loewis.de> parents: 21702 diff changeset	171 If no \file{.mo} file is found, this function raises
7531cc592e46 Add a per-message fallback mechanism for translations. Martin v. Löwis <martin@v.loewis.de> parents: 21702 diff changeset	172 \exception{IOError} if \var{fallback} is false (which is the default),
7531cc592e46 Add a per-message fallback mechanism for translations. Martin v. Löwis <martin@v.loewis.de> parents: 21702 diff changeset	173 and returns a \class{NullTranslations} instance if \var{fallback} is
7531cc592e46 Add a per-message fallback mechanism for translations. Martin v. Löwis <martin@v.loewis.de> parents: 21702 diff changeset	174 true.
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	175 \end{funcdesc}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	176
14259 ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	177 \begin{funcdesc}{install}{domain\optional{, localedir\optional{, unicode}}}
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	178 This installs the function \function{_} in Python's builtin namespace,
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	179 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	180 function \function{translation()}. The \var{unicode} flag is passed to
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	181 the resulting translation object's \method{install} method.
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 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	184 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	185 \function{_()} function, like this:
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	186
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	187 \begin{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	188 print _('This string will be translated.')
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	189 \end{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	190
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	191 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	192 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	193 of your application.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	194 \end{funcdesc}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	195
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	196 \subsubsection{The \class{NullTranslations} class}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	197 Translation classes are what actually implement the translation of
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	198 original source file message strings to translated message strings.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	199 The base class used by all translation classes is
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	200 \class{NullTranslations}; this provides the basic interface you can use
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	201 to write your own specialized translation classes. Here are the
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	202 methods of \class{NullTranslations}:
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	203
14259 ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	204 \begin{methoddesc}[NullTranslations]{__init__}{\optional{fp}}
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	205 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	206 class. Initializes ``protected'' instance variables \var{_info} and
21704 7531cc592e46 Add a per-message fallback mechanism for translations. Martin v. Löwis <martin@v.loewis.de> parents: 21702 diff changeset	207 \var{_charset} which are set by derived classes, as well as \var{_fallback},
7531cc592e46 Add a per-message fallback mechanism for translations. Martin v. Löwis <martin@v.loewis.de> parents: 21702 diff changeset	208 which is set through \method{add_fallback}. It then calls
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	209 \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	210 \end{methoddesc}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	211
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	212 \begin{methoddesc}[NullTranslations]{_parse}{fp}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	213 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	214 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	215 you have an unsupported message catalog file format, you should
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	216 override this method to parse your format.
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
21704 7531cc592e46 Add a per-message fallback mechanism for translations. Martin v. Löwis <martin@v.loewis.de> parents: 21702 diff changeset	219 \begin{methoddesc}{NullTranslations}{add_fallback}{fallback}
7531cc592e46 Add a per-message fallback mechanism for translations. Martin v. Löwis <martin@v.loewis.de> parents: 21702 diff changeset	220 Add \var{fallback} as the fallback object for the current translation
7531cc592e46 Add a per-message fallback mechanism for translations. Martin v. Löwis <martin@v.loewis.de> parents: 21702 diff changeset	221 object. A translation object should consult the fallback if it cannot
7531cc592e46 Add a per-message fallback mechanism for translations. Martin v. Löwis <martin@v.loewis.de> parents: 21702 diff changeset	222 provide a translation for a given message.
7531cc592e46 Add a per-message fallback mechanism for translations. Martin v. Löwis <martin@v.loewis.de> parents: 21702 diff changeset	223 \end{methoddesc}
7531cc592e46 Add a per-message fallback mechanism for translations. Martin v. Löwis <martin@v.loewis.de> parents: 21702 diff changeset	224
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	225 \begin{methoddesc}[NullTranslations]{gettext}{message}
21704 7531cc592e46 Add a per-message fallback mechanism for translations. Martin v. Löwis <martin@v.loewis.de> parents: 21702 diff changeset	226 If a fallback has been set, forward \method{gettext} to the fallback.
7531cc592e46 Add a per-message fallback mechanism for translations. Martin v. Löwis <martin@v.loewis.de> parents: 21702 diff changeset	227 Otherwise, return the translated message. Overridden in derived classes.
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	228 \end{methoddesc}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	229
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	230 \begin{methoddesc}[NullTranslations]{ugettext}{message}
21704 7531cc592e46 Add a per-message fallback mechanism for translations. Martin v. Löwis <martin@v.loewis.de> parents: 21702 diff changeset	231 If a fallback has been set, forward \method{ugettext} to the fallback.
7531cc592e46 Add a per-message fallback mechanism for translations. Martin v. Löwis <martin@v.loewis.de> parents: 21702 diff changeset	232 Otherwise, return the translated message as a Unicode string.
7531cc592e46 Add a per-message fallback mechanism for translations. Martin v. Löwis <martin@v.loewis.de> parents: 21702 diff changeset	233 Overridden in derived classes.
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	234 \end{methoddesc}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	235
26327 ea1d2050d7da Patch #633547: Support plural forms. Do TODOs in test suite. Martin v. Löwis <martin@v.loewis.de> parents: 23964 diff changeset	236 \begin{methoddesc}[NullTranslations]{ngettext}{singular, plural, n}
ea1d2050d7da Patch #633547: Support plural forms. Do TODOs in test suite. Martin v. Löwis <martin@v.loewis.de> parents: 23964 diff changeset	237 If a fallback has been set, forward \method{ngettext} to the fallback.
ea1d2050d7da Patch #633547: Support plural forms. Do TODOs in test suite. Martin v. Löwis <martin@v.loewis.de> parents: 23964 diff changeset	238 Otherwise, return the translated message. Overridden in derived classes.
ea1d2050d7da Patch #633547: Support plural forms. Do TODOs in test suite. Martin v. Löwis <martin@v.loewis.de> parents: 23964 diff changeset	239
ea1d2050d7da Patch #633547: Support plural forms. Do TODOs in test suite. Martin v. Löwis <martin@v.loewis.de> parents: 23964 diff changeset	240 \versionadded{2.3}
ea1d2050d7da Patch #633547: Support plural forms. Do TODOs in test suite. Martin v. Löwis <martin@v.loewis.de> parents: 23964 diff changeset	241 \end{methoddesc}
ea1d2050d7da Patch #633547: Support plural forms. Do TODOs in test suite. Martin v. Löwis <martin@v.loewis.de> parents: 23964 diff changeset	242
ea1d2050d7da Patch #633547: Support plural forms. Do TODOs in test suite. Martin v. Löwis <martin@v.loewis.de> parents: 23964 diff changeset	243 \begin{methoddesc}[NullTranslations]{ungettext}{singular, plural, n}
ea1d2050d7da Patch #633547: Support plural forms. Do TODOs in test suite. Martin v. Löwis <martin@v.loewis.de> parents: 23964 diff changeset	244 If a fallback has been set, forward \method{ungettext} to the fallback.
ea1d2050d7da Patch #633547: Support plural forms. Do TODOs in test suite. Martin v. Löwis <martin@v.loewis.de> parents: 23964 diff changeset	245 Otherwise, return the translated message as a Unicode string.
ea1d2050d7da Patch #633547: Support plural forms. Do TODOs in test suite. Martin v. Löwis <martin@v.loewis.de> parents: 23964 diff changeset	246 Overridden in derived classes.
ea1d2050d7da Patch #633547: Support plural forms. Do TODOs in test suite. Martin v. Löwis <martin@v.loewis.de> parents: 23964 diff changeset	247
ea1d2050d7da Patch #633547: Support plural forms. Do TODOs in test suite. Martin v. Löwis <martin@v.loewis.de> parents: 23964 diff changeset	248 \versionadded{2.3}
ea1d2050d7da Patch #633547: Support plural forms. Do TODOs in test suite. Martin v. Löwis <martin@v.loewis.de> parents: 23964 diff changeset	249 \end{methoddesc}
ea1d2050d7da Patch #633547: Support plural forms. Do TODOs in test suite. Martin v. Löwis <martin@v.loewis.de> parents: 23964 diff changeset	250
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	251 \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	252 Return the ``protected'' \member{_info} variable.
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	253 \end{methoddesc}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	254
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	255 \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	256 Return the ``protected'' \member{_charset} variable.
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	257 \end{methoddesc}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	258
14259 ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	259 \begin{methoddesc}[NullTranslations]{install}{\optional{unicode}}
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	260 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	261 \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	262 \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	263 instead. By default, \var{unicode} is false.
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	264
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	265 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	266 make the \function{_} function available to your application. Because it
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	267 affects the entire application globally, and specifically the built-in
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	268 namespace, localized modules should never install \function{_}.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	269 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	270 their module:
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	271
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	272 \begin{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	273 import gettext
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	274 t = gettext.translation('mymodule', ...)
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	275 _ = t.gettext
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	276 \end{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	277
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	278 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	279 only affects calls within this module.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	280 \end{methoddesc}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	281
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	282 \subsubsection{The \class{GNUTranslations} class}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	283
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	284 The \module{gettext} module provides one additional class derived from
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	285 \class{NullTranslations}: \class{GNUTranslations}. This class
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	286 overrides \method{_parse()} to enable reading GNU \program{gettext}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	287 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	288
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	289 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	290 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	291 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	292 \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	293 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	294 ``protected'' \member{_charset} instance variable. The entire set of
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	295 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	296 ``protected'' \member{_info} instance variable.
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	297
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	298 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	299 occur while reading the file, instantiating a \class{GNUTranslations} class
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	300 can raise \exception{IOError}.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	301
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	302 The other usefully overridden method is \method{ugettext()}, which
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	303 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	304 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	305 builtin \function{unicode()} function.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	306
26327 ea1d2050d7da Patch #633547: Support plural forms. Do TODOs in test suite. Martin v. Löwis <martin@v.loewis.de> parents: 23964 diff changeset	307 To facilitate plural forms, the methods \method{ngettext} and
ea1d2050d7da Patch #633547: Support plural forms. Do TODOs in test suite. Martin v. Löwis <martin@v.loewis.de> parents: 23964 diff changeset	308 \method{ungettext} are overridden as well.
ea1d2050d7da Patch #633547: Support plural forms. Do TODOs in test suite. Martin v. Löwis <martin@v.loewis.de> parents: 23964 diff changeset	309
14456 20aceb8edfa5 \file is not allowed in section titles -- converting to PDF fails due to Fred Drake <fdrake@acm.org> parents: 14259 diff changeset	310 \subsubsection{Solaris message catalog support}
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	311
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	312 The Solaris operating system defines its own binary
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	313 \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	314 this format, it is not supported at this time.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	315
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	316 \subsubsection{The Catalog constructor}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	317
14456 20aceb8edfa5 \file is not allowed in section titles -- converting to PDF fails due to Fred Drake <fdrake@acm.org> parents: 14259 diff changeset	318 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	319 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	320 documented usage was:
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	321
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	322 \begin{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	323 import gettext
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	324 cat = gettext.Catalog(domain, localedir)
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	325 _ = cat.gettext
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	326 print _('hello world')
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	327 \end{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	328
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	329 For compatibility with this older module, the function
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	330 \function{Catalog()} is an alias for the the \function{translation()}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	331 function described above.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	332
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	333 One difference between this module and Henstridge's: his catalog
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	334 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	335 unused and so is not currently supported.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	336
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	337 \subsection{Internationalizing your programs and modules}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	338 Internationalization (I18N) refers to the operation by which a program
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	339 is made aware of multiple languages. Localization (L10N) refers to
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	340 the adaptation of your program, once internationalized, to the local
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	341 language and cultural habits. In order to provide multilingual
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	342 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	343 steps:
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	344
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	345 \begin{enumerate}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	346 \item prepare your program or module by specially marking
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	347 translatable strings
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	348 \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	349 messages catalogs
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	350 \item create language specific translations of the message catalogs
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	351 \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	352 properly translated
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	353 \end{enumerate}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	354
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	355 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	356 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	357 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	358 to the function \function{_()}. For example:
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 \begin{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	361 filename = 'mylog.txt'
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	362 message = _('writing a log message')
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	363 fp = open(filename, 'w')
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	364 fp.write(message)
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	365 fp.close()
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	366 \end{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	367
14259 ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	368 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	369 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	370 \code{'w'} are not.
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	371
16371 3fe855526c55 Some rewriting of the "Internationalizing your programs and modules" Barry Warsaw <barry@python.org> parents: 15886 diff changeset	372 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	373 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	374 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	375 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	376
16371 3fe855526c55 Some rewriting of the "Internationalizing your programs and modules" Barry Warsaw <barry@python.org> parents: 15886 diff changeset	377 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	378 written a program called
14541 561c0b1d514b Include a link to Francois's po-utils. Barry Warsaw <barry@python.org> parents: 14456 diff changeset	379 \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	380 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	381 \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	382 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	383 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	384 \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	385 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	386 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	387 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	388
3fe855526c55 Some rewriting of the "Internationalizing your programs and modules" Barry Warsaw <barry@python.org> parents: 15886 diff changeset	389 \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	390 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	391 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	392 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	393 \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	394 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	395 run:
3fe855526c55 Some rewriting of the "Internationalizing your programs and modules" Barry Warsaw <barry@python.org> parents: 15886 diff changeset	396
3fe855526c55 Some rewriting of the "Internationalizing your programs and modules" Barry Warsaw <barry@python.org> parents: 15886 diff changeset	397 \begin{verbatim}
3fe855526c55 Some rewriting of the "Internationalizing your programs and modules" Barry Warsaw <barry@python.org> parents: 15886 diff changeset	398 pygettext.py --help
3fe855526c55 Some rewriting of the "Internationalizing your programs and modules" Barry Warsaw <barry@python.org> parents: 15886 diff changeset	399 \end{verbatim}
3fe855526c55 Some rewriting of the "Internationalizing your programs and modules" Barry Warsaw <barry@python.org> parents: 15886 diff changeset	400
3fe855526c55 Some rewriting of the "Internationalizing your programs and modules" Barry Warsaw <barry@python.org> parents: 15886 diff changeset	401 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	402 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	403 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	404 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	405 \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	406 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	407 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	408 \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	409 \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	410 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	411 \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	412 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	413 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	414 translation processing during run-time.
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	415
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	416 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	417 whether you are internationalizing your entire application or a single
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	418 module.
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 \subsubsection{Localizing your module}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	421
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	422 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	423 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	424 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	425
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	426 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	427 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	428 \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	429 you would put at the top of your module:
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	430
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	431 \begin{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	432 import gettext
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	433 t = gettext.translation('spam', '/usr/share/locale')
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	434 _ = t.gettext
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	435 \end{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	436
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	437 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	438 \file{.po} files, you'd instead do:
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 \begin{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	441 import gettext
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	442 t = gettext.translation('spam', '/usr/share/locale')
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	443 _ = t.ugettext
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	444 \end{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	445
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	446 \subsubsection{Localizing your application}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	447
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	448 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	449 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	450 of your application. This will let all your application-specific
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	451 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	452 each file.
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 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	455 to the main driver file of your application:
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	456
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	457 \begin{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	458 import gettext
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	459 gettext.install('myapplication')
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	460 \end{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	461
14259 ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	462 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	463 you can pass these into the \function{install()} function:
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	464
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	465 \begin{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	466 import gettext
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	467 gettext.install('myapplication', '/usr/share/locale', unicode=1)
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	468 \end{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	469
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	470 \subsubsection{Changing languages on the fly}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	471
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	472 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	473 may want to create multiple translation instances and then switch
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	474 between them explicitly, like so:
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	475
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	476 \begin{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	477 import gettext
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 lang1 = gettext.translation(languages=['en'])
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	480 lang2 = gettext.translation(languages=['fr'])
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	481 lang3 = gettext.translation(languages=['de'])
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	482
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	483 # start by using language1
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	484 lang1.install()
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	485
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	486 # ... time goes by, user selects language 2
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	487 lang2.install()
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	488
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	489 # ... more time goes by, user selects language 3
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	490 lang3.install()
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	491 \end{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	492
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	493 \subsubsection{Deferred translations}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	494
23964 f7e191c8db23 SF # 572928 One word change for lib/libgettext.tex Neal Norwitz <nnorwitz@gmail.com> parents: 21704 diff changeset	495 In most coding situations, strings are translated where they are coded.
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	496 Occasionally however, you need to mark strings for translation, but
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	497 defer actual translation until later. A classic example is:
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	498
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	499 \begin{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	500 animals = ['mollusk',
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	501 'albatross',
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	502 'rat',
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	503 'penguin',
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	504 'python',
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 # ...
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	507 for a in animals:
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	508 print a
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	509 \end{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	510
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	511 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	512 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	513 are printed.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	514
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	515 Here is one way you can handle this situation:
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	516
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	517 \begin{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	518 def _(message): return message
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	519
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	520 animals = [_('mollusk'),
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	521 _('albatross'),
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	522 _('rat'),
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	523 _('penguin'),
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	524 _('python'),
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	525 ]
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	526
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	527 del _
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	528
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	529 # ...
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	530 for a in animals:
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	531 print _(a)
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	532 \end{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	533
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	534 This works because the dummy definition of \function{_()} simply returns
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	535 the string unchanged. And this dummy definition will temporarily
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	536 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	537 (until the \keyword{del} command).
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	538 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	539 the local namespace.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	540
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	541 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	542 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	543 a string.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	544
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	545 Another way to handle this is with the following example:
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	546
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	547 \begin{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	548 def N_(message): return message
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	549
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	550 animals = [N_('mollusk'),
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	551 N_('albatross'),
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	552 N_('rat'),
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	553 N_('penguin'),
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	554 N_('python'),
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	555 ]
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	556
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	557 # ...
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	558 for a in animals:
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	559 print _(a)
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	560 \end{verbatim}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	561
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	562 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	563 \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	564 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	565 \function{MarkThisStringForTranslation()}.
ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	566 } which won't conflict with any definition of
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	567 \function{_()}. However, you will need to teach your message extraction
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	568 program to look for translatable strings marked with \function{N_()}.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	569 \program{pygettext} and \program{xpot} both support this through the
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	570 use of command line switches.
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	571
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	572 \subsection{Acknowledgements}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	573
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	574 The following people contributed code, feedback, design suggestions,
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	575 previous implementations, and valuable experience to the creation of
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	576 this module:
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	577
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	578 \begin{itemize}
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	579 \item Peter Funk
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	580 \item James Henstridge
26348 46bb9ad8318f Fix markup. Fred Drake <fdrake@acm.org> parents: 26327 diff changeset	581 \item Juan David Ib\'a\~nez Palomar
14259 ae275644457b Markup revisions. Nothing was actually required to be able to format it, Fred Drake <fdrake@acm.org> parents: 14254 diff changeset	582 \item Marc-Andr\'e Lemburg
14253 7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	583 \item Martin von L\"owis
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	584 \item Fran\c cois Pinard
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	585 \item Barry Warsaw
7459159ba249 Documentation for the gettext module. Barry Warsaw <barry@python.org> parents: diff changeset	586 \end{itemize}

Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libgettext.tex @ 27998:e27f58a50737 legacy-trunk