Ruby SDK

KI-Übersetzung mit Ruby und Lingo.dev

Einführung

Das Lingo.dev Ruby SDK übersetzt Text, Hash-Objekte und Chat-Konversationen mit Unterstützung für Batch-Operationen, Fortschrittsverfolgung und gleichzeitiger Verarbeitung. Es verarbeitet große Payloads, indem es Inhalte automatisch in optimale Batch-Größen aufteilt und unterstützt Glossare für konsistente Terminologie.

Installation

gem

gem install lingodotdev

Bundler

Fügen Sie zu Ihrem Gemfile hinzu:

gem 'lingodotdev'

Führen Sie dann aus:

bundle install

Schnellübersetzung

Überspringen Sie die Instanzverwaltung für einmalige Übersetzungen. Diese Methoden verwalten den Engine-Lebenszyklus automatisch und verwenden standardmäßig den Fast-Modus, was sie ideal für CLI-Tools und Skripte macht.

require 'lingodotdev'

# Translate text
text_result = LingoDotDev::Engine.quick_translate(
  'Hello world',
  api_key: ENV['LINGODOTDEV_API_KEY'],
  target_locale: 'es'
)
puts "Text: #{text_result}"

# Translate object
object_result = LingoDotDev::Engine.quick_translate(
  { greeting: 'Hello', farewell: 'Goodbye' },
  api_key: ENV['LINGODOTDEV_API_KEY'],
  target_locale: 'fr'
)
puts "Object: #{object_result}"

Grundlegende Verwendung

Das SDK benötigt einen API-Schlüssel von Lingo.dev.

require 'lingodotdev'

engine = LingoDotDev::Engine.new(api_key: ENV['LINGODOTDEV_API_KEY'])

result = engine.localize_text(
  'Welcome! We missed you.',
  target_locale: 'es'
)
puts result

Textübersetzung mit Fortschritt

Verfolgen Sie den Übersetzungsfortschritt mit einem Callback. Selbst einzelne Textstrings durchlaufen den Chunker, was Fortschrittsberichte für lange Texte ermöglicht und ein konsistentes Verhalten über alle Inhaltstypen hinweg bietet.

require 'lingodotdev'

engine = LingoDotDev::Engine.new(api_key: ENV['LINGODOTDEV_API_KEY'])

result = engine.localize_text(
  'We sent a confirmation email.',
  target_locale: 'es'
) do |progress|
  puts "Progress: #{progress}%"
end

puts "Result: #{result}"

Objektübersetzung

Übersetzen Sie verschachtelte Hashes unter Beibehaltung der Struktur. Das SDK verarbeitet rekursiv alle String-Werte unabhängig von der Tiefe.

require 'lingodotdev'

content = {
  title: 'Welcome',
  cta: 'Start your free trial',
  footer: {
    legal: 'All rights reserved.',
    help: 'Need help?'
  }
}

engine = LingoDotDev::Engine.new(api_key: ENV['LINGODOTDEV_API_KEY'])

result = engine.localize_object(content, target_locale: 'es')
puts result

Batch-Übersetzung in mehrere Sprachen

Übersetzen Sie Inhalte in mehrere Zielsprachen mit einem einzigen Aufruf. Gibt ein Array mit einem Ergebnis pro Zielsprache zurück, in der gleichen Reihenfolge wie angefordert.

require 'lingodotdev'

engine = LingoDotDev::Engine.new(api_key: ENV['LINGODOTDEV_API_KEY'])

# Translate text to multiple languages
text_results = engine.batch_localize_text(
  'Welcome to our application',
  target_locales: ['es', 'fr', 'de'],
  fast: true
)
puts "Text results: #{text_results}"

Batch-Objektübersetzung

Lokalisieren Sie mehrere Objekte in dieselbe Zielsprache. Nützlich für die effiziente Verarbeitung von Content-Sammlungen.

require 'lingodotdev'

engine = LingoDotDev::Engine.new(api_key: ENV['LINGODOTDEV_API_KEY'])

objects = [
  { title: 'Welcome', body: 'Hello there' },
  { title: 'About', body: 'Learn more about us' },
  { title: 'Contact', body: 'Get in touch' }
]

results = engine.batch_localize_objects(
  objects,
  target_locale: 'es',
  concurrent: true
)

results.each do |result|
  puts "#{result[:title]}: #{result[:body]}"
end

Chat-Übersetzung

Übersetzen Sie Chat-Nachrichten unter Beibehaltung der Sprechernamen. Jede Nachricht muss sowohl :name als auch :text Keys enthalten. Nützlich für die Lokalisierung von Support-Konversationen, Chat-Protokollen oder Dialogsystemen ohne Verlust der Konversationsstruktur.

require 'lingodotdev'

chat = [
  { name: 'Alice', text: 'Hello everyone!' },
  { name: 'Bob', text: 'How are you doing?' },
  { name: 'Alice', text: 'Great, thanks for asking!' }
]

engine = LingoDotDev::Engine.new(api_key: ENV['LINGODOTDEV_API_KEY'])

result = engine.localize_chat(chat, target_locale: 'es')

result.each do |message|
  puts "#{message[:name]}: #{message[:text]}"
end

Sequenzielle Verarbeitung mit Fortschritt

