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: multipart/form-data

Supported Translation Providers¶

The Translation API supports the following providers:

Provider	Model Name	Description
`AZURE`	`neural` (default)	Microsoft Azure Translator
`GOOGLE`	`nmt` (default)	Google Cloud Translation API V3 (Advanced)
`SARVAM`	`sarvam-translate:v1`	Sarvam AI Translation
`NLLB`	`nllb`	Meta's No Language Left Behind
`KARYA_LOCAL`	`nllb` (required)	Alias for NLLB — requires `models=["nllb"]`

Google Model Note

Google's base model is not supported — passing models: ["base"] will return HTTP 400. Use "nmt" for standard neural machine translation or a custom AutoML model ID for specialized use.

Azure Model Note

The default model is "neural". Azure always uses its standard translation model regardless of the models field — the value is accepted but not used in the provider call. The response always returns "model": "azure".

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. The full mapping is shown below.
Other providers use the codes as-is

NLLB Language Code Mapping¶

Short Code	NLLB Code
`en`	`eng_Latn`
`hi`	`hin_Deva`
`ta`	`tam_Taml`
`te`	`tel_Telu`
`ml`	`mal_Mlym`
`kn`	`kan_Knda`
`bn`	`ben_Beng`
`gu`	`guj_Gujr`
`mr`	`mar_Deva`
`or`	`ory_Orya`
`as`	`asm_Beng`

Note: If a code is not in this mapping, it is passed through unchanged.

Single (Sync) Translation¶

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

Endpoint Details¶

Endpoint: https://languageserver.karya.in/v1/task/translation
Method: POST

Request Body Structure¶

The request uses multipart/form-data with a single payload_data field containing the JSON-encoded payload:

{
  "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`, `NLLB`, or `KARYA_LOCAL`
`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: neural (standard model — value accepted but not used in the provider call) - Sarvam: sarvam-translate:v1 - NLLB: nllb (when used via KARYA_LOCAL, specify models=["nllb"] explicitly)

Example cURL Commands¶

Example 1: Google Translation¶

curl -X 'POST' \
  'https://languageserver.karya.in/v1/task/translation' \
  -H 'accept: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: multipart/form-data' \
  -F 'payload_data={"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://languageserver.karya.in/v1/task/translation' \
  -H 'accept: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: multipart/form-data' \
  -F 'payload_data={"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://languageserver.karya.in/v1/task/translation' \
  -H 'accept: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: multipart/form-data' \
  -F 'payload_data={"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://languageserver.karya.in/v1/task/translation' \
  -H 'accept: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: multipart/form-data' \
  -F 'payload_data={"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¶

{
  "task_id": "abc123def456",
  "status": "COMPLETED",
  "result": {
    "translations": [
      {
        "input": "Hello, world!",
        "output": "नमस्ते दुनिया!",
        "error": null
      }
    ],
    "source_language": "en",
    "target_language": "hi",
    "model": "nmt"
  }
}

Response Fields¶

Field	Type	Description
`task_id`	string	Unique identifier for the task
`status`	string	Always `"COMPLETED"` for successful requests
`result`	object	Contains the translation output
`result.translations`	array	Array of translation objects
`result.translations[].input`	string	Original input text
`result.translations[].output`	string	Translated text
`result.translations[].error`	string\|null	Error message if translation failed, null otherwise
`result.source_language`	string	Source language code
`result.target_language`	string	Target language code
`result.model`	string	Model used for translation

Google Provider: detected_language

When using Google, each translation item also includes "detected_language" — the language code Google detected for the input text:

{
  "input": "Hello",
  "output": "नमस्ते",
  "detected_language": "en",
  "error": null
}

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, unsupported language, Sarvam text item exceeds 2,000 characters
`401`	Unauthorized — Invalid or missing API key
`403`	Forbidden — Provider permission denied (e.g., Google Cloud permissions)
`404`	Not Found — Custom translation model not found (Google custom models)
`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, KARYA_LOCAL
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 json
import requests

url = "https://languageserver.karya.in/v1/task/translation"
headers = {
    "accept": "application/json",
    "X-API-Key": "YOUR_API_KEY"
}

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, data={"payload_data": json.dumps(payload)}, headers=headers)
print(response.json())

Using JavaScript (fetch)¶

const url = "https://languageserver.karya.in/v1/task/translation";

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

const formData = new FormData();
formData.append("payload_data", JSON.stringify(payload));

fetch(url, {
    method: "POST",
    headers: {
        "accept": "application/json",
        "X-API-Key": "YOUR_API_KEY"
    },
    body: formData
})
.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

Sarvam Character Limit

When using the Sarvam provider, each text item in the text array must not exceed 2,000 characters. Longer text items will cause the request to fail with HTTP 400.

Additional Resources¶

Info

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