Developer Portal

API Reference

Versioned REST at /v1. Send source_lang and target_lang on every call. Discover pairs with GET /v1/languages. Nested UI trees go to /v1/translate/tree for single pages, and to /v1/translate/jobs for a whole site.

01.Authentication

The production JSON translation API supports two methods of authentication. Use API Keys for server-to-server communication and Bearer tokens for client-side user sessions.

Method A

API Key (Recommended)

Use the X-API-Key header to authenticate requests from your backend services.

X-API-Key: YOUR_SECRET_KEY

Method B

Bearer Token

Use the standard Authorization header for authenticated user portal calls.

Authorization: Bearer <JWT_TOKEN>

02.The "UI Mirroring" Pattern

Stop flattening your data. Our API respects your UI tree.

Unlike legacy translation APIs that require you to send flat arrays of strings, translate processes entire nested objects. The engine recursively traverses your payload, translates every { "og": "..." } node, and returns the exact same structure back.

Recursive Engine v2.0

// Input: Send your actual UI state

{ "payload": { "dashboard": { "title": { "og": "Your Revenue" }, "stats": { "label": { "og": "Active Users" } } } } }

// Output: Receive the mirrored localization tree

{ "payload": { "dashboard": { "title": { "otjiherero": "..." }, "stats": { "label": { "otjiherero": "..." } } } } }

03.Quick Start

Integration with any stack is straightforward. Send any active source/target pair. GET /v1/languages lists what is live.

const response = await fetch('https://api.translate.nkngo.com/v1/translate', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    text: 'Professional Translation Engine',
    source_lang: 'eng',
    target_lang: 'her'
  })
});

const data = await response.json();
console.log(data.translations[0].text);

04.Bulk Translation Jobs

The synchronous endpoints stop at 5,000 characters per request, which is fine for a page but not for a whole site. For anything larger, submit a background job: one call accepts up to 2,000,000 characters, is billed against your normal quota, and stays available for an hour after it finishes.

Step 1

Submit

POST the texts or the nested tree. You get a job id back immediately.

Step 2

Wait

Poll the status endpoint, or watch the SSE stream for progress events.

Step 3

Collect

When status is complete, the finished payload is in "tree" (or "translations").

Whole-site example

# 1. Submit the whole site — returns a job id immediately
curl -X POST https://api.translate.nkngo.com/v1/translate/jobs \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "my-site",
    "source_lang": "eng",
    "target_languages": ["her", "ndo"],
    "tree": {
      "hero": { "title": { "og": "Contact us" } },
      "nav":   { "home":  { "og": "Home" } }
    }
  }'
# → {"job_id":"8f3c…","status":"queued","status_url":"/v1/translate/jobs/8f3c…",
#    "events_url":"/v1/translate/jobs/8f3c…/events"}

# 2. Poll the status endpoint (or stream the event URL instead)
curl https://api.translate.nkngo.com/v1/translate/jobs/8f3c… \
  -H "X-API-Key: YOUR_API_KEY"
# → {"job_id":"8f3c…","status":"processing","progress":0.5,…}

# 3. Collect the finished payload
# → {"job_id":"8f3c…","status":"complete","progress":1.0,
#    "tree":{"hero":{"title":{"her":"…","ndo":"…"}},
#            "nav":{"home":{"her":"…","ndo":"…"}}}}

The tree leaf contract

A leaf is any object containing an "og" string. That object is replaced by { "her": "...", "ndo": "..." }, so keep any metadata you need (a tag name, a class, a key) outside the leaf — inside it is replaced. Strings that are not wrapped in an "og" leaf are not translated, which is the usual reason some page text comes back unchanged.

05.Model Status

The live text mesh is English, Otjiherero, Oshikwanyama, Rumanyo, Oshindonga, Rukwangali, Khoekhoegowab, and Rugciriku — any of these to any other. Remaining languages are coming soon.

Available now

8-language text mesh

Any active language to any other active language, including English.

Coming soon

Silozi, Setswana, and others

Coming soon in upcoming model releases.

06.Errors & Limits

Standard HTTP response codes for clear debugging.

Code	Message	Description
400	Bad Request	Malformed JSON or missing "payload" key.
401	Unauthorized	Invalid API Key or expired Bearer token.
429	Limit Reached	Your current API plan quota has been exceeded.
500	Server Error	Unexpected service error during translation processing.