diff --git a/README.rst b/README.rst index 79e7eb5e..75df73c5 100644 --- a/README.rst +++ b/README.rst @@ -1,12 +1,7 @@ French Translation of the Python Documentation ============================================== -**Translated: 29%** - -See the `README.rst file on master -`_ -for more informations. - +**Translated: 28%** Documentation Contribution Agreement ------------------------------------ @@ -29,3 +24,223 @@ Python community is welcomed and appreciated. You signify acceptance of this agreement by submitting your work to the PSF for inclusion in the documentation. + + +Contributing to the Translation +------------------------------- + +How to Contribute +~~~~~~~~~~~~~~~~~ + +You can either contribute on `transifex/python-doc/public +`_, or by simply openning an +issue on this repository, or by editing the ``po`` files. + +To modify those files you first have to fork this project and follow +github instructions to clone it. + +Next, to edit the files, you can use an editor of your choice, there's many: + +- Highly recommended: `poedit `_ +- gted +- gtranslator +- lokalize +- betterpoeditor +- vim or emacs with an appropriate mode +- Vé on Android +- Probably many others + +Before commiting, you should use `grammalecte +`_ to check for your translations. + +Finally, once your contribution is done, do a ``pull request`` so we +can review and merge it. + +Please write your issues and pull requests in english for consistency +with the python github organization and because non-french people may +receive github notifications about our activity. + + +What to translate +~~~~~~~~~~~~~~~~~ + +You can start with easy tasks like reviewing fuzzy entries to help +keeping the documentation up to date (find them using ``make fuzzy``). + +You can also proofread already translated entries, and finally +translate untranslated ones (find them using ``make todo``).. + +- Do not translate content of ``:ref:...`` and ``:term:...`` +- Put english words, if you have to use them, in *italics* (surrounded + by stars). +- ``::`` at the end of some paragraphs have to be translated to `` : + ::`` in French to place the space before the column. +- If you translate a link title, please translate the link too + (typically if it's Wikipedia and the article has a translation). If + no translation of the target exists, do not translate the + title. + + +Where to get help +~~~~~~~~~~~~~~~~~ + +The coordinator for this translation is `mdk `_. + +Feel free to ask your questions on ``#python-fr`` on `freenode +`_. + + +Translation Resources +--------------------- + +- `Le Grand Dictionnaire Terminologique `_ +- IRC channel `#python-fr `_ on freenode. +- The `liste traductions `_. +- The `doc-sig mailing list + `_. +- `Glossaire traduc.org `_ +- `Glossaires et Dictionnaires of traduc.org + `_ +- `glossary.po `_, as it's + already translated. +- `deepl.com/translator `_ + + +Glossary +-------- + +For consistency in our translations, here are some propositions and +reminders for frequent terms you'll have to translate, don't hesitate +to open an issue if you disagree. + +========================== =========================================== +Term Proposed Translation +========================== =========================================== +-like -compatible +abstract data type type abstrait +argument argument (Don't mix with parameter) +backslash antislash, *backslash* +bound lier +bug bogue, *bug* +built-in native +call stack pile d'appels +debugging débogage +double quote guillemet +e.g. e.g. (pour *exempli gratia*) +garbage collector ramasse-miettes +identifier identifiant +immutable immuable +interpreter interpréteur +library bibliothèque +list comprehension liste en compréhension +little-endian, big-endian `petit-boutiste, gros-boutiste + `_ +mutable muable +namespace *namespace*, espace de noms +parameter paramètre +prompt invite +raise lever +regular expression expression rationnelle, expression régulière +return renvoie, donne (On évite + "retourne" qui pourrait porter à confusion. +simple quote guillemet simple, apostrophe (apostrophe + is to glue, guillemet is to surround) +socket *socket* +statement instruction +thread fil d'exécution +underscore tiret bas, *underscore* +========================== =========================================== + + +Project History +--------------- + +This project was started `around 2012 +`_ +by `afpy `_ members, in 2017 this project +became the official french Python documentation translation thanks to +`PEP 545 `_. + + +Simplify git diffs +------------------ + +Git diffs are often crowded with useless line number changes, like: + + -#: ../Doc/library/signal.rst:406 + +#: ../Doc/library/signal.rst:408 + +To tell git they are not usefull information, you can do the following +after ensuring ``~/.local/bin/`` is in your ``PATH``. + + cat < ~/.local/bin/podiff + #!/bin/sh + grep -v '^#:' "\$1" + EOF + + chmod a+x ~/.local/bin/podiff + + git config diff.podiff.textconv podiff + + +Maintenance +----------- + +All those snippets are to run from the root of a ``python-docs-fr`` +clone, and some expect to find an up-to-date CPython clone near to it, +like:: + + ~/ + ├── python-docs-fr/ + └── cpython/ + +To clone CPython you may use:: + + git clone --depth 1 --no-single-branch https://github.com/python/cpython.git + +This avoids to download the whole history (not usefull to build +documentation) but still fetches all branches. + + +Merge pot files from CPython +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + make merge + + +Find fuzzy strings +~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + make fuzzy + + +Run a test build locally +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + make + + +Synchronize translation with Transifex +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You'll need the ``transifex-client`` and ``poindent`` +from Pypi. + +You'll need to configure ``tx`` via ``tx init`` if not already done. + +You should work on a separate ``transifex`` branch. + +.. code-block:: bash + + tx pull + poindent --modified + git commit -m "tx pull" + git checkout 3.6 + git merge transifex -Xours + tx push -t