Ruby SDK

AI-перевод с использованием Ruby и Lingo.dev

Введение

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

Установка

gem

gem install lingodotdev

Bundler

Добавьте в ваш Gemfile:

gem 'lingodotdev'

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

bundle install

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

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

require 'lingodotdev'

# Перевод текста

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

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

object_result = LingoDotDev::Engine.quick_translate(
  { greeting: 'Hello', farewell: 'Goodbye' },
  api_key: ENV['LINGODOTDEV_API_KEY'],
  target_locale: 'fr'
)
puts "Объект: #{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

Перевод текста с отслеживанием прогресса

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

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

puts "Результат: #{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'])

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

text_results = engine.batch_localize_text(
  'Добро пожаловать в наше приложение',
  target_locales: ['es', 'fr', 'de'],
  fast: true
)
puts "Результаты текста: #{text_results}"

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

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

require 'lingodotdev'

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

objects = [
  { title: 'Добро пожаловать', body: 'Привет!' },
  { title: 'О нас', body: 'Узнайте больше о нас' },
  { title: 'Контакты', body: 'Свяжитесь с нами' }
]

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: 'Алиса', text: 'Всем привет!' },
  { name: 'Боб', text: 'Как дела?' },
  { name: 'Алиса', text: 'Отлично, спасибо, что спросил!' }
]

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: 'Привет',
  goodbye: 'Прощай',
  help: 'Нужна помощь?'
}

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

result = engine.localize_object(content, target_locale: 'es') do |progress|
  puts "#{progress}% завершено"
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 разделяет большие данные на основе количества ключей и ограничений по количеству слов, предотвращая тайм-ауты API и повышая надежность для крупных задач локализации.

require 'lingodotdev'

engine = LingoDotDev::Engine.new(
  api_key: ENV['LINGODOTDEV_API_KEY'],
  api_url: 'https://engine.lingo.dev',
  batch_size: 25,              # Элементов в пакете (1-250)
  ideal_batch_item_size: 250   # Слов в пакете (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 "Обнаруженный язык: #{locale}"

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

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

require 'lingodotdev'

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

user = engine.whoami
if user
  puts "Аутентифицирован как: #{user[:email]}"
else
  puts 'Аутентификация не удалась'
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 "Неверные параметры или некорректный запрос: #{e.message}"
rescue LingoDotDev::AuthenticationError => e
  puts "Ошибка аутентификации: #{e.message}"
rescue LingoDotDev::ServerError => e
  puts "Ошибка сервера или сети: #{e.message}"
rescue LingoDotDev::APIError => e
  puts "Ошибка API: #{e.message}"
rescue LingoDotDev::Error => e
  puts "Ошибка: #{e.message}"
end