แปลเนื้อหาแบบมีโครงสร้างจาก Ruby ด้วย PolyLingo gem

PolyLingo Ruby gem พร้อมใช้งานบน RubyGems แล้ว ครอบคลุมพื้นผิว API ของ PolyLingo ทั้งหมด: การแปลแบบซิงโครนัส, คำขอแบบกลุ่ม, งานแบบอะซิงโครนัสพร้อมการตรวจสอบสถานะ และจุดสิ้นสุดยูทิลิตี้ทั้งหมด ไม่มีการพึ่งพาในเวลารันไทม์และต้องการ Ruby 2.7 หรือใหม่กว่า

โพสต์นี้จะแนะนำการติดตั้ง การตั้งค่าคลไคลเอนต์ และทุกเมธอดที่มีใน gem

การติดตั้ง

เพิ่มใน Gemfile ของคุณ:

gem "polylingo"

จากนั้นรัน:

bundle install

หรือจะติดตั้งโดยตรง:

gem install polylingo

ไม่มีการพึ่งพาในเวลารันไทม์ gem ใช้เพียงไลบรารีมาตรฐานของ Ruby สำหรับ 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 key ของคุณในตัวแปรแวดล้อม อย่ารหัสคีย์ลงในโค้ดโดยตรงและอย่าคอมมิตลงในระบบควบคุมเวอร์ชัน

การแปลเนื้อหา

คำขอเดียว

ส่งเนื้อหาของคุณ, อาร์เรย์ของรหัสภาษาปลายทาง, และรูปแบบที่เลือกได้:

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 แท็กและแอตทริบิวต์จะถูกเก็บไว้และแปลเฉพาะโหนดข้อความ

การแปลไฟล์ 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

คำขอเดียวจัดการ locale ทั้งสาม คีย์เหมือนกับต้นฉบับในทุกไฟล์ผลลัพธ์

คำขอแบบกลุ่ม

ส่งเนื้อหาสูงสุด 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 ทันที และให้คุณตรวจสอบผลลัพธ์ได้ gem จัดการสองวิธี

เข้าคิวและตรวจสอบสถานะด้วยตนเอง

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 gem ใช้วินาที ตามมาตรฐาน Ruby lambda 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 key usage คืนค่าการใช้โทเค็นของเดือนปฏิทินปัจจุบันสำหรับบัญชีที่ยืนยันตัวตนแล้ว

การจัดการข้อผิดพลาด

ข้อผิดพลาดทั้งหมดสืบทอดจาก PolyLingo::PolyLingoError จับ subclass เฉพาะที่คุณต้องการจัดการ:

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 response body หรือ header Retry-After ที่มีอยู่ หรือ nil หากไม่มี JobFailedError#job_id ให้ ID ของงานที่ล้มเหลวเมื่อทราบ

อ้างอิงด่วน

Method	Endpoint	ต้องการ Auth
`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 + polling	ใช่

เริ่มต้น

gem อยู่บน RubyGems ที่ rubygems.org/gems/polylingo โค้ดต้นฉบับที่ github.com/UsePolyLingo/polylingo-ruby เอกสาร API เต็มที่ usepolylingo.com/docs

ระดับฟรีรวม 50,000 โทเค็นต่อเดือน ไม่ต้องใช้บัตรเครดิต

gem install polylingo

รับ API key ของคุณ

แปลเนื้อหาที่มีโครงสร้างจาก Ruby ด้วย PolyLingo gem