Build a Markdown Translation Tool with AI APIs in 50 Lines of Python

xuks124 — Fri, 24 Apr 2026 10:35:17 +0000

Why I Built This

I write documentation in Chinese, but my readers are everywhere. Manually translating each .md file was killing my productivity. Worse, keeping translations in sync with updates was a nightmare.

I needed a tool that could batch-translate entire documentation folders while preserving every # header, **bold**, `code`, and [link]() perfectly. So I built one.

The result is md-translator — a lightweight Python script that uses any OpenAI-compatible API to translate Markdown files in bulk. It's under 200 lines, supports concurrent processing, and costs pennies per project.

Let me show you how it works.

What You'll Build

A CLI tool that:

Batch translates all .md files in a directory
Supports any OpenAI-compatible API (DeepSeek, GPT, Qwen, etc.)
Preserves every bit of Markdown formatting
Caches translations for resume support
Runs concurrent translations with configurable workers

Setup

Requires Python 3.8+ and one dependency:

pip install requests
git clone https://github.com/xuks124/md-translator.git
cd md-translator

Set your API key:

export MD_TRANSLATOR_KEY="sk-your-api-key-here"

Core Translation Logic

The core is an API call to any OpenAI-compatible chat endpoint. Here's the key function:

def translate_chunk(chunk, source_lang, target_lang, api_key, api_url, model):
    prompt = f"""You are a professional translator. Translate from {source_lang} to {target_lang}.
Rules:
1. Keep ALL Markdown syntax unchanged (```
{% endraw %}
, **, [], ![], #, -, etc.)
2. Only translate text content
3. Keep code blocks and URLs unchanged
4. Return ONLY the translated content

Content:
---
{chunk}
---"""

    resp = requests.post(
        api_url,
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        },
        json={
            "model": model,
            "messages": [{"role": "user", "content": prompt}],
            "temperature": 0.3,
            "max_tokens": 4096
        },
        timeout=60
    )
    return resp.json()["choices"][0]["message"]["content"]
{% raw %}

The prompt is the secret sauce. By telling the model to keep syntax unchanged, we get clean Markdown out every time.

Batch Processing with Resume Support

Translation can take time, so the tool caches results by file hash. If you rerun it, already-translated files are skipped instantly:


python
def process_file(md_path, source_lang, target_lang, api_key, api_url, model, output_dir, force):
    content = open(md_path, encoding='utf-8').read()
    content_hash = hashlib.md5(content.encode()).hexdigest()[:8]

    # Load cache — resume from breakpoint
    cache_file = Path(md_path.parent / '.md_translator_cache' / f"{md_path.stem}.json")
    cache = json.load(open(cache_file)) if cache_file.exists() else {}

    if not force and content_hash in cache:
        translated = cache[content_hash]  # Cache hit!
    else:
        # Split long files into chunks
        if len(content) > 4000:
            chunks = [content[i:i+3000] for i in range(0, len(content), 3000)]
            translated = '\n'.join(translate_chunk(c, ...) for c in chunks)
        else:
            translated = translate_chunk(content, ...)

        cache[content_hash] = translated
        json.dump(cache, open(cache_file, 'w'))

    # Output: suffix-based naming (e.g., doc.en.md)
    output_path = md_path.parent / md_path.name.replace('.md', f'.{target_lang}.md')
    open(output_path, 'w', encoding='utf-8').write(translated)

For large documentation sites, the tool uses ThreadPoolExecutor to translate multiple files concurrently:


python
with ThreadPoolExecutor(max_workers=args.workers) as executor:
    futures = {executor.submit(process_file, f, ...): f for f in md_files}
    for future in as_completed(futures):
        output = future.result()

Running It


bash
# Translate all files in ./docs from Chinese to English
python translate.py --input ./docs --source zh --target en

# Use GPT-4o instead of default DeepSeek
python translate.py -i ./docs -s zh -t en -m gpt-4o -u https://api.openai.com/v1

# Force re-translate everything
python translate.py -i ./docs -s zh -t en -f

# 5 concurrent workers for big projects
python translate.py -i ./docs -s zh -t en -w 5 -o ./translations

Why OpenAI-Compatible APIs?

Lock-in is annoying. This tool works with any provider that speaks the OpenAI chat format:

