Met de Translation API laat je eigen systeem teksten vertalen via Tolkie, zonder de knoppen van de leeshulp. Je vertaalt losse teksten, zoals woorden of knopteksten, of een hele pagina met meerdere tekstblokken tegelijk. De API werkt alleen vanaf de domeinen die bij Tolkie voor jullie organisatie zijn geregistreerd. Standaard vertaalt Tolkie met DeepL.
Wat kan ik met de Translation API?
De API heeft twee endpoints:
Losse teksten vertalen (
/api/v2/translate): voor een lijst met woorden, labels of knopteksten. Je kunt een zin als context meesturen, zodat de vertaling beter klopt.Een pagina vertalen (
/api/v2/translate-advanced): voor meerdere tekstblokken op een pagina, elk met een eigen id en een eigen brontaal.
Wat je met de vertaling doet, bepaal je zelf. Tolkie levert de vertaalde tekst, en jullie systeem laat die zien. De koppeling bouwt jullie eigen developmentteam of webbouwer. Tolkie denkt mee en beantwoordt vragen.
Waarom werkt de API alleen vanaf onze eigen domeinen?
Zo is het token van jullie organisatie alleen bruikbaar vanaf jullie eigen websites. Bij elke aanvraag controleert Tolkie daarom twee dingen: de Origin-header (of anders de Referer) en het veld url_field, de URL van de pagina die je vertaalt. Horen die niet bij een geregistreerd domein, dan krijg je een foutmelding (403).
Wil je een domein laten toevoegen of wil je weten welke domeinen geregistreerd zijn? Mail dan naar [email protected].
Welke vertaalmachine gebruikt de API?
Standaard vertaalt Tolkie met DeepL, tenzij jullie organisatie iets anders heeft gekozen of met ons heeft afgesproken. Sommige talen heeft DeepL niet, zoals Fries, Tigrinya en Papiaments. Die vertaalt Tolkie via Google, met verwerking in de Europese Economische Ruimte. Tolkie stuurt een aanvraag automatisch naar de juiste vertaalmachine.
Worden vertalingen opgeslagen?
Vraag je dezelfde vertaling nog een keer aan, met dezelfde tekst, talen, vertaalmachine en context? Dan kan het antwoord uit de cache van Tolkie komen. Het veld url_field gebruikt Tolkie voor de toegangscontrole en voor statistieken.
Hoe krijg ik toegang tot de API?
Voor de API heb je een token nodig. Dat krijg je tijdens de implementatie van je contactpersoon bij Tolkie of van support. Wil je de API gaan gebruiken? Neem dan contact met ons op via de contactpagina.
Hoe werkt de API technisch?
Dit deel is bedoeld voor developers. Tolkie heeft twee POST-endpoints voor vertalen in de openbare v2-API:
Endpoint | Waarvoor |
| Een platte lijst met teksten vertalen (bijvoorbeeld tekstfragmenten of de context bij een woord) |
| Gestructureerde pagina-inhoud vertalen: meerdere DOM-elementen, elk met een eigen id en eventueel een eigen brontaal |
Beide endpoints vragen om authenticatie met een token en controle van herkomst en URL, zodat jullie API-token alleen werkt vanaf de domeinen die voor jullie organisatie zijn ingesteld.
Basispad: de paden hieronder horen achter het adres van de Tolkie-API, bijvoorbeeld https://<jouw-api-host>/api/v2/translate.
Hoe authenticeer je een aanvraag?
Stuur bij elke aanvraag het API-token van jullie organisatie mee:
Authorization: Token <jouw_api_token>
Content-Type: application/json
401 Unauthorized: het token ontbreekt of is ongeldig.
Tokens worden per klantaccount uitgegeven. Je ontvangt het token tijdens de implementatie.
Hoe controleert de API de herkomst en de URL?
Aanvragen worden gecontroleerd met CheckOriginPermission:
De
Origin-header (of anders deReferer) moet overeenkomen met een van de toegestane URL-patronen van jullie organisatie, of met een vertrouwde Tolkie-applicatie als je de ingebouwde widget of het iframe gebruikt.Het veld
url_fieldin de JSON-body is verplicht. Vul hier de volledige URL in van de pagina die je vertaalt. Tolkie gebruikt dit voor statistieken en, bij gebruik in een iframe, om de website van de klant te controleren.
Voorbeelden
Origin: https://www.your-site.com
{
"url_field": "https://www.your-site.com/articles/example"
}403 Forbidden:
Originofurl_fieldpast niet bij jullie toegestane domeinen.Een
url_fieldvan meer dan 256 tekens wordt op de server ingekort.Stuurt de browser een vertrouwde Tolkie-herkomst mee (bijvoorbeeld
https://app.tolkie.nl), dan moeturl_fieldnog steeds verwijzen naar een URL op een toegestaan domein van jullie organisatie.
Welke taalcodes kun je gebruiken?
Taalcodes volgen de ISO 639-1-stijl, soms met een regio erbij (bijvoorbeeld en-gb of pt-br). De API controleert of de code bij de talen hoort die Tolkie ondersteunt.
Veelgebruikte codes (niet volledig):
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
Een ongeldige code geeft 400, met een validatiefout waarin de ondersteunde waarden staan.
Vertaalmachine: standaard vertaalt Tolkie met DeepL, tenzij jullie organisatie iets anders heeft gekozen of afgesproken. Sommige talen zijn alleen bij een bepaalde aanbieder beschikbaar. Zo gaan Fries (fy), Tigrinya (ti) en Papiaments (pap) via Google. Tolkie stuurt de aanvraag automatisch naar de juiste aanbieder.
Hoe volg je een aanvraag terug?
Elk antwoord bevat de header X-Request-ID. Je kunt ook zelf een ID meesturen:
X-Request-ID: your-tracking-id-123
Het ID is 1 tot 64 tekens lang en bestaat uit letters, cijfers en koppeltekens. Bij validatiefouten staat het ID soms ook als request_id in de body. Stuur dit ID mee als je support om hulp vraagt.
Hoe vertaal je losse teksten met /api/v2/translate?
Hiermee vertaal je een of meer teksten in één aanvraag. Je kunt ook een aparte context laten vertalen, bijvoorbeeld de zin rond een woord dat iemand opzoekt.
Velden in de aanvraag
Veld | Type | Verplicht | Beschrijving |
|
| Ja | De teksten die je wilt vertalen, op volgorde |
|
| Ja | Taalcode van de doeltaal |
|
| Ja | URL van de pagina waar de vertaling plaatsvindt |
|
| Nee | Brontaal. Laat je dit weg, dan gebruikt de API de standaardtaal van jullie organisatie |
|
| Nee | Extra context voor de vertaalmachine, bijvoorbeeld de hele zin |
|
| Nee | Standaard |
Voorbeeld: alleen woorden
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"
}
Voorbeeld: ook de context vertalen
{
"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"
}Staat translate_context op true, dan voegt de server de context toe aan de teksten die vertaald worden, en haalt hem er in het antwoord weer apart uit.
Antwoord bij succes (200 OK)
{
"translated_text_list": ["Haus"],
"translated_context": ""
}Met translate_context: true:
{
"translated_text_list": ["Haus"],
"translated_context": "Ein Haus ist ein Gebäude, in dem Menschen leben"
}translated_text_listheeft dezelfde lengte en volgorde alstext_list.translated_contextis alleen gevuld alstranslate_contextoptruestond. Anders is het"".
Foutmeldingen
Status | Betekenis |
400 | Ongeldige JSON of een validatiefout, bijvoorbeeld een niet-ondersteunde taal of een ontbrekende |
401 | Het token ontbreekt of is ongeldig |
403 | Herkomst of URL is niet toegestaan voor jullie organisatie |
Goed om te weten
Een lange
text_listwordt verwerkt in delen van maximaal 45 teksten per aanroep van de vertaalmachine. De volgorde blijft gelijk.Bij dezelfde tekst, talen, vertaalmachine en context kan het antwoord uit de cache van Tolkie komen.
De
contexthelpt de vertaling, maar komt alleen terug alstranslate_contextoptruestaat.
Hoe vertaal je een pagina met /api/v2/translate-advanced?
Hiermee vertaal je veel pagina-elementen in één aanvraag. Elk element heeft een vaste id (bijvoorbeeld de id in de DOM), een lijst met tekstfragmenten en een eigen source_language. Teksten met dezelfde brontaal worden samen verwerkt.
Gebruik dit endpoint voor een hele pagina of meerdere tekstblokken, niet voor één platte lijst.
Velden in de aanvraag
Veld | Type | Verplicht | Beschrijving |
|
| Ja | Doeltaal voor alle elementen |
|
| Ja | URL van de pagina (voor statistieken en de controle van de herkomst) |
|
| Ja | Lijst met elementen die je wilt vertalen |
Elk object in text_list:
Veld | Type | Verplicht | Beschrijving |
|
| Ja | Vaste id, die terugkomt in het antwoord |
|
| Ja | Tekstfragmenten van dit element, op volgorde |
|
| Ja | Brontaal van dit element |
Voorbeeld
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"
}
]
}
Antwoord bij succes (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"]
}
}De sleutels in
translated_textzijn deid's van je elementen.Elke waarde is een
string[]met dezelfde lengte en volgorde als detextvan dat element.
Foutmeldingen
Status | Betekenis |
400 | Validatiefout |
401 | Het token ontbreekt of is ongeldig |
403 | Herkomst of URL is niet toegestaan |
Goed om te weten
Elementen worden gegroepeerd per
source_language. Elke groep gaat in een of meer delen naar de vertaalmachine, met maximaal 45 teksten per aanroep.De omschrijving van jullie organisatie die in Tolkie is ingesteld, dient als context voor de paginavertaling.
Dit endpoint vertaalt met oog voor HTML (intern
use_html: true). Stuur de tekst in zoals je hem van de pagina haalt.url_fieldis verplicht, maar wordt op de server niet bewaard. Tolkie gebruikt het voor de toegangscontrole en statistieken.
Welk endpoint kies je?
Wat wil je doen? | Endpoint |
Een lijst met labels, woorden of knopteksten vertalen |
|
Ook een aparte context laten vertalen |
|
Veel delen van een pagina vertalen, met id's en verschillende brontalen |
|
Waar kan ik terecht met vragen?
Heb je vragen over de koppeling, wil je een domein laten toevoegen of krijg je een foutmelding? Mail naar [email protected] en stuur de X-Request-ID mee. Wil je de API gaan gebruiken? Neem dan contact op via de contactpagina.