Referencja CLI¶

Co-op Translator instaluje następujące punkty wejścia w wierszu poleceń:

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

Polecenia translate, evaluate, migrate-links i co-op-review są wywoływane przez co_op_translator.__main__, który wybiera implementację polecenia na podstawie nazwy uruchomionego skryptu. Serwer MCP używa bezpośrednio co_op_translator.mcp.server.

Jeśli zastanawiasz się między CLI, Python API i MCP, zacznij od Wybierz swój przepływ pracy.

Pierwsze uruchomienie CLI¶

Zacznij tutaj, jeśli korzystasz z Co-op Translator z terminala:

Skonfiguruj dostawcę LLM zgodnie z opisem w Configuration.
Wybierz typ treści, który chcesz przetłumaczyć.
Najpierw uruchom ukierunkowane polecenie, na przykład tłumaczenie tylko Markdown.
Użyj --dry-run przed dużymi zmianami w repozytorium.
Użyj co-op-review po tłumaczeniu, aby sprawdzić strukturę i aktualność.

Cel	Polecenie początkowe
Translate Markdown documents	`translate -l "ko" -md`
Translate notebooks	`translate -l "ko" -nb`
Translate image text	`translate -l "ko" -img`
Preview work without writing files	`translate -l "ko" -md --dry-run`
Review existing translations	`co-op-review -l "ko"`
Update notebook and Markdown links	`migrate-links -l "ko" --dry-run`
Expose tools to an MCP client	Configure the MCP Server instead of running CLI commands directly.

translate¶

Translate Markdown files, notebooks, and image text into one or more target languages.

translate -l "ko ja fr"

Typowe przykłady¶

Translate only Markdown:

translate -l "de" -md

Translate only notebooks:

translate -l "zh-CN" -nb

Translate Markdown and images:

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

Update existing translations by deleting and recreating them:

translate -l "ko" -u

Run without interactive prompts:

translate -l "ko ja" -md -y

Save logs:

translate -l "ko" -s

Opcje¶

Option	Required	Description
`-l`, `--language-codes`	Yes	Space-separated language codes, such as `"es fr de"`, or `"all"`.
`-r`, `--root-dir`	No	Project root. Defaults to the current directory.
`-u`, `--update`	No	Delete existing translations for selected languages and recreate them.
`-img`, `--images`	No	Translate only image files.
`-md`, `--markdown`	No	Translate only Markdown files.
`-nb`, `--notebook`	No	Translate only Jupyter notebook files.
`-d`, `--debug`	No	Enable debug logging in the console.
`-s`, `--save-logs`	No	Save DEBUG-level logs under `<root-dir>/logs/`.
`-x`, `--fix`	No	Retranslate low-confidence Markdown files based on previous evaluation results.
`-c`, `--min-confidence`	No	Confidence threshold for `--fix`. Defaults to `0.7`.
`--add-disclaimer`, `--no-disclaimer`	No	Add or suppress machine translation disclaimers. Defaults to enabled in the CLI.
`-f`, `--fast`	No	Deprecated fast image mode.
`-y`, `--yes`	No	Auto-confirm prompts, useful in CI.
`--repo-url`	No	Repository URL used in the README languages table sparse-checkout advisory.
`--migrate-language-folders`	No	Rename legacy alias folders, such as `cn` or `tw`, to canonical BCP 47 folders.
`--dry-run`	No	Preview language folder migration and translation estimates without writing files.

If no type flag is provided, translate processes Markdown, notebooks, and images. Image translation requires Azure AI Vision configuration.

evaluate¶

Evaluate translated Markdown quality for one language.

Eksperymentalne

evaluate is experimental. It can use rule-based and LLM-based quality checks, writes evaluation results into translation metadata, and its scoring model and metadata behavior may change.

evaluate -l "ko"

Typowe przykłady¶

Use a stricter low-confidence threshold:

evaluate -l "es" -c 0.8

Run rule-based checks only:

evaluate -l "fr" -f

Run LLM-based checks only:

evaluate -l "ja" -D

Opcje¶

