Υπηρεσία ScriptForge.L10N

Αυτή η υπηρεσία παρέχει έναν αριθμό μεθόδων που σχετίζονται με τη μετάφραση συμβολοσειρών με ελάχιστη επίδραση στον πηγαίο κώδικα του προγράμματος. Οι μέθοδοι που παρέχονται από την υπηρεσία L10N μπορούν να χρησιμοποιηθούν κυρίως για:

• Δημιουργήστε αρχεία POT που μπορούν να χρησιμοποιηθούν ως πρότυπα για τη μετάφραση όλων των συμβολοσειρών του προγράμματος.

• Λάβετε μεταφρασμένες συμβολοσειρές κατά το χρόνο εκτέλεσης για τη γλώσσα που ορίζεται στην ιδιότητα Locale (τοπικές ρυθμίσεις).

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

Τα αρχεία PO έχουν από καιρό προωθηθεί στην κοινότητα του ελεύθερου λογισμικού ως μέσο για την παροχή πολύγλωσσων διεπαφών χρήστη. Αυτό επιτυγχάνεται μέσω της χρήσης αρχείων κειμένου αναγνώσιμων από τον άνθρωπο με μια καλά καθορισμένη δομή που καθορίζει, για οποιαδήποτε δεδομένη γλώσσα, τη συμβολοσειρά της γλώσσας πηγής και την τοπική συμβολοσειρά.

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

Η υπηρεσία L10N βασίζεται στην υλοποίηση GNU αρχείων PO (φορητό αντικείμενο). Για να μάθετε περισσότερα σχετικά με αυτήν τη μορφή αρχείου, επισκεφτείτε τα GNU gettext Utilities: PO Files.

Αυτή η υπηρεσία εφαρμόζει τις μεθόδους που αναφέρονται παρακάτω:

• AddText (Προσθήκη κειμένου): Χρησιμοποιείται από τον προγραμματιστή για τη δημιουργία ενός συνόλου συμβολοσειρών που θα μεταφραστούν αργότερα.

• AddTextsFromDialog: Εξάγει όλες τις συμβολοσειρές από μια παρουσία υπηρεσίας Dialog.

• ExportToPOTFile: Εξάγει τις συμβολοσειρές που προστέθηκαν με τη μέθοδο AddText σε ένα αρχείο POT.

• GetText: Λαμβάνει τις μεταφρασμένες συμβολοσειρές κατά το χρόνο εκτέλεσης.

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

Κλήση υπηρεσίας

Πριν χρησιμοποιήσετε την υπηρεσία L10N πρέπει να φορτωθεί ή να εισαχθεί η βιβλιοθήκη ScriptForge:

• Οι μακροεντολές Basic απαιτούν τη φόρτωση της βιβλιοθήκης ScriptForge χρησιμοποιώντας την ακόλουθη πρόταση:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Τα σενάρια Python απαιτούν εισαγωγή από την ενότητα scriptforge:
από το scriptforge import CreateScriptService

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

CreateScriptService("L10N", opt foldername: str, opt locale: str, encoding: str = "UTF-8", opt locale2: str, encoding2: str = "UTF-8"): svc

foldername (όνομα φακέλου): Ο φάκελος που περιέχει τα αρχεία PO. Πρέπει να εκφράζεται με τη σημειογραφία FileSystem.FileNaming.

locale: Μια συμβολοσειρά με τη μορφή "la-CO" (γλώσσα-ΧΩΡΑ) ή με τη μορφή "la" (γλώσσα) μόνο.

encoding (κωδικοποίηση): Το σύνολο των χαρακτήρων που θα χρησιμοποιηθεί. Η προεπιλεγμένη κωδικοποίηση είναι "UTF-8".

locale2: Μια συμβολοσειρά που καθορίζει την εναλλακτική τοπική ρύθμιση που θα χρησιμοποιηθεί σε περίπτωση που το αρχείο PO που αντιστοιχεί στην τοπική ρύθμιση που ορίζει την παράμετρο locale δεν υπάρχει. Αυτή η παράμετρος εκφράζεται μόνο με τη μορφή "la-CO" (γλώσσα-ΧΩΡΑ) ή "la" (γλώσσα).

encoding2: Το σύνολο χαρακτήρων του εναλλακτικού αρχείου PO που αντιστοιχεί στο όρισμα locale2. Η προεπιλεγμένη κωδικοποίηση είναι "UTF-8".

Για να μάθετε περισσότερα σχετικά με τα ονόματα των συνόλων χαρακτήρων, επισκεφτείτε τη σελίδα Σύνολα χαρακτήρων του IANA. Λάβετε υπόψη ότι το LibreOffice δεν υλοποιεί όλα τα υπάρχοντα σύνολα χαρακτήρων.

Το ακόλουθο παράδειγμα δημιουργεί την υπηρεσία L10N χωρίς προαιρετικά ορίσματα. Αυτό θα ενεργοποιήσει μόνο τις μεθόδους AddText και ExportToPOTFile, οι οποίες είναι χρήσιμες για τη δημιουργία αρχείων POT.

      GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
      Dim myPO As Variant
      Set myPO = CreateScriptService("L10N")
    

Το παρακάτω παράδειγμα καθορίζει τον φάκελο που περιέχει τα αρχεία PO. Επειδή η τοπική ρύθμιση δεν έχει οριστεί, η παρουσία της υπηρεσίας θα χρησιμοποιήσει την τοπική ρύθμιση που έχει οριστεί για τη διεπαφή χρήστη στο LibreOffice, η οποία είναι η ίδια τοπική ρύθμιση που ορίζεται στην ιδιότητα OfficeLocale της υπηρεσίας Πλατφόρμα.

      Set myPO = CreateScriptService("L10N", "C:\myPOFiles")
    

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

Στο παρακάτω παράδειγμα, η τοπική ρύθμιση ορίζεται ρητά ότι είναι Βελγικά Γαλλικά ("fr-BE"), επομένως η υπηρεσία θα φορτώσει το αρχείο "fr-BE.po" από το φάκελο "C:\myPOFiles". Εάν το αρχείο δεν υπάρχει, θα προκύψει σφάλμα.

      Set myPO = CreateScriptService("L10N", "C:\myPOFiles", "fr-BE", "UTF-8")
    

Για την αποφυγή σφαλμάτων, είναι δυνατό να ορίσετε μια προτιμώμενη και μια εναλλακτική τοπική ρύθμιση και κωδικοποίηση. Το παρακάτω παράδειγμα θα προσπαθήσει πρώτα να φορτώσει το αρχείο "fr-BE.po" από τον καθορισμένο φάκελο και εάν δεν υπάρχει, θα φορτωθεί το αρχείο "en-US.po".

      Set myPO = CreateScriptService("L10N", "C:\myPOFiles", "fr-BE", "UTF-8", "en-US", "UTF-8")
    

Τα αρχεία PO πρέπει να ονομάζονται με τη μορφή "la-CO.po" ή "la.po", όπου το "la" αναφέρεται στη γλώσσα και το "CO" είναι η χώρα. Μερικά παραδείγματα είναι: "en-US.po", "fr-BE.po" ή "fr.po".

Συνιστάται η απελευθέρωση πόρων μετά τη χρήση:

      Set myPO = myPO.Dispose()
    

Τα παραπάνω παραδείγματα μπορούν να μεταφραστούν σε Python ως εξής:

      from scriptforge import CreateScriptService
      myPO = CreateScriptService('L10N')
    

      myPO = CreateScriptService('L10N', r'C:\myPOFiles')
    

      myPO = CreateScriptService('L10N', r'C:\myPOFiles', 'fr-BE')
    

      myPO = CreateScriptService('L10N', r'C:\myPOFiles', 'fr-BE', 'UTF-8', 'en-US', 'UTF-8')
      myPO = myPO.Dispose()
    

Μπορεί να συνυπάρχουν πολλές περιπτώσεις της υπηρεσίας L10N. Ωστόσο, κάθε παρουσία πρέπει να χρησιμοποιεί ξεχωριστό κατάλογο για τα αρχεία PO του.

Ιδιότητες

AddText

Προσθέτει μια νέα καταχώρηση στον κατάλογο τοπικών συμβολοσειρών. Δεν πρέπει να υπάρχει ακόμα.

Η μέθοδος επιστρέφει True εάν είναι επιτυχής.

svc.AddText(context: str = '', msgid: str = '', comment: str = ''): bool

context: Το κλειδί για την ανάκτηση της μεταφρασμένης συμβολοσειράς με τη μέθοδο GetText. Αυτή η παράμετρος έχει μια προεπιλεγμένη τιμή "".

msgid: Η αμετάφραστη συμβολοσειρά, η οποία είναι το κείμενο που εμφανίζεται στον κώδικα του προγράμματος. Δεν πρέπει να είναι άδειο. Το msgid γίνεται το κλειδί για την ανάκτηση της μεταφρασμένης συμβολοσειράς μέσω της μεθόδου GetText, όταν το context είναι κενό.

Η συμβολοσειρά msgid μπορεί να περιέχει οποιονδήποτε αριθμό δεσμευτικών θέσης (%1 %2 %3 ...) για δυναμική τροποποίηση της συμβολοσειράς κατά το χρόνο εκτέλεσης.

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

