squirrel-battle/docs/translation.rst

121 lines
3.8 KiB
ReStructuredText
Raw Normal View History

2020-11-28 15:00:17 +00:00
Traduction
==========
2020-11-28 15:22:06 +00:00
Le jeu Squirrel Battle est entièrement traduit en anglais, en français et en allement.
2020-11-28 15:00:17 +00:00
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)``,
``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.