Ruby SDK - Lingo.dev SDK

はじめに

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

複数言語への一括翻訳

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

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