# TranslatePlus API Documentation

## Overview

TranslatePlus API Documentation is a comprehensive developer resource providing complete API reference, integration guides, code examples, and best practices for the TranslatePlus Translation API service. The documentation covers both API v1 (legacy) and API v2 (current) with detailed endpoint specifications, request/response examples, and implementation guides.

## Documentation Site

**Documentation URL:** https://docs.translateplus.io  
**API Base URL:** https://api.translateplus.io  
**Service Website:** https://translateplus.io

## Documentation Structure

### Getting Started
- **Quick Start Guide:** Step-by-step tutorial for making your first API request
- **Authentication:** API key setup and authentication methods
- **Base URL:** API endpoint configuration and base URLs

### API Reference - Version 2 (Current)

#### Translation Endpoints
- **POST /v2/translate** - Translate single text from source to target language
- **POST /v2/translate/batch** - Batch translation for multiple texts (up to 100 per request)
- **POST /v2/translate/html** - Translate HTML content while preserving tags and structure
- **POST /v2/translate/email** - Translate email subjects and HTML email bodies
- **POST /v2/translate/subtitles** - Translate subtitle files (SRT, VTT) with timestamp preservation

#### Internationalization (i18n) Endpoints
- **POST /v2/i18n/jobs** - Create translation job for i18n files (JSON, YAML, PO, Properties, Strings, XML)
- **GET /v2/i18n/jobs/{job_id}** - Get translation job status
- **GET /v2/i18n/jobs/{job_id}/download** - Download translated i18n file
- **DELETE /v2/i18n/jobs/{job_id}** - Delete translation job
- **GET /v2/i18n/jobs** - List all translation jobs

#### Language Endpoints
- **POST /v2/language/detect** - Detect source language of text
- **GET /v2/language/supported** - Get list of all supported languages (100+ languages)

#### Account & Management
- **GET /v2/user/account** - Get account summary (credits, usage, limits)
- **GET /v2/health** - Health check endpoint for service status

### API Reference - Version 1 (Legacy)

#### Legacy Endpoints (Backward Compatible)
- **POST /v1/translate** - Legacy text translation endpoint
- **POST /v1/language_detect** - Legacy language detection endpoint
- **GET /v1/supported-languages** - Legacy supported languages endpoint

### Guides & Tutorials

#### Integration Guides
- **Error Handling:** Comprehensive guide on handling API errors, status codes, and error messages
- **Rate Limits:** Understanding rate limits, concurrency limits, and best practices
- **Code Examples:** Real-world integration examples in multiple programming languages
- **API Changelog:** Complete changelog tracking all API changes and improvements

#### Code Examples
- **cURL:** Command-line examples for all endpoints
- **Python:** Python integration examples using requests library
- **JavaScript:** Browser-based JavaScript examples using fetch API
- **Node.js:** Node.js examples for server-side integration
- **PHP:** PHP integration examples

## API Features

### Core Translation Capabilities
- **100+ Languages:** Support for major world languages with high accuracy
- **Automatic Language Detection:** AI-powered language detection with confidence scoring
- **Batch Processing:** Efficient batch translation for processing multiple texts simultaneously
- **HTML Translation:** Intelligent HTML parsing that preserves structure, tags, attributes, and formatting
- **Subtitle Translation:** Professional subtitle file translation with timestamp and formatting preservation
- **Email Translation:** Specialized translation for email subjects and HTML email bodies

### Internationalization (i18n) Features
- **Multi-Format Support:** JSON, YAML, PO/POT, Java Properties, iOS Strings, XML file formats
- **Structure Preservation:** Maintains file structure, keys, placeholders, and formatting
- **Asynchronous Processing:** Background job processing for large i18n files
- **Webhook Notifications:** Real-time notifications when translation jobs complete
- **Placeholder Preservation:** Preserves ICU MessageFormat, HTML/XML tags, and variable placeholders

### Developer Experience
- **RESTful API Design:** Clean, intuitive REST API following industry best practices
- **Comprehensive Documentation:** Detailed API reference with request/response examples
- **Multiple SDKs:** Official client libraries for Python (`translateplus-python`) and JavaScript/TypeScript (`translateplus-js`)
- **Standardized Errors:** Consistent error messages with clear HTTP status codes
- **Versioning:** API versioning (v1, v2) for backward compatibility

### Enterprise Features
- **High Performance:** Sub-100ms response times, 5000+ requests per second capacity
- **Concurrency Control:** Configurable concurrent request limits per plan
- **Rate Limiting:** Transparent rate limits with clear error messages
- **Request Logging:** Detailed API request logging and analytics
- **Account Management:** Track usage, credits, and manage API keys
- **Health Monitoring:** Health check endpoints for service status monitoring

## Authentication

### API Key Authentication
- **Header:** `X-API-KEY: your_api_key`
- **Required:** All endpoints require API key authentication
- **Security:** API keys should be kept secure and never exposed in client-side code
- **Management:** API keys can be generated and managed from the dashboard

## Request & Response Format

### Request Format
- **Content-Type:** `application/json` for most endpoints
- **Method:** POST for translation endpoints, GET for information endpoints
- **Body:** JSON object with required parameters

### Response Format
- **Content-Type:** `application/json`
- **Status Codes:** Standard HTTP status codes (200, 400, 401, 403, 429, 500)
- **Error Format:** Consistent error response structure with `detail` field

## Supported Languages

The API supports 100+ languages including:
- **Major Languages:** English, Spanish, French, German, Italian, Portuguese, Chinese, Japanese, Korean, Arabic, Hindi, Russian, and more
- **Regional Languages:** Coverage for regional and less common languages
- **Language Codes:** ISO 639-1 and ISO 639-2 language codes

## Use Cases

### Web Applications
- Multi-language website content translation
- User-generated content translation
- Real-time chat translation
- E-commerce product description translation

### Mobile Applications
- App localization for iOS and Android
- In-app content translation
- User interface translation
- Push notification translation

### Content Management
- Blog post translation
- Documentation translation
- Marketing content localization
- News article translation

### Enterprise Applications
- Customer support ticket translation
- Email communication translation
- Document translation
- Subtitle translation for video content
- i18n file translation for software localization

## Integration Examples

### Python Integration
```python
import requests

url = "https://api.translateplus.io/v2/translate"
headers = {
    "X-API-KEY": "your_api_key",
    "Content-Type": "application/json"
}
data = {
    "text": "Hello, world!",
    "source": "en",
    "target": "fr"
}

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

### JavaScript Integration
```javascript
fetch('https://api.translateplus.io/v2/translate', {
  method: 'POST',
  headers: {
    'X-API-KEY': 'your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    text: 'Hello, world!',
    source: 'en',
    target: 'fr'
  })
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
```

### cURL Integration
```bash
curl https://api.translateplus.io/v2/translate \
  -H "X-API-KEY: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello, world!",
    "source": "en",
    "target": "fr"
  }'
