Ruby SDK

Ruby와 Lingo.dev를 이용한 AI 번역

소개

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: #{text_result}"

# 객체 번역

object_result = LingoDotDev::Engine.quick_translate(
  { greeting: 'Hello', farewell: 'Goodbye' },
  api_key: ENV['LINGODOTDEV_API_KEY'],
  target_locale: 'fr'
)
puts "Object: #{object_result}"

기본 사용법

SDK는 Lingo.dev의 API 키가 필요합니다.

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: #{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'])

# 여러 언어로 텍스트 번역

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

진행 상황이 포함된 순차적 처리

순차 모드는 상세한 진행 상황 콜백을 가능하게 합니다. 콜백은 처리된 각 배치에 대한 진행률 백분율을 수신하며, 번역 문제를 디버깅하거나 UI에서 상세한 진행 상황을 표시하는 데 유용합니다.

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는 키 수와 단어 수 제약에 따라 큰 페이로드를 분할하여 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 "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