diff --git a/Doc/library/gettext.rst b/Doc/library/gettext.rst --- a/Doc/library/gettext.rst +++ b/Doc/library/gettext.rst @@ -3,8 +3,8 @@ .. module:: gettext :synopsis: Multilingual internationalization services. -.. moduleauthor:: Barry A. Warsaw -.. sectionauthor:: Barry A. Warsaw +.. moduleauthor:: Barry A. Warsaw +.. sectionauthor:: Barry A. Warsaw **Source code:** :source:`Lib/gettext.py` @@ -94,7 +94,8 @@ The Plural formula is taken from the catalog header. It is a C or Python expression that has a free variable *n*; the expression evaluates to the index - of the plural in the catalog. See the GNU gettext documentation for the precise + of the plural in the catalog. See `the GNU gettext documentation `__ + for the precise syntax to be used in :file:`.po` files and the formulas for a variety of languages. @@ -451,35 +452,35 @@ In this example, the string ``'writing a log message'`` is marked as a candidate for translation, while the strings ``'mylog.txt'`` and ``'w'`` are not. -The Python distribution comes with two tools which help you generate the message -catalogs once you've prepared your source code. These may or may not be -available from a binary distribution, but they can be found in a source -distribution, in the :file:`Tools/i18n` directory. +There are a few tools to extract the strings meant for translation. +The original GNU :program:`gettext` only supports C or C++ source code but its +extended version :program:`xgettext` [#]_ scans code written in a number of +languages, including Python, to find strings marked as translatable. -The :program:`pygettext` [#]_ program scans all your Python source code looking -for the strings you previously marked as translatable. It is similar to the GNU -:program:`gettext` program except that it understands all the intricacies of -Python source code, but knows nothing about C or C++ source code. You don't -need GNU ``gettext`` unless you're also going to be translating C code (such as -C extension modules). +:program:`xgettext`, :program:`pygettext`, and similar tools generate :file:`.po` files that are message +catalogs. They are structured human-readable files that +contain every marked string in the source code, along with a placeholder for the +translation strings. -:program:`pygettext` generates textual Uniforum-style human readable message -catalog :file:`.pot` files, essentially structured human readable files which -contain every marked string in the source code, along with a placeholder for the -translation strings. :program:`pygettext` is a command line script that supports -a similar command line interface as :program:`xgettext`; for details on its use, -run:: +Copies of these :file:`.po` files are then handed over to the individual human +translators who write translated versions for every supported natural +language. They send back the completed language-specific versions as a +:file:`.po` file that's compiled into a +machine-readable :file:`.mo` binary catalog file using the :program:`msgfmt` +program. The :file:`.mo` files are used by the :mod:`gettext` module for the +actual translation processing at run-time. - pygettext.py --help - -Copies of these :file:`.pot` files are then handed over to the individual human -translators who write language-specific versions for every supported natural -language. They send you back the filled in language-specific versions as a -:file:`.po` file. Using the :program:`msgfmt.py` [#]_ program (in the -:file:`Tools/i18n` directory), you take the :file:`.po` files from your -translators and generate the machine-readable :file:`.mo` binary catalog files. -The :file:`.mo` files are what the :mod:`gettext` module uses for the actual -translation processing during run-time. +(Python also includes pure-Python versions of these programs, called +:program:`pygettext` and :file:`msgfmt.py`; some Python distributions +will install them for you. :program:`pygettext` is similar to +:program:`xgettext`, but only understands Python source code and +cannot handle other programming languages such as C or C++. +:program:`pygettext` supports a command-line interface similar to +:program:`xgettext`; for details on its use, run ``pygettext.py +--help``. :program:`msgfmt.py` is binary compatible with GNU +:program:`msgfmt`. With these two programs, you may not need the GNU +:program:`gettext` package to internationalize your Python +applications.) How you use the :mod:`gettext` module in your code depends on whether you are internationalizing a single module or your entire application. The next two @@ -517,7 +518,7 @@ import gettext gettext.install('myapplication') -If you need to set the locale directory, you can pass these into the +If you need to set the locale directory, you can pass it into the :func:`install` function:: import gettext @@ -590,7 +591,7 @@ namespace. Note that the second use of :func:`_` will not identify "a" as being -translatable to the :program:`pygettext` program, since it is not a string. +translatable to the :program:`gettext` program, since it is not a string. Another way to handle this is with the following example:: @@ -607,10 +608,13 @@ print(_(a)) In this case, you are marking translatable strings with the function :func:`N_`, -[#]_ which won't conflict with any definition of :func:`_`. However, you will +which won't conflict with any definition of :func:`_`. However, you will need to teach your message extraction program to look for translatable strings -marked with :func:`N_`. :program:`pygettext` and :program:`xpot` both support -this through the use of command line switches. +marked with :func:`N_`. :program:`xgettext`, :program:`pygettext`, and +:program:`xpot` all support +this through the use of the :option:`-k` command-line switch. +The choice of :func:`N_` here is totally arbitrary; it could have just as easily +been :func:`MarkThisStringForTranslation`. Acknowledgements @@ -649,12 +653,3 @@ .. [#] François Pinard has written a program called :program:`xpot` which does a similar job. It is available as part of his `po-utils package `_. - -.. [#] :program:`msgfmt.py` is binary compatible with GNU :program:`msgfmt` except that - it provides a simpler, all-Python implementation. With this and - :program:`pygettext.py`, you generally won't need to install the GNU - :program:`gettext` package to internationalize your Python applications. - -.. [#] The choice of :func:`N_` here is totally arbitrary; it could have just as easily - been :func:`MarkThisStringForTranslation`. -