Python SDK - Lingo.dev SDK

Einführung

Das Lingo.dev Python SDK übersetzt Text, JSON-Objekte und Chat-Konversationen über eine asynchrone API. Es verarbeitet große Datenmengen, indem es Inhalte automatisch in optimale Batch-Größen aufteilt, verfolgt den Fortschritt für langwierige Übersetzungen und unterstützt Glossare für konsistente Terminologie.

Installation

pip

pip install lingodotdev

uv

uv add lingodotdev

Schnellübersetzung

Überspringen Sie den Context Manager für einmalige Übersetzungen. Diese Methoden verwalten den Engine-Lebenszyklus automatisch und verwenden standardmäßig den Fast-Modus, was sie ideal für CLI-Tools und Skripte macht.

# /// script
# requires-python = ">=3.11"
# dependencies = [
#     "lingodotdev==1.3.0",
# ]
# ///

import asyncio
import os
from lingodotdev.engine import LingoDotDevEngine

async def main():
    api_key = os.environ["LINGODOTDEV_API_KEY"]

    # Translate text
    text_result = await LingoDotDevEngine.quick_translate(
        "Hello world",
        api_key=api_key,
        source_locale="en",
        target_locale="es"
    )
    print(f"Text: {text_result}")

    # Translate object
    object_result = await LingoDotDevEngine.quick_translate(
        {"greeting": "Hello", "farewell": "Goodbye"},
        api_key=api_key,
        source_locale="en",
        target_locale="fr"
    )
    print(f"Object: {object_result}")

asyncio.run(main())

Grundlegende Verwendung

Das SDK benötigt einen API-Schlüssel von Lingo.dev und verwendet asynchrone Context Manager.

# /// script
# requires-python = ">=3.11"
# dependencies = [
#     "lingodotdev==1.3.0",
# ]
# ///

import asyncio
import os
from lingodotdev import LingoDotDevEngine

async def main():
    api_key = os.environ["LINGODOTDEV_API_KEY"]
    async with LingoDotDevEngine({"api_key": api_key}) as engine:
        result = await engine.localize_text(
            "Welcome! We missed you.",
            {"source_locale": "en", "target_locale": "es"}
        )
        print(result)

asyncio.run(main())

Textübersetzung mit Fortschrittsanzeige

Verfolgen Sie den Übersetzungsfortschritt mit einem Callback. Selbst einzelne Textstrings durchlaufen den Chunker, was Fortschrittsberichte für lange Texte ermöglicht und ein konsistentes Verhalten über alle Inhaltstypen hinweg bietet.

# /// script
# requires-python = ">=3.11"
# dependencies = [
#     "lingodotdev==1.3.0",
# ]
# ///

import asyncio
import os
from lingodotdev import LingoDotDevEngine

def on_progress(percent: int):
    print(f"Progress: {percent}%")

async def main():
    api_key = os.environ["LINGODOTDEV_API_KEY"]
    async with LingoDotDevEngine({"api_key": api_key}) as engine:
        result = await engine.localize_text(
            "We sent a confirmation email.",
            {"source_locale": "en", "target_locale": "es"},
            progress_callback=on_progress
        )
        print(f"Result: {result}")

asyncio.run(main())

Objektübersetzung

Übersetzen Sie verschachtelte Dictionaries unter Beibehaltung der Struktur. Das SDK verarbeitet rekursiv alle String-Werte unabhängig von der Verschachtelungstiefe.

# /// script
# requires-python = ">=3.11"
# dependencies = [
#     "lingodotdev==1.3.0",
# ]
# ///

import asyncio
import os
from lingodotdev import LingoDotDevEngine

async def main():
    content = {
        "title": "Welcome",
        "cta": "Start your free trial",
        "footer": {
            "legal": "All rights reserved.",
            "help": "Need help?"
        }
    }

    api_key = os.environ["LINGODOTDEV_API_KEY"]
    async with LingoDotDevEngine({"api_key": api_key}) as engine:
        result = await engine.localize_object(
            content,
            {"source_locale": "en", "target_locale": "es"}
        )
        print(result)

asyncio.run(main())

Batch-Übersetzung in mehrere Sprachen

Übersetzen Sie Inhalte in mehrere Zielsprachen mit einem einzigen Aufruf. Gibt eine Liste mit einem Ergebnis pro Ziel-Locale zurück, in der gleichen Reihenfolge wie angefordert.

