← Torna al blog
Terminal window showing a Gemfile entry for the PolyLingo gem alongside a short Ruby translate call and its output hash.

Traduci contenuti strutturati da Ruby con la gemma PolyLingo

By Robert M

Traduci contenuti strutturati da Ruby con la gem PolyLingo

La gem PolyLingo Ruby è ora disponibile su RubyGems. Copre l'intera superficie dell'API PolyLingo: traduzione sincrona, richieste batch, lavori asincroni con polling e tutti gli endpoint di utilità. Non ha dipendenze di runtime e richiede Ruby 2.7 o versioni successive.

Questo post guida attraverso l'installazione, la configurazione del client e ogni metodo disponibile nella gem.

Installazione

Aggiungi al tuo Gemfile:

gem "polylingo"

Poi esegui:

bundle install

Oppure installa direttamente:

gem install polylingo

Nessuna dipendenza di runtime. La gem utilizza solo la libreria standard di Ruby per HTTP.

Configurazione del client

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

Sono disponibili due impostazioni opzionali:

client = PolyLingo.new(
  api_key:  ENV.fetch("POLYLINGO_API_KEY"),
  base_url: "https://api.usepolylingo.com/v1", # default, sovrascrivi per istanze self-hosted
  timeout:  120,                               # secondi (open + read), default 120
)

Tieni la tua chiave API in una variabile d'ambiente. Non inserirla mai hardcoded e non committarla mai nel controllo versione.

Traduzione dei contenuti

Richiesta singola

Passa il tuo contenuto, un array di codici lingua target e un formato opzionale:

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"]

Il parametro format accetta plain, markdown, json o html. Se omesso, l'API rileva automaticamente il formato. Puoi anche passare source come suggerimento di lingua e model come "standard" (default) o "advanced".

La preservazione del formato funziona allo stesso modo del resto dell'API PolyLingo. Per json, vengono tradotti solo i valori stringa e chiavi, annidamenti e tipi non stringa rimangono intatti. Per markdown, le intestazioni rimangono intestazioni e i blocchi di codice sono lasciati verbatim. Per html, tag e attributi sono preservati e solo i nodi di testo sono tradotti.

Traduzione di un file locale 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

Una singola richiesta gestisce tutte e tre le localizzazioni. Le chiavi sono identiche alla sorgente in ogni file di output.

Richieste batch

Invia fino a 100 elementi di contenuto in una singola richiesta, ciascuno con il proprio id e format opzionale:

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

Tutti gli elementi condividono lo stesso array targets. L'id che passi viene preservato nella risposta così puoi mappare i risultati ai dati sorgente senza fare affidamento sull'ordine.

Lavori asincroni

Per traduzioni di lunga durata, l'API lavori accetta la richiesta, restituisce immediatamente un job_id e ti permette di fare polling per il risultato. La gem gestisce questo in due modi.

Metti in coda e fai polling manualmente

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

Una chiamata che fa polling fino al completamento

done = client.jobs.translate(
  content:       File.read("content/long-article.md"),
  targets:       %w[es fr de],
  format:        "markdown",
 
  # Override opzionali (default mostrati):
  poll_interval: 5,    # secondi tra i polling, default 5
  timeout:       1200, # budget totale di attesa in secondi, default 1200 (20 minuti)
  on_progress:   ->(queue_position) { puts "Queue position: #{queue_position.inspect}" }
)
 
translations = done["translations"]
usage        = done["usage"]

Tutti i valori temporali nella gem Ruby usano secondi, coerenti con le convenzioni Ruby. La lambda on_progress viene chiamata ad ogni polling e riceve la posizione corrente in coda come intero, o nil se l'API non la restituisce.

Endpoint di utilità

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 e languages non richiedono chiave API. usage restituisce il consumo di token per il mese solare corrente per l'account autenticato.

Gestione degli errori

Tutti gli errori ereditano da PolyLingo::PolyLingoError. Cattura le sottoclassi specifiche che vuoi gestire:

begin
  result = client.translate(
    content: "# Hello",
    targets: %w[es],
    format:  "markdown"
  )
rescue PolyLingo::AuthError => e
  # HTTP 401 — chiave API non valida, mancante o revocata
  puts "Auth failed: #{e.message}"
rescue PolyLingo::RateLimitError => e
  # HTTP 429 — limite per minuto raggiunto
  retry_after = e.retry_after # secondi interi o nil
  sleep retry_after if retry_after
  retry
rescue PolyLingo::JobFailedError => e
  # Lavoro async ha raggiunto uno stato terminale fallito, o polling scaduto
  puts "Job failed: #{e.job_id}"
rescue PolyLingo::PolyLingoError => e
  # Tutti gli altri errori API
  puts "#{e.status}: #{e.error} — #{e.message}"
end

RateLimitError#retry_after restituisce un intero dal corpo della risposta JSON o dall'intestazione Retry-After, qualunque sia presente, o nil se nessuno è incluso. JobFailedError#job_id ti fornisce l'ID del lavoro fallito quando è noto.

Riferimento rapido

MetodoEndpointAuth richiesta
client.healthGET /healthNo
client.languagesGET /languagesNo
client.translate(...)POST /translateSì
client.batch(...)POST /translate/batchSì
client.usageGET /usageSì
client.jobs.create(...)POST /jobsSì
client.jobs.get(job_id)GET /jobs/:idSì
client.jobs.translate(...)POST /jobs + pollingSì

Inizia

La gem è su RubyGems a rubygems.org/gems/polylingo. Il codice sorgente è su github.com/UsePolyLingo/polylingo-ruby. La documentazione completa dell'API è su usepolylingo.com/docs.

Il piano gratuito include 50.000 token al mese. Nessuna carta di credito richiesta.

gem install polylingo

Ottieni la tua chiave API