Améliorations diverses du README. (#1288)

* Modifs mineures. * Corrections mineures. * Modifications diverses. * Encore des modifs. * Correction liste. * Suggestions de ChristopheNan. Co-authored-by: Christophe Nanteuil <35002064+christopheNan@users.noreply.github.com> * Suggestion de christopheNan sur podiff. Co-authored-by: Christophe Nanteuil <35002064+christopheNan@users.noreply.github.com>
2020-05-16 17:38:07 +02:00 · 2020-05-16 17:38:07 +02:00 · e6c0a1bf2d
parent 4a089de83b
commit e6c0a1bf2d
2 changed files with 75 additions and 59 deletions
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@ -6,7 +6,7 @@ Prérequis

 - un compte `Github <https://github.com/join>`_ ;
 - un client ``git`` `Linux <https://git-scm.com/>`_ ou `Windows <https://gitforwindows.org/>`_ ;
- un éditeur de fichier ``.po`` (comme `poedit <https://poedit.net/>`_).
+- un éditeur de fichier ``.po`` (comme `Poedit <https://poedit.net/>`_).

 Instructions
 ------------
@ -20,17 +20,17 @@ où vous avez le droit de faire des modifications.

 .. code-block:: bash

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

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

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

-    # Ajoutez le dépôt officiel (nommé upstream)
-    # Ceci permet à *git* de savoir quoi/où est *upstream*
+    # 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
@ -41,17 +41,16 @@ 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 <https://github.com/python/python-docs-fr/issues>`_
 en indiquant dans le titre ``Je travaille sur DOSSIER/FICHIER.po``
-(par exemple « Je travaille sur library/csv.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*.

-N'hésitez pas non plus à vous équiper de quelques outils pour vous aider dans
-votre traduction (voir `Outils utiles pour la traduction`_)
+É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.
@ -71,11 +70,11 @@ Cette nouvelle branche nommée « library-sys » est basée sur « upstream/3
    git checkout -b library-sys upstream/3.8


-Vous pouvez maintenant travailler sur le fichier (typiquement, en utilisant poedit).
-N'oubliez pas de configurer votre nom et votre email dans Poedit.
-(É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)
+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.

@ -83,10 +82,10 @@ Ici, remplacez « library/sys.po » par le fichier que vous avez choisi préc

    poedit library/sys.po

-Ou lancez simplement poedit puis « Fichier » → « Ouvrir »
+Ou lancez simplement Poedit puis « Fichier » → « Ouvrir ».

-Si vous n'utilisez pas poedit, vous pouvez utiliser `powrap <https://github.com/JulienPalard/powrap>`_. (voir la section *outils*)
-qui reformate correctement le fichier que avez vous avez modifié.
+Si vous n'utilisez pas Poedit, vous pouvez utiliser `powrap <https://github.com/JulienPalard/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) :

@ -95,8 +94,8 @@ 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
+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.

@ -105,8 +104,8 @@ 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
+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.

 .. code-block:: bash
@ -135,10 +134,11 @@ Github. Si vous l'avez manqué, allez simplement sur https://github.com/python/p
 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 : Fixes #9999 où 9999 est le numéro du ticket GitHub créé pour réserver le fichier traduit.
+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/corrections. Pour les prendre en compte, retournez sur votre branche
+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) :

@ -183,18 +183,18 @@ Vous pouvez utiliser `potodo`_, un outil fait pour trouver des fichiers ``po``
 local.

 Vous pouvez choisir n'importe quel fichier non réservé dans la liste
-renvoyée par la commande. Cependant, nous vous recommandons de ne **pas**
-commencer avec un fichier de ``c-api`` car c'est une partie très technique.
-Les anciennes versions de Python sont pour la plupart obsolètes et leurs
-journaux de modifications (dans le dossier ``whatsnew``) ne sont pas les pages
-les plus consultées. Il y a des fichiers plus prioritaires à traduire.
+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 sont pas traduites.
+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
@ -210,7 +210,7 @@ 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`_
+`Caractères spéciaux`_.

 Conseils
 --------
@ -249,13 +249,22 @@ 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. N'hésitez pas à ouvrir un ticket
-si vous n'êtes pas d'accord.
+rappels pour les termes fréquents à traduire.

 Pour trouver facilement comment un terme est déjà traduit dans la
 documentation, vous pouvez utiliser `pogrep`_.
@ -268,6 +277,7 @@ 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
@ -324,6 +334,7 @@ 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
@ -350,14 +361,14 @@ compositions suivantes :
 - :kbd:`Compose SPACE SPACE` donne une espace insécable
 - :kbd:`Compose . . .` donne ``…``

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

 - :kbd:`Compose C =` donne ``€``
 - :kbd:`Compose 1 2` donne ``½``
 - :kbd:`Compose ' E` donne ``É``
- …
+- etc.

 Comment définir la touche de composition ?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -390,7 +401,7 @@ Ensuite, dans votre fichier '~/.xsession', ajoutez :
    xmodmap $HOME/.Xmodmap

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

 => Sous Windows, vous
@ -399,10 +410,10 @@ pouvez utiliser `wincompose <https://github.com/SamHocevar/wincompose>`_.
 Le cas de « --- », « -- »,  « ... »
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

-La version anglaise utilise une chose nommée
+La version anglaise utilise les
 `smartquotes <http://docutils.sourceforge.net/docs/user/smartquotes.html>`_,
-qui fonctionne en anglais, mais cause des problèmes dans d'autres langues.
-Nous l'avons donc désactivée dans la version française.
+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
@ -420,7 +431,7 @@ 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 :
+=> Si vous voyez :  
 | « "…" » : faites :kbd:`Compose < <` ou :kbd:`Compose > >`

 Le cas de « :: »
@ -437,7 +448,7 @@ En français, nous mettons une espace insécable devant nos deux-points, comme :
 => Traduisez ``mot deux-points deux-points`` par
 ``mot espace-insécable deux-points deux-points``.

-Pour saisir une espace insécable faites : :kbd:`Compose SPACE SPACE`
+Pour saisir une espace insécable faites :kbd:`Compose SPACE SPACE`

 Le cas des doubles-espaces
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -471,7 +482,7 @@ Par exemple :

 - le dernier paragraphe.

-Malheureusement *poedit* n'aime pas les différences de ponctuation finales
+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
@ -494,12 +505,11 @@ 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``) dans un
-  environnement.
+| Installez-le à l'aide de *pip* (``pip install pogrep``).
 | `Lien vers le dépôt <https://github.com/JulienPalard/pogrep>`__

 Padpo (beta)
