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

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
- Glossary terms count
- Import status checking
- Add or replace glossary entries
- Delete glossary entries

cd examples
ruby glossaries_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 Translator
lara = Lara::Translator.new(
  access_key_id: "your-access-key-id",
  access_key_secret: "your-access-key-secret"
)

🌍 Translator

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

Text Translation

# 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
)

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 pair
single = lara.quality_estimation(
  source: "en-US",
  target: "it-IT",
  sentence: "Hello, how are you today?",
  translation: "Ciao, come stai oggi?"
)
puts single.score # e.g. 0.768

# Batch
batch = lara.quality_estimation(
  source: "en-US",
  target: "it-IT",
  sentence: ["Good morning.", "The weather is nice."],
  translation: ["Buongiorno.", "Il tempo è bello."]
)
puts batch.map(&:score).inspect # e.g. [0.751, 0.713]

📖 Document Translation

Simple document translation

# 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"
)

Document translation with status monitoring

Document upload

#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
)

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 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

🔊 Audio Translation

Simple audio translation

# 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"
)

Audio translation with status monitoring

Audio upload

#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
)

Audio translation status monitoring

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

Download translated audio

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

🧠 Memory Management

# 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

📚 Glossary Management

# 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")

🎨 Styleguides

Styleguides let you apply custom translation style rules. They can be listed and retrieved through the SDK.

# List all styleguides
styleguides = lara.styleguides.list

# Get a specific styleguide by ID
styleguide = lara.styleguides.get("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_results
if sg_results
  puts "Original translation: #{sg_results.original_translation}"

  sg_results.changes.each do |change|
    puts "Before: #{change.original_translation}"
    puts "After:  #{change.refined_translation}"
    puts "Why:    #{change.explanation}"
  end
end

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 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
  profanities_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 apply
  styleguide_reasoning: true,              # Enable styleguide change reasoning
  styleguide_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 codes
result = 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_languages
puts "Supported languages: #{languages.join(', ')}"

⚙️ Configuration

Error Handling

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

📋 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 example
cd 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 32 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

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

🔧 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

📚 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

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages