diff --git a/.overrides/CONTRIBUTING.rst b/.overrides/CONTRIBUTING.rst index 7faa17a2fc..3354871812 100644 --- a/.overrides/CONTRIBUTING.rst +++ b/.overrides/CONTRIBUTING.rst @@ -4,65 +4,84 @@ Guía para contribuir en la traducción ¡Muchas gracias por tu interés en participar de la traducción de la documentación oficial de Python al Español! Necesitamos *mucho* de tu ayuda para poder seguir adelante con este proyecto. -Actualmente se puede colaborar utilizando una de las dos siguientes formas que: - -#. Utilizando el repositorio de GitHub y el editor poedit_ -#. Realizando traducciones directamente en Transifex - .. note:: Si tienes cualquier duda, puedes enviarnos un email a docs-es@python.org. -Desde GitHub ------------- - #. Crea un fork del repositorio_. .. note:: Puedes consular la `ayuda oficial de GitHub`_, si lo deseas. -#. Clona el repositorio:: +#. Clona el fork del repositorio que acabas de crear:: - git clone git@github.com:/python-docs-es.git + git clone git@github.com:/python-docs-es.git #. Ingresa en la carpeta que `git clone` creó en tu computadora:: - cd python-docs-es/ + cd python-docs-es/ #. Agrega el repositorio original como "upstream":: - git remote add upstream https://github.com/pycampes/python-docs-es.git + git remote add upstream https://github.com/pycampes/python-docs-es.git #. Crea una branch nueva en base al artículo en el que vayas a trabajar. + Por ejemplo, si vas a trabajar en el archivo ``glosario.po``, usa un nombre similar a:: - git checkout -b traduccion_glosario - -#. Mira que archivo necesita ser traducido. El siguiente comando te mostrará una lista de archivos y los porcentajes traducidos. - Elige uno que no esté completo:: - - make progress + git checkout -b traduccion-glosario #. Una vez que hayas elegido el archivo, lo puedes abrir con el editor poedit_ y empezar a traducir. #. Cuando hayas terminado tu sesión, debes guardar tus cambios y enviarlos a GitHub de nuevo:: - git commit -am 'Traducido archivo {nombre de archivo}' - git push origin traduccion_glosario + git commit -am 'Traducido archivo {nombre de archivo}' + git push origin traduccion-glosario -#. No olvides añadir tu nombre al archivo TRANSLATORS si no lo has hecho todavía. +#. No olvides añadir tu nombre al archivo ``TRANSLATORS`` si no lo has hecho todavía. Los nombres se encuentran ordenados alfabéticamente por apellido. -#. Luego ve a tu página de GitHub y propone hacer un Pull Request +#. Luego ve a tu página de GitHub y propone hacer un Pull Request. .. note:: Puedes consultar la `ayuda oficial de GitHub para crear un Pull Request`_ si lo deseas. +¿Qué archivo traducir? +---------------------- + +Tenemos una `lista de issues en GitHub`_ en dónde vamos coordinando el trabajo realizado para no traducir dos veces lo mismo. +El proceso para traducir un archivo es el siguiente: + + +#. Elige cualquier de los que *no están asignados* a otra persona. +#. Deja un comentario en el issue diciendo que quieres trabajar en él. +#. Espera a que un administrador te asigne el issue. +#. ¡Empieza a traducir! + + + +A tener en cuenta +----------------- + +* No debes traducir el contenido de ``:ref:...`` y ``:term:...``. +* Si tienes que palabras en inglés, debes ponerlas en *italics* (rodeadas por asteristicos) +* Si traduces un título que es un link, por favor traduce el link también (por ejemplo un artículo a Wikipedia). + En caso de que no haya una traducción del artículo en Wikipedia, deja el título sin traducir. +* Tenemos una `Memoria de Traducción`_, que usamos para tener consistencia con algunos términos. + + + +.. note:: + + También puedes unirte a `nuestro canal de Telegram`_ si necesitas ayuda. + + + Previsualizar los cambios -~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------- Hay dos formas de visualizar, junto con el resultado final de la documentación, los cambios que has hecho. @@ -70,13 +89,13 @@ Read the Docs ````````````` Una vez que hayas hecho un Pull Request en GitHub, este mostrará al final de página una sección de "check". -Ahí, debería haber uno que diga `docs/readthedocs.org:python-docs-es`, y al lado un link de "Details". +Ahí, debería haber uno que diga ``docs/readthedocs.org:python-docs-es``, y al lado un link de "Details". Haciendo click en ese link, deberías poder ver una versión de la documentación con tus cambios. Construcción local `````````````````` -Desde el mismo directorio `python-docs-es/` que se creó cuando hiciste `git clone`, puedes ejecutar:: +Desde el mismo directorio ``python-docs-es/`` que se creó cuando hiciste ``git clone``, puedes ejecutar:: make build @@ -88,13 +107,11 @@ Puedes ver el con tu navegador de internet (Firefox, Chrome, etc) ejecutando:: Y luego accediendo a http://localhost:8000/ -Utilizando Transifex --------------------- - -ToDo. - - .. _repositorio: https://github.com/PyCampES/python-docs-es .. _ayuda oficial de GitHub: https://help.github.com/es/github/getting-started-with-github/fork-a-repo .. _ayuda oficial de GitHub para crear un Pull Request: https://help.github.com/es/github/collaborating-with-issues-and-pull-requests/about-pull-requests .. _poedit: https://poedit.net/ + +.. _nuestro canal de Telegram: https://t.me/python_docs_es +.. _Memoria de traducción: https://python-docs-es.readthedocs.io/es/3.7/translation-memory.html +.. _lista de issues en GitHub: https://github.com/PyCampES/python-docs-es/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc diff --git a/README.rst b/README.rst index f838de53f6..74b4e747fd 100644 --- a/README.rst +++ b/README.rst @@ -1,8 +1,20 @@ -Translation of the Python Documentation — es -============================================ +Spanish Translation of the Python Documentation +=============================================== .. image:: https://travis-ci.org/raulcd/python-docs-es.svg?branch=3.7 :target: https://travis-ci.org/raulcd/python-docs-es + :alt: Build Status + +.. image:: https://readthedocs.org/projects/python-docs-es/badge/?version=3.7 + :target: https://python-docs-es.readthedocs.io/es/3.7/?badge=3.7 + :alt: Documentation Status + + +How to Contribute +----------------- + +We have a guide that will help you to contribute at: https://python-docs-es.readthedocs.io/es/3.7/CONTRIBUTING.html. +Please, check the details there. Documentation Contribution Agreement @@ -26,276 +38,3 @@ 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 contribute using: - -- Github -- Or just by opening `an issue on github `_ - - -Contributing using Github -~~~~~~~~~~~~~~~~~~~~~~~~~ - -Prerequisites: - -- A `github account `_. -- ``git`` `installed `_ (for windows, see - https://gitforwindows.org/). -- A ``.po`` file editor (Use `poedit `_ - if you don't already have one). - - -Let's start: - -You'll need to fork the `python-docs-es -`_ clicking its ``Fork`` -button. This creates a copy of the whole project on your github -account: a place where you have the rights to do modifications. - -Step by step: - -.. code-block:: bash - - # Git clone your github fork using ssh (replace raulcd): - git clone git@github.com:raulcd/python-docs-es.git - - # Go to the cloned directory: - cd python-docs-es/ - - # Add the upstream (the public repository) using HTTPS (won't ask for password): - git remote add upstream https://github.com/raulcd/python-docs-es.git - -All the translations must be made on the latest release. -We never translate on an oldest version, by example, the latest python release -is python 3.7, we don't want to translate directly on the python 3.5 release. -If needed translations would be backported on the oldest versions by the -`documentation team `. - -Now you're ready to start a work session, each time you'll start a new task, start here: - -.. code-block:: bash - - # To work, we'll need a branch, based on an up-to-date (freshly fetched) - # upstream/3.7 branch, let's say we'll work on glossary so we name - # the branch "glossary": - git fetch upstream - git checkout -b glossary upstream/3.7 - - # You can now work on the file, typically using poedit, - poedit directory/file.po - - # When everything is clear (syntax errors from Sphinx, html rendering, - # semantics, typography), - # you can commit your work with a nice explicit message: - git commit -a -m "Working on glossary." - - # Then push your modifications to your github clone, - # as they are ephemeral branches, let's not configure git to track them all, - # "origin HEAD" is a "special" syntax to say "Push on origin, - # on a branch with the same name as the local one", - # it's nice as it's exactly what we want: - git push origin HEAD - - # The previous command will print you a link to open a PR on github. - # If you missed it, just go to - # https://github.com/raulcd/python-docs-es/ and a nice "Compare & pull request" - # button should appear after a few seconds telling you can ask for a pull request. - - # Now someone is reviewing your modifications, and you'll want to fix their - # findings, get back to your branch - # (in case you started something else on another branch): - git checkout glossary - # Fix the issues, then commit again: - git commit -a -m "glossary: small fixes." - git push origin HEAD - - -You may have noted that this looks like a triangle, with a missing segment: - -- You're fetching from upstream (public common repo on github) -- You're pushing to origin (your clone on github) - -So yes it's the work of someone to add the last segment, from your -origin to the public upstream, to "close the loop", that's the role of -the people who merges pull requests after proofreading them. - -You may also have noted you never ever commit on a version branch -(``3.6``, ``3.7``, ...), only pull from them, consider them read-only -you'll avoid problems. - - -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). -- 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 -~~~~~~~~~~~~~~~~~ - - -Translation Resources ---------------------- - - -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. - -To easily find how a term is already translated in our documentation, -you may use -`find_in_po.py `_. - -========================== =========================================== -Term Proposed Translation -========================== =========================================== --like -abstract data type -argument -backslash -bound -bug -built-in -call stack -debugging -deep copy -double quote -e.g. -garbage collector -identifier -immutable -installer -interpreter -library -list comprehension -little-endian, big-endian -mutable -namespace -parameter -prompt -raise -regular expression -return -simple quote -socket -statement -subprocess -thread -underscore -expression -========================== =========================================== - - -Simplify git diffs ------------------- - -Git diffs are often crowded with useless line number changes, like: - -.. code-block:: diff - - -#: ../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``. - -.. 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 ------------ - -All those snippets are to run from the root of a ``python-docs-es`` -clone, and some expect to find an up-to-date CPython clone near to it, -like: - -.. code-block:: bash - - ~/ - ├── python-docs-es/ - └── cpython/ - -To clone CPython you may use: - -.. code-block:: bash - - 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 ``powrap`` -from Pypi. - -You'll need to configure ``tx`` via ``tx init`` if not already done. - -.. code-block:: bash - - pomerge --from-files **/*.po - tx pull -f - pomerge --to-files **/*.po - pomerge --from-files **/*.po - git checkout -- . - pomerge --to-files **/*.po - powrap --modified - git commit -m "tx pull" - tx push -t -f