The Microsoft Co-Op Translator is a powerful tool for translating Markdown documents seamlessly. This guide will help you troubleshoot common issues encountered when using the tool.
Problem: The translated Markdown document includes a markdown
tag at the top, causing rendering issues.
Solution: To resolve this, simply delete the markdown
tag at the top of the file. This will allow the Markdown file to render correctly.
Steps:
.md
) file.markdown
tag at the top of the document.markdown
tag.Problem: The URLs of embedded images do not match the language locale, leading to incorrect or missing images.
Solution: Check the URL of embedded images and ensure they match the language locale. All images are located in the translated_images
folder each image has a language locale tag in the image file name.
Steps:
Problem: The translated content is not accurate or requires further editing.
Solution: Review the translated document and make necessary edits to improve accuracy and readability.
Steps:
If images or text is not being translated to the correct language and when running in -d debug mode you experience 401 error. This is a classic authentication failure—either the key is invalid, expired, or not linked to the endpoint’s region.
Run co-op translator with the -d debug switch to gain further understanding of root cause.
Access denied due to invalid subscription key or wrong API endpoint.
Resource Type
Azure AI services
→ Vision
.Starting with the new selective translation system, Co-op Translator now provides explicit error messages when required services are not configured.
Problem: You requested image translation (-img
flag) but Azure AI Service is not properly configured.
Error Message:
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.
Solution:
AZURE_AI_SERVICE_API_KEY
to your .env
fileAZURE_AI_SERVICE_ENDPOINT
to your .env
file# Instead of: translate -l "ko" -img
# Use: translate -l "ko" -md
Problem: Essential LLM configuration is missing.
Error Message:
Error: No language model configuration found.
Please configure either Azure OpenAI or OpenAI in your .env file.
Solution:
.env
file has at least one of the following LLM configurations:
AZURE_OPENAI_API_KEY
and AZURE_OPENAI_ENDPOINT
OPENAI_API_KEY
You need either Azure OpenAI OR OpenAI configured, not both.
Problem: No files were translated even though the command succeeded.
Possible Causes:
-md
, -img
, -nb
)Solution:
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
Problem: Commands that relied on automatic markdown-only fallback no longer work as expected.
Old Behavior:
# This used to automatically switch to markdown-only mode
translate -l "ko" # (when Azure AI Vision was not configured)
New Behavior:
# This now produces an error if image translation is requested but not configured
translate -l "ko" -img
Solution:
translate -l "ko" -md # Only markdown
translate -l "ko" -md -img # Markdown and images
translate -l "ko" # Everything (if all services configured)
Problem: Links in translated files point to unexpected locations.
Cause: Dynamic link processing changes based on selected file types.
Solution:
-nb
included: Notebook links point to translated versions-nb
excluded: Notebook links point to original files-img
included: Image links point to translated versions-img
excluded: Image links point to original files# 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
When troubleshooting translation issues:
-d
flag to see detailed logs-md
, -img
, -nb
match your intent.env
file has required keys-md
only, then add other typesFor more detailed information about available commands and flags, see the Command Reference.