Internationalisation

Added in version 1.1.

En complément des traductions fournies pour les messages générés par Sphinx comme les barres de navigation, Sphinx offre un mécanisme facilitant la traduction du document en lui-même. Voir les Options pour l’internationalisation pour les détails de configuration.

../../_images/translation.svg

Visualisation du flux de traitement des traductions dans Sphinx. (Le schéma est réalisé avec plantuml.)

Détails de l’internationalisation avec Sphinx

gettext [1] est un standard reconnu pour l’internationalisation et la localisation. Il met naïvement en correspondance les messages dans un programme avec des chaines traduites. Sphinx utilise cette infrastructure pour traduire des documents entiers.

Initially project maintainers have to collect all translatable strings (also referred to as messages) to make them known to translators. Sphinx extracts these through invocation of sphinx-build -M gettext.

Chaque élément du doctree se retrouvera individuellement dans un message unique, les liste se trouvant ainsi séparées en différents éléments, alors que les paragraphes le seront aussi grossièrement qu’ils le sont dans le document original. Ceci permet des mises à jour de documents transparentes tout en fournissant aux traducteurs un peu de contexte dans les passages en texte libre. Il appartient au mainteneur de séparer les paragraphes trop longs, car il n’existe pas de manière fiable de le faire automatiquement.

Après que Sphinx a exécuté le MessageCatalogBuilder, vous trouverez une collection de fichiers .pot dans votre répertoire de sortie. Ce sont les catalogues modèles et contiennent les messages dans votre langue d’origine uniquement.

Ils peuvent être distribués aux traducteurs qui les transformeront en fichiers .po — dits catalogues de messages — mettant en correspondance les messages originaux avec les chaines en langues étrangères.

gettext les compile sous forme de catalogues binaires avec msgfmt pour des raisons d’efficacité. Si vous rendez ces fichiers découvrables avec le paramètre locale_dirs pour votre language, Sphinx les trouvera automatiquement.

Par exemple : vous disposez d’un document usage.rst dans votre projet Sphinx. Le constructeur gettext génèrera les messages dans usage.pot. Imaginons que la traduction espagnole [2] soit stockée dans usage.po. Pour que vos documents générés soient traduits, vous devriez suivre les instructions suivantes :

  • Compiler vos catalogues de messages dans un répertoire de locales, disons locale, afin qu’ils se retrouvent dans ./locale/es/LC_MESSAGES/usage.mo dans votre répertoire source (où es est votre code langue pour l’Espagnol)

    msgfmt "usage.po" -o "locale/es/LC_MESSAGES/usage.mo"

  • Configurer locale_dirs comme valant ["locale/"].

  • Configurer language comme valant es (également possible grâce à l’option -D de sphinx-build).

  • Générer la sortie voulue.

Afin d’éviter les erreurs, un avertissement est émis si les références croisées dans le paragraphe traduit ne correspondent pas à celles de l’original. Ce comportement peut être désactivé globalement avec le paramètre suppress_warnings. Autrement, pour le supprimer pour certains messages seulement, terminer ceux-ci avec #noqa comme ceci

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse
risus tortor, luctus id ultrices at. #noqa

