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

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 ein "name"- als auch ein "text"-Feld enthalten. Nützlich für die Lokalisierung von Support-Konversationen, Chat-Protokollen oder Dialogsystemen ohne Verlust der Konversationsstruktur.

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

Der sequenzielle Modus ermöglicht detaillierte Fortschritts-Callbacks. Der Callback erhält für jeden verarbeiteten Batch den Quell-Chunk und den übersetzten Chunk, nützlich für das Debugging von Übersetzungsproblemen oder die Anzeige detaillierter Fortschritte 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

Verarbeiten Sie Chunks parallel für schnellere Übersetzungen. Dieser Modus opfert Fortschrittsverfolgung zugunsten von Geschwindigkeit und ist ideal für Produktions-Workloads, bei denen Durchsatz wichtiger ist als Benutzer-Feedback.

# /// 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 sicherzustellen. Referenzdaten werden mit jedem Chunk an die API gesendet, halten Sie sie daher in angemessener Größe. Verwenden Sie dies für Markenbegriffe, technisches Vokabular oder zur Aufrechterhaltung der Übersetzungskonsistenz ü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

Steuern Sie das Batching-Verhalten und API-Endpunkte. Das SDK teilt große Payloads basierend auf Schlüsselanzahl- und Wortanzahl-Beschränkungen auf, verhindert API-Timeouts und verbessert die Zuverlässigkeit für große Ü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 einer Textzeichenfolge. Nützlich für das automatische Routing von Inhalten zur korrekten Übersetzungs-Pipeline oder zur Validierung der Eingabesprache von Benutzern.

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

Prüfen Sie, welchem Konto ein API-Key gehört. Gibt None zurück, wenn die Authentifizierung fehlschlägt. Nützlich für das Debugging von Authentifizierungsproblemen oder die 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 Parameterprobleme und RuntimeError für Netzwerk-/Serverfehler aus. Unterscheiden Sie zwischen Benutzerfehlern (ValueError) und Infrastrukturproblemen (RuntimeError), um eine angemessene Wiederholungslogik zu implementieren.

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