Translator API: How to Translate Automated Online Store Product Descriptions (curl, Node.js, Python)

By , Tim Engineering APIPedia · Published · Updated · 11 min read

APIPedia's Translator API translates up to 50 texts at once via POST /v1/translate. Example of an online store catalog with curl, Node.js, and Python.

APIPedia cover: title "Translate store catalog once sent" with POST /v1/translate chip, max. 50 items, and 5,000 characters, as well as two cards: input text[] in Indonesian and output translatedText[] in English via the Google provider in 988 ms.

APIPedia's Translator API translates one text or up to 50 texts at once via one request POST /v1/translate, with the source language being detected automatically. The results are in field translatedText, in the same order as the text you sent.

This tutorial uses the case of an online store that wants to display a catalog in English: product names, descriptions and shipping notes are translated from the backend, then stored in the database. You'll see examples of curl, Node.js, and Python, real-world responses from our test on November 15, 2026, and when to use AI mode.

Quick summary: what do you need to know?

The Translator product has two endpoints: one for translating, one for viewing a list of languages ​​and providers. The following table summarizes the essence.

ItemsDetails
TranslatePOST https://api.apipedia.id/v1/translate
List of languages ​​and providersGET https://api.apipedia.id/v1/translate/languages
Mandatory bodytext (string or array of strings) and target (e.g. "en")
Body optionalsource (default auto), provider (default auto), and model, formality, instructions for AI mode
Limit5,000 characters per request, maximum 50 items in one array
AuthenticationHeader Authorization: Bearer apk_xxx
Auto mode providergoogle, then google-dict, then mymemory
ResultstranslatedText, source, target, provider, attempts

What problems does the Translator API solve?

This API eliminates the work of copying product descriptions one by one to a translation tool. Stores with hundreds of products typically hold off on the English version because translating the manual is time-consuming, and any changes to the description have to be re-translated.

With one endpoint in the backend, translation becomes part of the product save flow. The admin types a description in Indonesian, your system sends it to the API, then the result is saved as a draft English version that just needs to be checked.

Mode auto also eliminates one source of disruption: if the first provider fails due to blocking, quota exhaustion, or timeout, the API tries the next provider without you writing your own backup logic.

APIPedia Translator auto API mode flow diagram: the application sends POST /v1/translate, the gateway tries the Google provider first, if it fails it goes to google-dict, then mymemory, and the provider that fails is skipped. The results return as translatedText with the provider field and a list of attempts. Test example November 15, 2026: Google provider succeeded in 988 ms for three sentences.

What do you need to prepare before starting?

You only need one APIPedia API key. Register or log in at console.apipedia.id, open the API Token menu, then create a new key. The key starts with apk_ and is sent via header Authorization: Bearer apk_xxx.

Store the key in a server environment variable, for example APIPEDIA_KEY, and call the API from the backend. Translator products are listed in the Free tier in the catalog. AI mode is different: it cuts AI credits and requires a key with the AI ​​Gateway scope.

Step 1: how to translate a single text with curl?

Send text and target as JSON to POST /v1/translate. The following example translates a one-sentence product description into English.

curl -s -X POST https://api.apipedia.id/v1/translate \
  -H "Authorization: Bearer apk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"text": "Keripik tempe renyah khas Malang, digoreng tanpa pengawet.", "target": "en"}'

If text is a string, translatedText is also a string. Field source may be left blank; The API detects the language and reports it in the response. Commonly used language codes include id, en, jv (Javanese), su (Sundanese), ms, ar, ja, ko, and zh-CN.

Step 2: how to translate multiple texts in one request?

Send text as an array, and the API returns an array of results in the same order. This method is more economical than one request per sentence, because three product fields are just one call away.

curl -s -X POST https://api.apipedia.id/v1/translate \
  -H "Authorization: Bearer apk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "text": [
      "Keripik tempe renyah khas Malang, digoreng tanpa pengawet.",
      "Berat bersih 250 gram, tahan 3 bulan di suhu ruang.",
      "Gratis ongkir untuk pembelian minimal 5 bungkus."
    ],
    "target": "en"
  }'

Real response from our test:

{
  "is_success": true,
  "message": "Text translated (provider google).",
  "data": {
    "translatedText": [
      "Typical Malang crispy tempe chips, fried without preservatives.",
      "Net weight 250 grams, lasts 3 months at room temperature.",
      "Free shipping for minimum purchase of 5 packs."
    ],
    "source": "id",
    "target": "en",
    "provider": "google",
    "attempts": [
      { "provider": "google", "status": "success", "ms": 988 }
    ]
  }
}
FieldsMeaning
translatedTextTranslation results. String if the input is a string, array if the input is an array.
sourceSource language. In this test, id were detected even though they were not sent.
targetYour requested destination language.
providerThe provider ultimately produces the translation.
attemptsTrial history per provider: name, status, and processing time in milliseconds.

