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 durch automatische Aufteilung in optimale Batch-Größen, verfolgt den Fortschritt bei lang laufenden Übersetzungen und unterstützt Glossare für konsistente Terminologie.

Installation

pip

pip install lingodotdev

uv

uv add lingodotdev

Schnellübersetzung

Überspringen Sie den Kontextmanager für einmalige Übersetzungen. Diese Methoden verwalten den Engine-Lebenszyklus automatisch und verwenden standardmäßig den Schnellmodus, 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 Kontextmanager.


# /// 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 eine Fortschrittsanzeige für lange Texte ermöglicht und ein konsistentes Verhalten über alle Inhaltstypen hinweg gewährleistet.


# /// 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 Zielsprache 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

Die schnelle Batch-Methode 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

Übersetzen Sie Chat-Nachrichten unter Beibehaltung der Sprechernamen. Jede Nachricht muss sowohl "name"- als auch "text"-Felder enthalten. Nützlich für die Lokalisierung von Support-Gesprächen, Chat-Protokollen oder Dialogsystemen ohne Verlust der Gesprächsstruktur.


# /// 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())

Sequentielle Verarbeitung mit Fortschrittsanzeige

Der sequentielle Modus ermöglicht detaillierte Fortschritts-Callbacks. Der Callback erhält den Quellblock und den übersetzten Block für jeden verarbeiteten Batch, was für die Fehlersuche bei Übersetzungsproblemen oder die Anzeige detaillierter Fortschritte in Benutzeroberflächen nützlich ist.


# /// 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

Verarbeiten Sie Chunks parallel für schnellere Übersetzungen. Dieser Modus opfert die Fortschrittsverfolgung zugunsten der Geschwindigkeit und ist ideal für Produktionsworkloads, bei denen der Durchsatz wichtiger ist als das Benutzerfeedback.


# /// 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

Stellen Sie Glossare oder frühere Übersetzungen bereit, um Konsistenz zu gewährleisten. Referenzdaten werden mit jedem Chunk an die API gesendet, daher sollten sie eine angemessene Größe haben. Verwenden Sie dies für Markenbezeichnungen, technisches Vokabular oder zur Aufrechterhaltung der Übersetzungskonsistenz bei Produktaktualisierungen.


# /// 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

Steuern Sie das Batching-Verhalten und die API-Endpunkte. Das SDK teilt große Payloads basierend auf Schlüsselanzahl und Wortanzahlbeschränkungen auf, verhindert API-Timeouts und verbessert die Zuverlässigkeit für umfangreiche Übersetzungsaufträge.


# /// 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

Erkennen Sie die Sprache eines Textes. Nützlich für die automatische Weiterleitung von Inhalten an die richtige Übersetzungspipeline oder zur Validierung der Benutzer-Eingabesprache.


# /// 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-Introspection

Überprüfen Sie, welchem Konto ein API-Schlüssel gehört. Gibt None zurück, wenn die Authentifizierung fehlschlägt. Nützlich zur Fehlersuche bei Authentifizierungsproblemen oder zur Anzeige 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 für Parameterfehler und RuntimeError für Netzwerk-/Serverfehler aus. Unterscheiden Sie zwischen Benutzerfehlern (ValueError) und Infrastrukturproblemen (RuntimeError) für eine angemessene Wiederholungslogik.


# /// 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())