translaas 0.5.0b1

A strongly-typed, performant, and modular Python SDK for consuming the Translaas Translation Delivery API

Translaas SDK

A strongly-typed, performant, and modular Python SDK for consuming the Translaas Translation Delivery API. This SDK provides a clean, easy-to-use way to retrieve translations in your Python applications.

Features

• ✅ Strongly-typed API - Full type hints support with IDE autocomplete and type safety
• ✅ Convenience API - Simple t() method for quick translation lookups via TranslaasService
• ✅ Automatic Language Resolution - Optional language parameter with configurable providers (HTTP request, default)
• ✅ Framework Integrations - Flask, FastAPI, Django, and other framework integrations
• ✅ Flexible Caching - Built-in memory caching with configurable cache modes
• ✅ Offline Caching - File-based caching for offline mode with automatic sync
• ✅ Hybrid Caching - Two-level caching (memory L1 + file L2) for optimal performance
• ✅ Multi-Environment Support - Works in Python 3.8+, CPython, PyPy, and modern Python runtimes
• ✅ Configurable timeouts - HTTP client timeout via TranslaasOptions
• ✅ Single installable package - All modules ship in the translaas PyPI package
• ✅ Async/Await - Fully asynchronous API for optimal performance
• ✅ Type Hints - Native Python type hints with full IDE support

Installation

pip

pip install translaas

pip with virtual environment (Recommended)

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install translaas

Quick Start

1. Install Package

pip install translaas

2. Create Client

Option A: Using TranslaasService (Recommended for simple lookups)

from translaas import TranslaasService, TranslaasOptions, CacheMode, LanguageCodes

options = TranslaasOptions(
    api_key='your-api-key-here',
    base_url='https://api.translaas.com',  # or your custom base URL
    cache_mode=CacheMode.GROUP,  # Optional: configure caching
)

translaas = TranslaasService(options)

# Use the convenient t() method
# lang parameter is optional when language providers are configured
welcome = await translaas.t('common', 'welcome', LanguageCodes.ENGLISH)

# Automatic language resolution (requires providers configured)
welcome_auto = await translaas.t('common', 'welcome')  # lang omitted

# With pluralization
items = await translaas.t('messages', 'item', LanguageCodes.ENGLISH, 5)

# With pluralization and interpolation parameters
items = await translaas.t('messages', 'item', LanguageCodes.ENGLISH, 5, {'name': 'John'})

Option B: Using TranslaasClient (Full API access)

from translaas import TranslaasClient, TranslaasOptions

options = TranslaasOptions(
    api_key='your-api-key-here',
    base_url='https://api.translaas.com',
)

client = TranslaasClient(options)

# Get a single translation entry
translation = await client.get_entry('common', 'welcome', 'en')

Configuration

Basic Configuration

from translaas import TranslaasService, TranslaasOptions, LanguageCodes

options = TranslaasOptions(
    # Required: API key and base URL
    api_key='your-api-key',
    base_url='https://api.translaas.com',
)

translaas = TranslaasService(options)

Advanced Configuration

from translaas import TranslaasService, TranslaasOptions, CacheMode, LanguageCodes

options = TranslaasOptions(
    # Required: API key and base URL
    api_key='your-api-key',
    base_url='https://api.translaas.com',

    # Optional: Default language fallback
    default_language=LanguageCodes.ENGLISH,

    # Optional: Caching configuration
    cache_mode=CacheMode.GROUP,
    cache_absolute_expiration=3600.0,  # 1 hour in seconds
    cache_sliding_expiration=900.0,  # 15 minutes in seconds

    # Optional: HTTP Client timeout
    timeout=30.0,  # 30 seconds
)

translaas = TranslaasService(options)

Configuration Options:

