Übersetzen strukturierter Inhalte aus Ruby mit dem PolyLingo-Gem

Das PolyLingo Ruby-Gem ist jetzt auf RubyGems verfügbar. Es deckt die gesamte PolyLingo-API-Oberfläche ab: synchrone Übersetzung, Batch-Anfragen, asynchrone Jobs mit Polling und alle Dienstendpunkte. Es hat keine Laufzeitabhängigkeiten und erfordert Ruby 2.7 oder höher.

Dieser Beitrag führt durch die Installation, die Einrichtung des Clients und jede im Gem verfügbare Methode.

Installation

Fügen Sie Ihrer Gemfile hinzu:

gem "polylingo"

Dann führen Sie aus:

bundle install

Oder installieren Sie direkt:

gem install polylingo

Keine Laufzeitabhängigkeiten. Das Gem verwendet nur die Standardbibliothek von Ruby für HTTP.

Einrichtung des Clients

require "polylingo"

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

Zwei optionale Einstellungen sind verfügbar:

client = PolyLingo.new(
  api_key:  ENV.fetch("POLYLINGO_API_KEY"),
  base_url: "https://api.usepolylingo.com/v1", # Standard, überschreiben für selbstgehostete Instanzen
  timeout:  120,                               # Sekunden (öffnen + lesen), Standard 120
)

Bewahren Sie Ihren API-Schlüssel in einer Umgebungsvariable auf. Niemals hartkodieren und niemals in die Versionskontrolle einchecken.

Inhalte übersetzen

Einzelanfrage

Übergeben Sie Ihren Inhalt, ein Array von Zielsprachcodes und ein optionales Format:

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"]

Der Parameter format akzeptiert plain, markdown, json oder html. Wenn ausgelassen, erkennt die API das Format automatisch. Sie können auch source als Sprachhinweis und model als entweder "standard" (Standard) oder "advanced" übergeben.

Die Formatbeibehaltung funktioniert genauso wie der Rest der PolyLingo-API. Für json werden nur Zeichenkettenwerte übersetzt, Schlüssel, Verschachtelungen und Nicht-Zeichenketten-Typen bleiben unverändert. Für markdown bleiben Überschriften Überschriften und Codeblöcke werden unverändert gelassen. Für html werden Tags und Attribute beibehalten und nur Textknoten übersetzt.

Übersetzen einer JSON-Lokalisierungsdatei

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

Eine Anfrage verarbeitet alle drei Sprachen. Die Schlüssel sind in jeder Ausgabedatei identisch mit der Quelle.

Batch-Anfragen

Senden Sie bis zu 100 Inhaltselemente in einer einzigen Anfrage, jedes mit eigener id und optionalem 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

Alle Elemente teilen sich dasselbe targets-Array. Die übergebene id wird in der Antwort beibehalten, sodass Sie Ergebnisse ohne Reihenfolgeabhängigkeit auf Ihre Quelldaten abbilden können.

Asynchrone Jobs

Für lang laufende Übersetzungen akzeptiert die Jobs-API die Anfrage, gibt sofort eine job_id zurück und ermöglicht das Polling auf das Ergebnis. Das Gem unterstützt dies auf zwei Arten.

Manuelles Einreihen und Polling

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

Ein Aufruf, der bis zum Abschluss pollt

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

  # Optionale Überschreibungen (Standardwerte gezeigt):
  poll_interval: 5,    # Sekunden zwischen den Polls, Standard 5
  timeout:       1200, # Gesamtwartezeit in Sekunden, Standard 1200 (20 Minuten)
  on_progress:   ->(queue_position) { puts "Queue position: #{queue_position.inspect}" }
)

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

Alle Zeitwerte im Ruby-Gem verwenden Sekunden, konsistent mit Ruby-Konventionen. Die on_progress-Lambda wird bei jedem Poll ausgelöst und erhält die aktuelle Position in der Warteschlange als Integer oder nil, falls die API keine zurückgibt.

Dienstendpunkte

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 und languages benötigen keinen API-Schlüssel. usage gibt den Tokenverbrauch für den aktuellen Kalendermonat für das authentifizierte Konto zurück.

Fehlerbehandlung

Alle Fehler erben von PolyLingo::PolyLingoError. Fangen Sie die spezifischen Unterklassen, die Sie behandeln möchten:

begin
  result = client.translate(
    content: "# Hello",
    targets: %w[es],
    format:  "markdown"
  )
rescue PolyLingo::AuthError => e
  # HTTP 401 — ungültiger, fehlender oder widerrufener API-Schlüssel
  puts "Auth fehlgeschlagen: #{e.message}"
rescue PolyLingo::RateLimitError => e
  # HTTP 429 — Minutenlimit erreicht
  retry_after = e.retry_after # ganze Sekunden oder nil
  sleep retry_after if retry_after
  retry
rescue PolyLingo::JobFailedError => e
  # Asynchroner Job erreichte einen fehlgeschlagenen Endstatus oder Polling lief ab
  puts "Job fehlgeschlagen: #{e.job_id}"
rescue PolyLingo::PolyLingoError => e
  # Alle anderen API-Fehler
  puts "#{e.status}: #{e.error} — #{e.message}"
end

RateLimitError#retry_after gibt eine ganze Zahl aus dem JSON-Antwortkörper oder dem Retry-After-Header zurück, je nachdem, was vorhanden ist, oder nil, wenn keiner enthalten ist. JobFailedError#job_id gibt die ID des fehlgeschlagenen Jobs zurück, wenn bekannt.

Schnelle Referenz

Methode	Endpunkt	Auth erforderlich
`client.health`	GET /health	Nein
`client.languages`	GET /languages	Nein
`client.translate(...)`	POST /translate	Ja
`client.batch(...)`	POST /translate/batch	Ja
`client.usage`	GET /usage	Ja
`client.jobs.create(...)`	POST /jobs	Ja
`client.jobs.get(job_id)`	GET /jobs/:id	Ja
`client.jobs.translate(...)`	POST /jobs + Polling	Ja

Erste Schritte

Das Gem ist auf RubyGems unter rubygems.org/gems/polylingo verfügbar. Der Quellcode ist auf github.com/UsePolyLingo/polylingo-ruby. Die vollständige API-Dokumentation finden Sie unter usepolylingo.com/docs.

Der kostenlose Tarif umfasst 50.000 Tokens pro Monat. Keine Kreditkarte erforderlich.

gem install polylingo

Holen Sie sich Ihren API-Schlüssel

Strukturierte Inhalte aus Ruby mit dem PolyLingo-Gem übersetzen