# /// script
# requires-python = ">=3.11"
# dependencies = [
#     "lingodotdev==1.3.0",
# ]
# ///

import asyncio
import os
from lingodotdev import LingoDotDevEngine

async def main():
    api_key = os.environ["LINGODOTDEV_API_KEY"]
    async with LingoDotDevEngine({"api_key": api_key}) as engine:
        # Translate text to multiple languages
        text_results = await engine.batch_localize_text(
            "Welcome to our application",
            {
                "source_locale": "en",
                "target_locales": ["es", "fr", "de"],
                "fast": True
            }
        )
        print(f"Text results: {text_results}")

asyncio.run(main())

Batch-Objektübersetzung

Übersetze mehrere Objekte gleichzeitig in einem einzigen Aufruf. Jedes Objekt wird unabhängig verarbeitet – ideal, um Listen von Datensätzen, Produktkataloge oder jede Sammlung strukturierter Inhalte zu lokalisieren.

# /// script
# requires-python = ">=3.11"
# dependencies = [
#     "lingodotdev==1.3.0",
# ]
# ///

import asyncio
import os
from lingodotdev import LingoDotDevEngine

async def main():
    objects = [
        {"title": "Getting Started", "description": "Learn the basics"},
        {"title": "Advanced Usage", "description": "Deep dive into features"},
        {"title": "API Reference", "description": "Complete method listing"},
    ]

    api_key = os.environ["LINGODOTDEV_API_KEY"]
    async with LingoDotDevEngine({"api_key": api_key}) as engine:
        results = await engine.batch_localize_objects(
            objects,
            {"source_locale": "en", "target_locale": "es"}
        )
        for result in results:
            print(result)

asyncio.run(main())

Stapelobjekte schnell übersetzen

Die schnelle Stapelmethode verarbeitet sowohl Text als auch Objekte.

# /// script
# requires-python = ">=3.11"
# dependencies = [
#     "lingodotdev==1.3.0",
# ]
# ///

import asyncio
import os
from lingodotdev.engine import LingoDotDevEngine

async def main():
    api_key = os.environ["LINGODOTDEV_API_KEY"]
    results = await LingoDotDevEngine.quick_batch_translate(
        {"greeting": "Hello", "bye": "Goodbye"},
        api_key=api_key,
        target_locales=["es", "fr", "de"],
        source_locale="en",
        fast=True,
    )
    for locale, result in zip(["es", "fr", "de"], results):
        print(f"{locale}: {result}")

asyncio.run(main())

Chat-Übersetzung

Übersetze Chat-Nachrichten und behalte dabei die Namen der Gesprächsteilnehmer bei. Jede Nachricht muss sowohl ein "name"- als auch ein "text"-Feld enthalten. Praktisch, um Supportgespräche, Chatprotokolle oder Dialogsysteme zu lokalisieren, ohne die Gesprächsstruktur zu verlieren.

# /// script
# requires-python = ">=3.11"
# dependencies = [
#     "lingodotdev==1.3.0",
# ]
# ///

import asyncio
import os
from lingodotdev import LingoDotDevEngine

async def main():
    chat = [
        {"name": "Alice", "text": "Hello everyone!"},
        {"name": "Bob", "text": "How are you doing?"},
        {"name": "Alice", "text": "Great, thanks for asking!"},
    ]

    api_key = os.environ["LINGODOTDEV_API_KEY"]
    async with LingoDotDevEngine({"api_key": api_key}) as engine:
        result = await engine.localize_chat(
            chat,
            {"source_locale": "en", "target_locale": "es"}
        )
        for message in result:
            print(f"{message['name']}: {message['text']}")

asyncio.run(main())

Sequenzielle Verarbeitung mit Fortschritt

Im sequentiellen Modus können detaillierte Fortschritts-Callbacks genutzt werden. Der Callback erhält für jeden verarbeiteten Stapel das Quell- und das übersetzte Segment. Das ist hilfreich zum Debuggen von Übersetzungsproblemen oder zur Anzeige von Fortschrittsdetails in Benutzeroberflächen.

# /// script
# requires-python = ">=3.11"
# dependencies = [
#     "lingodotdev==1.3.0",
# ]
# ///

import asyncio
import os
from lingodotdev import LingoDotDevEngine

def progress(percent: int, src_chunk: dict, out_chunk: dict):
    print(f"{percent}% complete - processed {len(src_chunk)} keys")

