← Tilbage til bloggen
Terminal window showing a Gemfile entry for the PolyLingo gem alongside a short Ruby translate call and its output hash.

Oversæt struktureret indhold fra Ruby med PolyLingo-gem

By Robert M

Oversæt struktureret indhold fra Ruby med PolyLingo-gem

PolyLingo Ruby-gem er nu tilgængelig på RubyGems. Den dækker hele PolyLingo API-overfladen: synkron oversættelse, batch-forespørgsler, asynkrone jobs med polling og alle hjælpeendpoints. Den har ingen runtime-afhængigheder og kræver Ruby 2.7 eller nyere.

Dette indlæg gennemgår installation, klientopsætning og alle metoder, der er tilgængelige i gem'en.

Installation

Tilføj til din Gemfile:

gem "polylingo"

Kør derefter:

bundle install

Eller installer direkte:

gem install polylingo

Ingen runtime-afhængigheder. Gem'en bruger kun Rubys standardbibliotek til HTTP.

Opsætning af klienten

require "polylingo"

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

To valgfrie indstillinger er tilgængelige:

client = PolyLingo.new(
  api_key:  ENV.fetch("POLYLINGO_API_KEY"),
  base_url: "https://api.usepolylingo.com/v1", # standard, overskriv for selvhostede instanser
  timeout:  120,                               # sekunder (åbning + læsning), standard 120
)

Opbevar din API-nøgle i en miljøvariabel. Hardkod den aldrig og commit den aldrig til versionskontrol.

Oversættelse af indhold

Enkelt forespørgsel

Send dit indhold, et array af mål-sprogkoder og et valgfrit 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 accepterer plain, markdown, json eller html. Hvis den udelades, registrerer API'et formatet automatisk. Du kan også sende source som et sprog-hint og model som enten "standard" (standard) eller "advanced".

Formatbevarelse fungerer på samme måde som resten af PolyLingo API'et. For json oversættes kun strengværdier, og nøgler, indlejring og ikke-streng-typer forbliver uberørte. For markdown forbliver overskrifter overskrifter, og kodeblokke bevares ordret. For html bevares tags og attributter, og kun tekstnoder oversættes.

Oversættelse af en JSON lokalefil

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

En enkelt forespørgsel håndterer alle tre lokaliteter. Nøglerne er identiske med kilden i hver outputfil.

Batch-forespørgsler

Send op til 100 indholdselementer i en enkelt forespørgsel, hver med sit eget id og valgfrit 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 det samme targets-array. Det id, du sender med, bevares i svaret, så du kan matche resultaterne tilbage til dine kildedata uden at stole på rækkefølgen.

Asynkrone jobs

For langvarige oversættelser accepterer jobs-API'et forespørgslen, returnerer straks et job_id og lader dig poll'e efter resultatet. Gem'en håndterer dette på to måder.

Sæt 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

Ét kald, der poller indtil færdigt

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

  # Valgfrie overskrivninger (standardværdier vist):
  poll_interval: 5,    # sekunder mellem polls, standard 5
  timeout:       1200, # samlet ventetid i sekunder, standard 1200 (20 minutter)
  on_progress:   ->(queue_position) { puts "Queue position: #{queue_position.inspect}" }
)

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

Alle tidsværdier i Ruby-gem'en bruger sekunder, i overensstemmelse med Ruby-konventioner. on_progress lambdaen affyres ved hver polling og modtager den aktuelle køposition som et heltal, eller nil hvis API'et ikke returnerer en.

Hjælpeendpoints

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 kræver ikke API-nøgle. usage returnerer tokenforbrug for den aktuelle kalender måned for den autentificerede konto.

Fejlhåndtering

Alle fejl nedarver fra PolyLingo::PolyLingoError. Fang de specifikke underklasser, du vil håndtere:

begin
  result = client.translate(
    content: "# Hello",
    targets: %w[es],
    format:  "markdown"
  )
rescue PolyLingo::AuthError => e
  # HTTP 401 — ugyldig, manglende eller tilbagekaldt API-nøgle
  puts "Auth failed: #{e.message}"
rescue PolyLingo::RateLimitError => e
  # HTTP 429 — minutgrænse nået
  retry_after = e.retry_after # heltal i sekunder eller nil
  sleep retry_after if retry_after
  retry
rescue PolyLingo::JobFailedError => e
  # Async job nåede en fejlet terminal status, eller polling timeout
  puts "Job failed: #{e.job_id}"
rescue PolyLingo::PolyLingoError => e
  # Alle andre API-fejl
  puts "#{e.status}: #{e.error} — #{e.message}"
end

RateLimitError#retry_after returnerer et heltal fra enten JSON-responsens krop eller Retry-After headeren, alt efter hvad der er til stede, eller nil hvis ingen af delene er inkluderet. JobFailedError#job_id giver dig ID'et på det fejlede job, når det er kendt.

Hurtig reference

MetodeEndpointKræver autentificering
client.healthGET /healthNej
client.languagesGET /languagesNej
client.translate(...)POST /translateJa
client.batch(...)POST /translate/batchJa
client.usageGET /usageJa
client.jobs.create(...)POST /jobsJa
client.jobs.get(job_id)GET /jobs/:idJa
client.jobs.translate(...)POST /jobs + pollingJa

Kom godt i gang

Gem'en findes på RubyGems på rubygems.org/gems/polylingo. Kildekoden findes på github.com/UsePolyLingo/polylingo-ruby. Fuld API-dokumentation findes på usepolylingo.com/docs.

Gratis niveau inkluderer 50.000 tokens pr. måned. Ingen kreditkort kræves.

gem install polylingo

Få din API-nøgle