Translation API

De Kok Translations

Table of Contents

General Information

This translation API by De Kok Translations brings high-quality translations to your application. Email us (api@dekok.com) to learn more and to get set up with a free trial account.

Authentication

All requests require an authentication key (email us to get one). To authenticate, set the Authorization header to Auth-Key [your Auth-Key] as demonstrated below.

Example curl

``` console curl -X POST -H "Authorization: Auth-Key your-auth-key-goes-here:dk" \ https://api.dekok.com/usage ```

Example response

``` json { "characters_used": 123456, "end_period": "01-02-2022", "start_period": "01-01-2022" } ```

Testing

A testing environment is made available at https://api-test.dekok.com/. This environment is identical to the production environment, except for already having any unreleased changes and a testing Auth-Key (request one). While there are no hard limits, performance may be worse than the production environment and logs may be used to determine fair use.

5 workdays before any changes that would affect how to interact with the API are deployed to api.dekok.com, these changes will be

  1. made available to you in the testing environment;
  2. communicated to the contact email of your account;
  3. included in the changelog at the bottom of this page.

Error Handling

Succesful requests return status code 200. Unsuccesful requests return one of the errors below. The response body may contain additional information on what went wrong.

Status codes

| Code | Description | | ------------- |:-------------:| | 200 | Succesful request | | 400 | Invalid request. Check the response body and your request parameters | | 403 | Unsuccesful authorization. There should be an *Authorization* header set to *Auth-Key your-auth-key-goes-here:dk* | | 404 | Requested resource not found. Check the requested endpoint. | | 503 | Internal error or timeout (happens after 30 seconds). Delay your next request so that the server can recover. Please get in touch if you consistently get a 503 status code so that we can investigate.

Other Information

Endpoints

POST /translate

Request Parameters

| Parameter | Required | Description | | ------------- |:-------------:| -----:| | text | Required | Text(s) to be translated. Can be repeated and can contain multiple sentences, but **all *text* fields must be of the same language.** For optimal performance, it is recommended to include around 50,000 characters per request. | from | Optional* | The ISO 639-1 language code to translate from. Use the */languages* endpoint to see which languages are available for your account. Only one *from* field can be set. *If absent, the source language will be automatically determined at a performance cost (therefore it is recommended to set it when feasible). | | to | Required | The ISO 639-1 language code to translate to. Use the */languages* endpoint to see which languages are available for your account.

Response

| Value | Description | | ------------- |:-------------:| | detected_source_language | The source language that was specified in the *from* field or the ISO 639-1 language code that was detected and translated from. | | text | A list with the translated texts in the order of the request. Any double quotation marks will be escaped like \".

Example

Request

``` console curl https://api.dekok.com/translate -H "Authorization: Auth-Key your-auth-key-goes-here:dk" -d "from=ru" -d "to=en" -d "text=Эти переводы очень хороши." -d "text=Вы можете установить несколько текстовых переменных. Мы рекомендуем переводить до 50,000 символов или 5000 текстовых переменных на запрос." ```

Response

``` json { "detected_source_language": "ru", "text": [ "These translations are very good.", "You can set several text variables. We recommend translating up to 50, 000 characters or 5000 text variables per request." ] } ```

POST /usage

Returns the number of characters used in a certain month. Defaults to current month.

Request Parameters

| Parameter | Required | Description | | ------------- |:-------------:| -----:| | month | Optional | Number of the month (mm) to get the usage for. If left empty the current month is used. | | year | Optional | Year (yyyy) to look up a certain month's usage for. If left empty the current year is used.

Response

| Value | Description | | ------------- |:-------------:| | characters_used | The number of characters succesfully translated within a period. Each unicode point within 'text' fields of succesful /translate requests counts as one character. | | first_date_of_period | Usage is from this date (dd-mm-yyyy) up to to and including the laste_date_of_period. | | last_date_of_period | Usage is from first_date_of_period up to and including this date (dd-mm-yyyy).

Example

Request

``` console curl https://api.dekok.com/usage -H "Authorization: Auth-Key your-auth-key-goes-here:dk" -d "year=2021" -d "month=12" ```

Response

``` json { "characters_used": 123456, "first_date_of_period": "01-12-2021", "last_date_of_period": "31-12-2021" } ```

POST /languages

Returns the languages that are available to translate to and from. Does not take any parameters (but still requires the Authorization header as it is account based). Additional languages are available upon request.

Response

| Value | Description | | ------------- |:-------------:| | languages | A list of available languages to translate to and from.

Example

Request

``` console curl https://api.dekok.com/languages -H "Authorization: Auth-Key your-auth-key-goes-here:dk" ```

Response

``` json { "languages": [ "ru", "uk", "es", "en", "nl" ] } ```

Changelog

| Date | Environment | Description | | ------------- |:-------------:| -----:| | 09/09/2022 | api.dekok.com | Bugfixes |