lara-sdk 1.8.3

A Python library for Lara's API.

Lara Python 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: Audio file translation 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

📚 Documentation

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

🚀 Quick Start

Installation

pip install lara-sdk

Basic Usage

import os
from lara_sdk import Credentials, Translator

# Set your credentials using environment variables (recommended)
credentials = Credentials(
  os.environ.get('LARA_ACCESS_KEY_ID'),
  os.environ.get('LARA_ACCESS_KEY_SECRET')
)

# Create translator instance
lara = Translator(credentials)

# Simple text translation
try:
  result = lara.translate("Hello, world!", target="fr-FR", source="en-US")
  print(f"Translation: {result.translation}")
  # Output: Translation: Bonjour, le monde !
except Exception as error:
  print(f"Translation error: {error}")

📖 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.py - 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
python text_translation.py

Document Translation

• document_translation.py - Document translation examples
  • Basic document translation
  • Advanced options with memories and glossaries
  • Step-by-step translation with status monitoring

cd examples
python document_translation.py

Image Translation

• image_translation.py - Image translation examples
  • Full image translation with overlay or inpainting
  • Text-only extraction and translation
  • Style, memories, and glossaries options

cd examples
python image_translation.py

Audio Translation

• audio_translation.py - Audio translation examples
  • Basic audio translation
  • Advanced options with memories and glossaries
  • Step-by-step translation with status monitoring

cd examples
python audio_translation.py

Translation Memory Management

• memories_management.py - 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
python memories_management.py

Glossary Management

• glossaries_management.py - Glossary management examples
  • Create, list, update, delete glossaries
  • CSV import with status monitoring
  • Glossary export
  • Glossary terms count
  • Import status checking

cd examples
python glossaries_management.py

Language Detection

• language_detection.py - Language detection examples
  • Single string detection
  • Multiple strings detection
  • Detection with hint parameter
  • Detection with passlist to restrict languages
  • Combined hint and passlist

cd examples
python language_detection.py

🔧 API Reference

Core Components

🔐 Authentication

The SDK supports authentication via access key and secret:

from lara_sdk import Credentials, Translator

credentials = Credentials("your-access-key-id", "your-access-key-secret")
lara = Translator(credentials)

Environment Variables (Recommended):

export LARA_ACCESS_KEY_ID="your-access-key-id"
export LARA_ACCESS_KEY_SECRET="your-access-key-secret"

import os
from lara_sdk import Credentials

credentials = Credentials(
    os.environ['LARA_ACCESS_KEY_ID'],
    os.environ['LARA_ACCESS_KEY_SECRET']
)

Alternative Constructor:

# You can also pass credentials directly to Translator
lara = Translator(
    access_key_id="your-access-key-id",
    access_key_secret="your-access-key-secret"
)

🌍 Translator

# Create translator with credentials
lara = Translator(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)
from lara_sdk import TextBlock

text_blocks = [
    TextBlock(text="Translatable text", translatable=True),
    TextBlock(text="<br>", translatable=False),  # Non-translatable HTML
    TextBlock(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=["memory-id"],  # Replace with actual memory IDs
    glossaries=["glossary-id"],  # Replace with actual glossary IDs
    style="fluid",
    timeout_ms=10000
)

📖 Document Translation

Simple document translation

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

# 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

Simple image translation

translated_image = lara.images.translate(
  source="en-US",
  target="fr-FR",
  image_path="/path/to/your/image.png",  # Replace with actual file path
  text_removal="overlay"
)

Text-only image translation

text_results = lara.images.translate_text(
  source="en-US",
  target="es-ES",
  image_path="/path/to/your/image.png"  # Replace with actual file path
)

🎵 Audio Translation

Simple audio translation

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

# With options
audio_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
)

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

audio_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 CSV from file
glossary_import = lara.glossaries.import_csv("gls_1A2b3C4d5E6f7G8h9I0jKl", "/path/to/your/glossary.csv")  # Replace with actual CSV file path

# 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
csv_data = lara.glossaries.export("gls_1A2b3C4d5E6f7G8h9I0jKl", "csv/table-uni", "en-US")

# Get glossary terms count
counts = lara.glossaries.counts("gls_1A2b3C4d5E6f7G8h9I0jKl")

🌐 Language Detection

# Basic language detection
result = lara.detect("Hello, world!")
print(f"Detected language: {result.language}")
print(f"Content type: {result.content_type}")

# Detect multiple strings
result = lara.detect(["Hello", "Bonjour", "Hola"])

# Detection with hint
result = lara.detect("Hello", hint="en")

# Detection with passlist (restrict to specific languages)
result = lara.detect(
    "Guten Tag",
    passlist=["de-DE", "en-US", "fr-FR"]
)

# Combined hint and passlist
result = lara.detect(
    "Buongiorno",
    hint="it",
    passlist=["it-IT", "es-ES", "pt-PT"]
)

🎯 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 lists 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?",
)
print(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."],
)
print([r.score for r in batch])  # e.g. [0.751, 0.713]

Translation Options

result = lara.translate(
    text,
    target="fr-FR",                          # Target language (required)
    source="en-US",                          # Source language (optional, auto-detect if None)
    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
)

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 languages() method to get the current list:

languages = lara.languages()
print(f"Supported languages: {', '.join(languages)}")

⚙️ Configuration

Error Handling

The SDK provides detailed error information:

from lara_sdk import LaraApiError, LaraError

try:
    result = lara.translate("Hello", target="fr-FR", source="en-US")
    print(f"Translation: {result.translation}")
except LaraApiError as error:
    print(f"API Error [{error.status_code}]: {error.message}")
    print(f"Error type: {error.type}")
except LaraError as error:
    print(f"SDK Error: {error}")
except Exception as error:
    print(f"Unexpected error: {error}")

📋 Requirements

• Python 3.8 or higher
• pip
• 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
python text_translation.py

🏗️ Building from Source

# Clone the repository
git clone https://github.com/translated/lara-python.git
cd lara-python

# Install in development mode
pip install -e .

📄 License

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

Happy translating! 🌍✨