Markdown Translation CLI

版本：0.5.4

A general-purpose Markdown translation tool powered by Azure OpenAI. Translate Markdown files from any source language to any target language while preserving Markdown structure, code blocks, links, and formatting.

Defaults: English (en) → Traditional Chinese (zh-tw), but both are configurable.

Requirements

• Node.js 18 or newer
• Azure OpenAI credentials (API key, endpoint, deployment name, API version)

Quick Start (Local)

1. Install dependencies:

   npm install

2. Configure Azure OpenAI:

   cp .env.example .env
   # Edit .env with your Azure OpenAI credentials and preferences

3. Run translation:

   # Full translation of all markdown files
   npm run translate
      
   # Demo with sample file
   npm run demo
      
   # Basic functionality tests
   npm test

4. Promote zh-tw as default filenames (optional, dry-run by default):

   # Preview planned changes (no modifications)
   npm run promote:zh-tw-default
   
   # Apply changes (rename *.md -> *.en.md, then promote *_zh-tw.md -> *.md)
   npm run promote:zh-tw-default -- --execute
   
   # Apply changes and overwrite if destination exists
   npm run promote:zh-tw-default -- --execute --force
   
   # Limit scope via input glob (use -i/--input)
   # Example: only process zh-tw files under docs/
   npm run promote:zh-tw-default -- -i "docs/**/*_zh-tw.md"
   
   # Combine with execute
   npm run promote:zh-tw-default -- --execute -i "docs/**/*_zh-tw.md"

5. Demote zh-tw default back to en (optional, dry-run by default):

   # Preview planned changes (no modifications)
   npm run demote:zh-tw-default
   
   # Apply changes (rename *.md -> *_zh-tw.md, then promote *.en.md -> *.md)
   npm run demote:zh-tw-default -- --execute
   
   # Apply changes and overwrite if destination exists
   npm run demote:zh-tw-default -- --execute --force
   
   # Limit scope via input glob (use -i/--input)
   # Example: only process en files under docs/
   npm run demote:zh-tw-default -- -i "docs/**/*.en.md"
   
   # Combine with execute
   npm run demote:zh-tw-default -- --execute -i "docs/**/*.en.md"

CLI Installation

You can install this package globally to use the CLI anywhere:

npm install -g @willh/translator

Then run the translator with:

translator --help

Examples:

# Use .env values and translate all markdown files
translator

# Print effective config (redacted) and exit
translator --print-config

# Preview translation plan and verify API connectivity (no changes)
translator --dry-run

# Clean: delete translated files (interactive)
translator --clean

# Provide config via flags
translator \
  --azure-api-key $AZURE_OPENAI_API_KEY \
  --azure-endpoint "https://<resource>.openai.azure.com" \
  --deployment gpt-4.1 \
  --api-version 2025-01-01-preview \
  --input "docs/**/*.md" \
  --source-language en \
  --target-language zh-tw \
  --output-suffix _zh-tw \
  --dictionary translation-dictionary.json \
  --backup false \
  --max-retries 3 \
  --quality-threshold 7 \
  --log-level info \
  --log-file translation.log

# Translate a single file
translator -i README.md

# Translate files from a list (file-list.txt contains file paths, one per line)
translator -f file-list.txt

# Promote zh-tw as the default filenames (optional utility)
promote-zh-tw-default --execute --force

# Demote zh-tw default back to en (optional utility)
demote-zh-tw-default --execute --force

Copy files by glob (optional utility)

使用 copy-glob 依照 glob 路徑樣式複製檔案，並保留相對目錄結構。

# 以 npm scripts 執行
npm run copy-glob -- -i 'examples/**/*.md' -o out-dir

# 以全域 CLI 執行（若已全域安裝）
copy-glob -i 'examples/**/*.md' -o out-dir

# 目的地已有檔案時覆蓋
copy-glob -i 'examples/**/*.md' -o out-dir --force

# 複製時移除檔名後綴（副檔名之前）
# 精準匹配 *_zh-tw.md，例：README_zh-tw.md -> README.md
copy-glob -i 'examples/**/*_zh-tw.md' -o out-dir --remove-suffix _zh-tw

# 同時移除後綴並覆蓋
copy-glob -i 'examples/**/*_zh-tw.md' -o out-dir --remove-suffix _zh-tw --force

注意：

• 請以引號包住 glob（例如 'examples/**/*.md'）以避免 shell 預先展開。
• 預設不覆蓋既有檔案；若需要覆蓋請加上 --force。
• 若來源檔案位於輸出資料夾中，工具會自動略過以避免遞迴複製。
• 需要更詳細的處理過程（例如每個檔案的來源與目的地、略過原因），可加上 --verbose。

CLI Options

Required:

• --azure-api-key — Azure OpenAI API key [env: AZURE_OPENAI_API_KEY]
• --azure-endpoint — Azure OpenAI endpoint [env: AZURE_OPENAI_ENDPOINT]

Optional:

