From c71f48eda454487da709e6bd60b78ecdb4be3081 Mon Sep 17 00:00:00 2001
From: Tomas R <tomas.roun8@gmail.com>
Date: Sun, 23 Jul 2023 11:10:38 +0200
Subject: [PATCH] gh-54738: Add argparse i18n howto (#104562)

---
 Doc/howto/argparse.rst                        | 53 +++++++++++++++++++
 Doc/library/gettext.rst                       |  1 +
 ...3-05-16-22-08-24.gh-issue-54738.mJvCnj.rst |  1 +
 3 files changed, 55 insertions(+)
 create mode 100644 Misc/NEWS.d/next/Documentation/2023-05-16-22-08-24.gh-issue-54738.mJvCnj.rst

diff --git a/Doc/howto/argparse.rst b/Doc/howto/argparse.rst
index 52e98fa96201945..ae5bab90bf81315 100644
--- a/Doc/howto/argparse.rst
+++ b/Doc/howto/argparse.rst
@@ -788,6 +788,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 747f8703b750ec3..88a65b980d310fe 100644
--- 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
index 000000000000000..4da58fc982b6d70
--- /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.