PolyLingo जेम के साथ Ruby से संरचित सामग्री का अनुवाद करें

PolyLingo Ruby जेम अब RubyGems पर उपलब्ध है। यह पूरी PolyLingo API सतह को कवर करता है: समकालिक अनुवाद, बैच अनुरोध, पोलिंग के साथ असिंक्रोनस जॉब्स, और सभी उपयोगिता एंडपॉइंट्स। इसमें कोई रनटाइम निर्भरता नहीं है और यह Ruby 2.7 या बाद के संस्करण की आवश्यकता है।

यह पोस्ट इंस्टॉलेशन, क्लाइंट सेटअप, और जेम में उपलब्ध हर मेथड के बारे में बताता है।

इंस्टॉलेशन

अपने Gemfile में जोड़ें:

gem "polylingo"

फिर चलाएं:

bundle install

या सीधे इंस्टॉल करें:

gem install polylingo

कोई रनटाइम निर्भरता नहीं। जेम HTTP के लिए केवल Ruby की स्टैंडर्ड लाइब्रेरी का उपयोग करता है।

क्लाइंट सेटअप

require "polylingo"

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

दो वैकल्पिक सेटिंग्स उपलब्ध हैं:

client = PolyLingo.new(
  api_key:  ENV.fetch("POLYLINGO_API_KEY"),
  base_url: "https://api.usepolylingo.com/v1", # डिफ़ॉल्ट, सेल्फ-होस्टेड इंस्टेंस के लिए ओवरराइड करें
  timeout:  120,                               # सेकंड (ओपन + रीड), डिफ़ॉल्ट 120
)

अपनी API कुंजी को पर्यावरण चर में रखें। इसे कभी हार्डकोड न करें और न ही संस्करण नियंत्रण में कमिट करें।

सामग्री का अनुवाद

एकल अनुरोध

अपनी सामग्री, लक्षित भाषा कोडों की एक सूची, और एक वैकल्पिक फॉर्मेट पास करें:

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 पैरामीटर plain, markdown, json, या html स्वीकार करता है। यदि छोड़ा गया है, तो API फॉर्मेट का स्वचालित पता लगाता है। आप भाषा संकेत के रूप में source और मॉडल के रूप में "standard" (डिफ़ॉल्ट) या "advanced" भी पास कर सकते हैं।

फॉर्मेट संरक्षण PolyLingo API के बाकी हिस्सों की तरह काम करता है। json के लिए, केवल स्ट्रिंग मानों का अनुवाद किया जाता है और कुंजियाँ, नेस्टिंग, और गैर-स्ट्रिंग प्रकार अपरिवर्तित रहते हैं। markdown के लिए, हेडिंग्स हेडिंग्स रहते हैं और कोड ब्लॉक्स को वर्बैटिम छोड़ दिया जाता है। html के लिए, टैग और एट्रिब्यूट्स संरक्षित रहते हैं और केवल टेक्स्ट नोड्स का अनुवाद किया जाता है।

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

एक अनुरोध तीनों लोकल्स को संभालता है। प्रत्येक आउटपुट फ़ाइल में कुंजियाँ स्रोत के समान होती हैं।

बैच अनुरोध

एकल अनुरोध में 100 तक सामग्री आइटम भेजें, प्रत्येक के अपने id और वैकल्पिक 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

सभी आइटम एक ही targets सूची साझा करते हैं। आप जो id पास करते हैं वह प्रतिक्रिया में संरक्षित रहता है ताकि आप परिणामों को अपने स्रोत डेटा से बिना क्रम पर निर्भर हुए मैप कर सकें।

असिंक्रोनस जॉब्स

लंबे समय तक चलने वाले अनुवादों के लिए, जॉब्स API अनुरोध स्वीकार करता है, तुरंत job_id लौटाता है, और आपको परिणाम के लिए पोल करने देता है। जेम इसे दो तरीकों से संभालता है।

मैन्युअल रूप से कतार में डालें और पोल करें

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

एक कॉल जो पूरा होने तक पोल करता है

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

  # वैकल्पिक ओवरराइड (डिफ़ॉल्ट दिखाए गए):
  poll_interval: 5,    # पोल के बीच सेकंड, डिफ़ॉल्ट 5
  timeout:       1200, # कुल प्रतीक्षा बजट सेकंड में, डिफ़ॉल्ट 1200 (20 मिनट)
  on_progress:   ->(queue_position) { puts "Queue position: #{queue_position.inspect}" }
)

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

Ruby जेम में सभी समय मान सेकंड में होते हैं, Ruby कन्वेंशन्स के अनुरूप। on_progress लैम्ब्डा हर पोल पर फायर होता है और वर्तमान कतार स्थिति को पूर्णांक के रूप में प्राप्त करता है, या nil यदि API इसे वापस नहीं करता।

उपयोगिता एंडपॉइंट्स

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 और languages के लिए API कुंजी की आवश्यकता नहीं है। usage प्रमाणीकृत खाते के लिए वर्तमान कैलेंडर महीने में टोकन खपत लौटाता है।

त्रुटि हैंडलिंग

सभी त्रुटियाँ PolyLingo::PolyLingoError से विरासत में मिलती हैं। आप उन विशिष्ट उपश्रेणियों को पकड़ें जिन्हें आप संभालना चाहते हैं:

begin
  result = client.translate(
    content: "# Hello",
    targets: %w[es],
    format:  "markdown"
  )
rescue PolyLingo::AuthError => e
  # HTTP 401 — अमान्य, गायब, या रद्द की गई API कुंजी
  puts "Auth failed: #{e.message}"
rescue PolyLingo::RateLimitError => e
  # HTTP 429 — प्रति मिनट सीमा पहुंच गई
  retry_after = e.retry_after # पूर्णांक सेकंड या nil
  sleep retry_after if retry_after
  retry
rescue PolyLingo::JobFailedError => e
  # असिंक्रोनस जॉब ने विफल टर्मिनल स्थिति प्राप्त की, या पोलिंग टाइमआउट हुआ
  puts "Job failed: #{e.job_id}"
rescue PolyLingo::PolyLingoError => e
  # सभी अन्य API त्रुटियाँ
  puts "#{e.status}: #{e.error} — #{e.message}"
end

RateLimitError#retry_after JSON प्रतिक्रिया बॉडी या Retry-After हेडर में से जो भी मौजूद हो, उससे पूर्णांक लौटाता है, या यदि दोनों शामिल नहीं हैं तो nil। JobFailedError#job_id आपको विफल जॉब का ID देता है जब यह ज्ञात हो।

त्वरित संदर्भ

मेथड	एंडपॉइंट	ऑथ आवश्यक
`client.health`	GET /health	नहीं
`client.languages`	GET /languages	नहीं
`client.translate(...)`	POST /translate	हाँ
`client.batch(...)`	POST /translate/batch	हाँ
`client.usage`	GET /usage	हाँ
`client.jobs.create(...)`	POST /jobs	हाँ
`client.jobs.get(job_id)`	GET /jobs/:id	हाँ
`client.jobs.translate(...)`	POST /jobs + पोलिंग	हाँ

शुरू करें

जेम RubyGems पर rubygems.org/gems/polylingo पर है। स्रोत कोड github.com/UsePolyLingo/polylingo-ruby पर है। पूर्ण API दस्तावेज़ usepolylingo.com/docs पर है।

मुफ्त स्तर में प्रति माह 50,000 टोकन शामिल हैं। कोई क्रेडिट कार्ड आवश्यक नहीं।

gem install polylingo

अपनी API कुंजी प्राप्त करें

Ruby से PolyLingo जेम के साथ संरचित सामग्री का अनुवाद करें