Translate Document
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.
from lara_sdk import Translator, Credentials
LARA_ACCESS_KEY_ID = "your-access-key-id"
LARA_ACCESS_KEY_SECRET = "your-access-key-secret"
# Initialization of the Translator class
credentials = Credentials(access_key_id=LARA_ACCESS_KEY_ID, access_key_secret=LARA_ACCESS_KEY_SECRET)
lara = Translator(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);
use Lara\Translator;
use Lara\LaraCredentials;
define("LARA_ACCESS_KEY_ID", "your-access-key-id");
define("LARA_ACCESS_KEY_SECRET", "your-access-key-secret");
// Initialization of the Translator class
$credentials = new LaraCredentials(LARA_ACCESS_KEY_ID, LARA_ACCESS_KEY_SECRET);
$lara = new Translator($credentials);
Translate document
All document 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.
- Upload the file
- Wait for Lara to finish the process, polling the status at regular intervals until it changes to
translated
- 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
Field | Type | Description |
---|---|---|
id | String | Unique ID of the memory. Format: doc_xyz123 |
status | String | The current status of the translation. |
source | String | The source language of the document. |
target | String | The target language of the translation. |
filename | String | Filename of the source file. |
createdAt | DateTime | When the document is created. |
updatedAt | DateTime | When the document is last updated (equal to created_at with no updates). |
options | DocumentOptions | Options related to the document translation. |
translatedChars | Integer | The number of translated chars. |
totalChars | Integer | The number of chars in the document. |
errorReason | String | The reason of the error, if any. |
Translate method
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
# Translate a document
translation = lara.documents.translate(file_path, "test.pdf", source="en", target="it", adapt_to=['mem_1_id', 'mem_2_id'], output_format="pdf")
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);
final DocumentTranslateOptions 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);
$translateOptions = new DocumentTranslateOptions([
"adaptTo" => ["mem_1_id", "mem_2_id"]
]);
// Translate a file
$translation = $lara->documents->translate($file_path, "en", "it", $translateOptions);
Here follows the basic fields for the translate
method:
Field | Type | Required | Default | Description |
---|---|---|---|---|
file / filePath | File / String | Yes | The input file/the path to input file to translate. | |
filename | String | Yes* | Only the Typescript/Javascript SDK requires the filename as parameter. | |
source | String | No | Autodetected | The source language code (e.g., "en-EN" for English). If not specified, the system will attempt to detect it automatically. |
target | String | Yes | The target language code (e.g., "it-IT" for Italian). This specifies the language you want the text translated into. | |
options | DocumentTranslateOptions | No | See the table below for details. |
Some options are available to customize the behavior of the translate
method:
Field | Type | Required | Default | Description |
---|---|---|---|---|
adaptTo | String[] | No | Default is all Memories on your account | A list of translation memory IDs for adapting the translation. |
outputFormat | String | No | The desired output file format. Possible value: | |
noTrace | Boolean | No | False | If set to True, source content and its translation will not be saved on our system. |
The following sections provide a detailed breakdown of the phases and methods utilized by the translate
method.
Upload a document
The upload
method will take care of uploading the source file to Lara and starting the translation process.
Request
# Upload a document and start the translation process
document = lara.documents.upload(file_path, "text.pdf", source="en", target="it", adapt_to=['mem_1_id', 'mem_2_id'])
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);
final DocumentUploadOptions 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);
$translateOptions = new DocumentTranslateOptions(["adaptTo" => ["mem_1_id", "mem_2_id"]]);
// Upload a document and start the translation process
$document = $lara->documents->upload($file_path, "en", "it", $translateOptions);
Here follows the basic fields for the upload
method:
Field | Type | Required | Default | Description |
---|---|---|---|---|
file | File | Yes | The input file to translate. | |
filename | String | Yes* | The Typescript/Javascript and Python SDKs require the filename as a parameter. | |
source | String | No | Autodetected | The source language code (e.g., "en-EN" for English). If not specified, the system will attempt to detect it automatically. |
target | String | Yes | The target language code (e.g., "it-IT" for Italian). This specifies the language you want the text translated into. | |
options | DocumentUploadOptions | No | See the table below for details. |
There are some options available to customize the behavior of the upload
method:
Field | Type | Required | Default | Description |
---|---|---|---|---|
adaptTo | String[] | No | Default is all Memories on your account | A list of translation memory IDs for adapting the translation. |
noTrace | Boolean | No | False | If set to True, source content and its translation will not be saved on our system. |
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
document = Document(
status="initialized",
id="doc_3TJ2ObqnrYTC2k5vSfLlqz",
filename="test.txt",
updatedAt="2025-05-29T18:00:24.779000+00:00",
createdAt="2025-05-29T18:00:24.779000+00:00",
source="en",
target="it"
)
// 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"
)
// document
$document = [
"status" => "initialized",
"id" => "doc_3TJ2ObqnrYTC2k5vSfLlqz",
"filename" => "test.txt",
"updated_at" => "2025-05-29T18:00:24.779000+00:00",
"created_at" => "2025-05-29T18:00:24.779000+00:00",
"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 = lara.documents.status(document.id)
// 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());
// 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.
Field | Type | Required | Default | Description |
---|---|---|---|---|
id | String | Yes | The document id obtained with the |
Response
# document
document = Document(
status="translated",
id="doc_3TJ2ObqnrYTC2k5vSfLlqz",
filename="test.txt",
updatedAt="2025-05-29T18:00:32.519000+00:00",
createdAt="2025-05-29T18:00:32.519000+00:00",
source="en",
target="it"
)
// 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"
)
// document
$document = [
"status" => "translated",
"id" => "doc_3TJ2ObqnrYTC2k5vSfLlqz",
"filename" => "test.txt",
"updated_at" => "2025-05-29T18:00:32.519000+00:00",
"created_at" => "2025-05-15T09:28:14.626",
"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
# Download the translation:
translation = lara.documents.download(document.id, output_format="pdf")
const options: DocumentDownloadOptions = {
outputFormat: 'pdf'
}
// Download the translation:
const translation = await lara.documents.download(document.id, options);
final DocumentDownloadOptions options = new DocumentDownloadOptions();
options.setOutputFormat("pdf");
// Download the translation:
InputStream translation = lara.documents.download(document.getId(), options);
$downloadOptions = new DocumentDownloadOptions(["outputFormat" => "pdf"]);
// Download the translation:
$translation = $lara->documents->download($document->getId(), $downloadOptions);
Here follows the basic fields for the download
method:
Field | Type | Required | Default | Description |
---|---|---|---|---|
id | String | Yes | The id of the document obtained with the | |
options | DownloadDocumentOptions | No | See the table below for details. |
Some options are available to customize the behavior of the download
method:
Field | Type | Required | Default | Description |
---|---|---|---|---|
outputFormat | String | No | The desired output file format. Possible value: |
Output file format
This option can be used only with
Lara returns translated files with the same format as source files, except for
docx
file.In this scenario, to get a file with the same format, you need to use the
outputFormat = "pdf"
option.
Availability of Document Translation in SDKs
Starting from the following SDK versions, the Document Translation feature is available:
- Python: v1.3.0
- Node.js (TypeScript/JavaScript): v1.4.0
- Java: v1.2.4
- PHP: v1.1.0
For more details on implementation, refer to the SDK-specific documentation.
Billing & Character Usage
Lara determines usage and billing based on the number of characters extracted from the document’s text, not the file size, and applies this according to your subscription plan.
- Free Plan (Registered Users):
The number of characters extracted from the document is counted and applied to your monthly free character quota. - Pro and Team Plans:
A minimum charge of 20,000 characters applies per document. If a document contains fewer than 20,000 characters, it will still be billed as 20,000. For documents with 20,000 or more characters, only the exact count is billed.
Updated 4 days ago