Lara Java 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
Audio Translation: 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, reasoning, and more

📚 Documentation

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

🚀 Quick Start

Installation

Add the dependency to your pom.xml:

<dependency>
    <groupId>com.translated.lara</groupId>
    <artifactId>lara-sdk</artifactId>
    <version>1.4.2</version>
</dependency>

Or for Gradle, add to your build.gradle:

implementation 'com.translated.lara:lara-sdk:1.4.2'

Basic Usage

import com.translated.lara.Credentials;
import com.translated.lara.translator.Translator;
import com.translated.lara.translator.TextResult;
import com.translated.lara.errors.LaraException;
import java.util.Arrays;
import java.util.List;
import java.util.Map;

public class Example {
    public static void main(String[] args) {
        // Set your credentials using environment variables (recommended)
        Credentials credentials = new Credentials(
            System.getenv("LARA_ACCESS_KEY_ID"),
            System.getenv("LARA_ACCESS_KEY_SECRET")
        );

        // Create translator instance
        Translator lara = new Translator(credentials);

        try {
            // Simple text translation
            TextResult result = lara.translate("Hello, world!", "en-US", "fr-FR");
            
            System.out.println("Translation: " + result.getTranslation());
            // Output: Translation: Bonjour, le monde !
        } catch (LaraException e) {
            System.err.println("Translation error: " + e.getMessage());
        }
    }
}

📖 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

TextTranslation.java - 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
- Detect language

