ترجمة المحتوى المهيكل من روبي باستخدام مكتبة PolyLingo

مكتبة PolyLingo الخاصة بروبي متاحة الآن على RubyGems. تغطي كامل واجهة برمجة تطبيقات PolyLingo: الترجمة المتزامنة، طلبات الدُفعات، الوظائف غير المتزامنة مع الاستطلاع، وجميع نقاط النهاية المساعدة. لا تعتمد على مكتبات وقت التشغيل وتتطلب روبي 2.7 أو أحدث.

تشرح هذه المقالة كيفية التثبيت، إعداد العميل، وكل طريقة متاحة في المكتبة.

---

التثبيت

أضف إلى ملف Gemfile الخاص بك:

gem "polylingo"

ثم شغّل:

bundle install

أو ثبّت مباشرة:

gem install polylingo

لا توجد تبعيات وقت تشغيل. تستخدم المكتبة فقط مكتبة روبي القياسية للـ HTTP.

---

إعداد العميل

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. بالنسبة لـ 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 خاص به وصيغة اختيارية:

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 الذي تمرره في الاستجابة حتى تتمكن من ربط النتائج ببيانات المصدر دون الاعتماد على الترتيب.

---

الوظائف غير المتزامنة

لترجمات طويلة الأمد، تقبل واجهة الوظائف طلب الترجمة، وتعيد 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"]

جميع القيم الزمنية في مكتبة روبي تستخدم الثواني، متوافقة مع معايير روبي. تُنفذ دالة 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 "فشل التوثيق: #{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 "فشل الوظيفة: #{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. التوثيق الكامل للواجهة على usepolylingo.com/docs.

الطبقة المجانية تشمل 50,000 رمز شهريًا. لا حاجة لبطاقة ائتمان.

gem install polylingo

احصل على مفتاح API الخاص بك