Option	Required	Description
`-l`, `--language-code`	Yes	Single language code to evaluate. Alias codes are normalized.
`-r`, `--root-dir`	No	Project root. Defaults to the current directory.
`-c`, `--min-confidence`	No	Threshold used when listing low-confidence translations. Defaults to `0.7`.
`-d`, `--debug`	No	Enable debug logging.
`-s`, `--save-logs`	No	Save DEBUG-level logs under `<root-dir>/logs/`.
`-f`, `--fast`	No	Rule-based evaluation only.
`-D`, `--deep`	No	LLM-based evaluation only.

By default, evaluate uses both rule-based and LLM-based evaluation. Results are written into translation metadata and summarized in the console.

co-op-review¶

Run deterministic translation maintenance checks without API credentials.

Beta

co-op-review is a beta deterministic review command. It does not call model providers or write files, but its checks and issue output schema may evolve.

co-op-review -l "ko"

Typowe przykłady¶

Review Korean and Japanese translations from the current directory:

co-op-review -l "ko ja"

Review a specific project root:

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

Review only source files changed against a base ref:

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

Print GitHub-flavored Markdown output for CI summaries:

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

Opcje¶

Option	Required	Description
`-l`, `--language-code`	No	Language code to review. Can be passed multiple times or as a space-separated value. Defaults to all discovered translation languages.
`-r`, `--root-dir`	No	Project root. Defaults to the current directory.
`--changed-from`	No	Git ref used to limit review to changed source files.
`--format`	No	Output format: `text` or `github`. Defaults to `text`.

co-op-review currently checks for missing translated files, missing or stale translation metadata, Markdown frontmatter and code fence integrity, invalid translated notebook JSON, and missing local Markdown or image link targets. Missing links are warnings by default; structural and freshness problems fail the command.

co-op-translator-mcp¶

Run the Co-op Translator MCP server for agents, editors, and MCP-compatible clients.

co-op-translator-mcp

The default transport is stdio. See the Serwer MCP guide for client configuration, tools, resources, and safety notes.

Opcje¶

Option	Required	Description
`--transport`	No	MCP transport: `stdio`, `streamable-http`, or `sse`. Defaults to `stdio`.

migrate-links¶

Reprocess translated Markdown files and update notebook links so they point to translated notebooks when available.

migrate-links -l "ko ja"

Typowe przykłady¶

Preview link updates:

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

Process all supported languages without confirmation:

migrate-links -l "all" -y

Only rewrite links when translated notebooks exist:

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

Opcje¶

Option	Required	Description
`-l`, `--language-codes`	Yes	Space-separated language codes, or `"all"`.
`-r`, `--root-dir`	No	Project root. Defaults to the current directory.
`--image-dir`	No	Translated image directory relative to the root. Defaults to `translated_images`.
`--dry-run`	No	Show files that would change without writing updates.
`--fallback-to-original`, `--no-fallback-to-original`	No	Use original notebook links when translated notebooks are missing. Enabled by default.
`-d`, `--debug`	No	Enable debug logging.
`-s`, `--save-logs`	No	Save DEBUG-level logs under `<root-dir>/logs/`.
`-y`, `--yes`	No	Auto-confirm prompts when processing all languages.

Environment¶

All commands require one configured LLM provider:

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

# Lub OpenAI
OPENAI_API_KEY="..."
OPENAI_CHAT_MODEL_ID="gpt-4o"

Image translation additionally requires Azure AI Vision:

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

Output layout¶

Text translations are written under:

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

Translated image output is written under:

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

For example, translating README.md and docs/setup.md into Korean produces:

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

Przykłady CLI do kopiowania¶

Translate Markdown into three languages:

translate -l "ko ja fr" -md

Translate notebooks only:

translate -l "zh-CN" -nb

Translate images only:

translate -l "pt-BR" -img

Preview Markdown translation without writing files:

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

Repair low-confidence Markdown translations:

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

Run CI-friendly Markdown translation:

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

Review translated output:

co-op-review -l "ko ja"

Preview link migration:

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