API: Read translations

Last modified: October 18, 2022Author: Jakub Pomykała

This is split into two sections, Translation Hosting and REST API. The CDN offers free, fast and public access to your translations, it can be used in client-side application. API offers filter and query options, and uses your API Key which can be used also for modifying translations, so it should be used only in server-side applications and integrations.

Translation Hosting

Translation Hosting is a content-delivery network (CDN), it's a fast and safe to share the link to the public. It's not rate-limited, so you don't have to worry about the number of requests. You can use it safely in client-side applications. Fetching data from Translation Hosting is available in all pricing plans including the Community plan.

URL structures

List of all Translation Hosting resources is available in the 'Hosting' tab on your project page. Below you can find example URL structures.

# All translations
https://cdn.simplelocalize.io/{projectToken}/{environment}/_index

# List of all project languages
https://cdn.simplelocalize.io/{projectToken}/{environment}/_languages

# List of all project customers
https://cdn.simplelocalize.io/{projectToken}/{environment}/_customers

# Translations for given {languageKey}
https://cdn.simplelocalize.io/{projectToken}/{environment}/{languageKey}

# Translations for given {languageKey} and {customerId}, if at least one customerId is defined
https://cdn.simplelocalize.io/{projectToken}/{environment}/{languageKey}_{customerId}

# Translations for given {languageKey} and {namespace}, if at least one namespace is defined
https://cdn.simplelocalize.io/{projectToken}/{environment}/{languageKey}/{namespace}

# Translations for given {languageKey}, {namespace} and {customerId}, if at least one namespace and customerId is defined
https://cdn.simplelocalize.io/{projectToken}/{environment}/{languageKey}_{customerId}/{namespace}

Parameters

  • projectToken - your project token which can be found in the 'Integrations' tab,
  • environment - environment name, _latest or _production,
  • languageKey - language key, e.g.: en, pl, de,
  • namespace - namespace, e.g.: common, home, auth,
  • customerId - customerId used for customer-specific translations, e.g.: ikea, adidas.

GET Get all translations

https://cdn.simplelocalize.io/{projectToken}/{environment}/_index

Example response

{
  "de": {
    "SALE": "Verkauf",
    "ADDRESS": "Adresse"
  },
  "fr": {
    "SALE": "soldes",
    "ADDRESS": "adresse"
  }
}

GET Get translations by language key

https://cdn.simplelocalize.io/{projectToken}/{environment}/{languageKey}

Example response

{
  "SALE": "Verkauf",
  "ADDRESS": "Adresse"
}

GET Get languages

https://cdn.simplelocalize.io/{projectToken}/{environment}/_languages

Example response

[
   {
      "key": "de",
      "name": "Deutsch"
   },
   {
      "key": "en",
      "name": "English"
   },
   {
      "key": "es",
      "name": "Español"
   }
]

Link variables:

  • environment values: _latest or _production, 'Hosting' tab
  • projectToken value is the project token, 'Integrations > Project credentials' tab
  • languageKey value is the language key set in 'Languages' tab

REST API

This section is about using REST API to fetch translations. It's possible to use it in server-side applications and integrations. If you are using this endpoint, the authorization is required. Add API Key for your project as a X-SimpleLocalize-Token request header.

Please note that the API Access is rate-limited, and you should not use it to fetch translations for every end-user nor use it in client-side applications. Use Translation Hosting instead.

GET Query all translations

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

Available query parameters

Query parameterDescription
textquery for translated text, uses 'contains with ignore case'
keyfilter by given translation key, uses 'equals'
languagefilter by given language key, uses 'equals'
customerIdfilter by given customer id, uses 'equals'; see customer-specific translations

GET Query translations with language 'de' and translation key 'hello'

https://api.simplelocalize.io/api/v1/translations?languageKey=de&key=hello

Example response

{
    "msg": "OK",
    "status": 200,
    "data": {
        "content": [
            {
                "key": "CREATE.TAGS",
                "language": "en",
                "text": "Tags"
            },
            //...
        ]
    }
}