← Επιστροφή στο ιστολόγιο
A git diff view showing a locale file with three changed keys highlighted, and only those three keys being sent to the translation API below.

Δεν χρειάζεται να μεταφράσετε ξανά τα πάντα: πώς λειτουργεί η μετάφραση delta στο CI

By Robert M

Δεν χρειάζεται να ξαναμεταφράσετε τα πάντα: πώς λειτουργεί η μετάφραση διαφοράς (delta) στο CI

Μόλις ενσωματώσετε την αυτοματοποιημένη μετάφραση στην CI pipeline σας, προκύπτει γρήγορα ένα φυσικό ερώτημα: μεταφράζεται ολόκληρο το αρχείο τοπικής ρύθμισης κάθε φορά που κάποιος κάνει push μια αλλαγή;

Χωρίς λειτουργία delta, ναι. Κάθε push που επηρεάζει το αρχείο πηγής τοπικής ρύθμισης στέλνει ολόκληρο το αρχείο στο API, κάθε κλειδί, κάθε συμβολοσειρά, είτε έχει αλλάξει είτε όχι. Για ένα μικρό έργο στα αρχικά του στάδια αυτό είναι εντάξει. Για ένα ώριμο έργο με εκατοντάδες κλειδιά μετάφρασης σε 10 ή 20 γλώσσες, καίτε tokens για συμβολοσειρές που δεν έχουν αλλάξει από την τελευταία εκτέλεση και λαμβάνετε ταυτόσημη έξοδο ως αντάλλαγμα.

Η μετάφραση διαφοράς (delta) λύνει αυτό το πρόβλημα. Αντί να στέλνει ολόκληρο το αρχείο, η Action συγκρίνει το τρέχον αρχείο πηγής με μια αποθηκευμένη βάση αναφοράς, εντοπίζει μόνο τα κλειδιά που προστέθηκαν ή τροποποιήθηκαν και στέλνει μόνο αυτά στο API. Η έξοδος για τα αμετάβλητα κλειδιά λαμβάνεται από τα υπάρχοντα μεταφρασμένα αρχεία. Η χρήση tokens μειώνεται ώστε να ταιριάζει με την πραγματική εργασία που γίνεται.

Πώς λειτουργεί η βάση αναφοράς

Όταν η λειτουργία delta εκτελείται για πρώτη φορά ή όταν αναγκάζετε μια πλήρη ανανέωση, η Action μεταφράζει ολόκληρο το αρχείο πηγής και αποθηκεύει μια επίπεδη αναπαράσταση JSON ως αρχείο βάσης αναφοράς στο αποθετήριο σας. Σε επόμενες εκτελέσεις, η Action φορτώνει αυτή τη βάση, τη συγκρίνει με το τρέχον αρχείο πηγής και δημιουργεί ένα payload που περιέχει μόνο τα αλλαγμένα κλειδιά.

Για αρχεία τοπικής ρύθμισης JSON, η βάση αναφοράς αποθηκεύεται ως .polylingo-baseline.json στον φάκελο μηνυμάτων σας. Για αρχεία YAML τοπικής ρύθμισης, είναι .polylingo-yaml-baseline.json στον φάκελο τοπικών ρυθμίσεων. Για αρχεία Laravel PHP lang, είναι .polylingo-laravel-php-baseline.json στον φάκελο lang.

Η βάση αναφοράς δεσμεύεται μαζί με τα μεταφρασμένα αρχεία σας ώστε να ταξιδεύει με το αποθετήριο. Κάθε προγραμματιστής που κλωνοποιεί το repo παίρνει την ίδια βάση αναφοράς από την οποία λειτουργεί η pipeline.

Τι θεωρείται αλλαγή

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

{
  "nav.home": "Αρχική",
  "nav.about": "Σχετικά με εμάς",
  "hero.title": "Καλώς ήρθατε στην πλατφόρμα μας",
  "hero.cta": "Ξεκινήστε"
}

Ένα κλειδί περιλαμβάνεται στο payload διαφοράς αν:

  • Υπάρχει στο τρέχον αρχείο πηγής αλλά όχι στη βάση αναφοράς (νέο κλειδί)
  • Υπάρχει και στα δύο αλλά η τιμή έχει αλλάξει (τροποποιημένο κλειδί)

Κλειδιά που υπάρχουν στη βάση αναφοράς αλλά όχι στο τρέχον αρχείο πηγής (διαγραμμένα κλειδιά) αφαιρούνται αυτόματα από τα μεταφρασμένα αρχεία εξόδου. Κλειδιά που είναι ίδια και στα δύο παραλείπονται εντελώς και οι υπάρχουσες μεταφράσεις τους παραμένουν ανέπαφες.

Πώς φαίνεται αυτό στην πράξη

