Skip to content

Latest commit

 

History

History
246 lines (146 loc) · 18.1 KB

CONTRIBUTING.md

File metadata and controls

246 lines (146 loc) · 18.1 KB

Οδηγός συνεισφοράς στο πρότζεκτ Python-Docs-Gr της κοινότητας PyGreece

Ευχαριστούμε πολύ για το ενδιαφέρον σας να συμμετέχετε στη μετάφραση των επίσημων εγγράφων της Python στα Ελληνικά!

Το συγκεκριμένο πρότζεκτ έχει ξεκινήσει από το PyGreece, μια online κοινότητα εθελοντών της Python. Στο συγκεκριμένο repository θα βρείτε την ομάδα εργασίας που είναι υπεύθυνη για το πρότζεκτ. Όλο το περιεχόμενο της μετάφρασης συντηρείται από εθελοντές που συνεισφέρουν το χρόνο και την εργασία τους στην κοινότητα της Python.

Σε περίπτωση που έχετε οποιαδήποτε απορία για το πρότζεκτ, μπορείτε να μας βρείτε με τους εξής τρόπους:

Πριν ξεκινήσετε με την πρώτη σας μετάφραση θα θέλαμε να μοιραστούμε κάποιες γενικές οδηγίες.

Περιεχόμενα

Προετοιμασία

Δημιουργία Fork και Ρύθμιση του Repository

Ακολουθήστε τα παρακάτω βήματα για να ρυθμίσετε το περιβάλλον σας. Αυτό είναι απαραίτητο πριν ξεκινήσετε οποιαδήποτε μετάφραση και γίνεται μόνο μία φορά. Σκοπός είναι η δημιουργία ενός προσωπικού αντιγράφου του έργου. Με το συγκεκριμένο fork μπορείτε να κάνετε όσα PR θέλετε.

  1. Για να υποβάλετε μια μετάφραση, πρέπει να έχετε ένα fork του repository, κάνοντας click στο κουμπί fork όπως φαίνεται παρακάτω (για περισσότερες πληροφορίες δείτε εδώ). Αυτό σας επιτρέπει να δημιουργήσετε ένα προσωπικό αντίγραφο του repository για να δουλέψετε και να κάνετε αλλαγές πάνω σε αυτό:

fork

  1. Κάντε clone το repository που μόλις δημιουργήσατε:
git clone --recursive git@github.com:<το username σας>/python-docs-gr.git
  1. Μεταβείτε στον φάκελο που δημιουργήθηκε:
cd python-docs-gr/
  1. Προσθέστε το επίσημο repository ως upstream:
git remote add upstream git@github.com:pygreece/python-docs-gr.git
  1. Προσθέστε το κατάλληλο URL για το upstream repository σας:
git remote set-url --push upstream git@github.com:<your-username>/cpython.git

Χρήση DevContainers με VSCode [Προτεινόμενη]

Προαπαιτούμενα

Ανοίξτε το repository στο VSCode:

code python-docs-gr

Όταν σας ζητηθεί, ανοίξτε το DevContainer κάνοντας click στην επιλογή: "Reopen in Container".

Εναλλακτικές Ρυθμίσεις

  1. Δημιουργήστε ένα virtual environment και κάντε activate:
python -m venv env
source env/bin/activate   # macOS or Linux
env\Scripts\activate.bat  # Windows
  1. Εγκαταστήστε τα requirements:
pip install -r requirements.txt

Συνεισφορά

Έχουμε μια λίστα με issues στο GitHub όπου συντονίζουμε τη δουλειά που γίνεται ή που πρέπει να γίνει ώστε να γίνεται διαχωρισμός αρμοδιοτήτων και διαχείριση της δουλειάς και των απαιτούμενων ενεργειών.

Οι τρόποι συνεισφοράς στο έργο είναι δύο:

Μετάφραση Αρχείου

Μπορείτε να συνεισφέρετε στη μετάφραση ενός αρχείου από αυτά που θα βρείτε στα issues.

Η διαδικασία μετάφρασης ενός αρχείου είναι η εξής:

  • Επιλέξτε οποιοδήποτε από τα Issues που δεν έχουν ανατεθεί σε κάποιο άλλο άτομο.

  • Αφήστε ένα σχόλιο στο Issue λέγοντας ότι θέλετε να συνεισφέρετε, αναλαμβάνοντας το συγκεκριμένο Issue.

  • Περιμένετε έναν διαχειριστή να σας αναθέσει το Issue.

  • Ξεκινήστε τη μετάφραση!

Τα Issues είναι χωρισμένα σε milestones:

To milestone που μπορείτε να συνεισφέρετε είναι το translate_3.12_additional. Άμα είναι η πρώτη σας φορά σε αυτό το έργο ή γενικότερα σε έργο ανοιχτού κώδικα είναι προτιμότερο να αναλάβετε ένα Issue με label good first issue.

