Terjemahkan konten terstruktur dari Ruby dengan gem PolyLingo

Gem PolyLingo Ruby sekarang tersedia di RubyGems. Ini mencakup seluruh permukaan API PolyLingo: terjemahan sinkron, permintaan batch, pekerjaan async dengan polling, dan semua endpoint utilitas. Tidak memiliki dependensi runtime dan membutuhkan Ruby 2.7 atau lebih baru.

Posting ini menjelaskan instalasi, pengaturan klien, dan setiap metode yang tersedia dalam gem.

Instalasi

Tambahkan ke Gemfile Anda:

gem "polylingo"

Kemudian jalankan:

bundle install

Atau instal langsung:

gem install polylingo

Tidak ada dependensi runtime. Gem hanya menggunakan pustaka standar Ruby untuk HTTP.

Menyiapkan klien

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

Dua pengaturan opsional tersedia:

client = PolyLingo.new(
  api_key:  ENV.fetch("POLYLINGO_API_KEY"),
  base_url: "https://api.usepolylingo.com/v1", # default, ganti untuk instance self-hosted
  timeout:  120,                               # detik (open + read), default 120
)

Simpan kunci API Anda dalam variabel lingkungan. Jangan pernah menuliskannya secara hardcode dan jangan pernah meng-commit ke kontrol versi.

Menerjemahkan konten

Permintaan tunggal

Berikan konten Anda, array kode bahasa target, dan format opsional:

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 dihilangkan, API akan mendeteksi format secara otomatis. Anda juga dapat memberikan source sebagai petunjuk bahasa dan model sebagai "standard" (default) atau "advanced".

Preservasi format bekerja sama seperti API PolyLingo lainnya. Untuk json, hanya nilai string yang diterjemahkan dan kunci, penempatan, serta tipe non-string dibiarkan tidak berubah. Untuk markdown, heading tetap heading dan blok kode dibiarkan verbatim. Untuk html, tag dan atribut dipertahankan dan hanya node teks yang diterjemahkan.

Menerjemahkan file 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 menangani ketiga locale. Kunci identik dengan sumber di setiap file output.

Permintaan batch

Kirim hingga 100 item konten dalam satu permintaan, masing-masing dengan id dan format opsional:

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 berbagi array targets yang sama. id yang Anda berikan dipertahankan dalam respons sehingga Anda dapat memetakan hasil kembali ke data sumber tanpa bergantung pada urutan.

Pekerjaan async

Untuk terjemahan yang berjalan lama, API pekerjaan menerima permintaan, mengembalikan job_id segera, dan memungkinkan Anda melakukan polling untuk hasilnya. Gem menangani ini dengan dua cara.

Antri dan polling 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 polling sampai selesai

done = client.jobs.translate(
  content:       File.read("content/long-article.md"),
  targets:       %w[es fr de],
  format:        "markdown",
 
  # Override opsional (default ditampilkan):
  poll_interval: 5,    # detik antar polling, default 5
  timeout:       1200, # total waktu tunggu dalam detik, default 1200 (20 menit)
  on_progress:   ->(queue_position) { puts "Queue position: #{queue_position.inspect}" }
)
 
translations = done["translations"]
usage        = done["usage"]

Semua nilai waktu dalam gem Ruby menggunakan detik, konsisten dengan konvensi Ruby. Lambda on_progress dipanggil pada setiap polling dan menerima posisi antrean saat ini sebagai integer, atau nil jika API tidak mengembalikannya.

Endpoint utilitas

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 konsumsi token untuk bulan kalender saat ini untuk akun yang diautentikasi.

Penanganan error

Semua error mewarisi dari PolyLingo::PolyLingoError. Tangkap subclass spesifik yang ingin Anda tangani:

begin
  result = client.translate(
    content: "# Hello",
    targets: %w[es],
    format:  "markdown"
  )
rescue PolyLingo::AuthError => e
  # HTTP 401 — kunci API tidak valid, hilang, atau dicabut
  puts "Auth failed: #{e.message}"
rescue PolyLingo::RateLimitError => e
  # HTTP 429 — batas per menit tercapai
  retry_after = e.retry_after # detik integer atau nil
  sleep retry_after if retry_after
  retry
rescue PolyLingo::JobFailedError => e
  # Pekerjaan async mencapai status terminal gagal, atau polling timeout
  puts "Job failed: #{e.job_id}"
rescue PolyLingo::PolyLingoError => e
  # Semua error API lainnya
  puts "#{e.status}: #{e.error} — #{e.message}"
end

RateLimitError#retry_after mengembalikan integer dari respons JSON atau header Retry-After, mana yang tersedia, atau nil jika tidak ada. JobFailedError#job_id memberi Anda ID pekerjaan yang gagal saat diketahui.

Referensi cepat

Metode	Endpoint	Memerlukan 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

Mulai

Gem tersedia di RubyGems di rubygems.org/gems/polylingo. Kode sumber di github.com/UsePolyLingo/polylingo-ruby. Dokumentasi API lengkap di usepolylingo.com/docs.

Tingkat gratis mencakup 50.000 token per bulan. Tidak perlu kartu kredit.

gem install polylingo

Dapatkan kunci API Anda