🚧

SDK availability

Currently document translation is available only in the Typescript/Javascript and Java SDKs.

PHP and Python version will be updated soon with this feature.

Translator

The Translator class is the core component of the lara-sdk, designed for translating text and documents. It must be initialized with authentication credentials.

import {Credentials, Translator} from "@translated/lara";

const LARA_ACCESS_KEY_ID: string = "your-access-key-id";
const LARA_ACCESS_KEY_SECRET: string = "your-access-key-secret";

// Initialization of the Translator class
const credentials = new Credentials(LARA_ACCESS_KEY_ID, LARA_ACCESS_KEY_SECRET)
const lara: Translator = new Translator(credentials);

import com.translated.lara.Credentials;
import com.translated.lara.translator.Translator;

private static final String LARA_ACCESS_KEY_ID = "your-access-key-id";
private static final String LARA_ACCESS_KEY_SECRET = "your-access-key-secret";

// Initialization of the Translator class
Credentials credentials = new Credentials(LARA_ACCESS_KEY_ID, LARA_ACCESS_KEY_SECRET);
Translator lara = new Translator(credentials);

Translate document

All documents functionalities can be accessed via the same Translator (lara in the example) object of the above example, through the Documents class.

Document translation is an asynchronous process consisting of three phases.

1. Upload the file
2. Wait for Lara to finish the process, polling the status at regular intervals until it changes to translated
3. Download the file

For your convenience the SDK includes a translate method that takes care of the entire process.

Once uploaded with the upload method, Lara will return a Document object; the id of this object can be used both to check the status with the status method, both to download the translated file with the download method once its status became translated.

Consistent Formatting Guarantee
When you translate a document with Lara, the output will try to maintain the same layout, structure, and formatting as the original file. You’ll get back a fully translated version of your document—just as it was, only in your chosen target language.

About Image-Based and Scanned Documents
Lara is designed to handle a wide range of document types, including those with images and scanned content. While we strive to preserve formatting and extract text as accurately as possible, certain image-based or low-quality scanned files may present challenges that affect translation accuracy or layout fidelity. We continuously improve our technology to better manage these cases, but for optimal results, we recommend using high-quality, text-based files whenever possible.

Document object

Upload a document

The upload method will take care of uploading the source file to Lara and to start the translation process.

Request

const options: DocumentUploadOptions = {
  adaptTo: ['mem_1_id', 'mem_2_id']
};

// Upload a document and start the translation process
const document: Document = await lara.documents.upload(file, 'test.xml', 'en', 'it', options);

const options = new DocumentUploadOptions();
options.setAdaptTo("mem_1_id", "mem_2_id");

// Upload a document and start the translation process
Document document = lara.documents.upload(file, "en", "it", options);

Here follows the basic fields for the upload method:

There are some options available to customize the behavior of the upload method:

The result of the upload method is a Document object that is needed to check the translation status and download the translated document.

Response

// document
{
  status: 'initialized',
  id: 'doc_3TJ2ObqnrYTC2k5vSfLlqz',
  filename: 'test.txt',
  updatedAt: 2025-05-15T09:28:14.626Z,
  createdAt: 2025-05-15T09:28:14.626Z,
  source: 'en',
  target: 'it'
}

// document
Document(
    status="initialized",
    id="doc_3TJ2ObqnrYTC2k5vSfLlqz",
    filename="test.txt",
    updatedAt=2025-05-15T09:28:14.626Z,
    createdAt=2025-05-15T09:28:14.626Z,
    source="en",
    target="it"
)

Check status

After the upload is finished, it is possible to check the status of the translation at regular intervals. This can be done with the status method:

Request

// check the status of the document
document = await lara.documents.status(document.id);

// check the status of the document
document = lara.documents.status(document.getId());

The method takes as unique parameter the id of the Document object obtained with the upload method.

Response

// document
{
  status: 'translated',
  id: 'doc_3TJ2ObqnrYTC2k5vSfLlqz',
  filename: 'test.txt',
  updatedAt: 2025-05-15T09:28:22.347Z,
  createdAt: 2025-05-15T09:28:14.626Z,
  source: 'en',
  target: 'it'
}

// document
Document(
    status="translated",
    id="doc_3TJ2ObqnrYTC2k5vSfLlqz",
    filename="test.txt",
    updatedAt=2025-05-15T09:28:22.347Z,
    createdAt=2025-05-15T09:28:14.626Z,
    source="en",
    target="it"
)

Download the translation

After updating the document status with the status method and setting it to translated, you can download the translated document with the download method.

Request

const options: DocumentDownloadOptions = {
  outputFormat: 'pdf'
}

// Download the translation:
const translation = await lara.documents.download(document.id, options);

const options = new DocumentDownloadOptions();
options.setOutputFormat("pdf");

// check the status of the document
InputStream translation = lara.documents.download(document.getId(), options);

Here follows the basic fields for the download method:

Some options are available to customize the behavior of the download method:

📘

Output file format

This option can be used only with pdf source file.

Lara returns translated files with the same format as source files, except for pdf files for which by default it will return a docx file.

In this scenario, to get a file with the same format, you need to use the outputFormat = "pdf" option.

Put it all together

The SDK contains a translate method that simplifies the process of translating documents by uploading the file, checking the status at regular intervals, and returning the result of the download function.

Request

const options: DocumentTranslateOptions = {
  adaptTo: ['mem_1_id', 'mem_2_id'],
  outputFormat: 'pdf'
};

// Translate a document
const translation = await lara.documents.translate(file, 'test.pdf', 'en', 'it', options);

const options = new DocumentTranslateOptions();
options.setAdaptTo("mem_1_id", "mem_2_id");
options.setOutputFormat("pdf");

// Translate a file
InputStream translation = lara.documents.translate(file, "en", "it", options);

Here follows the basic fields for the translate method:

Some options are available to customize the behavior of the translate method: