rest25/library/gettext.rst => rest262/library/gettext.rst
92.. function:: ngettext(singular, plural, n)
93
94   Like :func:`gettext`, but consider plural forms. If a translation is found,
95   apply the plural formula to *n*, and return the resulting message (some
96   languages have more than two plural forms). If no translation is found, return
97   *singular* if *n* is 1; return *plural* otherwise.
98
99   The Plural formula is taken from the catalog header. It is a C or Python
n100-   expression that has a free variable n; the expression evaluates to the index of
n100+   expression that has a free variable *n*; the expression evaluates to the index
101-   the plural in the catalog. See the GNU gettext documentation for the precise
101+   of the plural in the catalog. See the GNU gettext documentation for the precise
102-   syntax to be used in .po files, and the formulas for a variety of languages.
102+   syntax to be used in :file:`.po` files and the formulas for a variety of
103+   languages.
103
104   .. versionadded:: 2.3
105
106
107.. function:: lngettext(singular, plural, n)
108
109   Equivalent to :func:`ngettext`, but the translation is returned in the preferred
110   system encoding, if no other encoding was explicitly set with
234
235Translation classes are what actually implement the translation of original
236source file message strings to translated message strings. The base class used
237by all translation classes is :class:`NullTranslations`; this provides the basic
238interface you can use to write your own specialized translation classes.  Here
239are the methods of :class:`NullTranslations`:
240
241
n242-.. method:: NullTranslations.__init__([fp])
n243+.. class:: NullTranslations([fp])
243
244   Takes an optional file object *fp*, which is ignored by the base class.
245   Initializes "protected" instance variables *_info* and *_charset* which are set
246   by derived classes, as well as *_fallback*, which is set through
247   :meth:`add_fallback`.  It then calls ``self._parse(fp)`` if *fp* is not
248   ``None``.
249
250
n251-.. method:: NullTranslations._parse(fp)
n252+   .. method:: _parse(fp)
252
n253-   No-op'd in the base class, this method takes file object *fp*, and reads the
n254+      No-op'd in the base class, this method takes file object *fp*, and reads
254-   data from the file, initializing its message catalog.  If you have an
255+      the data from the file, initializing its message catalog.  If you have an
255-   unsupported message catalog file format, you should override this method to
256+      unsupported message catalog file format, you should override this method
256-   parse your format.
257+      to parse your format.
257
258
n259-.. method:: NullTranslations.add_fallback(fallback)
n260+   .. method:: add_fallback(fallback)
260
n261-   Add *fallback* as the fallback object for the current translation object. A
n262+      Add *fallback* as the fallback object for the current translation
262-   translation object should consult the fallback if it cannot provide a
263+      object. A translation object should consult the fallback if it cannot provide a
263-   translation for a given message.
264+      translation for a given message.
264
265
n266-.. method:: NullTranslations.gettext(message)
n267+   .. method:: gettext(message)
267
n268-   If a fallback has been set, forward :meth:`gettext` to the fallback. Otherwise,
n269+      If a fallback has been set, forward :meth:`gettext` to the
269-   return the translated message.  Overridden in derived classes.
270+      fallback. Otherwise, return the translated message.  Overridden in derived
271+      classes.
270
271
n272-.. method:: NullTranslations.lgettext(message)
n274+   .. method:: lgettext(message)
273
n274-   If a fallback has been set, forward :meth:`lgettext` to the fallback. Otherwise,
n276+      If a fallback has been set, forward :meth:`lgettext` to the
275-   return the translated message.  Overridden in derived classes.
277+      fallback. Otherwise, return the translated message.  Overridden in derived
278+      classes.
276
n277-   .. versionadded:: 2.4
n280+      .. versionadded:: 2.4
278
279
n280-.. method:: NullTranslations.ugettext(message)
n283+   .. method:: ugettext(message)
281
n282-   If a fallback has been set, forward :meth:`ugettext` to the fallback. Otherwise,
n285+      If a fallback has been set, forward :meth:`ugettext` to the
283-   return the translated message as a Unicode string. Overridden in derived
286+      fallback. Otherwise, return the translated message as a Unicode
287+      string. Overridden in derived classes.
288+ 
289+ 
290+   .. method:: ngettext(singular, plural, n)
291+ 
292+      If a fallback has been set, forward :meth:`ngettext` to the
293+      fallback. Otherwise, return the translated message.  Overridden in derived
284-   classes.
294+      classes.
285
n286- 
287-.. method:: NullTranslations.ngettext(singular, plural, n)
288- 
289-   If a fallback has been set, forward :meth:`ngettext` to the fallback. Otherwise,
290-   return the translated message.  Overridden in derived classes.
291- 
292-   .. versionadded:: 2.3
296+      .. versionadded:: 2.3
293
294
n295-.. method:: NullTranslations.lngettext(singular, plural, n)
n299+   .. method:: lngettext(singular, plural, n)
296
n297-   If a fallback has been set, forward :meth:`ngettext` to the fallback. Otherwise,
n301+      If a fallback has been set, forward :meth:`ngettext` to the
298-   return the translated message.  Overridden in derived classes.
302+      fallback. Otherwise, return the translated message.  Overridden in derived
303+      classes.
299
n300-   .. versionadded:: 2.4
n305+      .. versionadded:: 2.4
301
302
n303-.. method:: NullTranslations.ungettext(singular, plural, n)
n308+   .. method:: ungettext(singular, plural, n)
304
n305-   If a fallback has been set, forward :meth:`ungettext` to the fallback.
n310+      If a fallback has been set, forward :meth:`ungettext` to the fallback.
306-   Otherwise, return the translated message as a Unicode string. Overridden in
311+      Otherwise, return the translated message as a Unicode string. Overridden
307-   derived classes.
312+      in derived classes.
308
n309-   .. versionadded:: 2.3
n314+      .. versionadded:: 2.3
310
311
n312-.. method:: NullTranslations.info()
n317+   .. method:: info()
313
n314-   Return the "protected" :attr:`_info` variable.
n319+      Return the "protected" :attr:`_info` variable.
315
316
n317-.. method:: NullTranslations.charset()
n322+   .. method:: charset()
318
n319-   Return the "protected" :attr:`_charset` variable.
n324+      Return the "protected" :attr:`_charset` variable.
320
321
n322-.. method:: NullTranslations.output_charset()
n327+   .. method:: output_charset()
323
n324-   Return the "protected" :attr:`_output_charset` variable, which defines the
n329+      Return the "protected" :attr:`_output_charset` variable, which defines the
325-   encoding used to return translated messages.
330+      encoding used to return translated messages.
326
n327-   .. versionadded:: 2.4
n332+      .. versionadded:: 2.4
328
329
n330-.. method:: NullTranslations.set_output_charset(charset)
n335+   .. method:: set_output_charset(charset)
331
n332-   Change the "protected" :attr:`_output_charset` variable, which defines the
n337+      Change the "protected" :attr:`_output_charset` variable, which defines the
333-   encoding used to return translated messages.
338+      encoding used to return translated messages.
334
n335-   .. versionadded:: 2.4
n340+      .. versionadded:: 2.4
336
337
n338-.. method:: NullTranslations.install([unicode [, names]])
n343+   .. method:: install([unicode [, names]])
339
n340-   If the *unicode* flag is false, this method installs :meth:`self.gettext` into
n345+      If the *unicode* flag is false, this method installs :meth:`self.gettext`
341-   the built-in namespace, binding it to ``_``.  If *unicode* is true, it binds
346+      into the built-in namespace, binding it to ``_``.  If *unicode* is true,
342-   :meth:`self.ugettext` instead.  By default, *unicode* is false.
347+      it binds :meth:`self.ugettext` instead.  By default, *unicode* is false.
343
n344-   If the *names* parameter is given, it must be a sequence containing the names of
n349+      If the *names* parameter is given, it must be a sequence containing the
345-   functions you want to install in the builtin namespace in addition to :func:`_`.
350+      names of functions you want to install in the builtin namespace in
346-   Supported names are ``'gettext'`` (bound to :meth:`self.gettext` or
351+      addition to :func:`_`.  Supported names are ``'gettext'`` (bound to
347-   :meth:`self.ugettext` according to the *unicode* flag), ``'ngettext'`` (bound to
348-   :meth:`self.ngettext` or :meth:`self.ungettext` according to the *unicode*
352+      :meth:`self.gettext` or :meth:`self.ugettext` according to the *unicode*
349-   flag), ``'lgettext'`` and ``'lngettext'``.
353+      flag), ``'ngettext'`` (bound to :meth:`self.ngettext` or
354+      :meth:`self.ungettext` according to the *unicode* flag), ``'lgettext'``
355+      and ``'lngettext'``.
350
n351-   Note that this is only one way, albeit the most convenient way, to make the
n357+      Note that this is only one way, albeit the most convenient way, to make
352-   :func:`_` function available to your application.  Because it affects the entire
358+      the :func:`_` function available to your application.  Because it affects
353-   application globally, and specifically the built-in namespace, localized modules
359+      the entire application globally, and specifically the built-in namespace,
354-   should never install :func:`_`. Instead, they should use this code to make
360+      localized modules should never install :func:`_`. Instead, they should use
355-   :func:`_` available to their module::
361+      this code to make :func:`_` available to their module::
356
n357-      import gettext
n363+         import gettext
358-      t = gettext.translation('mymodule', ...)
364+         t = gettext.translation('mymodule', ...)
359-      _ = t.gettext
365+         _ = t.gettext
360
n361-   This puts :func:`_` only in the module's global namespace and so only affects
n367+      This puts :func:`_` only in the module's global namespace and so only
362-   calls within this module.
368+      affects calls within this module.
363
n364-   .. versionchanged:: 2.5
n370+      .. versionchanged:: 2.5
365-      Added the *names* parameter.
371+         Added the *names* parameter.
366
367
368The :class:`GNUTranslations` class
369^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
370
371The :mod:`gettext` module provides one additional class derived from
372:class:`NullTranslations`: :class:`GNUTranslations`.  This class overrides
373:meth:`_parse` to enable reading GNU :program:`gettext` format :file:`.mo` files
379the translation for the empty string.  This meta-data is in :rfc:`822`\ -style
380``key: value`` pairs, and should contain the ``Project-Id-Version`` key.  If the
381key ``Content-Type`` is found, then the ``charset`` property is used to
382initialize the "protected" :attr:`_charset` instance variable, defaulting to
383``None`` if not found.  If the charset encoding is specified, then all message
384ids and message strings read from the catalog are converted to Unicode using
385this encoding.  The :meth:`ugettext` method always returns a Unicode, while the
386:meth:`gettext` returns an encoded 8-bit string.  For the message id arguments
n387-of both methods, either Unicode strings or 8-bit strings containing only US-
n393+of both methods, either Unicode strings or 8-bit strings containing only
388-ASCII characters are acceptable.  Note that the Unicode version of the methods
394+US-ASCII characters are acceptable.  Note that the Unicode version of the
389-(i.e. :meth:`ugettext` and :meth:`ungettext`) are the recommended interface to
395+methods (i.e. :meth:`ugettext` and :meth:`ungettext`) are the recommended
390-use for internationalized Python programs.
396+interface to use for internationalized Python programs.
391
392The entire set of key/value pairs are placed into a dictionary and set as the
393"protected" :attr:`_info` instance variable.
394
395If the :file:`.mo` file's magic number is invalid, or if other problems occur
396while reading the file, instantiating a :class:`GNUTranslations` class can raise
397:exc:`IOError`.
398
637^^^^^^^^^^^^^^^^^^^^^
638
639In most coding situations, strings are translated where they are coded.
640Occasionally however, you need to mark strings for translation, but defer actual
641translation until later.  A classic example is::
642
643   animals = ['mollusk',
644              'albatross',
n645-           'rat',
n651+              'rat',
646-           'penguin',
652+              'penguin',
647-           'python',
653+              'python', ]
648-           ]
649   # ...
650   for a in animals:
651       print a
652
653Here, you want to mark the strings in the ``animals`` list as being
654translatable, but you don't actually want to translate them until they are
655printed.
656
657Here is one way you can handle this situation::
658
659   def _(message): return message
660
661   animals = [_('mollusk'),
662              _('albatross'),
n663-           _('rat'),
n668+              _('rat'),
664-           _('penguin'),
669+              _('penguin'),
665-           _('python'),
670+              _('python'), ]
666-           ]
667
668   del _
669
670   # ...
671   for a in animals:
672       print _(a)
673
674This works because the dummy definition of :func:`_` simply returns the string
681translatable to the :program:`pygettext` program, since it is not a string.
682
683Another way to handle this is with the following example::
684
685   def N_(message): return message
686
687   animals = [N_('mollusk'),
688              N_('albatross'),
n689-           N_('rat'),
n693+              N_('rat'),
690-           N_('penguin'),
694+              N_('penguin'),
691-           N_('python'),
695+              N_('python'), ]
692-           ]
693
694   # ...
695   for a in animals:
696       print _(a)
697
698In this case, you are marking translatable strings with the function :func:`N_`,
699[#]_ which won't conflict with any definition of :func:`_`.  However, you will
700need to teach your message extraction program to look for translatable strings
746   The :mod:`gettext` module does not try to support these system dependent
747   defaults; instead its default is :file:`sys.prefix/share/locale`. For this
748   reason, it is always best to call :func:`bindtextdomain` with an explicit
749   absolute path at the start of your application.
750
751.. [#] See the footnote for :func:`bindtextdomain` above.
752
753.. [#] François Pinard has written a program called :program:`xpot` which does a
t754-   similar job.  It is available as part of his :program:`po-utils` package at
t757+   similar job.  It is available as part of his :program:`po-utils` package at http
755-   `<http://po-utils.progiciels-bpi.ca/>`_.
758+   ://po-utils.progiciels-bpi.ca/.
756
757.. [#] :program:`msgfmt.py` is binary compatible with GNU :program:`msgfmt` except that
758   it provides a simpler, all-Python implementation.  With this and
759   :program:`pygettext.py`, you generally won't need to install the GNU
760   :program:`gettext` package to internationalize your Python applications.
761
762.. [#] The choice of :func:`N_` here is totally arbitrary; it could have just as easily
763   been :func:`MarkThisStringForTranslation`.
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op