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

Text Translation with Image Context

Pass image_context to use an image as visual context for translating text, with reasoning enabled:

result = lara.translate(
  "Open", source: "en-US", target: "it-IT", reasoning: true,
  image_context: { url: "https://example.com/storefront.png" }
)
puts result.translation

result.warnings&.reasoning&.warnings&.each do |warning|
  warn "#{warning.code}: #{warning.message}"
end

You can also supply a single-element array or an inline image:

require "base64"
encoded = Base64.strict_encode64(File.binread("storefront.png"))
result = lara.translate(
  "Open", source: "en-US", target: "it-IT", reasoning: true,
  image_context: [{ url: "data:image/png;base64,#{encoded}" }]
)

The API accepts at most one image: an HTTPS URL or a base64 PNG, JPEG or WebP data URL. Inline images must match their declared MIME type and contain at most 5 MiB of decoded data; the serialized request body is limited to 16 MiB. Omitting image_context or passing [] preserves text-only behavior. Validation is performed by the API, which returns 400 for invalid input and 413 for size violations.

If the image cannot be used, the server may retry the entire request with reasoning without images. The result then includes an image_context_unavailable warning under warnings.reasoning.warnings in the API response, exposed by the typed warning models shown above. warnings.reasoning.applied is true when reasoning succeeds without images, or false (with an error containing statusCode and message) when the server falls back to standard translation. Reference retrieval and prosa failures are available under warnings.references and warnings.prosa.

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",
  model: Lara::Models::ImageTranslationModel::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

Request layout independently of verbose match details, then render the supplied translations:

result = lara.images.translate_text(
  file_path: "image.png", source: "en", target: "fr", include_layout: true
)
paragraphs = result.paragraphs.dup
if paragraphs.first
  paragraph = paragraphs.first
  paragraphs[0] = Lara::Models::ImageLayoutParagraph.new(
    text: paragraph.text, translation: "Bonjour !", bbox: paragraph.bbox,
    lines_bboxes: paragraph.lines_bboxes, text_info: paragraph.text_info,
    alignment: paragraph.alignment
  )
end
rendered = lara.images.render_translated(
  file_path: "image.png", source: result.source_language, target: "fr",
  paragraphs: paragraphs, model: "overlay"
)
File.binwrite("rendered.png", rendered)

When include_layout: true, every paragraph is an ImageLayoutParagraph, extending ImageParagraph, and contains the complete metadata required by classic rendering models. Rendering uses the supplied translations without translating again and defaults to GENERATIVE_FAST. Pass model and no_trace to configure rendering. OVERLAY and INPAINTING require complete layout on every paragraph; generative models accept text-only paragraphs or complete layout. Memory and glossary matches are omitted from rendering requests.

🔊 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

# list_paginated accepts an optional Lara::Models::ResourceQueryOptions object.
# Without options, returns all memories; page and size are nil.
# Providing search, page or size enables pagination.
memory_result = lara.memories.list_paginated
memories = memory_result.items
memory_total = memory_result.total # Total matching resources across all pages

# Page starts at 1; size ranges from 1 to 200.
# The missing parameter defaults to page 1 or size 20.
memory_page = lara.memories.list_paginated(Lara::Models::ResourceQueryOptions.new(page: 2, size: 50))
memory_default_size = lara.memories.list_paginated(Lara::Models::ResourceQueryOptions.new(page: 2)) # Page 2, 20 per page
memory_first_page = lara.memories.list_paginated(Lara::Models::ResourceQueryOptions.new(size: 50)) # Page 1, 50 per page
puts memory_page.page # Current page (1-based)
puts memory_page.size # Page size

# Search filters the displayed name (case- and accent-insensitive).
# It matches substrings, preserves spaces and accepts 1-255 characters.
# Search alone enables pagination with page 1 and size 20.
options = Lara::Models::ResourceQueryOptions.new(search: "Marketing", page: 2, size: 50)
memory_search = lara.memories.list_paginated(options)

# list is deprecated and emits a warning; use list_paginated instead.

# 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

# Share with the account or a group; shares can be renamed, listed, and revoked
lara.memories.add_account_share(memory.id, name: "Team memory")
lara.memories.rename_account_share(memory.id, name: "Company memory")
lara.memories.add_group_share(memory.id, "grp_1A2b3C4d5E6f7G8h9I0jKl", name: "Marketing memory")
shares = lara.memories.get_shares(memory.id)
lara.memories.revoke_group_share(memory.id, "grp_1A2b3C4d5E6f7G8h9I0jKl")
lara.memories.revoke_account_share(memory.id)

🔄 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 format
export_job = lara.memories.export_async(
  "mem_1A2b3C4d5E6f7G8h9I0jKl",
  format: "tmx",
  callback_url: "https://your-server.example.com/callbacks/memory-export"
)

📚 Glossary Management

# Create glossary
glossary = lara.glossaries.create("MyGlossary")

# list_paginated accepts an optional Lara::Models::ResourceQueryOptions object.
# Without options, returns all glossaries; page and size are nil.
# Providing search, page or size enables pagination.
glossary_result = lara.glossaries.list_paginated
glossaries = glossary_result.items
glossary_total = glossary_result.total # Total matching resources across all pages

