Internationalisation

Ajouté dans la 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 for 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.

An example: you have a document usage.rst in your Sphinx project. The gettext builder will put its messages into usage.pot. Imagine you have Spanish translations [2] stored in usage.po — for your builds to be translated you need to follow these instructions:

  • Compile your message catalog to a locale directory, say locale, so it ends up in ./locale/es/LC_MESSAGES/usage.mo in your source directory (where es is the language code for Spanish.)

    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.)

Ajouté dans la 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. Add configurations to 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

    The generated pot files will be placed in the _build/gettext directory. If you want to customize the output beyond what can be done via the Options for internationalisation, the default pot file template can be replaced by a custom message.pot.jinja file placed in any directory listed in templates_path.

  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 :

    As noted above, these are located in the ./locale/<lang>/LC_MESSAGES directory. An example of one such file, from Sphinx, builders.po, is given below.

    # 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."

    Please be careful not to break reStructuredText notation. Most po-editors will help you with that.

  6. Générer les documents traduits

    You need a language parameter in conf.py or you may also specify the parameter on the command line.

    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 :

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

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

Ajouté dans la 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 is one of several services that allow collaborative translation via a web interface. It has a nifty Go-based command line client that makes it easy to fetch and push translations.

  1. Install the Transifex CLI tool.

    You need the tx command line tool for uploading resources (pot files). The official installation process place the tx binary file in the current directory along with a README and a LICENSE file, and adds the current directory to $PATH.

    $ curl -o- https://raw.githubusercontent.com/transifex/cli/master/install.sh | bash

    Voir aussi

    Documentation du client Transifex

  2. Create your Transifex account and create a new project and an organization for your 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 :

    Organization ID:

    sphinx-document

    ID projet:

    sphinx-document-test_1_0

    URL projet:

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

  3. Create an API token to be used in the command-line.

    Go to your Transifex API token page and generate a token. Copy the generated token now, as you will not be able to see it again later.

  4. Set your Transifex API token in the user configuration file $HOME/.transifexrc.

    [https://app.transifex.com]
rest_hostname = https://rest.api.transifex.com
token         = paste_your_api_token_here

  5. Alternatively, you can store your Transifex API token as the environment variable TX_TOKEN, which is recognized and used by tx.

    $ export TX_TOKEN=paste_your_api_token_here

  6. Create the project’s config file for tx command.

    This process will create .tx/config in the current directory.

    $ cd /your/document/root
$ tx init

Successful creation of '.tx/config' file

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

    Register pot files to .tx/config file using sphinx-intl update-txconfig-resources, adjusting --pot-dir value to your project’s pot files” directory:

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

    You can use the SPHINXINTL_TRANSIFEX_ORGANIZATION_NAME and SPHINXINTL_TRANSIFEX_PROJECT_NAME environment variables instead of the respective command line arguments.

    Voir aussi

    sphinx-intl update-txconfig-resources documentation

    puis téléverser les fichiers POT :

    $ tx push -s
# Getting info about resources

sphinx-document-test_1_0.builders - Getting info
sphinx-document-test_1_0.builders - Done

# Pushing source files

sphinx-document-test_1_0.builders - Uploading file
sphinx-document-test_1_0.builders - Done

  8. Transfert des traductions vers Transifex.

  9. 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
# Getting info about resources

sphinx-document-test_1_0.builders - Getting info
sphinx-document-test_1_0.builders - Done

# Pulling files

sphinx-document-test_1_0.builders [de] - Pulling file
sphinx-document-test_1_0.builders [de] - Creating download job
sphinx-document-test_1_0.builders [de] - Done

    Invoke make html (for BSD/GNU make) passing the language code:

    $ 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.

Detail is here: https://help.transifex.com/en/articles/6248698-getting-started-as-a-translator

Translation progress and statistics

Ajouté dans la 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