Pour participer à la traduction, vous aurez besoin d'installer :

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

De plus, il peut être utile de s'équiper d'utilitaires pour faciliter la manipulation des fichiers .po et la traduction.

Poutils est un paquet PyPI qui regroupe un certain nombre d'outils liés à la traduction :

python3 -m pip install poutils

Si ce n'est pas déjà fait, créez un compte sur la forge de l'AFPy (souvent nommée Forgejo plus loin, ça se prononce /forˈd͡ʒe.jo/).

Commençons par créer une copie du dépôt python-docs-fr sur Forgejo, pour cela rendez-vous sur le dépôt python-docs-fr et cliquez sur le bouton « Fourche » (Fork) en haut à droite.

De votre point de vue il existe maintenant deux versions de python-docs-fr :

• https://git.afpy.org/AFPy/python-docs-fr le dépôt commun, que vous n'avez pas le droit de modifier.
• https://git.afpy.org/VOTRE_LOGIN/python-docs-fr votre dépôt, que vous avez le droit de modifier.

Une clé SSH permet d’effectuer des git pull et des git push en utilisant SSH : sans avoir à saisir son identifiant et son mot de passe HTTP à chaque fois : c'est du confort.

Vous pouvez sauter cette section pour le moment : vous pourrez y revenir plus tard.

Si vous n'avez pas encore de clé SSH, créez une paire de clés SSH en utilisant la commande ssh-keygen, consultez le guide de GitLab si vous souhaitez en savoir plus.

Vous obtiendrez deux fichiers : typiquement id_ed25519 et id_ed25519.pub (ou id_rsa et id_rsa.pub). Le premier est votre clé privée, elle doit rester secrète. La seconde se terminant par .pub est votre clé publique, comme son nom l'indique vous pouvez la partager publiquement.

Pour ajouter votre clé publique sur Forgejo, allez dans le menu de votre compte en haut à droite et cliquez sur « Configuration », puis d'aller dans l'onglet « Clés SSH / GPG », et copiez votre clé SSH publique.

Cette clé publique sur le serveur Forgejo lui permet de s'assurer de votre identité (en générant des défis que seul le détenteur de la clé privée peut résoudre).

Enfin, faites une copie locale du dépôt sur votre ordinateur afin de pouvoir éditer les fichiers, avec ces commandes :

# Si vous utilisez une clé SSH :
git clone git@git.afpy.org:VOTRE_NOM_DE_COMPTE_FORGEJO/python-docs-fr.git

# Sinon :
git clone https://git.afpy.org/VOTRE_NOM_DE_COMPTE_FORGEJO/python-docs-fr.git

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

# Profitez-en pour indiquer à git qu'il existe aussi le dépôt
# commun (qu'on nomme upstream) :
git remote add upstream https://git.afpy.org/AFPy/python-docs-fr.git

À partir de maintenant de votre point de vue il existe trois copies des fichiers :

• Une sur votre ordinateur, pour la modifier aisément.
• Une appartenant à l'AFPy sur Forgejo, que git appelle upstream.
• Une vous appartenant sur Forgejo, que git appelle origin.

Il est vivement conseillé de ne pas travailler sur fichiers des répertoires c-api/, whatsnew/, distutils/ et install/ :

• 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/, install/, et quelques autres parties qui seront bientôt obsolètes. De manière générale, il n'est pas utile de traduire un module que sa documentation mentionne comme obsolète.

Si vous avez besoin d'aide pour choisir un fichier à traduire, vous pouvez utiliser la commande make todo (dans le dossier python-docs-fr).

La liste renvoyée contient tous les fichiers qui ne sont pas encore complètement traduits. Vous pouvez choisir n'importe quel fichier non réservé dans la liste renvoyée (notez que ceux mentionnés plus haut sont automatiquement exclus).

