Riferimento CLI¶
Co-op Translator installa questi punti di ingresso della riga di comando:
translateevaluatemigrate-linksco-op-reviewco-op-translator-mcp
I comandi translate, evaluate, migrate-links e co-op-review vengono instradati tramite co_op_translator.__main__, che seleziona l'implementazione del comando in base al nome dello script invocato. Il server MCP usa co_op_translator.mcp.server direttamente.
Se stai decidendo tra CLI, API Python e MCP, inizia con Scegli il tuo flusso di lavoro.
Output della console¶
I terminali interattivi utilizzano la formattazione Rich per l'intestazione dei comandi, il progresso e i riepiloghi. L'output per CI e non interattivo passa automaticamente al testo semplice.
Imposta CO_OP_TRANSLATOR_OUTPUT_STYLE=plain per forzare l'output in testo semplice, oppure CO_OP_TRANSLATOR_OUTPUT_STYLE=rich per forzare l'output Rich. Imposta CO_OP_TRANSLATOR_NO_PROGRESS=1 per mantenere i riepiloghi sopprimendo le barre di avanzamento live.
Usa translate --json-events progress.ndjson quando un altro sistema ha bisogno
di un progresso leggibile dalla macchina. La CLI continua a rendere l'output per gli utenti umani, mentre
il file NDJSON riceve eventi versionati co-op.translation.event.v1 con
campi stabili come type, stage_key, completed, total e
current_path.
Flusso iniziale della CLI¶
Inizia qui se usi Co-op Translator da un terminale:
- Configura un provider LLM come descritto in Configurazione.
- Scegli il tipo di contenuto che vuoi tradurre.
- Esegui prima un comando mirato, come la traduzione solo Markdown.
- Usa
--dry-runprima di grandi modifiche al repository. - Usa
co-op-reviewdopo la traduzione per verificare struttura e freschezza.
| Obiettivo | Comando con cui iniziare |
|---|---|
| Tradurre documenti Markdown | translate -l "ko" -md |
| Tradurre notebook | translate -l "ko" -nb |
| Tradurre testo dalle immagini | translate -l "ko" -img |
| Visualizzare in anteprima senza scrivere file | translate -l "ko" -md --dry-run |
| Revisionare traduzioni esistenti | co-op-review -l "ko" |
| Aggiornare i link di notebook e Markdown | migrate-links -l "ko" --dry-run |
| Esporre gli strumenti a un client MCP | Configura il Server MCP invece di eseguire direttamente i comandi CLI. |
translate¶
Traduci file Markdown, notebook e testo nelle immagini in una o più lingue di destinazione.
Esempi comuni¶
Translate only Markdown:
Translate only notebooks:
Translate Markdown and images:
Aggiorna le traduzioni esistenti eliminandole e ricreandole:
Run without interactive prompts:
Save logs:
Write structured progress events:
Opzioni¶
| Option | Required | Description |
|---|---|---|
-l, --language-codes |
Sì | Codici lingua separati da spazi, come "es fr de", oppure "all". |
-r, --root-dir |
No | Radice del progetto. Predefinita la directory corrente. |
-u, --update |
No | Elimina le traduzioni esistenti per le lingue selezionate e le ricrea. |
-img, --images |
No | Traduci solo i file immagine. |
-md, --markdown |
No | Traduci solo i file Markdown. |
-nb, --notebook |
No | Traduci solo i file Jupyter notebook. |
-d, --debug |
No | Abilita il logging di debug nella console. |
-s, --save-logs |
No | Salva i log a livello DEBUG in <root-dir>/logs/. |
--json-events |
No | Scrive eventi di progresso della traduzione leggibili dalla macchina in formato NDJSON. |
-x, --fix |
No | Ritradurre file Markdown a bassa confidenza basandosi sui risultati di valutazioni precedenti. |
-c, --min-confidence |
No | Soglia di confidenza per --fix. Predefinita 0.7. |
--add-disclaimer, --no-disclaimer |
No | Aggiunge o sopprime il disclaimer di traduzione automatica. Di default è abilitato nella CLI. |
-f, --fast |
No | Modalità rapida per immagini deprecata. |
-y, --yes |
No | Conferma automaticamente i prompt, utile in CI. |
--repo-url |
No | URL del repository usato nella tabella delle lingue del README per il suggerimento sul sparse-checkout. |
--migrate-language-folders |
No | Rinomina le cartelle alias legacy, come cn o tw, in cartelle canoniche BCP 47. |
--dry-run |
No | Anteprima della migrazione delle cartelle per lingua e delle stime di traduzione senza scrivere file. |
Se non viene fornito il flag di tipo, translate elabora Markdown, notebook e immagini. La traduzione delle immagini richiede la configurazione di Azure AI Vision.
evaluate¶
Valuta la qualità del Markdown tradotto per una lingua.
Sperimentale
evaluate è sperimentale. Può utilizzare controlli di qualità basati su regole e su LLM, scrive i risultati della valutazione nei metadati della traduzione e il suo modello di punteggio e il comportamento dei metadati potrebbero cambiare.
Esempi comuni¶
Usa una soglia di confidenza bassa più rigorosa:
Run rule-based checks only:
Run LLM-based checks only:
Opzioni¶
| Option | Required | Description |
|---|---|---|
-l, --language-code |
Sì | Singolo codice lingua da valutare. I codici alias sono normalizzati. |
-r, --root-dir |
No | Radice del progetto. Predefinita la directory corrente. |
-c, --min-confidence |
No | Soglia usata quando si elencano traduzioni a bassa confidenza. Predefinita 0.7. |
-d, --debug |
No | Abilita il logging di debug. |
-s, --save-logs |
No | Salva i log a livello DEBUG in <root-dir>/logs/. |
-f, --fast |
No | Solo valutazione basata su regole. |
-D, --deep |
No | Solo valutazione basata su LLM. |
Per impostazione predefinita, evaluate utilizza sia una valutazione basata su regole che su LLM. I risultati vengono scritti nei metadati della traduzione e riepilogati nella console.
co-op-review¶
Esegui controlli deterministici di manutenzione della traduzione senza credenziali API.
Beta
co-op-review è un comando di revisione deterministico in beta. Non chiama provider di modelli né scrive file, ma i suoi controlli e lo schema di output delle issue potrebbero evolvere.
Esempi comuni¶
Rivedi le traduzioni in coreano e giapponese dalla directory corrente:
Review a specific project root:
Rivedi solo il README dopo una traduzione che riguarda soltanto il README:
--readme-only ignora altri documenti e i README annidati. Fallisce se il README principale
README.md manca. Combinato con --changed-from, esamina solo il README
quando quel file sorgente è cambiato. La traduzione solo del README lascia il README sorgente
invariato, inclusi eventuali marcatori di sezione condivisa.
Revisiona solo i file sorgente modificati rispetto a un riferimento base:
Stampa l'output Markdown in stile GitHub per i sommari CI:
Opzioni¶
| Option | Required | Description |
|---|---|---|
-l, --language-code |
No | Codice lingua da controllare. Può essere passato più volte o come valore separato da spazi. Predefinito: tutte le lingue di traduzione rilevate. |
-r, --root-dir |
No | Radice del progetto. Predefinita la directory corrente. |
--changed-from |
No | Ref Git usato per limitare il controllo ai file sorgente modificati. |
--readme-only |
No | Controlla solo la traduzione del README.md radice. |
--format |
No | Formato di output: text o github. Predefinito text. |
co-op-review attualmente verifica la presenza di file tradotti mancanti, metadati di traduzione mancanti o obsoleti, l'integrità del frontmatter Markdown e delle code fence, JSON di notebook tradotto non valido e destinazioni di link locali a Markdown o immagini mancanti. I link mancanti sono avvisi per impostazione predefinita; problemi strutturali e di aggiornamento fanno fallire il comando.
co-op-translator-mcp¶
Esegui il server MCP di Co-op Translator per agenti, editor e client compatibili con MCP.
Il trasporto predefinito è stdio. Consulta la guida Server MCP per la configurazione dei client, gli strumenti, le risorse e le note sulla sicurezza.
Opzioni¶
| Option | Required | Description |
|---|---|---|
--transport |
No | MCP transport: stdio, streamable-http, or sse. Predefinito stdio. |
migrate-links¶
Rielabora i file Markdown tradotti e aggiorna i link ai notebook in modo che puntino ai notebook tradotti quando disponibili.
Esempi comuni¶
Preview link updates:
Elabora tutte le lingue supportate senza conferma:
Riscrivi i collegamenti solo quando esistono notebook tradotti:
Opzioni¶
| Option | Required | Description |
|---|---|---|
-l, --language-codes |
Sì | Codici lingua separati da spazi, o "all". |
-r, --root-dir |
No | Radice del progetto. Predefinita la directory corrente. |
--image-dir |
No | Directory delle immagini tradotte relativa alla radice. Predefinita translated_images. |
--dry-run |
No | Mostra i file che verrebbero modificati senza scrivere aggiornamenti. |
--fallback-to-original, --no-fallback-to-original |
No | Usa i link ai notebook originali quando i notebook tradotti sono mancanti. Abilitato di default. |
-d, --debug |
No | Abilita il logging di debug. |
-s, --save-logs |
No | Salva i log a livello DEBUG in <root-dir>/logs/. |
-y, --yes |
No | Conferma automaticamente i prompt quando si elaborano tutte le lingue. |
Environment¶
Quando un comando richiede credenziali del provider, configura uno di questi set di provider. translate --dry-run e co-op-review non richiedono credenziali del 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"
# O OpenAI
OPENAI_API_KEY="..."
OPENAI_CHAT_MODEL_ID="gpt-4o"
# O Anthropic
ANTHROPIC_API_KEY="..."
ANTHROPIC_MODEL="claude-..."
La traduzione delle immagini richiede inoltre Azure AI Vision:
AZURE_AI_SERVICE_API_KEY="..."
AZURE_AI_SERVICE_ENDPOINT="https://<resource>.cognitiveservices.azure.com/"
Layout dell'output¶
Text translations are written under:
L'output delle immagini tradotte viene scritto in:
For example, translating README.md and docs/setup.md into Korean produces:
Esempi CLI da copiare e incollare¶
Translate Markdown into three languages:
Translate notebooks only:
Translate images only:
Anteprima della traduzione Markdown senza scrivere file:
Repair low-confidence Markdown translations:
Run CI-friendly Markdown translation:
Review translated output:
Preview link migration: