Справочник CLI¶

Co-op Translator устанавливает следующие точки входа командной строки:

translate
evaluate
migrate-links
co-op-review
co-op-translator-mcp

Команды translate, evaluate, migrate-links и co-op-review перенаправляются через co_op_translator.__main__, который выбирает реализацию команды в зависимости от имени запускаемого скрипта. Сервер MCP использует co_op_translator.mcp.server напрямую.

Если вы выбираете между CLI, Python API и MCP, начните с Выбор рабочего процесса.

Вывод в консоль¶

Интерактивные терминалы используют оформление Rich для заголовка команды, прогресса и сводок. CI и неинтерактивный вывод автоматически переключаются на простой текст.

Установите CO_OP_TRANSLATOR_OUTPUT_STYLE=plain, чтобы принудительно использовать простой вывод, или CO_OP_TRANSLATOR_OUTPUT_STYLE=rich, чтобы принудительно использовать Rich-вывод. Установите CO_OP_TRANSLATOR_NO_PROGRESS=1, чтобы сохранить сводки, подавив живые индикаторы прогресса.

Используйте translate --json-events progress.ndjson, когда другой системе нужен машиночитаемый прогресс. CLI продолжает отображать вывод для людей, в то время как файл NDJSON получает версионированные события co-op.translation.event.v1 с стабильными полями, такими как type, stage_key, completed, total, и current_path.

Порядок работы в CLI при первом запуске¶

Начните здесь, если вы используете Co-op Translator из терминала:

Настройте поставщика LLM как описано в Конфигурации.
Выберите тип содержимого, который хотите перевести.
Сначала запустите узконаправленную команду, например перевод только Markdown.
Используйте --dry-run перед крупными изменениями в репозитории.
Используйте co-op-review после перевода, чтобы проверить структуру и актуальность.

Цель	Команда для старта
Перевести документы Markdown	`translate -l "ko" -md`
Перевести ноутбуки	`translate -l "ko" -nb`
Перевести текст на изображениях	`translate -l "ko" -img`
Просмотреть результаты без записи файлов	`translate -l "ko" -md --dry-run`
Проверить существующие переводы	`co-op-review -l "ko"`
Обновить ссылки в ноутбуках и Markdown	`migrate-links -l "ko" --dry-run`
Предоставить инструменты клиенту MCP	Настройте Сервер MCP вместо прямого запуска команд CLI.

translate¶

Переводит файлы Markdown, ноутбуки и текст на изображениях на один или несколько целевых языков.

translate -l "ko ja fr"

Частые примеры¶

Перевести только Markdown:

translate -l "de" -md

Перевести только ноутбуки:

translate -l "zh-CN" -nb

Перевести Markdown и изображения:

translate -l "pt-BR" -md -img

Обновить существующие переводы путем удаления и воссоздания:

translate -l "ko" -u

Запустить без интерактивных подсказок:

translate -l "ko ja" -md -y

Сохранить логи:

translate -l "ko" -s

Записывать структурированные события прогресса:

translate -l "ko ja" -md --json-events progress.ndjson

Параметры¶

Опция	Обязательно	Описание
`-l`, `--language-codes`	Да	Коды языков, разделённые пробелом, например `"es fr de"`, или `"all"`.
`-r`, `--root-dir`	Нет	Корень проекта. По умолчанию текущая директория.
`-u`, `--update`	Нет	Удалить существующие переводы для выбранных языков и воссоздать их.
`-img`, `--images`	Нет	Перевести только файлы изображений.
`-md`, `--markdown`	Нет	Перевести только файлы Markdown.
`-nb`, `--notebook`	Нет	Перевести только файлы Jupyter notebook.
`-d`, `--debug`	Нет	Включить отладочное логирование в консоли.
`-s`, `--save-logs`	Нет	Сохранять логи уровня DEBUG в `<root-dir>/logs/`.
`--json-events`	Нет	Записывать машиночитаемые события прогресса перевода в формате NDJSON.
`-x`, `--fix`	Нет	Переперевести Markdown-файлы с низкой уверенностью на основе предыдущих результатов оценки.
`-c`, `--min-confidence`	Нет	Порог уверенности для `--fix`. По умолчанию `0.7`.
`--add-disclaimer`, `--no-disclaimer`	Нет	Добавлять или подавлять предупреждения о машинном переводе. По умолчанию включено в CLI.
`-f`, `--fast`	Нет	Устаревший быстрый режим обработки изображений.
`-y`, `--yes`	Нет	Автоматически подтверждать подсказки, полезно в CI.
`--repo-url`	Нет	URL репозитория, используемый в советах по sparse-checkout в таблице языков README.
`--migrate-language-folders`	Нет	Переименовывать устаревшие папки-алиасы, такие как `cn` или `tw`, в канонические папки BCP 47.
`--dry-run`	Нет	Просмотреть миграцию папок языков и оценки перевода без записи файлов.

