Switch from ModernMT

1. Overview

This guide provides a technical mapping between ModernMT API endpoints and the Lara Translation API. Lara is an adaptive AI platform that balances Large Language Models (LLM) with traditional Machine Translation speed.

2. Authentication Strategy

The most significant change in your integration will be the authentication flow.

• ModernMT: Uses a persistent API Key passed in the MMT-ApiKey header.
• Lara API: Uses a JWT (Bearer Token) system. You must first exchange your Access Key for a short-lived token, then keep it alive using a refresh token.

Auth Flow Comparison

2.1 Getting a Token (Access Key Flow)

Send a POST to /v2/auth/ with your Access Key ID in the body and an HMAC-SHA256 signature in the Authorization header. Every request also requires a Date or X-Lara-Date header within ±5 minutes of server time.

Build the signature by HMAC-SHA256-signing this canonical string with your Access Key secret, then Base64-encoding the result:

METHOD\nPATH\nCONTENT-MD5\nCONTENT-TYPE\nDATE

Set the header as:

Authorization: Lara:<base64-signature>

Example request:

POST /v2/auth/
Content-Type: application/json
X-Lara-Date: 2024-06-01T12:00:00.000Z
Authorization: Lara:<base64-hmac-signature>

{ "id": "<your-access-key-id>" }

Example response:

{ "token": "<JWT access token>" }

The refresh token is returned in the response header X-Lara-Refresh-Token. Store it — you will need it to renew the access token without re-authenticating.

2.2 Refreshing an Expired Token

Access tokens expire after 10 minutes. Use the refresh token (valid for 1 hour) to obtain a new pair without resending your Access Key.

POST /v2/auth/refresh
Authorization: Bearer <refresh-token>
X-Lara-Date: 2024-06-01T12:10:00.000Z

{ "token": "<new JWT access token>" }

A new refresh token is also returned in X-Lara-Refresh-Token. Discard the old one and store the new one.

2.3 Common HTTP Responses

Keep an eye out for these status codes when debugging your auth flow:

1. 200: Success.
2. 401 (Unauthorized): Token is missing, invalid, or expired.
3. 403 (Forbidden): Token is valid but lacks necessary permissions.

3. Core Translation Mapping

The main translation endpoint in Lara is /translate/.

Request Parameter Mapping

4. Quality Estimation (QE)

Lara maintains full parity with ModernMT’s Quality Estimation functionality. You can continue to use the same endpoints and logic to receive numerical quality scores (0.0 to 1.0) for your segments.

QE Endpoint Mapping

Integration Note: The request parameters and response JSON structure for these endpoints remain identical to your current ModernMT implementation.

5. Translation Memories (TM)

Lara uses Translation Memories to adapt output in real-time without retraining.

Note: Lara's TMX import is asynchronous. You must poll GET /memories/imports/[id] to check the status.

6. Glossaries

Lara glossaries ensure terminology consistency.

7. Document Translation Flow

Unlike ModernMT's direct document endpoints, Lara uses a secure Three-Step Flow for file security:

Request Upload URL: GET /documents/upload-url to get a pre-signed S3/Storage URL.
Upload File: Perform a PUT request directly to the provided URL.
Process: Call POST /documents/ to begin analysis/translation.
Poll & Download: Monitor status via GET /documents/[id] and download via GET /documents/[id]/download-url.

8. Error Handling Comparison

Lara follows standard HTTP status codes:

• 200/204: Success.
• 400: Bad Request (Check your parameters).
• 401: Unauthorized (Token expired or missing).
• 403: Forbidden (Insufficient permissions).
• 404: Not Found (Resource ID does not exist).

9. New Features in Lara (Not in ModernMT)

When migrating, consider implementing these additional Lara capabilities:

• Audio Translation: Full speech-to-speech translation with voice_gender selection.
• Image Translation: Translate text inside images or extract translated text.
• Style Control: Force formal or informal tone via the style parameter.
• Segmentation: Specialized endpoint to split text into CAT-compatible units.