[3.11] gh-54738: Add argparse i18n howto (GH-104562) (#107101)

(cherry picked from commit dcd7acb04a719d8d30c8d03b80d3d48b6c035e14)

Co-authored-by: Tomas R <tomas.roun8@gmail.com>

diff --git a/Doc/howto/argparse.rst b/Doc/howto/argparse.rst
index 9ea140c41a09c79e46c07a7f5d74807ce065ad68..06a301a120c1c74c548182da7f264cdc0dfee549 100644 (file)
--- a/Doc/howto/argparse.rst
+++ b/Doc/howto/argparse.rst
@@ -759,6 +759,59 @@ but not both at the same time:
      -q, --quiet
 
 
+How to translate the argparse output
+====================================
+
+The output of the :mod:`argparse` module such as its help text and error
+messages are all made translatable using the :mod:`gettext` module. This
+allows applications to easily localize messages produced by
+:mod:`argparse`. See also :ref:`i18n-howto`.
+
+For instance, in this :mod:`argparse` output:
+
+.. code-block:: shell-session
+
+   $ python prog.py --help
+   usage: prog.py [-h] [-v | -q] x y
+
+   calculate X to the power of Y
+
+   positional arguments:
+     x              the base
+     y              the exponent
+
+   options:
+     -h, --help     show this help message and exit
+     -v, --verbose
+     -q, --quiet
+
+The strings ``usage:``, ``positional arguments:``, ``options:`` and
+``show this help message and exit`` are all translatable.
+
+In order to translate these strings, they must first be extracted
+into a ``.po`` file. For example, using `Babel <https://babel.pocoo.org/>`__,
+run this command:
+
+.. code-block:: shell-session
+
+  $ pybabel extract -o messages.po /usr/lib/python3.12/argparse.py
+
+This command will extract all translatable strings from the :mod:`argparse`
+module and output them into a file named ``messages.po``. This command assumes
+that your Python installation is in ``/usr/lib``.
+
+You can find out the location of the :mod:`argparse` module on your system
+using this script::
+
+   import argparse
+   print(argparse.__file__)
+
+Once the messages in the ``.po`` file are translated and the translations are
+installed using :mod:`gettext`, :mod:`argparse` will be able to display the
+translated messages.
+
+To translate your own strings in the :mod:`argparse` output, use :mod:`gettext`.
+
 Conclusion
 ==========
 

diff --git a/Doc/library/gettext.rst b/Doc/library/gettext.rst
index 747f8703b750ec3614170ee9cfd413019ec19486..88a65b980d310feaa85b2a90f95bfb92cabb6f9f 100644 (file)
--- a/Doc/library/gettext.rst
+++ b/Doc/library/gettext.rst
@@ -411,6 +411,7 @@ One difference between this module and Henstridge's: his catalog objects
 supported access through a mapping API, but this appears to be unused and so is
 not currently supported.
 
+.. _i18n-howto:
 
 Internationalizing your programs and modules
 --------------------------------------------

diff --git a/Misc/NEWS.d/next/Documentation/2023-05-16-22-08-24.gh-issue-54738.mJvCnj.rst b/Misc/NEWS.d/next/Documentation/2023-05-16-22-08-24.gh-issue-54738.mJvCnj.rst
new file mode 100644 (file)
index 0000000..4da58fc
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2023-05-16-22-08-24.gh-issue-54738.mJvCnj.rst
@@ -0,0 +1 @@
+Add documentation on how to localize the :mod:`argparse` module.