Can I translate non-website content on Bablic?

Overview:

On Bablic, you will have access to the Bablic Translation API. The Bablic Translation API translates content outside your website: product feeds, JSON from your backend, transactional emails, documents and more. You send content to one endpoint, and Bablic returns it translated with the same structure.

Base URL

https://edge.bablic.com/xapis/TX

Before you begin

You need three things to use the API:

Try it with the demo credentials

You can test every example in this article with these demo credentials:

Authentication

Send your API token with every request in the X-TX_Token  header:

X-TX_Token: API-demo

Form-encoded requests can send the token as a tx_token  field in the request body instead (see Form-encoded requests below).

If the token is missing or doesn't match your project, the API returns 403 Forbidden .

Choose a content type

The Content-Type  header tells Bablic how to read your request body. Most formats return the translation immediately. HTML runs as an asynchronous batch job.

Translate plain text

Endpoint: POST /xapis/TX/{translation_key}

curl --request POST \
  --url https://edge.bablic.com/xapis/TX/97BB-3CE8-1CD2-FE93 \
  --header 'Content-Type: text/plain' \
  --header 'X-TX_Token: API-demo' \
  --data 'Maitake Cellular Support - 120 Vegetarian Capsules'

Response (demo key):

Måïțåķëǿ C룣ȗŁåȑǿ Sȗƥƥǿȑțǿ - 120 Vëģëțåȑïåǹåŷ CåƥșȗŁëșǿ

Plain text is translated exactly as sent. To translate content that contains HTML markup, use HTML translation instead.

Translate JSON

Endpoint: POST /xapis/TX/{translation_key}

Bablic keeps your JSON structure intact and translates only the values you choose. By default, nothing in a JSON payload is translated. You can choose which values to translate in two ways.

Option 1: Ask Bablic to translate specific keys

Bablic Support can add a rule to your project that lists the JSON keys to translate. For example, a rule for product_desc  looks like this in your project configuration:

"tx_api_rules": {
  "translate": [ { "T": "product_desc" } ]
}

This rule lives in your project settings, so you don't send it with your requests. The demo project already has this rule.

curl --request POST \
  --url https://edge.bablic.com/xapis/TX/97BB-3CE8-1CD2-FE93 \
  --header 'Content-Type: application/json' \
  --header 'X-TX_Token: API-demo' \
  --data '{"product_desc": "Maitake Cellular Support - 120 Vegetarian Capsules", "product_sku": "FJFOFOOSO1231213"}'

Response (demo key):

{
  "product_desc": "Måïțåķëǿ C룣ȗŁåȑǿ Sȗƥƥǿȑțǿ - 120 Vëģëțåȑïåǹåŷ CåƥșȗŁëșǿ",
  "product_sku": "FJFOFOOSO1231213"
}

Only product_desc  is translated. The SKU comes back unchanged.

Option 2: Mark keys in your own JSON

If you control the JSON, you can mark values directly in the key names, with no project configuration needed:

curl --request POST \
  --url https://edge.bablic.com/xapis/TX/97BB-3CE8-1CD2-FE93 \
  --header 'Content-Type: application/json' \
  --header 'X-TX_Token: API-demo' \
  --data '{"product_OneLinkTx": "Maitake Cellular Support - 120 Vegetarian Capsules", "product_sku": "FJFOFOOSO1231213"}'

Response (demo key):

{
  "product_OneLinkTx": "Måïțåķëǿ C룣ȗŁåȑǿ Sȗƥƥǿȑțǿ - 120 Vëģëțåȑïåǹåŷ CåƥșȗŁëșǿ",
  "product_sku": "FJFOFOOSO1231213"
}

Key names are returned exactly as you sent them, so your code can read the results with the same keys.

Translate XML and RSS

Endpoint: POST /xapis/TX/{translation_key}

Send any valid XML document. Bablic keeps the structure and the XML declaration, and translates text inside the elements.

curl --request POST \
  --url https://edge.bablic.com/xapis/TX/97BB-3CE8-1CD2-FE93 \
  --header 'Content-Type: application/xml' \
  --header 'X-TX_Token: API-demo' \
  --data '<?xml version="1.0" encoding="UTF-8"?><rss version="2.0"><channel><item><title>Maitake Cellular Support - 120 Vegetarian Capsules</title></item></channel></rss>'

Response (demo key):

<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0">
  <channel>
    <item>
      <title>Måïțåķëǿ C룣ȗŁåȑǿ Sȗƥƥǿȑțǿ - 120 Vëģëțåȑïåǹåŷ CåƥșȗŁëșǿ</title>
    </item>
  </channel>
</rss>

Important: By default, Bablic translates the text in every element, including elements that hold URLs, IDs or SKUs (such as <link>  or <guid> ). If your XML includes values that must stay unchanged, contact Bablic Support to set up rules for the elements to skip before you go live.

Translate CSV and other delimited files

Endpoint: POST /xapis/TX/{translation_key}

Send the file contents as the request body with the matching content type:

curl --request POST \
  --url https://edge.bablic.com/xapis/TX/97BB-3CE8-1CD2-FE93 \
  --header 'Content-Type: text/csv' \
  --header 'X-TX_Token: API-demo' \
  --data-binary @products.csv

A pipe-delimited file uses the separator  parameter:

curl --request POST \
  --url 'https://edge.bablic.com/xapis/TX/97BB-3CE8-1CD2-FE93?separator=|' \
  --header 'Content-Type: text/asv' \
  --header 'X-TX_Token: API-demo' \
  --data-binary @products.txt

Form-encoded requests

Endpoint: POST /xapis/TX/{translation_key}

Use form encoding when it's easier to send content and settings as form fields, for example from an HTML form or a tool that can't set custom headers. Set Content-Type: application/x-www-form-urlencoded  and send these fields:

curl --request POST \
  --url https://edge.bablic.com/xapis/TX/97BB-3CE8-1CD2-FE93 \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'tx_token=API-demo' \
  --data-urlencode 'tx_mimetype=text/plain' \
  --data-urlencode 'tx_content=Maitake Cellular Support - 120 Vegetarian Capsules'

Response (demo key):

Måïțåķëǿ C룣ȗŁåȑǿ Sȗƥƥǿȑțǿ - 120 Vëģëțåȑïåǹåŷ CåƥșȗŁëșǿ

The response uses the content type you set in tx_mimetype .

Translate HTML (batch sessions)

HTML translation renders each page the way a browser would, so it takes longer than the other formats and runs as a batch job.

Don't use HTML translation for real-time requests. It's built for translating pages, templates and emails ahead of time.Each HTML file must be complete and well-formed. Invalid HTML isn't supported.

A batch works in four steps:

1. Create a session.
2. Add your HTML files, once for each target language.
3. End the session (optional).
4. Download the translated files as a ZIP.

Step 1: Create a session

Endpoint: POST /xapis/TX/{project_key}?create_session=1

Use your project key, including the leading P .

curl --request POST \
  --url 'https://edge.bablic.com/xapis/TX/P6560-5B89-3A89-08DE?create_session=1' \
  --header 'Content-Type: text/html' \
  --header 'X-TX_Token: API-demo'

Response:

{
  "message": "created.",
  "session_id": "session-XXXX-XXXX-XXXX-XXXX"
}

Save the session_id . You'll use it in every following step.

Step 2: Add HTML files

Endpoint: POST /xapis/TX/{translation_key}/{filename}?session_id={session_id}

Send one request for each file and each target language. Use the translation key of the language you want, and give each file a name. Within a session, each filename must be unique for each translation key. You can reuse the same filename across different languages.

curl --request POST \
  --url 'https://edge.bablic.com/xapis/TX/97BB-3CE8-1CD2-FE93/order-confirmation.html?session_id=session-XXXX-XXXX-XXXX-XXXX' \
  --header 'Content-Type: text/html' \
  --header 'X-TX_Token: API-demo' \
  --data-binary @order-confirmation.html

You can add as many files as you need. If the same content appears more than once in a session, Bablic reuses the translation it already has.

The API returns 400 Bad Request  if:

• The filename or session_id  is missing
• The session is already completed
• The filename is already used for this translation key in this session

Step 3: End the session (optional)

Endpoint: PUT /xapis/TX/{project_key}?end_session={session_id}

Ending a session tells Bablic you've finished adding files. You can skip this step, because a session also completes once every queued file is translated.

curl --request PUT \
  --url 'https://edge.bablic.com/xapis/TX/P6560-5B89-3A89-08DE?end_session=session-XXXX-XXXX-XXXX-XXXX' \
  --header 'X-TX_Token: API-demo'

Step 4: Download the results

Endpoint: GET /xapis/TX?session_id={session_id}

curl --request GET \
  --url 'https://edge.bablic.com/xapis/TX?session_id=session-XXXX-XXXX-XXXX-XXXX' \
  --header 'X-TX_Token: API-demo' \
  --output translations.zip

While files are still being translated, you get a JSON progress message. Wait and try again.

{
  "message": "completed 3 of 10"
}

When everything is translated, you get a ZIP file named after the session (Content-Type: application/zip ). Inside, translated files are grouped in a folder for each translation key:

session-XXXX-XXXX-XXXX-XXXX.zip
├── 97BB-3CE8-1CD2-FE93/
│   └── order-confirmation.html
└── {another-translation-key}/
    └── order-confirmation.html

Once the ZIP is delivered, the session is marked as completed and you can't add more files to it. Save the ZIP when you receive it, and start a new session for your next batch.

Delete a session

Endpoint: DELETE /xapis/TX/{project_key}?session_id={session_id}

Deleting a session cancels any queued files and removes all of the session's data, including finished translations.

curl --request DELETE \
  --url 'https://edge.bablic.com/xapis/TX/P6560-5B89-3A89-08DE?session_id=session-XXXX-XXXX-XXXX-XXXX' \
  --header 'X-TX_Token: API-demo'

Errors

Quick reference

Need help?

Contact Bablic Support at support@bablic.com to set up keys, add translation rules for JSON, XML or CSV, or troubleshoot a request.