From e6c0a1bf2d0de715f9ffeff0e857a143a12b4551 Mon Sep 17 00:00:00 2001 From: Antoine <43954001+awecx@users.noreply.github.com> Date: Sat, 16 May 2020 17:38:07 +0200 Subject: [PATCH] =?UTF-8?q?Am=C3=A9liorations=20diverses=20du=20README.=20?= =?UTF-8?q?(#1288)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 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> --- CONTRIBUTING.rst | 120 +++++++++++++++++++++++++++-------------------- README.rst | 14 +++--- 2 files changed, 75 insertions(+), 59 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index d56e1e91..d0765549 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -6,7 +6,7 @@ Prérequis - un compte `Github `_ ; - un client ``git`` `Linux `_ ou `Windows `_ ; -- un éditeur de fichier ``.po`` (comme `poedit `_). +- un éditeur de fichier ``.po`` (comme `Poedit `_). 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 `_ 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 `_. (voir la section *outils*) -qui reformate correctement le fichier que avez vous avez modifié. +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) : @@ -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 `_. Le cas de « --- », « -- », « ... » ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -La version anglaise utilise une chose nommée +La version anglaise utilise les `smartquotes `_, -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 `__ 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 `__ Ressources de traduction -------------------------- +------------------------ - les canaux IRC sur freenode : @@ -531,7 +540,7 @@ Ressources de traduction - 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. + - 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 ; @@ -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 ----------- diff --git a/README.rst b/README.rst index ae339722..138caae2 100644 --- 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 `_. +- en envoyant un correctif à la liste `traductions `_. -Un guide pour contribuer au projet via Github se trouve dans -`CONTRIBUTING.rst -`_. +Consultez le +`guide `_ +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 `_. N'hésitez pas à poser vos questions sur le canal ``#python-fr`` sur `freenode -`_ (ne nécessite pas d'inscription) ou sur la -`liste de diffusion des traductions de l'AFPy `_. +`_ (ne nécessite pas d'inscription) ou par la +`liste de diffusion `_ des traductions de l'AFPy. Historique du projet @@ -70,4 +70,4 @@ l'`AFPy `_. En 2017 ce projet est devenu la traduction officielle de la documentation Python en français grâce à la `PEP 545 `_. `Jules Lasne `_ à publié fin 2019 une `vidéo de -l'histoire du dépôt `_. \ No newline at end of file +l'histoire du dépôt `_.