lingva — Python SDK

Python client for the Lingva localization platform.

Requires Python 3.11+.

This is a preview package. It follows the same conformance contract as the Swift, Kotlin, and Flutter SDKs but is not yet published to PyPI.

Install

# From the monorepo root (editable install)
pip install -e sdks/python

# With async HTTP support (httpx)
pip install -e "sdks/python[http]"

Once published:

pip install lingva-sdk
pip install "lingva-sdk[http]"   # adds httpx for async delivery

Quickstart

Load from a local bundle file

from lingva import LingvaClient

client = LingvaClient.from_file(".lingva/translations/en.bundle.json")

print(client.t("actions.continue"))           # Continue
print(client.t("welcome.title", name="Alice")) # Welcome, Alice.

Load from CDN (async)

import asyncio
from lingva import LingvaClient, LingvaDeliveryTarget

target = LingvaDeliveryTarget(
    base_url="https://api.lingva.dev",
    project_id="my-project",
    environment="production",
)

async def main():
    client = await LingvaClient.from_url(target, locale="fr", fallback_locale="en")
    print(client.t("welcome.title", name="Alice"))

asyncio.run(main())

Load from CDN (synchronous)

from lingva import LingvaClient, LingvaDeliveryTarget

target = LingvaDeliveryTarget(
    base_url="https://api.lingva.dev",
    project_id="my-project",
    environment="production",
)

client = LingvaClient.from_url_sync(target, locale="fr", fallback_locale="en")
print(client.t("welcome.title", name="Alice"))

API

LingvaClient

LingvaDeliveryTarget

LingvaDeliveryTarget(
    base_url="https://api.lingva.dev",
    project_id="my-project",
    environment="production",          # default
    uri_template="...",                # optional custom path template
)
target.resolve("fr")
# -> "https://api.lingva.dev/bundles/my-project/production/latest/fr.bundle.json"

Bundle schema

The SDK reads schemaVersion 1 bundles. Variables use {varname} syntax. Unknown variables pass through unchanged.

{
  "schemaVersion": 1,
  "locale": "en",
  "fallbackLocale": "en",
  "fallbackKeys": [],
  "messages": {
    "actions.continue": "Continue",
    "welcome.title": "Welcome, {name}."
  }
}