Lara Node.js 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
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

npm install @translated/lara

Basic Usage

const { Credentials, Translator } = require('@translated/lara');

// Set your credentials using environment variables (recommended)
const credentials = new Credentials(
    process.env.LARA_ACCESS_KEY_ID,
    process.env.LARA_ACCESS_KEY_SECRET
);

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

// Simple text translation
async function translateText() {
    try {
        const result = await lara.translate("Hello, world!", "en-US", "fr-FR");
        console.log("Translation: " + result.translation);
        // Output: Translation: Bonjour, le monde !
    } catch (error) {
        console.error("Translation error:", error.message);
    }
}

translateText();

📖 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.js - 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
node text_translation.js

Document Translation

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

cd examples
node document_translation.js

Image Translation

image_translation.js - Image translation examples
- Basic image translation
- Advanced options with memories and glossaries
- Extract and translate text from an image

cd examples
node image_translation.js

Audio Translation

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

cd examples
node audio_translation.js

Translation Memory Management

memories_management.js - 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
node memories_management.js

Glossary Management

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

cd examples
node glossaries_management.js

🔧 API Reference

Core Components

🔐 Authentication

The SDK supports authentication via access key and secret:

const credentials = new Credentials("your-access-key-id", "your-access-key-secret");
const 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"

const credentials = new Credentials(
    process.env.LARA_ACCESS_KEY_ID,
    process.env.LARA_ACCESS_KEY_SECRET
);

🌍 Translator

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

Text Translation

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

// Multiple strings
const result = await lara.translate(["Hello", "World"], "en-US", "fr-FR");

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

// With advanced options
const options = {
    instructions: ["Formal tone"],
    adaptTo: ["mem_1A2b3C4d5E6f7G8h9I0jKl"],  // Replace with actual memory IDs
    glossaries: ["gls_1A2b3C4d5E6f7G8h9I0jKl"],  // Replace with actual glossary IDs
    style: "fluid",
    timeoutInMillis: 10000
};

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

Language Detection

Use detect() to automatically identify the language of one or multiple texts.

// Single string detection
const single = await lara.detect("Bonjour tout le monde");
console.log(single.language); // fr

// Multiple strings detection
const multiple = await lara.detect(["Hello world", "How are you?"]);
console.log(multiple.languages); // "en"

You can provide a hint (expected source language) and a passlist (restrict candidates) to improve accuracy.

// Detection with hint and passlist
const detected = await lara.detect(
  "Es un día soleado",
  "es",                      // hint (optional)
  ["es", "pt", "fr"]         // passlist (optional)
);
console.log(detected.language); // es

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 arrays to get one result per pair.

// Single pair
const single = await lara.qualityEstimation(
  "en-US",
  "it-IT",
  "Hello, how are you today?",
  "Ciao, come stai oggi?"
);
console.log(single.score); // e.g. 0.768

// Batch
const batch = await lara.qualityEstimation(
  "en-US",
  "it-IT",
  ["Good morning.", "The weather is nice."],
  ["Buongiorno.", "Il tempo è bello."]
);
console.log(batch.map(r => r.score)); // e.g. [0.751, 0.713]

📖 Document Translation

Simple document translation

const fs = require('fs');

const fileStream = fs.createReadStream("/path/to/your/document.txt");  // Replace with actual file path
const translatedContent = await lara.documents.translate(fileStream, "document.txt", "en-US", "fr-FR");

// With options
const options = {
    adaptTo: ["mem_1A2b3C4d5E6f7G8h9I0jKl"],  // Replace with actual memory IDs
    glossaries: ["gls_1A2b3C4d5E6f7G8h9I0jKl"],  // Replace with actual glossary IDs
    style: "fluid"
};

const translatedContent = await lara.documents.translate(fileStream, "document.txt", "en-US", "fr-FR", options);

Document translation with status monitoring

Document upload

//Optional: upload options
const uploadOptions = {
    adaptTo: ["mem_1A2b3C4d5E6f7G8h9I0jKl"],  // Replace with actual memory IDs
    glossaries: ["gls_1A2b3C4d5E6f7G8h9I0jKl"]  // Replace with actual glossary IDs
};

const document = await lara.documents.upload(fileStream, "document.txt", "en-US", "fr-FR", uploadOptions);

Document translation status monitoring

const status = await lara.documents.status(document.id);

Download translated document

const translatedContent = await lara.documents.download(document.id);

🖼️ Image Translation

const fs = require("fs");

const imageStream = fs.createReadStream("/path/to/your/image.png"); // Replace with actual file path

// Translate image and receive a translated image stream
const translatedImageStream = await lara.images.translate(imageStream, "en", "fr", {
    textRemoval: "inpainting",
    style: "faithful"
});

