Simpleen API Reference

Table of Contents

• General
• Authentication
• Entities
• Errors and HTTP status codes
• Sorting

General

• Data to Simpleen is sent as JSON (Content-Type: application/json)
• All requests have to be authenticated (with a valid authentication key)

• Timestamps created_at and updated_at are sent for all entities in UTC, as ISO8601 format.

Authentication

You can create an authentication key after your 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.

• File
• Glossary
• Language
• Segment
• Translator
• User

File

A file is automatically created during the translation of localization files. It represents a file in your project to translate. As a user you don't have to create files. A subsequent online translation of a similar input is matched if the content is at least to 50% identical to a previous file. Otherwise a new file will be created.

Attributes

{
  "id": 8,
  "name": "File 6",
  "dataformat": "JSON",
  "interpolation": "icu",
  "filepath": null,
  "source_language": LanguageEntity,
  "user": UserEntity,
  "glossary": GlossaryEntity,
  "formality": "more" | "less" | "default",
  "segments": SegmentEntity[],
  "target_languages": LanguageEntity[]
}

GET /files

Get a list of your files.

GET /files/{id}

Get a specific file.

POST/PUT/DELETE /files/{id}

Create, update or delete a specific file.

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": UserEntity,
   "entries": [{
      "id": 2,
      "from": "Three of a Kind",
      "to": "Drilling",
      "postTranslate":false
   }],
   "ignored":[{
      "id": 1,
      "word":"chip"
   },{
      "id": 2,
      "word":"WSOP"
   }],
   "translators": TranslatorEntity[]
}

GET /glossaries

Get a list of your glossaries.

GET /glossaries/{id}

Get a specific glossary.

POST/PUT/DELETE /glossaries/{id}

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) or Google Translate (for languages that are not yet supported by DeepL).

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/{id}

Get a specific language.

POST/PUT/DELETE

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

Segment

A segment is a translatable part of your localization file. The segments will get automatically created during the translation process. You can post-edit existing translations to fix/correct future translation usage.

It gets translated from source_entry to entry if the parameters/configuraiton are comparable.

Attributes

{
  "id": 1,
  "entry": "Mein Eintrag (Translated version of source_entry in German)",
  "path": "JSON-Path in structure, i.e. $.title",
  "source_entry": "My Entry",
  "service": "DeepL",
  "file": FileEntity,
  "formality": "more" | "less" | "default",
  "interpolation": InterpolationValue,
  "user": UserEntity,
  "source_language": LanguageEntity,
  "target_language": LanguageEntity
}

GET /segments

Get a list of all segments.

GET /segments/{id}

Get a specific segment.

POST /segments

Create a specific segment.

PUT/DELETE /segments/{id}

Update, delete existing segment.

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",
  "dataformat": "JSON",
  "formality": "more" | "less" | "default",
  "interpolation": Interpolation,
  "user": UserEntity,
  "glossary": GlossaryEntity | null,
  "example_Input": "{'body': '<p>This is my text to translate</p>'}",
  "source_language": LanguageEntity,
  "target_language": LanguageEntity,
  "selections": [
    {
      "id": 1,
      "path": "body", // Selects .body from provided JSON Object
      "format": "HTML" // HTML | XML | Markdown | Text | PlainText
    }
  ]
}

Values for Interpolation

Interpolation value	Expected Variables
i18next	{{ variable }}
polyglot	%{ variable }
icu	{ variable, withParams }
i18n	{ variable }
ruby	${ variable }
laravel	:variable
default	Automatic/Guessing
none	none

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 '{
      "dataformat": "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

• dataformat (JSON, HTML, Markdown, Properties, PHPArray, PO, YAML)
• target_language (See field language of languageEntity 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.