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 grandes dividiendo automáticamente el contenido en tamaños óptimos de lotes y soporta 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, haciéndolos ideales para herramientas CLI y scripts.

require 'lingodotdev'

# Traducir texto

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

# Traducir objeto

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 fraccionador, permitiendo informes de progreso para textos largos y proporcionando 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 su 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 localización de destino, en el mismo orden que se solicitó.

require 'lingodotdev'

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

# Traducir texto a múltiples idiomas

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 a la misma localización 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 permite callbacks detallados de progreso. El callback recibe el porcentaje de progreso para cada lote procesado, útil para depurar problemas de traducción o mostrar un 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 de producción donde el rendimiento importa más que la retroalimentación del 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 la consistencia. Los datos de referencia se envían con cada fragmento a la API, así que mantenlos de un tamaño razonable. Utiliza esto para términos de marca, vocabulario técnico o para mantener la consistencia de traducción en las 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 las cargas grandes basándose en restricciones de recuento de claves y palabras, evitando tiempos de espera de la API y mejorando la fiabilidad 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,              # Elementos por fragmento (1-250)
  ideal_batch_item_size: 250   # Palabras por fragmento (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 dirigir automáticamente el contenido al proceso 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

Comprueba 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 la 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 una 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