Lara PHP 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
• Translation Memory: Store and reuse translations for consistency
• Glossaries: Enforce terminology standards across translations
• Styleguides: Define tone, voice, and writing style rules for 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-sdk

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

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

Image Translation

• image_translation.php - Image translation examples
  • Basic image translation
  • Advanced options with memories and glossaries
  • Extract and translate text from an image
  • Edit translations and render them with layout or text-only paragraphs

cd examples
php image_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 (sync and async)
  • Glossary terms count
  • Import status checking

cd examples
php glossaries_management.php

Styleguide Management

• styleguides_management.php - Styleguide management examples
  • Create, list, get, update, delete styleguides
  • Update name, content, or both at once
  • Handling of non-existent styleguides

cd examples
php styleguides_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);

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

// Batch
$batch = $lara->qualityEstimation(
    "en-US",
    "it-IT",
    ["Good morning.", "The weather is nice."],
    ["Buongiorno.", "Il tempo è bello."]
);
foreach ($batch as $r) {
    echo $r->getScore() . "\n"; // e.g. 0.751, 0.713
}

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

🖼️ Image Translation

use Lara\ImageTranslationOptions;
use Lara\ImageTextTranslationOptions;
use Lara\ImageLayoutParagraph;
use Lara\ImageParagraph;

$imagePath = "/path/to/your/image.png";

// Translate image and receive a translated image stream
$translatedImageStream = $lara->images->translate($imagePath, "en", "fr", new ImageTranslationOptions([
    'model' => 'generative_fast',
    'style' => 'faithful'
]));
$output = fopen("translated.png", "wb");
stream_copy_to_stream($translatedImageStream, $output);
fclose($output);
fclose($translatedImageStream);

// Request complete layout metadata for classic rendering.
$textBlocks = $lara->images->translateText($imagePath, "en", "fr", new ImageTextTranslationOptions([
    'includeLayout' => true
]));
$paragraphs = $textBlocks->getParagraphs();

if (!empty($paragraphs)) {
    // includeLayout=true guarantees complete geometry and text styling.
    $first = $paragraphs[0];
    $paragraphs[0] = new ImageLayoutParagraph(
        $first->getText(), "Bonjour le monde !", $first->getBbox(),
        $first->getLinesBboxes(), $first->getTextInfo(), $first->getAlignment(),
        $first->getAdaptedToMatches(), $first->getGlossariesMatches()
    );

    $renderedImage = $lara->images->renderTranslated(
        $imagePath, $textBlocks->getSourceLanguage(), "fr", $paragraphs, "overlay"
    );
    $output = fopen("edited-overlay.png", "wb");
    stream_copy_to_stream($renderedImage, $output);
    fclose($output);
    fclose($renderedImage);

    // Generative models accept text-only paragraphs. Omit model for generative_fast.
    $textOnlyParagraphs = array_map(function ($paragraph) {
        return new ImageParagraph($paragraph->getText(), $paragraph->getTranslation());
    }, $paragraphs);
    $renderedImage = $lara->images->renderTranslated($imagePath, null, "fr", $textOnlyParagraphs);
    $output = fopen("edited-generative.png", "wb");
    stream_copy_to_stream($renderedImage, $output);
    fclose($output);
    fclose($renderedImage);
}

renderTranslated($filePath, $source, $target, $paragraphs, $model = null, $noTrace = false) renders supplied translations without translating them again. Pass null for the source language to omit it. Supported models are overlay, inpainting, generative, and generative_fast; omitting the model uses the API default, generative_fast. Set $noTrace to true to disable request tracing. As with translate, the returned value is a stream resource that the caller must close.

overlay and inpainting require every entry to be an ImageLayoutParagraph, with bbox, linesBboxes, textInfo, and alignment. Generative models accept both ImageParagraph and ImageLayoutParagraph. The API validates paragraph contents; incomplete layout is invalid. Memory and glossary matches are excluded from rendering requests.

includeLayout can be set in the options constructor or with setIncludeLayout(true). When it is true, every entry is an ImageLayoutParagraph containing the complete metadata required by classic rendering. Omitting the option, or setting it to false or null, preserves the text-only response. The independent verbose option (or setVerbose(true)) requests memory and glossary matches.

