Terjemah kandungan berstruktur dari Ruby dengan gem PolyLingo

Gem PolyLingo Ruby kini tersedia di RubyGems. Ia merangkumi keseluruhan permukaan API PolyLingo: terjemahan segerak, permintaan kumpulan, kerja async dengan polling, dan semua titik akhir utiliti. Ia tidak mempunyai kebergantungan runtime dan memerlukan Ruby 2.7 atau lebih baru.

Pos ini menerangkan pemasangan, penyediaan klien, dan setiap kaedah yang tersedia dalam gem.

Pemasangan

Tambah ke Gemfile anda:

gem "polylingo"

Kemudian jalankan:

bundle install

Atau pasang terus:

gem install polylingo

Tiada kebergantungan runtime. Gem ini hanya menggunakan perpustakaan standard Ruby untuk HTTP.

Menyediakan klien

require "polylingo"

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

Dua tetapan pilihan tersedia:

client = PolyLingo.new(
  api_key:  ENV.fetch("POLYLINGO_API_KEY"),
  base_url: "https://api.usepolylingo.com/v1", # lalai, ganti untuk instans sendiri
  timeout:  120,                               # saat (buka + baca), lalai 120
)

Simpan kunci API anda dalam pembolehubah persekitaran. Jangan sekali-kali kod keras dan jangan sekali-kali komit ke kawalan versi.

Menerjemah kandungan

Permintaan tunggal

Hantar kandungan anda, tatasusunan kod bahasa sasaran, dan format pilihan:

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

Parameter format menerima plain, markdown, json, atau html. Jika diabaikan, API mengesan format secara automatik. Anda juga boleh hantar source sebagai petunjuk bahasa dan model sebagai sama ada "standard" (lalai) atau "advanced".

Pemeliharaan format berfungsi sama seperti API PolyLingo yang lain. Untuk json, hanya nilai rentetan diterjemah dan kunci, penjeratan, dan jenis bukan rentetan dibiarkan tidak disentuh. Untuk markdown, tajuk kekal sebagai tajuk dan blok kod dibiarkan secara verbatim. Untuk html, tag dan atribut dipelihara dan hanya nod teks diterjemah.

Menerjemah fail locale JSON

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

Satu permintaan mengendalikan ketiga-tiga locale. Kunci adalah sama dengan sumber dalam setiap fail output.

Permintaan kumpulan

Hantar sehingga 100 item kandungan dalam satu permintaan, setiap satu dengan id sendiri dan format pilihan:

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

Semua item berkongsi tatasusunan targets yang sama. id yang anda hantar disimpan dalam respons supaya anda boleh memetakan keputusan kembali ke data sumber tanpa bergantung pada susunan.

Kerja async

Untuk terjemahan yang berjalan lama, API kerja menerima permintaan, mengembalikan job_id segera, dan membolehkan anda melakukan polling untuk keputusan. Gem mengendalikan ini dengan dua cara.

Antri dan poll secara manual

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

Satu panggilan yang melakukan polling sehingga selesai

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

  # Gantian pilihan (lalai ditunjukkan):
  poll_interval: 5,    # saat antara polling, lalai 5
  timeout:       1200, # bajet menunggu total dalam saat, lalai 1200 (20 minit)
  on_progress:   ->(queue_position) { puts "Queue position: #{queue_position.inspect}" }
)

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

Semua nilai masa dalam gem Ruby menggunakan saat, konsisten dengan konvensyen Ruby. Lambda on_progress dipanggil pada setiap polling dan menerima posisi antrian semasa sebagai integer, atau nil jika API tidak mengembalikannya.

Titik akhir utiliti

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 dan languages tidak memerlukan kunci API. usage mengembalikan penggunaan token untuk bulan kalendar semasa bagi akaun yang disahkan.

Pengendalian ralat

Semua ralat mewarisi dari PolyLingo::PolyLingoError. Tangkap subclass khusus yang anda mahu kendalikan:

begin
  result = client.translate(
    content: "# Hello",
    targets: %w[es],
    format:  "markdown"
  )
rescue PolyLingo::AuthError => e
  # HTTP 401 — kunci API tidak sah, hilang, atau dibatalkan
  puts "Auth failed: #{e.message}"
rescue PolyLingo::RateLimitError => e
  # HTTP 429 — had per minit tercapai
  retry_after = e.retry_after # saat integer atau nil
  sleep retry_after if retry_after
  retry
rescue PolyLingo::JobFailedError => e
  # Kerja async mencapai status terminal gagal, atau polling tamat masa
  puts "Job failed: #{e.job_id}"
rescue PolyLingo::PolyLingoError => e
  # Semua ralat API lain
  puts "#{e.status}: #{e.error} — #{e.message}"
end

RateLimitError#retry_after mengembalikan integer dari sama ada badan respons JSON atau header Retry-After, mana-mana yang ada, atau nil jika tiada. JobFailedError#job_id memberi anda ID kerja yang gagal apabila diketahui.

Rujukan pantas

Kaedah	Titik akhir	Perlu Auth
`client.health`	GET /health	Tidak
`client.languages`	GET /languages	Tidak
`client.translate(...)`	POST /translate	Ya
`client.batch(...)`	POST /translate/batch	Ya
`client.usage`	GET /usage	Ya
`client.jobs.create(...)`	POST /jobs	Ya
`client.jobs.get(job_id)`	GET /jobs/:id	Ya
`client.jobs.translate(...)`	POST /jobs + polling	Ya

Mula

Gem ini ada di RubyGems di rubygems.org/gems/polylingo. Kod sumber di github.com/UsePolyLingo/polylingo-ruby. Dokumentasi API penuh di usepolylingo.com/docs.

Tier percuma termasuk 50,000 token sebulan. Tiada kad kredit diperlukan.

gem install polylingo

Dapatkan kunci API anda

Terjemahkan kandungan berstruktur dari Ruby dengan gem PolyLingo