Lara Ruby SDK

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.

🌍 Features:

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
Styleguides: Apply custom translation style rules with detailed change reasoning
Language Detection: Automatic source language identification
Profanity Detection & Handling: Detect profanities in source and/or target text, and hide or avoid them in translation
Advanced Options: Translation instructions and more

📚 Documentation

Lara's SDK full documentation is available at https://developers.laratranslate.com/

🚀 Quick Start

Installation

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

Basic Usage

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 instancelara=Lara::Translator.new(credentials: credentials)# Simple text translationbeginresult=lara.translate("Hello, world!",target: "fr-FR",source: "en-US")puts"Translation: #{result.translation}"# Output: Translation: Bonjour, le monde !rescue=>errorputs"Translation error: #{error.message}"end

📖 Examples

The 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

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
- Profanity detection and handling
- Translation with styleguides
- Get available languages

cd examples
ruby text_translation.rb

Document Translation

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

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

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

Translation Memory Management

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
- TMX import with callback URL (async notification)
- Async memory export with callback URL

cd examples
ruby memories_management.rb

Glossary Management

glossaries_management.rb - Glossary management examples
- Create, list, update, delete glossaries
- Individual term management (add/remove terms)
- CSV import with status monitoring
- Glossary export (sync and async)
- Glossary terms count
- Import status checking
- Add or replace glossary entries
- Delete glossary entries

cd examples
ruby glossaries_management.rb

Styleguide Management

styleguides_management.rb - Styleguide management examples
- Create, list, get, update, delete styleguides

cd examples
ruby styleguides_management.rb

🔧 API Reference

Core Components

🔐 Authentication

The 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 Translatorlara=Lara::Translator.new(access_key_id: "your-access-key-id",access_key_secret: "your-access-key-secret")

🌍 Translator

# Create translator with credentialslara=Lara::Translator.new(credentials: credentials)

Text Translation

# Basic translationresult=lara.translate("Hello",target: "fr-FR",source: "en-US")# Multiple stringsresult=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 HTMLLara::Models::TextBlock.new(text: "More translatable text",translatable: true)]result=lara.translate(text_blocks,target: "fr-FR",source: "en-US")# With advanced optionsresult=lara.translate("Hello",target: "fr-FR",source: "en-US",instructions: ["Formal tone"],adapt_to: ["mem_1A2b3C4d5E6f7G8h9I0jKl"],# Replace with actual memory IDsglossaries: ["gls_1A2b3C4d5E6f7G8h9I0jKl"],# Replace with actual glossary IDsstyle: "fluid",timeout_ms: 10000)

Quality Estimation

Use quality_estimation() to score how well a translation matches its source. Pass a single sentence/translation pair to get a single result, or two parallel arrays to get one result per pair.

# Single pairsingle=lara.quality_estimation(source: "en-US",target: "it-IT",sentence: "Hello, how are you today?",translation: "Ciao, come stai oggi?")putssingle.score# e.g. 0.768# Batchbatch=lara.quality_estimation(source: "en-US",target: "it-IT",sentence: ["Good morning.","The weather is nice."],translation: ["Buongiorno.","Il tempo è bello."])putsbatch.map(&:score).inspect# e.g. [0.751, 0.713]

📖 Document Translation

Simple document translation

# Replace with your actual file pathtranslated_content=lara.documents.translate(file_path: "/path/to/your/document.txt",filename: "document.txt",source: "en-US",target: "fr-FR")# With optionstranslated_content=lara.documents.translate(file_path: "/path/to/your/document.txt",# Replace with actual file pathfilename: "document.txt",source: "en-US",target: "fr-FR",adapt_to: ["mem_1A2b3C4d5E6f7G8h9I0jKl"],# Replace with actual memory IDsglossaries: ["gls_1A2b3C4d5E6f7G8h9I0jKl"],# Replace with actual glossary IDsstyle: "fluid")

Document translation with status monitoring

Document upload