• -i, --input — Glob for input markdown [env: INPUT_PATTERN, default: **/*.md]
• -f, --file-list — Path to text file containing list of files to translate (one per line, # for comments) [env: FILE_LIST_PATH]
• --source-language — Source language [env: SOURCE_LANGUAGE, default: en]
• --target-language — Target language [env: TARGET_LANGUAGE, default: zh-tw]
• --output-suffix — Output filename suffix [env: OUTPUT_SUFFIX, default: _zh-tw]
• --dictionary — Dictionary JSON path [env: DICTIONARY_FILE, default: translation-dictionary.json]
• --backup <true|false> — Backup originals [env: BACKUP_ORIGINAL, default: false]
• --max-retries — Retries per file [env: MAX_RETRIES, default: 3]
• --concurrent-limit — Max concurrent translations (files/sections) [env: CONCURRENT_LIMIT, default: 4]
• --quality-threshold — Minimum quality score [env: QUALITY_THRESHOLD, default: 7]
• --log-level — Log level [env: LOG_LEVEL, default: info]
• --log-file — Log file path [env: LOG_FILE, default: translation.log]
• --deployment — Azure deployment/model [env: AZURE_OPENAI_DEPLOYMENT_NAME, default: gpt-4.1]
• --api-version — Azure API version [env: AZURE_OPENAI_API_VERSION, default: 2025-01-01-preview]
• --print-config — Print effective config (redacted) and exit
• --dry-run — List planned files and run a 1‑token Azure API probe
• --clean — Delete files matching *<OUTPUT_SUFFIX>.md with interactive confirm (press Y/y to proceed)
• --glossary-suggest-limit — Max LLM glossary suggestions per file [env: GLOSSARY_SUGGEST_LIMIT, default: 3]
• --glossary-suggest-max-items — Max pairs per suggestion call [env: GLOSSARY_SUGGEST_MAX_ITEMS, default: 5]

Behavior:

• Files already containing the output suffix (e.g., *_zh-tw.md) are always excluded and will not be translated again.

Notes:

• You can provide values via CLI flags, environment variables, or a .env file.
• Use -i/--input to specify which files to translate via glob pattern (e.g., docs/**/*.md).
• Use -f/--file-list to provide a text file containing file paths (one per line). Comments start with # and blank lines are ignored.
• Quote glob patterns for -i/--input to prevent your shell from expanding them. Example: -i 'docs/**/*.md' or set INPUT_PATTERN='docs/**/*.md'. If you don't quote, the shell may expand to many files and only the first one will be used by -i.
• Incremental by default: if a target file like *_zh-tw.md already exists, it is skipped. Use --force to overwrite.

File List Format

When using -f/--file-list, create a text file with one file path per line:

# This is a comment - lines starting with # are ignored
# Blank lines are also ignored

docs/README.md
docs/guide/getting-started.md

# You can add comments to organize your list
src/documentation/api.md
src/documentation/examples.md

This is useful for:

• Translating a specific subset of files
• Maintaining a curated list of files to translate
• Integrating with other tools that generate file lists

Configuration

You can configure the tool via environment variables (recommended with .env) or CLI flags. See .env.example for a complete template.

Key variables:

# Azure OpenAI
AZURE_OPENAI_API_KEY=...
AZURE_OPENAI_ENDPOINT=https://<resource>.openai.azure.com/
AZURE_OPENAI_DEPLOYMENT_NAME=gpt-4.1
AZURE_OPENAI_API_VERSION=2025-01-01-preview

# Translation
SOURCE_LANGUAGE=en
TARGET_LANGUAGE=zh-tw
MAX_RETRIES=3
QUALITY_THRESHOLD=7
CONCURRENT_LIMIT=4

# Files
INPUT_PATTERN=**/*.md
FILE_LIST_PATH=
OUTPUT_SUFFIX=_zh-tw
DICTIONARY_FILE=translation-dictionary.json
BACKUP_ORIGINAL=false

# Logging
LOG_LEVEL=info
LOG_FILE=translation.log

# Glossary (LLM suggestion controls)
GLOSSARY_SUGGEST_LIMIT=3
GLOSSARY_SUGGEST_MAX_ITEMS=5

Equivalent CLI flags exist for these variables (run translator --help).

Files

• translate.js - Main translation orchestrator
• package.json - Node.js project configuration
• .env.example - Environment variables template
• TRANSLATION_README.md - Comprehensive documentation (Chinese)
• TRANSLATION_DEMO.md - Live demonstration with examples
• test-translation.js - Basic functionality tests
• demo-translation.js - Demo script
• promote-zh-tw-default.js - Utility to rename *.md -> *.en.md and promote *_zh-tw.md -> *.md
• copy-glob.js - Utility to copy files by glob while preserving structure; supports --force and --remove-suffix

Features

• 🔄 Automatic scanning of all *.md files
• 🧠 Azure OpenAI integration with quality analysis
• ⚡ Concurrent translation with configurable limit
• 📚 Shared dictionary for consistent terminology
  • 字典僅作為模型提示詞的參考（Glossary）；不會直接對產出內容做字串取代。
• 🔧 Specialized term handling (bilingual format)
• 🛡️ Error handling and retry mechanisms
• 📝 Comprehensive logging and backup

For detailed documentation and a Chinese walkthrough, see TRANSLATION_README.md and TRANSLATION_DEMO.md.