Translason API Documentation
Effortlessly transform your JSON content into any language while preserving its precise structure. Translason’s AI-powered service translates complex, nested JSON with unmatched accuracy across 95+ languages.
Getting Started in Minutes
Translating your JSON content is as simple as making a single API call. Follow these steps to get up and running quickly:
- Obtain Your API Token: Get your API token
- Make a POST Request: Send your JSON data to our translation endpoint with the required headers and parameters.
Translation Endpoint
POST https://api.translason.com/v1/translate
One powerful endpoint for all your translation needs. No complex configurations, no structural manipulations—just send your JSON and receive it translated. It’s that simple.
Simple Authentication
To authenticate your API requests, include your API token in the request headers.
Required Headers
Content-Type: application/json
Auth-Token: {{your-api-token}}
Replace {{your-api-token}} with the API token you obtained from Translason.
Request Body - Just Four Fields!
| Field | Type | Required | Description |
|---|---|---|---|
data | object | Yes | Your JSON content to translate |
target | string | Yes | ISO language code of the target language (e.g., “es” for Spanish) |
source | string | No | ISO language code of the source content (e.g., “en” for English). If not provided, the source language will be auto-detected. |
context | string | No | Additional context to improve translation accuracy (e.g., glossary terms, user preferences) |
Smart Translation in Action
See how our service intelligently handles your JSON structure:
Sample Request Body
{
"data": {
"welcome": {
"title": "Welcome to our platform",
"subtitle": "Get started in minutes"
},
"features": [
{
"name": "Fast Translation",
"description": "Translate your content instantly"
},
{
"name": "Structure Preservation",
"description": "Keep your JSON format intact"
}
],
"pricing": {
"amount": 99.99,
"period": "monthly",
"description": "Professional plan with advanced features"
}
},
"target": "es"
}
Response - Perfect Translation, Preserved Structure
Success Response (200 OK)
Experience perfectly translated content while maintaining your exact JSON structure:
{
"welcome": {
"title": "Bienvenido a nuestra plataforma",
"subtitle": "Comienza en minutos"
},
"features": [
{
"name": "Traducción Rápida",
"description": "Traduce tu contenido al instante"
},
{
"name": "Preservación de Estructura",
"description": "Mantén intacto tu formato JSON"
}
],
"pricing": {
"amount": 99.99,
"period": "mensual",
"description": "Plan profesional con características avanzadas"
}
}
Crystal Clear Error Handling
Authentication Error (403 Forbidden)
{
"error": "InvalidToken",
"message": "The provided authentication token is invalid or expired",
"requestId": "req_abc123"
}
Validation Error (400 Bad Request)
{
"error": "ValidationError",
"message": "Request validation failed",
"details": {
"missingProperty": "target",
"location": "body"
},
"requestId": "req_abc124"
}
Rate Limit Error (429 Too Many Requests)
{
"error": "RateLimitExceeded",
"message": "Rate limit exceeded. Please try again later.",
"details": {
"retryAfter": 60,
"limit": "10 requests per minute",
"reset": "2024-04-30T12:00:00Z"
},
"requestId": "req_abc125"
}
Fair and Transparent Pricing
Pay Only for What You Need
We believe in transparent pricing. You only pay for the actual content that needs translation:
- ✅ Charged: Translatable string content
- ❌ Not Charged: JSON keys, numbers, booleans, null values, structural elements, URLs, or technical strings
Here’s how our smart pricing works:
{
"user": { // Not charged (key)
"name": "John", // Charged (translatable string)
"age": 25, // Not charged (number)
"isActive": true, // Not charged (boolean)
"lastLogin": "2024-04-30", // Not charged (date)
"profile": { // Not charged (key)
"bio": "Hello, I'm a developer", // Charged (translatable string)
"url": "https://example.com" // Not charged (URL)
}
}
}
In this example, you are only charged for the actual content that needs translation: “John” and “Hello, I’m a developer”. The total number of characters is 26. The cost is calculated based on the number of characters, at $0.30 per 1 million characters. The cost for this example is $0.0000078. This means you can translate approximately 128,000 similar objects for just one dollar!
Powerful Features & Clear Limitations
What We Support
- ✅ Nested JSON Structures: Handle JSON of any depth
- ✅ Arrays and Object Arrays: Translate within arrays seamlessly
- ✅ HTML Content Within Strings: Preserve HTML tags within your strings
- ✅ Special Characters and Unicode: Accurately handle all character sets
- ✅ Numbers and Dates in String Format: Recognize and preserve numerical and date strings
- ✅ Context-Aware Translations: Provide translations that understand context for accuracy
What We Preserve
- ✅ JSON Structure and Hierarchy: Maintain your original JSON structure
- ✅ Non-String Values Automatically: No configuration needed to preserve non-string values
- ✅ Array Ordering and Nesting: Keep your arrays intact
- ✅ Object Property Names: Property names remain unchanged
- ✅ Formatting and Spacing: Original formatting is preserved
- ✅ Technical Strings: URLs, dates, emails are kept as is
Limitations
To ensure optimal performance:
- ❌ Maximum JSON String Length: 10,000 characters per request
Integration Made Easy
Node.js Example
const translateContent = async (content, target) => {
try {
const response = await fetch('https://api.translason.com/v1/translate', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Auth-Token': process.env.TRANSLASON_API_KEY
},
body: JSON.stringify({
data: content,
target
})
});
if (!response.ok) {
const error = await response.json();
throw new Error(error.message);
}
return response.json();
} catch (error) {
console.error('Translation failed:', error);
throw error;
}
};
Python Example
import requests
import json
def translate_content(content, target_language):
try:
response = requests.post(
'https://api.translason.com/v1/translate',
headers={
'Content-Type': 'application/json',
'Auth-Token': 'your-api-token'
},
json={
'data': content,
'target': target_language
}
)
response.raise_for_status()
return response.json()
except requests.exceptions.RequestException as e:
print(f'Translation failed: {e}')
raise
Best Practices for Optimal Results
Robust Error Handling
- Implement proper error handling for all possible response codes.
- Log requestId from error responses for efficient troubleshooting.
- Use exponential backoff when retrying after rate limit errors.
Performance Optimization
- Batch related translations into single requests to improve performance.
- Cache frequently translated content to reduce redundant requests.
- Implement retry logic with exponential backoff for transient errors.
Content Organization
- Group related content in single requests for better translation context.
- Use consistent key names across translations to maintain structure.
- Provide context hints for ambiguous terms within your content.
Security First
- Store API tokens securely and never expose them in client-side code.
- Use environment variables or secure key management systems for tokens.
- Regularly rotate your API tokens as a security best practice.
Global Language Support
We support 95+ languages to help you reach audiences worldwide:
| Language | Code |
|---|---|
| Arabic | ar |
| Chinese (Simplified) | zh |
| English | en |
| French | fr |
| German | de |
| Japanese | ja |
| Spanish | es |
| Russian | ru |
| Portuguese | pt |
| Hindi | hi |
Join Thousands Who Trust Translason
Unlock new markets and connect with audiences worldwide effortlessly. Start translating your JSON content with Translason today!