#Optional: upload optionsdocument=lara.documents.upload(file_path: "/path/to/your/document.txt",# Replace with actual file pathfilename: "document.txt",source: "en-US",target: "fr-FR",adapt_to: ["mem_1A2b3C4d5E6f7G8h9I0jKl"],# Replace with actual memory IDsglossaries: ["gls_1A2b3C4d5E6f7G8h9I0jKl"]# Replace with actual glossary IDs)

Document translation status monitoring

status=lara.documents.status(document.id)

Download translated document

translated_content=lara.documents.download(document.id)

🖼️ Image Translation

require'lara'# Translate an image and receive a translated image as binary datatranslated_image=lara.images.translate(file_path: "/path/to/your/image.png",# Replace with actual file pathsource: "en",target: "fr",model: Lara::Models::ImageTranslationModel::INPAINTING,style: "faithful")# Save the translated imageFile.binwrite("translated_image.png",translated_image)# Extract and translate text blocks from an imageresult=lara.images.translate_text(file_path: "/path/to/your/image.png",# Replace with actual file pathsource: "en",target: "fr",adapt_to: ["mem_1A2b3C4d5E6f7G8h9I0jKl"],# Replace with actual memory IDsglossaries: ["gls_1A2b3C4d5E6f7G8h9I0jKl"]# Replace with actual glossary IDs)result.paragraphs.eachdo |paragraph|
puts"Original: #{paragraph.text}"puts"Translated: #{paragraph.translation}"end

🔊 Audio Translation

Simple audio translation

# Replace with your actual file pathtranslated_content=lara.audio.translate(file_path: "/path/to/your/audio.mp3",filename: "audio.mp3",source: "en-US",target: "fr-FR")# With optionstranslated_content=lara.audio.translate(file_path: "/path/to/your/audio.mp3",# Replace with actual file pathfilename: "audio.mp3",source: "en-US",target: "fr-FR",adapt_to: ["mem_1A2b3C4d5E6f7G8h9I0jKl"],# Replace with actual memory IDsglossaries: ["gls_1A2b3C4d5E6f7G8h9I0jKl"],# Replace with actual glossary IDsstyle: "fluid")

Audio translation with status monitoring

Audio upload

#Optional: upload optionsaudio=lara.audio.upload(file_path: "/path/to/your/audio.mp3",# Replace with actual file pathfilename: "audio.mp3",source: "en-US",target: "fr-FR",adapt_to: ["mem_1A2b3C4d5E6f7G8h9I0jKl"],# Replace with actual memory IDsglossaries: ["gls_1A2b3C4d5E6f7G8h9I0jKl"]# Replace with actual glossary IDs)

Audio translation status monitoring

status=lara.audio.status(audio.id)

Download translated audio

translated_content=lara.audio.download(audio.id)

🧠 Memory Management

# Create memorymemory=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 memorymemory_import=lara.memories.add_translation("mem_1A2b3C4d5E6f7G8h9I0jKl","en-US","fr-FR","Hello","Bonjour",tuid: "greeting_001")# Add translation to multiple memoriesmemory_import=lara.memories.add_translation(["mem_1A2b3C4d5E6f7G8h9I0jKl","mem_2XyZ9AbC8dEf7GhI6jKlMn"],"en-US","fr-FR","Hello","Bonjour",tuid: "greeting_002")# Add with contextmemory_import=lara.memories.add_translation("mem_1A2b3C4d5E6f7G8h9I0jKl","en-US","fr-FR","Hello","Bonjour",tuid: "tuid",sentence_before: "sentenceBefore",sentence_after: "sentenceAfter")# TMX import from filememory_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 removeddelete_job=lara.memories.delete_translation("mem_1A2b3C4d5E6f7G8h9I0jKl","en-US","fr-FR","Hello","Bonjour",tuid: "greeting_001")# Wait for import completioncompleted_import=lara.memories.wait_for_import(memory_import,max_wait_time: 300)# 5 minutes

🔄 Async Memory Import & Export