Vous pouvez commencer par des tâches faciles comme réviser les entrées fuzzy pour aider à garder la documentation à jour (trouvez-les à l'aide de make fuzzy). Une entrée fuzzy correspond à une entrée déjà traduite mais dont la source en anglais a été modifiée depuis (correction orthographique, changement d'un terme, ajout ou suppression d'une phrase…). Elles sont généralement plus « faciles » à traduire.

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.

Nous vous conseillons de choisir, si possible, un fichier traitant d'un sujet que vous maîtrisez, cela vous aidera grandement à produire une traduction de bonne qualité.

Si c'est votre première contribution, commencez par une toute petite traduction, de quelques paragraphes maximum, pour vous familiariser. Il n'est pas nécessaire de terminer un fichier lorsqu'on le commence, vous pouvez donc prendre n'importe quel fichier, mais ne traduire que quelques paragraphes.

Chaque fois que vous commencez un nouveau fichier, suivez cette procédure.

Pour éviter que quelqu'un d'autre fasse le travail en double.

Une fois que vous avez choisi un fichier sur lequel travailler vous pouvez nous le signaler par différents moyens :

• Soit en ouvrant un ticket sur Forgejo 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 Forgejo les fichiers .po réservés dans les tickets et les demandes d'ajout.

Chaque fois que vous commencez un nouveau fichier, suivez cette procédure.

git représente une session de travail sous forme d'une branche (en traduisant vous allez faire diverger les fichiers qui sont sur votre ordinateur par rapport aux fichiers publics, comme une branche qui se sépare de son tronc).

Pour éviter de travailler sur des fichiers modifiés par d'autres, assurez-vous toujours que la base de votre future branche est « un tronc » à jour. Pour ceci utilisez :

git fetch upstream

Créez ensuite une branche git, dont la base est « upstream/3.14 », Il est pratique de nommer cette 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 ».

git switch -c library-sys upstream/3.14

Chaque branche ayant un nom, avec un peu de pratique vous pourrez bientôt avoir plusieurs sessions de travail en parallèle (avoir plusieurs branches, travailler un peu sur l'une, puis un peu sur l'autre, puis revenir à la première, …) !

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

Configurez votre nom et votre adresse de courriel (Édition →

Préférences → Général).

Vérifiez également que poedit est configuré pour passer à la ligne à 79 caractères (Édition → Préférences → Avancé → Passer à la ligne à 79).

Il n'est pas obligatoire de terminer un fichier, ni de le travailler de haut en bas, chacun traduit ce qu'il souhaite. Cependant évitons de changer plus de 200 lignes par pull request (pour le confort des relecteurs). Faire plusieurs pull requests est bien sûr autorisé !

La vocation de ce projet de traduction n'est pas d'y injecter la sortie brute d'un outil LLM. Si vous utilisez ce type d'outil, veillez à faire une relecture attentive afin que ce que vous soumettez soit agréable à lire et sémantiquement correct.

Après avoir modifié les fichiers, vérifiez que vous respectez les conventions du projet. Pour vous y aider, la commande :

make check

vérifie la longueur des lignes et l'orthographe (mais pas la grammaire, pour cela utilisez padpo (beta)). En cas de doute, un glossaire répertorie déjà les traductions retenues pour certains termes techniques ou faux amis en anglais.

Si make check trouve des problèmes de longueurs de ligne, vérifiez votre configuration poedit (Édition → Préférences → Avancé → Passer à la ligne à 79) ou utilisez make wrap.

Une fois la traduction finie, vous pouvez générer la documentation pour les relire. Si la commande précédente s'est exécutée sans erreur, la génération ne devrait pas échouer.

make htmlview

Attention: le port TCP/8000 ne peut être changé, il convient d'arrêter tout service qui écouterait sur celui-ci.

Vous pouvez recommencer les étapes de cette section autant de fois que nécessaire.

Poedit donne beaucoup d'avertissements, par exemple pour vous informer que « la traduction devrait commencer par une majuscule » car c'est le cas pour la source. Ces avertissements ne sont pas tous fondés. En cas de doute, affichez et relisez la page HTML produite avec make htmlview.

Une fois que le make check ne lève pas d'erreur et que vous êtes certains de bien respecter les Conventions de traduction, vient le moment d'envoyer votre travail sur votre dépôt Forgejo.

• git add permet d’indiquer à git quels fichiers vous voulez ajouter au futur commit.

git add library/sys.po

• git commit permet de valider les modifications effectuées.

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

Publiez ensuite vos modifications sur votre dépôt Forgejo avec git push.

git push origin

La commande précédente vous affiche un lien pour ouvrir une demande d'ajout sur Forgejo. Si vous l'avez manqué, allez simplement sur https://git.afpy.org/AFPy/python-docs-fr/pulls et cliquez sur le bouton « Nouvelle demande d'ajout ».

Mettez dans le commentaire de la demande d'ajout le texte suivant : « Closes #XXXX » où XXXX est le numéro du ticket Forgejo créé pour réserver le fichier traduit. Cela permet à Forgejo de lier la demande d'ajout au ticket de réservation.

Pour le moment vous savez :

• récupérez des modifications depuis upstream (le dépôt commun sur Forgejo) ;
• poussez des modifications vers origin (votre dépôt sur Forgejo).

Mais vous ne pouvez pas faire la dernière étape : copier les modifications depuis votre dépôt Forgejo vers le dépôt commun Forgejo, c'est le travail d’un administrateur du dépôt commun.

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.14, nous ne voulons pas traduire directement sur la version Python 3.6.

Certaines conventions ont été édictées pour homogénéiser la traduction. Il faut suivre les règles de style imposées, les règles rst et les traductions déjà définies dans le glossaire.

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.

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, it 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.

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 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… ».

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.

Il ne faut pas traduire le nom des éléments de la bibliothèque standard (noms de fonctions, paramètres de ces fonctions, constantes, etc.) mais les laisser tels quel, entourés d'astérisques dans les blocs de texte. Si la documentation contient des exemples, vous pouvez traduire les noms utilisés, en prenant garde d'être cohérent. Vous pouvez ainsi traduire :

def sample_function():
   result = thread.join(timeout=...)
   ...

en

def fonction_exemple():
   resultat = thread.join(timeout=...)
   ...

mais pas en

def fonction_exemple():
   resultat = fildexécution.attendre(délai=...)
   ...

Il faut transformer les liens hypertextes qui redirigent vers une page dont il existe une version française (c'est notamment très souvent le cas pour les articles de Wikipédia). Modifiez le lien et sa description dans ce cas. Si aucune traduction de la cible n'existe, ne traduisez pas la description. Par exemple, `Conway's Game of Life <https://en.wikipedia.org/wiki/Conway%27s_Game_of_Life>`_ doit devenir `Jeu de la vie <https://fr.wikipedia.org/wiki/Jeu_de_la_vie>`_.

Ne traduisez pas le contenu des balises comme :ref:... ou :class:.... Vous devez cependant traduire les balises :term:..., qui font référence à une primitive ou un concept défini dans le glossaire Python. La syntaxe est :term:`nom_français <nom_anglais>`. Par exemple, traduisez:

:term:`dictionary`

en:

:term:`dictionnaire <dictionary>`

Comme le glossaire est déjà traduit, il y a forcément une correspondance à chaque terme que vous pouvez rencontrer.

Afin d'assurer la cohérence de la traduction, voici quelques termes fréquents déjà traduits. Une liste blanche de noms propres, comme « Guido », « C99 » ou de certains anglicismes comme « sérialisable » ou « implémentation», est stockée dans le fichier dict à la racine du projet. Vous pouvez y ajouter une entrée si cela est nécessaire. Si vous devez absolument utiliser un mot anglais, mettez-le en italique (entouré par des astérisques).

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

Le résultat de git diff est souvent encombré de changements inutiles de numéros de ligne, comme :

-#: ../Doc/library/sys.rst:406
+#: ../Doc/library/sys.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

Allez ensuite dans le répertoire du dépôt récupéré (python-docs-fr) et faites :

git config diff.podiff.textconv podiff

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

• les canaux IRC sur irc.libera.chat : - #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 ;
• 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 française 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é succinct de typographie, utile pour apprendre le bon usage des majuscules, des espaces, etc.

L'utilisation de traducteurs automatiques comme DeepL ou semi-automatiques comme reverso 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 ».

Cette touche, absente par défaut 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.

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

• Sur Gnome c'est dans « Paramètres », « Clavier », « Touche de composition ».
• Sur Debian en ligne de commande dpkg-reconfigure keyboard-configuration.
• Ubuntu documente aussi la Compose Key.
• Sur Windows, vous pouvez utiliser wincompose.

Si aucune des solutions précédente ne vous convient, vous pouvez configurer votre fichier ~/.Xmodmap pour ajouter l'équivalent de :

# key Compose
keycode 115 = Multi_key

Utilisez xev pour connaître la bonne correspondance de la touche que vous voulez assigner !

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

# Gestion des touches clavier
xmodmap $HOME/.Xmodmap

Pour finir, redémarrez votre session.

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

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

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

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.

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.

Vérificateur d'orthographe fondé sur Hunspell, qu'il vous faut donc installer :

sudo apt install hunspell hunspell-fr-comprehensive

Attention, dans Debian notamment (et ses dérivés comme Ubuntu), il existe plusieurs dictionnaires français qui diffèrent en raison de l'orthographe réformée. Nous utilisons la version qui accepte les deux orthographes.

C'est l'outil qui se cache derrière make spell.

Permet d'identifier les parties de la documentation qu'il reste à traduire.

C'est l'outil qui se cache derrière make todo.

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. Pour connaître les options disponibles, tapez :

pogrep --help

Formateur de fichier .po. C'est l'outil qui se cache derrière make wrap.

Analyseur de code qui encapsule notamment Grammalecte et qui vérifie la grammaire, l'orthographe et la syntaxe des fichiers .po.