| |
| Translation classes are what actually implement the translation of original |
| source file message strings to translated message strings. The base class used |
| by all translation classes is :class:`NullTranslations`; this provides the basic |
| interface you can use to write your own specialized translation classes. Here |
| are the methods of :class:`NullTranslations`: |
| |
| |
n | .. method:: NullTranslations.__init__([fp]) |
n | .. class:: NullTranslations([fp]) |
| |
| Takes an optional file object *fp*, which is ignored by the base class. |
| Initializes "protected" instance variables *_info* and *_charset* which are set |
| by derived classes, as well as *_fallback*, which is set through |
| :meth:`add_fallback`. It then calls ``self._parse(fp)`` if *fp* is not |
| ``None``. |
| |
| |
n | .. method:: NullTranslations._parse(fp) |
n | .. method:: _parse(fp) |
| |
n | No-op'd in the base class, this method takes file object *fp*, and reads the |
n | No-op'd in the base class, this method takes file object *fp*, and reads |
| data from the file, initializing its message catalog. If you have an |
| the data from the file, initializing its message catalog. If you have an |
| unsupported message catalog file format, you should override this method to |
| unsupported message catalog file format, you should override this method |
| parse your format. |
| to parse your format. |
| |
| |
n | .. method:: NullTranslations.add_fallback(fallback) |
n | .. method:: add_fallback(fallback) |
| |
n | Add *fallback* as the fallback object for the current translation object. A |
n | Add *fallback* as the fallback object for the current translation |
| translation object should consult the fallback if it cannot provide a |
| object. A translation object should consult the fallback if it cannot provide a |
| translation for a given message. |
| translation for a given message. |
| |
| |
n | .. method:: NullTranslations.gettext(message) |
n | .. method:: gettext(message) |
| |
n | If a fallback has been set, forward :meth:`gettext` to the fallback. Otherwise, |
n | If a fallback has been set, forward :meth:`gettext` to the |
| return the translated message. Overridden in derived classes. |
| fallback. Otherwise, return the translated message. Overridden in derived |
| classes. |
| |
| |
n | .. method:: NullTranslations.lgettext(message) |
n | .. method:: lgettext(message) |
| |
n | If a fallback has been set, forward :meth:`lgettext` to the fallback. Otherwise, |
n | If a fallback has been set, forward :meth:`lgettext` to the |
| return the translated message. Overridden in derived classes. |
| fallback. Otherwise, return the translated message. Overridden in derived |
| classes. |
| |
n | .. versionadded:: 2.4 |
n | .. versionadded:: 2.4 |
| |
| |
n | .. method:: NullTranslations.ugettext(message) |
n | .. method:: ugettext(message) |
| |
n | If a fallback has been set, forward :meth:`ugettext` to the fallback. Otherwise, |
n | If a fallback has been set, forward :meth:`ugettext` to the |
| return the translated message as a Unicode string. Overridden in derived |
| fallback. Otherwise, return the translated message as a Unicode |
| string. Overridden in derived classes. |
| |
| |
| .. method:: ngettext(singular, plural, n) |
| |
| If a fallback has been set, forward :meth:`ngettext` to the |
| fallback. Otherwise, return the translated message. Overridden in derived |
| classes. |
| classes. |
| |
n | |
| .. method:: NullTranslations.ngettext(singular, plural, n) |
| |
| If a fallback has been set, forward :meth:`ngettext` to the fallback. Otherwise, |
| return the translated message. Overridden in derived classes. |
| |
| .. versionadded:: 2.3 |
| .. versionadded:: 2.3 |
| |
| |
n | .. method:: NullTranslations.lngettext(singular, plural, n) |
n | .. method:: lngettext(singular, plural, n) |
| |
n | If a fallback has been set, forward :meth:`ngettext` to the fallback. Otherwise, |
n | If a fallback has been set, forward :meth:`ngettext` to the |
| return the translated message. Overridden in derived classes. |
| fallback. Otherwise, return the translated message. Overridden in derived |
| classes. |
| |
n | .. versionadded:: 2.4 |
n | .. versionadded:: 2.4 |
| |
| |
n | .. method:: NullTranslations.ungettext(singular, plural, n) |
n | .. method:: ungettext(singular, plural, n) |
| |
n | If a fallback has been set, forward :meth:`ungettext` to the fallback. |
n | If a fallback has been set, forward :meth:`ungettext` to the fallback. |
| Otherwise, return the translated message as a Unicode string. Overridden in |
| Otherwise, return the translated message as a Unicode string. Overridden |
| derived classes. |
| in derived classes. |
| |
n | .. versionadded:: 2.3 |
n | .. versionadded:: 2.3 |
| |
| |
n | .. method:: NullTranslations.info() |
n | .. method:: info() |
| |
n | Return the "protected" :attr:`_info` variable. |
n | Return the "protected" :attr:`_info` variable. |
| |
| |
n | .. method:: NullTranslations.charset() |
n | .. method:: charset() |
| |
n | Return the "protected" :attr:`_charset` variable. |
n | Return the "protected" :attr:`_charset` variable. |
| |
| |
n | .. method:: NullTranslations.output_charset() |
n | .. method:: output_charset() |
| |
n | Return the "protected" :attr:`_output_charset` variable, which defines the |
n | Return the "protected" :attr:`_output_charset` variable, which defines the |
| encoding used to return translated messages. |
| encoding used to return translated messages. |
| |
n | .. versionadded:: 2.4 |
n | .. versionadded:: 2.4 |
| |
| |
n | .. method:: NullTranslations.set_output_charset(charset) |
n | .. method:: set_output_charset(charset) |
| |
n | Change the "protected" :attr:`_output_charset` variable, which defines the |
n | Change the "protected" :attr:`_output_charset` variable, which defines the |
| encoding used to return translated messages. |
| encoding used to return translated messages. |
| |
n | .. versionadded:: 2.4 |
n | .. versionadded:: 2.4 |
| |
| |
n | .. method:: NullTranslations.install([unicode [, names]]) |
n | .. method:: install([unicode [, names]]) |
| |
n | If the *unicode* flag is false, this method installs :meth:`self.gettext` into |
n | If the *unicode* flag is false, this method installs :meth:`self.gettext` |
| the built-in namespace, binding it to ``_``. If *unicode* is true, it binds |
| into the built-in namespace, binding it to ``_``. If *unicode* is true, |
| :meth:`self.ugettext` instead. By default, *unicode* is false. |
| it binds :meth:`self.ugettext` instead. By default, *unicode* is false. |
| |
n | If the *names* parameter is given, it must be a sequence containing the names of |
n | If the *names* parameter is given, it must be a sequence containing the |
| functions you want to install in the builtin namespace in addition to :func:`_`. |
| names of functions you want to install in the builtin namespace in |
| Supported names are ``'gettext'`` (bound to :meth:`self.gettext` or |
| addition to :func:`_`. Supported names are ``'gettext'`` (bound to |
| :meth:`self.ugettext` according to the *unicode* flag), ``'ngettext'`` (bound to |
| :meth:`self.ngettext` or :meth:`self.ungettext` according to the *unicode* |
| :meth:`self.gettext` or :meth:`self.ugettext` according to the *unicode* |
| flag), ``'lgettext'`` and ``'lngettext'``. |
| flag), ``'ngettext'`` (bound to :meth:`self.ngettext` or |
| :meth:`self.ungettext` according to the *unicode* flag), ``'lgettext'`` |
| and ``'lngettext'``. |
| |
n | Note that this is only one way, albeit the most convenient way, to make the |
n | Note that this is only one way, albeit the most convenient way, to make |
| :func:`_` function available to your application. Because it affects the entire |
| the :func:`_` function available to your application. Because it affects |
| application globally, and specifically the built-in namespace, localized modules |
| the entire application globally, and specifically the built-in namespace, |
| should never install :func:`_`. Instead, they should use this code to make |
| localized modules should never install :func:`_`. Instead, they should use |
| :func:`_` available to their module:: |
| this code to make :func:`_` available to their module:: |
| |
n | import gettext |
n | import gettext |
| t = gettext.translation('mymodule', ...) |
| t = gettext.translation('mymodule', ...) |
| _ = t.gettext |
| _ = t.gettext |
| |
n | This puts :func:`_` only in the module's global namespace and so only affects |
n | This puts :func:`_` only in the module's global namespace and so only |
| calls within this module. |
| affects calls within this module. |
| |
n | .. versionchanged:: 2.5 |
n | .. versionchanged:: 2.5 |
| Added the *names* parameter. |
| Added the *names* parameter. |
| |
| |
| The :class:`GNUTranslations` class |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| The :mod:`gettext` module provides one additional class derived from |
| :class:`NullTranslations`: :class:`GNUTranslations`. This class overrides |
| :meth:`_parse` to enable reading GNU :program:`gettext` format :file:`.mo` files |