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 parallele Verarbeitung. Es verarbeitet große Datenmengen, 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 Ihrer Gemfile hinzu:

gem 'lingodotdev'

Dann führen Sie 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 Schnellmodus, was sie ideal für CLI-Tools und Skripte macht.

require 'lingodotdev'

# Text übersetzen

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

# Objekt übersetzen

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 Fortschrittsanzeige

Verfolgen Sie den Übersetzungsfortschritt mit einem Callback. Selbst einzelne Textstrings durchlaufen den Chunker, was eine Fortschrittsberichterstattung 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 Ziel-Locale zurück, in der gleichen Reihenfolge wie angefordert.

require 'lingodotdev'

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

# Text in mehrere Sprachen übersetzen

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 Inhaltssammlungen.

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 Schlüssel haben. Nützlich für die Lokalisierung von Support-Gesprächen, Chat-Protokollen oder Dialogsystemen ohne Verlust der Gesprächsstruktur.

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

Sequentielle Verarbeitung mit Fortschrittsanzeige

Der sequentielle Modus ermöglicht detaillierte Fortschritts-Callbacks. Der Callback erhält den Fortschrittsprozentsatz für jeden verarbeiteten Batch, was nützlich ist für die Fehlersuche bei Übersetzungsproblemen oder die Anzeige detaillierter Fortschritte in Benutzeroberflächen.

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 die Fortschrittsverfolgung zugunsten der Geschwindigkeit und ist ideal für Produktionsworkloads, bei denen der Durchsatz wichtiger ist als Benutzerfeedback.

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 zu gewährleisten. Referenzdaten werden mit jedem Chunk an die API gesendet, halten Sie sie daher in angemessener Größe. Verwenden Sie dies für Markenbezeichnungen, technisches Vokabular oder zur Aufrechterhaltung der Übersetzungskonsistenz bei Produktaktualisierungen.

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 die API-Endpunkte. Das SDK teilt große Payloads basierend auf Schlüsselanzahl- und Wortanzahlbeschränkungen auf, verhindert API-Timeouts und verbessert die Zuverlässigkeit bei großen Übersetzungsaufträgen.

require 'lingodotdev'

engine = LingoDotDev::Engine.new(
  api_key: ENV['LINGODOTDEV_API_KEY'],
  api_url: 'https://engine.lingo.dev',
  batch_size: 25,              # Items pro Chunk (1-250)
  ideal_batch_item_size: 250   # Wörter pro 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

Erkennt die Sprache eines Textes. Nützlich für die automatische Weiterleitung von Inhalten an die richtige Übersetzungspipeline oder zur Validierung der Benutzerspracheingabe.

require 'lingodotdev'

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

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

API-Schlüssel-Introspection

Überprüft, welchem Konto ein API-Schlüssel gehört. Gibt nil zurück, wenn die Authentifizierung fehlschlägt. Nützlich zur Fehlersuche bei 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 Ausnahmeklassen für verschiedene Fehlerszenarien. Unterscheidet zwischen Benutzerfehlern (ValidationError) und Infrastrukturproblemen (ServerError, APIError) für eine angemessene Wiederholungslogik.

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