Ruby SDK - Lingo.dev SDK

简介

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