python-docs-fr/CONTRIBUTING.rst

Guide de contribution à la documention via GitHub.

Prérequis

• un compte Github ;
• un client git Linux ou Windows ;
• un éditeur de fichier .po (comme Poedit).

Instructions

Pour commencer vous aurez besoin de forker le dépôt des sources python-docs-fr en cliquant sur son bouton Fork. Ceci crée une copie du projet sur votre compte Github : un endroit où vous avez le droit de faire des modifications.

Étape par étape :

# Clonez votre fork Github avec `git` en utilisant ssh
git clone git@github.com:VOTRE_NOM_DE_COMPTE_GITHUB/python-docs-fr.git

# ou bien via HTTPS
git clone https://github.com/VOTRE_NOM_DE_COMPTE_GITHUB/python-docs-fr.git

# Allez dans le répertoire cloné
cd python-docs-fr/

# Ajoutez le dépôt officiel (nommé upstream),
# ceci permet à *git* de savoir quoi et où est *upstream*
git remote add upstream https://github.com/python/python-docs-fr.git

Ensuite, vous devez trouver un fichier sur lequel travailler (pour vous aiguiller, vous pouvez vous rendre à Que traduire ? et lire les explications concernant potodo qui vous permettra de voir ce qui a déjà été traduit et ce qui ne l'a pas été).

Une fois que vous avez choisi un fichier sur lequel travailler, veuillez ouvrir un ticket sur Github en indiquant dans le titre Je travaille sur DOSSIER/FICHIER.po (par exemple « Je travaille sur library/sys.po »). Ceci permet à potodo de détecter via l'API Github les fichiers .po réservés dans les tickets et les pull requests.

Équipez-vous aussi de quelques outils pour vous aider dans votre traduction (voir Outils utiles pour la traduction).

Vous êtes maintenant prêt. Chaque fois que vous commencerez un nouveau fichier, suivez cette procédure :

Pour travailler, nous aurons besoin d'une branche, basée sur une version à jour (fraîchement récupérée) de la branche upstream/3.8. On met donc à jour notre version locale.

git fetch upstream

On créé ensuite une branche. Il est pratique de nommer la branche en fonction du fichier sur lequel on travaille. Par exemple, si vous travaillez sur « library/sys.po », vous pouvez nommer votre branche « library-sys ». Cette nouvelle branche nommée « library-sys » est basée sur « upstream/3.8 ».

git checkout -b library-sys upstream/3.8

Vous pouvez maintenant travailler sur le fichier. Si vous utilisez Poedit, n'oubliez pas de configurer votre nom et votre adresse de courriel (Édition → Préférences → Général). Vérifiez aussi qu'il est configuré pour passer à la ligne à 79 caractères (Édition → Préférences → Avancé → Passer à la ligne à 79).

Ici, remplacez « library/sys.po » par le fichier que vous avez choisi précédemment.

poedit library/sys.po

Ou lancez simplement Poedit puis « Fichier » → « Ouvrir ».

Si vous n'utilisez pas Poedit, vous pouvez utiliser powrap (voir la section outils) qui reformate correctement le fichier que avez vous avez modifié. Exécutez powrap -m (reformater tous les fichiers modifiés) ou powrap library/sys.po (un fichier en particulier) :

powrap -m

Pour l'orthographe, une liste blanche de certains termes techniques ou de noms propres, comme « Guido », « C99 » ou « sérialisable », est stockée dans le fichier « dict » à la racine du projet. Vous pouvez bien sûr y ajouter une entrée si nécessaire. La commande suivante lance les vérifications nécessaires.

make verifs

C'est le moment de git add et git commit. git add place nos modifications dans l'index de Git en attendant d'être propagées dans le dépôt local.

git add library/sys.po

Puis on propage les modifications dans le dépôt local avec un commit.

git commit -m "Traduction de library/sys.po"  # Ou un autre message plus inspiré :)

Poussez ensuite vos modifications sur votre fork Github. Le -u n'est utile qu'une fois pour que votre client git se souvienne que cette branche est liée à votre fork Github (et donc que vos futurs git pull et git push sachent quoi tirer)

git push -u origin

La commande précédente vous affiche un lien pour ouvrir une pull request sur Github. Si vous l'avez manqué, allez simplement sur https://github.com/python/python-docs-fr/pulls et un joli bouton « Compare & pull request » devrait apparaître au bout de quelques secondes vous indiquant que vous pouvez demander une pull request.

Mettez dans le commentaire de la pull request le texte suivant : « Closes #XXXX » où XXXX est le numéro du ticket GitHub créé pour réserver le fichier traduit.

À partir de là, quelqu'un passera en revue vos modifications, et vous fera des suggestions et corrections. Pour les prendre en compte, retournez sur votre branche contenant du fichier concerné (au cas où vous auriez commencé quelque chose d'autre sur une autre branche) :

