A Ruby SDK for integrating with the Lingo.dev localization and translation API. Localize text, objects, and chat messages with support for batch operations, progress tracking, and concurrent processing.
The Lingo.dev Ruby SDK provides a simple and powerful interface for localizing content in your Ruby applications. It supports:
- Text, object (Hash), and chat message localization
- Batch operations for multiple locales or objects
- Automatic locale recognition
- Progress tracking with callbacks
- Concurrent processing for improved performance
- Comprehensive error handling and validation
Add this line to your application's Gemfile:
gem'lingodotdev'And then execute:
bundle installOr install it yourself with:
gem install lingodotdevrequire'lingodotdev'# Create an engine instanceengine=LingoDotDev::Engine.new(api_key: 'your-api-key',engine_id: 'your-engine-id')# Localize textresult=engine.localize_text('Hello world',target_locale: 'es',source_locale: 'en')putsresult# => "Hola mundo"Localize a simple string to a target locale:
engine=LingoDotDev::Engine.new(api_key: 'your-api-key',engine_id: 'your-engine-id')result=engine.localize_text('Hello world',target_locale: 'es',source_locale: 'en')# => "Hola mundo"Localize all string values in a Hash:
data={greeting: 'Hello',farewell: 'Goodbye',message: 'Welcome to our app'}result=engine.localize_object(data,target_locale: 'es',source_locale: 'en')# => {# greeting: "Hola",# farewell: "Adiós",# message: "Bienvenido a nuestra aplicación"# }Localize chat conversations while preserving structure:
chat=[{name: 'user',text: 'Hello!'},{name: 'assistant',text: 'Hi there! How can I help you?'},{name: 'user',text: 'I need some information.'}]result=engine.localize_chat(chat,target_locale: 'ja',source_locale: 'en')# => [# { name: 'user', text: 'こんにちは！' },# { name: 'assistant', text: 'こんにちは！どのようにお手伝いできますか？' },# { name: 'user', text: '情報が必要です。' }# ]Localize HTML documents while preserving structure and formatting:
html=<<~HTML<html><head><title>Welcome</title><metaname="description" content="Page description"></head><body><h1>Hello World</h1><p>This is a paragraph with <ahref="/test" title="Link title">a link</a>.</p><imgsrc="/image.jpg" alt="Test image"><inputtype="text" placeholder="Enter text"></body></html>HTMLresult=engine.localize_html(html,target_locale: 'es',source_locale: 'en')# => HTML with localized text content and attributes, lang="es" attribute updatedThe method handles:
- Text content in all elements
- Localizable attributes:
metacontent,imgalt,inputplaceholder,atitle - Preserves HTML structure and formatting
- Ignores content inside
scriptandstyletags - Updates the
langattribute on thehtmlelement
Localize the same content to multiple target locales:
# Batch localize textresults=engine.batch_localize_text('Hello world',target_locales: ['es','fr','de'],source_locale: 'en')# => ["Hola mundo", "Bonjour le monde", "Hallo Welt"]# With concurrent processing for better performanceresults=engine.batch_localize_text('Hello world',target_locales: ['es','fr','de','ja'],source_locale: 'en',concurrent: true)Localize multiple objects to the same target locale:
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',source_locale: 'en',concurrent: true)# => [# { title: "Bienvenido", body: "Hola" },# { title: "Acerca de", body: "Aprende más sobre nosotros" },# { title: "Contacto", body: "Ponte en contacto" }# ]Automatically detect the locale of a given text:
locale=engine.recognize_locale('Bonjour le monde')# => "fr"Monitor localization progress with callbacks:
# Using a blockresult=engine.localize_text('Hello world',target_locale: 'es',source_locale: 'en')do |progress|
puts"Progress: #{progress}%"end# Using the on_progress parametercallback=proc{ |progress| puts"Progress: #{progress}%"}result=engine.localize_text('Hello world',target_locale: 'es',source_locale: 'en',on_progress: callback)Provide existing translations as reference to improve translation accuracy. The reference hash maps locale codes to key-value content objects:
reference={'es'=>{'greeting'=>'Hola','farewell'=>'Adiós'},'fr'=>{'greeting'=>'Bonjour','farewell'=>'Au revoir'}}result=engine.localize_text('Hello',target_locale: 'ja',source_locale: 'en',reference: reference)For one-off translations without managing engine instances:
# Quick translate a stringresult=LingoDotDev::Engine.quick_translate('Hello world',api_key: 'your-api-key',engine_id: 'your-engine-id',target_locale: 'es',source_locale: 'en')# Quick translate a hashresult=LingoDotDev::Engine.quick_translate({greeting: 'Hello',farewell: 'Goodbye'},api_key: 'your-api-key',engine_id: 'your-engine-id',target_locale: 'fr',source_locale: 'en')# Quick batch translate to multiple localesresults=LingoDotDev::Engine.quick_batch_translate('Hello',api_key: 'your-api-key',engine_id: 'your-engine-id',target_locales: ['es','fr','de'],source_locale: 'en')Check the authenticated user details:
user=engine.whoami# => { email: "user@example.com", id: "user-id" }The SDK can be configured when creating an engine instance:
engine=LingoDotDev::Engine.new(api_key: 'your-api-key',# Required: Your Lingo.dev API keyengine_id: 'your-engine-id',# Optional: Your engine IDapi_url: 'https://api.lingo.dev',# Optional: API endpoint URLbatch_size: 25,# Optional: Max items per batch (1-250)ideal_batch_item_size: 250# Optional: Target word count per batch (1-2500))You can also configure using a block:
engine=LingoDotDev::Engine.new(api_key: 'your-api-key',engine_id: 'your-engine-id')do |config|
config.batch_size=50config.ideal_batch_item_size=500end| Option | Type | Default | Description |
|---|---|---|---|
api_key | String | Required | Your Lingo.dev API key |
engine_id | String | nil | Your engine ID for localization processing |
api_url | String | https://api.lingo.dev | API endpoint URL |
batch_size | Integer | 25 | Maximum items per batch (1-250) |
ideal_batch_item_size | Integer | 250 | Target word count per batch item (1-2500) |
localize_text(text, target_locale:, source_locale:, reference: nil, on_progress: nil, concurrent: false, &block)
Localizes a string to the target locale.
- Parameters:
text(String): Text to localizetarget_locale(String): Target locale code (e.g., 'es', 'fr', 'ja')source_locale(String): Source locale code (e.g., 'en')reference(Hash, optional): Existing translations keyed by locale code, e.g.{ 'es' => { 'key' => 'valor' } }on_progress(Proc, optional): Progress callbackconcurrent(Boolean): Enable concurrent processing&block: Alternative progress callback
- Returns: Localized string
localize_object(obj, target_locale:, source_locale:, reference: nil, on_progress: nil, concurrent: false, &block)
Localizes all string values in a Hash.
- Parameters: Same as
localize_text, withobj(Hash) instead oftext - Returns: Localized Hash
localize_chat(chat, target_locale:, source_locale:, reference: nil, on_progress: nil, concurrent: false, &block)
Localizes chat messages. Each message must have :name and :text keys.
- Parameters: Same as
localize_text, withchat(Array) instead oftext - Returns: Array of localized chat messages
localize_html(html, target_locale:, source_locale:, reference: nil, on_progress: nil, concurrent: false, &block)
Localizes an HTML document while preserving structure and formatting. Handles both text content and localizable attributes (alt, title, placeholder, meta content).
- Parameters:
html(String): HTML document string to localizetarget_locale(String): Target locale code (e.g., 'es', 'fr', 'ja')source_locale(String): Source locale code (e.g., 'en')reference(Hash, optional): Existing translations keyed by locale code, e.g.{ 'es' => { 'key' => 'valor' } }on_progress(Proc, optional): Progress callbackconcurrent(Boolean): Enable concurrent processing&block: Alternative progress callback
- Returns: Localized HTML document string with updated
langattribute
Localizes text to multiple target locales.
- Parameters:
text(String): Text to localizetarget_locales(Array): Array of target locale codes- Other parameters same as
localize_text
- Returns: Array of localized strings
Localizes multiple objects to the same target locale.
- Parameters:
objects(Array): Array of Hash objectstarget_locale(String): Target locale code- Other parameters same as
localize_object
- Returns: Array of localized Hash objects
Detects the locale of the given text.
- Parameters:
text(String): Text to analyze
- Returns: Locale code string
Returns information about the authenticated user.
- Returns: Hash with
:emailand:idkeys, ornilif authentication fails
Engine.quick_translate(content, api_key:, engine_id: nil, target_locale:, source_locale:, api_url: 'https://api.lingo.dev')
One-off translation without managing engine lifecycle.
- Parameters:
content(String or Hash): Content to translate- Other parameters as in instance methods
- Returns: Translated String or Hash
Engine.quick_batch_translate(content, api_key:, engine_id: nil, target_locales:, source_locale:, api_url: 'https://api.lingo.dev')
One-off batch translation to multiple locales.
- Parameters:
content(String or Hash): Content to translatetarget_locales(Array): Array of target locale codes- Other parameters as in instance methods
- Returns: Array of translated results
The SDK defines custom exception classes for different error scenarios:
beginengine=LingoDotDev::Engine.new(api_key: 'your-api-key')result=engine.localize_text('Hello',target_locale: 'es',source_locale: 'en')rescueLingoDotDev::ValidationError=>e# Invalid input or configurationputs"Validation error: #{e.message}"rescueLingoDotDev::AuthenticationError=>e# Invalid API key or authentication failureputs"Authentication error: #{e.message}"rescueLingoDotDev::ServerError=>e# Server-side error (5xx)puts"Server error: #{e.message}"rescueLingoDotDev::APIError=>e# General API errorputs"API error: #{e.message}"rescueLingoDotDev::Error=>e# Base error class for all SDK errorsputs"Error: #{e.message}"endLingoDotDev::Error(base class)LingoDotDev::ArgumentErrorLingoDotDev::ValidationError- Invalid input or configuration
LingoDotDev::APIError- API request errorsLingoDotDev::AuthenticationError- Authentication failuresLingoDotDev::ServerError- Server-side errors (5xx)
After checking out the repository, run bin/setup to install dependencies.
To run the test suite:
# Set your API keyexport LINGODOTDEV_API_KEY='your-api-key'# Run tests
bundle exec rspecYou can also run bin/console for an interactive prompt to experiment with the SDK.
To install this gem onto your local machine, run:
bundle exec rake install- Ruby >= 3.2.0
json~> 2.0nokogiri~> 1.0
See the LICENSE file for details.
Contributions are welcome! Please feel free to submit a Pull Request.