API: Add translations

Last updated: February 27, 2023Author: Jakub Pomykała

In this section, you will learn how to add translations using API access. You can use this endpoint to add new translation keys and translations or update existing translations. Requests with less than 50 elements are buffered, and they will be added to the translation editor after a few minutes (up to 15 minutes).

Deprecation notice: This endpoint will be deprecated in the future. Check the updated documentation instead.




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 the translation key and language if not found.
  • Endpoint will automatically update the last seen value in the translation editor.
  • Endpoint will automatically add language if not found.
  • Endpoint won't replace existing translations by default. Use update translations endpoint or importOptions=REPLACE_TRANSLATION_IF_FOUND.
  • Endpoint won't create customerId automatically if not found.
  • Endpoint won't update a translation, if key and/or language is missing.

Sample request

    --request POST 'https://api.simplelocalize.io/api/v1/translations' \
    --header 'X-SimpleLocalize-Token: <API_KEY>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "content": [
                "key": "HELLO_WORLD",
                "language": "en",
                "text": "Hello world!"
                 "key": "HELLLO_WORLD",
                 "language": "pl",
                 "text": "Witaj świecie!"

Request fields

  • content - array of objects with translations,
    • key - unique translation key for a project,
    • language - project language key,
    • text - translation text,
    • namespace - namespace for a translation key,
    • description - description for a translation key,
    • customerId - customer id for a translation key.

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.