Επίσης, για διευκόλυνση, έχουμε κάνει μια κατηγοριοποίηση των Issues με βάση το μέγεθος (γραμμές κώδικα προς μετάφραση). Πιο αναλυτικά:

  • small για αρχεία με λιγότερες από 200 γραμμές
  • medium για αρχεία με λιγότερες από 500 γραμμές
  • large για αρχεία με λιγότερες από 1000 γραμμές
  • xlarge για αρχεία με λιγότερες από 2500 γραμμές
  • god (για τους τολμηρούς) για αρχεία με περισσότερες από 2500 γραμμές

Αξιολόγηση Μετάφρασης

Μπορείτε να συνεισφέρετε κάνοντας μια αξιολόγηση των ήδη μεταφρασμένων αρχείων, για τυχόν παρατηρήσεις, βελτιώσεις, ελλείψεις ή διορθώσεις στη μετάφραση.

Η διαδικασία είναι:

  • Ανοίξτε ένα Issue

    new_issue

  • Γράψτε στην περιγραφή τις παρατηρήσεις σας.

  • Μέσα από τα σχόλια του Issue θα συζητηθεί η παρατήρηση και το σχόλιο σας.

  • Αν από τη συζήτηση προκύψει ότι απαιτείται κάποια αλλαγή, είναι αρεστό να την αναλάβετε εσείς. Κατ' αυτόν τον τρόπο θα κλείσετε το Issue σας με ένα δικό σας PR.

Λερώστε τα χέρια σας! Μεταφράστε!

Εφόσον σας έχει ανατεθεί ένα αρχείο προς μετάφραση, ήρθε η ώρα να λερώσετε τα χέρια σας και να ξεκινήσετε!

Τα αρχεία που πρέπει να μεταφραστούν είναι αυτά με την κατάληξη .po.

Τα εργαλεία που προτείνουμε να χρησιμοποιήσετε είναι το VSCode ή το Poedit. Για το VSCode μια χρήσιμη επέκταση είναι το gettext extension. Αντίθετα, το Poedit χρησιμοποιεί ένα καλύτερο περιβάλλον διεπαφής και δεν απαιτείται να ασχοληθεί ο χρήστης με τη δομή του αρχείου.

  1. Επιβεβαιώστε ότι είστε στο 3.12 branch (πολύ σημαντικό βήμα για να αποφύγετε να ξεκινήσετε ένα branch από παλαιότερη έκδοση):
git checkout 3.12
  1. Δημιουργήστε ένα branch βασισμένο στο αρχείο που θα δουλέψετε. Για παράδειγμα, εάν δουλέυετε στο αρχείο library/ast.po το όνομα του branch θα μπορούσε να είναι:
git checkout -b translate-library-ast

              ή

git checkout -b library-set

              ή

git checkout -b ft/library-set

  1. Αφού έχετε διαλέξει το αρχείο σας, ξεκινήστε τη μετάφραση στο IDE της επιλογής σας. Επίσης, μπορείτε να χρησιμοποιήσετε εργαλεία για τη σωστή μετάφραση προτάσεων, φράσεων ή λέξεων.

  2. Μετά από την ολοκλήρωση της μετάφρασης μην ξεχάσετε να βάλετε τα στοιχεία σας στο:

metadata

Στο Language-Team metadata γράφετε: "Language-Team: PyGreece <pygreece@gmail.com>\n"

  1. Όταν ολοκληρώσετε τη μετάφραση σας, πρέπει να αποθηκεύσετε τις αλλαγές σας και να κάνετε push στο GitHub (Μην ξεχάσετε να προσθέσετε το όνομά σας στο αρχείο TRANSLATORS). Για παράδειγμα, εάν εργαζόσασταν στο αρχείο library/ast.po τα βήματα θα ήταν:
git add library/ast.po
git commit -m 'Translate file library/ast.po'
git push origin translate-library-ast
  1. Έπειτα μπορείτε να ανοίξετε ένα Pull Request προκειμένου να εξεταστεί/ελεγχθεί η συνεισφορά σας, να γίνουν κάποια σχόλια και εν τέλει να προσαρτηθεί στο βασικό repository. Εφόσον έχετε κάνει push το branch σας θα δείτε κάτι όπως παρακάτω:

pr

Πατώντας το κουμπί θα μεταβείτε στην οθόνη για να βάλετε τις πληροφορίες του συγκεκριμένου Pull Request, και κάνοντας click στο κουμπί Create pull request θα δημιουργηθεί το PR.

pr_descrtiption

Μπράβο! Ανεβάσατε το πρώτο σας PR. Τώρα απλώς περιμένετε να το αξιολογήσουν οι διαχειριστές, και έχετε στο νου σας ότι μπορεί να σας ζητήσουν κάποιες αλλαγές.