cd examples
javac -cp ../target/classes:../target/dependency/* TextTranslation.java
java -cp .:../target/classes:../target/dependency/* TextTranslation

Document Translation

DocumentTranslation.java - Document translation examples
- Basic document translation
- Advanced options with memories and glossaries
- Step-by-step translation with status monitoring

cd examples
javac -cp ../target/classes:../target/dependency/* DocumentTranslation.java
java -cp .:../target/classes:../target/dependency/* DocumentTranslation

Audio Translation

AudioTranslation.java - Audio translation examples
- Basic audio translation
- Advanced options with memories and glossaries
- Step-by-step translation with status monitoring

cd examples
javac -cp ../target/classes:../target/dependency/* AudioTranslation.java
java -cp .:../target/classes:../target/dependency/* AudioTranslation

Translation Memory Management

MemoriesManagement.java - 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
javac -cp ../target/classes:../target/dependency/* MemoriesManagement.java
java -cp .:../target/classes:../target/dependency/* MemoriesManagement

Glossary Management

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

cd examples
javac -cp ../target/classes:../target/dependency/* GlossariesManagement.java
java -cp .:../target/classes:../target/dependency/* GlossariesManagement

🔧 API Reference

Core Components

🔐 Authentication

The SDK supports authentication via access key and secret:

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

Environment Variables (Recommended):

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

Credentials credentials = new Credentials(
    System.getenv("LARA_ACCESS_KEY_ID"),
    System.getenv("LARA_ACCESS_KEY_SECRET")
);

🌍 Translator

// Create translator with credentials
Translator lara = new Translator(credentials);

Text Translation

// Basic translation
TextResult result = lara.translate("Hello", "en-US", "fr-FR");

// Multiple strings
String[] texts = {"Hello", "World"};
TextResult result = lara.translate(texts, "en-US", "fr-FR");

// TextBlocks (mixed translatable/non-translatable content)
TextBlock[] textBlocks = {
    new TextBlock("Translatable text", true),
    new TextBlock("<br>", false),  // Non-translatable HTML
    new TextBlock("More translatable text", true),
};
TextResult result = lara.translateBlocks(textBlocks, "en-US", "fr-FR");

// With advanced options
TranslateOptions options = new TranslateOptions()
    .setInstructions("Formal tone")
    .setAdaptTo("memory-id")  // Replace with actual memory IDs
    .setGlossaries("glossary-id")  // Replace with actual glossary IDs
    .setStyle(TranslationStyle.FLUID)
    .setTimeoutMs(10000L);

TextResult result = lara.translate("Hello", "en-US", "fr-FR", options);

Quality Estimation

Use qualityEstimation() 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
QualityEstimationResult single = lara.qualityEstimation(
    "en-US",
    "it-IT",
    "Hello, how are you today?",
    "Ciao, come stai oggi?"
);
System.out.println(single.getScore()); // e.g. 0.768

// Batch
List<QualityEstimationResult> batch = lara.qualityEstimation(
    "en-US",
    "it-IT",
    Arrays.asList("Good morning.", "The weather is nice."),
    Arrays.asList("Buongiorno.", "Il tempo è bello.")
);
System.out.println(batch.stream().map(QualityEstimationResult::getScore).collect(java.util.stream.Collectors.toList())); // e.g. [0.751, 0.713]

Profanity Detection and Handling

Use setProfanitiesDetect and setProfanitiesHandling together to control how profanities are detected and handled.

ProfanitiesDetect.TARGET — detect profanities in the translated text only
ProfanitiesDetect.SOURCE_TARGET — detect in both source and target text
ProfanitiesHandling.DETECT — report profanities without modifying the translation
ProfanitiesHandling.HIDE — replace detected profanities with asterisks (default when detect is set)
ProfanitiesHandling.AVOID — instruct the model not to generate profanities

TranslateOptions options = new TranslateOptions()
    .setProfanitiesDetect(ProfanitiesDetect.SOURCE_TARGET)
    .setProfanitiesHandling(ProfanitiesHandling.DETECT);

TextResult result = lara.translate("Don't be such a tool.", "en-US", "it-IT", options);

TextResult.ProfanitiesResult profanities = result.getProfanitiesResult();
// profanities.getTarget() — detection result for the translated text
// profanities.getSource() — detection result for the source text (only with SOURCE_TARGET)

📖 Document Translation

Simple document translation

File inputFile = new File("/path/to/your/document.txt");  // Replace with actual file path
InputStream fileStream = lara.documents.translate(inputFile, "document.txt", "en-US", "fr-FR");

// With options
DocumentTranslateOptions options = new DocumentTranslateOptions()
    .setAdaptTo("memory-id")  // Replace with actual memory IDs
    .setGlossaries("glossary-id")  // Replace with actual glossary IDs
    .setStyle(TranslationStyle.FLUID)
    .setNoTrace(false);

InputStream fileStream = lara.documents.translate(inputFile, "document.txt", "en-US", "fr-FR", options);

Document translation with status monitoring

Document upload

//Optional: upload options
DocumentUploadOptions uploadOptions = new DocumentUploadOptions()
    .setAdaptTo("memory-id")  // Replace with actual memory IDs
    .setGlossaries("glossary-id")  // Replace with actual glossary IDs
    .setNoTrace(false);

Document document = lara.documents.upload(inputFile, "document.txt", "en-US", "fr-FR", uploadOptions);

Document translation status monitoring

String status = lara.documents.status(document.getId());

Download translated document

InputStream fileStream = lara.documents.download(document.getId());

🎵 Audio Translation

Simple audio translation

File inputFile = new File("/path/to/your/audio.mp3");
InputStream audioStream = lara.audio.translate(inputFile, "en-US", "fr-FR");

// With options
AudioUploadOptions options = new AudioUploadOptions()
    .setAdaptTo("memory-id")  // Replace with actual memory IDs
    .setGlossaries("glossary-id")  // Replace with actual glossary IDs
    .setStyle(TranslationStyle.FLUID)
    .setNoTrace(false);

InputStream audioStream = lara.audio.translate(inputFile, "en-US", "fr-FR", options);

Audio translation with status monitoring

Audio upload

AudioUploadOptions uploadOptions = new AudioUploadOptions()
    .setAdaptTo("memory-id")  // Replace with actual memory IDs
    .setGlossaries("glossary-id")  // Replace with actual glossary IDs
    .setNoTrace(false);

Audio audio = lara.audio.upload(inputFile, "en-US", "fr-FR", uploadOptions);

Audio translation status monitoring

Audio status = lara.audio.status(audio.getId());

Download translated audio

InputStream audioStream = lara.audio.download(audio.getId());

🧠 Memory Management

// Create memory
Memory memory = lara.memories.create("MyMemory");

// Create memory with external ID (MyMemory integration)
Memory memory = lara.memories.create("Memory from MyMemory", "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
MemoryImport memoryImport = lara.memories.addTranslation("mem_1A2b3C4d5E6f7G8h9I0jKl", "en-US", "fr-FR", "Hello", "Bonjour", "greeting_001");

// Add translation to multiple memories
List<String> memoryIds = Arrays.asList("mem_1A2b3C4d5E6f7G8h9I0jKl", "mem_2XyZ9AbC8dEf7GhI6jKlMn");  // Replace with actual memory IDs
MemoryImport memoryImport = lara.memories.addTranslation(memoryIds, "en-US", "fr-FR", "Hello", "Bonjour", "greeting_002");

// Add with context
MemoryImport memoryImport = lara.memories.addTranslation(
        "mem_1A2b3C4d5E6f7G8h9I0jKl", "en-US", "fr-FR", "Hello", "Bonjour", "tuid", 
        "sentenceBefore", "sentenceAfter"
);

// TMX import from file
File tmxFile = new File("/path/to/your/memory.tmx");  // Replace with actual TMX file path
MemoryImport memoryImport = lara.memories.importTmx("mem_1A2b3C4d5E6f7G8h9I0jKl", tmxFile);

// Delete translation
// Important: if you omit tuid, all entries that match the provided fields will be removed
MemoryImport deleteJob = lara.memories.deleteTranslation(
        "mem_1A2b3C4d5E6f7G8h9I0jKl", "en-US", "fr-FR", "Hello", "Bonjour", "greeting_001"
);

// Wait for import completion (timeout in MILLISECONDS)
MemoryImport completedImport = lara.memories.waitForImport(memoryImport, 300000L); // 5 minutes

📚 Glossary Management

// Create glossary
Glossary glossary = lara.glossaries.create("MyGlossary");

// Import CSV from file
File csvFile = new File("/path/to/your/glossary.csv");  // Replace with actual CSV file path
GlossaryImport glossaryImport = lara.glossaries.importCsv("gls_1A2b3C4d5E6f7G8h9I0jKl", csvFile);

// Add (or replace) individual terms to glossary
List<Map<String, String>> terms = Arrays.asList(
    Map.of("language", "fr-FR", "value", "Bonjour"),
    Map.of("language", "es-ES", "value", "Hola")
);
Object addResult = lara.glossaries.addOrReplaceEntry("gls_1A2b3C4d5E6f7G8h9I0jKl", terms, null);

// Remove a specific term from glossary
Map<String, String> termToRemove = Map.of("language", "fr-FR", "value", "Bonjour");
Object removeResult = lara.glossaries.deleteEntry("gls_1A2b3C4d5E6f7G8h9I0jKl", termToRemove, null);

// Check import status
GlossaryImport importStatus = lara.glossaries.getImportStatus("gls_1A2b3C4d5E6f7G8h9I0jKl");

// Wait for import completion
GlossaryImport completedImport = lara.glossaries.waitForImport(glossaryImport, 300000L); // 5 minutes

// Export glossary
String csvData = lara.glossaries.export("gls_1A2b3C4d5E6f7G8h9I0jKl", Glossary.Type.CSV_TABLE_UNI, "en-US");

// Get glossary terms count
GlossaryCounts 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
List<Styleguide> styleguides = lara.styleguides.list();

// Get a specific styleguide by ID
Styleguide styleguide = lara.styleguides.get("stg_1A2b3C4d5E6f7G8h9I0jKl");

Translate with a styleguide

TranslateOptions options = new TranslateOptions()
    .setStyleguideId("stg_1A2b3C4d5E6f7G8h9I0jKl");  // Replace with actual styleguide ID

TextResult result = lara.translate("Hello, world!", "en-US", "it-IT", options);

Styleguide reasoning

Enable reasoning to see what the styleguide changed and why:

TranslateOptions options = new TranslateOptions()
    .setStyleguideId("stg_1A2b3C4d5E6f7G8h9I0jKl")
    .setStyleguideReasoning(true)
    .setStyleguideExplanationLanguage("en-US");

TextResult result = lara.translate("Hello, world!", "en-US", "it-IT", options);

StyleguideResults sgResults = result.getStyleguideResults();
if (sgResults != null) {
    System.out.println("Original translation: " + sgResults.getOriginalTranslation());

    for (StyleguideChange change : sgResults.getChanges()) {
        System.out.println("Before: " + change.getOriginalTranslation());
        System.out.println("After:  " + change.getRefinedTranslation());
        System.out.println("Why:    " + change.getExplanation());
    }
}

Translation Options

public class TranslateOptions {
    setAdaptTo(String... memoryIds)             // Memory IDs to adapt to
    setGlossaries(String... glossaryIds)        // Glossary IDs to use
    setInstructions(String... instructions)     // Translation instructions
    setStyle(TranslationStyle style)            // Translation style (FLUID, FAITHFUL, CREATIVE)
    setContentType(String contentType)          // Content type (text/plain, text/html, etc.)
    setMultiline(Boolean multiline)             // Enable multiline translation
    setTimeoutMs(Long timeoutMs)                // Request timeout in milliseconds
    setSourceHint(String sourceHint)            // Hint for source language detection
    setNoTrace(Boolean noTrace)                 // Disable request tracing
    setVerbose(Boolean verbose)                 // Enable verbose response
    setProfanitiesDetect(ProfanitiesDetect d)   // Detect profanities in: TARGET or SOURCE_TARGET
    setProfanitiesHandling(ProfanitiesHandling h) // How to handle detected profanities: DETECT, HIDE, or AVOID
    setStyleguideId(String id)                  // Styleguide ID to apply
    setStyleguideReasoning(boolean enabled)     // Enable styleguide change reasoning
    setStyleguideExplanationLanguage(String lang) // Language for change explanations
}

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)
TextResult result = lara.translate("Hello", "en-US", "fr-FR");

// Simple language codes
TextResult result = lara.translate("Hello", "en", "fr");

🌐 Supported Languages

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

List<String> languages = lara.getLanguages();
System.out.println("Supported languages: " + String.join(", ", languages));

⚙️ Configuration

Error Handling

The SDK provides detailed error information:

try {
    TextResult result = lara.translate("Hello", "en-US", "fr-FR");
    System.out.println("Translation: " + result.getTranslation());
} catch (LaraApiException e) {
    System.err.println("API Error [" + e.getStatusCode() + "]: " + e.getMessage());
    System.err.println("Error type: " + e.getType());
} catch (LaraException e) {
    System.err.println("SDK Error: " + e.getMessage());
}

📋 Requirements

Java 8 or higher
Maven or Gradle
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"

# Build the project
mvn clean compile dependency:copy-dependencies

# Run basic text translation example
cd examples
javac -cp ../target/classes:../target/dependency/* TextTranslation.java
java -cp .:../target/classes:../target/dependency/* TextTranslation

🏗️ Building from Source

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

# Build with Maven
mvn clean install

📄 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 76 Commits
.github/workflows		.github/workflows
examples		examples
src/main/java/com/translated/lara		src/main/java/com/translated/lara
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
pom.xml		pom.xml
version.py		version.py

Folders and files

Latest commit

History

Repository files navigation

Lara Java SDK

🌍 Features:

📚 Documentation

🚀 Quick Start

Installation

Basic Usage

📖 Examples

Text Translation

Document Translation

Audio Translation

Translation Memory Management

Glossary Management

🔧 API Reference

Core Components

🔐 Authentication

🌍 Translator

Text Translation

Quality Estimation

Profanity Detection and Handling

📖 Document Translation

Simple document translation

Document translation with status monitoring

Document upload

Document translation status monitoring

Download translated document

🎵 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

Language Codes

🌐 Supported Languages

⚙️ Configuration

Error Handling

📋 Requirements

🧪 Testing

🏗️ Building from Source

📄 License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages