translated/lara-sdk

Official Lara SDK for PHP

1.2.5 2025-09-29 12:55 UTC

Requires

• php: >=5.6.0
• ext-curl: *
• ext-json: *

MIT

• Translated

README

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

composer require translated/lara-php

Basic Usage

require_once 'vendor/autoload.php';

use Lara\LaraCredentials;
use Lara\Translator;
use Lara\LaraException;

// Set your credentials using environment variables (recommended)
$credentials = new LaraCredentials(
    getenv('LARA_ACCESS_KEY_ID'),
    getenv('LARA_ACCESS_KEY_SECRET')
);

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

// Simple text translation
try {
    $result = $lara->translate("Hello, world!", "en-US", "fr-FR");
    echo "Translation: " . $result->getTranslation() . PHP_EOL;
    // Output: Translation: Bonjour, le monde !
} catch (LaraException $error) {
    echo "Translation error: " . $error->getMessage() . PHP_EOL;
}

📖 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.php - 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
php text_translation.php

Document Translation

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

cd examples
php document_translation.php

Translation Memory Management

• memories_management.php - 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
php memories_management.php

Glossary Management

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

cd examples
php glossaries_management.php

🔧 API Reference

Core Components

🔐 Authentication

The SDK supports authentication via access key and secret:

$credentials = new LaraCredentials("your-access-key-id", "your-access-key-secret");
$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 = new LaraCredentials(
    getenv('LARA_ACCESS_KEY_ID'),
    getenv('LARA_ACCESS_KEY_SECRET')
);

🌍 Translator

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

Text Translation

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

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

// TextBlocks (mixed translatable/non-translatable content)
use Lara\TextBlock;

$textBlocks = [
    new TextBlock('Translatable text', true),
    new TextBlock('<br>', false),  // Non-translatable HTML
    new TextBlock('More translatable text', true),
];
$result = $lara->translate($textBlocks, "en-US", "fr-FR");

// With advanced options  
$options = new TranslateOptions([
    'instructions' => ["Formal tone"],
    'adaptTo' => ["mem_1A2b3C4d5E6f7G8h9I0jKl"],  // Replace with actual memory IDs
    'glossaries' => ["gls_1A2b3C4d5E6f7G8h9I0jKl"],  // Replace with actual glossary IDs
    'style' => "fluid",
    'timeoutInMillis' => 10000
]);

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

📖 Document Translation

Simple document translation

$filePath = "/path/to/your/document.txt";  // Replace with actual file path
$fileStream = $lara->documents->translate($filePath, "en-US", "fr-FR");

// With options
$options = new DocumentTranslateOptions();
$options->setAdaptTo(["mem_1A2b3C4d5E6f7G8h9I0jKl"]);  // Replace with actual memory IDs
$options->setGlossaries(["gls_1A2b3C4d5E6f7G8h9I0jKl"]);  // Replace with actual glossary IDs

$fileStream = $lara->documents->translate($filePath, "en-US", "fr-FR", $options);

Document translation with status monitoring

Document upload

//Optional: upload options
$uploadOptions = new DocumentUploadOptions();
$uploadOptions->setAdaptTo(["mem_1A2b3C4d5E6f7G8h9I0jKl"]);  // Replace with actual memory IDs
$uploadOptions->setGlossaries(["gls_1A2b3C4d5E6f7G8h9I0jKl"]);  // Replace with actual glossary IDs

$document = $lara->documents->upload($filePath, "en-US", "fr-FR", $uploadOptions);

Document translation status monitoring

$status = $lara->documents->status($document->getId());

Download translated document

$downloadOptions = new DocumentDownloadOptions();

$fileStream = $lara->documents->download($document->getId(), $downloadOptions);

🧠 Memory Management

// Create memory
$memory = $lara->memories->create("MyMemory");

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

// Add translation to multiple memories
$memoryImport = $lara->memories->addTranslation(
    ["mem_1A2b3C4d5E6f7G8h9I0jKl", "mem_2XyZ9AbC8dEf7GhI6jKlMn"],  // Replace with actual memory IDs
    "en-US", "fr-FR", "Hello", "Bonjour", "greeting_002"
);

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

// TMX import from file
$tmxFilePath = "/path/to/your/memory.tmx";  // Replace with actual TMX file path
$memoryImport = $lara->memories->importTmx("mem_1A2b3C4d5E6f7G8h9I0jKl", $tmxFilePath);

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

// Wait for import completion
$completedImport = $lara->memories->waitForImport($memoryImport, 300); // 5 minutes

📚 Glossary Management

// Create glossary
$glossary = $lara->glossaries->create("MyGlossary");

// Import CSV from file
$csvFilePath = "/path/to/your/glossary.csv";  // Replace with actual CSV file path
$glossaryImport = $lara->glossaries->importCsv("gls_1A2b3C4d5E6f7G8h9I0jKl", $csvFilePath);

// Check import status
$importStatus = $lara->glossaries->getImportStatus($glossaryImport->getId());

// Wait for import completion
$completedImport = $lara->glossaries->waitForImport($glossaryImport, 300); // 5 minutes

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

// Get glossary terms count
$counts = $lara->glossaries->counts("gls_1A2b3C4d5E6f7G8h9I0jKl");

Translation Options

// Constructor array pattern (recommended)
$options = new 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
]);

// Alternative setter pattern
$options = new TranslateOptions();
$options->setSourceHint("en-US");
$options->setAdaptTo(["mem_1A2b3C4d5E6f7G8h9I0jKl", "mem_2XyZ9AbC8dEf7GhI6jKlMn"]);  // Replace with actual memory IDs
$options->setInstructions(["Formal tone", "Use technical terminology"]);
$options->setGlossaries(["gls_1A2b3C4d5E6f7G8h9I0jKl", "gls_2XyZ9AbC8dEf7GhI6jKlMn"]);  // Replace with actual glossary IDs
$options->setContentType("text/html");
$options->setMultiline(true);
$options->setTimeoutInMillis(15000);
$options->setNoTrace(false);
$options->setVerbose(true);
$options->setStyle("faithful");

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", "en-US", "fr-FR");

// Simple language codes
$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:

$languages = $lara->getLanguages();
echo "Supported languages: " . implode(', ', $languages) . PHP_EOL;

⚙️ Configuration

Error Handling

The SDK provides detailed error information:

try {
    $result = $lara->translate("Hello", "en-US", "fr-FR");
    echo "Translation: " . $result->getTranslation() . PHP_EOL;
} catch (LaraException $e) {
    echo "API Error: " . $e->getMessage() . PHP_EOL;
} catch (LaraTimeoutException $e) {
    echo "Timeout Error: " . $e->getMessage() . PHP_EOL;
}

📋 Requirements

• PHP 7.4 or higher
• Composer
• 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
php text_translation.php

📄 License

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

Happy translating! 🌍✨