Το παρακάτω παράδειγμα δημιουργεί ένα σύνολο συμβολοσειρών στα Αγγλικά:

      myPO.AddText(, "This is a string to be included in a POT file")
      myPO.AddText("CTX1", "A string with a context")
      myPO.AddText(, "Provide a String value", Comment := "Do not translate the word String")
    

      myPO.AddText(msgid = 'This is a string to be included in a POT file')
      myPO.AddText('CTX1', 'A string with a context')
      myPO.AddText(msgid = 'Provide a String value', comment = 'Do not translate the word String')
    

AddTextsFromDialog

Εξάγει αυτόματα συμβολοσειρές από ένα παράθυρο διαλόγου και τις προσθέτει στον κατάλογο των τοπικών συμβολοσειρών κειμένου. Εξάγονται οι ακόλουθες συμβολοσειρές:

• Ο τίτλος του διαλόγου.

• Η λεζάντα των ακόλουθων τύπων ελέγχου: Button (πλήκτρο), CheckBox (πλαίσιο ελέγχου), FixedLine (σταθερή γραμμή), FixedText (σταθερό κείμενο), GroupBox (πλαίσιο ομάδας)και RadioButton (πλήκτρο επιλογής).

• Στατικές συμβολοσειρές σε πλαίσια καταλόγου και σύνθετα πλαίσια.

• Η συμβουλή οθόνης ή το κείμενο βοήθειας που εμφανίζεται όταν το ποντίκι τοποθετείται πάνω από το στοιχείο ελέγχου.

Η μέθοδος επιστρέφει True εάν είναι επιτυχής.

Το παράθυρο διαλόγου από το οποίο θα εξαχθούν οι συμβολοσειρές δεν πρέπει να είναι ανοιχτό όταν καλείται η μέθοδος.

Όταν δημιουργείται μια παρουσία υπηρεσίας L10N από ένα υπάρχον αρχείο PO, χρησιμοποιήστε τη μέθοδο GetTextsFromL10N από την υπηρεσία Dialog για αυτόματη φόρτωση όλων των μεταφρασμένων συμβολοσειρών στο παράθυρο διαλόγου.

svc.AddTextsFromDialog(dialog: svc): bool

dialog (διάλογος): μια παρουσία υπηρεσίας διαλόγου που αντιστοιχεί στο παράθυρο διαλόγου από το οποίο θα εξαχθούν οι συμβολοσειρές.

Το ακόλουθο παράδειγμα εξάγει όλες τις συμβολοσειρές από το παράθυρο διαλόγου "MyDialog" που είναι αποθηκευμένο στη βιβλιοθήκη "Standard" και τις εξάγει σε ένα αρχείο POT:

      oDlg = CreateScriptService("Dialog", "GlobalScope", "Standard", "MyDialog")
      myPO = CreateScriptService("L10N")
      myPO.AddTextsFromDialog(oDlg)
      myPO.ExportToPOTFile("C:\en-US.pot")
    

      dlg = CreateScriptService("Dialog", "GlobalScope", "Standard", "Dialog1")
      myPO = CreateScriptService("L10N")
      myPO.AddTextsFromDialog(dlg)
      myPO.ExportToPOTFile("C:\en-US.pot")
    

ExportToPOTFile

Εξάγει ένα σύνολο αμετάφραστων συμβολοσειρών ως αρχείο POT.

Για να δημιουργήσετε ένα σύνολο συμβολοσειρών, μπορείτε να χρησιμοποιήσετε είτε μια διαδοχή κλήσεων μεθόδου AddText, είτε με μια επιτυχημένη κλήση της υπηρεσίας L10N με το όρισμα foldername (όνομα φακέλου) παρόν. Είναι επίσης δυνατό να χρησιμοποιηθεί ένας συνδυασμός και των δύο τεχνικών.

Η μέθοδος επιστρέφει True εάν είναι επιτυχής.

svc.ExportToPOTFile(filename: str, header: str = '', encoding:str = 'UTF-8'): bool

filename: Το πλήρες όνομα αρχείου εξόδου στη σημειογραφία FileSystem.FileNaming.

header (κεφαλίδα): Σχόλια που θα προστεθούν επιπλέον του POT που δημιουργήθηκε.

Μην συμπεριλάβετε κανέναν "#" χαρακτήρα στην αρχή. Εάν θέλετε η κεφαλίδα να σπάσει σε πολλές γραμμές, εισαγάγετε τις ακολουθίες διαφυγής (\n) όπου χρειάζεται. Μια τυπική κεφαλίδα θα προστεθεί δίπλα στο κείμενο που καθορίζεται στο όρισμα header.

encoding (κωδικοποίηση): Το σύνολο χαρακτήρων που θα χρησιμοποιηθεί (Προεπιλογή = "UTF-8").

       ' Basic
       myPO.ExportToPOTFile("C:\myFile.pot", Header := "First line of the header\nSecond line of the header")
    

      # Python
      myPO.ExportToPOTFile('C:\myFile.pot', header = 'First line of the header\nSecond line of the header')
    

Το αρχείο που δημιουργήθηκε θα πρέπει να περάσει με επιτυχία την εντολή GNU msgfmt --check.

GetText

Λαμβάνει τη μεταφρασμένη συμβολοσειρά που αντιστοιχεί στο δεδομένο όρισμα msgid.

Μπορεί να καθοριστεί ένας κατάλογος ορισμάτων για να αντικαταστήσει τα δεσμευτικά θέσης (%1, %2, ...) στη συμβολοσειρά.

Εάν δεν βρεθεί μεταφρασμένη συμβολοσειρά, η μέθοδος επιστρέφει τη αμετάφραστη συμβολοσειρά αφού αντικαταστήσει τα δεσμευτικά θέσης με τα καθορισμένα ορίσματα.

Αυτή η μέθοδος μπορεί να καλείται είτε με το πλήρες όνομα GetText, είτε με τη συντόμευση _ (μία μόνο υπογράμμιση):

svc.GetText(msgid: str, args: any[0..*]): str

svc._(msgid: str, args: any[0..*]): str

Στη βιβλιοθήκη ScriptForge, όλες οι μέθοδοι που ξεκινούν με τον χαρακτήρα "_" δεσμεύονται μόνο για εσωτερική χρήση. Ωστόσο, η συντόμευση _ που χρησιμοποιείται για το GetText είναι η μόνη εξαίρεση σε αυτόν τον κανόνα, επομένως μπορεί να χρησιμοποιηθεί με ασφάλεια σε σενάρια Basic και Python.

msgid: Η αμετάφραστη συμβολοσειρά, η οποία είναι το κείμενο που εμφανίζεται στον κώδικα του προγράμματος. Δεν πρέπει να είναι άδειο. Μπορεί να περιέχει οποιονδήποτε αριθμό δεσμευτικών θέσης (%1 %2 %3 ...) που μπορούν να χρησιμοποιηθούν για δυναμική εισαγωγή κειμένου κατά το χρόνο εκτέλεσης.

Εκτός από τη χρήση μιας μόνο συμβολοσειράς msgid, αυτή η μέθοδος δέχεται επίσης τις ακόλουθες μορφές:

• Η συμβολοσειρά context με την οποία η μέθοδος θα ανακτήσει το msgid στο αρχείο PO, ή,

• Ένας συνδυασμός context|msgid, που δίνει οδηγίες στη μέθοδο να ανακτήσει το msgid χρησιμοποιώντας την καθορισμένη τιμή context. Το δεύτερο μέρος του ορίσματος χρησιμοποιείται για τη βελτίωση της αναγνωσιμότητας του κώδικα.

args: Τιμές που θα εισαχθούν στα δεσμευτικά θέσης. Επιτρέπεται οποιοσδήποτε τύπος μεταβλητής, ωστόσο θα ληφθούν υπόψη μόνο συμβολοσειρές, αριθμοί και ημερομηνίες.

Σκεφτείτε ότι ο ακόλουθος κώδικας εκτελείται σε μια εγκατάσταση του LibreOffice με την τοπική ρύθμιση σε "es-ES". Επιπλέον, υπάρχει ένα αρχείο "es-ES.po" μέσα στον καθορισμένο φάκελο που μεταφράζει τη συμβολοσειρά που μεταβιβάστηκε στη μέθοδο GetText:

      myPO = CreateScriptService("L10N", "C:\myPOFiles\")
      myPO.GetText("Welcome %1! Hope you enjoy this program", "John")
      ' "¡Bienvenido John! Espero que disfrutes de este programa"
    

      myPO = CreateScriptService('L10N', r"C:\myPOFiles")
      myPO.GetText('Welcome %1! Hope you enjoy this program', 'John')
      # "¡Bienvenido John! Espero que disfrutes de este programa"
    

Όλες οι ρουτίνες ή αναγνωριστικά του ScriptForge στη Basic που έχουν το πρόθεμα χαρακτήρα υπογράμμισης "_" δεσμεύονται για εσωτερική χρήση. Δεν προορίζονται να χρησιμοποιηθούν σε μακροεντολές Basic ή σενάρια Python.