Translate document

To begin, you must first instantiate the Translator class. This is the mandatory first step for all operations within the Lara SDK.

Initialization Guide →

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 document. 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'], glossaries=['gls_1_id', 'gls_2_id'], output_format="pdf", style="fluid")

const options: DocumentTranslateOptions = {
  adaptTo: ['mem_1_id', 'mem_2_id'],
  glossaries: ['gls_1_id', 'gls_2_id'],
  outputFormat: 'pdf',
  style: 'fluid'
};

// 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.setGlossaries("gls_1_id", "gls_2_id");
options.setOutputFormat("pdf");
options.setStyle(TranslationStyle.FLUID);

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

$translateOptions = new DocumentTranslateOptions([
  "adaptTo" => ["mem_1_id", "mem_2_id"],
  "glossaries" => ["gls_1_id", "gls_2_id"],
  "style" => "fluid"
]);

// Translate a file
$translation = $lara->documents->translate($file_path, "en", "it", $translateOptions);

filePath := "test.txt"
filename := "test.txt"
source := "en-US"
target := "de-DE"

options := lara_sdk.DocumentTranslateOptions{}
options.AdaptTo = []string{"mem_1_id", "mem_2_id"}
options.Glossaries = []string{"gls_1_id", "gls_2_id"}
options.OutputFormat = "pdf"
options.Style = "fluid"

// Translate a document
reader, _ := translator.Documents.TranslateWithOptions(&filePath, &filename, &source, target, &options)

// Build options
val options = DocumentTranslateOptions().apply {
    setAdaptTo("mem_1_id", "mem_2_id")
    setGlossaries("gls_1_id", "gls_2_id")
    setOutputFormat("pdf")
    setStyle(TranslationStyle.FLUID)
}

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

var options = new DocumentTranslateOptions {
    AdaptTo = new[] { "mem_1_id", "mem_2_id" },
    Glossaries = new[] { "gls_1_id", "gls_2_id" },
    OutputFormat = "pdf",
    Style = TranslationStyle.Fluid
};

// Translate a document
var translation = await lara.Documents.Translate("path/to/file", "en", "it", options);

let fileURL = URL(fileURLWithPath: "path/to/file.pdf")
let fileData = try Data(contentsOf: fileURL)

let options = DocumentTranslateOptions(
    adaptTo: ["mem_1_id", "mem_2_id"],
    glossaries: ["gls_1_id", "gls_2_id"],
    outputFormat: "pdf",
    style: .fluid
)

// Translate a document
let translation = try await lara.documents.translate(
    data: fileData,
    filename: "file.pdf",
    source: "en",
    target: "it",
    options: options
)

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.
glossaries	String[]	No		A list of glossary IDs.
outputFormat	String	No		The desired output file format. Possible value: `pdf`
noTrace	Boolean	No	False	If set to True, source content and its translation will not be saved on our system. (AKA Incognito mode)
style	String	No	`faithful`	The style to apply to the translation. Available values: `faithful` `fluid` `creative`
password	String	No		The password of the PDF file if it's password protected.
extractionParams	DocumentExtractionParams	No		Options to customize the translation of specific file formats.

Currently, it is possible to specify extraction parameters only for DOCX files. Other formats will be supported in the future.

Possible extraction parameters for DOCX files are:

Field	Type	Required	Default	Description
extractComments	Boolean	No	False	Choose whether to extract comments added to the file.
acceptRevisions	Boolean	No	False	Choose whether to automatically accept revisions before extraction. If set to false and the document contains revisions an error is returned.

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'], glossaries=['gls_1_id', 'gls_2_id'], style="fluid")

const options: DocumentUploadOptions = {
  adaptTo: ['mem_1_id', 'mem_2_id'],
  glossaries: ['gls_1_id', 'gls_2_id'],
  style: 'fluid',
};

// 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");
options.setGlossaries("gls_1_id", "gls_2_id");
options.setStyle(TranslationStyle.FLUID);

// 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"],
  "glossaries" => ["gls_1_id", "gls_2_id"],
  "style" => "fluid"
]);

