Ruby SDK

AI-перевод с помощью Ruby и Lingo.dev

Введение

Lingo.dev Ruby SDK переводит текст, объекты Hash и чаты с поддержкой пакетных операций, отслеживания прогресса и параллельной обработки. Он справляется с большими объёмами данных, автоматически разбивая их на оптимальные пакеты, и поддерживает глоссарии для единообразия терминологии.

Установка

gem

gem install lingodotdev

Bundler

Добавьте в Gemfile:

gem 'lingodotdev'

Затем выполните:

bundle install

Быстрый перевод

Пропустите управление экземплярами для разовых переводов. Эти методы сами управляют жизненным циклом движка и по умолчанию используют быстрый режим — идеально для CLI-инструментов и скриптов.

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

Базовое использование

Для работы SDK нужен API-ключ 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

Перевод текста с прогрессом

Отслеживайте прогресс перевода с помощью callback-функции. Даже одиночные строки проходят через chunker, что позволяет отслеживать прогресс при длинных текстах и обеспечивает одинаковое поведение для всех типов контента.

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

Перевод объектов

Переводите вложенные Hash-объекты с сохранением структуры. SDK рекурсивно обрабатывает все строковые значения на любой глубине.

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

Пакетный перевод на несколько языков

Переводите контент на несколько целевых языков за один вызов. Возвращается массив с результатами для каждого языка в том же порядке, в котором они были запрошены.

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

Пакетный перевод объектов

Локализуйте несколько объектов на один целевой язык. Полезно для эффективной обработки коллекций контента.

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

Перевод чатов

Переводите сообщения чата с сохранением имён участников. В каждом сообщении должны быть ключи :name и :text. Это удобно для локализации поддержки, логов чатов или диалоговых систем без потери структуры беседы.

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

Последовательная обработка с прогрессом

В последовательном режиме доступны подробные обратные вызовы о прогрессе. Колбэк получает процент выполнения для каждой обработанной партии — это удобно для отладки переводов или отображения прогресса в интерфейсе.

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

Параллельная обработка

Обрабатывайте части данных параллельно для более быстрого перевода. В этом режиме отслеживание прогресса жертвуется ради скорости, что идеально для продакшн-нагрузок, где важна производительность, а не обратная связь.

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

Справочные данные

Передавайте глоссарии или предыдущие переводы для обеспечения согласованности. Справочные данные отправляются с каждым чанком в API, поэтому держите их компактными. Используйте это для бренд-терминов, технической лексики или поддержания единого стиля перевода при обновлениях продукта.

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

Конфигурация

Управляйте поведением пакетирования и конечными точками API. SDK разбивает большие данные по количеству ключей и слов, чтобы избежать таймаутов и повысить надёжность при больших задачах перевода.

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

Можно также настроить через блок:

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

Определение языка

Определяйте язык текстовой строки. Это удобно для автоматической маршрутизации контента в нужный переводческий пайплайн или проверки языка пользовательского ввода.

require 'lingodotdev'

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

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

Интроспекция API-ключа

Проверьте, какой аккаунт владеет API-ключом. Возвращает nil, если аутентификация не удалась. Полезно для отладки проблем с аутентификацией или отображения информации об аккаунте в админ-инструментах.

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

Обработка ошибок

SDK определяет собственные классы исключений для разных сценариев ошибок. Различайте пользовательские ошибки (ValidationError) и инфраструктурные проблемы (ServerError, APIError) для правильной логики повторных попыток.

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