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 ভাষা হিন্ট এবং model হিসেবে "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

একটি অনুরোধ তিনটি লোকেলই পরিচালনা করে। প্রতিটি আউটপুট ফাইলে কী গুলো সোর্সের সাথে একই থাকে।

ব্যাচ অনুরোধ

একটি অনুরোধে সর্বোচ্চ ১০০টি বিষয়বস্তু আইটেম পাঠান, প্রতিটির নিজস্ব 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 (২০ মিনিট)
  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 ব্যর্থ কাজের আইডি দেয় যখন তা জানা থাকে।

দ্রুত রেফারেন্স

পদ্ধতি	এন্ডপয়েন্ট	প্রমাণীকরণ প্রয়োজন
`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।

ফ্রি টিয়ার প্রতি মাসে ৫০,০০০ টোকেন অন্তর্ভুক্ত করে। কোনো ক্রেডিট কার্ডের প্রয়োজন নেই।

gem install polylingo

আপনার API কী পান

রুবি থেকে PolyLingo জেম দিয়ে কাঠামোবদ্ধ সামগ্রী অনুবাদ করুন