API: Add translations

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


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 importOptions=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


Example cURL

    --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 valueDescription
REPLACE_TRANSLATION_IF_FOUNDReplaces translation for key if the key already exists. Without this option SimpleLocalize will only add new translations.
PUBLISH_AFTER_IMPORTTranslations 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

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.