mirror of https://github.com/python/cpython
GH-101100: Fix reference warnings for ``gettext`` (#110115)
This commit is contained in:
Adam Turner
GitHub
parent
cbdacc738a
commit
0449fe999d
|
|
@ -58,7 +58,7 @@ class-based API instead.
|
|||
|
||||
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)
|
||||
|
|
@ -98,7 +98,7 @@ class-based API instead.
|
|||
.. 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::
|
||||
|
|
@ -119,7 +119,7 @@ greater convenience than the GNU :program:`gettext` API. It is the recommended
|
|||
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)
|
||||
|
|
@ -150,15 +150,12 @@ install themselves in the built-in namespace as the function :func:`_`.
|
|||
|
||||
.. 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
|
||||
|
|
@ -177,19 +174,19 @@ install themselves in the built-in namespace as the function :func:`_`.
|
|||
|
||||
.. 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.
|
||||
|
||||
|
|
@ -276,20 +273,20 @@ are the methods of :class:`!NullTranslations`:
|
|||
|
||||
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
|
||||
|
|
@ -314,7 +311,7 @@ initialize the "protected" :attr:`_charset` instance variable, defaulting to
|
|||
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
|
||||
|
|
@ -404,7 +401,7 @@ version has a slightly different API. Its documented usage was::
|
|||
_ = 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
|
||||
|
|
@ -432,7 +429,7 @@ take the following steps:
|
|||
|
||||
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')
|
||||
|
|
@ -504,7 +501,7 @@ module::
|
|||
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.
|
||||
|
|
@ -581,13 +578,13 @@ Here is one way you can handle this situation::
|
|||
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.
|
||||
|
||||
|
|
@ -606,13 +603,13 @@ Another way to handle this is with the following example::
|
|||
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
|
||||
|
|
|
|||
Loading…
Reference in New Issue