One request is limited to 5,000 characters and 50 items. Larger catalogs need to be split into batches, as in the next step.

Step 3: how to install it in Node.js backend?

Create a function that splits text into batches according to boundaries, then combines the results back together. This example runs on Node.js 18 and above without any additional dependencies.

const BASE = "https://api.apipedia.id/v1";
const headers = {
  Authorization: `Bearer ${process.env.APIPEDIA_KEY}`, // apk_xxx
  "Content-Type": "application/json",
};

// Batas API: 50 item dan 5.000 karakter per request.
function bagiBatch(daftarTeks, maxItem = 50, maxKarakter = 5000) {
  const batches = [];
  let batch = [];
  let jumlah = 0;
  for (const teks of daftarTeks) {
    if (teks.length > maxKarakter) throw new Error("Satu teks melebihi 5.000 karakter");
    if (batch.length === maxItem || jumlah + teks.length > maxKarakter) {
      batches.push(batch);
      batch = [];
      jumlah = 0;
    }
    batch.push(teks);
    jumlah += teks.length;
  }
  if (batch.length) batches.push(batch);
  return batches;
}

export async function terjemahkan(daftarTeks, target = "en", source = "id") {
  const hasil = [];
  for (const batch of bagiBatch(daftarTeks)) {
    const res = await fetch(`${BASE}/translate`, {
      method: "POST",
      headers,
      body: JSON.stringify({ text: batch, target, source }),
    });
    const body = await res.json();
    if (!body.is_success) throw new Error(`HTTP ${res.status}: ${body.message}`);
    hasil.push(...body.data.translatedText); // urutan sama dengan input
  }
  return hasil;
}

// Contoh: terjemahkan tiga field satu produk, lalu simpan sebagai draf.
const produk = {
  nama: "Keripik tempe renyah khas Malang",
  deskripsi: "Digoreng tanpa pengawet, berat bersih 250 gram.",
  pengiriman: "Gratis ongkir untuk pembelian minimal 5 bungkus.",
};
const [nama, deskripsi, pengiriman] = await terjemahkan(Object.values(produk));
console.log({ nama, deskripsi, pengiriman });

Because the results are always in sequence according to the input, you can map translations back to their original fields without additional markers. Save the result in a separate column, for example deskripsi_en, along with a sign that the text is machine generated and has not been checked.

Step 4: how to do the same example in Python?

In Python, send JSON with requests and read translatedText from the response. The pattern is the same as the Node.js version.

import os

import requests  # pip install requests

BASE = "https://api.apipedia.id/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['APIPEDIA_KEY']}"}  # apk_xxx


def bagi_batch(daftar_teks, max_item=50, max_karakter=5000):
    batch, jumlah = [], 0
    for teks in daftar_teks:
        if len(teks) > max_karakter:
            raise ValueError("Satu teks melebihi 5.000 karakter")
        if len(batch) == max_item or jumlah + len(teks) > max_karakter:
            yield batch
            batch, jumlah = [], 0
        batch.append(teks)
        jumlah += len(teks)
    if batch:
        yield batch


def terjemahkan(daftar_teks, target="en", source="id"):
    hasil = []
    for batch in bagi_batch(daftar_teks):
        res = requests.post(
            f"{BASE}/translate",
            headers=HEADERS,
            json={"text": batch, "target": target, "source": source},
            timeout=30,
        )
        body = res.json()
        if not body.get("is_success"):
            raise RuntimeError(f"HTTP {res.status_code}: {body.get('message')}")
        hasil.extend(body["data"]["translatedText"])
    return hasil


if __name__ == "__main__":
    teks = [
        "Keripik tempe renyah khas Malang, digoreng tanpa pengawet.",
        "Berat bersih 250 gram, tahan 3 bulan di suhu ruang.",
    ]
    for asli, inggris in zip(teks, terjemahkan(teks)):
        print(asli, "->", inggris)

When to use AI mode instead of auto mode?

Use AI mode when your text contains markdown, placeholders like {nama}, or requires a specific language style. According to the catalog, this mode preserves formatting, markdown, and placeholder {x}, and accepts settings formality and instructions.

Comparison of two APIPedia Translator API modes. Auto mode: provider google, google-dict, then mymemory; without field models; cached results; suitable for product names, plain descriptions, and simple interface text. ai mode: uses the AI ​​Gateway model of your choice so the model field is mandatory; retains markdown and placeholder {x}; supports formal or informal formalities and instructions up to 300 characters; cuts AI credits, requires AI Gateway scope, and is not cached. Both limits are the same: 5,000 characters and 50 items per request.

To use it, set provider to "ai" and fill model with a model ID of GET /v1/ai/models. The value MODEL_ANDA below is a placeholder, not a real model name.

curl -s -X POST https://api.apipedia.id/v1/translate \
  -H "Authorization: Bearer apk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Halo {nama}, pesanan **#{nomor}** sedang dikemas.",
    "target": "en",
    "provider": "ai",
    "model": "MODEL_ANDA",
    "formality": "formal",
    "instructions": "Pertahankan nama produk dalam bahasa Indonesia."
  }'
MatterAuto modeAI mode
Field modelNo needMust
Format and placeholdersNot guaranteed to be intactMaintained
Language styleCan't be setformality and instructions (max. 300 characters)
CostFollows the usual request quotaCutting AI credits
CacheYesNo

A rule of thumb: start with auto mode for plain text, and move to AI mode only for message templates, marked-down content, or text where tone matters.

What are the limits of this Translator API?

This API produces machine translations, so the results need to be human-checked before appearing on important pages. In our test, "typical Malang tempeh chips" became "Typical Malang crispy tempeh chips": understandable, but not necessarily the word choice you want for a display case.

  • Not for legal or medical documents. Contracts, ingredient labels and health claims still need an authorized translator.
  • Auto mode provider can be changed. Two similar requests can be served by different providers, so the translation style can be slightly different. See field provider.
  • One request has a maximum of 5,000 characters and 50 items. Long descriptions need to be broken down into paragraphs.
  • The list at /translate/languages is a sample of 40 common languages. Other provider-supported BCP-47 codes, for example pt-BR, are also accepted.

What common mistakes should you avoid?

The most common mistake is re-translating the same text every time the page is opened. Translate once when the product is saved, then serve it from the database. Also check the following things.

  • One request per sentence. Send an array to have dozens of texts completed in a single call.
  • Does not fill source for short text. Single words such as variant names can be incorrectly detected. If you know the language, send "source": "id".
  • Sends complete HTML in auto mode. There is no guarantee that the tag will remain intact. Just send the text, or use AI mode for formatted content.
  • Translating brand names and SKU codes. Separate it from the text before sending, then combine it again.
  • Calling from a browser. Key apk_xxx will be read by anyone. Call from backend.
  • Ignoring is_success. If the value is false, read message, do not save empty results to the database.
  • Immediate results. Save as draft and give admin a check button.

Status code that needs to be addressed

StatusMeaningAction
200Translation completeRead translatedText
400Invalid parameter or bodyRead message, which calls the field problematic
401Token is missing, unknown, or expiredCheck header Authorization
403The key has no scope for this endpointChange the key scope on the Token page
429Request limit exceededWait, then repeat with a pause

Frequently asked questions

Is APIPedia's Translator API free?

Translator products are listed in the Free tier in the APIPedia catalog. AI mode is an exception: the cost is deducted from the AI ​​credits according to the model you choose.

What languages ​​are supported?

Endpoint GET /v1/translate/languages returns 40 common languages, including Indonesian, English, Javanese, Sundanese, Malay, Arabic, Japanese, Korean, and Mandarin. Other BCP-47 codes supported by the provider are also accepted.

Can it be translated into Javanese or Sundanese?

Can. Codes jv for Javanese and su for Sundanese are in the language list. The quality of regional language translations is generally below that of major languages, so check the results.

How do I know which provider translated my text?

Read field provider in the response. Field attempts contains the complete history, including failed providers and the length of each attempt in milliseconds.

Are placeholders like {name} safe?

In AI mode, placeholder {x} and markdown are maintained. In auto mode there is no guarantee, so use AI mode for message templates.

Next step: try it on the console

A dual language catalog only needs one function terjemahkan in the backend and one additional column in the product table. Create a key at console.apipedia.id, run the curl example above with your own product description, then install that function in the product save flow.

To equip stores that serve overseas buyers, also read the rupiah exchange rate API to display prices in other currencies and the postage check API to estimate shipping costs. If your AI assistant needs to translate text, follow the guide for connecting APIPedia to Claude via MCP.

Topics:

About the author

Tim APIPedia — Tim Engineering APIPedia

Tim engineering di balik APIPedia yang membangun dan memelihara API data Indonesia - ongkir, OCR KTP, data wilayah, BMKG, hingga server MCP - dan menulis panduan integrasinya dari pengalaman langsung.