Simpleen API Documentation

Table of Contents

General

  • Data to Simpleen is sent as JSON (Content-Type: application/json)
  • All requests have to be authenticated (with a valid authentication key)
  • Timestamps createdat and updatedat are sent for all entities in UTC, as ISO8601 format.

Authentication

You can create an authentication key after login to the webapp.

The authentication key is 32 characters long. Provide the generated authentication key as a parameter.

curl -X GET \
  -F "auth_key=YOUR_AUTHENTICATION_KEY" \
  'https://api.simpleen.io/glossaries' \

Entities

All entities exposed via the API can be found in their respective sections.

Glossary

A glossary is a collection of word lists. These are used to mark the words that should not be translated (ignored) as well as some customized translations.

Attributes

{
   "id": 1,
   "name":"Test",
   "user": User-Entity,
   "entries": [{
      "id": 2,
      "from": "Three of a Kind",
      "to": "Drilling",
      "postTranslate":false
   }],
   "ignored":[{
      "id": 1,
      "word":"chip"
   },{
      "id": 2,
      "word":"WSOP"
   }],
   "translators": Translator-Entity[]
}

GET /glossaries

Get a list of your glossaries.

GET /glossary/

Get a specific glossary.

POST/PUT/DELETE/

Create, update or delete a specific glossary.

Language

Languages are preset and represent all supported languages of DeepL service with XML Markup support (Chinese and Japanese do not have XML Markup support yet).

Attributes

{
  "id": 1,
  "name": "English",
  "language": "EN",
  "source": true, // If set to true, this language can be used as a source_language
  "target": true // If set to true, this language can be used as a target_language
}

GET /languages

Get a list of all languages.

GET /language/

Get a specific language.

POST/PUT/DELETE

Not possible to create a new language. Please contact us if something is missing or has changed.

Translator

Each translator is configured and can be used to translate the provided text (See below POST translator/{id}/translate). This configuration is especially useful for reusing predefined structures and formats.

Attributes

{
  "id": 1,
  "name": "Translate Blog Entry EN->DE",
  "format": "JSON",
  "formality": "more" | "less" | "default",
  "interpolation": "i18next" | "polyglot", // Expects default interpolation: i18next as {{term}} and polyglot as %{term}
  "user": User - Entity,
  "glossary": (Glossary - Entity) | null,
  "example_Input": "{'body': '<p>This is my text to translate</p>'}",
  "source_language": Language - Entity,
  "target_language": Language - Entity,
  "selections": [
    {
      "id": 1,
      "path": "body", // Selects .body from provided JSON Object
      "format": "HTML" // HTML | XML | Markdown | Text | PlainText
    }
  ]
}

POST translator/{id}/translate

Use the translator to translate your provided text. The text needs to be provided as a string, i. e. stringify JSON data.

curl -X POST \
  'https://api.simpleen.io/translator/{id}/translate' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -F "auth_key=YOUR_AUTHENTICATION_KEY" \
  -d '{"text": "{\"header\": \"Our hero story\", \"intro\": \"This story starts with a translation\"}"}'

Translate dynamically via POST /translate

To use the translation service directly request translate via Post request and provide the required parameters. The provided text and selections need to be a strings, i. e. stringify JSON data. This is especially useful if you want to provide some config dynamically, i. e. a model of a headless CMS with different fields.

curl -X Post \
   'https://api.simpleen.io/translate' \
   -H 'Accept: application/json' \
   -H 'Content-Type: application/json' \
   -F "auth_key=YOUR_AUTHENTICATION_KEY" \
   -d '{
      "format": "JSON",
      "source_language": "EN",
      "target_language": "DE",
      "glossary": 100,
      "selections": "[{\"path\": \"header\", \"format\": \"Text\"}, {\"path\": \"intro\", \"format\": \"HTML\"}]",
      "text": "{\"header\": \"Our hero story\", \"intro\": \"This story starts with a translation\"}"
   }'

Required fields are

  • format (JSON, HTML, Markdown, YAML)
  • target_language (See field language of language-entity without 'auto')
  • text (Text to be translated/stringified JSON-Object)

Default values:

  • source_language: "auto"
  • selections:
[
  { "path": "$.*", "format": "HTML" },
  { "path": "$.*.*", "format": "HTML" },
  { "path": "$.*.*.*", "format": "HTML" },
  { "path": "$.*.*.*.*", "format": "HTML" },
  { "path": "$.*.*.*.*.*", "format": "HTML" },
  { "path": "$.*.*.*.*.*.*", "format": "HTML" },
  { "path": "$.*.*.*.*.*.*.*", "format": "HTML" }
]
  • glossary: null

Returns the translated text in the provided format. Our example above becomes: { "header": "Unsere Helden-Geschichte", "intro": "Diese Geschichte beginnt mit einer √úbersetzung" }

User

A user can authenticate himself and be the owner of glossaries, translators and settings. He can only list and change entities that belong to him.

Attributes

{
  "id": 1,
  "username": "info",
  "email": "info@simpleen.io",
  "provider": "local",
  "confirmed": true,
  "blocked": false,
  "role": 1
}

Errors and HTTP status codes

The Simpleen API is mostly conformant with the general HTTP status codes.

Filter and Sort

All returned lists can be filtered and sorted. Check out the available parameters of strapi for further explanations.