Translation Service Guide¶

This guide explains how to use the Language Server Translation API for single (synchronous) text translation tasks. It covers endpoints, request formats, supported providers, and all payload parameters.

Request Headers¶

Ensure your requests include the following headers:

Accept: application/json
X-API-Key: YOUR_API_KEY   # (Replace YOUR_API_KEY with your actual API key)
Content-Type: application/json

Supported Translation Providers¶

The Translation API supports the following providers:

Provider	Model Name	Description
`AZURE`	`azure`	Microsoft Azure Translator
`GOOGLE`	`nmt` (default), `base`	Google Cloud Translation API v2
`SARVAM`	`sarvam-translate:v1`	Sarvam AI Translation
`NLLB`	`nllb`	Meta's No Language Left Behind

Environment Variables Configuration¶

Each provider requires specific environment variables to be configured on the server:

Azure Translator¶

AZURE_TRANSLATION_SUBSCRIPTION_KEY=your_subscription_key
AZURE_TRANSLATION_ENDPOINT=https://api.cognitive.microsofttranslator.com
AZURE_TRANSLATION_LOCATION=your_resource_location  # e.g., eastus

Google Cloud Translation¶

SERVICE_ACCOUNT={"type":"service_account","project_id":"..."}  # Service account JSON

Note

The service account must have Cloud Translation API permissions enabled.

Sarvam AI¶

SARVAM_API_KEY=your_sarvam_api_key

NLLB (No Language Left Behind)¶

NLLB_API_KEY=your_nllb_api_key
NLLB_API_URL=https://your-nllb-api-endpoint.com/translate

Supported Language Codes¶

The following language codes are supported across all providers:

Code	Language
`en`	English
`hi`	Hindi
`ta`	Tamil
`te`	Telugu
`ml`	Malayalam
`kn`	Kannada
`bn`	Bengali
`gu`	Gujarati
`mr`	Marathi
`or`	Odia
`as`	Assamese

Note

Sarvam AI automatically appends -IN to language codes (e.g., hi becomes hi-IN)
NLLB uses extended codes internally (e.g., hi → hin_Deva, en → eng_Latn)
Other providers use the codes as-is

Single (Sync) Translation¶

Single translation is used for processing text synchronously. The API will return the translated text immediately.

Endpoint Details¶

Endpoint: https://language-server-url/v1/task/translation
Method: POST

Request Body Structure¶

{
  "user_email": "your_email@example.com",
  "project_name": "MyProject",
  "source_language": "en",
  "target_language": "hi",
  "provider": "GOOGLE",
  "text": [
    "Hello, how are you?",
    "This is a test translation."
  ],
  "models": ["nmt"]
}

Request Body Fields¶

Mandatory Fields¶

Field	Type	Description
`user_email`	string	Your user email address
`project_name`	string	Name of your project
`source_language`	string	Source language code (e.g., `en`, `hi`)
`target_language`	string	Target language code (e.g., `hi`, `ta`)
`provider`	string	Translation provider: `AZURE`, `GOOGLE`, `SARVAM`, or `NLLB`
`text`	array	List of strings to translate (must be non-empty)

Optional Fields¶

Field	Type	Description	Default
`models`	array	List of models to use	Provider-specific default

Default models by provider: - Google: nmt (Neural Machine Translation) - Azure: azure (standard model) - Sarvam: sarvam-translate:v1 - NLLB: nllb

Example cURL Commands¶

Example 1: Google Translation¶

curl -X 'POST' \
  'https://language-server-url/v1/sync/translation' \
  -H 'accept: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "user_email": "user@example.com",
  "project_name": "MyProject",
  "source_language": "en",
  "target_language": "hi",
  "provider": "GOOGLE",
  "text": ["Hello, world!", "How are you?"],
  "models": ["nmt"]
}'

Example 2: Azure Translation¶

curl -X 'POST' \
  'https://language-server-url/v1/sync/translation' \
  -H 'accept: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "user_email": "user@example.com",
  "project_name": "MyProject",
  "source_language": "en",
  "target_language": "ta",
  "provider": "AZURE",
  "text": ["Good morning", "Thank you"]
}'

Example 3: Sarvam AI Translation¶

curl -X 'POST' \
  'https://language-server-url/v1/sync/translation' \
  -H 'accept: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "user_email": "user@example.com",
  "project_name": "MyProject",
  "source_language": "en",
  "target_language": "hi",
  "provider": "SARVAM",
  "text": ["Welcome", "Goodbye"]
}'

Example 4: NLLB Translation¶

