SDK de Ruby - Lingo.dev SDK

Introducción

El SDK de Ruby de Lingo.dev traduce texto, objetos Hash y conversaciones de chat con soporte para operaciones por lotes, seguimiento de progreso y procesamiento concurrente. Maneja cargas útiles grandes dividiendo automáticamente el contenido en tamaños de lote óptimos y admite glosarios para una terminología consistente.

Instalación

gem

gem install lingodotdev

Bundler

Añade a tu Gemfile:

gem 'lingodotdev'

Luego ejecuta:

bundle install

Traducción rápida

Omite la gestión de instancias para traducciones puntuales. Estos métodos manejan el ciclo de vida del motor automáticamente y utilizan el modo rápido por defecto, lo que los hace ideales para herramientas CLI y 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}"

Uso básico

El SDK requiere una clave 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

Traducción de texto con progreso

Realiza seguimiento del progreso de traducción con un callback. Incluso las cadenas de texto individuales pasan por el fragmentador, lo que permite informar el progreso para textos largos y proporciona un comportamiento consistente en todos los tipos de contenido.

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

Traducción de objetos

Traduce Hashes anidados preservando la estructura. El SDK procesa recursivamente todos los valores de cadena independientemente de la profundidad.

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

Traducción por lotes a múltiples idiomas

Traduce contenido a múltiples idiomas de destino en una sola llamada. Devuelve un array con un resultado por cada locale de destino, en el mismo orden solicitado.

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

Traducción de objetos por lotes

Localiza múltiples objetos al mismo locale de destino. Útil para procesar colecciones de elementos de contenido de manera eficiente.

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

Traducción de chat

Traduce mensajes de chat preservando los nombres de los interlocutores. Cada mensaje debe tener las claves :name y :text. Útil para localizar conversaciones de soporte, registros de chat o sistemas de diálogo sin perder la estructura de la conversación.

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

Procesamiento secuencial con progreso

El modo secuencial habilita callbacks de progreso detallados. El callback recibe el porcentaje de progreso por cada lote procesado, útil para depurar problemas de traducción o mostrar progreso detallado en interfaces de usuario.

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

Procesamiento concurrente

Procesa fragmentos en paralelo para una traducción más rápida. Este modo sacrifica el seguimiento del progreso por velocidad, haciéndolo ideal para cargas de trabajo en producción donde el rendimiento importa más que la retroalimentación al usuario.

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

Datos de referencia

Proporciona glosarios o traducciones previas para garantizar consistencia. Los datos de referencia se envían con cada fragmento a la API, así que mantenlos de tamaño razonable. Úsalos para términos de marca, vocabulario técnico o para mantener consistencia en las traducciones a través de actualizaciones del producto.

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

Configuración

Controla el comportamiento de procesamiento por lotes y los endpoints de la API. El SDK divide payloads grandes basándose en restricciones de cantidad de claves y cantidad de palabras, previniendo timeouts de la API y mejorando la confiabilidad para trabajos de traducción grandes.

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

También puedes configurar usando un bloque:

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

Detección de idioma

Detecta el idioma de una cadena de texto. Útil para enrutar automáticamente contenido al pipeline de traducción correcto o validar el idioma de entrada del usuario.

require 'lingodotdev'

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

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

Introspección de clave API

Verifica qué cuenta posee una clave API. Devuelve nil si la autenticación falla. Útil para depurar problemas de autenticación o mostrar información de cuenta en herramientas de administración.

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

Manejo de errores

El SDK define clases de excepción personalizadas para diferentes escenarios de error. Distingue entre errores de usuario (ValidationError) y problemas de infraestructura (ServerError, APIError) para aplicar la lógica de reintento apropiada.

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