O Microsoft Co-Op Translator é uma ferramenta poderosa para traduzir documentos Markdown de forma simples e eficiente. Este guia vai te ajudar a resolver os problemas mais comuns ao usar a ferramenta.
Problema: O documento Markdown traduzido inclui uma tag markdown no topo, causando problemas de renderização.
Solução: Para resolver, basta apagar a tag markdown do topo do arquivo. Assim, o arquivo Markdown será renderizado corretamente.
Passos:
.md) traduzido.markdown no topo do documento.markdown.Problema: As URLs das imagens embutidas não correspondem ao idioma do documento, resultando em imagens erradas ou ausentes.
Solução: Verifique a URL das imagens embutidas e garanta que estejam no idioma correto. Todas as imagens ficam na pasta translated_images e cada imagem tem uma tag de idioma no nome do arquivo.
Passos:
Problema: O conteúdo traduzido não está preciso ou precisa de ajustes.
Solução: Revise o documento traduzido e faça os ajustes necessários para melhorar a precisão e a clareza.
Passos:
Se imagens ou textos não estão sendo traduzidos corretamente e, ao rodar em modo -d debug, você recebe erro 401, trata-se de uma falha de autenticação—ou a chave está inválida, expirada ou não vinculada à região do endpoint.
Execute o co-op translator com o parâmetro -d debug para entender melhor a causa raiz.
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 mostra mensagens de erro explícitas quando serviços obrigatórios não estão configurados.
Problema: Você solicitou tradução de imagens (flag -img), mas o Azure AI Service não está configurado corretamente.
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 arquivo .envAZURE_AI_SERVICE_ENDPOINT ao seu arquivo .env# Instead of: translate -l "ko" -img
# Use: translate -l "ko" -md
Problema: Configuração essencial do LLM está faltando.
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 de LLM:
AZURE_OPENAI_API_KEY e AZURE_OPENAI_ENDPOINTOPENAI_API_KEYVocê precisa configurar Azure OpenAI OU OpenAI, não ambos.
Problema: Nenhum arquivo foi traduzido, mesmo com o comando 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 fallback automático para markdown não funcionam mais 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: Links em arquivos traduzidos apontam para locais inesperados.
Causa: O processamento dinâmico de links muda conforme os tipos de arquivo selecionados.
Solução:
-nb: Links de notebooks apontam para versões traduzidas-nb: Links de notebooks apontam para arquivos originais-img: Links de imagens apontam para versões traduzidas-img: Links de imagens apontam para arquivos 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 logs 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 arquivos que você espera commitar (ex: *.ipynb, translations/, translated_images/).Como corrigir / verificar:
translations/ e/ou translated_images/.
.ipynb estão realmente em translations/<lang>/.....gitignore: Não ignore as saídas geradas. Certifique-se de NÃO 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 mostrar quais arquivos foram encontrados e escritos.permissions:
contents: write
pull-requests: write
Ao resolver problemas de tradução:
-d para ver logs detalhados-md, -img, -nb correspondem ao que você quer.env tem as chaves necessárias-md, depois adicione outros tiposPara mais detalhes sobre comandos e flags disponíveis, veja a Referência de Comandos.
Aviso Legal: Este documento foi traduzido utilizando o serviço de tradução por IA 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 em seu idioma nativo 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 decorrentes do uso desta tradução.