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"

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