Add a gettext example

Add a small example along with a German translation using gettext.
Add a tutorial.

Change-Id: I254a5a66521ecc2827a5811469d9d21360f99b81
Reviewed-by: Christian Tismer <tismer@stackless.com>
(cherry picked from commit 4b55835767b7aca1b49a8ab1c1966521695abb56)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

7 files changed, 359 insertions, 0 deletions

diff --git a/examples/widgets/gettext/gettext.pyproject b/examples/widgets/gettext/gettext.pyproject
new file mode 100644
index 000000000..f304bf8a5
--- /dev/null
+++ b/examples/widgets/gettext/gettext.pyproject
@@ -0,0 +1,4 @@
+{
+    "files": ["main.py", "locales/example.pot",
+              "locales/de_DE/LC_MESSAGES/example.pot"]
+}
diff --git a/examples/widgets/gettext/locales/de_DE/LC_MESSAGES/example.mo b/examples/widgets/gettext/locales/de_DE/LC_MESSAGES/example.mo
new file mode 100644
index 000000000..c1862497d
--- /dev/null
+++ b/examples/widgets/gettext/locales/de_DE/LC_MESSAGES/example.mo
diff --git a/examples/widgets/gettext/locales/de_DE/LC_MESSAGES/example.pot b/examples/widgets/gettext/locales/de_DE/LC_MESSAGES/example.pot
new file mode 100644
index 000000000..07b0e09c9
--- /dev/null
+++ b/examples/widgets/gettext/locales/de_DE/LC_MESSAGES/example.pot
@@ -0,0 +1,69 @@
+#############################################################################
+##
+## Copyright (C) 2021 The Qt Company Ltd.
+## Contact: http://www.qt.io/licensing/
+##
+## This file is part of the Qt for Python examples of the Qt Toolkit.
+##
+## $QT_BEGIN_LICENSE:BSD$
+## You may use this file under the terms of the BSD license as follows:
+##
+## "Redistribution and use in source and binary forms, with or without
+## modification, are permitted provided that the following conditions are
+## met:
+##   * Redistributions of source code must retain the above copyright
+##     notice, this list of conditions and the following disclaimer.
+##   * Redistributions in binary form must reproduce the above copyright
+##     notice, this list of conditions and the following disclaimer in
+##     the documentation and/or other materials provided with the
+##     distribution.
+##   * Neither the name of The Qt Company Ltd nor the names of its
+##     contributors may be used to endorse or promote products derived
+##     from this software without specific prior written permission.
+##
+##
+## THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+## "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+## LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+## A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+## OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+## SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+## LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+## DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+## THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+## (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+## OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+##
+## $QT_END_LICENSE$
+##
+#############################################################################
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: PySide6 gettext example\n"
+"POT-Creation-Date: 2021-07-05 14:16+0200\n"
+"Language: de_DE\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Plural-Forms: nplurals=2; plural=n != 1;\n"
+
+#: main.py:57
+msgid "&File"
+msgstr "&Datei"
+
+#: main.py:58
+msgid "Quit"
+msgstr "Beenden"
+
+#: main.py:59
+msgid "CTRL+Q"
+msgstr "CTRL+B"
+
+#: main.py:73
+#, python-brace-format
+msgid "{0} language selected"
+msgid_plural "{0} languages selected"
+msgstr[0] "{0} Sprache ausgewählt"
+msgstr[1] "{0} Sprachen ausgewählt"
diff --git a/examples/widgets/gettext/locales/example.pot b/examples/widgets/gettext/locales/example.pot
new file mode 100644
index 000000000..e2c16e407
--- /dev/null
+++ b/examples/widgets/gettext/locales/example.pot
@@ -0,0 +1,69 @@
+#############################################################################
+##
+## Copyright (C) 2021 The Qt Company Ltd.
+## Contact: http://www.qt.io/licensing/
+##
+## This file is part of the Qt for Python examples of the Qt Toolkit.
+##
+## $QT_BEGIN_LICENSE:BSD$
+## You may use this file under the terms of the BSD license as follows:
+##
+## "Redistribution and use in source and binary forms, with or without
+## modification, are permitted provided that the following conditions are
+## met:
+##   * Redistributions of source code must retain the above copyright
+##     notice, this list of conditions and the following disclaimer.
+##   * Redistributions in binary form must reproduce the above copyright
+##     notice, this list of conditions and the following disclaimer in
+##     the documentation and/or other materials provided with the
+##     distribution.
+##   * Neither the name of The Qt Company Ltd nor the names of its
+##     contributors may be used to endorse or promote products derived
+##     from this software without specific prior written permission.
+##
+##
+## THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+## "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+## LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+## A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+## OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+## SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+## LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+## DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+## THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+## (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+## OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+##
+## $QT_END_LICENSE$
+##
+#############################################################################
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: PySide6 gettext example\n"
+"POT-Creation-Date: 2021-07-05 14:16+0200\n"
+"Language: de_DE\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Plural-Forms: nplurals=2; plural==n != 1;\n"
+
+#: main.py:57
+msgid "&File"
+msgstr ""
+
+#: main.py:58
+msgid "Quit"
+msgstr ""
+
+#: main.py:59
+msgid "CTRL+Q"
+msgstr ""
+
+#: main.py:73
+#, python-brace-format
+msgid "{0} language selected"
+msgid_plural "{0} languages selected"
+msgstr[0] ""
+msgstr[1] ""
diff --git a/examples/widgets/gettext/main.py b/examples/widgets/gettext/main.py
new file mode 100644
index 000000000..be0579263
--- /dev/null
+++ b/examples/widgets/gettext/main.py
@@ -0,0 +1,97 @@
+#############################################################################
+##
+## Copyright (C) 2021 The Qt Company Ltd.
+## Contact: http://www.qt.io/licensing/
+##
+## This file is part of the Qt for Python examples of the Qt Toolkit.
+##
+## $QT_BEGIN_LICENSE:BSD$
+## You may use this file under the terms of the BSD license as follows:
+##
+## "Redistribution and use in source and binary forms, with or without
+## modification, are permitted provided that the following conditions are
+## met:
+##   * Redistributions of source code must retain the above copyright
+##     notice, this list of conditions and the following disclaimer.
+##   * Redistributions in binary form must reproduce the above copyright
+##     notice, this list of conditions and the following disclaimer in
+##     the documentation and/or other materials provided with the
+##     distribution.
+##   * Neither the name of The Qt Company Ltd nor the names of its
+##     contributors may be used to endorse or promote products derived
+##     from this software without specific prior written permission.
+##
+##
+## THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+## "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+## LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+## A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+## OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+## SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+## LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+## DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+## THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+## (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+## OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+##
+## $QT_END_LICENSE$
+##
+#############################################################################
+
+from pathlib import Path
+import gettext
+import sys
+
+from PySide6.QtCore import QItemSelection, QLocale, Qt, Slot
+from PySide6.QtWidgets import (QAbstractItemView, QApplication, QListWidget,
+                               QMainWindow, QWidget)
+
+
+_ = None
+ngettext = None
+
+
+class Window(QMainWindow):
+    def __init__(self):
+        super().__init__()
+        file_menu = self.menuBar().addMenu(_("&File"))
+        quit_action = file_menu.addAction(_("Quit"))
+        quit_action.setShortcut(_("CTRL+Q"))
+        quit_action.triggered.connect(self.close)
+
+        self._list_widget = QListWidget()
+        self._list_widget.setSelectionMode(QAbstractItemView.MultiSelection)
+        self._list_widget.selectionModel().selectionChanged.connect(self.selection_changed)
+        self._list_widget.addItem("C++")
+        self._list_widget.addItem("Java")
+        self._list_widget.addItem("Python")
+        self.setCentralWidget(self._list_widget)
+
+    @Slot(QItemSelection, QItemSelection)
+    def selection_changed(self, selected, deselected):
+        count = len(self._list_widget.selectionModel().selectedRows())
+        message = ngettext("{0} language selected",
+                           "{0} languages selected", count).format(count)
+        self.statusBar().showMessage(message)
+
+
+if __name__ == '__main__':
+    app = QApplication(sys.argv)
+
+    src_dir = Path(__file__).resolve().parent
+    try:
+        translation = gettext.translation('example', localedir=src_dir / 'locales')
+        if translation:
+            translation.install()
+            _ = translation.gettext
+            ngettext = translation.ngettext
+    except FileNotFoundError:
+        pass
+    if not _:
+        _ = gettext.gettext
+        ngettext = gettext.ngettext
+        print('No translation found')
+
+    window = Window()
+    window.show()
+    sys.exit(app.exec())
diff --git a/sources/pyside6/doc/tutorials/basictutorial/translations.rst b/sources/pyside6/doc/tutorials/basictutorial/translations.rst
new file mode 100644
index 000000000..eb51baac3
--- /dev/null
+++ b/sources/pyside6/doc/tutorials/basictutorial/translations.rst
@@ -0,0 +1,119 @@
+.. _translations:
+
+Translating Applications
+========================
+
+GNU gettext
+-----------
+
+The `GNU gettext <https://docs.python.org/3/library/gettext.html>`_ module
+can be used to provide translations for applications.
+
+The ``examples/widgets/gettext`` example illustrates this. The example is
+very simple, it has a menu and shows a list of programming languages with
+multiselection.
+
+Translation works by passing the message strings through function calls that
+look up the translation. It is common to alias the main translation function
+to ``_``. There is a special translation function for sentences that contain
+a plural form depending on a count ("{0} items(s) selected"). It is commonly
+aliased to ``ngettext``.
+
+Those functions are defined at the top:
+
+    .. code-block:: python
+
+        import gettext
+        ...
+        _ = None
+        ngettext = None
+
+and later assigned as follows:
+
+    .. code-block:: python
+
+        src_dir = Path(__file__).resolve().parent
+        try:
+            translation = gettext.translation('example', localedir=src_dir / 'locales')
+            if translation:
+                translation.install()
+                _ = translation.gettext
+                ngettext = translation.ngettext
+        except FileNotFoundError:
+            pass
+        if not _:
+            _ = gettext.gettext
+            ngettext = gettext.ngettext
+
+This specifies that our translation file has the base name ``example`` and
+will be found in the source tree under ``locales``. The code will try
+to load a translation matching the current language.
+
+Messages to be translated look like:
+
+    .. code-block:: python
+
+        file_menu = self.menuBar().addMenu(_("&File"))
+
+The status bar message shown in response to a selection change uses
+a plural form depending on a count:
+
+    .. code-block:: python
+
+        count = len(self._list_widget.selectionModel().selectedRows())
+        message = ngettext("{0} language selected",
+                           "{0} languages selected", count).format(count)
+
+The ``ngettext()`` function takes the singular form, plural form and the count.
+The returned string still contains the formatting placeholder, so it needs
+to be passed through ``format()``.
+
+In order to translate the messages to say German, a template file (``.pot``)
+is first created:
+
+.. code-block:: bash
+
+    mkdir -p locales/de_DE/LC_MESSAGES
+    xgettext -L Python -o locales/example.pot main.py
+
+This file has a few generic placeholders which can be replaced by the
+appropriate values.  It is then copied to the ``de_DE/LC_MESSAGES`` directory.
+
+    .. code-block:: bash
+
+        cd locales/de_DE/LC_MESSAGES/
+        cp ../../example.pot .
+
+Further adaptions need to be made to account for the German plural
+form and encoding:
+
+    .. code-block::
+
+        "Project-Id-Version: PySide6 gettext example\n"
+        "POT-Creation-Date: 2021-07-05 14:16+0200\n"
+        "Language: de_DE\n"
+        "MIME-Version: 1.0\n"
+        "Content-Type: text/plain; charset=UTF-8\n"
+        "Content-Transfer-Encoding: 8bit\n"
+        "Plural-Forms: nplurals=2; plural=n != 1;\n"
+
+Below, the translated messages can be given:
+
+    .. code-block::
+
+        #: main.py:57
+        msgid "&File"
+        msgstr "&Datei"
+
+Finally, the ``.pot`` is converted to its binary form (machine object file,
+``.mo``), which needs to be deployed:
+
+    .. code-block:: bash
+
+        msgfmt -o example.mo example.pot
+
+The example can then be run in German:
+
+    .. code-block:: bash
+
+        LANG=de python main.py
diff --git a/sources/pyside6/doc/tutorials/index.rst b/sources/pyside6/doc/tutorials/index.rst
index 51ff02401..ae02153e4 100644
--- a/sources/pyside6/doc/tutorials/index.rst
+++ b/sources/pyside6/doc/tutorials/index.rst
@@ -40,6 +40,7 @@ names and how they look like.
     basictutorial/treewidget.rst
     basictutorial/uifiles.rst
     basictutorial/qrcfiles.rst
+    basictutorial/translations.rst
     basictutorial/widgetstyling.rst