git checkout library/sys
git pull  # pour rapatrier les modifications que vous auriez acceptées
          # sur l'interface web.

# Réglez les problèmes, puis commitez à nouveau :
git commit -a -m "prise en compte des remarques"
git push

Vous avez peut-être remarqué que cela ressemble à un triangle, avec un segment manquant :

• vous récupérez depuis upstream (le dépôt commun public sur Github) ;
• vous poussez sur origin (votre clone sur Github).

C'est le travail de quelqu'un d'autre d'ajouter le dernier segment, de votre origin au upstream public, pour « boucler la boucle ». C'est le rôle des personnes qui fusionnent les pull requests après les avoir relues.

Vous avez peut-être aussi remarqué que vous n'avez jamais commité sur une branche de version (3.7, 3.8, etc.), seulement récupéré les modifications à partir d'elles.

Toutes les traductions sont faites sur la dernière version. Nous ne traduisons jamais sur une version plus ancienne. Par exemple, si la dernière version de python est Python 3.8, nous ne voulons pas traduire directement sur la version python 3.5. Si nécessaire, les traductions seraient rétroportées sur les versions les plus anciennes par l'équipe de documentation.

Que traduire ?

Vous pouvez utiliser potodo, un outil fait pour trouver des fichiers po à traduire. Une fois installé, utilisez la commande potodo dans votre clone local.

Vous pouvez choisir n'importe quel fichier non réservé dans la liste renvoyée par la commande à l'exception des fichiers de :

• c-api/ car c'est une partie très technique ;
• whatsnew/ car les anciennes versions de Python sont pour la plupart obsolètes et leurs journaux de modifications ne sont pas les pages les plus consultées ;
• distutils/ et install/ car ces pages seront bientôt obsolètes.