Если флаг типа не указан, translate обрабатывает Markdown, ноутбуки и изображения. Перевод изображений требует настройки Azure AI Vision.

evaluate¶

Оценить качество перевода Markdown для одного языка.

Экспериментально

evaluate экспериментален. Он может использовать проверки качества на основе правил и LLM, записывает результаты оценки в метаданные перевода, и его модель оценки и поведение с метаданными могут измениться.

evaluate -l "ko"

Частые примеры¶

Использовать более строгий порог низкой уверенности:

evaluate -l "es" -c 0.8

Запустить только проверки на основе правил:

evaluate -l "fr" -f

Запустить только проверки на основе LLM:

evaluate -l "ja" -D

Параметры¶

Опция	Обязательно	Описание
`-l`, `--language-code`	Да	Код одного языка для оценки. Псевдонимы кодов нормализуются.
`-r`, `--root-dir`	Нет	Корень проекта. По умолчанию текущая директория.
`-c`, `--min-confidence`	Нет	Порог, используемый при перечислении переводов с низкой уверенностью. По умолчанию `0.7`.
`-d`, `--debug`	Нет	Включить отладочное логирование.
`-s`, `--save-logs`	Нет	Сохранять логи уровня DEBUG в `<root-dir>/logs/`.
`-f`, `--fast`	Нет	Только оценка на основе правил.
`-D`, `--deep`	Нет	Только оценка на основе LLM.

По умолчанию evaluate использует как оценку на основе правил, так и на основе LLM. Результаты записываются в метаданные перевода и суммируются в консоли.

co-op-review¶

Запустить детерминированные проверки обслуживания переводов без учётных данных API.

Бета

co-op-review — это бета-версия детерминированной команды обзора. Она не обращается к поставщикам моделей и не записывает файлы, но её проверки и схема вывода проблем могут измениться.

co-op-review -l "ko"

Частые примеры¶

Проверить переводы на корейский и японский из текущей директории:

co-op-review -l "ko ja"

Проверить конкретный корень проекта:

co-op-review -l "fr" -r ./my-course

Проверить только README после перевода только README:

translate -l "ko" --readme-only -y
co-op-review -l "ko" --readme-only --format github

--readme-only игнорирует другие документы и вложенные READMEs. Она завершится с ошибкой, если корневой README.md отсутствует. В сочетании с --changed-from она просматривает только README, когда исходный файл изменился. Перевод только README оставляет исходный README без изменений, включая любые маркеры общих секций.

Проверить только исходные файлы, изменённые по сравнению с базовым ref:

co-op-review -l "ko" --changed-from origin/main

Выводить Markdown в стиле GitHub для сводок CI:

co-op-review -l "ko ja" --changed-from origin/main --format github

Параметры¶

Опция	Обязательно	Описание
`-l`, `--language-code`	Нет	Код языка для проверки. Может быть передан несколько раз или как значение, разделённое пробелами. По умолчанию — все обнаруженные языки перевода.
`-r`, `--root-dir`	Нет	Корень проекта. По умолчанию текущая директория.
`--changed-from`	Нет	Git ref, используемый для ограничения проверки изменёнными исходными файлами.
`--readme-only`	Нет	Проверять только перевод корневого `README.md`.
`--format`	Нет	Формат вывода: `text` или `github`. По умолчанию `text`.

co-op-review в настоящее время проверяет отсутствие переведённых файлов, отсутствие или устаревание метаданных перевода, целостность frontmatter и блоков кода в Markdown, неверный JSON переведённых ноутбуков и отсутствующие локальные цели ссылок в Markdown или изображениях. Отсутствующие ссылки по умолчанию считаются предупреждениями; структурные и проблемы с актуальностью приводят к сбою команды.

