Překlad strukturovaného obsahu z Ruby pomocí knihovny PolyLingo

Ruby knihovna PolyLingo je nyní dostupná na RubyGems. Pokrývá celé rozhraní API PolyLingo: synchronní překlad, dávkové požadavky, asynchronní úlohy s pollingem a všechny pomocné koncové body. Nemá žádné runtime závislosti a vyžaduje Ruby 2.7 nebo novější.

Tento příspěvek provází instalací, nastavením klienta a každou metodou dostupnou v knihovně.

Instalace

Přidejte do svého Gemfile:

gem "polylingo"

Poté spusťte:

bundle install

Nebo nainstalujte přímo:

gem install polylingo

Žádné runtime závislosti. Knihovna používá pouze standardní Ruby knihovnu pro HTTP.

Nastavení klienta

require "polylingo"

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

Jsou dostupná dvě volitelná nastavení:

client = PolyLingo.new(
  api_key:  ENV.fetch("POLYLINGO_API_KEY"),
  base_url: "https://api.usepolylingo.com/v1", # výchozí, přepište pro self-hosted instance
  timeout:  120,                               # sekundy (otevření + čtení), výchozí 120
)

Uchovávejte svůj API klíč v proměnné prostředí. Nikdy jej nezakódujte přímo a nikdy jej necommitujte do verzovacího systému.

Překlad obsahu

Jednotlivý požadavek

Předáte svůj obsah, pole cílových jazykových kódů a volitelný formát:

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

Parametr format přijímá plain, markdown, json nebo html. Pokud je vynechán, API formát automaticky detekuje. Můžete také předat source jako jazykovou nápovědu a model buď "standard" (výchozí) nebo "advanced".

Zachování formátu funguje stejně jako zbytek API PolyLingo. Pro json se překládají pouze řetězcové hodnoty, klíče, vnoření a netextové typy zůstávají nedotčeny. Pro markdown zůstávají nadpisy nadpisy a bloky kódu jsou ponechány beze změny. Pro html jsou značky a atributy zachovány a překládají se pouze textové uzly.

Překlad JSON lokalizačního souboru

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

Jeden požadavek zpracuje všechny tři lokalizace. Klíče jsou ve všech výstupních souborech shodné se zdrojem.

Dávkové požadavky

Pošlete až 100 obsahových položek v jednom požadavku, každou se svým id a volitelným 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

Všechny položky sdílejí stejné pole targets. Vámi předané id je zachováno v odpovědi, takže můžete výsledky mapovat zpět na zdrojová data bez spoléhání se na pořadí.

Asynchronní úlohy

Pro dlouhotrvající překlady přijímá jobs API požadavek, okamžitě vrací job_id a umožňuje vám pollovat výsledek. Knihovna to řeší dvěma způsoby.

Zařazení do fronty a manuální 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

Jeden volání, které polluje dokud není hotovo

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

  # Volitelné přepsání (výchozí hodnoty):
  poll_interval: 5,    # sekundy mezi pollováním, výchozí 5
  timeout:       1200, # celkový čas čekání v sekundách, výchozí 1200 (20 minut)
  on_progress:   ->(queue_position) { puts "Queue position: #{queue_position.inspect}" }
)

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

Všechny časové hodnoty v Ruby knihovně jsou v sekundách, v souladu s konvencemi Ruby. Lambda on_progress se spouští při každém pollu a přijímá aktuální pozici ve frontě jako celé číslo, nebo nil, pokud API žádnou nevrátí.

Pomocné koncové body

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 a languages nevyžadují API klíč. usage vrací spotřebu tokenů za aktuální kalendářní měsíc pro autentizovaný účet.

Zpracování chyb

Všechny chyby dědí z PolyLingo::PolyLingoError. Zachyťte konkrétní podtřídy, které chcete zpracovat:

begin
  result = client.translate(
    content: "# Hello",
    targets: %w[es],
    format:  "markdown"
  )
rescue PolyLingo::AuthError => e
  # HTTP 401 — neplatný, chybějící nebo odvolaný API klíč
  puts "Auth failed: #{e.message}"
rescue PolyLingo::RateLimitError => e
  # HTTP 429 — dosažen limit za minutu
  retry_after = e.retry_after # celé sekundy nebo nil
  sleep retry_after if retry_after
  retry
rescue PolyLingo::JobFailedError => e
  # Asynchronní úloha dosáhla chybového stavu nebo vypršel čas pro polling
  puts "Job failed: #{e.job_id}"
rescue PolyLingo::PolyLingoError => e
  # Všechny ostatní chyby API
  puts "#{e.status}: #{e.error} — #{e.message}"
end

RateLimitError#retry_after vrací celé číslo z JSON odpovědi nebo hlavičky Retry-After, podle toho, co je přítomné, nebo nil, pokud není žádné z nich. JobFailedError#job_id vám dává ID neúspěšné úlohy, pokud je známo.

Rychlá reference

Metoda	Endpoint	Vyžaduje autentizaci
`client.health`	GET /health	Ne
`client.languages`	GET /languages	Ne
`client.translate(...)`	POST /translate	Ano
`client.batch(...)`	POST /translate/batch	Ano
`client.usage`	GET /usage	Ano
`client.jobs.create(...)`	POST /jobs	Ano
`client.jobs.get(job_id)`	GET /jobs/:id	Ano
`client.jobs.translate(...)`	POST /jobs + polling	Ano

Začněte

Knihovna je na RubyGems na rubygems.org/gems/polylingo. Zdrojový kód je na github.com/UsePolyLingo/polylingo-ruby. Kompletní dokumentace API je na usepolylingo.com/docs.

Bezplatná úroveň zahrnuje 50 000 tokenů měsíčně. Kreditní karta není potřeba.

gem install polylingo

Získejte svůj API klíč