From 960410b69ae7067426f757df425fba01255a43ad Mon Sep 17 00:00:00 2001 From: Julien Palard Date: Thu, 28 Sep 2017 00:45:15 +0200 Subject: [PATCH 01/11] A master branch, to welcome newcomers. --- README.rst | 303 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 303 insertions(+) create mode 100644 README.rst diff --git a/README.rst b/README.rst new file mode 100644 index 000000000..bf7e93da2 --- /dev/null +++ b/README.rst @@ -0,0 +1,303 @@ +This is the French Translation of the Python Documentation +========================================================== + +We currently only translate stable documentation versions. That's why +the master branch is empty. See the 3.6 branch for real content. + + +Documentation Contribution Agreement +------------------------------------ + +NOTE REGARDING THE LICENSE FOR TRANSLATIONS: Python's documentation is +maintained using a global network of volunteers. By posting this +project on Transifex, Github, and other public places, and inviting +you to participate, we are proposing an agreement that you will +provide your improvements to Python's documentation or the translation +of Python's documentation for the PSF's use under the CC0 license +(available at +https://creativecommons.org/publicdomain/zero/1.0/legalcode). In +return, you may publicly claim credit for the portion of the +translation you contributed and if your translation is accepted by the +PSF, you may (but are not required to) submit a patch including an +appropriate annotation in the Misc/ACKS or TRANSLATORS file. Although +nothing in this Documentation Contribution Agreement obligates the PSF +to incorporate your textual contribution, your participation in the +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 + +Finally, once your contribution is done, do a ``pull request`` so we +can review and merge it. + + +What to translate +~~~~~~~~~~~~~~~~~ + +You can start with easy tasks like reviewing fuzzy entries to help +keeping the documentation up to date. You can also proofread already +translated entries, and finally translate untranslated ones. + +- 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. + +You can find files with a few translations missing:: + + for file in library/*; do echo $(msgattrib --untranslated $file | grep ^msgid | sed 1d | wc -l ) $file; done | grep -v ^0 | sort -gr | tail + +Or replace the ``tail`` by a ``head`` to get files with a lot of work. + + +Where to get help +~~~~~~~~~~~~~~~~~ + +The coordinator for this translation is `mdk `_. + +Feel free to ask your questions on ``#python-fr`` on `freenode +`_. + + +Translation Progression +----------------------- + +============ ===== ===== ===== + .. 2.7 3.5 3.6 +============ ===== ===== ===== + about.po 100% 100% 100% + bugs.po 100% 100% 100% + c-api 9% 12% 11% + contents.po 100% 100% 100% +copyright.po 100% 100% 100% +distributing 100% 100% 100% + distutils 32% 33% 33% + extending 21% 24% 24% + faq 29% 33% 32% + glossary.po 85% 100% 100% + howto 7% 6% 6% + install 45% 46% 43% + installing 100% 100% 66% + library 16% 20% 19% + license.po 100% 100% 100% + reference 5% 5% 5% + sphinx.po 100% 100% 100% + tutorial 100% 100% 100% + using 31% 21% 19% + whatsnew 6% 41% 7% + ~total~ 19% 25% 19% +============ ===== ===== ===== + + +Priorities +---------- + +The ``tutorial/`` directory has a high priority as translations aim +for newcomers, then here are files most read in the original version: + +- library/functions.po +- library/stdtypes.po +- library/string.po +- library/re.po +- library/datetime.po +- library/csv.po +- library/os.po +- library/random.po +- library/json.po +- library/subprocess.po + + +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 primitive, native +debugging débogage +double quote guillemet +call stack pile d'appels +e.g. e.g. (pour *exempli gratia*) +garbage collector ramasse-miettes +identifier identifiant +immutable immuable +interpreter interpréteur +library bibliothèque +list compréhension liste en compréhension +little-endian, big-endian `petit-boutiste, gros-boutiste + `_ +mutable variable +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 +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 + + VERSION="$(git describe --contains --all HEAD)" + (cd ../cpython; git checkout $VERSION && git pull --ff-only && sphinx-build -Q -b gettext -D gettext_compact=0 Doc pot/) + find ../cpython/pot/ -name '*.pot' | + while read -r POT + do + PO="./$(echo "$POT" | sed "s#../cpython/pot/##; s#\.pot\$#.po#")" + mkdir -p "$(dirname "$PO")" + if [ -f "$PO" ] + then + msgmerge --backup=off --force-po -U "$PO" "$POT" + else + msgcat -o "$PO" "$POT" + fi + done + + +Find fuzzy strings +~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + find -name '*.po' | xargs -L1 msgattrib --only-fuzzy --no-obsolete + + +Run a test build locally +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + mkdir -p /tmp/$USER/locales/fr + ln -nfs $(readlink -f .) /tmp/$USER/locales/fr/LC_MESSAGES + make -C ../cpython/Doc SPHINXOPTS="-D locale_dirs=/tmp/$USER/locales/ -D language=fr -D gettext_compact=0" autobuild-dev-html + + +Synchronize translation with Transifex +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You'll need the ``transifex-client``, ``pomerge``, and ``poindent`` +from Pypi, and you'll need to configure ``tx`` via ``tx init``, and then: + +.. code-block:: bash + + tx pull + pomerge --from .tx/*.po .tx/**/*.po --to *.po **/*.po + poindent --modified + +Now you should review and commit the pull, then push: + +.. code-block:: bash + + pomerge --from *.po **/*.po --to .tx/*.po .tx/**/*.po + tx push -t From 98273ae72a650301bc827b5caef379f6ff023878 Mon Sep 17 00:00:00 2001 From: Julien Palard Date: Sat, 30 Sep 2017 18:47:54 +0200 Subject: [PATCH 02/11] More readable REAMDE title. --- README.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.rst b/README.rst index bf7e93da2..d50b34abf 100644 --- a/README.rst +++ b/README.rst @@ -1,5 +1,5 @@ -This is the French Translation of the Python Documentation -========================================================== +French Translation of the Python Documentation +============================================== We currently only translate stable documentation versions. That's why the master branch is empty. See the 3.6 branch for real content. From be7a6f99160758b9ad885aa0c3924f3e4773cb5a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20Magimel?= Date: Wed, 4 Oct 2017 22:25:54 +0200 Subject: [PATCH 03/11] Readme: fix the IRC link The link was broken because the scheme was missing. --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index d50b34abf..0215d9093 100644 --- a/README.rst +++ b/README.rst @@ -137,7 +137,7 @@ Translation Resources --------------------- - `Le Grand Dictionnaire Terminologique `_ -- IRC channel `#python-fr `_ on freenode. +- IRC channel `#python-fr `_ on freenode. - The `liste traductions `_. - The `doc-sig mailing list `_. From 73e778b185de53453af72025c1aa6d0879667898 Mon Sep 17 00:00:00 2001 From: Julien Palard Date: Fri, 13 Oct 2017 19:29:24 +0200 Subject: [PATCH 04/11] Remove progression, we're showing a badge per branch. --- README.rst | 30 ------------------------------ 1 file changed, 30 deletions(-) diff --git a/README.rst b/README.rst index 0215d9093..0deac7dfb 100644 --- a/README.rst +++ b/README.rst @@ -85,36 +85,6 @@ Feel free to ask your questions on ``#python-fr`` on `freenode `_. -Translation Progression ------------------------ - -============ ===== ===== ===== - .. 2.7 3.5 3.6 -============ ===== ===== ===== - about.po 100% 100% 100% - bugs.po 100% 100% 100% - c-api 9% 12% 11% - contents.po 100% 100% 100% -copyright.po 100% 100% 100% -distributing 100% 100% 100% - distutils 32% 33% 33% - extending 21% 24% 24% - faq 29% 33% 32% - glossary.po 85% 100% 100% - howto 7% 6% 6% - install 45% 46% 43% - installing 100% 100% 66% - library 16% 20% 19% - license.po 100% 100% 100% - reference 5% 5% 5% - sphinx.po 100% 100% 100% - tutorial 100% 100% 100% - using 31% 21% 19% - whatsnew 6% 41% 7% - ~total~ 19% 25% 19% -============ ===== ===== ===== - - Priorities ---------- From e881f47c83ff3c15304abc9b641fe5c3de664b0a Mon Sep 17 00:00:00 2001 From: Julien Palard Date: Fri, 13 Oct 2017 22:52:55 +0200 Subject: [PATCH 05/11] Dropping bash scripts, as we moved them in a Makefile for non-bash users. --- README.rst | 33 +++++++-------------------------- 1 file changed, 7 insertions(+), 26 deletions(-) diff --git a/README.rst b/README.rst index 0deac7dfb..fa3a479bd 100644 --- a/README.rst +++ b/README.rst @@ -60,8 +60,10 @@ What to translate ~~~~~~~~~~~~~~~~~ You can start with easy tasks like reviewing fuzzy entries to help -keeping the documentation up to date. You can also proofread already -translated entries, and finally translate untranslated ones. +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 @@ -69,12 +71,6 @@ translated entries, and finally translate untranslated ones. - ``::`` at the end of some paragraphs have to be translated to `` : ::`` in French to place the space before the column. -You can find files with a few translations missing:: - - for file in library/*; do echo $(msgattrib --untranslated $file | grep ^msgid | sed 1d | wc -l ) $file; done | grep -v ^0 | sort -gr | tail - -Or replace the ``tail`` by a ``head`` to get files with a lot of work. - Where to get help ~~~~~~~~~~~~~~~~~ @@ -219,20 +215,7 @@ Merge pot files from CPython .. code-block:: bash - VERSION="$(git describe --contains --all HEAD)" - (cd ../cpython; git checkout $VERSION && git pull --ff-only && sphinx-build -Q -b gettext -D gettext_compact=0 Doc pot/) - find ../cpython/pot/ -name '*.pot' | - while read -r POT - do - PO="./$(echo "$POT" | sed "s#../cpython/pot/##; s#\.pot\$#.po#")" - mkdir -p "$(dirname "$PO")" - if [ -f "$PO" ] - then - msgmerge --backup=off --force-po -U "$PO" "$POT" - else - msgcat -o "$PO" "$POT" - fi - done + make merge Find fuzzy strings @@ -240,7 +223,7 @@ Find fuzzy strings .. code-block:: bash - find -name '*.po' | xargs -L1 msgattrib --only-fuzzy --no-obsolete + make fuzzy Run a test build locally @@ -248,9 +231,7 @@ Run a test build locally .. code-block:: bash - mkdir -p /tmp/$USER/locales/fr - ln -nfs $(readlink -f .) /tmp/$USER/locales/fr/LC_MESSAGES - make -C ../cpython/Doc SPHINXOPTS="-D locale_dirs=/tmp/$USER/locales/ -D language=fr -D gettext_compact=0" autobuild-dev-html + make Synchronize translation with Transifex From 1f5ea91aac62ed10261624b61189421d3b1494b1 Mon Sep 17 00:00:00 2001 From: Julien Palard Date: Fri, 13 Oct 2017 22:53:29 +0200 Subject: [PATCH 06/11] Remove now deprecated list of priorities. --- README.rst | 18 ------------------ 1 file changed, 18 deletions(-) diff --git a/README.rst b/README.rst index fa3a479bd..df84d6547 100644 --- a/README.rst +++ b/README.rst @@ -81,24 +81,6 @@ Feel free to ask your questions on ``#python-fr`` on `freenode `_. -Priorities ----------- - -The ``tutorial/`` directory has a high priority as translations aim -for newcomers, then here are files most read in the original version: - -- library/functions.po -- library/stdtypes.po -- library/string.po -- library/re.po -- library/datetime.po -- library/csv.po -- library/os.po -- library/random.po -- library/json.po -- library/subprocess.po - - Translation Resources --------------------- From 7df6c0fe7fac31b833dd6c7acf4698f2007f9b2b Mon Sep 17 00:00:00 2001 From: Julien Palard Date: Fri, 27 Oct 2017 17:44:52 +0200 Subject: [PATCH 07/11] Use *muable* for mutable. See https://github.com/AFPy/python_doc_fr/issues/63 --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index df84d6547..e1d1ed904 100644 --- a/README.rst +++ b/README.rst @@ -126,7 +126,7 @@ library bibliothèque list compréhension liste en compréhension little-endian, big-endian `petit-boutiste, gros-boutiste `_ -mutable variable +mutable muable namespace *namespace*, espace de noms parameter paramètre prompt invite From f6b51e1faa47fd1c4402fb45019038e56fc40434 Mon Sep 17 00:00:00 2001 From: Julien Palard Date: Sun, 12 Nov 2017 20:33:00 +0100 Subject: [PATCH 08/11] Looks like we never use 'primitive'. --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index e1d1ed904..fb8a35d7e 100644 --- a/README.rst +++ b/README.rst @@ -113,7 +113,7 @@ argument argument (Don't mix with parameter) backslash antislash, *backslash* bound lier bug bogue, *bug* -built-in primitive, native +built-in native debugging débogage double quote guillemet call stack pile d'appels From f930bfc09ba2983686dfba575b69cdd52fb17c93 Mon Sep 17 00:00:00 2001 From: Julien Palard Date: Sun, 12 Nov 2017 20:39:18 +0100 Subject: [PATCH 09/11] Guideline about link translation. --- README.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.rst b/README.rst index fb8a35d7e..d907ecf71 100644 --- a/README.rst +++ b/README.rst @@ -70,6 +70,10 @@ translate untranslated ones (find them using ``make todo``).. 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 From 68d2ab597fcad64cd018741eab5a06bd87184266 Mon Sep 17 00:00:00 2001 From: Julien Palard Date: Tue, 14 Nov 2017 10:10:27 +0100 Subject: [PATCH 10/11] Sort glossary. --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index d907ecf71..ccc70393d 100644 --- a/README.rst +++ b/README.rst @@ -118,9 +118,9 @@ backslash antislash, *backslash* bound lier bug bogue, *bug* built-in native +call stack pile d'appels debugging débogage double quote guillemet -call stack pile d'appels e.g. e.g. (pour *exempli gratia*) garbage collector ramasse-miettes identifier identifiant From 8f39a795a0e1e3087309d973ee4517ec3aa2607d Mon Sep 17 00:00:00 2001 From: Julien Palard Date: Tue, 14 Nov 2017 10:12:11 +0100 Subject: [PATCH 11/11] Adding thread to glossary. --- README.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/README.rst b/README.rst index ccc70393d..7ab547779 100644 --- a/README.rst +++ b/README.rst @@ -142,6 +142,7 @@ 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* ========================== ===========================================