DeepSeek (free tier available)
OpenAI (GPT-4o / GPT-4o-mini)
One-API (self-hosted unified gateway)
Qwen / Moonshot / Groq (all OpenAI-compatible)

Just swap --api-url and --model — no code changes needed.

Real-World Usage

I use this to keep my programming handbook in 3 languages. A full translation of 400+ files runs in about 15 minutes and costs less than $2 with DeepSeek.

Format preservation is the killer feature — tables, code blocks with syntax highlighting, nested lists, embedded images — everything stays intact.

Try It Yourself

The full source is on GitHub:

https://github.com/xuks124/md-translator

It's MIT licensed, so fork it, tweak it, use it for your docs. If you build something cool with it, drop a star or open an issue.

Happy translating!

Building an AI API Gateway with One-API: A Practical Guide

xuks124 — Fri, 24 Apr 2026 10:32:29 +0000

Building an AI API Gateway with One-API: A Practical Guide

Why You Need an AI API Gateway

It's 2026. Every AI company ships its own API — OpenAI, Claude, Gemini, DeepSeek, Qwen... If you're building anything real, you're likely juggling 3+ different API keys, billing dashboards, and SDKs.

One-API is an open-source unified gateway that solves this:

Single endpoint for all major LLM providers
Load balancing and failover between models
Token quota management per user/group
Usage analytics and cost tracking

Setup in Under 5 Minutes

Docker Deployment

docker pull justsong/one-api
docker run -d --restart always \\
  --name one-api \\
  -p 3000:3000 \\
  -v /data/one-api:/data \\
  justsong/one-api

Visit http://your-server:3000. Default login: root / 123456 — change this immediately.

Adding Your First Channel (Aliyun Bailian Example)

# Login
curl -X POST http://localhost:3000/api/user/login \\
  -H 'Content-Type: application/json' \\
  -d '{"username":"root", "password": "***"}'

# Add channel
curl http://localhost:3000/api/channel/ \\
  -X POST \\
  -H 'Content-Type: application/json' \\
  -d '{
    "name": "Aliyun Bailian",
    "type": 41,
    "key": "sk-your-bailian-key",
    "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
    "models": "qwen-plus,qwen-turbo"
  }'

Pro tip: One-API v0.12.x has a bug where POST to /api/channel/ panics. Use PUT to update an existing channel instead.

Client Usage

Once configured, all models are accessed via a single OpenAI-compatible endpoint:

from openai import OpenAI

client = OpenAI(
    api_key="your-one-api-token",
    base_url="http://your-server:3000/v1"
)

response = client.chat.completions.create(
    model="qwen-plus",
    messages=[{"role": "user", "content": "Hello"}]
)
print(response.choices[0].message.content)

Essential Security Hardening

After deployment, do this immediately:

Disable open registration — turn off public signups
Enable CORS restrictions — don't leave Access-Control-Allow-Origin: *
Rate limiting — set 60 req/min per user as a baseline
HTTPS — put Nginx in front with a Let's Encrypt cert
Regular admin password rotation — use strong 16+ char passwords

Cost Optimization Strategy

With a unified gateway, you can route tasks to the cheapest adequate model:

Chat/QA: qwen-turbo or deepseek-chat ($0.02-0.05/1M tokens)
Code generation: claude-3-haiku or gpt-4o-mini
Complex reasoning: claude-3.5-sonnet or gpt-4o
Batch processing: route to cheapest model with retry fallback

Real-world result: 40-70% cost reduction vs. using premium models for everything.

Why I Built This

I needed a way to serve multiple users across my team without giving each one 5 different API keys. One-API handles quotas, tracks usage, and lets me add new model providers in 30 seconds via the dashboard.

Check out my open-source tools: md-translator — batch translate Markdown files using AI.

DEV Community: xuks124

Build a Markdown Translation Tool with AI APIs in 50 Lines of Python

Why I Built This

What You'll Build

Setup

Core Translation Logic

Batch Processing with Resume Support

Running It

Why OpenAI-Compatible APIs?

Real-World Usage

Try It Yourself

Building an AI API Gateway with One-API: A Practical Guide

Building an AI API Gateway with One-API: A Practical Guide

Why You Need an AI API Gateway

Setup in Under 5 Minutes

Docker Deployment

Adding Your First Channel (Aliyun Bailian Example)

Client Usage

Essential Security Hardening

Cost Optimization Strategy

Why I Built This