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_result}"

# 翻译对象

object_result = LingoDotDev::Engine.quick_translate(
  { greeting: 'Hello', farewell: 'Goodbye' },
  api_key: ENV['LINGODOTDEV_API_KEY'],
  target_locale: 'fr'
)
puts "对象：#{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}%"
end

puts "结果：#{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(
  '欢迎使用我们的应用',
  target_locales: ['es', 'fr', 'de'],
  fast: true
)
puts "文本结果: #{text_results}"

批量对象翻译

将多个对象本地化为相同的目标语言。这对于高效处理内容项集合非常有用。

require 'lingodotdev'

engine = LingoDotDev::Engine.new(api_key: ENV['LINGODOTDEV_API_KEY'])

objects = [
  { title: '欢迎', body: '你好' },
  { title: '关于', body: '了解更多关于我们的信息' },
  { title: '联系', body: '保持联系' }
]

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: '大家好！' },
  { name: 'Bob', text: '你们怎么样？' },
  { name: 'Alice', text: '很好，谢谢关心！' }
]

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

带进度的顺序处理

顺序模式支持详细的进度回调。回调会接收每批处理的进度百分比，这对于调试翻译问题或在用户界面中显示详细进度非常有用。

require 'lingodotdev'

content = {
  welcome: '你好',
  goodbye: '再见',
  help: '需要帮助吗？'
}

engine = LingoDotDev::Engine.new(api_key: ENV['LINGODOTDEV_API_KEY'])

result = engine.localize_object(content, target_locale: 'es') do |progress|
  puts "#{progress}% 完成"
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 "检测到的语言: #{locale}"

API 密钥检查

检查哪个账户拥有某个 API 密钥。如果身份验证失败，则返回 nil。这对于调试身份验证问题或在管理工具中显示账户信息非常有用。

require 'lingodotdev'

engine = LingoDotDev::Engine.new(api_key: ENV['LINGODOTDEV_API_KEY'])

user = engine.whoami
if user
  puts "已认证账户: #{user[:email]}"
else
  puts '身份验证失败'
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 "无效的参数或错误请求: #{e.message}"
rescue LingoDotDev::AuthenticationError => e
  puts "身份验证错误: #{e.message}"
rescue LingoDotDev::ServerError => e
  puts "服务器或网络错误: #{e.message}"
rescue LingoDotDev::APIError => e
  puts "API 错误: #{e.message}"
rescue LingoDotDev::Error => e
  puts "错误: #{e.message}"
end