Der sequenzielle Modus ermöglicht detaillierte Fortschritts-Callbacks. Der Callback erhält den Fortschrittsprozentsatz für jeden verarbeiteten Batch, nützlich für das Debugging von Übersetzungsproblemen oder die Anzeige detaillierter Fortschritte in UIs.

require 'lingodotdev'

content = {
  welcome: 'Hello',
  goodbye: 'Farewell',
  help: 'Need assistance?'
}

engine = LingoDotDev::Engine.new(api_key: ENV['LINGODOTDEV_API_KEY'])

result = engine.localize_object(content, target_locale: 'es') do |progress|
  puts "#{progress}% complete"
end

puts result

Parallele Verarbeitung

Verarbeiten Sie Chunks parallel für schnellere Übersetzungen. Dieser Modus opfert Fortschrittsverfolgung zugunsten von Geschwindigkeit und ist ideal für Produktions-Workloads, bei denen Durchsatz wichtiger ist als Benutzer-Feedback.

require 'lingodotdev'

content = {
  header: { title: 'Welcome', subtitle: 'Get started' },
  body: { intro: 'Learn more', details: 'Full description' },
  footer: { copyright: '2024', contact: 'Email us' }
}

engine = LingoDotDev::Engine.new(api_key: ENV['LINGODOTDEV_API_KEY'])

result = engine.localize_object(
  content,
  target_locale: 'es',
  concurrent: true
)

puts result

Referenzdaten

Stellen Sie Glossare oder frühere Übersetzungen bereit, um Konsistenz sicherzustellen. Referenzdaten werden mit jedem Chunk an die API gesendet, halten Sie sie daher in angemessener Größe. Verwenden Sie dies für Markenbegriffe, technisches Vokabular oder zur Aufrechterhaltung der Übersetzungskonsistenz über Produktaktualisierungen hinweg.

require 'lingodotdev'

content = { cta: 'Start your free trial', title: 'Welcome' }

reference = {
  es: { cta: 'Comienza tu prueba gratuita' },
  fr: { cta: 'Commencez votre essai gratuit' }
}

engine = LingoDotDev::Engine.new(api_key: ENV['LINGODOTDEV_API_KEY'])

result = engine.localize_object(
  content,
  target_locale: 'es',
  reference: reference,
  concurrent: true
)

puts result

Konfiguration

Steuern Sie das Batching-Verhalten und API-Endpunkte. Das SDK teilt große Payloads basierend auf Key-Anzahl und Wortzahl-Beschränkungen auf, verhindert API-Timeouts und verbessert die Zuverlässigkeit für große Übersetzungsjobs.

require 'lingodotdev'

engine = LingoDotDev::Engine.new(
  api_key: ENV['LINGODOTDEV_API_KEY'],
  api_url: 'https://engine.lingo.dev',
  batch_size: 25,              # Items per chunk (1-250)
  ideal_batch_item_size: 250   # Words per chunk (1-2500)
)

result = engine.localize_text(
  'Reset your password',
  target_locale: 'es',
  fast: true
)

puts result

Sie können auch mit einem Block konfigurieren:

require 'lingodotdev'

engine = LingoDotDev::Engine.new(api_key: ENV['LINGODOTDEV_API_KEY']) do |config|
  config.batch_size = 50
  config.ideal_batch_item_size = 500
end

result = engine.localize_text('Hello world', target_locale: 'es')
puts result

Spracherkennung

Erkennen Sie die Sprache eines Textstrings. Nützlich für das automatische Routing von Inhalten zur korrekten Übersetzungs-Pipeline oder zur Validierung der Eingabesprache von Benutzern.

require 'lingodotdev'

engine = LingoDotDev::Engine.new(api_key: ENV['LINGODOTDEV_API_KEY'])

locale = engine.recognize_locale('Guten Morgen')
puts "Detected language: #{locale}"

API-Key-Introspection

Prüfen Sie, welchem Konto ein API-Key gehört. Gibt nil zurück, wenn die Authentifizierung fehlschlägt. Nützlich zum Debuggen von Authentifizierungsproblemen oder zur Anzeige von Kontoinformationen in Admin-Tools.

require 'lingodotdev'

engine = LingoDotDev::Engine.new(api_key: ENV['LINGODOTDEV_API_KEY'])

user = engine.whoami
if user
  puts "Authenticated as: #{user[:email]}"
else
  puts 'Authentication failed'
end

Fehlerbehandlung

Das SDK definiert benutzerdefinierte Exception-Klassen für verschiedene Fehlerszenarien. Unterscheiden Sie zwischen Benutzerfehlern (ValidationError) und Infrastrukturproblemen (ServerError, APIError) für eine angemessene Retry-Logik.

require 'lingodotdev'

begin
  engine = LingoDotDev::Engine.new(api_key: ENV['LINGODOTDEV_API_KEY'])
  result = engine.localize_text('Hello', target_locale: 'es')
  puts result
rescue LingoDotDev::ValidationError => e
  puts "Invalid parameters or bad request: #{e.message}"
rescue LingoDotDev::AuthenticationError => e
  puts "Authentication error: #{e.message}"
rescue LingoDotDev::ServerError => e
  puts "Server or network error: #{e.message}"
rescue LingoDotDev::APIError => e
  puts "API error: #{e.message}"
rescue LingoDotDev::Error => e
  puts "Error: #{e.message}"
end