// Upload a document and start the translation process
$document = $lara->documents->upload($file_path, "en", "it", $translateOptions);

filePath := "test.pdf"
filename := "test.pdf"
source := "en-US"
target := "de-DE"

options := lara_sdk.DocumentUploadOptions{}
options.AdaptTo = []string{"mem_1_id", "mem_2_id"}
options.Glossaries = []string{"gls_1_id", "gls_2_id"}
options.Style = "fluid"

// Translate a document
doc, err := translator.Documents.UploadWithOptions(&filePath, &filename, &source, target, &options)

// Build options
val options = DocumentUploadOptions().apply {
    setAdaptTo("mem_1_id", "mem_2_id")
    setGlossaries("gls_1_id", "gls_2_id")
    setStyle(TranslationStyle.FLUID)
}

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

var options = new DocumentUploadOptions {
    AdaptTo = new[] { "mem_1_id", "mem_2_id" },
    Glossaries = new[] { "gls_1_id", "gls_2_id" },
    Style = TranslationStyle.Fluid
  };

var document = await lara.Documents.Upload("path/to/file", "en", "it", options);

let fileURL = URL(fileURLWithPath: "path/to/file.pdf")
let fileData = try Data(contentsOf: fileURL)

let options = DocumentUploadOptions(
    adaptTo: ["mem_1_id", "mem_2_id"],
    glossaries: ["gls_1_id", "gls_2_id"],
    style: .fluid
)

// Upload a document and start the translation process
let document = try await lara.documents.upload(
    data: fileData,
    filename: "file.pdf",
    source: "en",
    target: "it",
    options: options
)

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.
glossaries	String[]	No		A list of glossary IDs.
noTrace	Boolean	No	False	If set to True, source content and its translation will not be saved on our system.
style	String	No	`faithful`	The style to apply to the translation. Available values: `faithful` `fluid` `creative`

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"
];

// document
{
  "id": "doc_3TJ2ObqnrYTC2k5vSfLlqz",
  "status": "initialized",
  "source": "en-US",
  "target": "de-DE",
  "filename": "test.txt",
  "created_at": "2025-07-03T07:57:53.697Z",
  "updated_at": "2025-07-03T07:57:53.697Z"
}

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

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

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

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

// check the status of the document
document, _ := lara.Documents.Status(document.id)

// Check the status of the document
val document = lara.documents.status(document.id)

// Check the status of the document
var document = await lara.Documents.Status(document.Id);

// Check the status of the document
let document = try await lara.documents.status(document.id)

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 `upload` method.

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"
];

// document
{
  "id": "doc_3TJ2ObqnrYTC2k5vSfLlqz",
  "status": "translated",
  "source": "en-US",
  "target": "de-DE",
  "filename": "test.txt",
  "created_at": "2025-07-03T08:37:53.454Z",
  "updated_at": "2025-07-03T08:37:53.454Z"
}

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

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

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

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

// Download the translation:
translation, _ := lara.Documents.DownloadWithOptions(document.ID, &lara_sdk.DocumentDownloadOptions{
	OutputFormat: "pdf",
})

// Build options
val options = DocumentDownloadOptions().apply {
    setOutputFormat("pdf")
}

// Download the translation
val translation: InputStream = lara.documents.download(
    document.id,
    options
)

var downloadOptions = new DocumentDownloadOptions {
    OutputFormat = "pdf"
};

// Download the translation
var translation = await lara.Documents.Download(document.Id, downloadOptions);

let options = DocumentDownloadOptions(outputFormat: "pdf")

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

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 `upload` method.
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: `pdf`

📘
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.

❗️
XLIFF support
Support for inline tags within the <source> element of xliff files is limited to:
XLIFF 1.2:<g>, <x>, <ex>, <bx>, <ph>, <it>, and <mrk>.
XLIFF 2.0: <cp>, <ph>, <pc>, <sc>, <ec>, <sm>, <em> and <mrk>.

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
Go: v1.0.0
Swift: v1.0.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.

For more details see the pricing page