Option	Required	Description
api_key	✅ Required	Your Translaas API key
base_url	✅ Required	API origin (e.g. https://api.translaas.com). May include /sdk/v1; it is stripped automatically.
default_project	⚪ Optional	Default project query for text calls and offline get_entry when using a multi-project key
channel	⚪ Optional	SDK snapshot channel query (channel)
snapshot_version	⚪ Optional	SDK snapshot version query (v)
include_context	⚪ Optional	Adds includeContext on project/group/offline-cache requests
use_conditional_requests	⚪ Optional	Send If-None-Match and handle 304 Not Modified when caching is enabled
offline_cache	⚪ Optional	OfflineCacheOptions for file-based offline mode (see below)
default_language	⚪ Optional	Default language code fallback (e.g., LanguageCodes.ENGLISH)
cache_mode	⚪ Optional	Caching mode (CacheMode.NONE, CacheMode.ENTRY, CacheMode.GROUP, CacheMode.PROJECT)
cache_absolute_expiration	⚪ Optional	Absolute cache expiration time (seconds)
cache_sliding_expiration	⚪ Optional	Sliding cache expiration time (seconds)
timeout	⚪ Optional	HTTP client timeout (seconds)

Configuration from Environment Variables

# .env file
TRANSLAAS_API_KEY=your-api-key
TRANSLAAS_BASE_URL=https://api.translaas.com
TRANSLAAS_CACHE_MODE=GROUP
TRANSLAAS_DEFAULT_LANGUAGE=en

import os
from translaas import TranslaasService, TranslaasOptions, CacheMode

options = TranslaasOptions(
    api_key=os.getenv('TRANSLAAS_API_KEY'),
    base_url=os.getenv('TRANSLAAS_BASE_URL', 'https://api.translaas.com'),
    cache_mode=CacheMode[os.getenv('TRANSLAAS_CACHE_MODE', 'NONE')],
    default_language=os.getenv('TRANSLAAS_DEFAULT_LANGUAGE'),
)

translaas = TranslaasService(options)

Note: api_key should be stored in environment variables or secure configuration, not in source code.

Framework integrations (Flask, Django, from_env) also accept TRANSLAAS_DEFAULT_PROJECT, TRANSLAAS_CHANNEL, TRANSLAAS_SNAPSHOT_VERSION, TRANSLAAS_INCLUDE_CONTEXT, TRANSLAAS_USE_CONDITIONAL_REQUESTS, and offline settings (TRANSLAAS_OFFLINE_CACHE_ENABLED, TRANSLAAS_OFFLINE_CACHE_DIRECTORY, TRANSLAAS_OFFLINE_FALLBACK_MODE, etc.). See translaas.extensions.config.

Offline mode

When offline_cache.enabled is True, TranslaasService wraps the HTTP client with CachingTranslaasClient and reads/writes the on-disk layout from the HTTP spec (§7.6): manifest.json, {project}/locales.json, {project}/{lang}/project.json.

from translaas import TranslaasOptions, TranslaasService
from translaas.models.enums import OfflineFallbackMode
from translaas.models.options import OfflineCacheOptions

options = TranslaasOptions(
    api_key="your-api-key",
    base_url="https://api.translaas.com",
    default_project="my-project",
    offline_cache=OfflineCacheOptions(
        enabled=True,
        cache_directory=".translaas-cache",
        fallback_mode=OfflineFallbackMode.CACHE_FIRST,
        default_project_id="my-project",
    ),
)

async with TranslaasService(options) as service:
    text = await service.t("common", "welcome", "en")

Use OfflineCacheSyncService to populate the cache from the API or an offline ZIP bundle (parse_offline_zip).

.NET SDK parity

The Python SDK aligns with the .NET Translaas.SDK as the cross-language contract:

Area	Online (TranslaasClient / t())	Offline (CachingTranslaasClient)
Plural selection	Server resolves via n / N query params	One/other only (1 → one, else other; language ignored)
Parameter substitution	Server resolves when using TranslaasClient.get_entry(); TranslaasService.t() applies client-side {name} / {{name}} after fetch	{name} placeholders only; case-insensitive keys; auto-N from number unless explicit N is provided
t() overloads	t(group, entry, lang, number, parameters) and auto-language variants	Same service API; offline cache path uses .NET-aligned helpers

TranslaasService.t() sends number to the API for plural resolution and performs parameter replacement client-side (matching .NET ITranslaasService.T). Offline cache reads use determine_plural_category and substitute_parameters from translaas.i18n.offline_helpers.

Usage Examples

Get Single Translation Entry

Using TranslaasService (Convenience API):

from translaas import LanguageCodes

# Basic usage with explicit language
translation = await translaas.t('ui', 'button.save', LanguageCodes.ENGLISH)

# Automatic language resolution (requires providers configured)
translation = await translaas.t('ui', 'button.save')  # lang omitted

# With pluralization
message = await translaas.t('messages', 'item.count', LanguageCodes.ENGLISH, 5)

# With pluralization and parameters
message = await translaas.t('messages', 'item.count', LanguageCodes.ENGLISH, 5, {'name': 'John'})

Using TranslaasClient (Full API):

from translaas import LanguageCodes

# Basic usage
translation = await client.get_entry('ui', 'button.save', LanguageCodes.ENGLISH)

# With pluralization
message = await client.get_entry(
    'messages',
    'item.count',
    LanguageCodes.ENGLISH,
    5  # Used for pluralization rules
)

Environment Compatibility

The SDK supports multiple Python environments:

Environment	Compatible With
CPython	Python 3.8+
PyPy	PyPy 3.8+
AsyncIO	Full async/await support

The SDK uses httpx for async HTTP requests and requests for synchronous requests.

Error Handling

from translaas import TranslaasApiException, LanguageCodes

try:
    translation = await client.get_entry('group', 'entry', LanguageCodes.ENGLISH)
except TranslaasApiException as e:
    # Handle Translaas-specific errors
    print(f"Error: {e.message}")
    print(f"Status Code: {e.status_code}")
except Exception as e:
    # Handle other errors
    print(f"Error: {str(e)}")

Development

Building from Source

git clone https://github.com/acuencadev/translaas-sdk-python.git
cd translaas-sdk-python
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e ".[dev]"
python -m build

Running Tests

pytest

Running Tests with Coverage

pytest --cov=translaas --cov-report=html

API Endpoints

The SDK communicates with the Translaas HTTP API (OpenAPI-aligned paths). base_url should be the API origin only (for example https://api.translaas.com).

Endpoint	Method	Purpose
/sdk/v1/translations/text	GET	Get single translation entry
/sdk/v1/translations/group	GET	Get all translations for a group
/sdk/v1/translations/project	GET	Get all translations for a project
/sdk/v1/translations/locales	GET	Get available locales for a project
/sdk/v1/translations/report-missing	POST	Report missing keys (project-scoped API key)
/sdk/v1/translations/offline-cache	GET	Download offline translation ZIP bundle
/api/v1/api-keys/validate	GET	Validate API key (connectivity / bootstrap)

Note: Translation endpoints use GET with query parameters except report-missing (JSON body). Optional query flags include channel, v, and includeContext where the backend supports them; configure via TranslaasOptions or per-call arguments on the client.

Authentication

The SDK uses API key authentication via the X-Api-Key header. Provide your API key during client creation:

options = TranslaasOptions(
    api_key='your-api-key-here',
    base_url='https://api.translaas.com',
)

Examples

In the translaas-all meta-repo, Python samples live under examples/python/ (mirroring the JavaScript samples under examples/js/).

Offline — Node-style console sample

CacheOnly demo using CachingTranslaasClient and a pre-seeded file cache (no live API calls):

cd examples/python/offline-node
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
python main.py

Optional: copy .env.example to .env when extending the sample to call the live API for cache sync.

Additional framework examples (basic, flask, fastapi, django) may exist locally but are not tracked in the SDK repository (see .gitignore).

License

This project is licensed under the MIT License - see the LICENSE file for details.

Copyright (c) 2025 Translaas SDK Contributors

Support

• Documentation: [Link to full documentation]
• Issues: [https://github.com/acuencadev/translaas-sdk-python/issues]
• API Reference: [Swagger/API Docs URL]

Contributing

We welcome contributions to the Translaas SDK! Please read our Contributing Guidelines for details on:

• How to get started
• Development guidelines and code style
• Pull request process
• Commit message conventions
• Reporting issues

For more information, see CONTRIBUTING.md.

---

Made with ❤️ for the Python community