Προδιαγραφή¶

Μπορείτε να χρησιμοποιήσετε αυτή τη βιβλιοθήκη χωρίς να διαβάσετε αυτή τη σελίδα — η εκμάθηση και ο οδηγός καλύπτουν την καθημερινή χρήση. Αυτή η σελίδα απευθύνεται σε δημιουργούς εργαλείων: η σύμβαση που υλοποιεί η βιβλιοθήκη είναι καταγεγραμμένη ως μικρό, σταθερό συμβόλαιο, ώστε μια άλλη υλοποίηση — ένας εξαγωγέας, ένα IDE, ένας ελεγκτής τύπων ή ένα μελλοντικό pygettext — να μπορεί να το στοχεύσει και να διαλειτουργήσει. Για τους ίδιους κανόνες εξηγημένους μαζί με τους λόγους τους, και για το πώς τους εφαρμόζει η υλοποίηση αναφοράς, διαβάστε πρώτα το Πώς λειτουργεί.

Διαβάστε το spec v1

Οι κανόνες σε μία οθόνη¶

Ένα msgid είναι η συνένωση, με τη σειρά της πηγής, των κυριολεκτικών τμημάτων και ενός διακριτικού {name} ανά παρεμβολή. Τα κυριολεκτικά άγκιστρα διαφεύγουν (το { γίνεται {{). Ένα όνομα πρέπει να είναι απλό όνομα συμβόλου κράτησης θέσης — η str.isidentifier() είναι αληθής και δεν πρόκειται για δεσμευμένη λέξη της Python. Οι μετατροπές και οι προδιαγραφές μορφοποίησης δεν είναι μέρος του msgid· μένουν υπό τον έλεγχο της εφαρμογής.

t-string	msgid
`t"Hello {name}"`	`Hello {name}`
`t"Total: {amount:,.2f}"`	`Total: {amount}`
`t"Config {{raw}} is {value}"`	`Config {{raw}} is {value}`
`t"Hello {user.name}"`	απορρίπτεται — δεν είναι απλό όνομα

Μια μετάφραση είναι έγκυρη όταν περιέχει μόνο γυμνά σύμβολα κράτησης θέσης {name}, κάθε απαιτούμενο όνομα εμφανίζεται τουλάχιστον μία φορά, και δεν εμφανίζεται κανένα όνομα εκτός του επιτρεπτού συνόλου. Η αναδιάταξη και η επανάληψη είναι σκόπιμα χωρίς περιορισμούς: και τα δύο μπορεί να είναι γραμματικά αναγκαία σε μια γλώσσα-στόχο.

Για τους πληθυντικούς, τα επιτρεπτά είναι η ένωση των ονομάτων των κλάδων και τα απαιτούμενα η τομή τους — έτσι το t"One file" απέναντι στο t"{n} files" αφήνει το n διαθέσιμο σε όποιον μεταφράζει οποιαδήποτε από τις δύο μορφές αλλά απαιτούμενο σε καμία, και οι κανόνες πληθυντικού μιας γλώσσας-στόχου μπορούν να διαφέρουν από εκείνους της πηγής.

Ένα κενό msgid δεν αναζητείται ποτέ, γιατί το gettext το δεσμεύει για την κεφαλίδα μεταδεδομένων ενός καταλόγου.

Συμμόρφωση¶

Το conformance/v1.json είναι το ίδιο έγγραφο σε μηχανικά αναγνώσιμη μορφή: περιπτώσεις που αντιστοιχίζουν τη στατική δομή ενός t-string σε ένα msgid, και ένα msgid μαζί με ένα μοτίβο καταλόγου σε μια αποδιδόμενη συμβολοσειρά ή σε μια απόρριψη.

Μια υλοποίηση συμμορφώνεται με το spec v1 όταν αναπαράγει κάθε περίπτωση. Οι περιπτώσεις κατονομάζουν μόνο όσα ορίζει η προδιαγραφή — παραγόμενα msgid, αποδεκτά και απορριπτόμενα μοτίβα, αποδιδόμενη έξοδο — και ποτέ ένα μήνυμα σφάλματος ή έναν τύπο εξαίρεσης, ώστε μια υλοποίηση σε άλλη γλώσσα να μπορεί να τις τρέξει αναλλοίωτες.

Οι παρεμβολές περιγράφονται δομικά, ποτέ ως πηγαίος κώδικας Python:

{
  "spec": "2.2",
  "name": "format spec stays out of the msgid",
  "source": [
    "Total: ",
    {"expression": "amount", "value": 1234.5, "format_spec": ",.2f"}
  ],
  "msgid": "Total: {amount}"
}

Το πεδίο "spec" δεν είναι έκδοση της προδιαγραφής — κάθε περίπτωση στο v1.json ανήκει στην έκδοση v1 της προδιαγραφής. Ονομάζει την ενότητα του SPEC.md που ασκεί η περίπτωση, οπότε το "2.2" διαβάζεται ως §2.2, ο κανόνας παραγωγής ενός διακριτικού συμβόλου κράτησης θέσης.

Η υλοποίηση αναφοράς τρέχει τη σουίτα ως μέρος της δικής της σουίτας δοκιμών, ώστε το κείμενο και ο κώδικας να μην μπορούν να αποκλίνουν σιωπηλά.

Διαχείριση εκδόσεων¶

Αυτό είναι το spec v1. Μια αλλαγή που σπάει τη συμβατότητα προς τα πίσω στην παραγωγή των msgid ή στην επικύρωση των μεταφράσεων αυξάνει την έκδοση και αποστέλλει ένα νέο conformance/vN.json δίπλα στο υπάρχον. Οι προσθετικές διευκρινίσεις που δεν αλλάζουν ούτε τα παραγόμενα msgid ούτε τα αποδεκτά μοτίβα δεν το κάνουν.