From e39a69c2bd8a5f07b4c2806086a69a43785582cb Mon Sep 17 00:00:00 2001 From: Kydlaw Date: Thu, 5 Dec 2019 10:11:04 -0500 Subject: [PATCH] Restructuration du README (#1024) Co-Authored-By: Jules Lasne (jlasne) Co-Authored-By: Vincent Poulailleau Co-Authored-By: Antoine <43954001+awecx@users.noreply.github.com> Co-Authored-By: Julien Palard --- CONTRIBUTION.rst | 552 +++++++++++++++++++++++++++++++++++++++++++++++ README.rst | 515 +------------------------------------------ 2 files changed, 555 insertions(+), 512 deletions(-) create mode 100644 CONTRIBUTION.rst diff --git a/CONTRIBUTION.rst b/CONTRIBUTION.rst new file mode 100644 index 00000000..c39d3502 --- /dev/null +++ b/CONTRIBUTION.rst @@ -0,0 +1,552 @@ +Guide de contribution à la documention via GitHub. +=================================================== + +Prérequis +--------- + +- Un compte `Github `_. +- Un client ``git`` `Linux `_ ou `Windows `_. + https://gitforwindows.org/). +- 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 : + +.. code-block:: bash + + # 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 : + 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/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 aiguillez 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/csv.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`_) + +Vous êtes maintenant prêt. Chaque fois que vous commencerez un nouveau fichier, +suivez cette procédure : + +.. code-block:: bash + + # 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 (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) + # + # 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 va reformater 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 va lancer les vérifications nécessaires. + make verifs + + # C'est le moment de git add et git commit + # git add va permettre de déplacer nos modifications dans l'index de Git en + # attendant d'être déplacée dans le dépôt local. + git add library/sys.po + + # Puis on bascule 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 affichera 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. + + # À 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 + # 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é + # 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. + +**Nous vous recommandons de ne pas commencer avec un fichier de ``c-api`` +car c'est une partie très technique.** + +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. +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 utiliser des mots anglais, mettez les en *italique* +(entourés par des astérisques). + +Pour les caractères spéciaux, référez vous à la section +`Les caractères spéciaux`_ + +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 deuxième 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. + +Traduction de *should* +~~~~~~~~~~~~~~~~~~~~~~ + +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. + +Les 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 : + +- :kbd:`Compose < <` donne « +- :kbd:`Compose > >` donne » +- :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 +simplement fonctionner : + +- :kbd:`Compose C =` donne ``€`` +- :kbd:`Compose 1 2` donne ``½`` +- :kbd:`Compose ' E` donne ``É`` +- … … + +Comment définir la touche de composition ? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Cela dépend de votre système d'exploitation et de votre clavier. + +=> Sous Linux/Unix/\*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 : + +.. code-block:: shell + + # 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 : + +.. code-block:: shell + + # 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 : puis +'Touche composée'. Pour finir, redémarrez votre session. + +=> Sous Windows, vous +pouvez utiliser `wincompose `_. + +Le cas de « --- », « -- », « ... » : +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +La version anglaise utilise une chose nommée +`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. + +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 :kbd:`Compose - - -` +| « ... » : faites :kbd:`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 :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. :: ». +| ``::`` 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 : :kbd:`Compose SPACE SPACE` + +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 repository `__ + +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. +| `Lien vers le repository `__ + +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 repository `__ + +Powrap +~~~~~~ + +| Formateur de fichier .po. +| Installez-le à l'aide de *pip* (``pip install powrap``) dans un + environnement. +| `Lien vers le repository `__ + +Ressources de traduction +------------------------- + +- les canaux IRC sur freenode : + - `#python-docs-fr `_ + Communauté python autour de la documentation française. + - `#python-fr `_ + Communauté python française. + - `#python-doc `_ + Communauté python autour de la documentation anglaise. +- la `liste traductions AFPy `_ ; +- la `liste de diffusion doc-sig + `_ ; +- les `glossaires et dictionnaires de traduc.org + `_, en particulier le + `grand dictionnaire terminologique `_ + de l'Office québécois de la langue française ; +- le `glossaire Python `_, car + il est déjà traduit ; +- le `guide stylistique pour le français de localisation des produits Sun + `_ donne + beaucoup de conseils pour éviter une traduction trop mot à mot ; +- Wikipédia : En allant sur l'article d'un sujet sur la version anglaise + de Wikipédia, puis en basculant sur la version francaise pour voir + comment le sujet est traduit. +- `Petites leçons de typographie `_, + résumé succint de typographie, utile pour apprendre le bon usage des + majuscules, des espaces, etc. + +Glossaire +--------- + +Afin d'assurer la cohérence de nos traductions, 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. + +Pour trouver facilement comment un terme est déjà traduit dans notre +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 +bound lier +bug bogue, *bug* +built-in native +callback fonction de rappel +call stack pile d'appels +debugging débogage +deep copy copie récursive (préféré), ou copie profonde +double quote guillemet +deprecated obsolète +-like -compatible +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 +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 +thread fil d'exécution +traceback trace d'appels, trace de pile +underscore tiret bas, *underscore* +whitespace caractère d'espacement +========================== =============================================== + +Simplifier les diffs git +------------------------ + +Les diffs git sont souvent encombrés de changements inutiles de numéros +de ligne, comme : + +.. code-block:: diff + + -#: ../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``. + +.. 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 + + +Maintenance +----------- + +Toutes ces commandes doivent être exécutées à partir de la racine d'un clone +de ``python-docs-fr``, et certains s'attendent à trouver un clone de CPython +à jour à proximité, comme : + +.. code-block:: bash + + ~/ + ├── python-docs-fr/ + └── cpython/ + +Pour cloner CPython, vous pouvez utiliser : + +.. code-block:: bash + + 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 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + make merge + + +Trouver les chaînes de caractères *fuzzy* +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + make fuzzy + + +Lancer un *build* en local +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + 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 : + +.. code-block:: bash + + 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 : + +.. code-block:: bash + + 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 diff --git a/README.rst b/README.rst index b09cf7fb..78ca3b24 100644 --- a/README.rst +++ b/README.rst @@ -33,7 +33,6 @@ Python est bienvenue et appréciée. En soumettant votre travail à la PSF pour inclusion dans la documentation, vous signifiez votre acceptation de cet accord. - Contribuer à la traduction -------------------------- @@ -42,316 +41,11 @@ Comment contribuer Vous pouvez contribuer en utilisant : -- Des *pull requests* Github (solution recommandée). - En envoyant un patch à la liste `traductions `_. +- Des *pull requests* Github (solution recommandée). - -Contribuer en utilisant Github -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Prérequis : - -- Un compte `Github `_. -- ``git`` `installé `_ (pour Windows, voir - https://gitforwindows.org/). -- Un éditeur de fichier ``.po`` (utilisez `poedit `_ - si vous n'en avez pas déjà un). - - -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 : - -.. code-block:: bash - - # 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 : - git clone https://github.com/VOTRE_NOM_DE_COMPTE/python-docs-fr.git - - # Allez dans le répertoire cloné : - cd python-docs-fr/ - - # Ajoutez le dépot upstream (le dépôt public) en utilisant HTTPS (git - # ne demandera pas de mot de passe ainsi) : - # Ceci permet à *git* de savoir quoi/où est *upstream* - git remote add upstream https://github.com/python/python-docs-fr.git - -Ensuite, vous devez trouver un fichier sur lequel travailler. -Vous pouvez utiliser `potodo `_, un outil -fait pour trouver des fichiers ``po`` à traduire. -Installez-le à l'aide de *pip* (``pip install potodo``) dans un environnement -``python3.6`` ou plus. -Lancez ensuite 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. - -**Nous vous recommandons de ne pas commencer avec un fichier de ``c-api`` -car c'est une partie très technique.** - -Une fois que vous avez choisi un fichier sur lequel travailler, veuillez -ouvrir un `ticket sur Github `_ dans -le format ``Je travaille sur RÉPERTOIRE/FICHIER.po``. Ceci permet à ``potodo`` -de détecter via l'API Github les fichiers ``.po`` réservés dans les tickets -et les *pull requests*. - -Vous êtes maintenant prêt à commencer une session de travail. Chaque -fois que vous commencerez un nouveau fichier, commencez ainsi : - -.. code-block:: bash - - # 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. Nous appellerons notre branche - # « library-sys » mais vous pouvez appeller la vôtre comme vous voulez. - # En général, vous nommez une branche en fonction du fichier sur lequel vous travaillez. - # Par exemple, si vous travaillez sur « library/venv.po », vous pouvez nommer votre - # branche « library-venv ». - - # Mettez à jour votre version locale - git fetch upstream - # Créez une nouvelle branche nommée « library-sys » basée sur « upstream/3.8 ». - git checkout -b library-sys upstream/3.8 - - # Vous pouvez maintenant travailler sur le fichier, typiquement en utilisant poedit. - # Bien sûr, remplacez « library/sys.po » par le fichier que vous avez choisi - # précédemment. - # Configurez poedit pour « ne pas préserver le formatage des - # fichiers existants » (décochez la case), et indiquez une longueur - # de ligne maximum de 79 caractères. - - poedit library/sys.po - - # Si vous n'utilisez pas poedit, vous pouvez utiliser *powrap* (pip install powrap) - # qui va reformater correctement le fichier que avez vous avez modifié. - # Exécutez cette commande : `powrap -m` (reformater tous les fichiers modifiés), - # ou `powrap library/sys.po` (un fichier en particulier) : - powrap -m - - # Quand vous avez fini de traduire, vous pouvez lancer *make verifs* - # (si vous ne le faites pas, ce sera fait automatiquement - # sur github, pas d'inquiétude). - - # 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. - make verifs - - # C'est le moment de git add et git commit - git add -p # C'est l'occasion de se relire, mais git add -u c'est bien aussi - # ou même git add library/sys.po - - 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 qu'un futur `git pull` sache quoi - # tirer) - git push -u origin - - # La commande précédente vous affichera un lien pour ouvrir une pull request sur - # Github. Si vous l'avez manqué, allez simplement sur https://github.com/python/python-docs-fr/ - # et un joli bouton « Compare & pull request » devrait apparaître au bout de quelques secondes - # vous indiquant que vous pouvez demander une pull request. - - # À partir de là, quelqu'un passera en revue vos modifications, et vous voudrez - # probablement corriger les erreurs qu'ils auront trouvé. Retournez alors sur votre - # branche (au cas où vous auriez commencé quelque chose d'autre sur une autre branche) : - git checkout glossary - git pull # pour rapatrier les modifications que vous auriez accepté - # sur l'interface web. - # Réglez les problèmes, puis commitez à nouveau : - git commit -a -m "glossaire : petites corrections". - 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) - -Donc oui, 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. Considérez-les comme étant en lecture seule, -vous éviterez les problèmes. - -Avant de valider, vous devriez utiliser `grammalecte -`_ pour vérifier vos traductions. - - -Toutes les traductions doivent être 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 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 les entrées déjà traduites, et enfin -traduire celles qui ne sont pas traduites (trouvez-les à l'aide de -`make todo`)... - -- Ne traduisez pas le contenu de ``:ref :...`` et ``:term :...``. -- Mettez les mots anglais, si vous devez les utiliser, en *italique* - (entourés par des astérisques). -- ``::`` à la fin de certains paragraphes doivent être traduits en `` : - ::`` en français pour placer l'espace avant les deux-points. -- Si vous traduisez un titre de lien, veuillez traduire le lien aussi. - (surtout si c'est un lien Wikipédia et que l'article a une traduction). - Si aucune traduction de la cible n'existe, ne traduisez pas le titre. -- 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. - -Le cas de « --- » -~~~~~~~~~~~~~~~~~ - -La version anglaise utilise une chose nommée `smartquotes -`_, qui -essaie d'être intelligente, qui fonctionne en anglais, mais cause -rapidement des problèmes dans d'autres langues. -Nous l'avons donc désactivée. - -Les *smartquotes* sont également responsables de la transformation de -``--`` en *en-dash* (``–``), de ``---`` en *em-dash* (``—``), et de -``...`` en ``…``. - -Comme nous n'avons pas de *smartquotes*, nous devrons également « traduire » -cela manuellement, donc si vous voyez ``---`` en anglais, vous devez le -transformer en ``—`` en français. - - -Le cas de « :: » -~~~~~~~~~~~~~~~~ - -Du point de vue du langage *reStructuredText* (ou *rst*) utilisé dans la documentation : - -=> ``::`` 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 ». - -Donc, dans du *rst*, en anglais, nous voyons soit « bla bla:: », soit « bla bla. :: ». - -En français, nous mettons une espace insécable devant nos deux-points, comme : -« Et voilà : ». - -L'utilisation de l'espace insécable en *rst* est naturelle, vous n'aurez qu'à -écrire ``Et voilà ::``. Le ``::`` n'est pas précédé d'un espace normal, -il affichera les deux-points et introduira le bloc de code, et c'est bon. - -Si vous ne savez pas comment taper une espace insécable, il y a une astuce : -lisez celle de la touche *compose* dans la section suivante ; sinon : - -=> Traduisez ``deux-points deux-points`` par -``espace deux-points espace deux-points deux-points``. - -Les caractères ``espace deux-points`` sont restitués tel quel, -c'est du français correct, et la balise ``espace deux-points deux-points`` qui -suit n'affichera rien et introduira le bloc de code. - -Dans un ``.po`` ça donne : `` : ::`` - -Non ! Ça n'insère pas magiquement une espace insécable donc ce n'est toujours pas -vraiment du français valide. - -Oui ! il vaut mieux apprendre à taper les espaces insécables. - - -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'utlisation 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 deuxième 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. - -Traduction de *should* -~~~~~~~~~~~~~~~~~~~~~~ - -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. - -Comment saisir des em-dash, des ellipses, des guillemets français, ou des espaces insécables ? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Malheureusement, cela dépend de votre système d'exploitation et de votre clavier. - -=> Sous Linux/Unix/\*BSD (tel OpenBSD), vous pouvez utilisez une -`Touche de composition `_, -c'est facile à 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 : - -.. code-block:: shell - - # 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 : - -.. code-block:: shell - - # 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 : puis 'Touche composée'. -Pour finir, redémarrez votre session. - -=> Sous Windows, vous -pouvez utiliser `wincompose `_. - -Avec une touche de composition (personnellement j'utilise ``alt-gr``, -vous pouvez aussi utiliser ``verr maj 🔒``), vous pouvez utiliser les -compositions suivantes : - -- Composer ``<`` ``<`` donne ``« `` -- Composer ``>`` ``>`` donne `` »`` -- Composer espace espace donne une espace insécable -- Composer ``.`` ``.`` ``.`` donne ``…`` - -Comme vous l'avez noté, presque toutes les compositions sont faciles -à retenir, vous pouvez donc essayer les autres et elles devraient tout -simplement fonctionner : - -- Composer ``C`` ``=`` donne ``€`` -- Composer ``1`` ``2`` donne ``½`` -- Composer ``'`` ``E`` donne ``É`` -- … … - +Un guide pour contribuer via Github `se trouve ici +`_ : Où obtenir de l'aide ? ~~~~~~~~~~~~~~~~~~~~~~ @@ -362,104 +56,6 @@ 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 `_. - -Ressources de traduction ------------------------- - -- le canal IRC `#python-fr `_ sur freenode ; -- la `liste traductions AFPy `_ ; -- la `liste de diffusion doc-sig - `_ ; -- les `glossaires et dictionnaires de traduc.org - `_, en particulier le - `grand dictionnaire terminologique `_ - de l'Office québécois de la langue française ; -- le `glossaire Python `_, car - il est déjà traduit ; -- le `guide stylistique pour le français de localisation des produits Sun - `_ donne - beaucoup de conseils pour éviter une traduction trop mot à mot ; -- `deepl.com/translator `_ ; -- `Petites leçons de typographie `_, - résumé succint de typographie, utile pour apprendre le bon usage des majuscules, - des espaces, etc. - - -Glossaire ---------- - -Afin d'assurer la cohérence de nos traductions, 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. - -Pour trouver facilement comment un terme est déjà traduit dans notre documentation, -vous pouvez utiliser -`find_in_po.py `_. - -========================== =============================================== -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 -bound lier -bug bogue, *bug* -built-in native -callback fonction de rappel -call stack pile d'appels -debugging débogage -deep copy copie récursive (préféré), ou copie profonde -double quote guillemet -deprecated obsolète --like -compatible -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 -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 -thread fil d'exécution -traceback trace d'appels, trace de pile -underscore tiret bas, *underscore* -========================== =============================================== - - Historique du projet -------------------- @@ -468,108 +64,3 @@ Ce projet a été lancé `vers 2012 par des membres de l'`AFPy `_. En 2017 ce projet est devenu la traduction officielle de la documentation Python en français grâce à la `PEP 545 `_. - - -Simplifier les diffs git ------------------------- - -Les diffs git sont souvent encombrés de changements inutiles de numéros -de ligne, comme : - -.. code-block:: diff - - -#: ../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``. - -.. 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 - - -Maintenance ------------ - -Toutes ces commandes doivent être exécutées à partir de la racine d'un clone -de ``python-docs-fr``, et certains s'attendent à trouver un clone de CPython -à jour à proximité, comme : - -.. code-block:: bash - - ~/ - ├── python-docs-fr/ - └── cpython/ - -Pour cloner CPython, vous pouvez utiliser : - -.. code-block:: bash - - 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 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. code-block:: bash - - make merge - - -Trouver les chaînes de caractères *fuzzy* -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. code-block:: bash - - make fuzzy - - -Lancer un *build* en local -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. code-block:: bash - - 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 : - -.. code-block:: bash - - 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 : - -.. code-block:: bash - - 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