curl -X 'POST' \
  'https://language-server-url/v1/sync/translation' \
  -H 'accept: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "user_email": "user@example.com",
  "project_name": "MyProject",
  "source_language": "hi",
  "target_language": "en",
  "provider": "NLLB",
  "text": ["नमस्ते", "आप कैसे हैं?"]
}'

Response Format¶

All translation providers return a standardized response format:

Success Response¶

{
  "translations": [
    {
      "input": "Hello, world!",
      "output": "नमस्ते दुनिया!",
      "error": null
    },
    {
      "input": "How are you?",
      "output": "आप कैसे हैं?",
      "error": null
    }
  ],
  "source_language": "en",
  "target_language": "hi",
  "model": "nmt"
}

Response Fields¶

Field	Type	Description
`translations`	array	Array of translation objects
`translations[].input`	string	Original input text
`translations[].output`	string	Translated text
`translations[].error`	string\|null	Error message if translation failed, null otherwise
`source_language`	string	Source language code
`target_language`	string	Target language code
`model`	string	Model used for translation

Error Handling¶

Provider-Specific Behavior¶

Different providers handle errors differently:

Provider	Error Behavior	Description
Azure	Fail-fast	Entire request fails if any error occurs
Google	Fail-fast	Entire request fails if any error occurs
Sarvam	Partial results	Continues processing, returns errors for failed items
NLLB	Partial results	Continues processing, returns errors for failed items

Example Error Response (Partial Results)¶

For providers that support partial results (Sarvam, NLLB):

{
  "translations": [
    {
      "input": "Hello",
      "output": "नमस्ते",
      "error": null
    },
    {
      "input": "",
      "output": "",
      "error": "Input text was empty."
    }
  ],
  "source_language": "en",
  "target_language": "hi",
  "model": "sarvam-translate:v1"
}

Common Error Codes¶

Status Code	Description
`400`	Bad Request - Invalid payload, empty text, or unsupported language
`401`	Unauthorized - Invalid or missing API key
`500`	Internal Server Error - Provider credentials not configured or API failure

Example Error Response¶

{
  "detail": "Translation text cannot be empty"
}

Validation Rules¶

The Translation API applies the following validation rules:

Text Array: Must be non-empty and contain at least one non-whitespace string
Language Codes: Must be in the supported languages list
Provider: Must be one of: AZURE, GOOGLE, SARVAM, NLLB
Whitespace Normalization: Multiple spaces are collapsed to single spaces
Empty Strings: Empty or whitespace-only strings in the text array will cause validation errors

Best Practices¶

1. Input Validation¶

Always trim and validate input text before sending
Check for empty strings in your text array
Ensure language codes are supported

2. Error Handling¶

Implement retry logic for transient failures
Check the error field in each translation result for partial failure providers
Log provider-specific error messages for debugging

3. Performance Optimization¶

Batch multiple text items in a single request when possible
Use appropriate models for your use case (e.g., nmt for higher quality)
Consider provider-specific limitations:
Azure: Limited by API rate limits
Google: Better for batch processing
Sarvam: Optimized for Indian languages
NLLB: Handles rare language pairs

4. Cost Optimization¶

Avoid translating already-translated content
Cache translation results when appropriate
Choose providers based on your language pairs and budget

Testing the API¶

You can test the translation API using the following methods:

Using cURL¶

See the example cURL commands above.

Using Python¶

import requests

url = "https://language-server-url/v1/sync/translation"
headers = {
    "accept": "application/json",
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

payload = {
    "user_email": "user@example.com",
    "project_name": "MyProject",
    "source_language": "en",
    "target_language": "hi",
    "provider": "GOOGLE",
    "text": ["Hello, world!", "How are you?"],
    "models": ["nmt"]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Using JavaScript (fetch)¶

const url = "https://language-server-url/v1/sync/translation";
const headers = {
    "accept": "application/json",
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
};

const payload = {
    user_email: "user@example.com",
    project_name: "MyProject",
    source_language: "en",
    target_language: "hi",
    provider: "GOOGLE",
    text: ["Hello, world!", "How are you?"],
    models: ["nmt"]
};

fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(payload)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error("Error:", error));

Troubleshooting¶

Issue: "Translation text cannot be empty"¶

Solution: Ensure your text array contains at least one non-empty, non-whitespace string.

Issue: "Invalid source_language"¶

Solution: Check that your language code is in the supported languages list.

Issue: "Provider credentials not configured"¶

Solution: Contact your system administrator to ensure the provider's environment variables are set correctly on the server.

Issue: Partial translations missing¶

Solution: - For Azure/Google: Check server logs, as these providers fail-fast - For Sarvam/NLLB: Check the error field in each translation object

Additional Resources¶

Info

For questions or issues, contact the development team or refer to the main API documentation.