ImageBBox exposes getTopLeft(), getTopRight(), getBottomRight(), and getBottomLeft() integer coordinate pairs ([x, y]). ImageTextInfo exposes direction (ltr, rtl, or ttb), text color, and background color through getters. Alignment is left, center, or right. The SDK serializes layout using the API's snake_case field names.

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

// TMX import with a callback URL (notified when the import completes)
$memoryImport = $lara->memories->importTmx(
    "mem_1A2b3C4d5E6f7G8h9I0jKl",
    $tmxFilePath,
    false, // uncompressed input
    "https://your-server.example.com/lara/import-callback"
);

// Async memory export - returns a job ID; the result is delivered to your callback URL when ready
$exportJob = $lara->memories->exportAsync(
    "mem_1A2b3C4d5E6f7G8h9I0jKl",
    "https://your-server.example.com/lara/export-callback",
    "tmx" // optional, defaults to the server-side default ("tmx" or "jtm")
);
$jobId = $exportJob->getJobId();

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

// Share with the account or a group; shares can be renamed, listed, and revoked
$lara->memories->addAccountShare($memory->getId(), "Team memory");
$lara->memories->renameAccountShare($memory->getId(), "Company memory");
$lara->memories->addGroupShare($memory->getId(), "grp_1A2b3C4d5E6f7G8h9I0jKl", "Marketing memory");
$shares = $lara->memories->getShares($memory->getId());
$lara->memories->revokeGroupShare($memory->getId(), "grp_1A2b3C4d5E6f7G8h9I0jKl");
$lara->memories->revokeAccountShare($memory->getId());

📚 Glossary Management

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

// Import a glossary file (use \Lara\GlossaryFileFormat::TBX for TBX files)
$glossaryFilePath = "/path/to/your/glossary.csv";
$glossaryImport = $lara->glossaries->importFile("gls_1A2b3C4d5E6f7G8h9I0jKl", $glossaryFilePath,
    new \Lara\GlossaryImportOptions(['contentType' => \Lara\GlossaryFileFormat::CSV_TABLE_UNI]));

// Options default to unidirectional CSV.
// A callback can be supplied on its own:
// $lara->glossaries->importFile($glossary->getId(), $glossaryFilePath,
//     new \Lara\GlossaryImportOptions(['callbackUrl' => $callbackUrl]));

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

// Async glossary export - returns a job ID; the result is delivered to your callback URL when ready
$exportJob = $lara->glossaries->exportAsync(
    "gls_1A2b3C4d5E6f7G8h9I0jKl",
    "https://your-server.example.com/lara/export-callback",
    "csv/table-uni",
    "en-US"
);
$jobId = $exportJob->getJobId();

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

// Glossaries support the same account and group sharing workflow
$lara->glossaries->addAccountShare($glossary->getId(), "Team glossary");
$glossaryShares = $lara->glossaries->getShares($glossary->getId());
$lara->glossaries->revokeAccountShare($glossary->getId());

📋 Styleguide Management

// Create styleguide
$styleguide = $lara->styleguides->create("MyStyleguide", "Always use formal language.");

// List all styleguides
$styleguides = $lara->styleguides->getAll();

// Get a specific styleguide
$styleguide = $lara->styleguides->get("stg_1A2b3C4d5E6f7G8h9I0jKl");

// Update styleguide — pass null for fields you don't want to change
// Update only the name
$styleguide = $lara->styleguides->update("stg_1A2b3C4d5E6f7G8h9I0jKl", "UpdatedStyleguide");

// Update only the content
$styleguide = $lara->styleguides->update("stg_1A2b3C4d5E6f7G8h9I0jKl", null, "Always use informal language.");

// Update both
$styleguide = $lara->styleguides->update("stg_1A2b3C4d5E6f7G8h9I0jKl", "UpdatedStyleguide", "Always use informal language.");

// Share a styleguide and inspect visible account, group, and user shares
$lara->styleguides->addGroupShare($styleguide->getId(), "grp_1A2b3C4d5E6f7G8h9I0jKl", "Marketing styleguide");
$styleguideShares = $lara->styleguides->getShares($styleguide->getId());

// Delete styleguide
$styleguide = $lara->styleguides->delete("stg_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! 🌍✨