O Microsoft Co-Op Translator é uma ferramenta poderosa para traduzir documentos Markdown de forma simples e eficiente. Este guia vai ajudá-lo a resolver os problemas mais comuns encontrados ao utilizar a ferramenta.
Problema: O documento Markdown traduzido inclui uma tag markdown no topo, causando problemas de visualização.
Solução: Para resolver, basta eliminar a tag markdown no topo do ficheiro. Assim, o ficheiro Markdown será apresentado corretamente.
Passos:
.md) traduzido.markdown no topo do documento.markdown.Problema: Os URLs das imagens incorporadas não correspondem ao idioma do documento, resultando em imagens incorretas ou ausentes.
Solução: Verifique o URL das imagens incorporadas e confirme que correspondem ao idioma do documento. Todas as imagens estão na pasta translated_images e cada imagem tem uma etiqueta de idioma no nome do ficheiro.
Passos:
Problema: O conteúdo traduzido não está correto ou precisa de mais edição.
Solução: Reveja o documento traduzido e faça as edições necessárias para melhorar a precisão e a clareza.
Passos:
Se as imagens ou o texto não estão a ser traduzidos para o idioma correto e, ao executar em modo -d debug, aparece um erro 401, trata-se de uma falha clássica de autenticação — a chave é inválida, expirou ou não está associada à região do endpoint.
Execute o co-op translator com o parâmetro -d debug para obter mais detalhes sobre a causa do problema.
Access denied due to invalid subscription key or wrong API endpoint.Tipo de Recurso
Azure AI services → Vision.Com o novo sistema de tradução seletiva, o Co-op Translator agora apresenta mensagens de erro explícitas quando os serviços necessários não estão configurados.
Problema: Solicitou tradução de imagens (flag -img), mas o Azure AI Service não está devidamente configurado.
Mensagem de Erro:
Error: Image translation requested but Azure AI Service is not configured.
Please add AZURE_AI_SERVICE_API_KEY and AZURE_AI_SERVICE_ENDPOINT to your .env file.
Check Azure AI Service availability and configuration.
Solução:
AZURE_AI_SERVICE_API_KEY ao seu ficheiro .envAZURE_AI_SERVICE_ENDPOINT ao seu ficheiro .env# Instead of: translate -l "ko" -img
# Use: translate -l "ko" -md
Problema: Falta a configuração essencial do LLM.
Mensagem de Erro:
Error: No language model configuration found.
Please configure either Azure OpenAI or OpenAI in your .env file.
Solução:
.env tem pelo menos uma das seguintes configurações LLM:
AZURE_OPENAI_API_KEY e AZURE_OPENAI_ENDPOINTOPENAI_API_KEYPrecisa de ter Azure OpenAI OU OpenAI configurado, não ambos.
Problema: Nenhum ficheiro foi traduzido, mesmo que o comando tenha sido executado com sucesso.
Possíveis Causas:
-md, -img, -nb)Solução:
translate -l "ko" -md -d
# For markdown files
find . -name "*.md" -not -path "./translations/*"
# For notebooks
find . -name "*.ipynb" -not -path "./translations/*"
# For images
find . -name "*.png" -o -name "*.jpg" -o -name "*.jpeg" -not -path "./translations/*"
# Translate everything (default)
translate -l "ko"
# Translate specific types
translate -l "ko" -md -img
Problema: Comandos que dependiam do modo automático só-markdown já não funcionam como antes.
Comportamento Antigo:
# This used to automatically switch to markdown-only mode
translate -l "ko" # (when Azure AI Vision was not configured)
Novo Comportamento:
# This now produces an error if image translation is requested but not configured
translate -l "ko" -img
Solução:
translate -l "ko" -md # Only markdown
translate -l "ko" -md -img # Markdown and images
translate -l "ko" # Everything (if all services configured)
Problema: Os links nos ficheiros traduzidos apontam para locais inesperados.
Causa: O processamento dinâmico de links muda consoante os tipos de ficheiro selecionados.
Solução:
-nb: Os links dos notebooks apontam para as versões traduzidas-nb: Os links dos notebooks apontam para os ficheiros originais-img: Os links das imagens apontam para as versões traduzidas-img: Os links das imagens apontam para os ficheiros originais# All internal links point to translated versions
translate -l "ko" -md -img -nb
# Only markdown translated, other links point to originals
translate -l "ko" -md
Sintoma: Os registos do workflow para peter-evans/create-pull-request mostram:
Branch ‘update-translations’ is not ahead of base ‘main’ and will not be created
Causas prováveis:
.gitignore exclui ficheiros que espera que sejam commitados (ex: *.ipynb, translations/, translated_images/).Como corrigir / verificar:
translations/ e/ou translated_images/.
.ipynb são realmente escritos em translations/<lang>/.....gitignore: Não ignore as saídas geradas. Certifique-se de que NÃO está a ignorar:
translations/translated_images/*.ipynb (se traduzir notebooks)with:
add-paths: |
translations/
translated_images/
with:
commit-empty: true
-d ao comando de tradução para ver que ficheiros foram detetados e escritos.permissions:
contents: write
pull-requests: write
Ao resolver problemas de tradução:
-d para ver registos detalhados-md, -img, -nb correspondem ao que pretende.env tem as chaves necessárias-md, depois adicione outros tiposPara mais informações sobre comandos e flags disponíveis, consulte a Referência de Comandos.
Aviso Legal: Este documento foi traduzido utilizando o serviço de tradução automática Co-op Translator. Embora nos esforcemos pela precisão, esteja ciente de que traduções automáticas podem conter erros ou imprecisões. O documento original, na sua língua nativa, deve ser considerado a fonte autorizada. Para informações críticas, recomenda-se a tradução profissional humana. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações incorretas resultantes da utilização desta tradução.