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