[3.11] GH-101100: Fix reference warnings for ``gettext`` (GH-110115) by miss-islington · Pull Request #110141 · python/cpython
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)
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::
.. 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
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
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')
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.
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.
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