Ας πούμε ότι έχετε ένα έργο Next.js με 200 κλειδιά μετάφρασης στο messages/en.json, ήδη μεταφρασμένα σε 12 γλώσσες. Ένας προγραμματιστής ενημερώνει το κείμενο στην ενότητα hero και προσθέτει δύο νέα κλειδιά για μια ανακοίνωση λειτουργίας. Αυτό είναι 4 αλλαγμένα κλειδιά από τα 200.

Χωρίς λειτουργία delta, η pipeline στέλνει όλα τα 200 κλειδιά πολλαπλασιασμένα επί 12 γλώσσες σε κάθε push. Με λειτουργία delta στέλνει 4 κλειδιά. Η χρήση tokens για αυτή την εκτέλεση είναι περίπου 2% του κόστους μιας πλήρους μετάφρασης. Η pipeline είναι επίσης ταχύτερη επειδή υπάρχει λιγότερο να σταλεί και λιγότερο να περιμένει.

Σε ένα μήνα τακτικής ανάπτυξης, η εξοικονόμηση συσσωρεύεται σημαντικά. Τα περισσότερα push αφορούν λίγες συμβολοσειρές. Η πλήρης επανεξαγωγή συμβαίνει μόνο όταν προσθέτετε μια νέα γλώσσα ή επαναφέρετε ρητά τη βάση αναφοράς.

Οι τρεις PolyLingo GitHub Actions

Η λειτουργία delta είναι διαθέσιμη και στους τρεις PolyLingo μεταφραστικούς Actions. Κάθε ένας είναι κατασκευασμένος για συγκεκριμένο τύπο περιεχομένου και δομή έργου.

translateAction — JSON και Markdown

Η αρχική Action. Διαχειρίζεται επίπεδα αρχεία τοπικής ρύθμισης JSON στο στυλ next-intl και i18next, με προαιρετική επεξεργασία τεκμηρίωσης Markdown μέσω του async jobs API για μεγαλύτερα αρχεία.

- uses: UsePolyLingo/translate-action@v1
  with:
    api_key: ${{ secrets.POLYLINGO_API_KEY }}
    source_file: messages/en.json
    locales: fr,de,es,ja,zh
    delta: true
    commit: true
    commit_message: "chore(i18n): sync translations"

Βάση delta: messages/.polylingo-baseline.json

github.com/UsePolyLingo/translateAction — Προβολή στο Marketplace

translate-action-yaml — Αρχεία τοπικής ρύθμισης YAML

Για έργα που χρησιμοποιούν εμφωλευμένα αρχεία τοπικής ρύθμισης YAML: Rails i18n, Vue i18n και οποιοδήποτε άλλο πλαίσιο που χρησιμοποιεί τη μορφή YAML. Η Action χειρίζεται αυτόματα τη σύμβαση Rails με ριζικό κλειδί τοπικής ρύθμισης — το en.yml έχει ριζικό κλειδί en:, και κάθε αρχείο εξόδου παίρνει το σωστό κλειδί γλώσσας στόχου (fr:, de: κ.λπ.).

Επειδή το API PolyLingo λειτουργεί εγγενώς με JSON, η Action επίπεδωνει το εμφωλευμένο YAML σε JSON με σημειογραφία τελείας πριν το στείλει, το μεταφράζει και μετά ανακατασκευάζει τη δομή και γράφει έγκυρη έξοδο YAML. Μια προειδοποίηση για την έκδοση v1: κλειδιά που περιέχουν τελείες φυσικά δεν υποστηρίζονται, καθώς συγκρούονται με την επίπεδωση σημειογραφίας τελείας.

- uses: UsePolyLingo/translate-action-yaml@v1
  with:
    api_key: ${{ secrets.POLYLINGO_API_KEY }}
    locales_dir: config/locales
    source_file: config/locales/en.yml
    locales: fr,de,es,ja
    delta: true
    commit: true

Βάση delta: config/locales/.polylingo-yaml-baseline.json

github.com/UsePolyLingo/translate-action-yaml — Προβολή στο Marketplace

translate-action-laravel — Αρχεία lang Laravel

