PolyLingo gem ile Ruby'den yapılandırılmış içeriği çevirme

PolyLingo Ruby gem artık RubyGems üzerinde mevcut. Tam PolyLingo API yüzeyini kapsar: senkron çeviri, toplu istekler, anket ile asenkron işler ve tüm yardımcı uç noktalar. Çalışma zamanı bağımlılığı yoktur ve Ruby 2.7 veya daha yeni sürüm gerektirir.

Bu yazı kurulum, istemci ayarı ve gem'deki tüm kullanılabilir yöntemleri anlatır.

Kurulum

Gemfile dosyanıza ekleyin:

gem "polylingo"

Sonra çalıştırın:

bundle install

Ya da doğrudan yükleyin:

gem install polylingo

Çalışma zamanı bağımlılığı yoktur. Gem sadece Ruby'nin standart HTTP kütüphanesini kullanır.

İstemciyi ayarlama

require "polylingo"

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

İki isteğe bağlı ayar mevcuttur:

client = PolyLingo.new(
  api_key:  ENV.fetch("POLYLINGO_API_KEY"),
  base_url: "https://api.usepolylingo.com/v1", # varsayılan, kendi sunucunuz için geçersiz kılın
  timeout:  120,                               # saniye (açma + okuma), varsayılan 120
)

API anahtarınızı bir ortam değişkeninde tutun. Asla sert kodlama yapmayın ve versiyon kontrolüne asla eklemeyin.

İçerik çevirme

Tek istek

İçeriğinizi, hedef dil kodlarından oluşan bir diziyi ve isteğe bağlı bir formatı geçirin:

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 parametresi plain, markdown, json veya html kabul eder. Atlanırsa, API formatı otomatik algılar. Ayrıca source dil ipucu olarak ve model "standard" (varsayılan) veya "advanced" olarak geçilebilir.

Format koruma, PolyLingo API'nin geri kalanıyla aynı şekilde çalışır. json için sadece string değerler çevrilir, anahtarlar, iç içe yapılar ve string olmayan türler dokunulmaz. markdown için başlıklar başlık olarak kalır ve kod blokları olduğu gibi bırakılır. html için etiketler ve öznitelikler korunur ve sadece metin düğümleri çevrilir.

JSON locale dosyası çevirme

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

Tek istek tüm üç locale'yi işler. Anahtarlar her çıktı dosyasında kaynakla aynıdır.

Toplu istekler

Tek bir istekte 100 içeriğe kadar gönderin, her biri kendi id ve isteğe bağlı format ile:

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

Tüm öğeler aynı targets dizisini paylaşır. Gönderdiğiniz id yanıt içinde korunur, böylece sonuçları kaynak verinize sıraya bağlı kalmadan eşleyebilirsiniz.

Asenkron işler

Uzun süren çeviriler için işler API isteği kabul eder, hemen bir job_id döner ve sonucu sorgulamanıza izin verir. Gem bunu iki şekilde yönetir.

Elle kuyruğa alma ve sorgulama

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

Tamamlanana kadar sorgulayan tek çağrı

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

  # İsteğe bağlı geçersiz kılmalar (varsayılanlar gösterilmiştir):
  poll_interval: 5,    # sorgular arası saniye, varsayılan 5
  timeout:       1200, # toplam bekleme süresi saniye cinsinden, varsayılan 1200 (20 dakika)
  on_progress:   ->(queue_position) { puts "Queue position: #{queue_position.inspect}" }
)

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

Ruby gem'deki tüm zaman değerleri saniye cinsindendir, Ruby standartlarına uygundur. on_progress lambda her sorguda tetiklenir ve mevcut kuyruk pozisyonunu tam sayı olarak veya API döndürmezse nil olarak alır.

Yardımcı uç noktalar

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 ve languages API anahtarı gerektirmez. usage doğrulanmış hesap için mevcut takvim ayı token kullanımını döner.

Hata yönetimi

Tüm hatalar PolyLingo::PolyLingoError sınıfından türetilir. Yönetmek istediğiniz özel alt sınıfları yakalayın:

begin
  result = client.translate(
    content: "# Hello",
    targets: %w[es],
    format:  "markdown"
  )
rescue PolyLingo::AuthError => e
  # HTTP 401 — geçersiz, eksik veya iptal edilmiş API anahtarı
  puts "Auth failed: #{e.message}"
rescue PolyLingo::RateLimitError => e
  # HTTP 429 — dakika başı limit aşıldı
  retry_after = e.retry_after # tam sayı saniye veya nil
  sleep retry_after if retry_after
  retry
rescue PolyLingo::JobFailedError => e
  # Asenkron iş başarısız terminal duruma ulaştı veya sorgulama zaman aşımına uğradı
  puts "Job failed: #{e.job_id}"
rescue PolyLingo::PolyLingoError => e
  # Diğer tüm API hataları
  puts "#{e.status}: #{e.error} — #{e.message}"
end

RateLimitError#retry_after JSON yanıt gövdesinden veya Retry-After başlığından mevcut olan tam sayı değerini veya nil döner. JobFailedError#job_id başarısız işin ID'sini verir, biliniyorsa.

Hızlı referans

Method	Endpoint	Auth required
`client.health`	GET /health	Hayır
`client.languages`	GET /languages	Hayır
`client.translate(...)`	POST /translate	Evet
`client.batch(...)`	POST /translate/batch	Evet
`client.usage`	GET /usage	Evet
`client.jobs.create(...)`	POST /jobs	Evet
`client.jobs.get(job_id)`	GET /jobs/:id	Evet
`client.jobs.translate(...)`	POST /jobs + polling	Evet

Başlayın

Gem RubyGems üzerinde rubygems.org/gems/polylingo adresinde. Kaynak kod github.com/UsePolyLingo/polylingo-ruby adresinde. Tam API dokümantasyonu usepolylingo.com/docs adresinde.

Ücretsiz katman ayda 50.000 token içerir. Kredi kartı gerekmez.

gem install polylingo

API anahtarınızı alın

Ruby'den PolyLingo gem ile yapılandırılmış içeriği çevirin