Docs

Everything you need to add translation to your website or app. Each part has a short example you can copy.

Start here

Send a request with your key, and you get the answer back as JSON.

Address: https://api.neotranslate.org/v1
Your key: Send it in a header: Authorization: Bearer nt_live_…
Format: Send JSON and get JSON back. Text is UTF-8.
Languages: Short codes, like en, fr, sw, yo. See how to list them.

Keep your key in your server code or settings. Don't put it in web page code that visitors can see. If a key gets out, turn it off and make a new one.

No key yet? Ask for access and get a key.

Translate text

Send some text and the language you want. Get the translation back.

POST /v1/translate

Request

curl https://api.neotranslate.org/v1/translate \
  -H "Authorization: Bearer nt_live_…" \
  -H "Content-Type: application/json" \
  -d '{"text":"God loves you.","from":"en","to":"sw"}'

Response

JSON

{
  "translation": "Mungu anakupenda.",
  "from": "en",
  "to": "sw",
  "early": false
}

Fields you send

text: The words to translate. Up to 5,000 characters.
to: The language you want, as a code.
from: The language of your text. Leave it out and Neo works it out. For a word or two, send it: short text is hard to tell apart.

Fields you get back

translation: Your text in the new language.
from: The language Neo translated from. Useful when you left it out.
to: The language Neo translated into.
early: true for a language that is still being reviewed. What this means.

Many languages at once

Give to a list of up to 10 languages, and get every translation back in one answer.

POST /v1/translate

Request

curl https://api.neotranslate.org/v1/translate \
  -H "Authorization: Bearer nt_live_…" \
  -H "Content-Type: application/json" \
  -d '{"text":"Welcome to church.","from":"en","to":["fr","yo","ha"]}'

Response

JSON

{
  "from": "en",
  "translations": [
    { "to": "fr", "translation": "Bienvenue à l'église.", "early": false },
    { "to": "yo", "translation": "Kaabo si ile ijọsin.", "early": false },
    { "to": "ha", "translation": "Barka da zuwa coci.", "early": false }
  ]
}

to: A list of language codes instead of one.
translations: One entry for each language, in the order you asked.

If one language can't be done right now, the others still come back. That entry has an error instead of a translation, and its characters aren't counted:

One entry

{ "to": "yo", "early": false, "error": { "status": 503, "message": "Not available right now: this language can't be used at the moment. Try again later." } }

Find the language

Send some text and find out which language it is in.

POST /v1/detect

Request

curl https://api.neotranslate.org/v1/detect \
  -H "Authorization: Bearer nt_live_…" \
  -H "Content-Type: application/json" \
  -d '{"text":"Dieu vous aime beaucoup"}'

Response

JSON

{
  "language": "fr",
  "name": "French",
  "confidence": 0.65,
  "reliable": true,
  "others": [{ "language": "lu", "name": "Luba-Kasai", "confidence": 0.35 }]
}

language: The most likely language, as a code. null if Neo can't tell.
name: Its name in English.
confidence: From 0 to 1: how sure Neo is.
reliable: true when you can rely on it. A word or two is often false: ask the person, or send more text.
others: Up to two other possible languages.

List languages

Get every language you can use, with its code and its name in its own language.

GET /v1/languages

Request

curl https://api.neotranslate.org/v1/languages \
  -H "Authorization: Bearer nt_live_…"

Response

JSON

{
  "languages": [
    { "code": "sw", "name": "Swahili", "nativeName": "Kiswahili", "rtl": false, "early": false },
    { "code": "ar", "name": "Arabic", "nativeName": "العربية", "rtl": true, "early": false }
  ]
}

code: What you put in from and to.
name: The language's name in English.
nativeName: The name in the language itself. Show this to your readers.
rtl: true when the language is written right to left. Set dir="rtl" on the text.
early: true for an Early language. What this means.

It's the same list every Neo platform uses. When a language is added, it shows up here too. The list changes rarely: fetch it once a day, not on every page view.

Early languages

Some languages are still being reviewed by speakers. They work, and every answer marks them with "early": true. Translations into them may need a check by someone who speaks the language before you publish.

A good way to show it: a small note such as "New language, help us improve" next to the translation.

Errors

When something goes wrong, you get a status code and a message in plain words.

Example

{
  "error": {
    "status": 401,
    "message": "Key problem: this key has been turned off."
  }
}

What each code means

400: Something is missing. A field is missing, or a language code isn't right. The message says which.
401: Key problem. Your key is missing, not valid, or turned off.
413: Too long. The text is over 5,000 characters. Split it into parts.
429: Slow down, or a limit is reached. The message says which, and Retry-After says how many seconds to wait.
503: Not available right now. Try again later.
500: Our mistake. Something went wrong on our side. Try again. If it keeps happening, contact support.

Is it just you? Check the status at the foot of any page.

Limits

Fair-use limits keep Neo fast for everyone.

Free plan: 100,000 characters every 30 days, for all your keys together. It renews 30 days after you were approved, and every 30 days after that.
Per request: Up to 5,000 characters, and up to 10 languages.
Per key: 60 requests a minute, 4 at the same time, and 100,000 characters a day (days end at midnight, Lagos time).

How characters are counted: the length of your text times the number of languages. A language that fails isn't counted.

Every answer has RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (requests this minute), and Neo-Characters-Remaining (what you can still send).

If you get a 429, wait the seconds in Retry-After, then try again. Wait a little longer each time it happens.
Translate once and save the result. Don't ask for the same text again on every page view.
Need more for a big event or a large website? Please talk to us, and we'll help.

Keys in phone apps

Anyone who unpacks a phone app can read a key inside it. The safest way: your app asks your own server, and your server calls Neo with the key.

If you do put a key in an app, give that app its own key. Then, if it gets out, you can turn it off without stopping your website.