diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index b68711d5..8e9a595b 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1,26 +1,125 @@ Guide de contribution à la documentation via GitHub -=================================================== - -Instructions ------------- +################################################### Prérequis -~~~~~~~~~ +========= + +Outils souhaitables +------------------- + +Pour pouvoir participer à la traduction en commun, il est souhaitable +d'installer : + +- un client ``git`` `Linux `_, `MacOS + `_ ou `Windows `_ ; -- un client ``git`` `Linux `_, `MacOS `_ ou `Windows `_ ; - un éditeur de fichier ``.po`` (comme `Poedit `_). -Équipez-vous aussi de quelques outils pour vous aider dans -votre traduction (voir `Outils utiles pour la traduction`_). + +Outils facultatifs +------------------ +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. Dans un +environnement disposant de Python 3.7 ou plus, installez-le avec :: + + python3 -m pip install poutils + +Dans notre cas, les utilitaires de *Poutils* qui nous intéressent sont : + +Pospell +^^^^^^^ + +Vérificateur d'orthographe fondé sur Hunspell. ``make spell`` exécute +Pospell. Pour l'utiliser, il vous faut installer Hunspell. 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. Installez celui qui contient les deux orthographes avec :: + + sudo apt install hunspell hunspell-fr-comprehensive + +Potodo +^^^^^^ + +Permet d'identifier les parties de la documentation qu'il reste à +traduire. ``make todo`` fait appel à Potodo. + +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. Pour connaître les options disponibles, tapez :: + + pogrep --help + +Powrap +^^^^^^ + +Formateur de fichier *.po*. C'est l'outil qui se cache derrière ``make +wrap``. + +Padpo (beta) +^^^^^^^^^^^^ + +Analyseur de code qui encapsule notamment `Grammalecte +`_ et qui vérifie la grammaire, l'orthographe +et la syntaxe des fichiers *.po*. + +Configuration des outils +------------------------ + +Configuration de Poedit +^^^^^^^^^^^^^^^^^^^^^^^ +* N'oubliez pas de configurer votre nom et + votre adresse de courriel (Édition → Préférences → Général). +* Vérifiez égalemnt qu'il est configuré pour passer à la ligne à 79 + caractères (Édition → Préférences → Avancé → Passer à la ligne à + 79). + +Configuration de Git (rendre plus lisible l'affichage des modifications) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Le résultat de ``git diff`` est souvent encombré de changements inutiles de numéros +de ligne, comme : + +.. code-block:: diff + + -#: ../Doc/library/sys.rst:406 + +#: ../Doc/library/sys.rst:408 -*fork* personnel sur Github -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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``. -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, c'est un endroit -où vous avez le droit de faire des modifications. +.. code-block:: bash + + cat < ~/.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 affiche les changements que sur +les fichiers de la traduction, sans incidence sur les autres. + +Première étape : créer et peupler son dépôt +=========================================== + +Sur Github +---------- + +Depuis votre compte GitHub, se rendre dans le dépôt des sources `python-docs-fr +`_ puis cliquer sur son bouton ``Fork``. +Ceci crée une copie du projet sur votre compte Github. C'est sur cette copie +que vous avez le droit de faire des modifications. Étape par étape : @@ -40,12 +139,14 @@ où vous avez le droit de faire des modifications. git remote add upstream https://github.com/python/python-docs-fr.git -*fork* personnel sur une autre forge -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Sur une autre forge +------------------- -Si vous n'avez pas de compte Github, il est possible *fork* ce dépôt sur une autre forge. +Si vous n'avez pas de compte Github, il est possible d'utiliser une autre forge. Vous devez dans un premier temps initier un dépôt vide sur la forge où vous voulez héberger le -dépôt. +dépôt puis le peupler. + +Étape par étape : .. code-block:: bash @@ -66,15 +167,49 @@ dépôt. git push -u origin -Réservation d'un fichier -~~~~~~~~~~~~~~~~~~~~~~~~ +Deuxième étape : choisir et réserver le fichier sur lequel travailler +===================================================================== -*Chaque fois que vous commencez un nouveau fichier, suivez cette procédure.* +Note liminaire +-------------- -Ensuite, vous devez trouver un fichier sur lequel travailler -(pour vous aiguiller, lisez la section `Que traduire ?`_). Nous vous conseillons -de choisir, si possible, un fichier traitant d'un sujet que vous maitrisez, cela -vous aidera grandement à produire une traduction de bonne qualité. +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. + +Trouver un fichier sur lequel travailler +---------------------------------------- + +Pour vous aiguiller dans votre choix, vous pouvez utiliser `potodo`, +un outil recherchant des fichiers ``.po`` à traduire. Une fois +installé, utilisez la commande ``make todo`` dans votre clone local. + +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 maitrisez, 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 @@ -82,6 +217,11 @@ 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. +Réserver le fichier +------------------- + +*Chaque fois que vous commencez un nouveau fichier, suivez cette procédure.* + Une fois que vous avez choisi un fichier sur lequel travailler vous pouvez nous le signaler par différents moyens : @@ -100,12 +240,15 @@ dans les tickets et les *pull requests*. `irc://irc.libera.chat/#python-docs-fr `_ pour nous le signaler. -Vous êtes maintenant prêt. Chaque fois que vous commencerez un nouveau fichier, -suivez cette procédure : -Pour travailler, nous avons besoin d'une branche, basée sur une version à jour -(fraîchement récupérée) de la branche « upstream/3.11 ». On met donc à jour notre -version locale. +Création de la branche de traduction +------------------------------------ + +*Chaque fois que vous commencez un nouveau fichier, suivez cette procédure.* + +Vous êtes maintenant prêt. Pour travailler, nous avons besoin d'une +branche, basée sur une version à jour (fraîchement récupérée) de la +branche « upstream/3.11 ». On met donc à jour notre version locale. .. code-block:: bash @@ -122,12 +265,12 @@ fichier sur lequel on travaille. Par exemple, si vous travaillez sur git checkout -b library-sys upstream/3.11 -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). +Troisième étape: Traduction +=========================== + +Avec Poedit +--------------- Ici, remplacez « library/sys.po » par le fichier que vous avez choisi précédemment. .. code-block:: bash @@ -138,11 +281,11 @@ Ici, remplacez « library/sys.po » par le fichier que vous avez choisi préc Ou lancez simplement Poedit puis « Fichier » → « Ouvrir ». -Traduction -~~~~~~~~~~ +Vérifications après traduction +------------------------------ -Vous pouvez dès à présent commencer à traduire le fichier en -respectant les `conventions`_ du projet. Pour vous y aider, la commande : +Après avoir modifié les fichiers, vérifiez que vous respectez les +`conventions`_ du projet. Pour vous y aider, la commande : .. code-block:: bash @@ -157,8 +300,9 @@ Si ``make verifs`` 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, il faut compiler la documentation, c'est-à-dire générer les fichiers HTML -affichés par le site, pour les relire. Si la commande précédente s'est exécutée sans erreur, la +Une fois la traduction finie, il faut compiler la documentation, +c'est-à-dire générer les fichiers HTML affichés par le site, pour les +relire. Si la commande précédente s'est exécutée sans erreur, la compilation ne devrait pas échouer. .. code-block:: bash @@ -175,12 +319,9 @@ documentation local : La documentation est publiée l'adresse ``_. -Si vous souhaitez modifier le port de ce serveur (par exemple 8080), utilisez : - -.. code-block:: bash - - make serve SERVE_PORT=8080 +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. @@ -190,21 +331,21 @@ Poedit donne beaucoup d'avertissements, par exemple pour vous informer que la source. Ces avertissements ne sont pas tous fondés. En cas de doute, *affichez et relisez la page HTML produite* avec ``make serve``. -*pull request* -~~~~~~~~~~~~~~ +Quatrième étape : publier sa traduction +======================================= Une fois que le *make verifs* 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 le dépôt local. -``git add`` place nos modifications dans l'index de Git en -attendant d'être propagées dans le dépôt local. +* ``git add`` place nos modifications dans l'index de Git en attendant + d'être propagées dans le dépôt local. .. code-block:: bash git add library/sys.po -``git commit`` permet de les propager : +* ``git commit`` permet de les propager : .. code-block:: bash @@ -222,7 +363,7 @@ branche est liée à votre *fork* (et donc que vos futurs ``git pull`` et git push --set-upstream origin Sur Github -++++++++++ +---------- 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 @@ -250,7 +391,7 @@ GitHub puis relancer ``powrap`` : git push Sur une autre forge -+++++++++++++++++++ +------------------- Quand vous avez poussé vos modifications, il y a plusieurs possibilités. @@ -307,38 +448,10 @@ 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 ``make todo`` dans votre clone -local. - -Vous pouvez choisir n'importe quel fichier non réservé dans la liste renvoyée. -Elle contient tous les fichiers qui ne sont pas encore complètement traduits, à -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/*, *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. - -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é remodifié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. Conventions ------------ +=========== 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 @@ -346,7 +459,7 @@ les traductions déjà définies dans le `glossaire`_. 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 @@ -357,7 +470,7 @@ documentation anglaise, si le rythme l'exige. Il faut aussi chercher des garde aux anglicismes. 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 @@ -370,7 +483,7 @@ 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 @@ -384,17 +497,17 @@ phrase « these objects can be accessed by… » se traduit mieux par « on ac 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. Règles rst -~~~~~~~~~~ +---------- Prototypes et exemples -++++++++++++++++++++++ +^^^^^^^^^^^^^^^^^^^^^^ 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 @@ -428,7 +541,7 @@ mais pas en Liens hypertextes -+++++++++++++++++ +^^^^^^^^^^^^^^^^^ 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 @@ -439,7 +552,7 @@ doit devenir ```Jeu de la vie `_``. Balises -+++++++ +^^^^^^^ Ne traduisez pas le contenu des balises comme ``:ref:...`` ou ``:class:...``. Vous devez cependant traduire les balises ``:term:...``, qui font référence à @@ -452,7 +565,7 @@ terme que vous pouvez rencontrer. Glossaire -~~~~~~~~~ +========= 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 », @@ -552,7 +665,7 @@ whitespace caractère d'espacement ========================== =============================================== Ressources de traduction ------------------------- +======================== - les canaux IRC sur irc.libera.chat : @@ -582,10 +695,10 @@ page et génèrent une documentation au style très « lourd ». Caractères spéciaux et typographie ----------------------------------- +================================== La touche de composition -~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------ Cette `touche `_, absente par défaut des claviers, permet de saisir des @@ -610,7 +723,7 @@ simplement fonctionner : - etc. Comment définir la touche de composition ? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------------------------ Cela dépend de votre système d'exploitation et de votre clavier. @@ -648,7 +761,7 @@ modifier dans les « Paramètres » → « Clavier » → « Disposition » → pouvez utiliser `wincompose `_. Le cas de « --- », « -- », « ... » -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ La version anglaise utilise les `smartquotes `_, @@ -664,7 +777,7 @@ Les *smartquotes* sont normalement responsables de la transformation de | « ... » : faites :kbd:`Compose . . .` Le cas de « "…" » -~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^ Les guillemets français ``«`` et ``»`` ne sont pas identiques aux guillemets anglais ``"``. Cependant, Python utilise les guillemets @@ -675,7 +788,7 @@ traduire les guillemets mais pas les délimiteurs de chaîne. | « "…" » : faites :kbd:`Compose < <` ou :kbd:`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. :: ». @@ -691,7 +804,7 @@ En français, nous mettons une espace insécable devant nos deux-points, comme : Pour saisir une espace insécable faites :kbd:`Compose SPACE SPACE` Les doubles-espaces -~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^ La documentation originale comporte beaucoup de doubles-espaces. Cela se fait en anglais, mais pas en français. De toute manière, @@ -702,7 +815,7 @@ 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 @@ -728,87 +841,3 @@ 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 --------------------------------- - -Poutils -~~~~~~~ - -`Poutils `_ est un paquet PyPI qui -regroupe un certain nombre d'outils liés à la traduction. Dans un -environnement disposant de Python 3.7 ou plus, installez-le avec :: - - python3 -m pip install poutils - -Voici le détail des paquets qui nous intéressent dans Poutils : - -Pospell -+++++++ - -Vérificateur d'orthographe fondé sur Hunspell. ``make spell`` exécute -Pospell. Pour l'utiliser, il vous faut installer Hunspell. 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. Installez celui qui contient les deux orthographes avec :: - - sudo apt install hunspell hunspell-fr-comprehensive - -Potodo -++++++ - -Permet d'identifier les parties de la documentation qu'il reste à -traduire. ``make todo`` fait appel à Potodo. - -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. Pour connaître les options disponibles, tapez :: - - pogrep --help - -Powrap -++++++ - -Formateur de fichier *.po*. C'est l'outil qui se cache derrière ``make -wrap``. - -Padpo (beta) -++++++++++++ - -Analyseur de code qui encapsule notamment `Grammalecte -`_ et qui vérifie la grammaire, l'orthographe -et la syntaxe des fichiers *.po*. - - -Affichage des modifications par Git -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Le résultat de ``git diff`` est souvent encombré de changements inutiles de numéros -de ligne, comme : - -.. code-block:: diff - - -#: ../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``. - -.. code-block:: bash - - cat < ~/.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 affiche les changements que sur -les fichiers de la traduction, sans incidence sur les autres.