This SDK empowers you to build your own branded translation AI leveraging our translation fine-tuned language model.
All major translation features are accessible, making it easy to integrate and customize for your needs.
- Text Translation: Single strings, multiple strings, and complex text blocks
- Document Translation: Word, PDF, and other document formats with status monitoring
- Image Translation: Translate whole images or extract and translate text blocks
- Audio Translation: Translate audio files with status monitoring
- Translation Memory: Store and reuse translations for consistency
- Glossaries: Enforce terminology standards across translations
- Language Detection: Automatic source language identification
- Advanced Options: Translation instructions and more
Lara's SDK full documentation is available at https://developers.laratranslate.com/
Add this line to your application's Gemfile:
gem 'lara-sdk'And then execute:
$ bundle install
Or install it yourself as:
$ gem install lara-sdk
require 'lara'
# Set your credentials using environment variables (recommended)
credentials = Lara::Credentials.new(
ENV['LARA_ACCESS_KEY_ID'],
ENV['LARA_ACCESS_KEY_SECRET']
)
# Create translator instance
lara = Lara::Translator.new(credentials: credentials)
# Simple text translation
begin
result = lara.translate("Hello, world!", target: "fr-FR", source: "en-US")
puts "Translation: #{result.translation}"
# Output: Translation: Bonjour, le monde !
rescue => error
puts "Translation error: #{error.message}"
endThe examples/ directory contains comprehensive examples for all SDK features.
All examples use environment variables for credentials, so set them first:
export LARA_ACCESS_KEY_ID="your-access-key-id"
export LARA_ACCESS_KEY_SECRET="your-access-key-secret"- text_translation.rb - Complete text translation examples
- Single string translation
- Multiple strings translation
- Translation with instructions
- TextBlocks translation (mixed translatable/non-translatable content)
- Auto-detect source language
- Advanced translation options
- Get available languages
cd examples
ruby text_translation.rb- document_translation.rb - Document translation examples
- Basic document translation
- Advanced options with memories and glossaries
- Step-by-step translation with status monitoring
cd examples
ruby document_translation.rb- image_translation.rb - Image translation examples
- Basic image translation
- Advanced options with memories and glossaries
- Extract and translate text from an image
cd examples
ruby image_translation.rb- audio_translation.rb - Audio translation examples
- Basic audio translation
- Advanced options with memories and glossaries
- Step-by-step audio translation with status monitoring
cd examples
ruby audio_translation.rb- memories_management.rb - Memory management examples
- Create, list, update, delete memories
- Add individual translations
- Multiple memory operations
- TMX file import with progress monitoring
- Translation deletion
- Translation with TUID and context
cd examples
ruby memories_management.rb- glossaries_management.rb - Glossary management examples
- Create, list, update, delete glossaries
- Individual term management (add/remove terms)
- CSV import with status monitoring
- Glossary export
- Glossary terms count
- Import status checking
- Add or replace glossary entries
- Delete glossary entries
cd examples
ruby glossaries_management.rbThe SDK supports authentication via access key and secret:
require 'lara'
credentials = Lara::Credentials.new("your-access-key-id", "your-access-key-secret")
lara = Lara::Translator.new(credentials: credentials)Environment Variables (Recommended):
export LARA_ACCESS_KEY_ID="your-access-key-id"
export LARA_ACCESS_KEY_SECRET="your-access-key-secret"require 'lara'
credentials = Lara::Credentials.new(
ENV['LARA_ACCESS_KEY_ID'],
ENV['LARA_ACCESS_KEY_SECRET']
)
lara = Lara::Translator.new(credentials: credentials)Alternative Constructor:
# You can also pass credentials directly to Translator
lara = Lara::Translator.new(
access_key_id: "your-access-key-id",
access_key_secret: "your-access-key-secret"
)# Create translator with credentials
lara = Lara::Translator.new(credentials: credentials)# Basic translation
result = lara.translate("Hello", target: "fr-FR", source: "en-US")
# Multiple strings
result = lara.translate(["Hello", "World"], target: "fr-FR", source: "en-US")
# TextBlocks (mixed translatable/non-translatable content)
require 'lara'
text_blocks = [
Lara::Models::TextBlock.new(text: "Translatable text", translatable: true),
Lara::Models::TextBlock.new(text: "<br>", translatable: false), # Non-translatable HTML
Lara::Models::TextBlock.new(text: "More translatable text", translatable: true)
]
result = lara.translate(text_blocks, target: "fr-FR", source: "en-US")
# With advanced options
result = lara.translate(
"Hello",
target: "fr-FR",
source: "en-US",
instructions: ["Formal tone"],
adapt_to: ["mem_1A2b3C4d5E6f7G8h9I0jKl"], # Replace with actual memory IDs
glossaries: ["gls_1A2b3C4d5E6f7G8h9I0jKl"], # Replace with actual glossary IDs
style: "fluid",
timeout_ms: 10000
)# Replace with your actual file path
translated_content = lara.documents.translate(
file_path: "/path/to/your/document.txt",
filename: "document.txt",
source: "en-US",
target: "fr-FR"
)
# With options
translated_content = lara.documents.translate(
file_path: "/path/to/your/document.txt", # Replace with actual file path
filename: "document.txt",
source: "en-US",
target: "fr-FR",
adapt_to: ["mem_1A2b3C4d5E6f7G8h9I0jKl"], # Replace with actual memory IDs
glossaries: ["gls_1A2b3C4d5E6f7G8h9I0jKl"], # Replace with actual glossary IDs
style: "fluid"
)#Optional: upload options
document = lara.documents.upload(
file_path: "/path/to/your/document.txt", # Replace with actual file path
filename: "document.txt",
source: "en-US",
target: "fr-FR",
adapt_to: ["mem_1A2b3C4d5E6f7G8h9I0jKl"], # Replace with actual memory IDs
glossaries: ["gls_1A2b3C4d5E6f7G8h9I0jKl"] # Replace with actual glossary IDs
)status = lara.documents.status(document.id)translated_content = lara.documents.download(document.id)require 'lara'
# Translate an image and receive a translated image as binary data
translated_image = lara.images.translate(
file_path: "/path/to/your/image.png", # Replace with actual file path
source: "en",
target: "fr",
text_removal: "inpainting",
style: "faithful"
)
# Save the translated image
File.binwrite("translated_image.png", translated_image)
# Extract and translate text blocks from an image
result = lara.images.translate_text(
file_path: "/path/to/your/image.png", # Replace with actual file path
source: "en",
target: "fr",
adapt_to: ["mem_1A2b3C4d5E6f7G8h9I0jKl"], # Replace with actual memory IDs
glossaries: ["gls_1A2b3C4d5E6f7G8h9I0jKl"] # Replace with actual glossary IDs
)
result.paragraphs.each do |paragraph|
puts "Original: #{paragraph.text}"
puts "Translated: #{paragraph.translation}"
end# Replace with your actual file path
translated_content = lara.audio.translate(
file_path: "/path/to/your/audio.mp3",
filename: "audio.mp3",
source: "en-US",
target: "fr-FR"
)
# With options
translated_content = lara.audio.translate(
file_path: "/path/to/your/audio.mp3", # Replace with actual file path
filename: "audio.mp3",
source: "en-US",
target: "fr-FR",
adapt_to: ["mem_1A2b3C4d5E6f7G8h9I0jKl"], # Replace with actual memory IDs
glossaries: ["gls_1A2b3C4d5E6f7G8h9I0jKl"], # Replace with actual glossary IDs
style: "fluid"
)#Optional: upload options
audio = lara.audio.upload(
file_path: "/path/to/your/audio.mp3", # Replace with actual file path
filename: "audio.mp3",
source: "en-US",
target: "fr-FR",
adapt_to: ["mem_1A2b3C4d5E6f7G8h9I0jKl"], # Replace with actual memory IDs
glossaries: ["gls_1A2b3C4d5E6f7G8h9I0jKl"] # Replace with actual glossary IDs
)status = lara.audio.status(audio.id)translated_content = lara.audio.download(audio.id)# Create memory
memory = lara.memories.create("MyMemory")
# Create memory with external ID (MyMemory integration)
memory = lara.memories.create("Memory from MyMemory", external_id: "aabb1122") # Replace with actual external ID
# Important: To update/overwrite a translation unit you must provide a tuid. Calls without a tuid always create a new unit and will not update existing entries.
# Add translation to single memory
memory_import = lara.memories.add_translation("mem_1A2b3C4d5E6f7G8h9I0jKl", "en-US", "fr-FR", "Hello", "Bonjour", tuid: "greeting_001")
# Add translation to multiple memories
memory_import = lara.memories.add_translation(["mem_1A2b3C4d5E6f7G8h9I0jKl", "mem_2XyZ9AbC8dEf7GhI6jKlMn"], "en-US", "fr-FR", "Hello", "Bonjour", tuid: "greeting_002")
# Add with context
memory_import = lara.memories.add_translation(
"mem_1A2b3C4d5E6f7G8h9I0jKl", "en-US", "fr-FR", "Hello", "Bonjour",
tuid: "tuid", sentence_before: "sentenceBefore", sentence_after: "sentenceAfter"
)
# TMX import from file
memory_import = lara.memories.import_tmx("mem_1A2b3C4d5E6f7G8h9I0jKl", "/path/to/your/memory.tmx") # Replace with actual TMX file path
# Delete translation
# Important: if you omit tuid, all entries that match the provided fields will be removed
delete_job = lara.memories.delete_translation(
"mem_1A2b3C4d5E6f7G8h9I0jKl", "en-US", "fr-FR", "Hello", "Bonjour", tuid: "greeting_001"
)
# Wait for import completion
completed_import = lara.memories.wait_for_import(memory_import, max_wait_time: 300) # 5 minutes# Create glossary
glossary = lara.glossaries.create("MyGlossary")
# Import unidirectional CSV from file
glossary_import = lara.glossaries.import_csv("gls_1A2b3C4d5E6f7G8h9I0jKl", "/path/to/your/glossary.csv") # Replace with actual CSV file path
# Import multidirectional CSV from file
glossary_import = lara.glossaries.import_csv(
"gls_1A2b3C4d5E6f7G8h9I0jKl",
"/path/to/your/multidirectional_glossary.csv", # Replace with actual CSV file path
content_type: Lara::Glossaries::FileFormat::MULTIDIRECTIONAL
)
# Add (or replace) individual terms to glossary (unidirectional)
terms = [
{ language: "fr-FR", value: "Bonjour" },
{ language: "es-ES", value: "Hola" }
]
lara.glossaries.add_or_replace_entry("gls_1A2b3C4d5E6f7G8h9I0jKl", terms)
# Add (or replace) a multidirectional entry with a custom GUID
terms_with_guid = [
{ language: "en-US", value: "keyboard" },
{ language: "it-IT", value: "tastiera" },
{ language: "fr-FR", value: "clavier" }
]
lara.glossaries.add_or_replace_entry("gls_1A2b3C4d5E6f7G8h9I0jKl", terms_with_guid, guid: "custom-guid-123")
# Remove a specific term from glossary
term_to_remove = { language: "fr-FR", value: "Bonjour" }
lara.glossaries.delete_entry("gls_1A2b3C4d5E6f7G8h9I0jKl", term: term_to_remove)
# Remove a multidirectional entry by GUID
lara.glossaries.delete_entry("gls_1A2b3C4d5E6f7G8h9I0jKl", guid: "custom-guid-123")
# Check import status
import_status = lara.glossaries.get_import_status(import_id)
# Wait for import completion
completed_import = lara.glossaries.wait_for_import(glossary_import, max_wait_time: 300) # 5 minutes
# Export glossary (unidirectional)
csv_data = lara.glossaries.export("gls_1A2b3C4d5E6f7G8h9I0jKl",
content_type: Lara::Glossaries::FileFormat::UNIDIRECTIONAL,
source: "en-US")
# Export glossary (multidirectional)
csv_data = lara.glossaries.export("gls_1A2b3C4d5E6f7G8h9I0jKl",
content_type: Lara::Glossaries::FileFormat::MULTIDIRECTIONAL)
# Get glossary terms count (includes both unidirectional and multidirectional counts)
counts = lara.glossaries.counts("gls_1A2b3C4d5E6f7G8h9I0jKl")result = lara.translate(
text,
target: "fr-FR", # Target language (required)
source: "en-US", # Source language (optional, auto-detect if nil)
source_hint: "en", # Hint for source language detection
adapt_to: ["memory-id"], # Memory IDs to adapt to
glossaries: ["glossary-id"], # Glossary IDs to use
instructions: ["instruction"], # Translation instructions
style: "fluid", # Translation style (fluid, faithful, creative)
content_type: "text/plain", # Content type (text/plain, text/html, etc.)
multiline: true, # Enable multiline translation
timeout_ms: 10000, # Request timeout in milliseconds
no_trace: false, # Disable request tracing
verbose: false, # Enable verbose response
)The SDK supports full language codes (e.g., en-US, fr-FR, es-ES) as well as simple codes (e.g., en, fr, es):
# Full language codes (recommended)
result = lara.translate("Hello", target: "fr-FR", source: "en-US")
# Simple language codes
result = lara.translate("Hello", target: "fr", source: "en")The SDK supports all languages available in the Lara API. Use the get_languages() method to get the current list:
languages = lara.get_languages
puts "Supported languages: #{languages.join(', ')}"The SDK provides detailed error information:
begin
result = lara.translate("Hello", target: "fr-FR", source: "en-US")
puts "Translation: #{result.translation}"
rescue Lara::LaraApiError => error
puts "API Error [#{error.status_code}]: #{error.message}"
puts "Error type: #{error.type}"
rescue Lara::LaraError => error
puts "SDK Error: #{error.message}"
rescue => error
puts "Unexpected error: #{error.message}"
end- Ruby 2.6 or higher
- Bundler
- Valid Lara API credentials
Run the examples to test your setup:
# All examples use environment variables for credentials, so set them first:
export LARA_ACCESS_KEY_ID="your-access-key-id"
export LARA_ACCESS_KEY_SECRET="your-access-key-secret"# Run basic text translation example
cd examples
ruby text_translation.rb# Clone the repository
git clone https://github.com/translated/lara-ruby.git
cd lara-ruby
# Install dependencies
bundle installThe test suite uses RSpec with WebMock to stub HTTP calls, so no real API requests are made and no credentials are required.
# Run all tests
bundle exec rspec spec
# Run with documentation format (lists each example)
bundle exec rspec spec --format documentation
# Run a specific file or example
bundle exec rspec spec/lara/translator_spec.rb
bundle exec rspec spec/lara/translator_spec.rb:45After a run, a coverage report is generated in coverage/ (via SimpleCov). Open coverage/index.html in a browser to view line coverage.
This project is licensed under the MIT License - see the LICENSE file for details.
Happy translating! πβ¨