Ruby SDK - Lingo.dev SDK

はじめに

Lingo.dev Ruby SDKは、バッチ操作、進捗追跡、並行処理をサポートし、テキスト、Hashオブジェクト、チャット会話を翻訳します。大きなペイロードを最適なバッチサイズに自動的にチャンク化して処理し、一貫した用語のためのグロッサリーをサポートします。

インストール

gem

gem install lingodotdev

Bundler

Gemfileに追加:

gem 'lingodotdev'

その後、実行:

bundle install

クイック翻訳

1回限りの翻訳のためのインスタンス管理をスキップします。これらのメソッドはエンジンのライフサイクルを自動的に処理し、デフォルトで高速モードを使用するため、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

複数言語へのバッチ翻訳

1回の呼び出しで複数のターゲット言語にコンテンツを翻訳します。リクエストされた順序で、ターゲットロケールごとに1つの結果を含む配列を返します。

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