Ruby SDK (polylingo)

Official Ruby client for the PolyLingo REST API. Uses only the standard library (net/http + json) — no runtime gem dependencies.

• RubyGems: polylingo
• Source: UsePolyLingo/polylingo-ruby

For raw HTTP details, see API reference.

Installation

gem install polylingo

Or in your Gemfile:

gem "polylingo"

Ruby: >= 2.7

Constructor

require "polylingo"

client = PolyLingo.new(
  api_key: ENV.fetch("POLYLINGO_API_KEY"), # required
  base_url: "https://api.usepolylingo.com/v1", # optional; this is the default
  timeout: 120, # optional; open + read timeout in **seconds** (default 120)
)

Methods

client.health

GET /health. Returns { "status" => …, "timestamp" => … }.

h = client.health

client.languages

GET /languages. Returns the supported language list.

data = client.languages
langs = data["languages"]

client.translate

POST /translate

r = client.translate(
  content: "# Hello",
  targets: %w[es fr],
  format: "markdown", # optional; omit to auto-detect
  source: "en",       # optional hint
  model: "standard",  # optional: "standard" | "advanced"
)

r["translations"]["es"] # String
r["usage"]["total_tokens"]
r["usage"]["input_tokens"]
r["usage"]["output_tokens"]

client.batch

POST /translate/batch

b = client.batch(
  items: [
    { "id" => "a", "content" => "Hello" },
    { "id" => "b", "content" => "## Title", "format" => "markdown" },
  ],
  targets: ["de"],
  source: "en",       # optional
  model: "standard",  # optional
)

b["results"][0]["translations"]["de"]
b["usage"]["total_tokens"]

client.usage

GET /usage. Returns plan usage for the authenticated key.

u = client.usage

Jobs (client.jobs)

client.jobs.create

POST /jobs. Enqueues async work and returns the 202 body (job_id, status, created_at, …).

job = client.jobs.create(
  content: long_markdown,
  targets: %w[de fr],
  format: "markdown",
)
puts job["job_id"]

client.jobs.get(job_id)

GET /jobs/:id. When status == "completed", the response includes translations and usage at the top level.

status = client.jobs.get(job["job_id"])

client.jobs.translate (convenience)

Submits a job, then polls until completed or failed, or until the timeout is reached.

All time values are in seconds (Ruby convention):

done = client.jobs.translate(
  content: long_markdown,
  targets: %w[de fr es],
  format: "markdown",
  poll_interval: 5,    # seconds between polls; default 5
  timeout: 1200,       # **total** seconds budget; default 1200 (20 minutes)
  on_progress: ->(pos) { puts "Queue position: #{pos}" }, # optional
)

done["translations"]["de"]
done["usage"]["total_tokens"]

Job lifecycle statuses: pending, processing, completed, failed.

Error handling

All failures raise subclasses of PolyLingo::PolyLingoError:

require "polylingo"

begin
  client.translate(content: "Hi", targets: ["es"])
rescue PolyLingo::AuthError => e
  puts "Auth failed: #{e.status} #{e.error}"
rescue PolyLingo::RateLimitError => e
  puts "Rate limited. Retry after #{e.retry_after}s"
rescue PolyLingo::JobFailedError => e
  puts "Job #{e.job_id} failed: #{e.message}"
rescue PolyLingo::PolyLingoError => e
  puts "API error #{e.status}: #{e.error} — #{e.message}"
end

Async jobs pattern (summary)

1. Fire-and-forget polling: jobs.create → your worker calls jobs.get on an interval until completed or failed.
2. Built-in polling: jobs.translate. Same semantics, with poll_interval, timeout, and on_progress.

Large payloads and long-running translations should prefer jobs over synchronous translate to avoid HTTP timeouts.

Changelog

0.1.0

• Initial release: health, languages, translate, batch, usage, jobs.create, jobs.get, jobs.translate.