SDK Ruby - Lingo.dev SDK

Introduction

Le SDK Ruby 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 tailles de lots optimales 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 les 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'

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

Utilisation de base

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 progression

Suivez la progression de la traduction avec un callback. Même les chaînes de texte uniques passent par le découpeur, permettant le rapport de 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 Hash imbriqués tout en préservant la structure. Le SDK traite récursivement toutes les valeurs de chaîne quelle que soit la 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'])

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

Traduction d'objets par lot

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 contenir à la fois les clés :name et :text. Utile pour localiser des conversations d'assistance, 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 callbacks de progression détaillés. 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 progression au profit de la vitesse, ce qui le rend idéal pour les charges de travail en production où le débit compte plus 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 garantir la cohérence. Les données de référence sont envoyées avec chaque fragment à l'API, gardez donc une taille raisonnable. Utilisez ceci pour les termes de marque, le vocabulaire technique ou pour maintenir la cohérence des traductions lors des mises à jour de produit.

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 du traitement par lots et les endpoints de l'API. Le SDK divise les grandes charges utiles en fonction du nombre de clés et du nombre de mots, évitant les timeouts de l'API et améliorant la fiabilité pour les gros travaux de traduction.

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

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 router automatiquement le contenu vers le pipeline de traduction approprié ou valider la langue de saisie 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 de 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