SDK Python - Lingo.dev SDK

Introduction

Le SDK Python Lingo.dev traduit du texte, des objets JSON et des conversations de chat via une API asynchrone. Il gère les charges utiles volumineuses en découpant automatiquement le contenu en lots de taille optimale, suit la progression des traductions longues et prend en charge les glossaires pour une terminologie cohérente.

Installation

pip

pip install lingodotdev

uv

uv add lingodotdev

Traduction rapide

Ignorez le gestionnaire de contexte pour les traductions ponctuelles. Ces méthodes gèrent automatiquement le cycle de vie du moteur et utilisent par défaut le mode rapide, ce qui les rend idéales pour les outils CLI et les scripts.

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

Utilisation de base

Le SDK nécessite une clé API de Lingo.dev et utilise des gestionnaires de contexte asynchrones.

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

Traduction de texte avec progression

Suivez la progression de la traduction avec un callback. Même les chaînes de texte uniques passent par le découpeur, permettant le suivi de la progression pour les textes longs et offrant un comportement cohérent pour tous les types de contenu.

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

Traduction d'objets

Traduisez des dictionnaires imbriqués tout en préservant la structure. Le SDK traite récursivement toutes les valeurs de chaîne quelle que soit la profondeur.

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

Traduction par lots vers plusieurs langues

Traduisez du contenu vers plusieurs langues cibles en un seul appel. Renvoie une liste avec un résultat par locale cible, dans le même ordre que demandé.

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

Traduction d'objets par lots

Traduisez plusieurs objets simultanément en une seule requête. Chaque objet est traité indépendamment, ce qui est idéal pour localiser des listes d'enregistrements, des catalogues produits ou toute collection de contenus structurés.

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

Traduction par lot d'objets avec la méthode rapide

La méthode rapide par lot gère à la fois les textes et les objets.

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

Traduction de chat

Traduisez les messages de chat tout en conservant les noms des intervenants. Chaque message doit comporter les champs "name" et "text". Pratique pour localiser des conversations de support, des historiques de chat ou des systèmes de dialogue sans perdre la structure des échanges.

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

Traitement séquentiel avec progression

Le mode séquentiel permet des retours détaillés sur la progression. Le rappel reçoit la partie source et la partie traduite pour chaque batch traité, ce qui est utile pour déboguer ou afficher la progression détaillée dans l'interface utilisateur.

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

Traitement concurrent

Traitez les lots en parallèle pour une traduction plus rapide. Ce mode privilégie la vitesse au suivi de la progression, ce qui le rend parfait pour les environnements de production où le débit est plus important que le retour utilisateur.

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

Données de référence

Fournissez des glossaires ou des traductions précédentes pour assurer la cohérence. Les données de référence sont envoyées avec chaque lot à l'API, alors gardez-les de taille raisonnable. Utilisez-les pour des termes de marque, du vocabulaire technique ou une cohérence de traduction entre les mises à jour produits.

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

Configuration

Contrôlez le comportement de regroupement et les points de terminaison de l'API. Le SDK découpe les grandes charges selon le nombre de clés ou de mots afin d'éviter les expirations de requêtes et d'améliorer la fiabilité pour les grands travaux de traduction.

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

Détection de langue

Détectez la langue d'une chaîne de texte. Pratique pour acheminer automatiquement le contenu vers la bonne chaîne de traduction ou valider la langue saisie par l'utilisateur.

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

Introspection de la clé API

Vérifiez à quel compte appartient une clé API. Retourne None si l'authentification échoue. Utile pour déboguer les problèmes d'authentification ou afficher des informations de compte dans des outils d'administration.

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

Gestion des erreurs

Le SDK lève une ValueError pour les problèmes de paramètres et une RuntimeError pour les erreurs réseau/serveur. Faites la distinction entre les erreurs utilisateur (ValueError) et les problèmes d'infrastructure (RuntimeError) pour appliquer une logique de nouvelle tentative appropriée.

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

Référence de l'API

Constructeur

Paramètre	Type	Valeur par défaut	Description
`api_key`	`str`	requis	Clé API Lingo.dev
`api_url`	`str`	`"https://engine.lingo.dev"`	URL de l'endpoint de l'API
`batch_size`	`int`	`25`	Éléments par lot (1–250)
`ideal_batch_item_size`	`int`	`250`	Mots par lot (1–2500)

Méthodes d'instance

Méthode	Paramètres	Retourne	Description
`localize_text(text, params, progress_callback?)`	`text: str`, `params: dict`	`str`	Traduire une chaîne de texte unique
`localize_object(obj, params, progress_callback?, concurrent?)`	`obj: dict`, `params: dict`	`dict`	Traduire un dictionnaire tout en conservant sa structure
`localize_chat(chat, params, progress_callback?)`	`chat: list[dict]`, `params: dict`	`list[dict]`	Traduire des messages de chat en gardant les noms des intervenants
`batch_localize_text(text, params)`	`text: str`, `params: dict` avec `target_locales`	`list[str]`	Traduire un texte vers plusieurs langues cibles à la fois
`batch_localize_objects(objects, params)`	`objects: list[dict]`, `params: dict`	`list[dict]`	Traduire plusieurs objets en parallèle
`recognize_locale(text)`	`text: str`	`str`	Détecter la langue d'une chaîne de texte
`whoami()`	—	`dict \| None`	Obtenir les infos du compte pour la clé API actuelle

Méthodes de classe

Méthode	Paramètres	Retour	Description
`quick_translate(content, api_key, target_locale, source_locale?, api_url?, fast?)`	`content: str \| dict`	`str \| dict`	Traduction ponctuelle sans gestionnaire de contexte
`quick_batch_translate(content, api_key, target_locales, source_locale?, api_url?, fast?)`	`content: str \| dict`	`list`	Traduction en lot vers plusieurs langues

Paramètres de localisation

Clé	Type	Requis	Description
`source_locale`	`str`	non	Code langue source (détecté automatiquement si omis)
`target_locale`	`str`	oui	Code langue cible
`target_locales`	`list[str]`	pour lot	Liste des codes langues cibles
`fast`	`bool`	non	Activer le mode rapide pour des traductions plus rapides
`reference`	`dict`	non	Glossaire ou traductions de référence pour la cohérence