SDK de Python - Lingo.dev SDK

Introducción

El SDK de Python de Lingo.dev traduce texto, objetos JSON y conversaciones de chat a través de una API asíncrona. Gestiona cargas grandes dividiendo automáticamente el contenido en lotes de tamaño óptimo, realiza seguimiento del progreso para traducciones de larga duración y admite glosarios para mantener una terminología consistente.

Instalación

pip

pip install lingodotdev

uv

uv add lingodotdev

Traducción rápida

Omite el gestor de contexto para traducciones puntuales. Estos métodos gestionan automáticamente el ciclo de vida del motor y utilizan el modo rápido por defecto, lo que los hace ideales para herramientas CLI y 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())

Uso básico

El SDK requiere una clave API de Lingo.dev y utiliza gestores de contexto asíncronos.

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

Traducción de texto con progreso

Realiza seguimiento del progreso de traducción con un callback. Incluso las cadenas de texto individuales pasan por el fragmentador, lo que permite informar del progreso para textos largos y proporciona un comportamiento consistente en todos los tipos de contenido.

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

Traducción de objetos

Traduce diccionarios anidados preservando la estructura. El SDK procesa recursivamente todos los valores de cadena independientemente de la profundidad.

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

Traducción por lotes a múltiples idiomas

Traduce contenido a múltiples idiomas de destino en una sola llamada. Devuelve una lista con un resultado por configuración regional de destino, en el mismo orden solicitado.

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

Traducción de objetos por lotes

Traduce varios objetos a la vez en una sola llamada. Cada objeto se procesa de forma independiente, lo que lo hace ideal para localizar listas de registros, catálogos de productos o cualquier colección de contenido estructurado.

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

Traducción por lotes de objetos con método rápido

El método rápido por lotes maneja tanto texto como objetos.

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

Traducción de chats

Traduce mensajes de chat manteniendo los nombres de los participantes. Cada mensaje debe tener los campos "name" y "text". Útil para localizar conversaciones de soporte, registros de chat o sistemas de diálogo sin perder la estructura de la conversación.

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

Procesamiento secuencial con progreso

El modo secuencial permite disponer de callbacks de progreso detallados. El callback recibe el fragmento original y el traducido por cada lote procesado, útil para depurar problemas de traducción o mostrar el avance detallado en las interfaces.

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

Procesamiento concurrente

Procesa fragmentos en paralelo para una traducción más rápida. Este modo sacrifica el seguimiento del progreso a cambio de velocidad, ideal para cargas de trabajo en producción donde el rendimiento es más importante que la retroalimentación al usuario.

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

Datos de referencia

Proporciona glosarios o traducciones anteriores para asegurar la coherencia. Los datos de referencia se envían con cada fragmento a la API, así que mantenlos en un tamaño razonable. Úsalos para términos de marca, vocabulario técnico o mantener la consistencia de las traducciones en actualizaciones de productos.

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

Configuración

Controla el comportamiento de procesamiento por lotes y los endpoints de la API. El SDK divide cargas grandes según la cantidad de claves y palabras, evitando tiempos de espera de la API y mejorando la fiabilidad en trabajos de traducción extensos.

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

Detección de idioma

Detecta el idioma de una cadena de texto. Útil para dirigir automáticamente el contenido a la canalización de traducción correcta o validar el idioma del texto de entrada del usuario.

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

Introspección de la clave API

Verifica a qué cuenta pertenece una clave API. Devuelve None si la autenticación falla. Es útil para depurar problemas de autenticación o mostrar información de la cuenta en herramientas de administración.

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

Manejo de errores

El SDK genera ValueError para problemas de parámetros y RuntimeError para errores de red o servidor. Distingue entre errores de usuario (ValueError) y problemas de infraestructura (RuntimeError) para aplicar la lógica de reintentos adecuada.

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

Referencia de la API

Constructor

Parámetro	Tipo	Predeterminado	Descripción
`api_key`	`str`	requerido	Clave API de Lingo.dev
`api_url`	`str`	`"https://engine.lingo.dev"`	URL del endpoint de la API
`batch_size`	`int`	`25`	Elementos por lote (1–250)
`ideal_batch_item_size`	`int`	`250`	Palabras por lote (1–2500)

Métodos de instancia

Método	Parámetros	Devuelve	Descripción
`localize_text(text, params, progress_callback?)`	`text: str`, `params: dict`	`str`	Traduce una sola cadena de texto
`localize_object(obj, params, progress_callback?, concurrent?)`	`obj: dict`, `params: dict`	`dict`	Traduce un diccionario, conservando la estructura
`localize_chat(chat, params, progress_callback?)`	`chat: list[dict]`, `params: dict`	`list[dict]`	Traduce mensajes de chat, manteniendo los nombres de los interlocutores
`batch_localize_text(text, params)`	`text: str`, `params: dict` con `target_locales`	`list[str]`	Traduce texto a varios idiomas de destino al mismo tiempo
`batch_localize_objects(objects, params)`	`objects: list[dict]`, `params: dict`	`list[dict]`	Traduce varios objetos simultáneamente
`recognize_locale(text)`	`text: str`	`str`	Detecta el idioma de una cadena de texto
`whoami()`	—	`dict \| None`	Obtiene la información de cuenta para la clave API actual

Métodos de clase

Método	Parámetros	Retorna	Descripción
`quick_translate(content, api_key, target_locale, source_locale?, api_url?, fast?)`	`content: str \| dict`	`str \| dict`	Traducción puntual sin gestor de contexto
`quick_batch_translate(content, api_key, target_locales, source_locale?, api_url?, fast?)`	`content: str \| dict`	`list`	Traducción en lote puntual a varios idiomas

Parámetros de localización

Clave	Tipo	Requerido	Descripción
`source_locale`	`str`	no	Código del idioma de origen (detectado automáticamente si se omite)
`target_locale`	`str`	sí	Código del idioma de destino
`target_locales`	`list[str]`	para lote	Lista de códigos de idioma de destino
`fast`	`bool`	no	Activar modo rápido para traducciones más ágiles
`reference`	`dict`	no	Glosario o traducciones de referencia para consistencia