SDK Ruby

Traduction IA avec Ruby et Lingo.dev

Introduction

Le SDK Ruby de Lingo.dev traduit du texte, des objets Hash et des conversations de chat avec prise en charge des opérations par lots, du suivi de progression et du traitement concurrent. Il gère les charges utiles volumineuses en découpant automatiquement le contenu en lots de taille optimale et prend en charge les glossaires pour une terminologie cohérente.

Installation

gem

gem install lingodotdev

Bundler

Ajoutez à votre Gemfile :

gem 'lingodotdev'

Puis exécutez :

bundle install

Traduction rapide

Évitez la gestion d'instance pour des traductions ponctuelles. Ces méthodes gèrent automatiquement le cycle de vie du moteur et utilisent par défaut le mode rapide, ce qui les rend idéales pour les outils CLI et les scripts.

require 'lingodotdev'

# Traduire du texte

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

# Traduire un objet

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

Utilisation basique

Le SDK nécessite une clé API de 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

Traduction de texte avec suivi de progression

Suivez la progression de la traduction avec un callback. Même les chaînes de texte uniques passent par le découpeur, permettant ainsi de signaler la progression pour les textes longs et offrant un comportement cohérent pour tous les types de contenu.

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

Traduction d'objets

Traduisez des Hashes imbriqués tout en préservant leur structure. Le SDK traite récursivement toutes les valeurs de chaîne quelle que soit leur profondeur.

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

Traduction par lots vers plusieurs langues

Traduisez du contenu vers plusieurs langues cibles en un seul appel. Renvoie un tableau avec un résultat par locale cible, dans le même ordre que demandé.

require 'lingodotdev'

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

# Traduire du texte vers plusieurs langues

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

Traduction d'objets par lots

Localisez plusieurs objets vers la même locale cible. Utile pour traiter efficacement des collections d'éléments de contenu.

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

Traduction de chat

Traduisez des messages de chat tout en préservant les noms des interlocuteurs. Chaque message doit avoir à la fois les clés :name et :text. Utile pour localiser des conversations de support, des journaux de chat ou des systèmes de dialogue sans perdre la structure de la conversation.

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

Traitement séquentiel avec progression

Le mode séquentiel permet des rappels détaillés de progression. Le callback reçoit le pourcentage de progression pour chaque lot traité, utile pour déboguer les problèmes de traduction ou afficher une progression détaillée dans les interfaces utilisateur.

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

Traitement concurrent

Traitez les fragments en parallèle pour une traduction plus rapide. Ce mode sacrifie le suivi de la progression au profit de la vitesse, ce qui le rend idéal pour les charges de travail en production où le débit est plus important que le retour utilisateur.

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

Données de référence

Fournissez des glossaires ou des traductions précédentes pour assurer la cohérence. Les données de référence sont envoyées avec chaque fragment à l'API, donc gardez-les de taille raisonnable. Utilisez-les pour les termes de marque, le vocabulaire technique ou pour maintenir la cohérence des traductions lors des mises à jour de produits.

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

Configuration

Contrôlez le comportement de traitement par lots et les points de terminaison de l'API. Le SDK divise les charges utiles volumineuses en fonction des contraintes de nombre de clés et de nombre de mots, évitant ainsi les délais d'expiration de l'API et améliorant la fiabilité pour les travaux de traduction volumineux.

require 'lingodotdev'

engine = LingoDotDev::Engine.new(
  api_key: ENV['LINGODOTDEV_API_KEY'],
  api_url: 'https://engine.lingo.dev',
  batch_size: 25,              # Éléments par fragment (1-250)
  ideal_batch_item_size: 250   # Mots par fragment (1-2500)
)

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

puts result

Vous pouvez également configurer en utilisant un bloc :

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

Détection de langue

Détectez la langue d'une chaîne de texte. Utile pour acheminer automatiquement le contenu vers le pipeline de traduction approprié ou pour valider la langue saisie par l'utilisateur.

require 'lingodotdev'

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

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

Introspection de clé API

Vérifiez quel compte possède une clé API. Renvoie nil si l'authentification échoue. Utile pour déboguer les problèmes d'authentification ou afficher les informations du compte dans les outils d'administration.

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

Gestion des erreurs

Le SDK définit des classes d'exception personnalisées pour différents scénarios d'erreur. Distinguez les erreurs utilisateur (ValidationError) des problèmes d'infrastructure (ServerError, APIError) pour une logique de nouvelle tentative appropriée.

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