squirrel-battle/docs/translation.rst

Traduction
==========

Le jeu Squirrel Battle est entièrement traduit en anglais, en français et en allement.
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.