From 55f3317e984cc35bd18ba0326ed98766a2750ffd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A9phane=20Wirtel?= Date: Sun, 4 Nov 2018 23:24:41 +0100 Subject: [PATCH] bpo-10536: Enhancements to gettext docs (GH-10324) --- Doc/library/gettext.rst | 46 +++++++++---------- .../2018-11-04-22-03-56.bpo-10536.a0IsfE.rst | 1 + 2 files changed, 24 insertions(+), 23 deletions(-) create mode 100644 Misc/NEWS.d/next/Documentation/2018-11-04-22-03-56.bpo-10536.a0IsfE.rst diff --git a/Doc/library/gettext.rst b/Doc/library/gettext.rst index ef315e041e1..38515ebdf59 100644 --- a/Doc/library/gettext.rst +++ b/Doc/library/gettext.rst @@ -13,7 +13,7 @@ The :mod:`gettext` module provides internationalization (I18N) and localization (L10N) services for your Python modules and applications. It supports both the -GNU ``gettext`` message catalog API and a higher level, class-based API that may +GNU :program:`gettext` message catalog API and a higher level, class-based API that may be more appropriate for Python files. The interface described below allows you to write your module and application messages in one natural language, and provide a catalog of translated messages for running under different natural @@ -38,7 +38,7 @@ class-based API instead. Bind the *domain* to the locale directory *localedir*. More concretely, :mod:`gettext` will look for binary :file:`.mo` files for the given domain using - the path (on Unix): :file:`localedir/language/LC_MESSAGES/domain.mo`, where + the path (on Unix): :file:`{localedir}/{language}/LC_MESSAGES/{domain}.mo`, where *languages* is searched for in the environment variables :envvar:`LANGUAGE`, :envvar:`LC_ALL`, :envvar:`LC_MESSAGES`, and :envvar:`LANG` respectively. @@ -138,17 +138,16 @@ Class-based API The class-based API of the :mod:`gettext` module gives you more flexibility and greater convenience than the GNU :program:`gettext` API. It is the recommended way of localizing your Python applications and modules. :mod:`!gettext` defines -a "translations" class which implements the parsing of GNU :file:`.mo` format -files, and has methods for returning strings. Instances of this "translations" -class can also install themselves in the built-in namespace as the function -:func:`_`. +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:`_`. .. function:: find(domain, localedir=None, languages=None, all=False) This function implements the standard :file:`.mo` file search algorithm. It takes a *domain*, identical to what :func:`textdomain` takes. Optional - *localedir* is as in :func:`bindtextdomain` Optional *languages* is a list of + *localedir* is as in :func:`bindtextdomain`. Optional *languages* is a list of strings, where each string is a language code. If *localedir* is not given, then the default system locale directory is used. @@ -172,10 +171,10 @@ class can also install themselves in the built-in namespace as the function .. function:: translation(domain, localedir=None, languages=None, class_=None, fallback=False, codeset=None) - Return a :class:`Translations` instance based on the *domain*, *localedir*, + Return a :class:`*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 either *class_* if + 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 @@ -241,7 +240,7 @@ are the methods of :class:`!NullTranslations`: .. method:: _parse(fp) - No-op'd in the base class, this method takes file object *fp*, and reads + No-op in the base class, this method takes file object *fp*, and reads the data from the file, initializing its message catalog. If you have an unsupported message catalog file format, you should override this method to parse your format. @@ -285,7 +284,8 @@ are the methods of :class:`!NullTranslations`: .. method:: info() - Return the "protected" :attr:`_info` variable. + Return the "protected" :attr:`_info` variable, a dictionary containing + the metadata found in the message catalog file. .. method:: charset() @@ -340,15 +340,15 @@ The :mod:`gettext` module provides one additional class derived from :meth:`_parse` to enable reading GNU :program:`gettext` format :file:`.mo` files in both big-endian and little-endian format. -:class:`GNUTranslations` parses optional meta-data out of the translation -catalog. It is convention with GNU :program:`gettext` to include meta-data as -the translation for the empty string. This meta-data is in :rfc:`822`\ -style +:class:`GNUTranslations` parses optional metadata out of the translation +catalog. It is convention with GNU :program:`gettext` to include metadata as +the translation for the empty string. This metadata is in :rfc:`822`\ -style ``key: value`` pairs, and should contain the ``Project-Id-Version`` key. If the key ``Content-Type`` is found, then the ``charset`` property is used to initialize the "protected" :attr:`_charset` instance variable, defaulting to ``None`` if not found. If the charset encoding is specified, then all message ids and message strings read from the catalog are converted to Unicode using -this encoding, else ASCII encoding is assumed. +this encoding, else ASCII is assumed. Since message ids are read as Unicode strings too, all :meth:`*gettext` methods will assume message ids as Unicode strings, not byte strings. @@ -452,7 +452,7 @@ take the following steps: #. run a suite of tools over your marked files to generate raw messages catalogs -#. create language specific translations of the message catalogs +#. create language-specific translations of the message catalogs #. use the :mod:`gettext` module so that message strings are properly translated @@ -462,9 +462,8 @@ it in ``_('...')`` --- that is, a call to the function :func:`_`. For example:: filename = 'mylog.txt' message = _('writing a log message') - fp = open(filename, 'w') - fp.write(message) - fp.close() + with open(filename, 'w') as fp: + fp.write(message) In this example, the string ``'writing a log message'`` is marked as a candidate for translation, while the strings ``'mylog.txt'`` and ``'w'`` are not. @@ -515,7 +514,7 @@ Localizing your module ^^^^^^^^^^^^^^^^^^^^^^ If you are localizing your module, you must take care not to make global -changes, e.g. to the built-in namespace. You should not use the GNU ``gettext`` +changes, e.g. to the built-in namespace. You should not use the GNU :program:`gettext` API but instead the class-based API. Let's say your module is called "spam" and the module's various natural language @@ -669,8 +668,9 @@ implementations, and valuable experience to the creation of this module: .. [#] The default locale directory is system dependent; for example, on RedHat Linux it is :file:`/usr/share/locale`, but on Solaris it is :file:`/usr/lib/locale`. The :mod:`gettext` module does not try to support these system dependent - defaults; instead its default is :file:`sys.prefix/share/locale`. For this - reason, it is always best to call :func:`bindtextdomain` with an explicit - absolute path at the start of your application. + defaults; instead its default is :file:`{sys.prefix}/share/locale` (see + :data:`sys.prefix`). For this reason, it is always best to call + :func:`bindtextdomain` with an explicit absolute path at the start of your + application. .. [#] See the footnote for :func:`bindtextdomain` above. diff --git a/Misc/NEWS.d/next/Documentation/2018-11-04-22-03-56.bpo-10536.a0IsfE.rst b/Misc/NEWS.d/next/Documentation/2018-11-04-22-03-56.bpo-10536.a0IsfE.rst new file mode 100644 index 00000000000..b5036481fb6 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2018-11-04-22-03-56.bpo-10536.a0IsfE.rst @@ -0,0 +1 @@ +Enhance the gettext docs. Patch by Éric Araujo