121 lines
3.8 KiB
ReStructuredText
121 lines
3.8 KiB
ReStructuredText
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=23.14
|
|
"--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.
|