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
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.
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.
.. 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
.. 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.
.. 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()
: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.
#. 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
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.
^^^^^^^^^^^^^^^^^^^^^^
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
.. [#] 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.
projects / thirdparty / Python / cpython.git / commitdiff
