md-bilingual-translate

name	md-bilingual-translate
description	Translate one Markdown file into a bilingual Markdown file with each original block followed by Simplified Chinese. Preserve formulas and code blocks. Use uv with httpx for high concurrency.

Markdown Bilingual Translate

Use this skill when you need to translate one Markdown file into Simplified Chinese while keeping bilingual Markdown output.

What It Does

• Input: one .md file
• Output: a new .md file
• Default output name: <input_stem>_zh.md (when input_stem > 60 chars, it is truncated to 60 chars first)
• For each translatable block:
  • keep the original block first
  • put the Chinese translation directly below it
• Preserve formulas and fenced code blocks

Runtime

• Main script: scripts/translate_md.py
• Python 3.8+
• High-concurrency mode: run with httpx via uv
• Fallback mode: plain Python standard library HTTP client

API Key

The script requires DEEPSEEK_API_KEY.

It looks for the key in this order:

1. DEEPSEEK_API_KEY in the current process environment
2. DEEPSEEK_API_KEY in %CODEX_HOME%\.env

Example:

DEEPSEEK_API_KEY=sk-your_api_key_here

Default API Settings

• API URL: https://api.deepseek.com/chat/completions
• Model: deepseek-v4-flash
• Thinking mode: disabled
• Temperature: 0.2
• User ID: md-bilingual-translate
• HTTP client: httpx when installed, otherwise urllib
• Default max workers: 64
• Default max grouped blocks per request: 4
• Max grouped input characters per request: 24000
• Max output tokens per request: 8192

Command

From the skill root:

uv run --with httpx python .\scripts\translate_md.py --input-path papers\example.md

This now defaults to the measured speed-oriented configuration:

• --model deepseek-v4-flash
• --max-workers 64
• --max-group-blocks 4
• --max-output-tokens 8192

The official account concurrency limit for deepseek-v4-flash is 2500, but this skill defaults to the measured fast-stable setting for Markdown papers: 64 workers and 4 grouped blocks per request. Raise workers only when a document creates far more than 64 request groups and metrics show few connection retries. Lower --max-workers to 32 when many retries, timeouts, or local socket errors appear.

The request shape uses OpenAI Chat Completions with non-thinking mode, low temperature, a shared httpx connection pool, and retries for HTTP 429, transient 5xx, redirects, and HTTPS connection failures.

Optional output path:

uv run --with httpx python .\scripts\translate_md.py `
  --input-path papers\example.md `
  --output-path papers\example_zh.md