```

## Error Handling

### Common Error Codes
- **400 Bad Request:** Invalid request parameters or malformed request body
- **401 Unauthorized:** Missing or invalid API key
- **403 Forbidden:** API key not found or invalid credentials
- **429 Too Many Requests:** Rate limit or concurrency limit exceeded
- **500 Internal Server Error:** Server-side error, retry recommended

### Error Response Format
```json
{
  "detail": "Error message describing what went wrong"
}
```

## Rate Limits & Concurrency

### Rate Limits
- **Per Plan:** Rate limits vary by subscription plan
- **Headers:** Rate limit information included in response headers
- **Error Response:** 429 status code when rate limit exceeded

### Concurrency Limits
- **Concurrent Requests:** Configurable concurrent request limits per plan
- **Tracking:** Real-time concurrency tracking and enforcement
- **Error Response:** 429 status code when concurrency limit exceeded

## Best Practices

### Performance Optimization
- Use batch translation endpoint for multiple texts
- Implement request retry logic with exponential backoff
- Cache language detection results when possible
- Use async processing for large i18n files

### Error Handling
- Implement proper error handling for all API calls
- Check HTTP status codes before processing responses
- Handle rate limit errors with appropriate retry logic
- Log errors for debugging and monitoring

### Security
- Never expose API keys in client-side code
- Use environment variables for API key storage
- Rotate API keys regularly
- Monitor API usage for suspicious activity

## Migration Guide

### From v1 to v2
- **Endpoint Mapping:** v1 endpoints map to v2 equivalents
- **Backward Compatibility:** v1 endpoints remain available
- **New Features:** v2 includes batch translation, HTML translation, i18n support
- **Improved Performance:** v2 offers better response times and error handling

## Resources

### Official Documentation
- **API Documentation:** https://docs.translateplus.io
- **Getting Started:** https://docs.translateplus.io/getting-started/quick-start
- **API Reference:** https://docs.translateplus.io/reference
- **Code Examples:** https://docs.translateplus.io/guides/examples

### Official Client Libraries

#### Python SDK - translateplus-python
- **Package Name:** `translateplus-python`
- **PyPI Link:** https://pypi.org/project/translateplus-python/
- **Installation:** `pip install translateplus-python`
- **Current Version:** 2.0.5 (Production/Stable)
- **Python Requirements:** Python 3.8+
- **Features:**
  - Full API endpoint support (text, batch, HTML, email, subtitles, i18n)
  - Built-in concurrent request handling
  - Comprehensive error handling with custom exceptions
  - Full type hints for better IDE support
  - Retry logic and rate limiting
  - Production-ready with connection pooling
- **Quick Start:**
  ```python
  from translateplus import TranslatePlusClient
  
  client = TranslatePlusClient(api_key="your-api-key")
  result = client.translate(text="Hello", source="en", target="fr")
  print(result["translations"]["translation"])
  ```

#### JavaScript/TypeScript SDK - translateplus-js
- **Package Name:** `translateplus-js`
- **npm Link:** https://www.npmjs.com/package/translateplus-js
- **Installation:** `npm install translateplus-js`
- **Current Version:** 2.0.1+ (Production/Stable)
- **Node.js Requirements:** Node.js 18+
- **Features:**
  - Full API endpoint support (text, batch, HTML, email, subtitles, i18n)
  - TypeScript support with full type definitions
  - Built-in concurrent request handling
  - Comprehensive error handling with custom exceptions
  - Retry logic with exponential backoff
  - ESM and CommonJS support
- **Quick Start:**
  ```javascript
  import { TranslatePlusClient } from 'translateplus-js';
  
  const client = new TranslatePlusClient({ apiKey: 'your-api-key' });
  const result = await client.translate({
    text: 'Hello',
    source: 'en',
    target: 'fr'
  });
  console.log(result.translations.translation);
  ```

#### PHP SDK - translateplus/translateplus-php
- **Package Name:** `translateplus/translateplus-php`
- **Packagist Link:** https://packagist.org/packages/translateplus/translateplus-php
- **GitHub Link:** https://github.com/translateplus/translateplus-php
- **Installation:** `composer require translateplus/translateplus-php`
- **Current Version:** Latest (Production/Stable)
- **PHP Requirements:** PHP 7.4+
- **Features:**
  - Full API endpoint support (text, batch, HTML, email, subtitles, i18n)
  - Comprehensive error handling with custom exceptions
  - Automatic retry with exponential backoff
  - Built-in concurrent request handling with configurable limits
  - Full PHPDoc annotations for IDE support
  - Production-ready with connection pooling and rate limiting
- **Quick Start:**
  ```php
  require 'vendor/autoload.php';
  use TranslatePlus\Client;
  
  $client = new Client(['api_key' => 'your-api-key']);
  $result = $client->translate([
      'text' => 'Hello',
      'source' => 'en',
      'target' => 'fr'
  ]);
  echo $result['translations']['translation'];
  ```

#### Java SDK - io.translateplus:translateplus-java
- **Package Name:** `io.translateplus:translateplus-java`
- **Maven Central Link:** https://central.sonatype.com/artifact/io.translateplus/translateplus-java
- **GitHub Link:** https://github.com/translateplus/translateplus-java
- **Installation:** Add to `pom.xml`: `<dependency><groupId>io.translateplus</groupId><artifactId>translateplus-java</artifactId><version>2.1.3</version></dependency>`
- **Current Version:** 2.1.3+ (Production/Stable)
- **Java Requirements:** Java 11+
- **Features:**
  - Full API endpoint support (text, batch, HTML, email, subtitles, i18n)
  - Comprehensive error handling with specific exception types
  - Automatic retry with exponential backoff
  - Built-in concurrent request handling with configurable limits
  - Full Java type safety with proper exception hierarchy
  - Production-ready with connection pooling and rate limiting
- **Quick Start:**
  ```java
  import io.translateplus.TranslatePlusClient;
  import java.util.Map;
  
  TranslatePlusClient client = new TranslatePlusClient.Builder()
      .apiKey("your-api-key")
      .build();
  Map<String, Object> result = client.translate("Hello", "en", "fr");
  Map<String, Object> translations = (Map<String, Object>) result.get("translations");
  System.out.println(translations.get("translation"));
  ```

#### Direct REST API Integration
- **Base URL:** https://api.translateplus.io
- **Authentication:** X-API-KEY header
- **Documentation:** https://docs.translateplus.io
- **Code Examples:** Available in cURL, Python (requests), JavaScript (fetch), Node.js, PHP

### Support
- **Support Email:** support@translateplus.io
- **Service Website:** https://translateplus.io
- **API Status:** Check `/v2/health` endpoint for service status

## Company Information

**Corporate Entity:** TranslatePlus.io is managed and operated by **PetaBytes, Inc.**, a US-based corporation. All billing, payment processing, and financial transactions related to TranslatePlus services are handled by PetaBytes, Inc. As a US-based company, PetaBytes, Inc. operates in compliance with applicable United States laws and regulations, ensuring transparency, security, and accountability in all business operations.

## Technical Details

### API Architecture
- **Protocol:** RESTful HTTP/HTTPS
- **Authentication:** API key via X-API-KEY header
- **Response Format:** JSON
- **Versioning:** URL-based versioning (/v1/, /v2/)

### Performance Characteristics
- **Response Time:** 300ms average for text translation
- **Throughput:** High-throughput architecture for large-scale usage
- **Reliability:** 99.9% uptime SLA with redundant infrastructure
- **Scalability:** Auto-scaling infrastructure for enterprise workloads

### Translation Quality
- **Engine:** Advanced neural machine translation models
- **Accuracy:** High accuracy with context-aware translation
- **Domain Support:** Specialized models for different content types
- **Continuous Improvement:** Regular model updates and quality enhancements

---

*This document provides an overview of the TranslatePlus API Documentation. For the most current API reference, code examples, and integration guides, please visit https://docs.translateplus.io*