Mandarin Skill for OpenClaw

Translate English phrases into Mandarin Chinese with pinyin, pronunciation guides, audio, interactive HTML lessons, and Telegram delivery.

Invoke with /mandarin <phrase> in any connected chat.

Installation

Via ClawHub

clawhub install mandarin

Manual

Clone this repo into your OpenClaw skills directory:

git clone https://github.com/nickholub/mandarin-skill.git ~/.openclaw/skills/mandarin

Or, for a workspace-specific install:

git clone https://github.com/nickholub/mandarin-skill.git /path/to/workspace/skills/mandarin

OpenClaw loads skills from these locations (highest priority first):

1. <workspace>/skills/
2. ~/.openclaw/skills/
3. Bundled skills

Prerequisites

• Python 3 (standard library only, no pip packages required)
• Mandarin TTS tool at one of:
  • ~/projects/mandarin_voice/mandarin_audio.py
  • ~/projects/mandarin-audio/mandarin_audio.py
• Telegram integration configured in OpenClaw (for message delivery)

Usage

/mandarin I want to order coffee

The skill runs a deterministic pipeline:

1. Translates the phrase into natural Mandarin and produces structured JSON
2. Sends the text breakdown to Telegram immediately (phrase, pinyin, English-style pronunciation, word-by-word list with grammar notes)
3. Runs pipeline.py which handles all remaining steps automatically:
   • Builds lesson markdown (compatible with TTS tool)
   • Checks audio cache for each phrase/word
   • Runs TTS for cache misses (single invocation)
   • Caches new audio with deduplication (by meaning + file hash)
   • Renders interactive HTML lesson with play buttons
4. Sends audio files and lesson path as Telegram follow-ups

Output

Output	Location
Audio files (MP3)	/Users/Shared/mandarin/audio/
Audio index	/Users/Shared/mandarin/audio/index.json
HTML lessons	/Users/Shared/mandarin/<phrase>.html
Temp files	~/.openclaw/workspace/.tmp/mandarin/

HTML lessons include per-word play buttons — green for cached MP3 playback, yellow for browser speech synthesis fallback.

Scripts

scripts/pipeline.py

Main orchestrator. Takes translation JSON and runs the full pipeline. Outputs a JSON status report.

# Full pipeline
python3 scripts/pipeline.py --json input.json

# Skip TTS (HTML will use browser TTS fallback)
python3 scripts/pipeline.py --json input.json --skip-tts

# Override TTS tool location
python3 scripts/pipeline.py --json input.json --tts-tool /path/to/mandarin_audio.py

# Pipe from stdin
echo '{"phrase_english":"hello",...}' | python3 scripts/pipeline.py

scripts/build_lesson_md.py

Converts structured translation JSON into deterministic lesson markdown.

# File to stdout
python3 scripts/build_lesson_md.py --json input.json

# File to file
python3 scripts/build_lesson_md.py --json input.json --out lesson.md

# Stdin to file
cat input.json | python3 scripts/build_lesson_md.py --out lesson.md

scripts/audio_cache.py

Caches and deduplicates TTS audio files. Two-tier dedup: by semantic meaning first, then by file content (SHA-256).

# Check if audio already exists
python3 scripts/audio_cache.py --lookup-only --meaning "hello"
# exit 0 = cache hit (prints path), exit 2 = miss

# Cache a new audio file
python3 scripts/audio_cache.py \
  --src /path/to/file.mp3 \
  --english-label "hello" \
  --meaning "hello" \
  --chinese "你好"

scripts/html_with_relative_audio.py

Renders a lesson markdown file into a self-contained HTML page with audio play buttons.

python3 scripts/html_with_relative_audio.py \
  --md /path/to/lesson.md \
  --out /path/to/output.html \
  --index /Users/Shared/mandarin/audio/index.json

Running Tests

python3 -m pytest tests/ -v

Repository Structure

SKILL.md                           # Skill definition (loaded by OpenClaw)
CLAUDE.md                          # Development instructions
scripts/
  pipeline.py                      # Main orchestrator (JSON → markdown → audio → HTML)
  build_lesson_md.py               # JSON → lesson markdown converter
  audio_cache.py                   # Audio caching/dedup utility
  html_with_relative_audio.py      # Markdown → HTML renderer with play buttons
  template.html                    # HTML template for lesson pages
tests/
  test_pipeline.py                 # Tests for pipeline.py
  test_build_lesson_md.py          # Tests for build_lesson_md.py
  test_audio_cache.py              # Tests for audio_cache.py
  test_html_renderer.py            # Tests for html_with_relative_audio.py