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

Översätt strukturerat innehåll från Ruby med PolyLingo-gem

By Robert M

Översätt strukturerat innehåll från Ruby med PolyLingo-gemet

PolyLingo Ruby-gemet finns nu tillgängligt på RubyGems. Den täcker hela PolyLingo API-ytan: synkron översättning, batchförfrågningar, asynkrona jobb med polling och alla hjälpfunktioner. Den har inga beroenden vid körning och kräver Ruby 2.7 eller senare.

Detta inlägg går igenom installation, klientinställning och varje metod som finns i gemet.

Installation

Lägg till i din Gemfile:

gem "polylingo"

Kör sedan:

bundle install

Eller installera direkt:

gem install polylingo

Inga beroenden vid körning. Gemet använder endast Rubys standardbibliotek för HTTP.

Ställa in klienten

require "polylingo"

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

Två valfria inställningar finns:

client = PolyLingo.new(
  api_key:  ENV.fetch("POLYLINGO_API_KEY"),
  base_url: "https://api.usepolylingo.com/v1", # standard, skriv över för självhostade instanser
  timeout:  120,                               # sekunder (öppna + läs), standard 120
)

Håll din API-nyckel i en miljövariabel. Aldrig hårdkoda den och aldrig checka in den i versionskontroll.

Översätta innehåll

Enskild förfrågan

Skicka ditt innehåll, en array med målspråkskoder och ett valfritt format:

result = client.translate(
  content: "# Hej\n\nDetta är **strukturerat** innehåll.",
  targets: %w[es fr de],
  format:  "markdown"
)

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

Parametern format accepterar plain, markdown, json eller html. Om den utelämnas upptäcker API:et formatet automatiskt. Du kan också skicka source som en språktips och model som antingen "standard" (standard) eller "advanced".

Formatbevarande fungerar på samma sätt som resten av PolyLingo API. För json översätts endast strängvärden och nycklar, nästling och icke-strängtyper lämnas orörda. För markdown förblir rubriker rubriker och kodblock lämnas verbatim. För html bevaras taggar och attribut och endast textnoder översätts.

Översätta en JSON-lokalfil

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 "Skriver config/locales/#{locale}.json"
end

En förfrågan hanterar alla tre lokaler. Nycklarna är identiska med källan i varje utdatafil.

Batchförfrågningar

Skicka upp till 100 innehållsobjekt i en enda förfrågan, varje med sitt eget id och valfritt format:

result = client.batch(
  items: [
    { id: "hero_title",    content: "Välkommen tillbaka",   format: "plain" },
    { id: "hero_subtitle", content: "Här är vad som ändrats idag", format: "plain" },
    { id: "cta",           content: "Kom igång",    format: "plain" },
  ],
  targets: %w[es fr de]
)

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

Alla objekt delar samma targets-array. Det id du skickar med bevaras i svaret så att du kan mappa resultaten tillbaka till din källdata utan att förlita dig på ordning.

Asynkrona jobb

För långvariga översättningar accepterar jobb-API:et förfrågan, returnerar ett job_id omedelbart och låter dig poll:a efter resultatet. Gemet hanterar detta på två sätt.

Köa och poll:a manuellt

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

Ett anrop som poll:ar tills klart

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

  # Valfria överskrivningar (standardvärden visas):
  poll_interval: 5,    # sekunder mellan pollar, standard 5
  timeout:       1200, # total väntetid i sekunder, standard 1200 (20 minuter)
  on_progress:   ->(queue_position) { puts "Köposition: #{queue_position.inspect}" }
)

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

Alla tidsvärden i Ruby-gemet använder sekunder, i enlighet med Ruby-konventioner. Lambda-funktionen on_progress körs vid varje poll och får aktuell köposition som ett heltal, eller nil om API:et inte returnerar någon.

Hjälpändpunkter

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 och languages kräver ingen API-nyckel. usage returnerar tokenförbrukning för innevarande kalendermånad för det autentiserade kontot.

Felhantering

Alla fel ärver från PolyLingo::PolyLingoError. Fånga de specifika underklasser du vill hantera:

begin
  result = client.translate(
    content: "# Hej",
    targets: %w[es],
    format:  "markdown"
  )
rescue PolyLingo::AuthError => e
  # HTTP 401 — ogiltig, saknad eller återkallad API-nyckel
  puts "Autentisering misslyckades: #{e.message}"
rescue PolyLingo::RateLimitError => e
  # HTTP 429 — minutgräns nådd
  retry_after = e.retry_after # heltal i sekunder eller nil
  sleep retry_after if retry_after
  retry
rescue PolyLingo::JobFailedError => e
  # Asynkront jobb nådde ett misslyckat slutstatus, eller polling timeout
  puts "Jobbet misslyckades: #{e.job_id}"
rescue PolyLingo::PolyLingoError => e
  # Alla andra API-fel
  puts "#{e.status}: #{e.error} — #{e.message}"
end

RateLimitError#retry_after returnerar ett heltal från antingen JSON-svarskroppen eller Retry-After-huvudet, vad som än finns, eller nil om inget av dem finns. JobFailedError#job_id ger dig ID för det misslyckade jobbet när det är känt.

Snabbreferens

MetodEndpointKräver autentisering
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 igång

Gemet finns på RubyGems på rubygems.org/gems/polylingo. Källkoden finns på github.com/UsePolyLingo/polylingo-ruby. Fullständig API-dokumentation finns på usepolylingo.com/docs.

Gratisnivån inkluderar 50 000 tokens per månad. Ingen kreditkort krävs.

gem install polylingo

Hämta din API-nyckel