co-op-translator-mcp¶

Запустить MCP-сервер Co-op Translator для агентов, редакторов и клиентов, совместимых с MCP.

co-op-translator-mcp

Транспорт по умолчанию — stdio. См. руководство Сервер MCP для настройки клиента, инструментов, ресурсов и замечаний по безопасности.

Параметры¶

Опция	Обязательно	Описание
`--transport`	Нет	MCP-транспорт: `stdio`, `streamable-http`, или `sse`. По умолчанию `stdio`.

migrate-links¶

Повторно обработать переведённые Markdown-файлы и обновить ссылки в ноутбуках так, чтобы они указывали на переведённые ноутбуки, если они доступны.

migrate-links -l "ko ja"

Частые примеры¶

Просмотреть обновления ссылок:

migrate-links -l "ko" --dry-run

Обработать все поддерживаемые языки без подтверждения:

migrate-links -l "all" -y

Перезаписывать ссылки только если существуют переведённые ноутбуки:

migrate-links -l "ko" --no-fallback-to-original

Параметры¶

Опция	Обязательно	Описание
`-l`, `--language-codes`	Да	Коды языков, разделённые пробелом, или `"all"`.
`-r`, `--root-dir`	Нет	Корень проекта. По умолчанию текущая директория.
`--image-dir`	Нет	Каталог переведённых изображений относительно корня. По умолчанию `translated_images`.
`--dry-run`	Нет	Показать файлы, которые бы изменились, без записи обновлений.
`--fallback-to-original`, `--no-fallback-to-original`	Нет	Использовать оригинальные ссылки на ноутбуки, когда переведённые ноутбуки отсутствуют. По умолчанию включено.
`-d`, `--debug`	Нет	Включить отладочное логирование.
`-s`, `--save-logs`	Нет	Сохранять логи уровня DEBUG в `<root-dir>/logs/`.
`-y`, `--yes`	Нет	Автоматически подтверждать подсказки при обработке всех языков.

Окружение¶

Когда команда требует учётных данных поставщика, настройте один из этих наборов поставщиков. translate --dry-run и co-op-review не требуют учётных данных поставщика:

# Azure OpenAI
AZURE_OPENAI_API_KEY="..."
AZURE_OPENAI_ENDPOINT="https://<resource>.openai.azure.com/"
AZURE_OPENAI_MODEL_NAME="gpt-4o"
AZURE_OPENAI_CHAT_DEPLOYMENT_NAME="<deployment>"
AZURE_OPENAI_API_VERSION="2024-12-01-preview"

# Или OpenAI
OPENAI_API_KEY="..."
OPENAI_CHAT_MODEL_ID="gpt-4o"

# Или Anthropic
ANTHROPIC_API_KEY="..."
ANTHROPIC_MODEL="claude-..."

Перевод изображений дополнительно требует Azure AI Vision:

AZURE_AI_SERVICE_API_KEY="..."
AZURE_AI_SERVICE_ENDPOINT="https://<resource>.cognitiveservices.azure.com/"

Структура вывода¶

Текстовые переводы записываются в:

translations/<language-code>/<original-path>

Переведённые изображения записываются в:

translated_images/<language-code>/<original-path>

Например, перевод README.md и docs/setup.md на корейский даст:

translations/ko/README.md
translations/ko/docs/setup.md

Примеры команд CLI для копирования¶

Перевести Markdown на три языка:

translate -l "ko ja fr" -md

Перевести только ноутбуки:

translate -l "zh-CN" -nb

Перевести только изображения:

translate -l "pt-BR" -img

Просмотреть перевод Markdown без записи файлов:

translate -l "de es" -md --dry-run

Исправить переводы Markdown с низкой уверенностью:

evaluate -l "ko" -c 0.8
translate -l "ko" --fix -c 0.8 -md

Запустить перевод Markdown, удобный для CI:

translate -l "ko ja" -md -y -s

Проверить переведённый результат:

co-op-review -l "ko ja"

Просмотреть миграцию ссылок:

migrate-links -l "ko" --dry-run