Περιμένετε να σας κάνουν αποδοχή το PR σας.

🎉🎉ΤΕΛΟΣ🎉🎉

Συγχαρητήρια, συνεισφέρατε στο έργο και πλέον είστε μέλος του μεγάλου εγχειρήματος της μετάφρασης.

Εργαλεία Ελέγχου & Προεπισκόπηση Αλλαγών [Προαιρετικό]

Εφόσον έχετε ολοκληρώσει τη μετάφρασή σας ενδείκνυται να χρησιμοποιήσετε την παρακάτω εντολή προκειμένου να γίνει μορφοποίηση του αρχείου για να έχει μια σωστή δομή καθώς και να γίνει ορθογραφικός έλεγχος.

make lint

Εάν κάποια από τις λέξεις δεν είναι αναγνωρισμένη από το script προσθέστε τη στο dictionary και επαναλάβετε.

Εάν είστε χρήστης των windows μπορείτε να δείτε περισσότερες πληροφορίες εδώ.

Αν θέλετε να κάνετε προεπισκόπηση των αλλαγών που κάνατε μπορείτε να χρησιμοποιήσετε την παρακάτω εντολή:

make preview

Mε την ολοκλήρωση της εντολής, επισκεφτείτε τη διεύθυνση http://localhost:8000/ στον browser σας.

Γενικές Οδηγίες

  • Σε πολλές περιπτώσεις το καλύτερο κριτήριο είναι να σκεφτούμε το λεξιλόγιο που χρησιμοποιούμε όταν εξηγούμε σε άλλο άτομο ή στη δουλειά. Σε πολλές περιπτώσεις, η αγγλική είναι πολύ καλύτερη αν θέλετε πχ. να πείτε "git join".

  • Θα έχετε πάντα διαθέσιμο ένα preview αυτού που προτείνετε, καθώς και reviewers να σας βοηθήσουν.

  • Η διαδικασία του review είναι επίσης πολύ σημαντική. Αν έχετε ελεύθερο χρόνο θα ήταν το ίδιο σημαντικό να συνεισφέρετε κάνοντας review σε ήδη ανοιχτά Pull Requests (περισσότερες πληροφορίες εδώ).

  • Τα επίσημα έγγραφα της Python είναι άπειρα! Αν αντιμετωπίσετε εμπόδια, μπορείτε πάντα να επισημάνετε το κείμενο ως "ασαφές" ή να το αναθεωρήσετε στο μέλλον. Μη σπαταλάτε ώρες αναζητώντας την τέλεια λέξη.

  • Δεν πρέπει να μεταφράσετε το περιεχόμενο των :ref:..., :term:..., :dfn:..., κλπ.

  • Εάν πρέπει να χρησιμοποιήσετε αγγλικές λέξεις, θα πρέπει να τις βάλετε με πλάγιους χαρακτήρες (περιτριγυρισμένοι με αστερίσκους).

  • Μπορείτε να συμβουλευτείτε τις Συχνές Ερωτήσεις για να διαβάσετε για γνωστά ζητήματα.

  • Εάν μεταφράσετε έναν τίτλο που είναι σύνδεσμος, μεταφράστε και τον σύνδεσμο (για παράδειγμα ένα άρθρο στη Wikipedia). Σε περίπτωση που δεν υπάρχει μετάφραση του άρθρου στη Wikipedia, αφήστε τον τίτλο αμετάφραστο.

  • Εάν έχετε μια ερώτηση σχετικά με μια λέξη ή όρο, γράψτε την όπως σας φαίνεται καλύτερα και σημειώστε αυτήν την παράγραφο ως "Needs Work". Επίσης, γράψτε ένα σχόλιο εξηγώντας για ποιον όρο σε αυτήν την παράγραφο δεν ήσασταν σίγουροι.

  • Συνιστούμε να ανοίξετε ένα Pull Request ακόμα κι αν είναι σε μορφή draft (επισημασμένο ως πρόχειρο) από τις πρώτες προσπάθειες της μετάφρασης του αρχείου σας. Με αυτόν τον τρόπο, μπορείτε να λάβετε σχόλια από την αρχή που μπορείτε να εφαρμόσετε στην υπόλοιπη μετάφραση.

  • Τελευταίο αλλά όχι λιγότερο σημαντικό, διασκεδάστε και βασιστείτε στη βοήθεια όλων. Περιμένουμε τα μηνύματα σας στο Discord, εδώ ή στο LinkedIn. Ευχαριστούμε!

  • Για τους contributors που χρησιμοποιούν το VSCode ως IDE ένα πολύ χρήσιμο add-on για τα .po αρχεία είναι το gettext extension.