Python SDK

AI-перевод с помощью Python и Lingo.dev

Введение

Lingo.dev Python SDK переводит текст, JSON-объекты и чаты через асинхронный API. Он обрабатывает большие объёмы данных, автоматически разбивая их на оптимальные пакеты, отслеживает прогресс для длительных переводов и поддерживает глоссарии для единообразия терминологии.

Установка

pip

pip install lingodotdev

uv

uv add lingodotdev

Быстрый перевод

Для разовых переводов можно не использовать менеджер контекста. Эти методы сами управляют жизненным циклом движка и по умолчанию работают в быстром режиме — идеально для CLI-инструментов и скриптов.

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

Базовое использование

Для работы SDK нужен API-ключ Lingo.dev и используются асинхронные менеджеры контекста.

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

Перевод текста с отслеживанием прогресса

Отслеживайте прогресс перевода с помощью callback-функции. Даже одиночные строки проходят через chunker, что позволяет отслеживать прогресс для длинных текстов и обеспечивает одинаковое поведение для всех типов контента.

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

Перевод объектов

Переводите вложенные словари с сохранением структуры. SDK рекурсивно обрабатывает все строковые значения на любой глубине.

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

Пакетный перевод на несколько языков

Переводите контент на несколько целевых языков за один вызов. Возвращается список с результатами для каждого языка в том же порядке, в котором они были запрошены.

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

Пакетный перевод объектов

Переводите несколько объектов одновременно за один вызов. Каждый объект обрабатывается отдельно, что идеально подходит для локализации списков записей, товарных каталогов или любых коллекций структурированного контента.

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

Пакетный перевод объектов с быстрым методом

Быстрый пакетный метод обрабатывает как текст, так и объекты.

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

Перевод чата

Переводите сообщения в чате с сохранением имён участников. Каждое сообщение должно содержать поля "name" и "text". Удобно для локализации переписок поддержки, логов чата или диалоговых систем без потери структуры разговора.

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

Последовательная обработка с отслеживанием прогресса

В последовательном режиме доступен подробный вызов обратных функций прогресса. Колбек получает исходный и переведённый фрагменты для каждого обработанного пакета, что полезно для отладки переводов или показа детального прогресса в интерфейсе.

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

Параллельная обработка

Обрабатывайте фрагменты одновременно для более быстрого перевода. В этом режиме скорость важнее отслеживания прогресса, поэтому он подходит для продакшн-задач, где важна максимальная производительность.

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

Справочные данные

Добавляйте глоссарии или предыдущие переводы для сохранения единообразия. Справочные данные отправляются с каждым фрагментом в API, поэтому старайтесь не делать их слишком большими. Используйте их для бренд-терминов, технической лексики или поддержки согласованности перевода между версиями продукта.

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

Конфигурация

Управляйте поведением пакетирования и API-эндпоинтами. SDK разбивает большие задачи по количеству ключей и слов, чтобы избежать тайм-аутов и повысить надёжность при крупных переводах.

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

Определение языка

Определяйте язык текстовой строки. Полезно для автоматического направления контента в правильный поток перевода или проверки языка, вводимого пользователем.

# /// 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-ключа

Проверьте, какому аккаунту принадлежит API-ключ. Возвращает None, если аутентификация не удалась. Полезно для отладки проблем с аутентификацией или отображения информации об аккаунте в админских инструментах.

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

Обработка ошибок

SDK вызывает ValueError при ошибках в параметрах и RuntimeError при сетевых/серверных ошибках. Разделяйте ошибки пользователя (ValueError) и инфраструктурные проблемы (RuntimeError), чтобы правильно реализовать логику повторов.

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

Конструктор

ПараметрТипЗначение по умолчаниюОписание
api_keystrобязательноAPI-ключ Lingo.dev
api_urlstr"https://engine.lingo.dev"URL конечной точки API
batch_sizeint25Элементов в чанке (1–250)
ideal_batch_item_sizeint250Слов в чанке (1–2500)

Методы экземпляра

МетодПараметрыВозвращаетОписание
localize_text(text, params, progress_callback?)text: str, params: dictstrПеревести одну текстовую строку
localize_object(obj, params, progress_callback?, concurrent?)obj: dict, params: dictdictПеревести словарь, сохраняя структуру
localize_chat(chat, params, progress_callback?)chat: list[dict], params: dictlist[dict]Перевести сообщения чата, сохраняя имена собеседников
batch_localize_text(text, params)text: str, params: dict с target_localeslist[str]Перевести текст сразу на несколько целевых языков
batch_localize_objects(objects, params)objects: list[dict], params: dictlist[dict]Перевести несколько объектов одновременно
recognize_locale(text)text: strstrОпределить язык текстовой строки
whoami()—dict | NoneПолучить информацию об аккаунте по текущему API-ключу

Методы класса

МетодПараметрыВозвращаетОписание
quick_translate(content, api_key, target_locale, source_locale?, api_url?, fast?)content: str | dictstr | dictОдноразовый перевод без контекстного менеджера
quick_batch_translate(content, api_key, target_locales, source_locale?, api_url?, fast?)content: str | dictlistПакетный перевод на несколько локалей за раз

Параметры локализации

КлючТипОбязательноОписание
source_localestrнетКод исходного языка (определяется автоматически, если не указан)
target_localestrдаКод целевого языка
target_localeslist[str]для batchСписок кодов целевых языков
fastboolнетВключить быстрый режим для ускорения переводов
referencedictнетГлоссарий или эталонные переводы для единообразия