API: Add translations

Last modified: April 07, 2021Author: Jakub Pomykała

Description

This endpoint allows you to:

  • create new translation keys and translations
  • add new languages/locales
  • modify existing translations (importOptions=REPLACE_TRANSLATION_IF_FOUND)

Check importOptions section to learn more. If you use this endpoint, note that it requires authorization.

Endpoint behaviour

  • Endpoint will add translation for translation key and language if not found.
  • Endpoint won't replace existing translations by default. Use update translations endpoint or importOption=REPLACE_TRANSLATION_IF_FOUND.
  • Endpoint will automatically add language if not found.
  • Endpoint won't create customerId automatically if not found.
  • Endpoint will automatically update last seen value in translation editor.
  • Endpoint won't update a translation, if key and/or language is missing.

POST Endpoint

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

Example cURL

curl 
    --location 
    --request POST 'https://api.simplelocalize.io/api/v1/translations' \
    --header 'X-SimpleLocalize-Token: <API_KEY>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "content": [
            {
                "key": "EXAMPLE_KEY",
                "language": "en",
                "text": "example text"
            },
            {
                 "key": "SALE",
                 "language": "pl",
                 "text": "Sprzedaż",
                 "customerId": "my_customer"
            }
        ]
    }'

Request fields

  • key (required) - unique translation key for a project
  • language - project language key
  • text - translated message for given key, language and customerId (optional)
  • customerId - if customerId is provided, then translation will be assigned to the customer translation for given key and language. Otherwise, translation will be treated as a default translation for given key and language. See customer-specific translation

Import options

Use query param importOptions to invoke custom logic after or during the import. You can pass more than one import option.

Option value Description
REPLACE_TRANSLATION_IF_FOUND Replaces translation for key if the key already exists. Without this option SimpleLocalize will only add new translations.
PUBLISH_AFTER_IMPORT Translations will be published automatically to the CDN after successful import. Option available only in paid plans. Check also how to publish translations using API endpoint
FAIL_FAST (soon) Request will fail on first encountered warning, processed translations won't be reverted to the original state
REVERT_ON_FAIL (soon) Request will fail on first encountered warning, and processed translations will be reverted to the original state before the request

Example response

{
  "msg": "OK",
  "status": 200,
  "data": {
    "uniqueKeysProcessed": 2,
    "processedWithWarnings": false,
    "message": "OK"
  }
}

Response fields

  • uniqueKeysProcessed - informs about number of processed translation keys which was sent by a client,
  • processedWithWarnings - informs about encountered warnings during import,
  • message - informs about warning details.