# TMX import with callback URL (async notification on completion)memory_import=lara.memories.import_tmx("mem_1A2b3C4d5E6f7G8h9I0jKl","/path/to/your/memory.tmx",callback_url: "https://your-server.example.com/callbacks/memory-import")# Async memory export (callback receives the exported file)export_job=lara.memories.export_async("mem_1A2b3C4d5E6f7G8h9I0jKl",callback_url: "https://your-server.example.com/callbacks/memory-export")# Export with specific formatexport_job=lara.memories.export_async("mem_1A2b3C4d5E6f7G8h9I0jKl",format: "tmx",callback_url: "https://your-server.example.com/callbacks/memory-export")

📚 Glossary Management

# Create glossaryglossary=lara.glossaries.create("MyGlossary")# Import unidirectional CSV from fileglossary_import=lara.glossaries.import_csv("gls_1A2b3C4d5E6f7G8h9I0jKl","/path/to/your/glossary.csv")# Replace with actual CSV file path# Import multidirectional CSV from fileglossary_import=lara.glossaries.import_csv("gls_1A2b3C4d5E6f7G8h9I0jKl","/path/to/your/multidirectional_glossary.csv",# Replace with actual CSV file pathcontent_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 GUIDterms_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 glossaryterm_to_remove={language: "fr-FR",value: "Bonjour"}lara.glossaries.delete_entry("gls_1A2b3C4d5E6f7G8h9I0jKl",term: term_to_remove)# Remove a multidirectional entry by GUIDlara.glossaries.delete_entry("gls_1A2b3C4d5E6f7G8h9I0jKl",guid: "custom-guid-123")# Check import statusimport_status=lara.glossaries.get_import_status(import_id)# Wait for import completioncompleted_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)# Async glossary export — returns a job_id; the result is delivered to your callback URL when readyexport_job=lara.glossaries.export_async("gls_1A2b3C4d5E6f7G8h9I0jKl",callback_url: "https://your-server.example.com/lara/export-callback",content_type: Lara::Glossaries::FileFormat::UNIDIRECTIONAL,source: "en-US")# Get glossary terms count (includes both unidirectional and multidirectional counts)counts=lara.glossaries.counts("gls_1A2b3C4d5E6f7G8h9I0jKl")

🎨 Styleguides

Styleguides let you apply custom translation style rules. Create, list, get, update, and delete them through the SDK.

# Create styleguidestyleguide=lara.styleguides.create(name: "MyStyleguide",content: "Use a formal tone. Prefer British English spelling. Avoid contractions.")# List all styleguidesstyleguides=lara.styleguides.list# Get a specific styleguide by IDstyleguide=lara.styleguides.get("stg_1A2b3C4d5E6f7G8h9I0jKl")# Update only the namerenamed=lara.styleguides.update("stg_1A2b3C4d5E6f7G8h9I0jKl",name: "UpdatedName")# Update only the contentupdated_content=lara.styleguides.update("stg_1A2b3C4d5E6f7G8h9I0jKl",content: "Use a casual tone. Prefer American English spelling.")# Update both name and contentupdated=lara.styleguides.update("stg_1A2b3C4d5E6f7G8h9I0jKl",name: "FinalName",content: "Use clear and concise language. Avoid jargon.")# Delete a styleguidedeleted=lara.styleguides.delete("stg_1A2b3C4d5E6f7G8h9I0jKl")

Translate with a styleguide

