Μετάφραση δομημένου περιεχομένου από Ruby με το PolyLingo gem

Το PolyLingo Ruby gem είναι πλέον διαθέσιμο στο RubyGems. Καλύπτει ολόκληρη την επιφάνεια της PolyLingo API: συγχρονισμένη μετάφραση, παρτίδες αιτημάτων, ασύγχρονα jobs με polling και όλα τα βοηθητικά endpoints. Δεν έχει εξαρτήσεις χρόνου εκτέλεσης και απαιτεί Ruby 2.7 ή νεότερη.

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

---

Εγκατάσταση

Προσθέστε στο Gemfile σας:

gem "polylingo"

Έπειτα τρέξτε:

bundle install

Ή εγκαταστήστε απευθείας:

gem install polylingo

Δεν υπάρχουν εξαρτήσεις χρόνου εκτέλεσης. Το gem χρησιμοποιεί μόνο τη βασική βιβλιοθήκη Ruby για HTTP.

---

Ρύθμιση του πελάτη

require "polylingo"

client = PolyLingo.new(api_key: ENV.fetch("POLYLINGO_API_KEY"))

Διατίθενται δύο προαιρετικές ρυθμίσεις:

client = PolyLingo.new(
  api_key:  ENV.fetch("POLYLINGO_API_KEY"),
  base_url: "https://api.usepolylingo.com/v1", # προεπιλογή, παρακαμφθεί για αυτο-φιλοξενούμενες περιπτώσεις
  timeout:  120,                               # δευτερόλεπτα (άνοιγμα + ανάγνωση), προεπιλογή 120
)

Κρατήστε το κλειδί API σε μια μεταβλητή περιβάλλοντος. Ποτέ μην το σκληροκωδικοποιείτε και μην το δεσμεύετε σε σύστημα ελέγχου εκδόσεων.

---

Μετάφραση περιεχομένου

Μονή αίτηση

Περάστε το περιεχόμενό σας, έναν πίνακα με κωδικούς γλωσσών στόχου και ένα προαιρετικό format:

result = client.translate(
  content: "# Hello\n\nThis is **structured** content.",
  targets: %w[es fr de],
  format:  "markdown"
)

puts result["translations"]["es"]
puts result["usage"]["total_tokens"]

Η παράμετρος format δέχεται plain, markdown, json ή html. Αν παραληφθεί, η API ανιχνεύει αυτόματα το format. Μπορείτε επίσης να περάσετε source ως υπόδειξη γλώσσας και model είτε ως "standard" (προεπιλογή) είτε ως "advanced".

Η διατήρηση του format λειτουργεί όπως και το υπόλοιπο της PolyLingo API. Για json, μεταφράζονται μόνο οι τιμές συμβολοσειρών και τα κλειδιά, η εμφωλευμένη δομή και οι μη-συμβολοσειρές τύποι παραμένουν ανέπαφα. Για markdown, οι επικεφαλίδες παραμένουν επικεφαλίδες και τα μπλοκ κώδικα παραμένουν αυτούσια. Για html, οι ετικέτες και τα attributes διατηρούνται και μόνο οι κόμβοι κειμένου μεταφράζονται.

Μετάφραση αρχείου JSON τοπικής γλώσσας

require "json"

source = JSON.parse(File.read("config/locales/en.yml"))

result = client.translate(
  content: source.to_json,
  format:  "json",
  targets: %w[fr de ja]
)

%w[fr de ja].each do |locale|
  translated = JSON.parse(result["translations"][locale])
  File.write(
    "config/locales/#{locale}.json",
    JSON.pretty_generate(translated)
  )
  puts "Wrote config/locales/#{locale}.json"
end

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

---

Αιτήσεις παρτίδας

Στείλτε έως 100 αντικείμενα περιεχομένου σε μία αίτηση, το καθένα με το δικό του id και προαιρετικό format:

result = client.batch(
  items: [
    { id: "hero_title",    content: "Welcome back",   format: "plain" },
    { id: "hero_subtitle", content: "Here is what changed today", format: "plain" },
    { id: "cta",           content: "Get started",    format: "plain" },
  ],
  targets: %w[es fr de]
)

result["results"].each do |row|
  puts "#{row["id"]}: #{row["translations"]["es"]}"
end

Όλα τα αντικείμενα μοιράζονται τον ίδιο πίνακα targets. Το id που περνάτε διατηρείται στην απάντηση ώστε να μπορείτε να αντιστοιχίσετε τα αποτελέσματα πίσω στα δεδομένα πηγής χωρίς να βασίζεστε στη σειρά.

---

Ασύγχρονα jobs

Για μεταφράσεις μεγάλης διάρκειας, η API jobs δέχεται το αίτημα, επιστρέφει αμέσως ένα job_id και σας επιτρέπει να κάνετε polling για το αποτέλεσμα. Το gem το χειρίζεται με δύο τρόπους.

