AI Translation Service

AI Translation Service is a microservice for multilingual text translation, powered by Cloudflare Workers AI (m2m100-1.2b model). It provides RESTful API endpoints for single and batch translation, automatic language detection, health monitoring, and is fully containerized for easy deployment.

Features

• Single Text Translation: Translate individual texts between 100+ supported languages
• Batch Translation: Translate up to 100 texts in a single request
• Automatic Language Detection: Detects source language if not specified
• Health Monitoring: Built-in health and status endpoints
• Swagger Documentation: Interactive API docs at /api/docs
• Docker & Docker Compose Support: Easy local and production deployment

Supported Languages

Supports 100+ languages, including:

• English (en), Spanish (es), French (fr), German (de), Russian (ru), Chinese (zh), Japanese (ja), Korean (ko), and many more.
• Full list available via /api/v1/translate/languages endpoint.

Quick Start with Docker Compose

1. Prepare Environment Variables

Create a .env file in the project root with your Cloudflare credentials:

CLOUDFLARE_API_TOKEN=your_api_token_here
CLOUDFLARE_ACCOUNT_ID=your_account_id_here
CLOUDFLARE_API_BASE_URL=https://api.cloudflare.com/client/v4/accounts
NODE_ENV=development
PORT=8381

2. Start the Service

Run the following command to start the service using Docker Compose:

docker-compose up

This will build and launch the service on port 8381 by default.

3. Access the API

• Swagger UI: http://localhost:8381/api/docs
• Health Check: http://localhost:8381/api/v1/health

API Endpoints

Method	Endpoint	Description
GET	/api/v1/health	Health check
GET	/api/v1/translate/languages	List supported languages
POST	/api/v1/translate	Single text translation
POST	/api/v1/translate/batch	Batch translation
GET	/api/docs	Swagger API documentation

Example: Single Translation

POST /api/v1/translate
Content-Type: application/json

{
  "text": "Hello, how are you?",
  "source_lang": "en",
  "target_lang": "fr"
}

Response:

{
  "translated_text": "Bonjour, comment ça va?",
  "source_lang": "en",
  "target_lang": "fr",
  "original_text": "Hello, how are you?",
  "timestamp": "2025-09-10T10:30:00.000Z"
}

Example: Batch Translation

POST /api/v1/translate/batch
Content-Type: application/json

{
  "requests": [
    { "text": "Hello, world!", "source_lang": "en", "target_lang": "fr" },
    { "text": "How are you?", "source_lang": "en", "target_lang": "de" }
  ]
}

Example: Get Supported Languages

GET /api/v1/translate/languages

Example: Health Check

GET /api/v1/health

Usage Examples

cURL

curl -X POST http://localhost:8381/api/v1/translate \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello, world!",
    "source_lang": "en",
    "target_lang": "es"
  }'

JavaScript/TypeScript

const translateText = async (text: string, targetLang: string) => {
  const response = await fetch('http://localhost:8381/api/v1/translate', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ text, target_lang: targetLang })
  });
  return response.json();
};

const result = await translateText('Hello, world!', 'fr');
console.log(result.translated_text); // "Bonjour, le monde!"

Python

import requests

def translate_text(text, target_lang, source_lang=None):
    payload = { "text": text, "target_lang": target_lang }
    if source_lang:
        payload["source_lang"] = source_lang
    response = requests.post(
        "http://localhost:8381/api/v1/translate",
        json=payload
    )
    return response.json()

result = translate_text("Hello, world!", "fr")
print(result["translated_text"])  # "Bonjour, le monde!"

Error Handling

• 200 - Success
• 400 - Bad Request (invalid parameters, unsupported language, etc.)
• 429 - Too Many Requests (rate limit exceeded)
• 500 - Internal Server Error
• 503 - Service Unavailable

Error response format:

{
  "statusCode": 400,
  "message": "Invalid request: Unsupported target language",
  "error": "Bad Request"
}

Configuration

Variable	Description	Default
CLOUDFLARE_API_TOKEN	Cloudflare API token	Required
CLOUDFLARE_ACCOUNT_ID	Cloudflare account ID	Required
CLOUDFLARE_API_BASE_URL	Cloudflare API base URL	https://api.cloudflare.com/client/v4/accounts
CF_MODEL_NAME	Translation model name	@cf/meta/m2m100-1.2b
NODE_ENV	Environment mode	development
PORT	Server port	8381
REQUEST_TIMEOUT	API request timeout (ms)	30000
CORS_ORIGIN	CORS allowed origins	*

Development

Prerequisites

• Node.js 18+
• npm or yarn
• Cloudflare account with Workers AI access

Local Development

npm install
npm run start:dev

Testing

npm test         # Unit tests
npm run test:cov # Test coverage
npm run test:e2e # E2E tests

Linting & Formatting

npm run lint
npm run format

Monitoring & Logging

• Health endpoint: /api/v1/health provides service and dependency status
• Structured logging with configurable levels (debug/info)

MIT License

This project is licensed under the MIT License. See the LICENSE file for details.