Translate File

About Translate File

The Translate File service allows you to translate a text-based file while maintaining the original layout, images, and other visual elements.

Although retrieving only the translated text is quicker due to simpler computation, you also have the option to obtain the entire translated file.

You can customize your translation by specifying the output_language and the return_type.

Supported Languages

CosmosPlatform supports many languages, which are expected in ISO 639 language codes. You can find more information about in the Translate Text tutorial.

Refer to the ISO 639-1 codes for more options.

Supported File Formats

CosmosPlatform supports a wide range of document formats for file translation, including:

• Documents: .docx, .doc, .odt, .txt, .md, .pdf (only available for return_type=raw_text)
• Spreadsheets: .xlsx, .xls, .ods, .csv
• Presentations: .pptx, .ppt, .odp
• Notebooks: .ipynb

Step-by-step Tutorial

In this guide:

• Section 1: Prerequisites.
• Section 2: Setup Cosmos Python Client.
• Section 3: Translate a file. Parameters and examples.
• Section 4: Handle Errors.

1. Prerequisites

Before you begin, ensure you have:

• An active CosmosPlatform account
• API key from the API keys dashboard

2. Setup Cosmos Python Client

Using Python Cosmos client you can perform the API requests in a convenient way.

2.1. Install Cosmos Python Client:

Get the Cosmos Python client through PIP:

pip install delos-cosmos

2.2. Authenticate Requests:

Initialize the client with your API key:

from cosmos import CosmosClient

cosmos_client = CosmosClient(api_key=your-cosmos-api-key)

2.3. Call API:

You can start invoking any Cosmos endpoints. For example, let's try the /health endpoint to check the validity of your API key and the availability of the client services:

response = cosmos_client.status_health()
print(response)

3. Translate a file

Initialize the client and perform your request (/translate-file endpoint):

from cosmos import CosmosClient

cosmos_client = CosmosClient(api_key="your-cosmos-api-key")
response = cosmos_client.translate_file(
              filepath="path/to/file.docx",
              output_language="es"
            )
print(response)

The response :

{
  "request_id":"185bb400-e53b-433f-b539-e8cb3452a582",
  "response_id":"a145d330-6542-4510-81cb-543bd837b2f3",
  "status_code":200,
  "status":"success",
  "message":"Translation completed successfully",
  "data":
  {
    "translation":"Este documento contiene texto en inglés.",
    "file_url":"None"
  },
  "error":null,
  "timestamp":"2025-02-19T10:15:42.891708Z",
  "cost":0.0006803
}

3.1. Parameters:

The parameters for the file translation request are:

• The filepath contains the local path for the file to translate.

• The output_language determines the language for the translated file.

• The return_type parameter allows choosing two file translation modes (optional):

  • return_type=raw_text: Translation will only concern the text, dismissing the file formatting. The text will be returned directly in the response. It is the default behavior, being faster and less costly. (Default)
  • return_type=url: Cosmos API will process the file with its original layout and formatting. The link to download the translated file will be returned.

3.2. Examples:

For example, to simply return the translated text, use the following request (return_type=raw_text):

response = cosmos_client.translate_file(
              filepath="path/to/file.docx",
              output_language="es",
              return_type="raw_text"
            )
print(response)

The retrieved response will contain:

{
  "status_code": 200,
  "translation": "(Text translated in Spanish)"
}

This type of processing is faster since it is lighter in computation. If we require the file with its original layout, we can use the return_type=url parameter:

response = cosmos_client.translate_file(filepath="path/to/file.docx", output_language="es", return_type="url")
print(response)

The retrieved response will contain:

{
  "status_code": 200,
  "url": "https://platform.cosmos-suite.ai/files/translated/file_es.docx"
}

4. Handle Errors

If there’s an error, you’ll receive a error response with details. For example, if the output_language is missing:

{
  "status_code": 400,
  "error_message": "No output_language provided for translation."
}