AutoLocalise Python SDK
A framework-agnostic Python SDK for the AutoLocalise translation service. Works seamlessly with Django, Flask, FastAPI, or any Python backend.
Features
- Framework-agnostic — Works with any Python web framework
- Intelligent caching — In-memory cache with thread-safe operations
- Template support — Built-in Python Template support with parameter protection
- Batch translation — Efficient bulk translation support
- Smart API usage — Only translates new strings, reuses existing translations
- Error handling — Graceful fallbacks when translation fails
Installation
pip install autolocalise
Quick Start
from autolocalise import Translator
# Initialize translator
translator = Translator(api_key="your-api-key", source_locale="en", target_locale="fr")
# Simple translation
result = translator.translate(["Hello", "Goodbye"])
print(result)
# {"Hello": "Bonjour", "Goodbye": "Au revoir"}
# Template with parameters
from string import Template
template = Template("Hello $name, you have $count new messages!")
translated = translator.translate_template(template, name="Alice", count=5)
print(translated)
# "Bonjour Alice, vous avez 5 nouveaux messages!"
Core Usage
Basic Translation
from autolocalise import Translator
translator = Translator(
api_key="your-api-key",
source_locale="en",
target_locale="fr"
)
# Single or multiple texts
texts = ["Welcome", "Login", "Submit"]
translations = translator(texts)
Template Translation with Parameters
The SDK supports Python's string.Template with automatic parameter protection:
from string import Template
from autolocalise import Translator
translator = Translator(api_key="your-api-key", source_locale="en", target_locale="fr")
# Create template
template = Template("Welcome $name! You have $count items in your $container.")
# Translate with parameters - parameters are protected from translation
result = translator.translate_template(template, name="John", count=3, container="cart")
print(result)
# "Bienvenue John! Vous avez 3 articles dans votre cart."
Environment Configuration
import os
from autolocalise import Translator
translator = Translator(
api_key=os.getenv("AUTOLOCALISE_API_KEY"),
source_locale=os.getenv("AUTOLOCALISE_SOURCE_LANG", "en"),
target_locale=os.getenv("AUTOLOCALISE_TARGET_LANG", "fr")
)
Framework Examples
Django
# utils.py
from django.conf import settings
from autolocalise import Translator
from string import Template
translator = Translator(
api_key=settings.AUTOLOCALISE_API_KEY,
source_locale="en",
target_locale="fr"
)
def translate_message(template_str, **params):
template = Template(template_str)
return translator.translate_template(template, **params)
# views.py
def dashboard_view(request):
message = translate_message(
"Hello $name, you have $count notifications!",
name=request.user.first_name,
count=request.user.notifications.unread().count()
)
return render(request, 'dashboard.html', {'message': message})
Flask
from flask import Flask
from autolocalise import Translator
from string import Template
app = Flask(__name__)
translator = Translator(api_key=app.config['AUTOLOCALISE_API_KEY'], source_locale="en", target_locale="fr")
@app.route('/user/<username>')
def user_profile(username):
template = Template("Welcome back, $name!")
message = translator.translate_template(template, name=username)
return f"<h1>{message}</h1>"
FastAPI
from fastapi import FastAPI
from autolocalise import Translator
from string import Template
app = FastAPI()
translator = Translator(api_key="your-api-key", source_locale="en", target_locale="fr")
@app.get("/welcome/{user_name}")
async def welcome_user(user_name: str):
template = Template("Welcome $name! Enjoy using our API.")
message = translator.translate_template(template, name=user_name)
return {"message": message}
API Reference
Translator Class
__init__(api_key, source_locale, target_locale)
Initialize a new translator instance.
Parameters:
api_key(str): Your AutoLocalise API keysource_locale(str): Source language code (e.g., "en")target_locale(str): Target language code (e.g., "fr")
Raises:
ConfigurationError: If required parameters are missing
translate(texts, target_locale=None, source_locale=None)
Translate multiple strings.
Parameters:
texts(List[str]): List of strings to translatetarget_locale(str, optional): Target language code (overrides instance default)source_locale(str, optional): Source language code (overrides instance default)
Returns: Dict[str, str] - Dictionary mapping original text to translated text
Behavior:
- Non-string values are silently skipped
- Empty strings are returned as-is
Raises:
ValueError: If any text exceeds 10,000 characters
Example:
# Valid strings
result = translator.translate(["Hello", "World"])
# Returns: {"Hello": "Bonjour", "World": "Monde"}
# Mixed valid and invalid inputs
result = translator.translate(["Hello", 123, ""])
# Returns: {"Hello": "Bonjour", "": ""}
# Note: 123 is skipped (not a string)
# Text too long
translator.translate(["a" * 10001]) # Raises: ValueError
translate_template(template, **params)
Translate a Python Template with parameter protection.
Parameters:
template(Template): Python string.Template object**params: Template parameters (protected from translation)
Returns: str - Translated text with parameters substituted
Cache Management
# Check cache size
translator.cache_size()
# Clear cache
translator.clear_cache()
# Clear global cache
Translator.clear_global_cache()
How Parameter Protection Works
When using translate_template():
- Parameter Extraction: Parameters are temporarily replaced with short placeholders like
X1X,X2X - Translation: Only the template text with placeholders is sent for translation
- Parameter Restoration: Original parameter values are substituted back
- Result: Translated text with original parameter values intact
Cost Optimization: Short placeholders minimize translation API costs while ensuring parameters like usernames, numbers, and dynamic content are never accidentally translated.
Example: "Hello $name!" → "Hello X1X!" (sent to API) → "Bonjour John!" (final result)
Development
git clone https://github.com/AutoLocalise/autolocalise-py.git
cd autolocalise-py
pip install -e ".[dev]"
pytest
License
MIT License - see LICENSE file for details.
Support
For support, please contact at https://www.autolocalise.com/support
Metadata
Release files for autolocalise 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| autolocalise-0.2.0.tar.gz | 17.9 kB | Without provenance | Details for autolocalise-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| autolocalise-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for autolocalise-0.2.0-py3-none-any.whl |
Total release size: 36.1 kB
Release files / autolocalise-0.2.0.tar.gz
| Download URL | autolocalise-0.2.0.tar.gz |
|---|---|
| Size | 17.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e1c9a758d5688149f608b67c71cbc9d8cc9f9bffbe5a37c42038d4c6fb1f6461
|
|
BLAKE2b-256 checksum How to use checksums |
36cced6c098c7d05635724466abf5d74acadbcd61096d72fe83176361586f742
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Release files / autolocalise-0.2.0-py3-none-any.whl
| Download URL | autolocalise-0.2.0-py3-none-any.whl |
|---|---|
| Size | 18.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d68abadecf9060ef807cc715c4f5bd2db68ba7a92aad5befca869df62273b3c9
|
|
BLAKE2b-256 checksum How to use checksums |
ec9b9e486efabb060130b597fe462e3c6cffb7dfc81468f4f1a0a75074689fdf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Security for autolocalise 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.