title: Create i18n Translation Job description: Create a new i18n translation job with example code

Create i18n Translation Job

Create a new i18n translation job to translate your internationalization files to multiple target languages.

Endpoint

POST /v2/translate/i18n

Content-Type: multipart/form-data (required)

ℹ️

What is i18n Translation? Internationalization (i18n) translation allows you to translate application localization files (JSON, YAML, PO, Properties, Strings, XML) to multiple languages while preserving file structure, keys, placeholders, and formatting.

⚠️

Important: This endpoint requires multipart/form-data. Do not send JSON. All parameters must be sent as form fields.

Headers

X-API-KEY string (required) : Your API key for authentication

Request Parameters

Form Data Parameters

file file (required) : i18n file to translate (JSON, YAML, PO, Properties, Strings, XML). Max 10MB.

source_language string (optional) : Source language code (e.g., "en", "fr") or "auto" for auto-detection. Default: "auto"

target_languages string (required) : Comma-separated list of target language codes (e.g., "fr,es,de"). Minimum 1, maximum 50 languages.

webhook_url string (optional) : Optional webhook URL to receive notification when job completes. Must be a valid HTTPS URL.

Supported File Formats

| Format | Extensions | Common Use Cases | |--------|------------|------------------| | JSON | .json | Web applications (React, Vue, Angular) | | YAML | .yaml, .yml | Configuration files, web applications | | PO/POT | .po, .pot | GNU gettext, desktop applications | | Properties | .properties | Java applications, resource bundles | | Strings | .strings | iOS applications | | XML | .xml | Android applications, resource files |

Example Request

curl -X POST https://v2-api.translateplus.io/v2/translate/i18n \
  -H "X-API-KEY: your_api_key" \
  -F "file=@translations.json" \
  -F "source_language=en" \
  -F "target_languages=fr,es,de" \
  -F "webhook_url=https://your-app.com/webhooks/i18n-completed"

import requests

# Note: This endpoint uses multipart/form-data, not JSON
url = "https://v2-api.translateplus.io/v2/translate/i18n"
headers = {
    "X-API-KEY": "your_api_key"
    # Do NOT set Content-Type header - requests will set it automatically
}

files = {
    'file': ('translations.json', open('translations.json', 'rb'), 'application/json')
}
data = {
    'source_language': 'en',
    'target_languages': 'fr,es,de',
    'webhook_url': 'https://your-app.com/webhooks/i18n-completed'  # Optional
}

response = requests.post(url, headers=headers, files=files, data=data)
result = response.json()

print(f"Job ID: {result['job_id']}")
print(f"Status: {result['status']}")
# Output:
# Job ID: 550e8400-e29b-41d4-a716-446655440000
# Status: pending

// Note: This endpoint uses multipart/form-data, not JSON
const formData = new FormData();
formData.append('file', fileInput.files[0]); // File from <input type="file">
formData.append('source_language', 'en');
formData.append('target_languages', 'fr,es,de');
formData.append('webhook_url', 'https://your-app.com/webhooks/i18n-completed'); // Optional

fetch('https://v2-api.translateplus.io/v2/translate/i18n', {
  method: 'POST',
  headers: {
    'X-API-KEY': 'your_api_key'
    // Do NOT set Content-Type header - browser will set it automatically
  },
  body: formData
})
.then(response => response.json())
.then(data => {
  console.log('Job ID:', data.job_id);
  console.log('Status:', data.status);
  // Output:
  // Job ID: 550e8400-e29b-41d4-a716-446655440000
  // Status: pending
})
.catch(error => console.error('Error:', error));

const https = require('https');
const fs = require('fs');
const FormData = require('form-data');

const form = new FormData();
form.append('file', fs.createReadStream('translations.json'));
form.append('source_language', 'en');
form.append('target_languages', 'fr,es,de');
form.append('webhook_url', 'https://your-app.com/webhooks/i18n-completed');

const options = {
  hostname: new URL('https://v2-api.translateplus.io').hostname,
  path: '/v2/translate/i18n',
  method: 'POST',
  headers: {
    'X-API-KEY': 'your_api_key',
    ...form.getHeaders()
  }
};

const req = https.request(options, (res) => {
  let responseData = '';

  res.on('data', (chunk) => {
    responseData += chunk;
  });

  res.on('end', () => {
    const result = JSON.parse(responseData);
    console.log('Job ID:', result.job_id);
    console.log('Status:', result.status);
  });
});

req.on('error', (error) => {
  console.error('Error:', error);
});

form.pipe(req);

<?php

// Note: This endpoint uses multipart/form-data, not JSON
$url = 'https://v2-api.translateplus.io/v2/translate/i18n';
$apiKey = 'your_api_key';
$filePath = 'translations.json';

$data = [
    'file' => new CURLFile($filePath, 'application/json', 'translations.json'),
    'source_language' => 'en',
    'target_languages' => 'fr,es,de',
    'webhook_url' => 'https://your-app.com/webhooks/i18n-completed' // Optional
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-KEY: ' . $apiKey
    // Do NOT set Content-Type header - cURL will set it automatically
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 201) {
    $result = json_decode($response, true);
    echo 'Job ID: ' . $result['job_id'] . PHP_EOL;
    echo 'Status: ' . $result['status'] . PHP_EOL;
} else {
    echo 'Error: ' . $response;
}

Example File (translations.json)

Here's an example of a JSON i18n file you might upload:

{
  "welcome": {
    "title": "Welcome to TranslatePlus",
    "message": "Hello, {name}! You have {count} new messages.",
    "button": "Get Started"
  },
  "errors": {
    "not_found": "The requested resource was not found.",
    "unauthorized": "You are not authorized to access this resource."
  },
  "plural": {
    "item": "{count, plural, =0 {No items} =1 {One item} other {# items}}"
  }
}

After translation to French (fr), the file structure and keys remain the same, but values are translated:

{
  "welcome": {
    "title": "Bienvenue sur TranslatePlus",
    "message": "Bonjour, {name} ! Vous avez {count} nouveaux messages.",
    "button": "Commencer"
  },
  "errors": {
    "not_found": "La ressource demandée est introuvable.",
    "unauthorized": "Vous n'êtes pas autorisé à accéder à cette ressource."
  },
  "plural": {
    "item": "{count, plural, =0 {Aucun élément} =1 {Un élément} other {# éléments}}"
  }
}

Notice how:

✅ Keys remain identical (welcome.title, welcome.message, etc.)
✅ Placeholders are preserved ({name}, {count})
✅ ICU MessageFormat is preserved ({count, plural, ...})
✅ File structure is maintained

Success Response (201 Created)

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "message": "Translation job created successfully"
}

Response Fields

| Field | Type | Description | |-------|------|-------------| | job_id | string (UUID) | Unique identifier for the translation job. Use this to check status and download files. | | status | string | Initial job status, always "pending" when created | | message | string | Success message |

Webhook Notifications

If you provide a webhook_url when creating a translation job, you will receive a POST request to that URL when the job completes (successfully, partially, or with failure).

Webhook Payload

The webhook will send a JSON payload with the following structure:

{
  "event": "i18n_translation.completed",
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "job": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "original_filename": "translations.json",
    "file_type": "json",
    "source_language": "en",
    "target_languages": ["fr", "es", "de"],
    "total_keys": 150,
    "translated_keys": 150,
    "failed_keys": 0,
    "error_message": null,
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:32:15Z",
    "completed_at": "2025-01-15T10:32:15Z"
  },
  "translated_files": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "language_code": "fr",
      "file_url": "https://v2-api.translateplus.io/v2/translate/i18n/jobs/550e8400-e29b-41d4-a716-446655440000/download/?language_code=fr",
      "file_size": 15234,
      "created_at": "2025-01-15T10:32:10Z"
    }
  ],
  "completed_at": "2025-01-15T10:32:15Z"
}

Webhook Requirements

URL Format: Must be a valid HTTPS URL
Response: Your webhook endpoint should return a 2xx status code (200-299) to indicate successful receipt
Timeout: Webhook requests timeout after 10 seconds
Retries: Failed webhook requests will be retried up to 3 times with exponential backoff
Security: Always validate webhook requests in your application

Webhook Status Values

The status field in the webhook payload can be:

completed: All translations completed successfully
partial: Some translations completed, some failed
failed: Translation job failed

Next Steps

After creating a job, you can:

Check Job Status - Monitor the progress of your translation job
Download Translated Files - Download translated files for each target language
List All Jobs - View all your translation jobs
Delete Job - Remove a job and its associated files