Skip to main content

Translation API for Python

This guide shows you how to use the Langbly translation API in Python. Langbly is a Google Translate v2 compatible API with context-aware translation quality, 81–90% cheaper than Google Translate.

Installation​

pip install langbly

Quick Start​

from langbly import Langbly

client = Langbly(api_key="your-api-key-here")

result = client.translate(
    q="Hello, how are you?",
    target="nl"
)

print(result.translated_text)
# Output: "Hallo, hoe gaat het met je?"

Get Your API Key​

  1. Sign up at langbly.com/signup (free, no credit card)
  2. Create an API key in your dashboard
  3. Free tier includes 500K characters/month

Translate Text​

Basic Translation​

from langbly import Langbly

client = Langbly(api_key="your-api-key-here")

# English to Dutch
result = client.translate(q="Good morning!", target="nl")
print(result.translated_text)  # "Goedemorgen!"

# English to German
result = client.translate(q="Good morning!", target="de")
print(result.translated_text)  # "Guten Morgen!"

With Source Language​

By default, Langbly auto-detects the source language. You can specify it explicitly:

result = client.translate(
    q="Bonjour le monde",
    target="en",
    source="fr"
)
print(result.translated_text)  # "Hello world"

HTML Translation​

Translate HTML content while preserving tags:

result = client.translate(
    q="<p>Welcome to our <strong>website</strong></p>",
    target="nl",
    format="html"
)
print(result.translated_text)
# "<p>Welkom op onze <strong>website</strong></p>"

Batch Translation​

Translate multiple strings in a single API call:

results = client.translate(
    q=["Hello", "Goodbye", "Thank you"],
    target="nl"
)

for r in results:
    print(r.translated_text)
# "Hallo"
# "Tot ziens"
# "Dank je"

Error Handling​

The SDK provides typed exceptions:

from langbly import Langbly, AuthenticationError, RateLimitError

client = Langbly(api_key="your-api-key-here")

try:
    result = client.translate(q="Hello", target="nl")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")
except Exception as e:
    print(f"Error: {e}")

Auto-Retry​

The SDK automatically retries on 429 (rate limit) and 5xx (server error) responses with exponential backoff:

# Retries are enabled by default
client = Langbly(
    api_key="your-api-key-here",
    max_retries=3,  # default
)

Translate Files​

Translate a JSON i18n File​

import json
from langbly import Langbly

client = Langbly(api_key="your-api-key-here")

# Load source file
with open("en.json") as f:
    source = json.load(f)

# Translate all values
translated = {}
keys = list(source.keys())
values = list(source.values())

results = client.translate(q=values, target="nl")
for key, result in zip(keys, results):
    translated[key] = result.translated_text

# Save translated file
with open("nl.json", "w") as f:
    json.dump(translated, f, ensure_ascii=False, indent=2)

Translate a CSV File​

import csv
from langbly import Langbly

client = Langbly(api_key="your-api-key-here")

with open("products.csv") as f:
    reader = csv.DictReader(f)
    rows = list(reader)

# Translate product names
names = [row["name"] for row in rows]
results = client.translate(q=names, target="nl")

for row, result in zip(rows, results):
    row["name_nl"] = result.translated_text

# Write output
with open("products_nl.csv", "w", newline="") as f:
    writer = csv.DictWriter(f, fieldnames=rows[0].keys())
    writer.writeheader()
    writer.writerows(rows)

Environment Variables​

Instead of passing the API key directly, use an environment variable:

export LANGBLY_API_KEY=your-api-key-here
from langbly import Langbly

# Automatically reads LANGBLY_API_KEY from environment
client = Langbly()

Google Translate Migration​

If you're migrating from Google Translate, the Langbly API is compatible:

# Before (Google Translate)
# from google.cloud import translate_v2 as translate
# client = translate.Client()
# result = client.translate("Hello", target_language="nl")

# After (Langbly)
from langbly import Langbly
client = Langbly(api_key="your-key")
result = client.translate(q="Hello", target="nl")
print(result.translated_text)

Next Steps​