result=lara.translate("Hello, world!",target: "it-IT",source: "en-US",styleguide_id: "stg_1A2b3C4d5E6f7G8h9I0jKl"# Replace with actual styleguide ID)

Styleguide reasoning

Enable reasoning to see what the styleguide changed and why:

result=lara.translate("Hello, world!",target: "it-IT",source: "en-US",styleguide_id: "stg_1A2b3C4d5E6f7G8h9I0jKl",styleguide_reasoning: true,styleguide_explanation_language: "en-US")sg_results=result.styleguide_resultsifsg_resultsputs"Original translation: #{sg_results.original_translation}"sg_results.changes.eachdo |change|
puts"Before: #{change.original_translation}"puts"After: #{change.refined_translation}"puts"Why: #{change.explanation}"endend

Translation Options

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 detectionadapt_to: ["memory-id"],# Memory IDs to adapt toglossaries: ["glossary-id"],# Glossary IDs to useinstructions: ["instruction"],# Translation instructionsstyle: "fluid",# Translation style (fluid, faithful, creative)content_type: "text/plain",# Content type (text/plain, text/html, etc.)multiline: true,# Enable multiline translationtimeout_ms: 10000,# Request timeout in millisecondsno_trace: false,# Disable request tracingverbose: false,# Enable verbose responseprofanities_detect: "target",# Detect profanities in: "target" or "source_target"profanities_handling: "detect",# How to handle profanities: "detect", "hide", or "avoid"styleguide_id: "stg_id",# Styleguide ID to applystyleguide_reasoning: true,# Enable styleguide change reasoningstyleguide_explanation_language: "en-US",# Language for change explanations)

🚫 Profanity Detection and Handling

Use profanities_detect and profanities_handling together to control how profanities are detected and handled.

"target" — detect profanities in the translated text only
"source_target" — detect in both source and target text
"detect" — report profanities without modifying the translation
"hide" — replace detected profanities with asterisks (default when detect is set)
"avoid" — instruct the model not to generate profanities

result=lara.translate("Don't be such a tool.",target: "it-IT",source: "en-US",profanities_detect: "source_target",profanities_handling: "detect")# result.profanities.target — detection result for the translated text# result.profanities.source — detection result for the source text (only with source_target)

Language Codes

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 codesresult=lara.translate("Hello",target: "fr",source: "en")

🌐 Supported Languages

The SDK supports all languages available in the Lara API. Use the get_languages() method to get the current list:

languages=lara.get_languagesputs"Supported languages: #{languages.join(', ')}"

⚙️ Configuration

Error Handling

The SDK provides detailed error information:

beginresult=lara.translate("Hello",target: "fr-FR",source: "en-US")puts"Translation: #{result.translation}"rescueLara::LaraApiError=>errorputs"API Error [#{error.status_code}]: #{error.message}"puts"Error type: #{error.type}"rescueLara::LaraError=>errorputs"SDK Error: #{error.message}"rescue=>errorputs"Unexpected error: #{error.message}"end

📋 Requirements

Ruby 2.6 or higher
Bundler
Valid Lara API credentials

🧪 Testing

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 examplecd examples
ruby text_translation.rb

🏗️ Building from Source

# Clone the repository
git clone https://github.com/translated/lara-ruby.git
cd lara-ruby
# Install dependencies
bundle install

🧪 Running tests

The 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:45

After a run, a coverage report is generated in coverage/ (via SimpleCov). Open coverage/index.html in a browser to view line coverage.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Happy translating! 🌍✨

Name		Name	Last commit message	Last commit date
Latest commit History 53 Commits
.github/workflows		.github/workflows
examples		examples
lib		lib
spec		spec
.gitignore		.gitignore
.rspec		.rspec
.rubocop.yml		.rubocop.yml
.ruby-version		.ruby-version
Gemfile		Gemfile
LICENSE		LICENSE
README.md		README.md
lara-sdk.gemspec		lara-sdk.gemspec
version		version

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Lara Ruby SDK

🌍 Features:

📚 Documentation

🚀 Quick Start

Installation

Basic Usage

📖 Examples

Text Translation

Document Translation

Image Translation

Audio Translation

Translation Memory Management

Glossary Management

Styleguide Management

🔧 API Reference

Core Components

🔐 Authentication

🌍 Translator

Text Translation

Quality Estimation

📖 Document Translation

Simple document translation

Document translation with status monitoring

Document upload

Document translation status monitoring

Download translated document

🖼️ Image Translation

🔊 Audio Translation

Simple audio translation

Audio translation with status monitoring

Audio upload

Audio translation status monitoring

Download translated audio

🧠 Memory Management

🔄 Async Memory Import & Export

📚 Glossary Management

🎨 Styleguides

Translate with a styleguide

Styleguide reasoning

Translation Options

🚫 Profanity Detection and Handling

Language Codes

🌐 Supported Languages

⚙️ Configuration

Error Handling

📋 Requirements

🧪 Testing

🏗️ Building from Source

🧪 Running tests

📄 License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages