From ff2c6cd2f65889cbfcac2e888547e3aec9da06be Mon Sep 17 00:00:00 2001 From: Tomas Roun Date: Mon, 15 May 2023 22:59:14 +0200 Subject: [PATCH 1/4] Add argparse i18n howto --- Doc/howto/argparse.rst | 53 +++++++++++++++++++++++++++++++++++++++++ Doc/library/gettext.rst | 1 + 2 files changed, 54 insertions(+) diff --git a/Doc/howto/argparse.rst b/Doc/howto/argparse.rst index 52e98fa9620194..f2927b1fba9736 100644 --- a/Doc/howto/argparse.rst +++ b/Doc/howto/argparse.rst @@ -788,6 +788,59 @@ but not both at the same time: -q, --quiet +Internationalization support +============================ + +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`. (If you are not familiar with Internationalization and +Localization, you can check out :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, you will probably want to extract them +into a ``.po`` file. For example, using `Babel `__, +you can run: + +.. 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 simple 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. + + Conclusion ========== diff --git a/Doc/library/gettext.rst b/Doc/library/gettext.rst index 747f8703b750ec..88a65b980d310f 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 -------------------------------------------- From 2de7a06e64f0a9b81ce50c2b9d6a5fb91396aee4 Mon Sep 17 00:00:00 2001 From: Tomas Roun Date: Tue, 16 May 2023 22:10:46 +0200 Subject: [PATCH 2/4] Add news entry --- .../Documentation/2023-05-16-22-08-24.gh-issue-54738.mJvCnj.rst | 1 + 1 file changed, 1 insertion(+) create mode 100644 Misc/NEWS.d/next/Documentation/2023-05-16-22-08-24.gh-issue-54738.mJvCnj.rst 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 00000000000000..4da58fc982b6d7 --- /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. From 8fcd1b54d1be990e5474def9f238a11a7dd13bc6 Mon Sep 17 00:00:00 2001 From: Tomas R Date: Sat, 22 Jul 2023 10:55:46 +0200 Subject: [PATCH 3/4] Apply changes from review --- Doc/howto/argparse.rst | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/Doc/howto/argparse.rst b/Doc/howto/argparse.rst index f2927b1fba9736..ab253d2d55c153 100644 --- a/Doc/howto/argparse.rst +++ b/Doc/howto/argparse.rst @@ -788,14 +788,13 @@ but not both at the same time: -q, --quiet -Internationalization support -============================ +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`. (If you are not familiar with Internationalization and -Localization, you can check out :ref:`i18n-howto`). +:mod:`argparse`. See also :ref:`i18n-howto`. For instance, in this :mod:`argparse` output: @@ -818,9 +817,9 @@ For instance, in this :mod:`argparse` output: The strings ``usage:``, ``positional arguments:``, ``options:`` and ``show this help message and exit`` are all translatable. -In order to translate these strings, you will probably want to extract them +In order to translate these strings, they must first be extracted into a ``.po`` file. For example, using `Babel `__, -you can run: +run this command: .. code-block:: shell-session @@ -831,7 +830,7 @@ 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 simple script:: +using this script:: import argparse print(argparse.__file__) From 4f13dea4191843ef63ccd5ff85f731eb06932a41 Mon Sep 17 00:00:00 2001 From: Tomas R Date: Sun, 23 Jul 2023 10:30:16 +0200 Subject: [PATCH 4/4] Mention gettext for user-defined strings --- Doc/howto/argparse.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/Doc/howto/argparse.rst b/Doc/howto/argparse.rst index ab253d2d55c153..ae5bab90bf8131 100644 --- a/Doc/howto/argparse.rst +++ b/Doc/howto/argparse.rst @@ -839,6 +839,7 @@ 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 ==========