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