# Page starts at 1; size ranges from 1 to 200.
# The missing parameter defaults to page 1 or size 20.
glossary_page = lara.glossaries.list_paginated(Lara::Models::ResourceQueryOptions.new(page: 2, size: 50))
glossary_default_size = lara.glossaries.list_paginated(Lara::Models::ResourceQueryOptions.new(page: 2)) # Page 2, 20 per page
glossary_first_page = lara.glossaries.list_paginated(Lara::Models::ResourceQueryOptions.new(size: 50)) # Page 1, 50 per page
puts glossary_page.page # Current page (1-based)
puts glossary_page.size # Page size

# Search filters the displayed name (case- and accent-insensitive).
# It matches substrings, preserves spaces and accepts 1-255 characters.
# Search alone enables pagination with page 1 and size 20.
options = Lara::Models::ResourceQueryOptions.new(search: "Marketing", page: 2, size: 50)
glossary_search = lara.glossaries.list_paginated(options)

# list is deprecated and emits a warning; use list_paginated instead.

# Import unidirectional CSV from file (use Lara::Glossaries::FileFormat::TBX for TBX files)
glossary_import = lara.glossaries.import_file("gls_1A2b3C4d5E6f7G8h9I0jKl", "/path/to/your/glossary.csv")

# Options are independent keyword arguments.
# A callback can be supplied on its own:
# lara.glossaries.import_file(glossary.id, "/path/to/your/glossary.csv", callback_url: callback_url)

# Import multidirectional CSV from file
glossary_import = lara.glossaries.import_file(
  "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)

# Async glossary export — returns a job_id; the result is delivered to your callback URL when ready
export_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")

# Glossaries support the same account and group sharing workflow
lara.glossaries.add_account_share(glossary.id, name: "Team glossary")
glossary_shares = lara.glossaries.get_shares(glossary.id)
lara.glossaries.revoke_account_share(glossary.id)

🎨 Styleguides

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

# Create styleguide
styleguide = lara.styleguides.create(
  name: "MyStyleguide",
  content: "Use a formal tone. Prefer British English spelling. Avoid contractions."
)

# list_paginated accepts an optional Lara::Models::ResourceQueryOptions object.
# Without options, returns all styleguides; page and size are nil.
# Providing search, page or size enables pagination.
styleguide_result = lara.styleguides.list_paginated
styleguides = styleguide_result.items
styleguide_total = styleguide_result.total # Total matching resources across all pages

# Page starts at 1; size ranges from 1 to 200.
# The missing parameter defaults to page 1 or size 20.
styleguide_page = lara.styleguides.list_paginated(Lara::Models::ResourceQueryOptions.new(page: 2, size: 50))
styleguide_default_size = lara.styleguides.list_paginated(Lara::Models::ResourceQueryOptions.new(page: 2)) # Page 2, 20 per page
styleguide_first_page = lara.styleguides.list_paginated(Lara::Models::ResourceQueryOptions.new(size: 50)) # Page 1, 50 per page
puts styleguide_page.page # Current page (1-based)
puts styleguide_page.size # Page size

# Search filters the displayed name (case- and accent-insensitive).
# It matches substrings, preserves spaces and accepts 1-255 characters.
# Search alone enables pagination with page 1 and size 20.
options = Lara::Models::ResourceQueryOptions.new(search: "Marketing", page: 2, size: 50)
styleguide_search = lara.styleguides.list_paginated(options)

# list is deprecated and emits a warning; use list_paginated instead.

# Get a specific styleguide by ID
styleguide = lara.styleguides.get("stg_1A2b3C4d5E6f7G8h9I0jKl")

# Update only the name
renamed = lara.styleguides.update("stg_1A2b3C4d5E6f7G8h9I0jKl", name: "UpdatedName")

# Update only the content
updated_content = lara.styleguides.update(
  "stg_1A2b3C4d5E6f7G8h9I0jKl",
  content: "Use a casual tone. Prefer American English spelling."
)

# Update both name and content
updated = lara.styleguides.update(
  "stg_1A2b3C4d5E6f7G8h9I0jKl",
  name: "FinalName",
  content: "Use clear and concise language. Avoid jargon."
)

# Share a styleguide and inspect visible account, group, and user shares
lara.styleguides.add_group_share(styleguide.id, "grp_1A2b3C4d5E6f7G8h9I0jKl", name: "Marketing styleguide")
styleguide_shares = lara.styleguides.get_shares(styleguide.id)

# Delete a styleguide
deleted = 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_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(', ')}"

Asset permissions

Memories, glossaries, styleguides, and their share entries expose permission_mask from the API's permission_mask field. Masks use read (r), write (w), export (e), and share (s) positions; - means absent. Supported masks are r---, rw--, r-e-, r--s, rwe-, rw-s, r-es, and rwes.

On memory, glossary, and styleguide resources, permission_mask is optional and is nil when omitted by the API, including POST, PUT, and DELETE resource responses. GET list and detail responses report the combined effective mask from the caller's applicable shares. Resources embedded in GET /shares responses report the selected share's stored mask; individual share entries report their own required stored mask.

The legacy permissions field and its read/write compatibility API have been removed. Use permission_mask to inspect the read, write, export, and share bits. Share-entry masks are required, matching the service contract. Resource masks remain optional.

⚙️ 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! 🌍✨

lara-sdk

Development

Runtime

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

Text Translation with Image Context

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

Asset permissions

⚙️ Configuration

Error Handling

📋 Requirements

🧪 Testing

🏗️ Building from Source

🧪 Running tests

📄 License