Για έργα Laravel που χρησιμοποιούν είτε αρχεία μετάφρασης JSON (lang/en.json, υποστηρίζοντας τόσο εμφωλευμένες όσο και επίπεδες δομές στο στυλ Laravel 9+) είτε αρχεία PHP array lang (lang/en/*.php). Η Action ανιχνεύει αυτόματα ποια μορφή χρησιμοποιεί το έργο σας μέσω php_format: auto — ελέγχει πρώτα για lang/en.json και αν δεν βρεθεί, επιστρέφει σε αρχεία PHP array.

Για αρχεία PHP, εκτελεί την PHP CLI για να διαβάσει τα αρχεία πηγής και σειριοποιεί την μεταφρασμένη έξοδο πίσω σε έγκυρη σύνταξη PHP array σε JavaScript, χωρίς επιπλέον εξαρτήσεις. Οι runners ubuntu-latest που φιλοξενούνται στο GitHub περιλαμβάνουν PHP 8.x από προεπιλογή, οπότε δεν απαιτείται επιπλέον βήμα εγκατάστασης. Απαιτείται PHP 7.4 ή νεότερη.

Μια προειδοποίηση για την έκδοση v1: κλειδιά που περιέχουν τελείες δεν υποστηρίζονται σε λειτουργία PHP λόγω της στρατηγικής επίπεδωσης σημειογραφίας τελείας.

- uses: UsePolyLingo/translate-action-laravel@v1
  with:
    api_key: ${{ secrets.POLYLINGO_API_KEY }}
    lang_dir: lang
    source_locale: en
    locales: fr,de,es,pt,nl
    php_format: auto
    delta: true
    open_pr: true

Βάση delta: lang/.polylingo-laravel-json-baseline.json ή lang/.polylingo-laravel-php-baseline.json ανάλογα με τη μορφή.

github.com/UsePolyLingo/translate-action-laravel — Προβολή στο Marketplace

Λειτουργία PR έναντι λειτουργίας commit

Και οι τρεις Actions υποστηρίζουν δύο τρόπους εξόδου.

Λειτουργία commit (commit: true) γράφει τα μεταφρασμένα αρχεία και τα δεσμεύει απευθείας στο τρέχον branch. Απλή ρύθμιση, κατάλληλη για ομάδες που θεωρούν τη μετάφραση ως αυτοματοποιημένη διαδικασία που δεν χρειάζεται έλεγχο.

Λειτουργία PR (open_pr: true) δημιουργεί ένα νέο branch (polylingo/yaml-<sha>, polylingo/laravel-<sha> κ.λπ.), γράφει εκεί τα μεταφρασμένα αρχεία και ανοίγει ένα pull request προς το βασικό σας branch. Καλύτερο για ομάδες που θέλουν ανθρώπινο έλεγχο πριν συγχωνευτεί το μεταφρασμένο περιεχόμενο ή για έργα όπου η ποιότητα της μετάφρασης επηρεάζει άμεσα την εμπειρία χρήστη.

Όταν και τα δύο είναι ενεργοποιημένα, υπερισχύει η λειτουργία PR.

Η λειτουργία PR απαιτεί pull-requests: write στα δικαιώματα του workflow σας:

permissions:
  contents: write
  pull-requests: write

Εξαναγκασμός πλήρους ανανέωσης

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

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

- uses: UsePolyLingo/translate-action-yaml@v1
  with:
    api_key: ${{ secrets.POLYLINGO_API_KEY }}
    locales_dir: config/locales
    locales: fr,de,es,ja,zh,ko,ar
    delta: false  # πλήρης ανανέωση, ενημερώνει τη βάση
    commit: true

Εξαγωγές για επόμενα βήματα

Και οι τρεις Actions εκθέτουν τις ίδιες εξαγωγές ώστε να μπορείτε να τις χρησιμοποιήσετε σε επόμενα βήματα του workflow:

- uses: UsePolyLingo/translate-action@v1
  id: translate
  with:
    api_key: ${{ secrets.POLYLINGO_API_KEY }}
    source_file: messages/en.json
    locales: fr,de,es
    delta: true
    commit: true

- name: Καταγραφή στατιστικών μετάφρασης
  run: |
    echo "Μεταφρασμένες γλώσσες: ${{ steps.translate.outputs.locales_translated }}"
    echo "Αρχεία που άλλαξαν: ${{ steps.translate.outputs.files_changed }}"
    echo "Χρησιμοποιημένα tokens: ${{ steps.translate.outputs.tokens_used }}"

Κάθε εκτέλεση γράφει επίσης έναν πίνακα σύνοψης στο βήμα σύνοψης των GitHub Actions, ώστε να μπορείτε να δείτε τη χρήση tokens και τα αποτελέσματα μετάφρασης χωρίς να ψάχνετε στα logs.

Ξεκινώντας

Και οι τρεις Actions είναι διαθέσιμοι στο GitHub Marketplace. Θα χρειαστείτε ένα κλειδί API PolyLingo, διαθέσιμο δωρεάν στο usepolylingo.com. Το δωρεάν επίπεδο περιλαμβάνει 50.000 tokens ανά μήνα. Με ενεργοποιημένη τη λειτουργία delta, τα περισσότερα έργα θα παραμείνουν άνετα εντός αυτού κατά τις τακτικές αναπτύξεις.

Προσθέστε το κλειδί API σας ως μυστικό αποθετηρίου (POLYLINGO_API_KEY) και ενσωματώστε την αντίστοιχη Action στο workflow σας. Η πρώτη εκτέλεση κάνει πλήρη μετάφραση και ορίζει τη βάση. Κάθε επόμενη εκτέλεση μεταφράζει μόνο ό,τι άλλαξε.