Käännä jäsennelty sisältö Rubylla PolyLingo-kirjastolla

PolyLingo Ruby -kirjasto on nyt saatavilla RubyGemsissä. Se kattaa koko PolyLingo API -rajapinnan: synkronisen käännöksen, eräpyynnöt, asynkroniset tehtävät kyselyllä sekä kaikki apupäätepisteet. Kirjastolla ei ole ajonaikaisia riippuvuuksia ja se vaatii Ruby 2.7:n tai uudemman.

Tässä artikkelissa käydään läpi asennus, asiakkaan asetukset ja kaikki kirjaston tarjoamat metodit.

Asennus

Lisää Gemfileesi:

gem "polylingo"

Sitten suorita:

bundle install

Tai asenna suoraan:

gem install polylingo

Ei ajonaikaisia riippuvuuksia. Kirjasto käyttää vain Rubyn standardikirjastoa HTTP:lle.

Asiakkaan asetukset

require "polylingo"

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

Kaksi valinnaista asetusta on saatavilla:

client = PolyLingo.new(
  api_key:  ENV.fetch("POLYLINGO_API_KEY"),
  base_url: "https://api.usepolylingo.com/v1", # oletus, ylikirjoita itseisännöidyissä instansseissa
  timeout:  120,                               # sekunteina (avaus + luku), oletus 120
)

Pidä API-avaimesi ympäristömuuttujassa. Älä koskaan kovakoodaa sitä tai tallenna versionhallintaan.

Sisällön kääntäminen

Yksittäinen pyyntö

Anna sisältösi, kohdekielikoodien taulukko ja valinnainen formaatti:

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

format-parametri hyväksyy arvot plain, markdown, json tai html. Jos se jätetään pois, API tunnistaa formaatin automaattisesti. Voit myös antaa source-kielen vihjeeksi ja model joko "standard" (oletus) tai "advanced".

Formaatin säilyttäminen toimii samalla tavalla kuin muualla PolyLingo API:ssa. json-formaatissa käännetään vain merkkijonoarvot, avaimet, sisäkkäisyys ja ei-merkkijonotyypit jätetään koskemattomiksi. markdown-formaatissa otsikot pysyvät otsikoina ja koodilohkot säilytetään sellaisenaan. html-formaatissa tagit ja attribuutit säilyvät ja vain tekstisolmut käännetään.

JSON-lokalisointitiedoston kääntäminen

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

Yksi pyyntö käsittelee kaikki kolme lokalisointia. Avaimet ovat identtiset lähteen kanssa kaikissa tulostiedostoissa.

Eräpyynnöt

Lähetä jopa 100 sisältöä yhdellä pyynnöllä, jokaisella oma id ja valinnainen 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

Kaikilla kohteilla on sama targets-taulukko. Antamasi id säilyy vastauksessa, joten voit yhdistää tulokset lähdetietoihisi ilman, että sinun tarvitsee luottaa järjestykseen.

Asynkroniset tehtävät

Pitkään kestävissä käännöksissä jobs API hyväksyy pyynnön, palauttaa heti job_id:n ja antaa sinun kysellä tulosta. Kirjasto hoitaa tämän kahdella tavalla.

Laita jonoon ja kysy manuaalisesti

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

Yksi kutsu, joka kysyy kunnes valmis

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

  # Valinnaiset ylikirjoitukset (oletukset näytetty):
  poll_interval: 5,    # sekuntia kyselyjen välillä, oletus 5
  timeout:       1200, # kokonaisaika sekunteina, oletus 1200 (20 minuuttia)
  on_progress:   ->(queue_position) { puts "Queue position: #{queue_position.inspect}" }
)

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

Kaikki aika-arvot Ruby-kirjastossa ovat sekunteina, Rubyn käytäntöjen mukaisesti. on_progress-lambda kutsutaan jokaisella kyselyllä ja saa parametrina jonon nykyisen sijainnin kokonaislukuna tai nil jos API ei palauta sitä.

Apupäätepisteet

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 ja languages eivät vaadi API-avainta. usage palauttaa tokenien kulutuksen kuluvan kalenterikuukauden ajalta todennetulle tilille.

Virheenkäsittely

Kaikki virheet periytyvät luokasta PolyLingo::PolyLingoError. Käsittele haluamasi aliluokat:

begin
  result = client.translate(
    content: "# Hello",
    targets: %w[es],
    format:  "markdown"
  )
rescue PolyLingo::AuthError => e
  # HTTP 401 — virheellinen, puuttuva tai peruutettu API-avain
  puts "Auth failed: #{e.message}"
rescue PolyLingo::RateLimitError => e
  # HTTP 429 — minuuttikohtainen raja saavutettu
  retry_after = e.retry_after # kokonaisluku sekunteina tai nil
  sleep retry_after if retry_after
  retry
rescue PolyLingo::JobFailedError => e
  # Asynkroninen tehtävä epäonnistui tai kysely aikakatkaistiin
  puts "Job failed: #{e.job_id}"
rescue PolyLingo::PolyLingoError => e
  # Kaikki muut API-virheet
  puts "#{e.status}: #{e.error} — #{e.message}"
end

RateLimitError#retry_after palauttaa kokonaisluvun joko JSON-vastauksen rungosta tai Retry-After-otsikosta, kumpi tahansa on saatavilla, tai nil jos kumpaakaan ei ole. JobFailedError#job_id antaa epäonnistuneen tehtävän tunnuksen, jos se on tiedossa.

Pikaviite

Metodi	Päätepiste	Tarvitseeko autentikoinnin
`client.health`	GET /health	Ei
`client.languages`	GET /languages	Ei
`client.translate(...)`	POST /translate	Kyllä
`client.batch(...)`	POST /translate/batch	Kyllä
`client.usage`	GET /usage	Kyllä
`client.jobs.create(...)`	POST /jobs	Kyllä
`client.jobs.get(job_id)`	GET /jobs/:id	Kyllä
`client.jobs.translate(...)`	POST /jobs + kysely	Kyllä

Aloita

Kirjasto on RubyGemsissä osoitteessa rubygems.org/gems/polylingo. Lähdekoodi löytyy osoitteesta github.com/UsePolyLingo/polylingo-ruby. Täydellinen API-dokumentaatio on osoitteessa usepolylingo.com/docs.

Ilmainen taso sisältää 50 000 tokenia kuukaudessa. Ei luottokorttia vaadita.

gem install polylingo

Hanki API-avaimesi

Käännä jäsennelty sisältö Rubystä PolyLingo-kirjastolla