Naar de hoofdinhoud

Tolkie Translation API

Overview

Tolkie exposes two POST translation endpoints under the public v2 API:

Endpoint

Use case

/api/v2/translate

Translate a flat list of strings (widget snippets, dictionary context, etc.)

/api/v2/translate-advanced

Translate structured page content: multiple DOM elements, each with its own ID and optional per-element source language

Both endpoints require token authentication and origin / URL validation so your API token can only be used from domains configured for your Tolkie client.

Base path: paths below are relative to your Tolkie API host, e.g. https://api.example.com/api/v2/translate.

Authentication

Send your client API token on every request:

Authorization: Token <your_api_token>

Content-Type: application/json

  • 401 Unauthorized — missing or invalid token.

  • Tokens are issued per Tolkie client account (contact Tolkie or use your onboarding flow to obtain one).

Origin and URL security

Requests are validated with CheckOriginPermission:

  1. Origin header (or Referer as fallback) must match one of your client’s allowed URL patterns, or a trusted Tolkie application origin when using the embedded widget/iframe.

  2. url_field in the JSON body is required and must be the full URL of the page being translated (used for analytics and, in iframe scenarios, to verify the customer site).

Examples

Origin: https://www.your-site.com
{
    "url_field": "https://www.your-site.com/articles/example"
}

  • 403 Forbidden — Origin / url_field does not match your allowed domains.

  • url_field longer than 256 characters is truncated server-side.

  • When the browser sends a trusted Tolkie app origin (e.g. https://app.tolkie.nl), url_field must still point to a URL whose origin is allowed for your client.

Supported languages

Language codes use ISO 639-1 style strings, sometimes with a region (e.g. en-gb, pt-br). Codes are validated against Tolkie’s supported set.

Common codes (not exhaustive):

ar, bg, cs, da, de, el, en-gb, en-us, es, et, fi, fr, fy, hu, id, it, ja, ko, lt, lv, nb, nl, pap, pl, pt-pt, pt-br, ro, ru, sk, sl, sv, ti, tr, uk, zh

Invalid codes return 400 with a validation error listing supported values.

Provider note: The translation backend (Google, DeepL, or Azure) is chosen per your Tolkie client configuration. Some languages are only available on specific providers; Tolkie routes accordingly.

Correlation ID

Every response includes X-Request-ID. You may send your own id:

X-Request-ID: your-tracking-id-123

(1–64 characters: letters, digits, hyphen.) Error bodies from validation may also include request_id.

1. Simple translation — POST /api/v2/translate

Translate one or more strings in a single request. Optionally translate a separate context string (e.g. surrounding sentence for a dictionary lookup).

Request body

Field

Type

Required

Description

text_list

string[]

Yes

Texts to translate, in order

target_language

string

Yes

Target language code

url_field

string (URL)

Yes

Page URL where translation runs

source_language

string

No

Source language; if omitted, uses your client’s default language

context

string

No

Extra context passed to the translator (e.g. full sentence)

translate_context

boolean

No

Default false. If true, context is also translated

Example — words only

POST /api/v2/translate
Authorization: Token abc123...
Origin: https://www.example.com
Content-Type: application/json
{
  "text_list": ["huis"],
  "context": "Een huis is een gebouw waarin mensen wonen",
  "translate_context": false,
  "target_language": "de",
  "url_field": "https://www.example.com/page"
}

Example — translate context as well

{
  "text_list": ["huis"],
  "context": "Een huis is een gebouw waarin mensen wonen",
  "translate_context": true,
  "target_language": "de",
  "url_field": "https://www.example.com/page"
}

When translate_context is true, the server appends context to the batch for translation, then splits it out in the response.

Success response — 200 OK

{
  "translated_text_list": ["Haus"],
  "translated_context": ""
}

With translate_context: true:

{
  "translated_text_list": ["Haus"],
  "translated_context": "Ein Haus ist ein Gebäude, in dem Menschen leben"
}

  • translated_text_list — same length and order as text_list.

  • translated_context — populated only when translate_context was true; otherwise "".

Error responses

Status

Meaning

400

Invalid JSON or validation error (e.g. unsupported language, missing url_field)

401

Invalid or missing token

403

Origin / URL not allowed for this client

Behavior notes

  • Large text_list values are processed in chunks of up to 45 strings per provider call; order is preserved.

  • Results may be served from Tolkie’s cache for identical text, languages, provider, and context.

  • context influences translation quality but is not returned unless translate_context is true.

2. Advanced (page) translation — POST /api/v2/translate-advanced

Translate many page elements in one request. Each element has a stable id (e.g. DOM id), an array of text fragments, and its own source_language. Texts that share the same source language are batched efficiently.

Use this for full-page or multi-block translation, not for a single flat list.

Request body

Field

Type

Required

Description

target_language

string

Yes

Target language for all elements

url_field

string (URL)

Yes

Page URL (analytics / origin checks)

text_list

object[]

Yes

List of elements to translate

Each object in text_list:

Field

Type

Required

Description

id

string

Yes

Stable identifier (returned in the response map)

text

string[]

Yes

Text fragments for this element, in order

source_language

string

Yes

Source language for this element

Example

POST /api/v2/translate-advanced
Authorization: Token abc123...
Origin: https://www.example.com
Content-Type: application/json
{
  "target_language": "nl",
  "url_field": "https://www.example.com/news",
  "text_list": [
    {
      "id": "123",
      "text": ["News of the day", "This seems perfect"],
      "source_language": "en-gb"
    },
    {
      "id": "456",
      "text": ["Rain in the morning", "This is a test"],
      "source_language": "en-gb"
    },
    {
      "id": "789",
      "text": ["Es ist ganz gut", "aber nicht so gut"],
      "source_language": "de"
    }
  ]
}

Success response — 200 OK

{
  "translated_text": {
    "123": ["Nieuws van de dag", "Dit lijkt perfect"],
    "456": ["Regen in de ochtend", "Dit is een test"],
    "789": ["Het is allemaal goed", "maar niet zo goed"]
  }
}

  • Keys in translated_text match your element id values.

  • Each value is a string[] with the same length and order as that element’s text array.

Error responses

Status

Meaning

400

Validation error

401

Invalid or missing token

403

Origin / URL not allowed

Behaviour notes

  • Elements are grouped by source_language; each group is sent to the translator in one or more batches (max 45 strings per provider call).

  • The client’s “about” text (configured in Tolkie) is used as translation context for advanced/page translation.

  • HTML-aware translation is enabled for this endpoint (use_html: true internally)—send text as extracted from the page.

  • url_field is required by the API but is not persisted server-side; it is used for permission checks and analytics.

Choosing an endpoint

Need

Endpoint

Translate a list of labels, words, or UI strings

/api/v2/translate

Optional: also translate a separate context string

/api/v2/translate with translate_context: true

Translate many page regions with IDs and mixed source languages

/api/v2/translate-advanced

Was dit een antwoord op uw vraag?

Gerelateerde artikelen