-~~~~~~~~~~~~~~~
+~~~~~~~~~~~~

 | Analyseur de code qui vérifie la grammaire et l'orthographe et la syntaxe
  du fichier .po.
@ -511,12 +521,11 @@ Powrap
 ~~~~~~

 | Formateur de fichier .po.
-| Installez-le à l'aide de *pip* (``pip install powrap``) dans un
-  environnement.
+| Installez-le à l'aide de *pip* (``pip install powrap``).
 | `Lien vers le dépôt <https://github.com/JulienPalard/powrap>`__

 Ressources de traduction
-------------------------
+------------------------

 - les canaux IRC sur freenode :

@ -531,7 +540,7 @@ Ressources de traduction
  
  - le `glossaire de la documentation Python <https://docs.python.org/fr/3/glossary.html>`_, car il est déjà traduit,
  - les `glossaires et dictionnaires de traduc.org <https://traduc.org/Glossaires_et_dictionnaires>`_, en particulier le  `grand dictionnaire terminologique <http://gdt.oqlf.gouv.qc.ca/>`_ 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.
+  - 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
  <https://web.archive.org/web/20160821182818/http://frenchmozilla.org/FTP/TEMP/guide_stylistique_December05.pdf>`_ donne
  beaucoup de conseils pour éviter une traduction trop mot à mot ;
@ -539,9 +548,13 @@ Ressources de traduction
  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 ». 

-Simplifier les diffs git
------------------------
+Simplification des diffs git
+----------------------------

 Les diffs git sont souvent encombrés de changements inutiles de numéros
 de ligne, comme :
@ -567,6 +580,9 @@ ce qui suit après vous être assuré que ``~/.local/bin/`` se trouve dans votre
    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
 -----------

--- a/README.rst
+++ b/README.rst
@ -43,11 +43,11 @@ Comment contribuer
 Vous pouvez contribuer :

 - en proposant des *pull requests* Github (solution recommandée) ;
- en envoyant un patch à la liste `traductions <https://lists.afpy.org/mailman/listinfo/traductions>`_.
+- en envoyant un correctif à la liste `traductions <https://lists.afpy.org/mailman/listinfo/traductions>`_.

-Un guide pour contribuer au projet via Github se trouve dans
-`CONTRIBUTING.rst
-<https://github.com/python/python-docs-fr/blob/3.8/CONTRIBUTING.rst>`_.
+Consultez le
+`guide <https://github.com/python/python-docs-fr/blob/3.8/CONTRIBUTING.rst>`_
+pour apprendre les conventions à respecter.


 Où obtenir de l'aide ?
@ -56,8 +56,8 @@ Où obtenir de l'aide ?
 Le coordinateur de cette traduction est `Julien Palard <https://mdk.fr/>`_.

 N'hésitez pas à poser vos questions sur le canal ``#python-fr`` sur `freenode
-<https://kiwi.freenode.net/>`_ (ne nécessite pas d'inscription) ou sur la
-`liste de diffusion des traductions de l'AFPy <https://lists.afpy.org/mailman/listinfo/traductions>`_.
+<https://kiwi.freenode.net/>`_ (ne nécessite pas d'inscription) ou par la
+`liste de diffusion <https://lists.afpy.org/mailman/listinfo/traductions>`_ des traductions de l'AFPy.


 Historique du projet
@ -70,4 +70,4 @@ l'`AFPy <https://www.afpy.org/>`_. En 2017 ce projet est devenu la
 traduction officielle de la documentation Python en français grâce à
 la `PEP 545 <https://www.python.org/dev/peps/pep-0545/>`_. `Jules Lasne
 <https://github.com/Seluj78>`_ à publié fin 2019 une `vidéo de
-l'histoire du dépôt <https://youtu.be/azXmvpEJMhU>`_.
+l'histoire du dépôt <https://youtu.be/azXmvpEJMhU>`_.