Python SDK - Lingo.dev SDK

Введение

Python SDK Lingo.dev переводит текст, 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"]

    # Перевод текста
    text_result = await LingoDotDevEngine.quick_translate(
        "Hello world",
        api_key=api_key,
        source_locale="en",
        target_locale="es"
    )
    print(f"Текст: {text_result}")

    # Перевод объекта
    object_result = await LingoDotDevEngine.quick_translate(
        {"greeting": "Hello", "farewell": "Goodbye"},
        api_key=api_key,
        source_locale="en",
        target_locale="fr"
    )
    print(f"Объект: {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())

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

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


# /// 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"Прогресс: {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(
            "Мы отправили письмо с подтверждением.",
            {"source_locale": "en", "target_locale": "es"},
            progress_callback=on_progress
        )
        print(f"Результат: {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": "Добро пожаловать",
        "cta": "Начните бесплатный пробный период",
        "footer": {
            "legal": "Все права защищены.",
            "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:
        # Перевод текста на несколько языков
        text_results = await engine.batch_localize_text(
            "Добро пожаловать в наше приложение",
            {
                "source_locale": "en",
                "target_locales": ["es", "fr", "de"],
                "fast": True
            }
        )
        print(f"Результаты перевода текста: {text_results}")

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": "Привет", "bye": "До свидания"},
        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": "Всем привет!"},
        {"name": "Bob", "text": "Как дела?"},
        {"name": "Alice", "text": "Отлично, спасибо, что спросил!"},
    ]

    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}% завершено - обработано {len(src_chunk)} ключей")

async def main():
    content = {
        "welcome": "Привет",
        "goodbye": "Прощай",
        "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"},
            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": "Добро пожаловать", "subtitle": "Начните"},
        "body": {"intro": "Узнать больше", "details": "Полное описание"},
        "footer": {"copyright": "2024", "contact": "Напишите нам"}
    }

    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": "Начните бесплатный пробный период", "title": "Добро пожаловать"}

    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 разделяет большие объемы данных на основе ограничений по количеству ключей и слов, предотвращая тайм-ауты API и повышая надежность для крупных задач перевода.


# /// 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,              # Элементов в пакете (1-250)
        "ideal_batch_item_size": 250,  # Слов в пакете (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"Обнаруженный язык: {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) для соответствующей логики повторных попыток.


# /// скрипт

# 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"Неверные параметры или некорректный запрос: {e}")
    except RuntimeError as e:
        print(f"Ошибка сервера или сети: {e}")

asyncio.run(main())