Ruby SDK

Ruby 및 Lingo.dev를 사용한 AI 번역

소개

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는 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'])

# 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

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

순차 모드는 상세한 진행 상황 콜백을 활성화합니다. 콜백은 처리된 각 배치에 대한 진행률을 수신하며, 번역 문제를 디버깅하거나 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,              # 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