Oversett strukturert innhold fra Ruby med PolyLingo-gem

PolyLingo Ruby-gemet er nå tilgjengelig på RubyGems. Den dekker hele PolyLingo API-overflaten: synkron oversettelse, batch-forespørsler, asynkrone jobber med polling, og alle hjelpeendepunkter. Den har ingen runtime-avhengigheter og krever Ruby 2.7 eller nyere.

Dette innlegget går gjennom installasjon, klientoppsett, og alle metoder som er tilgjengelige i gemet.

Installasjon

Legg til i Gemfile:

gem "polylingo"

Kjør deretter:

bundle install

Eller installer direkte:

gem install polylingo

Ingen runtime-avhengigheter. Gemet bruker kun Rubys standardbibliotek for HTTP.

Sette opp klienten

require "polylingo"

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

To valgfrie innstillinger er tilgjengelige:

client = PolyLingo.new(
  api_key:  ENV.fetch("POLYLINGO_API_KEY"),
  base_url: "https://api.usepolylingo.com/v1", # standard, overstyr for selvhostede instanser
  timeout:  120,                               # sekunder (åpne + lese), standard 120
)

Hold API-nøkkelen din i en miljøvariabel. Aldri hardkod den og aldri legg den i versjonskontroll.

Oversette innhold

Enkelt forespørsel

Send innholdet ditt, en liste med målspråkkoder, og et valgfritt 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"]

Parameteren format godtar plain, markdown, json, eller html. Hvis utelatt, oppdager API-et formatet automatisk. Du kan også sende source som språktips og model som enten "standard" (standard) eller "advanced".

Formatbevaring fungerer på samme måte som resten av PolyLingo API. For json oversettes kun strengverdier, og nøkler, nestinger og ikke-streng-typer forblir urørt. For markdown forblir overskrifter overskrifter og kodeblokker forblir ordrett. For html bevares tagger og attributter, og kun tekstnoder oversettes.

Oversette en JSON locale-fil

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

Én forespørsel håndterer alle tre locale. Nøklene er identiske med kilden i hver utdatafil.

Batch-forespørsler

Send opptil 100 innholdsobjekter i én enkelt forespørsel, hver med sin egen id og valgfritt 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

Alle elementer deler samme targets-array. id-en du sender med beholdes i svaret slik at du kan koble resultater tilbake til kildedata uten å stole på rekkefølge.

Async jobber

For langvarige oversettelser aksepterer job API-et forespørselen, returnerer en job_id umiddelbart, og lar deg poll for resultatet. Gemet håndterer dette på to måter.

Kjø inn i kø og poll manuelt

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

Én kall som poller til ferdig

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

  # Valgfrie overstyringer (standardverdier vist):
  poll_interval: 5,    # sekunder mellom polling, standard 5
  timeout:       1200, # total ventetid i sekunder, standard 1200 (20 minutter)
  on_progress:   ->(queue_position) { puts "Queue position: #{queue_position.inspect}" }
)

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

Alle tidsverdier i Ruby-gemet bruker sekunder, i tråd med Ruby-konvensjoner. on_progress lambdaen kalles ved hver polling og mottar gjeldende køposisjon som et heltall, eller nil hvis API-et ikke returnerer en.

Hjelpeendepunkter

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 og languages krever ingen API-nøkkel. usage returnerer tokenforbruk for inneværende kalendermåned for den autentiserte kontoen.

Feilhåndtering

Alle feil arver fra PolyLingo::PolyLingoError. Fang de spesifikke underklassene du vil håndtere:

begin
  result = client.translate(
    content: "# Hello",
    targets: %w[es],
    format:  "markdown"
  )
rescue PolyLingo::AuthError => e
  # HTTP 401 — ugyldig, manglende eller tilbakekalt API-nøkkel
  puts "Auth failed: #{e.message}"
rescue PolyLingo::RateLimitError => e
  # HTTP 429 — per-minutt grense nådd
  retry_after = e.retry_after # heltall sekunder eller nil
  sleep retry_after if retry_after
  retry
rescue PolyLingo::JobFailedError => e
  # Async jobb nådde en mislykket terminal status, eller polling tidsavbrudd
  puts "Job failed: #{e.job_id}"
rescue PolyLingo::PolyLingoError => e
  # Alle andre API-feil
  puts "#{e.status}: #{e.error} — #{e.message}"
end

RateLimitError#retry_after returnerer et heltall fra enten JSON-responsens kropp eller Retry-After headeren, hvilken som helst som er tilstede, eller nil hvis ingen er inkludert. JobFailedError#job_id gir deg ID-en til den mislykkede jobben når den er kjent.

Rask referanse

Metode	Endepunkt	Auth kreves
`client.health`	GET /health	Nei
`client.languages`	GET /languages	Nei
`client.translate(...)`	POST /translate	Ja
`client.batch(...)`	POST /translate/batch	Ja
`client.usage`	GET /usage	Ja
`client.jobs.create(...)`	POST /jobs	Ja
`client.jobs.get(job_id)`	GET /jobs/:id	Ja
`client.jobs.translate(...)`	POST /jobs + polling	Ja

Kom i gang

Gemet er på RubyGems på rubygems.org/gems/polylingo. Kildekode er på github.com/UsePolyLingo/polylingo-ruby. Full API-dokumentasjon er på usepolylingo.com/docs.

Gratisnivået inkluderer 50 000 tokens per måned. Ingen kredittkort kreves.

gem install polylingo

Få din API-nøkkel