Doc/lib/libgettext.tex

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