Documentation on translation

debian/control

@@ -2,7 +2,7 @@ Source: python3-squirrel-battle
 Section: devel
 Priority: optional
 Maintainer: ynerant <squirrel-battle@crans.org>
-Build-Depends: debhelper (>=10~), dh-python, python3-all, python3-setuptools
+Build-Depends: debhelper (>=10~), dh-python, gettext, python3-all, python3-setuptools
 Depends: fonts-noto-color-emoji
 Standards-Version: 4.1.4
 Homepage: https://gitlab.crans.org/ynerant/squirrel-battle

docs/deployment.rst

@@ -34,6 +34,16 @@ paquet ainsi que des détails à fournir à PyPI :
     with open("README.md", "r") as f:
         long_description = f.read()
 
+    # Compile messages
+    for language in ["en", "fr"]:
+        args = ["msgfmt", "--check-format",
+                "-o", f"squirrelbattle/locale/{language}/LC_MESSAGES"
+                      "/squirrelbattle.mo",
+                f"squirrelbattle/locale/{language}/LC_MESSAGES"
+                "/squirrelbattle.po"]
+        print(f"Compiling {language} messages...")
+        subprocess.Popen(args)
+
     setup(
         name="squirrel-battle",
         version="3.14.1",
@@ -60,7 +70,7 @@ paquet ainsi que des détails à fournir à PyPI :
         ],
         python_requires='>=3.6',
         include_package_data=True,
