Return the localized translation of *message*, based on the current global
domain, language, and locale directory. This function is usually aliased as
- :func:`_` in the local namespace (see examples below).
+ :func:`!_` in the local namespace (see examples below).
.. function:: dgettext(domain, message)
.. versionadded:: 3.8
-Note that GNU :program:`gettext` also defines a :func:`dcgettext` method, but
+Note that GNU :program:`gettext` also defines a :func:`!dcgettext` method, but
this was deemed not useful and so it is currently unimplemented.
Here's an example of typical usage for this API::
way of localizing your Python applications and modules. :mod:`!gettext` defines
a :class:`GNUTranslations` class which implements the parsing of GNU :file:`.mo` format
files, and has methods for returning strings. Instances of this class can also
-install themselves in the built-in namespace as the function :func:`_`.
+install themselves in the built-in namespace as the function :func:`!_`.
.. function:: find(domain, localedir=None, languages=None, all=False)
.. function:: translation(domain, localedir=None, languages=None, class_=None, fallback=False)
- Return a :class:`*Translations` instance based on the *domain*, *localedir*,
+ Return a ``*Translations`` instance based on the *domain*, *localedir*,
and *languages*, which are first passed to :func:`find` to get a list of the
associated :file:`.mo` file paths. Instances with identical :file:`.mo` file
names are cached. The actual class instantiated is *class_* if
provided, otherwise :class:`GNUTranslations`. The class's constructor must
- take a single :term:`file object` argument. If provided, *codeset* will change
- the charset used to encode translated strings in the
- :meth:`~NullTranslations.lgettext` and :meth:`~NullTranslations.lngettext`
- methods.
+ take a single :term:`file object` argument.
If multiple files are found, later files are used as fallbacks for earlier ones.
To allow setting the fallback, :func:`copy.copy` is used to clone each
.. function:: install(domain, localedir=None, *, names=None)
- This installs the function :func:`_` in Python's builtins namespace, based on
+ This installs the function :func:`!_` in Python's builtins namespace, based on
*domain* and *localedir* which are passed to the function :func:`translation`.
For the *names* parameter, please see the description of the translation
object's :meth:`~NullTranslations.install` method.
As seen below, you usually mark the strings in your application that are
- candidates for translation, by wrapping them in a call to the :func:`_`
+ candidates for translation, by wrapping them in a call to the :func:`!_`
function, like this::
print(_('This string will be translated.'))
- For convenience, you want the :func:`_` function to be installed in Python's
+ For convenience, you want the :func:`!_` function to be installed in Python's
builtins namespace, so it is easily accessible in all modules of your
application.
If the *names* parameter is given, it must be a sequence containing the
names of functions you want to install in the builtins namespace in
- addition to :func:`_`. Supported names are ``'gettext'``, ``'ngettext'``,
- ``'pgettext'``, ``'npgettext'``, ``'lgettext'``, and ``'lngettext'``.
+ addition to :func:`!_`. Supported names are ``'gettext'``, ``'ngettext'``,
+ ``'pgettext'``, and ``'npgettext'``.
Note that this is only one way, albeit the most convenient way, to make
- the :func:`_` function available to your application. Because it affects
+ the :func:`!_` function available to your application. Because it affects
the entire application globally, and specifically the built-in namespace,
- localized modules should never install :func:`_`. Instead, they should use
- this code to make :func:`_` available to their module::
+ localized modules should never install :func:`!_`. Instead, they should use
+ this code to make :func:`!_` available to their module::
import gettext
t = gettext.translation('mymodule', ...)
_ = t.gettext
- This puts :func:`_` only in the module's global namespace and so only
+ This puts :func:`!_` only in the module's global namespace and so only
affects calls within this module.
.. versionchanged:: 3.8
ids and message strings read from the catalog are converted to Unicode using
this encoding, else ASCII is assumed.
-Since message ids are read as Unicode strings too, all :meth:`*gettext` methods
+Since message ids are read as Unicode strings too, all ``*gettext()`` methods
will assume message ids as Unicode strings, not byte strings.
The entire set of key/value pairs are placed into a dictionary and set as the
_ = cat.gettext
print(_('hello world'))
-For compatibility with this older module, the function :func:`Catalog` is an
+For compatibility with this older module, the function :func:`!Catalog` is an
alias for the :func:`translation` function described above.
One difference between this module and Henstridge's: his catalog objects
In order to prepare your code for I18N, you need to look at all the strings in
your files. Any string that needs to be translated should be marked by wrapping
-it in ``_('...')`` --- that is, a call to the function :func:`_`. For example::
+it in ``_('...')`` --- that is, a call to the function :func:`_ <gettext>`. For example::
filename = 'mylog.txt'
message = _('writing a log message')
Localizing your application
^^^^^^^^^^^^^^^^^^^^^^^^^^^
-If you are localizing your application, you can install the :func:`_` function
+If you are localizing your application, you can install the :func:`!_` function
globally into the built-in namespace, usually in the main driver file of your
application. This will let all your application-specific files just use
``_('...')`` without having to explicitly install it in each file.
for a in animals:
print(_(a))
-This works because the dummy definition of :func:`_` simply returns the string
+This works because the dummy definition of :func:`!_` simply returns the string
unchanged. And this dummy definition will temporarily override any definition
-of :func:`_` in the built-in namespace (until the :keyword:`del` command). Take
-care, though if you have a previous definition of :func:`_` in the local
+of :func:`!_` in the built-in namespace (until the :keyword:`del` command). Take
+care, though if you have a previous definition of :func:`!_` in the local
namespace.
-Note that the second use of :func:`_` will not identify "a" as being
+Note that the second use of :func:`!_` will not identify "a" as being
translatable to the :program:`gettext` program, because the parameter
is not a string literal.
print(_(a))
In this case, you are marking translatable strings with the function
-:func:`N_`, which won't conflict with any definition of :func:`_`.
+:func:`!N_`, which won't conflict with any definition of :func:`!_`.
However, you will need to teach your message extraction program to
-look for translatable strings marked with :func:`N_`. :program:`xgettext`,
+look for translatable strings marked with :func:`!N_`. :program:`xgettext`,
:program:`pygettext`, ``pybabel extract``, and :program:`xpot` all
support this through the use of the :option:`!-k` command-line switch.
-The choice of :func:`N_` here is totally arbitrary; it could have just
-as easily been :func:`MarkThisStringForTranslation`.
+The choice of :func:`!N_` here is totally arbitrary; it could have just
+as easily been :func:`!MarkThisStringForTranslation`.
Acknowledgements
projects / thirdparty / Python / cpython.git / commitdiff
