API: Auto-translate

Learn how to start an 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.

Table of contents

• Endpoint

  • Sample request
  • Request fields
  • Available options field values
  • Additional request fields for DeepL provider
  • Target Language and Source Language
  • Example response

• Get auto-translation jobs

  • Sample request
  • Example response

• Get auto-translation job by id

  • Sample request
  • Example response

Endpoint

Sample request

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.

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 the auto-translation job, and it's removed once the job is finished. It won't show up in the job details at any time.
• deeplFormality - sets whether the translated text should lean towards formal or informal language. This feature currently only works for only a few target languages. Possible options are: default, more - for a more formal language, less for a more informal language.

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.

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 the 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 the 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 auto-translation jobs

Sample request

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"
            }
        },
    ...
    }

Get auto-translation job by id

Sample request

curl
    --location
    --request POST 'https://api.simplelocalize.io/api/v1/jobs/42bc498cc33c4ac4866b18f33ce4ed65' \
    --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"
            }
        }
    }