merwyn
/
python-docs-fr
forked from AFPy/python-docs-fr
1
0
Fork 0
Code Pull Requests Activity
python-docs-fr/CONTRIBUTING.rst

866 lines
34 KiB
ReStructuredText
Raw Permalink Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Guide de contribution à la documentation
########################################
Prérequis
=========
Outils souhaitables
-------------------
Pour pouvoir participer à la traduction en commun, il est souhaitable
d'installer :
- un client ``git`` `Linux <https://git-scm.com/>`_, `MacOS
<https://git-scm.com/>`_ ou `Windows <https://gitforwindows.org/>`_ ;
- un éditeur de fichier ``.po`` (comme `Poedit <https://poedit.net/>`_).
Outils facultatifs
------------------
De plus, il peut être utile de s'équiper d'utilitaires pour faciliter
la manipulation des fichiers ``.po`` et la traduction.
`Poutils <https://pypi.org/project/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 :
Debian / Ubuntu ::
python3 -m pip install poutils
MacOS (intel) ::
brew install hunspell
sudo mkdir /Library/Spelling/
# Aller chercher le dictionnaire français sur grammalecte
# http://grammalecte.net:8080/file?name=gc_lang/fr/oxt/Dictionnaires/dictionaries/fr-toutesvariantes.dic&ci=tip
# http://grammalecte.net:8080/file?name=gc_lang/fr/oxt/Dictionnaires/dictionaries/fr-toutesvariantes.aff&ci=tip
sudo mv ~/Downloads/fr-toutesvariantes.dic /Library/Spelling/fr_FR.dic
sudo mv ~/Downloads/fr-toutesvariantes.aff /Library/Spelling/fr_FR.aff
ln -s /usr/local/Cellar/hunspell/1.7.2/lib/libhunspell-1.7.0.dylib /usr/local/Cellar/hunspell/1.7.2/lib/libhunspell.dylib
CFLAGS=$(pkg-config --cflags hunspell) LDFLAGS=$(pkg-config --libs hunspell) python3 -m pip install hunspell
python3 -m pip install poutils
MacOS (Universal) ::
brew install hunspell
sudo mkdir /Library/Spelling/
# Aller chercher le dictionnaire français sur grammalecte
# http://grammalecte.net:8080/file?name=gc_lang/fr/oxt/Dictionnaires/dictionaries/fr-toutesvariantes.dic&ci=tip
# http://grammalecte.net:8080/file?name=gc_lang/fr/oxt/Dictionnaires/dictionaries/fr-toutesvariantes.aff&ci=tip
sudo mv ~/Downloads/fr-toutesvariantes.dic /Library/Spelling/fr_FR.dic
sudo mv ~/Downloads/fr-toutesvariantes.aff /Library/Spelling/fr_FR.aff
ln -s /opt/homebrew/lib/libhunspell-1.7.0.dylib /opt/homebrew/Cellar/hunspell/1.7.2/lib/libhunspell-1.7.0.dylib
CFLAGS=$(pkg-config --cflags hunspell) LDFLAGS=$(pkg-config --libs hunspell) python3 -m pip install hunspell
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
<https://grammalecte.net>`_ 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 également 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
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 <<EOF > ~/.local/bin/podiff
#!/bin/sh
grep -v '^#:' "\$1"
EOF
chmod a+x ~/.local/bin/podiff
Allez ensuite dans le répertoire du dépôt récupéré (``python-docs-fr``) et faites :
.. code-block:: bash
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.
.. _cloner:
Première étape : créer et peupler son dépôt
===========================================
Si ce n'est pas déjà fait, créez un compte sur `le serveur Git de
l'AFPy <https://git.afpy.org/>`_. Puis, allez sur le dépôt
`python-docs-fr <https://git.afpy.org/AFPy/python-docs-fr>`_ et
cliquez sur le bouton « Bifurcation » en haut à droite. Vous créez
ainsi sur Gitea une copie privée du projet où vous avez le droit de
faire des modifications.
À ce stade, il est recommandé, bien que facultatif, de vous créer une
clé SSH si vous n'en avez pas encore, et de l'ajouter à votre compte
Gitea. Pour générer la clé, consultez `le guide de GitLab
<https://docs.gitlab.com/ee/user/ssh.html>`_ ou `celui de GitHub
<https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/connecting-to-github-with-ssh>`_.
Pour l'ajouter à votre compte Gitea, il suffit d'aller dans le menu de
votre compte en haut à droite et de cliquer sur « Configuration »,
puis d'aller dans l'onglet « Clés SSH / GPG », et de copier la clé
SSH.
Si vous le préférez, vous pouvez également vous passer de cette
configuration et utiliser le HTTPS à la place du SSH. Néanmoins,
sachez que vous devrez taper votre nom d'utilisateur et votre mot de
passe Gitea à chaque fois que vous ouvrez ou modifiez une
contribution.
Enfin, faites une copie locale du dépôt sur votre ordinateur afin de
pouvoir éditer les fichiers, avec ces commandes :
.. code-block:: bash
# Clonez votre copie sur Gitea avec `git` en utilisant SSH :
git clone git@git.afpy.org:VOTRE_NOM_DE_COMPTE_GITEA/python-docs-fr.git
# ... ou bien avec HTTPS :
git clone https://git.afpy.org/VOTRE_NOM_DE_COMPTE_GITEA/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 et où est *upstream*
git remote add upstream https://git.afpy.org/AFPy/python-docs-fr.git
Deuxième étape : choisir et réserver le fichier sur lequel travailler
=====================================================================
Note liminaire
--------------
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 maîtrisez, cela vous aidera grandement à produire
une traduction de bonne qualité.
Si c'est votre première contribution, commencez par une toute petite
traduction, de quelques paragraphes maximum, pour vous familiariser. Il n'est
pas nécessaire de terminer un fichier lorsqu'on le commence, vous
pouvez donc prendre n'importe quel fichier, mais ne traduire que
quelques paragraphes.
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 :
* Soit en ouvrant un `ticket sur Gitea <https://git.afpy.org/AFPy/python-docs-fr/issues>`_
en indiquant dans le titre ``Je travaille sur DOSSIER/FICHIER.po``
(par exemple « Je travaille sur library/sys.po »).
Ceci permet à `potodo`_ de détecter via l'API Gitea les fichiers ``.po`` réservés
dans les tickets et les demandes d'ajout.
* Soit en créant un sujet sur le
`discuss de l'AFPy <https://discuss.afpy.org/>`_ dans la section Traduction
en indiquant sur quoi vous travaillez et l'URL de votre dépôt.
* Soit sur IRC en venant sur le canal
`irc://irc.libera.chat/#python-docs-fr <https://web.libera.chat/#python-docs-fr>`_
pour nous le signaler.
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
git fetch upstream
On crée ensuite la branche, en la basant sur « upstream/3.11 », fraîchement récupérée.
Il est pratique de nommer cette branche en fonction du
fichier sur lequel on travaille. Par exemple, si vous travaillez sur
« library/sys.po », vous pouvez nommer votre branche « library-sys ».
.. code-block:: bash
git switch -c library-sys upstream/3.11
Troisième étape: Traduction
===========================
Avec Poedit
---------------
Ici, remplacez « library/sys.po » par le fichier que vous avez choisi précédemment.
.. code-block:: bash
poedit library/sys.po
Ou lancez simplement Poedit puis « Fichier » → « Ouvrir ».
Vérifications après traduction
------------------------------
Après avoir modifié les fichiers, vérifiez que vous respectez les
`conventions`_ du projet. Pour vous y aider, la commande :
.. code-block:: bash
make verifs
vérifie la longueur des lignes et l'orthographe (mais pas la
grammaire, pour cela utilisez `padpo (beta)`_). En cas de doute, un
`glossaire`_ répertorie déjà les traductions retenues pour certains
termes techniques ou faux amis en anglais.
Si ``make 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
compilation ne devrait pas échouer.
.. code-block:: bash
make
Vérifiez alors le rendu de la traduction « en vrai ». Lancez un serveur de
documentation local :
.. code-block:: bash
make htmlview
La documentation est publiée à l'adresse `<http://localhost:8000/library/sys.html>`_.
Attention: le port TCP/8000 ne peut être changé, il convient d'arrêter
tout service qui écouterait sur celui-ci.
Vous pouvez recommencer les étapes de cette section autant de fois que
nécessaire.
Poedit donne beaucoup d'avertissements, par exemple pour vous informer que
« la traduction devrait commencer par une majuscule » car c'est le cas pour
la source. Ces avertissements ne sont pas tous fondés. En cas de doute,
*affichez et relisez la page HTML produite* avec ``make htmlview``.
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.
.. code-block:: bash
git add library/sys.po
* ``git commit`` permet de les propager :
.. code-block:: bash
git commit --message "Traduction de library/sys.po" # Ou un autre message plus inspiré :)
Poussez ensuite vos modifications sur votre bifurcation (*fork*) avec ``git push``.
Le ``-u`` n'est utile qu'une fois pour que votre client git se souvienne que cette
branche est liée à votre bifurcation (et donc que vos futurs ``git pull`` et
``git push`` sachent quoi tirer).
.. code-block:: bash
git push --set-upstream origin
Sur Gitea
---------
La commande précédente vous affiche un lien pour ouvrir une demande d'ajout sur
Gitea. Si vous l'avez manqué, allez simplement sur
https://git.afpy.org/AFPy/python-docs-fr/pulls et cliquez
sur le bouton « Nouvelle demande d'ajout ».
Mettez dans le commentaire de la demande d'ajout le texte suivant :
« Closes #XXXX » où XXXX est le numéro du ticket Gitea créé pour réserver le
fichier traduit. Cela permet à Gitea de lier la demande d'ajout au ticket de
réservation.
Il peut arriver que vous ayez besoin de reprendre votre demande d'ajout sur votre
ordinateur après avoir fait des modifications en ligne sur Gitea,
par exemple lorsque Gitea vous offre la possibilité de faire un commit
automatique contenant les suggestions proposées pendant la revue.
Cela fonctionne bien, mais le résultat n'est pas toujours accepté par
``powrap``. Si cela arrive, vous pouvez récupérer le commit fait par
Gitea puis relancer ``powrap`` :
.. code-block:: bash
git pull
powrap <fichier.po>
git add <fichier.po>
git commit -m "Formatage après commit automatique"
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 Gitea) ;
- vous poussez sur *origin* (votre clone sur Gitea).
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 demandes d'ajout après les avoir relues.
Vous avez peut-être aussi remarqué que vous n'avez jamais commité sur une
branche de version (3.9, 3.10, 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.10, nous ne voulons pas
traduire directement sur la version Python 3.6.
Si nécessaire, les traductions seraient rétroportées sur les versions
les plus anciennes par l'`équipe de documentation
<https://www.python.org/dev/peps/pep-8015/#documentation-team>`_.
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
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
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.
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, it will produce
that… ». En français, l'utilisation du présent convient tout à fait et le
présent est souvent plus facile à lire : « si vous faites ceci, il se
produit cela… ». On ne conserve le futur que si la seconde proposition
se situe réellement dans le futur (par exemple, on peut penser qu'un
processus de compilation n'est pas immédiat) ou pour des raisons de
concordance des temps.
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
français, il est d'usage d'être plus direct pour être correctement compris :
« vous devez ». *Vous devriez* est en effet généralement compris comme quelque
chose dont on peut de temps en temps se passer, alors que c'est très
rarement le cas pour les « you should » de cette documentation.
De la même manière, « can » est souvent mieux traduit sans introduire de notion
de possibilité, en particulier quand la phrase est à la voix passive ; la
phrase « these objects can be accessed by… » se traduit mieux par « on accède à
ces objets en… ».
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
tels quel, entourés d'astérisques dans les blocs de texte.
Si la documentation contient des exemples, vous *pouvez* traduire les noms
utilisés, en prenant garde d'être cohérent. Vous pouvez ainsi traduire :
.. code-block:: python
def sample_function():
result = thread.join(timeout=...)
...
en
.. code-block:: python
def fonction_exemple():
resultat = thread.join(timeout=...)
...
mais pas en
.. code-block:: python
def fonction_exemple():
resultat = fildexécution.attendre(délai=...)
...
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
articles de Wikipédia). Modifiez le lien *et* sa description dans ce cas.
Si aucune traduction de la cible n'existe, ne traduisez pas la description.
Par exemple, ```Conway's Game of Life <https://en.wikipedia.org/wiki/Conway%27s_Game_of_Life>`_``
doit devenir ```Jeu de la vie <https://fr.wikipedia.org/wiki/Jeu_de_la_vie>`_``.
Balises
^^^^^^^
Ne traduisez pas le contenu des balises comme ``:ref:...`` ou ``:class:...``.
Vous devez cependant traduire les balises ``:term:...``, qui font référence à
une primitive ou un concept défini dans le `glossaire Python <https://docs.python.org/fr/3/glossary.html>`_.
La syntaxe est ``:term:`nom_français <nom_anglais>```. Par exemple, traduisez
``:term:`dictionary``` en ``:term:`dictionnaire <dictionary>```.
Comme le glossaire est déjà traduit, il y a forcément une correspondance à chaque
terme que vous pouvez rencontrer.
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 »,
« C99 » ou de certains anglicismes comme « sérialisable » ou « implémentation»,
est stockée dans le fichier *dict* à la racine du projet. Vous pouvez
y ajouter une entrée si cela est nécessaire.
Si vous devez *absolument* utiliser un mot anglais, mettez-le en italique
(entouré par des astérisques).
Pour trouver facilement comment un terme est déjà traduit dans la
documentation, vous pouvez utiliser `pogrep`_.
========================== ===============================================
Terme Traduction
========================== ===============================================
-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
backport rétroporter
base class classe mère
bound lier
bug bogue
built-in natif
bytecode code intermédiaire
callback fonction de rappel
call stack pile d'appels
caught (exception) interceptée
code points points de code
daemon *daemon*
debugging débogage
deep copy copie récursive (préféré), ou copie profonde
double quote guillemet
deprecated obsolète
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
<https://fr.wikipedia.org/wiki/Et_al.>`_
suivant le contexte
export exportation
expression expression
framework cadriciel
frozen package or set paquet ou ensemble figé
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
index indice (en particulier quand on parle de chaînes
de caractères)
installer installateur
interpreter interpréteur
keyword mot clé
keyword argument argument nommé
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
<https://fr.wikipedia.org/wiki/Endianness>`_
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
parse, parser analyser, analyseur syntaxique
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)
roughly approximativement, à peu près (on ne traduit pas
« roughly equivalent » par « sensiblement équivalent »)
setter mutateur
simple quote guillemet simple
socket connecteur ou interface de connexion
sort trier (préféré), ordonner, classer
specify définir, préciser (plutôt que « spécifier »)
statement instruction
subprocess sous-processus
support prendre en charge, implémenter (« supporter »
n'a pas le même sens en français)
token (parsing) lexème
thread fil d'exécution
traceback trace d'appels, trace de pile
tuple *n*-uplet (avec *n* en italique), on peut
traduire *2-tuple* par « paire » ou « couple »,
*3-tuple* par « triplet », *4-tuple* par
« quadruplet » etc.
typically normalement, habituellement, comme d'habitude
(plutôt que « typiquement »)
underscore tiret bas, *underscore*, sous-tiret
whitespace caractère d'espacement
========================== ===============================================
Ressources de traduction
========================
- les canaux IRC sur irc.libera.chat :
- `#python-docs-fr <https://web.libera.chat/#python-docs-fr>`_ — communauté python autour de la documentation française,
- `#python-fr <https://web.libera.chat/#python-fr>`_ — communauté python francophone,
- `#python-doc <https://web.libera.chat/#python-doc>`_ — communauté python autour de la documentation anglophone ;
- les listes de diffusion relatives à la documentation (courriel) :
- `de l'AFPy <http://lists.afpy.org/mailman/listinfo/traductions>`_,
- `de CPython <https://mail.python.org/mailman/listinfo/doc-sig>`_ ;
- des glossaires et dictionnaires :
- 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 française 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 ;
- `Petites leçons de typographie <https://jacques-andre.fr/faqtypo/lessons.pdf>`_,
résumé succinct 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 ».
Caractères spéciaux et typographie
==================================
La touche de composition
------------------------
Cette `touche <https://fr.wikipedia.org/wiki/Touche_de_composition>`_,
absente par défaut des claviers, permet de saisir des
caractères spéciaux en combinant les caractères déjà présents sur le
clavier. C'est à l'utilisateur de définir la touche de composition.
Avec une touche de composition, vous pouvez utiliser les
compositions suivantes :
- :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 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 ?
------------------------------------------
Cela dépend de votre système d'exploitation et de votre clavier.
⇒ Sous Linux, Unix et \*BSD (tel OpenBSD), vous pouvez la configurer à l'aide de
l'outil graphique de configuration de votre clavier ou avec
``dpkg-reconfigure keyboard-configuration``
(pour `Ubuntu <https://help.ubuntu.com/community/ComposeKey>`_ ou Debian
et distributions assimilées).
À tout le moins, vous pouvez configurer votre fichier *~/.Xmodmap* pour
ajouter l'équivalent de :
.. code-block:: shell
# key Compose
keycode 115 = Multi_key
Utilisez ``xev`` pour connaître la bonne correspondance de la touche que vous
voulez assigner !
Ensuite, dans votre fichier *~/.xsession*, ajoutez :
.. 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 » →
« Touche composée ». Pour finir, redémarrez votre session.
⇒ Sous Windows, vous
pouvez utiliser `wincompose <https://github.com/SamHocevar/wincompose>`_.
Le cas de « --- », « -- », « ... »
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
La version anglaise utilise les
`smartquotes <http://docutils.sourceforge.net/docs/user/smartquotes.html>`_,
qui fonctionnent en anglais, mais causent des problèmes dans d'autres langues.
Nous les avons donc désactivées (voir #303) dans la version française.
Les *smartquotes* sont normalement responsables de la transformation de
``--`` en *en-dash* (``—``), de ``---`` en *em-dash* (``—``), et de
``...`` en *ellipses* ``…``.
⇒ Si vous voyez :
| « -- » ou « --- » : faites :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`
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,
ils passent ensuite à une moulinette et le rendu des espaces est délégué
au HTML et au PDF, qui n'en tiennent pas compte.
Nous avons décidé de ne rien changer pour les doubles-espaces
coté traduction : nous ne les retirons pas et ce n'est pas grave
si des traducteurs en retirent par accident.
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
espace insécable) quelle que soit sa ponctuation interne. Seul le dernier
paragraphe de l'énumération s'achève par un point ou, si la phrase
continue après l'énumération, une virgule. Si l'un des paragraphes est
lui-même une énumération, chacun des sous-paragraphes se termine par
une virgule et le dernier par un point-virgule.
Par exemple :
- le premier paragraphe de l'énumération ;
- le deuxième paragraphe, lui aussi une énumération :
- premier sous-paragraphe,
- second sous-paragraphe ;
- le dernier paragraphe.
Malheureusement Poedit n'aime pas les différences de ponctuation finales
entre un paragraphe et sa traduction ; il faut passer outre ses avertissements.
Vous pouvez aussi rajouter un commentaire dans le fichier *.po* pour avertir
les traducteurs suivants et éviter qu'ils ne « corrigent » par erreur ces
avertissements.
Migration vers Gitea
====================
En novembre 2022, le dépôt de cette traduction a migré de GitHub à une
instance de Gitea hébergée par l'AFPy. Si vous contribuiez auparavant
sur GitHub, voici comment s'y prendre pour la migration :
- Suivez le guide `plus haut <cloner_>`_ pour faire une bifurcation (*fork*)
du dépôt sur Gitea. De manière facultative mais recommandée, ajoutez
votre clé SSH à votre profil Gitea comme expliqué ci-dessus (vous
aviez probablement une clé sur GitHub, auquel cas il suffit de
réutiliser la même, qui doit se trouver dans le fichier
``~/.ssh/id_ed25519.pub`` ou un nom similaire).
- Exécutez ces deux commandes pour mettre à jour votre dépôt local
afin qu'il interagisse avec Gitea au lieu de GitHub :
.. code-block:: bash
git remote set-url upstream https://git.afpy.org/AFPy/python-docs-fr.git
git remote set-url origin git@git.afpy.org:VOTRE_NOM_DE_COMPTE_GITEA/python-docs-fr.git
Si vous avez choisi d'utiliser le HTTPS à la place du SSH, remplacez
la deuxième ligne par :
.. code-block:: bash
git remote set-url origin https://git.afpy.org/VOTRE_NOM_DE_COMPTE_GITEA/python-docs-fr.git
View Git Blame Copy Permalink