(Écrire \#noqua si vous souhaitez que « #noqua » apparaisse littéralement dans le texte. Ceci ne s’applique pas aux blocs de code dans lesquels #noqua est ignoré puisqu’ils ne contiennent pas de références croisées de toute façon.)

Added in version 4.5: Le mécanisme #noqa.

Traduire avec sphinx-intl

Guide rapide

sphinx-intl est un outil pratique pour travailler avec le flux de traduction de Sphinx. Cette section décrit une manière facile de traduire avec sphinx-intl.

  1. Installer sphinx-intl :

    $ pip install sphinx-intl

  2. Ajouter la configuration à conf.py :

    locale_dirs = ['locale/']   # path is example but recommended.
gettext_compact = False     # optional.

    Cette étude de cas présume que la valeur _build est affectée à la variable d’environnement BUILDDIR, locale/ au paramètre locale_dirs, et False à gettext_compact (the Sphinx document is already configured as such).

  3. Extraire les messages traduisibles dans des fichiers POT :

    $ make gettext

    Les fichiers POT générés seront placés dans le répertoire _build/gettext.

  4. Générer les fichiers PO :

    Nous utiliserons les fichiers POT générés à l’étape précédente.

    $ sphinx-intl update -p _build/gettext -l de -l ja

    Une fois terminé, les fichiers PO générés seront placés dans les répertoires suivants :

    • ./locale/de/LC_MESSAGES/

    • ./locale/ja/LC_MESSAGES/

  5. Traduire les fichiers PO :

    Comme indiqué ci-dessus, ceux-ci se trouvent dans les répertoires ./locale/<lang>/LC_MESSAGES. Un exemple d’un tel fichier, venant de Sphinx, builders.po, est donné ci-dessous :

    # a5600c3d2e3d48fc8c261ea0284db79b
#: ../../builders.rst:4
msgid "Available builders"
msgstr "<FILL HERE BY TARGET LANGUAGE>"

    Autre cas, msgid est un segment de texte multiligne comportant de la syntaxe reStructuredText :

    # 302558364e1d41c69b3277277e34b184
#: ../../builders.rst:9
msgid ""
"These are the built-in Sphinx builders. More builders can be added by "
":ref:`extensions <extensions>`."
msgstr ""
"FILL HERE BY TARGET LANGUAGE FILL HERE BY TARGET LANGUAGE FILL HERE "
"BY TARGET LANGUAGE :ref:`EXTENSIONS <extensions>` FILL HERE."

    Veuillez prendre gare à ne pas endommager la syntaxe reST. La plupart des éditeurs de fichiers PO vous y aideront.

  6. Générer les documents traduits

    Un paramètre confval:language est nécessaire dans le fichier conf.py, ou vous pouvez aussi préciser ce paramètre dans la ligne de commande.

    Pour BSD/GNU make, exécutez :

    $ make -e SPHINXOPTS="-D language='de'" html

    Dans l’Invite de commande Windows cmd.exe, exécuter :

    > set SPHINXOPTS=-D language=de
> .\make.bat html

    Dans Windows PowerShell, exécuter :

    > Set-Item env:SPHINXOPTS "-D language=de"
> .\make.bat html

Félicitations ! La documentation traduite est obtenue dans le répertoire _build/html`.

Added in version 1.3: Le programme sphinx-build invoqué via la commande make compilera les fichiers PO en fichiers MO.

Si vous utilisez la version 1.2.x ou antérieure, veuillez exécuter la commande sphinx-intl build avant d’invoquer la commande make.

Traduction

Mise-à-jour des fichiers PO avec de nouveaux fichiers POT

Si un document est actualisé, il est nécessaire de générer des fichiers POT mis-à-jour et d’appliquer les différences aux fichiers PO traduits. Afin d’appliquer les mises à jour depuis un fichier POT vers un fichier PO, utilisez la commande sphinx-intl update.

$ sphinx-intl update -p _build/gettext

Utilisation du service Transifex pour la traduction en équipe

Transifex est un des nombreux services permettant la traduction collaborative via une interface Web. Il offre également un excellent client en ligne de commande redant facile la récupération et l’envoie des traductions.

  1. Installation du transifex-client.

    Vous avez besoin de la commande tx pour téléverser vos resources (fichiers POT).

    $ pip install transifex-client

    Voir aussi

    Documentation du client Transifex

  2. Créez votre compte Transifex ainsi qu’un nouveau projet pour votre document.

    À ce jour, Transifex ne permet pas de gérer plusieurs versions de document dans un projet de traduction. Il est donc préférable d’inclure un numéro de version dans votre nom de projet.

    Par exemple :

    ID projet:

    sphinx-document-test_1_0

    URL projet:

    https://www.transifex.com/projects/p/sphinx-document-test_1_0/

  3. Création du fichier de configuration pour la commande tx.

    Cette opération créera un fichier .tx/config dans le dossier courant, ainsi qu’un fichier ~/.transifexrc comportant les informations d’authentification.

    $ tx init
Creating .tx folder...
Transifex instance [https://www.transifex.com]:
...
Please enter your transifex username: <transifex-username>
Password: <transifex-password>
...
Done.

  4. Téléversement des fichiers POT vers le service Transifex.

    Référencer les fichiers POT dans le fichier .tx/config :

    $ cd /your/document/root
$ sphinx-intl update-txconfig-resources --pot-dir _build/locale \
  --transifex-project-name sphinx-document-test_1_0

    puis téléverser les fichiers POT :

    $ tx push -s
Pushing translations for resource sphinx-document-test_1_0.builders:
Pushing source file (locale/pot/builders.pot)
Resource does not exist.  Creating...
...
Done.

  5. Transfert des traductions vers Transifex.

  6. Récupération des fichiers PO traduits et génération des traductions HTML.

    Téléchargez les catalogues traduits et construisez les fichiers MO. Par exemple, pour générer les fichiers MO pour l’Allemand (de) :

    $ cd /your/document/root
$ tx pull -l de
Pulling translations for resource sphinx-document-test_1_0.builders (...)
 -> de: locale/de/LC_MESSAGES/builders.po
...
Done.

    Exécutez la commande make html (pour make sous BSD/GNU) :

    $ make -e SPHINXOPTS="-D language='de'" html

C’est tout !

Astuce

Traduction en local et sur Transifex

Si vous souhaitez pousser tous les fichiers PO de langues, vous le pouvez avec la commande tx push -t. Prenez garde ! Cette opération écrase les traductions dans Transifex.

En d’autres termes, si les fichiers PO ont été édités simultanément en local et via le service, cela nécessiterait beaucoup de temps et d’effort pour les réconcilier.

Utilisation du service Weblate pour la traduction en équipe

Pour en savoir plus, consultez la documentation de Weblate.

Contribution à la traduction de Sphinx

La manière recommandée aux nouveaux contributeurs pour traduire Sphinx est de rejoindre l’équipe de traduction sur Transifex.

Il y a une sphinx translation page pour la documentation de Sphinx (branche master).

  1. Connectez-vous au service Transifex.

  2. Rendez-vous sur la sphinx translation page.

  3. Cliquez sur Demander une langue et remplissez le formulaire.

  4. Attendez l’approbation par les mainteneurs de la traduction de Sphinx.

  5. (Après approbation) Traduisez Sphinx sur Transifex.

Voir les détails ici : https://docs.transifex.com/getting-started-1/translators

Translation progress and statistics

Added in version 7.1.0.

During the rendering process, Sphinx marks each translatable node with a translated attribute, indicating if a translation was found for the text in that node.

The translation_progress_classes configuration value can be used to add a class to each element, depending on the value of the translated attribute.

The |translation progress| substitution can be used to display the percentage of nodes that have been translated on a per-document basis.

Notes de bas de page