-        package_data={"squirrelbattle": ["assets/*"]},
+        package_data={"squirrelbattle": ["assets/*", "locale/*/*/*.mo"]},
         entry_points={
             "console_scripts": [
                 "squirrel-battle = squirrelbattle.bootstrap:Bootstrap.run_game",
@@ -72,6 +82,8 @@ Ce fichier contient le nom du paquet, sa version, l'auteur et son contact,
 sa description en une ligne et sa description longue, le lien d'accueil du projet,
 sa licence, ses classificateurs et son exécutable.
 
+Il commence tout d'abord par compiler les fichiers de `traduction <translation.html>`_.
+
 Le paramètre ``entry_points`` définit un exécutable nommé ``squirrel-battle``,
 qui permet de lancer le jeu.
 
@@ -167,7 +179,7 @@ du dépôt Git. Le fichier ``PKGBUILD`` dispose de cette structure :
     url="https://gitlab.crans.org/ynerant/squirrel-battle"
     license=('GPLv3')
     depends=('python')
-    makedepends=('python-setuptools')
+    makedepends=('gettext' 'python-setuptools')
     depends=('noto-fonts-emoji')
     checkdepends=('python-tox')
     ssource=("git+https://gitlab.crans.org/ynerant/squirrel-battle.git")
@@ -217,7 +229,7 @@ les releases, est plus ou moins similaire :
     url="https://gitlab.crans.org/ynerant/squirrel-battle"
     license=('GPLv3')
     depends=('python')
-    makedepends=('python-setuptools')
+    makedepends=('gettext' 'python-setuptools')
     depends=('noto-fonts-emoji')
     checkdepends=('python-tox')
     source=("https://gitlab.crans.org/ynerant/squirrel-battle/-/archive/v3.14.1/$pkgbase-v$pkgver.tar.gz")
@@ -296,7 +308,7 @@ D'abord on installe les paquets nécessaires :
 .. code::
 
   apt update
-  apt --no-install-recommends install build-essential debmake dh-python debhelper python3-all python3-setuptools
+  apt --no-install-recommends install build-essential debmake dh-python debhelper gettext python3-all python3-setuptools
 
 On peut ensuite construire le paquet :
 

docs/index.rst

@@ -37,6 +37,7 @@ Bienvenue dans la documentation de Squirrel Battle !
    install-dev
    tests
    display/index
+   translation
    deployment
    documentation
 

docs/install-dev.rst

@@ -1,16 +1,19 @@
 Installation d'un environnement de développement
 ================================================
 
-Il est toujours préférable de travailler dans un environnement Python isolé du reste de son instalation.
+Il est toujours préférable de travailler dans un environnement Python isolé du
+reste de son instalation.
 
 1.  **Installation des dépendances de la distribution.**
-    Vous devez déjà installer Python et le module qui permet de créer des environnements virtuels.
-    On donne ci-dessous l'exemple pour une distribution basée sur Debian, mais vous pouvez facilement adapter pour ArchLinux ou autre.
+    Vous devez déjà installer Python et le module qui permet de créer des
+    environnements virtuels.
+    On donne ci-dessous l'exemple pour une distribution basée sur Debian,
+    mais vous pouvez facilement adapter pour ArchLinux ou autre.
 
 .. code:: bash
 
     $ sudo apt update
-    $ sudo apt install --no-install-recommends -y python3-setuptools python3-venv python3-dev git
+    $ sudo apt install --no-install-recommends -y python3-setuptools python3-venv python3-dev gettext git
 
 2.  **Clonage du dépot** là où vous voulez :
 
@@ -25,7 +28,13 @@ Il est toujours préférable de travailler dans un environnement Python isolé d
 
     $ python3 -m venv env
     $ source env/bin/activate  # entrer dans l'environnement
-    (env)$ pip3 install -r requirements.txt
-    (env)$ deactivate  # sortir de l'environnement
+    (env) $ pip3 install -r requirements.txt
+    (env) $ deactivate  # sortir de l'environnement
+
+4.  **Compilation des messages de traduction.**
+
+.. code:: bash
+
+    (env) $ python3 main.py --compilemessages
 
 Le lancement du jeu se fait en lançant la commande ``python3 main.py``.

docs/translation.rst

@@ -0,0 +1,120 @@
+Traduction
+==========
+
+Le jeu Squirrel Battle est entièrement traduit en anglais et en français.
+La langue se choisit dans les `paramètres <settings.html>`_.
+
+
+Utitisation
+-----------
+
+Les traductions sont gérées grâce au module natif ``gettext``. Le module
+``squirrelbattle.translations`` s'occupe d'installer les traductions, et de
+donner les chaînes traduites.
+
+Pour choisir la langue, il faut appeler ``Translator.setlocale(language: str)``,
+où ``language`` correspond au code à 2 lettres de la langue.
+
+Enfin, le module expose une fonction ``gettext(str) -> str`` qui permet de
+traduire les chaînes.
+
+Il est courant et recommandé d'importer cette fonction sous l'alias ``_``,
+afin de limiter la verbositer et de permettre de rendre facilement une chaîne
+traduisible.
+
+.. code:: python
+
+  from squirrelbattle.translations import gettext as _, Translator
+
+  Translator.setlocale("fr")
+  print(_("I am a translatable string"))
+  print("I am not translatable")
+
+Si les traductions sont bien faites (voir ci-dessous), cela donnera :
+
+.. code::
+
+  Je suis une chaîne traduisible
+  I am not translatable
+
+À noter que si la chaîne n'est pas traduite, alors par défaut on renvoie la
+chaîne elle-même.
+
+
+Extraction des chaînes à traduire
+---------------------------------
+
+L'appel à ``gettext`` ne fait pas que traduire les chaînes : il est possible
+également d'extraire toutes les chaînes à traduire.
+
+Il est nécessaire d'installer le paquet Linux ``gettext`` pour cela.
+
+L'utilitaire ``xgettext`` s'occupe de cette extraction. Il s'utilise de la façon
+suivante :
+
+.. code:: bash
+
+  xgettext --from-code utf-8 -o output_file.po source_1.py ... source_n.py
+
+Afin de ne pas avoir à sélectionner manuellement chaque fichier, il est possible
+d'appeler directement ``python3 main.py --makemessages``. Cela a pour effet
+d'exécuter pour chaque langue ``<LANG>`` :
+
+.. code:: bash
+
+  find squirrelbattle -iname '*.py' | xargs xgettext --from-code utf-8
+                    --add-comments
+                    --package-name=squirrelbattle
+                    --package-version=3.14.1
+                    "--copyright-holder=ÿnérant, eichhornchen, nicomarg, charlse"
+                    --msgid-bugs-address=squirrel-battle@crans.org
+                    -o squirrelbattle/locale/<LANG>/LC_MESSAGES/squirrelbattle.po
+
+Les fichiers de traductions se trouvent alors dans
+``squirrelbattle/locale/<LANG>/LC_MESSAGES/squirrelbattle.po``.
+
+
+Traduire les chaînes
+--------------------
+
+Après extraction des chaînes, les chaînes à traduire se trouvent dans
+``squirrelbattle/locale/<LANG>/LC_MESSAGES/squirrelbattle.po``, comme indiqué
+ci-dessus.
+
+Ce fichier peut-être édité avec un utilitaire tel que ``poedit``, sur
+l'interface Web sur `<https://translate.ynerant.fr/squirrel-battle/squirrel-battle>`_,
+mais surtout manuellement avec un éditeur de texte.
+
+Dans ce fichier, on obtient pour chaque chaîne à traduire un paragraphe de la
+forme :
+
+.. code:: po
+
+  #: main.py:4
+  msgid "I am a translatable string"
+  msgstr "Je suis une chaîne traduisible"
+
+Il sufift de remplir les champs ``msgstr``.
+
+
+Compilation des chaînes
+-----------------------
+
+Pour gagner en efficacité, les chaînes sont compilées dans un fichier avec
+l'extension ``.mo``. Ce sont ces fichiers qui sont lus par le module de traduction.
+
+Pour compiler les traductions, c'est l'utilitaire ``msgfmt`` fourni toujours par
+le paquet Linux ``gettext`` que nous utilisons. Il s'utilise assez simplement :
+
+.. code:: bash
+
+  msgfmt po_file.po -o mo_file.mo
+
+À nouveau, il est possible de compiler automatiquement les messages en exécutant
+``python3 main.py --compilemessages``.
+
+.. warning::
+
+  On ne partagera pas dans le dépôt Git les fichiers compilé. En développement,
+  on compilera soi-même les messages, et en production, la construction des
+  paquets se charge de compiler automatiquement les traductions.

setup.py

@@ -46,7 +46,7 @@ setup(
     ],
     python_requires='>=3.6',
     include_package_data=True,
-    package_data={"squirrelbattle": ["assets/*", "locale/*/*/*"]},
+    package_data={"squirrelbattle": ["assets/*", "locale/*/*/*.mo"]},
     entry_points={
         "console_scripts": [
             "squirrel-battle = squirrelbattle.bootstrap:Bootstrap.run_game",