// Extract and translate text blocks from an image
const textBlocks = await lara.images.translateText(imageStream, "en", "fr", {
    adaptTo: ["mem_1A2b3C4d5E6f7G8h9I0jKl"],
    glossaries: ["gls_1A2b3C4d5E6f7G8h9I0jKl"],
});

🔊 Audio Translation

Simple audio translation

const fs = require("fs");

const fileStream = fs.createReadStream("/path/to/your/audio.mp3");  // Replace with actual file path
const translatedStream = await lara.audio.translate(fileStream, "audio.mp3", "en-US", "de-DE");

// With options
const options = {
    adaptTo: ["mem_1A2b3C4d5E6f7G8h9I0jKl"],  // Replace with actual memory IDs
    glossaries: ["gls_1A2b3C4d5E6f7G8h9I0jKl"]  // Replace with actual glossary IDs
};

const translatedStream = await lara.audio.translate(fileStream, "audio.mp3", "en-US", "de-DE", options);

Audio translation with status monitoring

Audio upload

// Optional: upload options
const uploadOptions = {
    adaptTo: ["mem_1A2b3C4d5E6f7G8h9I0jKl"],  // Replace with actual memory IDs
    glossaries: ["gls_1A2b3C4d5E6f7G8h9I0jKl"]  // Replace with actual glossary IDs
};

const audio = await lara.audio.upload(fileStream, "audio.mp3", "en-US", "de-DE", uploadOptions);

Audio translation status monitoring

const status = await lara.audio.status(audio.id);

Download translated audio

const translatedStream = await lara.audio.download(audio.id);

🧠 Memory Management

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

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

// Add translation to multiple memories
const memoryImport = await lara.memories.addTranslation(["mem_1A2b3C4d5E6f7G8h9I0jKl", "mem_2XyZ9AbC8dEf7GhI6jKlMn"], "en-US", "fr-FR", "Hello", "Bonjour", "greeting_002");

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

// TMX import from file
const tmxFileStream = fs.createReadStream("/path/to/your/memory.tmx");  // Replace with actual TMX file path
const memoryImport = await lara.memories.importTmx("mem_1A2b3C4d5E6f7G8h9I0jKl", tmxFileStream);

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

// Wait for import completion
const completedImport = await lara.memories.waitForImport(memoryImport, undefined, 300000); // 5 minutes

📚 Glossary Management

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

// Import CSV from file
const csvFileStream = fs.createReadStream("/path/to/your/glossary.csv");  // Replace with actual CSV file path
const glossaryImport = await lara.glossaries.importCsv("gls_1A2b3C4d5E6f7G8h9I0jKl", csvFileStream);

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

// Wait for import completion
const completedImport = await lara.glossaries.waitForImport(glossaryImport, undefined, 300000); // 5 minutes

// Export glossary
const csvData = await lara.glossaries.export("gls_1A2b3C4d5E6f7G8h9I0jKl", "csv/table-uni", "en-US");

// Get glossary terms count
const counts = await lara.glossaries.counts("gls_1A2b3C4d5E6f7G8h9I0jKl");

Translation Options

const TranslateOptions = {
    adaptTo: ["mem_1A2b3C4d5E6f7G8h9I0jKl"],              // Memory IDs to adapt to
    glossaries: ["gls_1A2b3C4d5E6f7G8h9I0jKl"],           // Glossary IDs to use
    instructions: ["instruction"],                        // Translation instructions
    style: "fluid",                                       // Translation style (fluid, faithful, creative)
    contentType: "text/plain",                            // Content type (text/plain, text/html, etc.)
    multiline: true,                                      // Enable multiline translation
    timeoutInMillis: 10000,                               // Request timeout in milliseconds
    sourceHint: "en",                                     // Hint for source language detection
    noTrace: 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)
const result = await lara.translate("Hello", "en-US", "fr-FR");

// Simple language codes
const result = await 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:

const languages = await lara.getLanguages();
console.log("Supported languages: " + languages.join(', '));

⚙️ Configuration

Error Handling

The SDK provides detailed error information:

try {
    const result = await lara.translate("Hello", "en-US", "fr-FR");
    console.log("Translation: " + result.translation);
} catch (error) {
    if (error.constructor.name === 'LaraApiError') {
        console.error("API Error [" + error.statusCode + "]: " + error.message);
        console.error("Error type: " + error.type);
    } else {
        console.error("SDK Error: " + error.message);
    }
}

📋 Requirements

Node.js 12 or higher
npm or yarn
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
node text_translation.js

📄 License

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

Happy translating! 🌍✨

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Lara Node.js 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

Language Detection

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

Translation Options

Language Codes

🌐 Supported Languages

⚙️ Configuration

Error Handling

📋 Requirements

🧪 Testing

📄 License