Learn how to generate multi-language images in seconds with Bannerly!See Bannerly.io

API: Auto-translate

Last modified: October 12, 2021Author: Jakub Pomykała

Learn how to start auto-translation job to translate text in your project to another language using automated translation services like DeepL or Google Translate. In the second section you will learn how to track progress of started auto-translation jobs.

POST Start auto-translation job

https://api.simplelocalize.io/api/v1/jobs/auto-translate

Example cURL

curl 
    --location 
    --request POST 'https://api.simplelocalize.io/api/v1/jobs/auto-translate' \
    --header 'X-SimpleLocalize-Token: <API_KEY>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "translationProvider": "DEEPL",
        "options": ["FORCE_REPLACE"],
        "targetProjectLanguage": "en",
        "targetLanguage": "EN-GB",
        "sourceProjectLanguage": "pl",
        "sourceLanguage": "PL",
    }'

Request fields

  • translationProvider (required) - translation provider (GOOGLE_TRANSLATE or DEEPL),
  • targetProjectLanguage (required) - target language key from your project,
  • targetLanguage (required) - target provider language key,
  • sourceProjectLanguage - source language key from your project,
  • sourceLanguage - source language key,
  • options - auto-translate options array.

Available options field values

Options field must be always provided as string array.

Option Value Description
USE_TRANSLATION_KEYS Use translation keys as source, if no translation available
FORCE_REPLACE Translate all and replace existing translations
EXCLUDE_VARIABLES Do not translate variables like: {{count}}
AUTO_PUBLISH Publish translations to CDN after successful translation (changes are pushed to the "Latest Environment")

Additional request fields for DeepL provider

  • deeplGlossaryId - specify the glossary to use. This requires deeplApiKey and sourceLanguage field to be set and the language pair of the glossary has to match the language pair of the request,
  • deeplApiKey - if you use DeepL glossary, then your DeepL API Key is required. The API Key is used only during auto-translation job, and it's removed once job is finished. It won't show up in the job details at any time.

See DeepL API documentation.

Target Language and Source Language

  • targetLanguage and sourceLanguage are different for each translation provider.
  • targetProjectLanguage and sourceProjectLanguage comes from your project

Where to find project language keys?

Values for targetProjectLanguage and sourceProjectLanguage must be provided as language keys. Language keys can be found in the Languages tab in your project.

Where to find project language keys in SimpleLocalize?

Language keys for Google Translate

Here is a list of example language keys supported by Google Translate as target or source language key.

  • en for English
  • pl for Polish
  • pt for Portuguese
  • sv for Swedish

See full list of supported language keys

Language keys for DeepL

Here is a list of example language keys supported by DeepL as target or source language key.

  • EN-GB for English (British)
  • PL for Polish
  • PT-BR for Portuguese (Brazilian)
  • SV for Swedish

See full list of supported language keys

Example response

{
  "msg": "OK",
  "status": 200,
  "data": {
    "jobId": "<JOB_ID>",
    "progress": 0.01,
    "state": "STARTED",
    "started": "2021-09-01T11:09:52.919Z",
    "message": "OK",
    "metadata": {},
  }
}

GET Get auto-translation jobs

https://api.simplelocalize.io/api/v1/jobs

Example cURL

curl 
    --location 
    --request POST 'https://api.simplelocalize.io/api/v1/jobs' \
    --header 'X-SimpleLocalize-Token: <API_KEY>' \
    --header 'Content-Type: application/json'

Example response

{
    "msg": "OK",
    "status": 200,
    "data": [
        {
            "jobId": "42bc498cc33c4ac4866b18f33ce4ed65",
            "progress": 1.0,
            "state": "SUCCESS",
            "message": "Translated 99 texts (chars: 1823)",
            "started": "2021-09-01T11:09:52.919Z",
            "metadata": {
                "targetProjectLanguage": "fr",
                "targetLanguage": "FR",
                "sourceType": "API",
                "options": "FORCE_REPLACE",
                "translationProvider": "DEEPL",
                "sourceProjectLanguage": "en",
                "sourceLanguage": "en"
            }
        },
    ...
    }