Выберите рабочий процесс

Co-op Translator можно использовать тремя способами: CLI, Python API и MCP Server. Они используют одни и те же возможности перевода, но каждый подходит для разных рабочих процессов.

Используйте эту страницу, когда решаете, с чего начать.

Если вы редактируете переводы вручную: стандартные рабочие процессы CLI и Actions повторно переводят изменённые исходные файлы полностью, поэтому ваши формулировки в этих файлах могут быть перезаписаны. Просмотрите diff перед принятием обновления. Для сохранения блоковой структуры Markdown в принятых правках используйте опциональный поставщик состояния перевода Python API.

Быстрое решение

Если вы хотите...	Использовать	Начать здесь
Перевести или просмотреть репозиторий из терминала	CLI	Справочник CLI
Добавить перевод в Python-скрипт, сервис, ноутбук или CI-задачу	Python API	Python API
Позволить агенту, редактору или клиенту, совместимому с MCP, переводить контент за вас	MCP Server	MCP Server
Перевести один Markdown-документ, ноутбук или изображение, которое ваше приложение уже загрузило	Python API или MCP Server	Python API или MCP Server
Перевести весь репозиторий со стандартными выходными папками и метаданными	CLI или run_translation	Справочник CLI или Python API

Используйте CLI, когда

Выбирайте CLI, когда перевод репозитория запускает человек или CI-задача из оболочки.

CLI — самый прямой путь, когда вы хотите, чтобы Co-op Translator обнаруживал файлы проекта, создавал переведённые выходные данные, сохранял структуру проекта, обновлял метаданные и запускал команды для обзора.

translate -l "ko" -md --dry-run
translate -l "ko" -md -nb
co-op-review -l "ko"
migrate-links -l "ko" --dry-run

Этот пример переводит Markdown и ноутбуки. Добавьте -img только после настройки Azure AI Vision. Для первого запуска только с Markdown, следуйте Ваш первый перевод.

Подходит для:

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

Используйте Python API, когда

Выбирайте Python API, когда рабочим процессом должен управлять ваш собственный код.

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

Переведите один Markdown-документ и решите, где его сохранить:

import asyncio
from pathlib import Path

from co_op_translator.api import rewrite_markdown_paths, translate_markdown_content


async def main() -> None:
    source_path = Path("docs/guide.md")
    target_path = Path("translations/ko/docs/guide.md")

    translated = await translate_markdown_content(
        source_path.read_text(encoding="utf-8"),
        "ko",
        {"source_path": source_path},
    )

    rewritten = rewrite_markdown_paths(
        translated,
        source_path=source_path,
        target_path=target_path,
    )

    target_path.parent.mkdir(parents=True, exist_ok=True)
    target_path.write_text(rewritten, encoding="utf-8")


asyncio.run(main())

Запустите перевод репозитория из Python:

from co_op_translator.api import run_translation

run_translation(
    language_codes="ko",
    markdown=True,
    notebook=True,
    images=False,
    dry_run=True,
)

Подходит для:

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

Используйте MCP Server, когда

Выбирайте MCP Server, когда агент, редактор или клиент, совместимый с MCP, должен вызывать инструменты Co-op Translator.

В обычной локальной конфигурации пользователь не поддерживает сервер запущенным вручную. MCP-клиент запускает co-op-translator-mcp через stdio, когда нужны инструменты.

Примеры пользовательских запросов, которые агент может обработать:

• "Переведите этот Markdown-файл на корейский и сохраните правильность ссылок."
• "Переведите этот Markdown-файл на корейский с помощью рабочего процесса MCP с поддержкой агента, используя вашу собственную модель для переведённых фрагментов."
• "Переведите этот ноутбук на корейский, сохраните кодовые ячейки и используйте Co-op Translator MCP для реконструкции ноутбука."
• "Переведите текст на этом изображении на японский и сохраните результат."
• "Прогон по сухому сценарию перевода репозитория на испанский и скажите, что бы изменилось."
• "Проверьте, актуален ли вывод перевода на корейский."

Для Markdown и ноутбуков MCP может работать в двух режимах:

Режим	Использовать, когда	Основные инструменты
С поддержкой агента	Хост-агент MCP должен переводить фрагменты своей собственной моделью, без учётных данных провайдера LLM Co-op Translator.	start_markdown_agent_translation, finish_markdown_agent_translation, start_notebook_agent_translation, finish_notebook_agent_translation
С поддержкой провайдера	Co-op Translator должен вызывать Azure OpenAI, OpenAI или Anthropic напрямую.	translate_markdown_content, translate_notebook_content

Форма вызова инструмента Markdown в режиме с поддержкой провайдера:

{
  "tool": "translate_markdown_content",
  "arguments": {
    "document": "# Setup\n\nInstall Co-op Translator first.",
    "language_code": "ko",
    "options": {
      "source_path": "docs/setup.md"
    }
  }
}

MCP image tool call shape:

{
  "tool": "translate_image_content",
  "arguments": {
    "image_path": "assets/architecture.png",
    "language_code": "ko",
    "output_path": "translated_images/ko/assets/architecture.png"
  }
}

Перевод репозитория по умолчанию выполняется в режиме предварительного прогона (dry-run) через MCP:

{
  "tool": "run_translation",
  "arguments": {
    "language_codes": ["ko"],
    "translate_markdown": true,
    "translate_notebooks": true,
    "translate_images": false,
    "dry_run": true
  }
}

Подходит для:

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

Как они взаимодействуют

CLI — лучший вариант по умолчанию для людей, переводящих репозитории. Python API подходит, когда рабочим процессом управляет ваш код. MCP Server лучше, когда рабочим процессом управляет агент или редактор.

Все три варианта используют один и тот же публичный API Co-op Translator, поэтому вы можете начать с CLI, затем автоматизировать с помощью Python и предоставить те же возможности клиентам MCP, когда вам потребуются рабочие процессы, управляемые агентом.