Skip to content

Latest commit

 

History

History
148 lines (88 loc) · 11.6 KB

CONTRIBUTING.md

File metadata and controls

148 lines (88 loc) · 11.6 KB
Raw

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

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

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

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

  • Μπορείτε να μπείτε στον discord server του PyGreece (πρόσκληση εδώ: https://discord.gg/evcNPRVCMB)

  • Μπορείτε να μας βρείτε στο linkedin εδώ

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

Βήμα 1: Github Setup

Πρέπει να κάνετε αυτό το βήμα μόνο μία φορά. Με το συγκεκριμένο fork μπορείτε να κάνετε όσα PR θέλετε.

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

fork

  1. Κάντε clone το repository που μόλις δημιουργήσατε:
git clone 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. [Προαιρετικό βήμα] Δημιουργείστε ένα 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

Βήμα 2: Ποια αρχεία πρέπει να μεταφραστούν;

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

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

  • Αφήστε ένα σχόλιο για στο issue λέγοντας ότι θέλετε να το δουλέψετε.

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

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

Σημειώστε πως όλα τα translation issues είναι χωρισμένα σε δύο milestones:

  • Το πρώτο milestone ονομάζεται translate_3.12_mvp και όλα τα issues μέσα σε αυτό είναι τα απαραίτητα ώστε να δημοσιευτεί η μετάφραση.
  • Το δεύτερο milestone ονομαζεται translate_3.12_additional και όλα τα issues μέσα σε αυτό είναι προεαιρετικά.

Ιδανικά θα θέλαμε πρώτα να ολοκληρώσουμε το translate_3.12_mvp milestone και εν συνεχεία να μεταφράσουμε όλα τα issues του translate_3.12_additional.

Βήμα 3: Ξεκινήστε τη μετάφραση!

  1. Διαλέξτε το αρχείο που θέλετε να μεταφράσετε. Το αρχείο θα υπάρχει στον τίτλο του issue που έχετε αναλάβει.

  2. Επιβεβαιώστε ότι είστε στο 3.12 branch (πολύ σημαντικό βήμα για να αποφύγετε να ξεκινήσετε ένα branch απο παλαιότερη έκδοση):

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

  1. Αφού έχετε διαλέξει το αρχείο σας, ξεκινήστε την μετάφραση στο IDE σας. Προτείνουμε το poedit ή το vscode.

  2. Εάν χρησιμοποιείτε το poedit είναι πιθανό πως το αρχείο σας θα έχει σωστό structure, αλλά για παν ενδεχόμενο μπορείτε να το επιβεβαιώσετε με το powrap. Για να το εγκαταστείσετε:

powrap <φακελος>/<ονομα_του_αρχειου>.po

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

  1. Έλεγχος ορθογραφίας: Για να ελέγξετε την ορθοργραφία της μετάφρασης σας μπορείτε να χρησιμοποιείσετε το pospell για να επιβεβαιώσετε ότι όλες οι λέξεις είναι γνωστές ή ανήκουν σε κάποιο από τα dictionaries. Μπορείτε επίσης να χρησιμοποιήσετε το παρακάτω script:
python scripts/check_spelling.py <dir>/<file>.po

Εάν κάποια από τις λέξεις δεν είναι αναγνωρισμένη από το script προσθέστε την στο dictionary και επαναλάβετε. Για παράδειγμα, εάν το αρχείο που δουλεύετε είναι το library/ast.po το αντίστοιχο dictionary είναι το dictionaries/library_ast.txt. Εάν το αρχείο που ψάχνετε δεν υπάρχει στο φάκελο dictionaries δημιουργείστε το.

  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 μπορείτε να γράψετε:
Closes #<αριθμός issue>

Έτσι θα κλείσει και το issue μόλις γίνει merge το PR.

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

  • Σε πολλές περιπτώσεις το καλύτερο κριτήριο είναι να σκεφτούμε το λεξιλόγιο που χρησιμοποιούμε όταν εξηγούμε σε άλλο άτομο ή στη δουλειά. Σε πολλές περιπτώσεις, η αγγλική είναι πολύ καλύτερη αν θελετε πχ. να πείτε "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.