Εισαγωγή στην ουρά και χειροκίνητο polling

accepted = client.jobs.create(
  content: File.read("content/long-article.md"),
  targets: %w[es fr de ja zh],
  format:  "markdown"
)

job_id = accepted["job_id"]

loop do
  sleep 5
  state = client.jobs.get(job_id)
  break if %w[complete failed].include?(state["status"])
end

if state["status"] == "complete"
  translations = state["translations"]
end

Μία κλήση που κάνει polling μέχρι να ολοκληρωθεί

done = client.jobs.translate(
  content:       File.read("content/long-article.md"),
  targets:       %w[es fr de],
  format:        "markdown",

  # Προαιρετικές παρακάμψεις (εμφανίζονται οι προεπιλογές):
  poll_interval: 5,    # δευτερόλεπτα μεταξύ των polls, προεπιλογή 5
  timeout:       1200, # συνολικός χρόνος αναμονής σε δευτερόλεπτα, προεπιλογή 1200 (20 λεπτά)
  on_progress:   ->(queue_position) { puts "Queue position: #{queue_position.inspect}" }
)

translations = done["translations"]
usage        = done["usage"]

Όλες οι χρονικές τιμές στο Ruby gem χρησιμοποιούν δευτερόλεπτα, σύμφωνα με τις συμβάσεις Ruby. Η συνάρτηση on_progress εκτελείται σε κάθε polling και λαμβάνει τη θέση στην ουρά ως ακέραιο ή nil αν η API δεν επιστρέφει κάποια.

---

Βοηθητικά endpoints

health    = client.health
# => { "status" => "ok", "timestamp" => "..." }

languages = client.languages
# => { "languages" => [{ "code" => "en", "name" => "English", "rtl" => false }, ...] }

usage     = client.usage
# => { "usage" => { "tokens_used" => 12000, "tokens_remaining" => 38000, ... } }

Τα health και languages δεν απαιτούν κλειδί API. Το usage επιστρέφει την κατανάλωση tokens για τον τρέχοντα ημερολογιακό μήνα για τον πιστοποιημένο λογαριασμό.

---

Διαχείριση σφαλμάτων

Όλα τα σφάλματα κληρονομούν από PolyLingo::PolyLingoError. Πιάστε τις συγκεκριμένες υποκλάσεις που θέλετε να χειριστείτε:

begin
  result = client.translate(
    content: "# Hello",
    targets: %w[es],
    format:  "markdown"
  )
rescue PolyLingo::AuthError => e
  # HTTP 401 — άκυρο, λείπει ή ανακληθέν κλειδί API
  puts "Auth failed: #{e.message}"
rescue PolyLingo::RateLimitError => e
  # HTTP 429 — όριο ανά λεπτό επιτεύχθηκε
  retry_after = e.retry_after # ακέραια δευτερόλεπτα ή nil
  sleep retry_after if retry_after
  retry
rescue PolyLingo::JobFailedError => e
  # Ασύγχρονο job έφτασε σε αποτυχημένη τελική κατάσταση ή το polling έληξε
  puts "Job failed: #{e.job_id}"
rescue PolyLingo::PolyLingoError => e
  # Όλα τα άλλα σφάλματα API
  puts "#{e.status}: #{e.error} — #{e.message}"
end

Το RateLimitError#retry_after επιστρέφει έναν ακέραιο από το σώμα της JSON απόκρισης ή από την κεφαλίδα Retry-After, όποιο υπάρχει, ή nil αν κανένα δεν περιλαμβάνεται. Το JobFailedError#job_id σας δίνει το ID του αποτυχημένου job όταν είναι γνωστό.

---

Γρήγορη αναφορά

Μέθοδος	Endpoint	Απαιτείται Auth
client.health	GET /health	Όχι
client.languages	GET /languages	Όχι
client.translate(...)	POST /translate	Ναι
client.batch(...)	POST /translate/batch	Ναι
client.usage	GET /usage	Ναι
client.jobs.create(...)	POST /jobs	Ναι
client.jobs.get(job_id)	GET /jobs/:id	Ναι
client.jobs.translate(...)	POST /jobs + polling	Ναι

---

Ξεκινήστε

Το gem είναι στο RubyGems στο rubygems.org/gems/polylingo. Ο πηγαίος κώδικας είναι στο github.com/UsePolyLingo/polylingo-ruby. Η πλήρης τεκμηρίωση API είναι στο usepolylingo.com/docs.

Το δωρεάν επίπεδο περιλαμβάνει 50.000 tokens το μήνα. Δεν απαιτείται πιστωτική κάρτα.

gem install polylingo

Αποκτήστε το κλειδί API σας