Vous pouvez commencer par des tâches faciles comme réviser les entrées fuzzy pour aider à garder la documentation à jour (trouvez les entrées fuzzy l'aide de make fuzzy).

Vous pouvez également relire des entrées déjà traduites pour vous faire une idée, et passer ensuite à la traduction de celles qui ne le sont pas encore. Vous pouvez les trouver à l'aide de make todo…

Vous pouvez aussi « traduire » des liens hypertextes (par exemple s'il s'agit d'un lien vers un article de Wikipédia qui possède une traduction). Modifiez le lien et sa description dans ce cas. Si aucune traduction de la cible n'existe, ne traduisez pas le titre.

Dans les fichiers, ne traduisez pas le contenu des balises telles que :ref :... et :term :....

Si vous devez absolument utiliser un mot anglais, mettez-le en italique (entouré par des astérisques).

Pour les caractères spéciaux, référez-vous à la section Caractères spéciaux.

Conseils

Utilisation du futur

Dans la description du comportement de Python (au sens large, c'est-à-dire l'interpréteur lui-même mais aussi toutes les bibliothèques), la version originale utilise souvent le futur : « if you do this, il will produce that… ». En français, l'utilisation du présent convient tout à fait et le présent est souvent plus facile à lire : « si vous faites ceci, il se produit cela… ». On ne conserve le futur que si la seconde proposition se situe réellement dans le futur (par exemple, on peut penser qu'un processus de compilation n'est pas immédiat) ou pour des raisons de concordance des temps.

Utilisation du conditionnel

La version originale est très polie envers le lecteur ; elle lui intime rarement des obligations, préférant employer « you should ». Cependant, en français, il est d'usage d'être plus direct pour être correctement compris : « vous devez ». Vous devriez est en effet généralement compris comme quelque chose dont l'on peut de temps en temps se passer, alors que c'est très rarement le cas pour les « you should » de cette documentation. De la même manière, « can » est souvent mieux traduit sans introduire de notion de possibilité, en particulier quand la phrase est à la voix passive ; la phrase « these objects can be accessed by… » se traduit mieux par « on accède à ces objets en… ».

Utilisation du masculin

Dans un souci de lisibilité et en accord avec la préconisation de l'Académie française, nous utilisons le masculin pour indiquer un genre neutre. Par exemple : l'utilisateur ou le lecteur.

Style

Une bonne traduction est une traduction qui transcrit fidèlement l'idée originelle en français, sans rien ajouter ni enlever au fond, tout en restant claire, concise et agréable à lire. Les traductions mot-à-mot sont à proscrire et il est permis — même conseillé — d'intervertir des propositions ou de réarranger des phrases de la documentation anglaise, si le rythme l'exige. Il faut aussi chercher des équivalents français aux termes techniques et aux idiotismes rencontrés, et prendre garde aux anglicismes.

Glossaire

Afin d'assurer la cohérence de la traduction, voici quelques propositions et rappels pour les termes fréquents à traduire.

Pour trouver facilement comment un terme est déjà traduit dans la documentation, vous pouvez utiliser pogrep.

Terme	Traduction proposée
-like	-compatible
abstract data type	type abstrait
argument	argument (à ne pas confondre avec paramètre)
backslash	antislash, backslash
backtrace	trace d'appels, trace de pile
backport	rétroporter
bound	lier
bug	bogue
built-in	natif
bytecode	code intermédiaire
callback	fonction de rappel
call stack	pile d'appels
caught (exception)	interceptée
debugging	débogage
deep copy	copie récursive (préféré), ou copie profonde
double quote	guillemet
deprecated	obsolète
e.g.	p. ex. (on n'utilise pas l'anglicisme « e.g. », lui-même issu du latin exempli gratia). On sépare les deux mots par une espace insécable pour éviter les retours à la ligne malheureux.
et al.	et autres, à accorder suivant le contexte
export	exportation
expression	expression
garbage collector	ramasse-miettes
getter	accesseur
i.e.	c.-à-d. (on n'utilise pas l'anglicisme « i.e. », lui-même issu du latin id est)
identifier	identifiant
immutable	immuable
import	importation
index	indice (en particulier quand on parle de chaînes de caractères)
installer	installateur
interpreter	interpréteur
library	bibliothèque
list comprehension	liste en compréhension (liste en intension est valide, mais nous ne l'utilisons pas)
little-endian, big-endian	petit-boutiste, gros-boutiste
mixin type	type de mélange
mutable	muable
namespace	espace de nommage (sauf pour le XML où c'est espace de noms)
parameter	paramètre
pickle (v.)	sérialiser
prompt	invite
raise	lever
regular expression	expression rationnelle, expression régulière
return	renvoie, donne (on évite « retourne » qui pourrait porter à confusion)
setter	mutateur
simple quote	guillemet simple
socket	connecteur ou interface de connexion
statement	instruction
subprocess	sous-processus
support	prendre en charge, implémenter (« supporter » n'a pas le même sens en français)
specify	définir, préciser (plutôt que « spécifier »)
typically	normalement, habituellement, comme d'habitude (plutôt que « typiquement »)
thread	fil d'exécution
traceback	trace d'appels, trace de pile
tuple	n-uplet
underscore	tiret bas, underscore
whitespace	caractère d'espacement

Caractères spéciaux

La touche de composition

Cette touche, absente par défault des claviers, permet de saisir des caractères spéciaux en combinant les caractères déjà présents sur le clavier. C'est à l'utilisateur de définir la touche de composition.

Avec une touche de composition, vous pouvez utiliser les compositions suivantes :

• Compose < < donne «
• Compose > > donne »
• Compose SPACE SPACE donne une espace insécable
• Compose . . . donne …

Comme vous l'avez noté, presque toutes les compositions sont intuitives, vous pouvez donc en essayer d'autres et elles devraient tout simplement fonctionner :

• Compose C = donne €
• Compose 1 2 donne ½
• Compose ' E donne É
• etc.

Comment définir la touche de composition ?

Cela dépend de votre système d'exploitation et de votre clavier.

=> Sous Linux, Unix et *BSD (tel OpenBSD), vous pouvez la configurer à l'aide de l'outil graphique de configuration de votre clavier ou via dpkg-reconfigure keyboard-configuration (pour Ubuntu ou Debian et distributions assimilées).

À minima, vous pouvez configurer votre fichier '~/.Xmodmap' pour ajouter l'équivalent de :

# key Compose
keycode 115 = Multi_key

Utilisez xev pour connaitre la bonne correspondance de la touche que vous voulez assigner !

Ensuite, dans votre fichier '~/.xsession', ajoutez :

# Gestion des touches clavier
xmodmap $HOME/.Xmodmap

Sous X, avec un bureau graphique, tel que Gnome, ou Xfce, il faut aller modifier dans les « Paramètres » → « Clavier » → « Disposition » → « Touche composée ». Pour finir, redémarrez votre session.

=> Sous Windows, vous pouvez utiliser wincompose.

Le cas de « --- », « -- », « ... »

La version anglaise utilise les smartquotes, qui fonctionnent en anglais, mais causent des problèmes dans d'autres langues. Nous les avons donc désactivées (voir #303) dans la version française.

Les smartquotes sont normalement responsables de la transformation de -- en en-dash (—), de --- en em-dash (—), et de ... en ellipses ….

=> Si vous voyez : | « -- » ou « --- » : faites Compose - - - | « ... » : faites Compose . . .

Le cas de « "…" »

Les guillemets français « et » ne sont pas identiques aux guillemets anglais ". Cependant, Python utilise les guillemets anglais comme délimiteurs de chaîne de caractères. Il convient donc de traduire les guillemets mais pas les délimiteurs de chaîne.

=> Si vous voyez : | « "…" » : faites Compose < < ou Compose > >

Le cas de « :: »

Du point de vue du langage reStructuredText (ou rst) utilisé dans la documentation nous voyons soit « bla bla:: », soit « bla bla. :: ».
:: collé à la fin d'un mot signifie « affiche : et introduit un bloc de code », mais un :: après une espace signifie « introduit juste un bloc de code ».

En français, nous mettons une espace insécable devant nos deux-points, comme : « Et voilà : ».

=> Traduisez mot deux-points deux-points par mot espace-insécable deux-points deux-points.

Pour saisir une espace insécable faites Compose SPACE SPACE

Le cas des doubles-espaces

La documentation originale comporte beaucoup de doubles-espaces. Cela se fait en anglais, mais pas en français. De toute manière, ils passent ensuite à une moulinette et le rendu des espaces est délégué au HTML et au PDF, qui n'en tiennent pas compte. Nous avons décidé de ne rien changer pour les doubles-espaces coté traduction : nous ne les retirons pas et ce n'est pas grave si des traducteurs en retirent par accident.

Les énumérations

Chaque paragraphe d'une énumération introduite par un deux-point doit se terminer par un point-virgule (bien entendu précédé d'une espace insécable) quelle que soit sa ponctuation interne. Seul le dernier paragraphe de l'énumération s'achève par un point ou, si la phrase continue après l'énumération, une virgule. Si l'un des paragraphes est lui-même une énumération, chacun des sous-paragraphes se termine par une virgule et le dernier par un point-virgule.

Par exemple :

• le premier paragraphe de l'énumération ;
• le deuxième paragraphe, lui-aussi une énumération :
  • premier sous-paragraphe,
  • second sous-paragraphe ;
• le dernier paragraphe.

Malheureusement Poedit n'aime pas les différences de ponctuation finales entre un paragraphe et sa traduction ; il faut passer outre ses avertissements. Vous pouvez aussi rajouter un commentaire dans le fichier .po pour avertir les traducteurs suivants et éviter qu'ils ne « corrigent » par erreur ces avertissements.

Outils utiles pour la traduction

Potodo

Permet de d'identifier les parties de la documention qu'il reste à traduire.
Installez-le à l'aide de pip (pip install potodo) dans un environnement python3.6 ou plus.
Lien vers le dépôt

Pogrep

Permet de rechercher dans la documentation des termes. Utile si on a un doute sur comment traduire un terme ou chercher la traduction d'un terme dans d'autres fichiers.
Installez-le à l'aide de pip (pip install pogrep).
Lien vers le dépôt

Padpo (beta)

Analyseur de code qui vérifie la grammaire et l'orthographe et la syntaxe du fichier .po.
Installez-le à l'aide de pip (pip install padpo) dans un environnement python3.7 ou plus.
Lien vers le dépôt

Powrap

Formateur de fichier .po.
Installez-le à l'aide de pip (pip install powrap).
Lien vers le dépôt

Ressources de traduction

• les canaux IRC sur freenode :
  • #python-docs-fr — communauté python autour de la documentation française,
  • #python-fr — communauté python francophone,
  • #python-doc — communauté python autour de la documentation anglophone ;
• les listes de diffusion relatives à la documentation (courriel) :
  • de l'AFPy,
  • de cpython ;
• des glossaires et dictionnaires :
  • le glossaire de la documentation Python, car il est déjà traduit,
  • les glossaires et dictionnaires de traduc.org, en particulier le grand dictionnaire terminologique de l'Office québécois de la langue française,
  • Wikipédia. En consultant un article sur la version anglaise, puis en basculant sur la version francaise pour voir comment le sujet de l'article est traduit ;
• le guide stylistique pour le français de localisation des produits Sun donne beaucoup de conseils pour éviter une traduction trop mot à mot ;
• Petites leçons de typographie, résumé succint de typographie, utile pour apprendre le bon usage des majuscules, des espaces, etc.

L'utilisation de traducteurs automatiques comme DeepL https://www.deepl.com/ ou semi-automatiques comme reverso https://context.reverso.net/traduction/anglais-francais/ est proscrite. Les traductions générées sont très souvent à retravailler, ils ignorent les règles énoncées sur cette page et génèrent une documentation au style très « lourd ».

Simplification des diffs git

Les diffs git sont souvent encombrés de changements inutiles de numéros de ligne, comme :

-#: ../Doc/library/signal.rst:406
+#: ../Doc/library/signal.rst:408

Pour dire à git que ce ne sont pas des informations utiles, vous pouvez faire ce qui suit après vous être assuré que ~/.local/bin/ se trouve dans votre PATH.

cat <<EOF > ~/.local/bin/podiff
#!/bin/sh
grep -v '^#:' "\$1"
EOF

chmod a+x ~/.local/bin/podiff

git config diff.podiff.textconv podiff

Pas d'inquiétude, cela ne change la façon dont Git voit les changements que sur les fichiers de la traduction, sans incidence sur les autres.

Maintenance

Toutes ces commandes doivent être exécutées à partir de la racine d'un clone de python-docs-fr et certaines s'attendent à trouver un clone de CPython à jour à proximité, comme :

~/
├── python-docs-fr/
└── cpython/

Pour cloner CPython, vous pouvez utiliser :

git clone --depth 1 --no-single-branch https://github.com/python/cpython.git

Ceci évite de télécharger tout l'historique (inutile pour générer la documentation) mais récupère néanmoins toutes les branches.

Fusionner les fichiers pot de CPython

make merge

Trouver les chaînes de caractères fuzzy

make fuzzy

Lancer un build en local

make

Synchroniser la traduction avec Transifex

Vous aurez besoin de transifex-client et powrap, depuis PyPI.

Vous devrez configurer tx via tx init si ce n'est déjà fait.

Propagez d'abord les traductions connues localement :

pomerge --no-overwrite --from-files **/*.po --to-files **/*.po
powrap --modified
git commit -m "Propagating known translations."

Ensuite récupérez les changements depuis Transifex :

tx pull -f --parallel
pomerge --from-files **/*.po
git checkout -- .
pomerge --no-overwrite --mark-as-fuzzy --to-files **/*.po
powrap --modified
git add -p
git commit -m "tx pull"
tx push -t -f --no-interactive --parallel