async def main():
    content = {
        "welcome": "Hello",
        "goodbye": "Farewell",
        "help": "Need assistance?"
    }

    api_key = os.environ["LINGODOTDEV_API_KEY"]
    async with LingoDotDevEngine({"api_key": api_key}) as engine:
        result = await engine.localize_object(
            content,
            {"source_locale": "en", "target_locale": "es"},
            progress_callback=progress
        )
        print(result)

asyncio.run(main())

Parallele Verarbeitung

Verarbeite Segmente parallel für schnellere Übersetzungen. Dieser Modus verzichtet auf die Fortschrittsverfolgung zugunsten höherer Geschwindigkeit – ideal für Produktionsumgebungen, in denen Durchsatz wichtiger ist als Rückmeldungen für Nutzer.

# /// script
# requires-python = ">=3.11"
# dependencies = [
#     "lingodotdev==1.3.0",
# ]
# ///

import asyncio
import os
from lingodotdev import LingoDotDevEngine

async def main():
    content = {
        "header": {"title": "Welcome", "subtitle": "Get started"},
        "body": {"intro": "Learn more", "details": "Full description"},
        "footer": {"copyright": "2024", "contact": "Email us"}
    }

    api_key = os.environ["LINGODOTDEV_API_KEY"]
    async with LingoDotDevEngine({"api_key": api_key}) as engine:
        result = await engine.localize_object(
            content,
            {"source_locale": "en", "target_locale": "es"},
            concurrent=True
        )
        print(result)

asyncio.run(main())

Referenzdaten

Nutze Glossare oder frühere Übersetzungen, um Konsistenz sicherzustellen. Referenzdaten werden mit jedem Segment an die API geschickt – achte deshalb auf eine überschaubare Größe. Besonders nützlich für Markennamen, Fachbegriffe oder gleichbleibende Übersetzungen über Produktaktualisierungen hinweg.

# /// script
# requires-python = ">=3.11"
# dependencies = [
#     "lingodotdev==1.3.0",
# ]
# ///

import asyncio
import os
from lingodotdev import LingoDotDevEngine

async def main():
    content = {"cta": "Start your free trial", "title": "Welcome"}

    reference = {
        "es": {"cta": "Comienza tu prueba gratuita"},
        "fr": {"cta": "Commencez votre essai gratuit"},
    }

    api_key = os.environ["LINGODOTDEV_API_KEY"]
    async with LingoDotDevEngine({"api_key": api_key}) as engine:
        result = await engine.localize_object(
            content,
            {
                "source_locale": "en",
                "target_locale": "es",
                "reference": reference,
            },
            concurrent=True
        )
        print(result)

asyncio.run(main())

Konfiguration

Steuere das Stapelverhalten und die API-Endpunkte. Das SDK teilt große Datenmengen je nach Schlüsselanzahl und Wortanzahl auf. So werden API-Timeouts vermieden und die Zuverlässigkeit bei großen Übersetzungsaufträgen erhöht.

# /// script
# requires-python = ">=3.11"
# dependencies = [
#     "lingodotdev==1.3.0",
# ]
# ///

import asyncio
import os
from lingodotdev import LingoDotDevEngine

async def main():
    config = {
        "api_key": os.environ["LINGODOTDEV_API_KEY"],
        "api_url": "https://engine.lingo.dev",
        "batch_size": 25,              # Items per chunk (1-250)
        "ideal_batch_item_size": 250,  # Words per chunk (1-2500)
    }

    async with LingoDotDevEngine(config) as engine:
        result = await engine.localize_text(
            "Reset your password",
            {"source_locale": "en", "target_locale": "es", "fast": True}
        )
        print(result)

asyncio.run(main())

Spracherkennung

Erkenne die Sprache eines Textes. Hilfreich, um Inhalte automatisch der richtigen Übersetzungspipeline zuzuweisen oder die Spracheingabe von Nutzern zu überprüfen.

# /// script
# requires-python = ">=3.11"
# dependencies = [
#     "lingodotdev==1.3.0",
# ]
# ///

import asyncio
import os
from lingodotdev import LingoDotDevEngine

async def main():
    api_key = os.environ["LINGODOTDEV_API_KEY"]
    async with LingoDotDevEngine({"api_key": api_key}) as engine:
        locale = await engine.recognize_locale("Guten Morgen")
        print(f"Detected language: {locale}")

asyncio.run(main())

API-Schlüssel-Überprüfung

Prüfe, welchem Konto ein API-Schlüssel gehört. Gibt None zurück, wenn die Authentifizierung fehlschlägt. Nützlich zum Debuggen von Authentifizierungsproblemen oder zum Anzeigen von Kontoinformationen in Admin-Tools.

# /// script
# requires-python = ">=3.11"
# dependencies = [
#     "lingodotdev==1.3.0",
# ]
# ///

import asyncio
import os
from lingodotdev import LingoDotDevEngine

async def main():
    api_key = os.environ["LINGODOTDEV_API_KEY"]
    async with LingoDotDevEngine({"api_key": api_key}) as engine:
        user = await engine.whoami()
        if user:
            print(f"Authenticated as: {user}")
        else:
            print("Authentication failed")

asyncio.run(main())

Fehlerbehandlung

Das SDK löst ValueError bei Parameterproblemen und RuntimeError bei Netzwerk- oder Serverfehlern aus. Unterscheide zwischen Benutzerfehlern (ValueError) und Infrastrukturproblemen (RuntimeError), um die passende Wiederholungslogik anzuwenden.

# /// script
# requires-python = ">=3.11"
# dependencies = [
#     "lingodotdev==1.3.0",
# ]
# ///

import asyncio
import os
from lingodotdev import LingoDotDevEngine

async def main():
    try:
        api_key = os.environ["LINGODOTDEV_API_KEY"]
        async with LingoDotDevEngine({"api_key": api_key}) as engine:
            result = await engine.localize_text(
                "Hello",
                {"target_locale": "es"}
            )
            print(result)
    except ValueError as e:
        print(f"Invalid parameters or bad request: {e}")
    except RuntimeError as e:
        print(f"Server or network error: {e}")

asyncio.run(main())

API-Referenz

Konstruktor

Parameter	Typ	Standardwert	Beschreibung
`api_key`	`str`	erforderlich	Lingo.dev API-Schlüssel
`api_url`	`str`	`"https://engine.lingo.dev"`	API-Endpoint-URL
`batch_size`	`int`	`25`	Elemente pro Abschnitt (1–250)
`ideal_batch_item_size`	`int`	`250`	Wörter pro Abschnitt (1–2500)

Instanzmethoden

Methode	Parameter	Rückgabewert	Beschreibung
`localize_text(text, params, progress_callback?)`	`text: str`, `params: dict`	`str`	Übersetzt einen einzelnen Textstring
`localize_object(obj, params, progress_callback?, concurrent?)`	`obj: dict`, `params: dict`	`dict`	Übersetzt ein Dictionary und bewahrt die Struktur
`localize_chat(chat, params, progress_callback?)`	`chat: list[dict]`, `params: dict`	`list[dict]`	Übersetzt Chatnachrichten und bewahrt Sprechernamen
`batch_localize_text(text, params)`	`text: str`, `params: dict` mit `target_locales`	`list[str]`	Übersetzt Text gleichzeitig in mehrere Zielsprachen
`batch_localize_objects(objects, params)`	`objects: list[dict]`, `params: dict`	`list[dict]`	Übersetzt mehrere Objekte gleichzeitig
`recognize_locale(text)`	`text: str`	`str`	Erkennt die Sprache eines Textstrings
`whoami()`	—	`dict \| None`	Holt Kontoinformationen für den aktuellen API-Schlüssel

Klassenmethoden

Methode	Parameter	Rückgabe	Beschreibung
`quick_translate(content, api_key, target_locale, source_locale?, api_url?, fast?)`	`content: str \| dict`	`str \| dict`	Einmalige Übersetzung ohne Kontext-Manager
`quick_batch_translate(content, api_key, target_locales, source_locale?, api_url?, fast?)`	`content: str \| dict`	`list`	Einmalige Massenübersetzung in mehrere Sprachen

Lokalisierungsparameter

Schlüssel	Typ	Erforderlich	Beschreibung
`source_locale`	`str`	nein	Quellsprach-Code (wird automatisch erkannt, wenn weggelassen)
`target_locale`	`str`	ja	Zielsprachen-Code
`target_locales`	`list[str]`	für Batch	Liste von Zielsprach-Codes
`fast`	`bool`	nein	Schnellen Modus für zügigere Übersetzungen aktivieren
`reference`	`dict`	nein	Glossar oder Referenzübersetzungen für Konsistenz