Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`gettext` --- Multilingual internationalization services |
| 2 | ============================================================= |
| 3 | |
| 4 | .. module:: gettext |
| 5 | :synopsis: Multilingual internationalization services. |
Andrew Kuchling | 587e970 | 2013-11-12 10:02:35 -0500 | [diff] [blame] | 6 | .. moduleauthor:: Barry A. Warsaw <barry@python.org> |
| 7 | .. sectionauthor:: Barry A. Warsaw <barry@python.org> |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 8 | |
Raymond Hettinger | 469271d | 2011-01-27 20:38:46 +0000 | [diff] [blame] | 9 | **Source code:** :source:`Lib/gettext.py` |
| 10 | |
| 11 | -------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 12 | |
| 13 | The :mod:`gettext` module provides internationalization (I18N) and localization |
| 14 | (L10N) services for your Python modules and applications. It supports both the |
| 15 | GNU ``gettext`` message catalog API and a higher level, class-based API that may |
| 16 | be more appropriate for Python files. The interface described below allows you |
| 17 | to write your module and application messages in one natural language, and |
| 18 | provide a catalog of translated messages for running under different natural |
| 19 | languages. |
| 20 | |
| 21 | Some hints on localizing your Python modules and applications are also given. |
| 22 | |
| 23 | |
| 24 | GNU :program:`gettext` API |
| 25 | -------------------------- |
| 26 | |
| 27 | The :mod:`gettext` module defines the following API, which is very similar to |
| 28 | the GNU :program:`gettext` API. If you use this API you will affect the |
| 29 | translation of your entire application globally. Often this is what you want if |
| 30 | your application is monolingual, with the choice of language dependent on the |
| 31 | locale of your user. If you are localizing a Python module, or if your |
| 32 | application needs to switch languages on the fly, you probably want to use the |
| 33 | class-based API instead. |
| 34 | |
| 35 | |
Georg Brandl | 036490d | 2009-05-17 13:00:36 +0000 | [diff] [blame] | 36 | .. function:: bindtextdomain(domain, localedir=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 37 | |
| 38 | Bind the *domain* to the locale directory *localedir*. More concretely, |
| 39 | :mod:`gettext` will look for binary :file:`.mo` files for the given domain using |
| 40 | the path (on Unix): :file:`localedir/language/LC_MESSAGES/domain.mo`, where |
| 41 | *languages* is searched for in the environment variables :envvar:`LANGUAGE`, |
| 42 | :envvar:`LC_ALL`, :envvar:`LC_MESSAGES`, and :envvar:`LANG` respectively. |
| 43 | |
| 44 | If *localedir* is omitted or ``None``, then the current binding for *domain* is |
| 45 | returned. [#]_ |
| 46 | |
| 47 | |
Georg Brandl | 036490d | 2009-05-17 13:00:36 +0000 | [diff] [blame] | 48 | .. function:: bind_textdomain_codeset(domain, codeset=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 49 | |
| 50 | Bind the *domain* to *codeset*, changing the encoding of strings returned by the |
| 51 | :func:`gettext` family of functions. If *codeset* is omitted, then the current |
| 52 | binding is returned. |
| 53 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 54 | |
Georg Brandl | 036490d | 2009-05-17 13:00:36 +0000 | [diff] [blame] | 55 | .. function:: textdomain(domain=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 56 | |
| 57 | Change or query the current global domain. If *domain* is ``None``, then the |
| 58 | current global domain is returned, otherwise the global domain is set to |
| 59 | *domain*, which is returned. |
| 60 | |
| 61 | |
| 62 | .. function:: gettext(message) |
| 63 | |
| 64 | Return the localized translation of *message*, based on the current global |
| 65 | domain, language, and locale directory. This function is usually aliased as |
| 66 | :func:`_` in the local namespace (see examples below). |
| 67 | |
| 68 | |
| 69 | .. function:: lgettext(message) |
| 70 | |
Georg Brandl | bded4d3 | 2008-07-17 18:15:35 +0000 | [diff] [blame] | 71 | Equivalent to :func:`gettext`, but the translation is returned in the |
| 72 | preferred system encoding, if no other encoding was explicitly set with |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 73 | :func:`bind_textdomain_codeset`. |
| 74 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 75 | |
| 76 | .. function:: dgettext(domain, message) |
| 77 | |
| 78 | Like :func:`gettext`, but look the message up in the specified *domain*. |
| 79 | |
| 80 | |
| 81 | .. function:: ldgettext(domain, message) |
| 82 | |
Georg Brandl | bded4d3 | 2008-07-17 18:15:35 +0000 | [diff] [blame] | 83 | Equivalent to :func:`dgettext`, but the translation is returned in the |
| 84 | preferred system encoding, if no other encoding was explicitly set with |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 85 | :func:`bind_textdomain_codeset`. |
| 86 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 87 | |
| 88 | .. function:: ngettext(singular, plural, n) |
| 89 | |
| 90 | Like :func:`gettext`, but consider plural forms. If a translation is found, |
| 91 | apply the plural formula to *n*, and return the resulting message (some |
| 92 | languages have more than two plural forms). If no translation is found, return |
| 93 | *singular* if *n* is 1; return *plural* otherwise. |
| 94 | |
| 95 | The Plural formula is taken from the catalog header. It is a C or Python |
| 96 | expression that has a free variable *n*; the expression evaluates to the index |
Andrew Kuchling | 30c5ad2 | 2013-11-19 11:05:20 -0500 | [diff] [blame] | 97 | of the plural in the catalog. See |
| 98 | `the GNU gettext documentation <https://www.gnu.org/software/gettext/manual/gettext.html>`__ |
| 99 | for the precise syntax to be used in :file:`.po` files and the |
| 100 | formulas for a variety of languages. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 101 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 102 | |
| 103 | .. function:: lngettext(singular, plural, n) |
| 104 | |
Georg Brandl | bded4d3 | 2008-07-17 18:15:35 +0000 | [diff] [blame] | 105 | Equivalent to :func:`ngettext`, but the translation is returned in the |
| 106 | preferred system encoding, if no other encoding was explicitly set with |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 107 | :func:`bind_textdomain_codeset`. |
| 108 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 109 | |
| 110 | .. function:: dngettext(domain, singular, plural, n) |
| 111 | |
| 112 | Like :func:`ngettext`, but look the message up in the specified *domain*. |
| 113 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 114 | |
| 115 | .. function:: ldngettext(domain, singular, plural, n) |
| 116 | |
| 117 | Equivalent to :func:`dngettext`, but the translation is returned in the |
| 118 | preferred system encoding, if no other encoding was explicitly set with |
| 119 | :func:`bind_textdomain_codeset`. |
| 120 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 121 | |
| 122 | Note that GNU :program:`gettext` also defines a :func:`dcgettext` method, but |
| 123 | this was deemed not useful and so it is currently unimplemented. |
| 124 | |
| 125 | Here's an example of typical usage for this API:: |
| 126 | |
| 127 | import gettext |
| 128 | gettext.bindtextdomain('myapplication', '/path/to/my/language/directory') |
| 129 | gettext.textdomain('myapplication') |
| 130 | _ = gettext.gettext |
| 131 | # ... |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 132 | print(_('This is a translatable string.')) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 133 | |
| 134 | |
| 135 | Class-based API |
| 136 | --------------- |
| 137 | |
| 138 | The class-based API of the :mod:`gettext` module gives you more flexibility and |
| 139 | greater convenience than the GNU :program:`gettext` API. It is the recommended |
| 140 | way of localizing your Python applications and modules. :mod:`gettext` defines |
| 141 | a "translations" class which implements the parsing of GNU :file:`.mo` format |
Georg Brandl | f694518 | 2008-02-01 11:56:49 +0000 | [diff] [blame] | 142 | files, and has methods for returning strings. Instances of this "translations" |
| 143 | class can also install themselves in the built-in namespace as the function |
| 144 | :func:`_`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 145 | |
| 146 | |
Georg Brandl | 036490d | 2009-05-17 13:00:36 +0000 | [diff] [blame] | 147 | .. function:: find(domain, localedir=None, languages=None, all=False) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 148 | |
| 149 | This function implements the standard :file:`.mo` file search algorithm. It |
| 150 | takes a *domain*, identical to what :func:`textdomain` takes. Optional |
| 151 | *localedir* is as in :func:`bindtextdomain` Optional *languages* is a list of |
| 152 | strings, where each string is a language code. |
| 153 | |
| 154 | If *localedir* is not given, then the default system locale directory is used. |
| 155 | [#]_ If *languages* is not given, then the following environment variables are |
| 156 | searched: :envvar:`LANGUAGE`, :envvar:`LC_ALL`, :envvar:`LC_MESSAGES`, and |
| 157 | :envvar:`LANG`. The first one returning a non-empty value is used for the |
| 158 | *languages* variable. The environment variables should contain a colon separated |
| 159 | list of languages, which will be split on the colon to produce the expected list |
| 160 | of language code strings. |
| 161 | |
| 162 | :func:`find` then expands and normalizes the languages, and then iterates |
| 163 | through them, searching for an existing file built of these components: |
| 164 | |
Georg Brandl | 036490d | 2009-05-17 13:00:36 +0000 | [diff] [blame] | 165 | :file:`{localedir}/{language}/LC_MESSAGES/{domain}.mo` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 166 | |
| 167 | The first such file name that exists is returned by :func:`find`. If no such |
| 168 | file is found, then ``None`` is returned. If *all* is given, it returns a list |
| 169 | of all file names, in the order in which they appear in the languages list or |
| 170 | the environment variables. |
| 171 | |
| 172 | |
Georg Brandl | 036490d | 2009-05-17 13:00:36 +0000 | [diff] [blame] | 173 | .. function:: translation(domain, localedir=None, languages=None, class_=None, fallback=False, codeset=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 174 | |
Georg Brandl | bded4d3 | 2008-07-17 18:15:35 +0000 | [diff] [blame] | 175 | Return a :class:`Translations` instance based on the *domain*, *localedir*, |
| 176 | and *languages*, which are first passed to :func:`find` to get a list of the |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 177 | associated :file:`.mo` file paths. Instances with identical :file:`.mo` file |
Georg Brandl | bded4d3 | 2008-07-17 18:15:35 +0000 | [diff] [blame] | 178 | names are cached. The actual class instantiated is either *class_* if |
| 179 | provided, otherwise :class:`GNUTranslations`. The class's constructor must |
Antoine Pitrou | 11cb961 | 2010-09-15 11:11:28 +0000 | [diff] [blame] | 180 | take a single :term:`file object` argument. If provided, *codeset* will change |
| 181 | the charset used to encode translated strings in the :meth:`lgettext` and |
Georg Brandl | bded4d3 | 2008-07-17 18:15:35 +0000 | [diff] [blame] | 182 | :meth:`lngettext` methods. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 183 | |
| 184 | If multiple files are found, later files are used as fallbacks for earlier ones. |
| 185 | To allow setting the fallback, :func:`copy.copy` is used to clone each |
| 186 | translation object from the cache; the actual instance data is still shared with |
| 187 | the cache. |
| 188 | |
Antoine Pitrou | 62ab10a0 | 2011-10-12 20:10:51 +0200 | [diff] [blame] | 189 | If no :file:`.mo` file is found, this function raises :exc:`OSError` if |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 190 | *fallback* is false (which is the default), and returns a |
| 191 | :class:`NullTranslations` instance if *fallback* is true. |
| 192 | |
Antoine Pitrou | 62ab10a0 | 2011-10-12 20:10:51 +0200 | [diff] [blame] | 193 | .. versionchanged:: 3.3 |
| 194 | :exc:`IOError` used to be raised instead of :exc:`OSError`. |
| 195 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 196 | |
Georg Brandl | 036490d | 2009-05-17 13:00:36 +0000 | [diff] [blame] | 197 | .. function:: install(domain, localedir=None, codeset=None, names=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 198 | |
Georg Brandl | 22b3431 | 2009-07-26 14:54:51 +0000 | [diff] [blame] | 199 | This installs the function :func:`_` in Python's builtins namespace, based on |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 200 | *domain*, *localedir*, and *codeset* which are passed to the function |
Benjamin Peterson | 801844d | 2008-07-14 14:32:15 +0000 | [diff] [blame] | 201 | :func:`translation`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 202 | |
| 203 | For the *names* parameter, please see the description of the translation |
Alexandre Vassalotti | 6d3dfc3 | 2009-07-29 19:54:39 +0000 | [diff] [blame] | 204 | object's :meth:`~NullTranslations.install` method. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 205 | |
| 206 | As seen below, you usually mark the strings in your application that are |
| 207 | candidates for translation, by wrapping them in a call to the :func:`_` |
| 208 | function, like this:: |
| 209 | |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 210 | print(_('This string will be translated.')) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 211 | |
| 212 | For convenience, you want the :func:`_` function to be installed in Python's |
Georg Brandl | 22b3431 | 2009-07-26 14:54:51 +0000 | [diff] [blame] | 213 | builtins namespace, so it is easily accessible in all modules of your |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 214 | application. |
| 215 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 216 | |
| 217 | The :class:`NullTranslations` class |
| 218 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 219 | |
| 220 | Translation classes are what actually implement the translation of original |
| 221 | source file message strings to translated message strings. The base class used |
| 222 | by all translation classes is :class:`NullTranslations`; this provides the basic |
| 223 | interface you can use to write your own specialized translation classes. Here |
| 224 | are the methods of :class:`NullTranslations`: |
| 225 | |
| 226 | |
Georg Brandl | 036490d | 2009-05-17 13:00:36 +0000 | [diff] [blame] | 227 | .. class:: NullTranslations(fp=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 228 | |
Antoine Pitrou | 11cb961 | 2010-09-15 11:11:28 +0000 | [diff] [blame] | 229 | Takes an optional :term:`file object` *fp*, which is ignored by the base class. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 230 | Initializes "protected" instance variables *_info* and *_charset* which are set |
| 231 | by derived classes, as well as *_fallback*, which is set through |
| 232 | :meth:`add_fallback`. It then calls ``self._parse(fp)`` if *fp* is not |
| 233 | ``None``. |
| 234 | |
Georg Brandl | bded4d3 | 2008-07-17 18:15:35 +0000 | [diff] [blame] | 235 | .. method:: _parse(fp) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 236 | |
Georg Brandl | bded4d3 | 2008-07-17 18:15:35 +0000 | [diff] [blame] | 237 | No-op'd in the base class, this method takes file object *fp*, and reads |
| 238 | the data from the file, initializing its message catalog. If you have an |
| 239 | unsupported message catalog file format, you should override this method |
| 240 | to parse your format. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 241 | |
| 242 | |
Georg Brandl | bded4d3 | 2008-07-17 18:15:35 +0000 | [diff] [blame] | 243 | .. method:: add_fallback(fallback) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 244 | |
Georg Brandl | bded4d3 | 2008-07-17 18:15:35 +0000 | [diff] [blame] | 245 | Add *fallback* as the fallback object for the current translation object. |
| 246 | A translation object should consult the fallback if it cannot provide a |
| 247 | translation for a given message. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 248 | |
| 249 | |
Georg Brandl | bded4d3 | 2008-07-17 18:15:35 +0000 | [diff] [blame] | 250 | .. method:: gettext(message) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 251 | |
Georg Brandl | bded4d3 | 2008-07-17 18:15:35 +0000 | [diff] [blame] | 252 | If a fallback has been set, forward :meth:`gettext` to the fallback. |
| 253 | Otherwise, return the translated message. Overridden in derived classes. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 254 | |
| 255 | |
Georg Brandl | bded4d3 | 2008-07-17 18:15:35 +0000 | [diff] [blame] | 256 | .. method:: lgettext(message) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 257 | |
Georg Brandl | bded4d3 | 2008-07-17 18:15:35 +0000 | [diff] [blame] | 258 | If a fallback has been set, forward :meth:`lgettext` to the fallback. |
| 259 | Otherwise, return the translated message. Overridden in derived classes. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 260 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 261 | |
Georg Brandl | bded4d3 | 2008-07-17 18:15:35 +0000 | [diff] [blame] | 262 | .. method:: ngettext(singular, plural, n) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 263 | |
Georg Brandl | bded4d3 | 2008-07-17 18:15:35 +0000 | [diff] [blame] | 264 | If a fallback has been set, forward :meth:`ngettext` to the fallback. |
| 265 | Otherwise, return the translated message. Overridden in derived classes. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 266 | |
| 267 | |
Georg Brandl | bded4d3 | 2008-07-17 18:15:35 +0000 | [diff] [blame] | 268 | .. method:: lngettext(singular, plural, n) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 269 | |
Éric Araujo | 35a502b | 2011-10-07 22:02:58 +0200 | [diff] [blame] | 270 | If a fallback has been set, forward :meth:`lngettext` to the fallback. |
Georg Brandl | bded4d3 | 2008-07-17 18:15:35 +0000 | [diff] [blame] | 271 | Otherwise, return the translated message. Overridden in derived classes. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 272 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 273 | |
Georg Brandl | bded4d3 | 2008-07-17 18:15:35 +0000 | [diff] [blame] | 274 | .. method:: info() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 275 | |
Georg Brandl | bded4d3 | 2008-07-17 18:15:35 +0000 | [diff] [blame] | 276 | Return the "protected" :attr:`_info` variable. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 277 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 278 | |
Georg Brandl | bded4d3 | 2008-07-17 18:15:35 +0000 | [diff] [blame] | 279 | .. method:: charset() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 280 | |
Georg Brandl | bded4d3 | 2008-07-17 18:15:35 +0000 | [diff] [blame] | 281 | Return the "protected" :attr:`_charset` variable, which is the encoding of |
| 282 | the message catalog file. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 283 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 284 | |
Georg Brandl | bded4d3 | 2008-07-17 18:15:35 +0000 | [diff] [blame] | 285 | .. method:: output_charset() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 286 | |
Georg Brandl | bded4d3 | 2008-07-17 18:15:35 +0000 | [diff] [blame] | 287 | Return the "protected" :attr:`_output_charset` variable, which defines the |
| 288 | encoding used to return translated messages in :meth:`lgettext` and |
| 289 | :meth:`lngettext`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 290 | |
| 291 | |
Georg Brandl | bded4d3 | 2008-07-17 18:15:35 +0000 | [diff] [blame] | 292 | .. method:: set_output_charset(charset) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 293 | |
Georg Brandl | bded4d3 | 2008-07-17 18:15:35 +0000 | [diff] [blame] | 294 | Change the "protected" :attr:`_output_charset` variable, which defines the |
| 295 | encoding used to return translated messages. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 296 | |
Benjamin Peterson | 801844d | 2008-07-14 14:32:15 +0000 | [diff] [blame] | 297 | |
Georg Brandl | 036490d | 2009-05-17 13:00:36 +0000 | [diff] [blame] | 298 | .. method:: install(names=None) |
Benjamin Peterson | 801844d | 2008-07-14 14:32:15 +0000 | [diff] [blame] | 299 | |
Georg Brandl | bded4d3 | 2008-07-17 18:15:35 +0000 | [diff] [blame] | 300 | This method installs :meth:`self.gettext` into the built-in namespace, |
| 301 | binding it to ``_``. |
Benjamin Peterson | 801844d | 2008-07-14 14:32:15 +0000 | [diff] [blame] | 302 | |
Georg Brandl | bded4d3 | 2008-07-17 18:15:35 +0000 | [diff] [blame] | 303 | If the *names* parameter is given, it must be a sequence containing the |
Georg Brandl | 22b3431 | 2009-07-26 14:54:51 +0000 | [diff] [blame] | 304 | names of functions you want to install in the builtins namespace in |
Georg Brandl | bded4d3 | 2008-07-17 18:15:35 +0000 | [diff] [blame] | 305 | addition to :func:`_`. Supported names are ``'gettext'`` (bound to |
| 306 | :meth:`self.gettext`), ``'ngettext'`` (bound to :meth:`self.ngettext`), |
| 307 | ``'lgettext'`` and ``'lngettext'``. |
Benjamin Peterson | 801844d | 2008-07-14 14:32:15 +0000 | [diff] [blame] | 308 | |
Georg Brandl | bded4d3 | 2008-07-17 18:15:35 +0000 | [diff] [blame] | 309 | Note that this is only one way, albeit the most convenient way, to make |
| 310 | the :func:`_` function available to your application. Because it affects |
| 311 | the entire application globally, and specifically the built-in namespace, |
| 312 | localized modules should never install :func:`_`. Instead, they should use |
| 313 | this code to make :func:`_` available to their module:: |
Benjamin Peterson | 801844d | 2008-07-14 14:32:15 +0000 | [diff] [blame] | 314 | |
Georg Brandl | bded4d3 | 2008-07-17 18:15:35 +0000 | [diff] [blame] | 315 | import gettext |
| 316 | t = gettext.translation('mymodule', ...) |
| 317 | _ = t.gettext |
Benjamin Peterson | 801844d | 2008-07-14 14:32:15 +0000 | [diff] [blame] | 318 | |
Georg Brandl | bded4d3 | 2008-07-17 18:15:35 +0000 | [diff] [blame] | 319 | This puts :func:`_` only in the module's global namespace and so only |
| 320 | affects calls within this module. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 321 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 322 | |
| 323 | The :class:`GNUTranslations` class |
| 324 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 325 | |
| 326 | The :mod:`gettext` module provides one additional class derived from |
| 327 | :class:`NullTranslations`: :class:`GNUTranslations`. This class overrides |
| 328 | :meth:`_parse` to enable reading GNU :program:`gettext` format :file:`.mo` files |
Benjamin Peterson | 801844d | 2008-07-14 14:32:15 +0000 | [diff] [blame] | 329 | in both big-endian and little-endian format. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 330 | |
| 331 | :class:`GNUTranslations` parses optional meta-data out of the translation |
| 332 | catalog. It is convention with GNU :program:`gettext` to include meta-data as |
| 333 | the translation for the empty string. This meta-data is in :rfc:`822`\ -style |
| 334 | ``key: value`` pairs, and should contain the ``Project-Id-Version`` key. If the |
| 335 | key ``Content-Type`` is found, then the ``charset`` property is used to |
| 336 | initialize the "protected" :attr:`_charset` instance variable, defaulting to |
| 337 | ``None`` if not found. If the charset encoding is specified, then all message |
| 338 | ids and message strings read from the catalog are converted to Unicode using |
Georg Brandl | bded4d3 | 2008-07-17 18:15:35 +0000 | [diff] [blame] | 339 | this encoding, else ASCII encoding is assumed. |
| 340 | |
| 341 | Since message ids are read as Unicode strings too, all :meth:`*gettext` methods |
| 342 | will assume message ids as Unicode strings, not byte strings. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 343 | |
| 344 | The entire set of key/value pairs are placed into a dictionary and set as the |
| 345 | "protected" :attr:`_info` instance variable. |
| 346 | |
| 347 | If the :file:`.mo` file's magic number is invalid, or if other problems occur |
| 348 | while reading the file, instantiating a :class:`GNUTranslations` class can raise |
Antoine Pitrou | 62ab10a0 | 2011-10-12 20:10:51 +0200 | [diff] [blame] | 349 | :exc:`OSError`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 350 | |
| 351 | The following methods are overridden from the base class implementation: |
| 352 | |
| 353 | |
| 354 | .. method:: GNUTranslations.gettext(message) |
| 355 | |
| 356 | Look up the *message* id in the catalog and return the corresponding message |
Georg Brandl | bded4d3 | 2008-07-17 18:15:35 +0000 | [diff] [blame] | 357 | string, as a Unicode string. If there is no entry in the catalog for the |
| 358 | *message* id, and a fallback has been set, the look up is forwarded to the |
| 359 | fallback's :meth:`gettext` method. Otherwise, the *message* id is returned. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 360 | |
| 361 | |
| 362 | .. method:: GNUTranslations.lgettext(message) |
| 363 | |
Georg Brandl | bded4d3 | 2008-07-17 18:15:35 +0000 | [diff] [blame] | 364 | Equivalent to :meth:`gettext`, but the translation is returned as a |
| 365 | bytestring encoded in the selected output charset, or in the preferred system |
| 366 | encoding if no encoding was explicitly set with :meth:`set_output_charset`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 367 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 368 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 369 | .. method:: GNUTranslations.ngettext(singular, plural, n) |
| 370 | |
| 371 | Do a plural-forms lookup of a message id. *singular* is used as the message id |
| 372 | for purposes of lookup in the catalog, while *n* is used to determine which |
Georg Brandl | bded4d3 | 2008-07-17 18:15:35 +0000 | [diff] [blame] | 373 | plural form to use. The returned message string is a Unicode string. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 374 | |
| 375 | If the message id is not found in the catalog, and a fallback is specified, the |
| 376 | request is forwarded to the fallback's :meth:`ngettext` method. Otherwise, when |
| 377 | *n* is 1 *singular* is returned, and *plural* is returned in all other cases. |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 378 | |
Benjamin Peterson | 801844d | 2008-07-14 14:32:15 +0000 | [diff] [blame] | 379 | Here is an example:: |
| 380 | |
| 381 | n = len(os.listdir('.')) |
| 382 | cat = GNUTranslations(somefile) |
| 383 | message = cat.ngettext( |
| 384 | 'There is %(num)d file in this directory', |
| 385 | 'There are %(num)d files in this directory', |
| 386 | n) % {'num': n} |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 387 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 388 | |
| 389 | .. method:: GNUTranslations.lngettext(singular, plural, n) |
| 390 | |
Georg Brandl | bded4d3 | 2008-07-17 18:15:35 +0000 | [diff] [blame] | 391 | Equivalent to :meth:`gettext`, but the translation is returned as a |
| 392 | bytestring encoded in the selected output charset, or in the preferred system |
| 393 | encoding if no encoding was explicitly set with :meth:`set_output_charset`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 394 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 395 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 396 | Solaris message catalog support |
| 397 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 398 | |
| 399 | The Solaris operating system defines its own binary :file:`.mo` file format, but |
| 400 | since no documentation can be found on this format, it is not supported at this |
| 401 | time. |
| 402 | |
| 403 | |
| 404 | The Catalog constructor |
| 405 | ^^^^^^^^^^^^^^^^^^^^^^^ |
| 406 | |
| 407 | .. index:: single: GNOME |
| 408 | |
| 409 | GNOME uses a version of the :mod:`gettext` module by James Henstridge, but this |
| 410 | version has a slightly different API. Its documented usage was:: |
| 411 | |
| 412 | import gettext |
| 413 | cat = gettext.Catalog(domain, localedir) |
| 414 | _ = cat.gettext |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 415 | print(_('hello world')) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 416 | |
| 417 | For compatibility with this older module, the function :func:`Catalog` is an |
| 418 | alias for the :func:`translation` function described above. |
| 419 | |
| 420 | One difference between this module and Henstridge's: his catalog objects |
| 421 | supported access through a mapping API, but this appears to be unused and so is |
| 422 | not currently supported. |
| 423 | |
| 424 | |
| 425 | Internationalizing your programs and modules |
| 426 | -------------------------------------------- |
| 427 | |
| 428 | Internationalization (I18N) refers to the operation by which a program is made |
| 429 | aware of multiple languages. Localization (L10N) refers to the adaptation of |
| 430 | your program, once internationalized, to the local language and cultural habits. |
| 431 | In order to provide multilingual messages for your Python programs, you need to |
| 432 | take the following steps: |
| 433 | |
| 434 | #. prepare your program or module by specially marking translatable strings |
| 435 | |
| 436 | #. run a suite of tools over your marked files to generate raw messages catalogs |
| 437 | |
| 438 | #. create language specific translations of the message catalogs |
| 439 | |
| 440 | #. use the :mod:`gettext` module so that message strings are properly translated |
| 441 | |
| 442 | In order to prepare your code for I18N, you need to look at all the strings in |
| 443 | your files. Any string that needs to be translated should be marked by wrapping |
| 444 | it in ``_('...')`` --- that is, a call to the function :func:`_`. For example:: |
| 445 | |
| 446 | filename = 'mylog.txt' |
| 447 | message = _('writing a log message') |
| 448 | fp = open(filename, 'w') |
| 449 | fp.write(message) |
| 450 | fp.close() |
| 451 | |
| 452 | In this example, the string ``'writing a log message'`` is marked as a candidate |
| 453 | for translation, while the strings ``'mylog.txt'`` and ``'w'`` are not. |
| 454 | |
Andrew Kuchling | 30c5ad2 | 2013-11-19 11:05:20 -0500 | [diff] [blame] | 455 | There are a few tools to extract the strings meant for translation. |
| 456 | The original GNU :program:`gettext` only supported C or C++ source |
| 457 | code but its extended version :program:`xgettext` scans code written |
| 458 | in a number of languages, including Python, to find strings marked as |
| 459 | translatable. `Babel <http://babel.pocoo.org/>`__ is a Python |
| 460 | internationalization library that includes a :file:`pybabel` script to |
| 461 | extract and compile message catalogs. François Pinard's program |
| 462 | called :program:`xpot` does a similar job and is available as part of |
| 463 | his `po-utils package <http://po-utils.progiciels-bpi.ca/>`__. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 464 | |
Andrew Kuchling | 30c5ad2 | 2013-11-19 11:05:20 -0500 | [diff] [blame] | 465 | (Python also includes pure-Python versions of these programs, called |
| 466 | :program:`pygettext.py` and :program:`msgfmt.py`; some Python distributions |
| 467 | will install them for you. :program:`pygettext.py` is similar to |
| 468 | :program:`xgettext`, but only understands Python source code and |
| 469 | cannot handle other programming languages such as C or C++. |
| 470 | :program:`pygettext.py` supports a command-line interface similar to |
| 471 | :program:`xgettext`; for details on its use, run ``pygettext.py |
| 472 | --help``. :program:`msgfmt.py` is binary compatible with GNU |
| 473 | :program:`msgfmt`. With these two programs, you may not need the GNU |
| 474 | :program:`gettext` package to internationalize your Python |
| 475 | applications.) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 476 | |
Andrew Kuchling | 30c5ad2 | 2013-11-19 11:05:20 -0500 | [diff] [blame] | 477 | :program:`xgettext`, :program:`pygettext`, and similar tools generate |
| 478 | :file:`.po` files that are message catalogs. They are structured |
Georg Brandl | ed007d5 | 2013-11-24 16:09:26 +0100 | [diff] [blame] | 479 | human-readable files that contain every marked string in the source |
| 480 | code, along with a placeholder for the translated versions of these |
| 481 | strings. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 482 | |
Andrew Kuchling | 30c5ad2 | 2013-11-19 11:05:20 -0500 | [diff] [blame] | 483 | Copies of these :file:`.po` files are then handed over to the |
| 484 | individual human translators who write translations for every |
| 485 | supported natural language. They send back the completed |
| 486 | language-specific versions as a :file:`<language-name>.po` file that's |
| 487 | compiled into a machine-readable :file:`.mo` binary catalog file using |
| 488 | the :program:`msgfmt` program. The :file:`.mo` files are used by the |
| 489 | :mod:`gettext` module for the actual translation processing at |
| 490 | run-time. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 491 | |
| 492 | How you use the :mod:`gettext` module in your code depends on whether you are |
| 493 | internationalizing a single module or your entire application. The next two |
| 494 | sections will discuss each case. |
| 495 | |
| 496 | |
| 497 | Localizing your module |
| 498 | ^^^^^^^^^^^^^^^^^^^^^^ |
| 499 | |
| 500 | If you are localizing your module, you must take care not to make global |
| 501 | changes, e.g. to the built-in namespace. You should not use the GNU ``gettext`` |
| 502 | API but instead the class-based API. |
| 503 | |
| 504 | Let's say your module is called "spam" and the module's various natural language |
| 505 | translation :file:`.mo` files reside in :file:`/usr/share/locale` in GNU |
| 506 | :program:`gettext` format. Here's what you would put at the top of your |
| 507 | module:: |
| 508 | |
| 509 | import gettext |
| 510 | t = gettext.translation('spam', '/usr/share/locale') |
| 511 | _ = t.lgettext |
| 512 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 513 | |
| 514 | Localizing your application |
| 515 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 516 | |
| 517 | If you are localizing your application, you can install the :func:`_` function |
| 518 | globally into the built-in namespace, usually in the main driver file of your |
| 519 | application. This will let all your application-specific files just use |
| 520 | ``_('...')`` without having to explicitly install it in each file. |
| 521 | |
| 522 | In the simple case then, you need only add the following bit of code to the main |
| 523 | driver file of your application:: |
| 524 | |
| 525 | import gettext |
| 526 | gettext.install('myapplication') |
| 527 | |
Andrew Kuchling | 30c5ad2 | 2013-11-19 11:05:20 -0500 | [diff] [blame] | 528 | If you need to set the locale directory, you can pass it into the |
Benjamin Peterson | 801844d | 2008-07-14 14:32:15 +0000 | [diff] [blame] | 529 | :func:`install` function:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 530 | |
| 531 | import gettext |
Benjamin Peterson | 801844d | 2008-07-14 14:32:15 +0000 | [diff] [blame] | 532 | gettext.install('myapplication', '/usr/share/locale') |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 533 | |
| 534 | |
| 535 | Changing languages on the fly |
| 536 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 537 | |
| 538 | If your program needs to support many languages at the same time, you may want |
| 539 | to create multiple translation instances and then switch between them |
| 540 | explicitly, like so:: |
| 541 | |
| 542 | import gettext |
| 543 | |
| 544 | lang1 = gettext.translation('myapplication', languages=['en']) |
| 545 | lang2 = gettext.translation('myapplication', languages=['fr']) |
| 546 | lang3 = gettext.translation('myapplication', languages=['de']) |
| 547 | |
| 548 | # start by using language1 |
| 549 | lang1.install() |
| 550 | |
| 551 | # ... time goes by, user selects language 2 |
| 552 | lang2.install() |
| 553 | |
| 554 | # ... more time goes by, user selects language 3 |
| 555 | lang3.install() |
| 556 | |
| 557 | |
| 558 | Deferred translations |
| 559 | ^^^^^^^^^^^^^^^^^^^^^ |
| 560 | |
| 561 | In most coding situations, strings are translated where they are coded. |
| 562 | Occasionally however, you need to mark strings for translation, but defer actual |
| 563 | translation until later. A classic example is:: |
| 564 | |
| 565 | animals = ['mollusk', |
| 566 | 'albatross', |
Georg Brandl | a1c6a1c | 2009-01-03 21:26:05 +0000 | [diff] [blame] | 567 | 'rat', |
| 568 | 'penguin', |
| 569 | 'python', ] |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 570 | # ... |
| 571 | for a in animals: |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 572 | print(a) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 573 | |
| 574 | Here, you want to mark the strings in the ``animals`` list as being |
| 575 | translatable, but you don't actually want to translate them until they are |
| 576 | printed. |
| 577 | |
| 578 | Here is one way you can handle this situation:: |
| 579 | |
| 580 | def _(message): return message |
| 581 | |
| 582 | animals = [_('mollusk'), |
| 583 | _('albatross'), |
Georg Brandl | a1c6a1c | 2009-01-03 21:26:05 +0000 | [diff] [blame] | 584 | _('rat'), |
| 585 | _('penguin'), |
| 586 | _('python'), ] |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 587 | |
| 588 | del _ |
| 589 | |
| 590 | # ... |
| 591 | for a in animals: |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 592 | print(_(a)) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 593 | |
| 594 | This works because the dummy definition of :func:`_` simply returns the string |
| 595 | unchanged. And this dummy definition will temporarily override any definition |
| 596 | of :func:`_` in the built-in namespace (until the :keyword:`del` command). Take |
| 597 | care, though if you have a previous definition of :func:`_` in the local |
| 598 | namespace. |
| 599 | |
| 600 | Note that the second use of :func:`_` will not identify "a" as being |
Andrew Kuchling | 30c5ad2 | 2013-11-19 11:05:20 -0500 | [diff] [blame] | 601 | translatable to the :program:`gettext` program, because the parameter |
| 602 | is not a string literal. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 603 | |
| 604 | Another way to handle this is with the following example:: |
| 605 | |
| 606 | def N_(message): return message |
| 607 | |
| 608 | animals = [N_('mollusk'), |
| 609 | N_('albatross'), |
Georg Brandl | a1c6a1c | 2009-01-03 21:26:05 +0000 | [diff] [blame] | 610 | N_('rat'), |
| 611 | N_('penguin'), |
| 612 | N_('python'), ] |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 613 | |
| 614 | # ... |
| 615 | for a in animals: |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 616 | print(_(a)) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 617 | |
Andrew Kuchling | 30c5ad2 | 2013-11-19 11:05:20 -0500 | [diff] [blame] | 618 | In this case, you are marking translatable strings with the function |
| 619 | :func:`N_`, which won't conflict with any definition of :func:`_`. |
| 620 | However, you will need to teach your message extraction program to |
| 621 | look for translatable strings marked with :func:`N_`. :program:`xgettext`, |
| 622 | :program:`pygettext`, ``pybabel extract``, and :program:`xpot` all |
| 623 | support this through the use of the :option:`-k` command-line switch. |
| 624 | The choice of :func:`N_` here is totally arbitrary; it could have just |
| 625 | as easily been :func:`MarkThisStringForTranslation`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 626 | |
| 627 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 628 | Acknowledgements |
| 629 | ---------------- |
| 630 | |
| 631 | The following people contributed code, feedback, design suggestions, previous |
| 632 | implementations, and valuable experience to the creation of this module: |
| 633 | |
| 634 | * Peter Funk |
| 635 | |
| 636 | * James Henstridge |
| 637 | |
| 638 | * Juan David Ibáñez Palomar |
| 639 | |
| 640 | * Marc-André Lemburg |
| 641 | |
| 642 | * Martin von Löwis |
| 643 | |
| 644 | * François Pinard |
| 645 | |
| 646 | * Barry Warsaw |
| 647 | |
| 648 | * Gustavo Niemeyer |
| 649 | |
| 650 | .. rubric:: Footnotes |
| 651 | |
| 652 | .. [#] The default locale directory is system dependent; for example, on RedHat Linux |
| 653 | it is :file:`/usr/share/locale`, but on Solaris it is :file:`/usr/lib/locale`. |
| 654 | The :mod:`gettext` module does not try to support these system dependent |
| 655 | defaults; instead its default is :file:`sys.prefix/share/locale`. For this |
| 656 | reason, it is always best to call :func:`bindtextdomain` with an explicit |
| 657 | absolute path at the start of your application. |
| 658 | |
| 659 | .. [#] See the footnote for :func:`bindtextdomain` above. |