translate-cli Practical Guide: One Command for Multilingual Translation, Batch File Processing, and Preset Configuration

translate-cli is a command-line translation powerhouse that supports multiple translation engines, batch file processing, and preset configurations. Here's a complete practical guide for 2026.

What translate-cli Does

Multi-engine support: OpenAI, DeepL, Google Translate, Ollama (local), and more
Batch processing: Translate entire directories of files at once
Preset configurations: Save and reuse translation settings for recurring tasks
Format preservation: Maintains Markdown, HTML, and code block formatting
Incremental translation: Only translates changed sections in updates

Installation

clawhub install translate-cli

# Or install the CLI tool directly:
npm install -g @sfd/translate-cli

Basic Usage

# Translate a single file
translate --from zh-CN --to en --engine openai input.md output_en.md

# Translate a directory (batch)
translate --from zh-CN --to en --dir ./content/ --output ./content-en/

# Translate to multiple targets at once
translate --from zh-CN --to en,zh-TW,ja --file article.md

Engine Configuration

# OpenAI (default, best quality)
translate config set engine openai
translate config set openai.apiKey your-key
translate config set openai.model gpt-4o-mini  # Cost-effective option

# DeepL (fast, accurate for European languages)
translate config set engine deepl
translate config set deepl.apiKey your-key

# Ollama (local, free, private)
translate config set engine ollama
translate config set ollama.model qwen2.5:7b

Presets: Save Recurring Configurations

# Create a preset for SFD blog content
translate presets create sfd-blog   --from zh-CN   --to en,zh-TW   --engine openai   --model gpt-4o-mini   --preserve-code-blocks   --preserve-urls

# Use the preset
translate --preset sfd-blog ./new-article.md

SFD Lab Workflow Integration

At SFD Lab, translate-cli is how our content pipeline handles the Chinese-to-English-to-Traditional-Chinese translation flow for the website.

Our batch translation command:

translate --preset sfd-blog   --dir ./content/zh-CN/   --output-dir ./content/   --output-structure locale-subdirs   --skip-existing

This processes all new zh-CN articles, skips already-translated ones, and places output in ./content/en/ and ./content/zh-TW/ respectively.

Custom Prompt Templates

For domain-specific translations (like technical documentation), customize the translation prompt:

# ~/.translate-cli/templates/tech-docs.yaml
system: |
  You are a technical translator specializing in AI/ML documentation.
  Preserve all technical terms, code references, and product names in English.
  For zh-TW output, use Taiwan Mandarin conventions.
prompt: |
  Translate the following {from} content to {to}:
  - Keep proper nouns: OpenClaw, ClawHub, SFD Lab, skill names
  - Maintain all HTML tags and code blocks unchanged
  - {content}

Pitfalls

Token costs with long files: Large files can be expensive with OpenAI. Use --model gpt-4o-mini for routine translation work — quality is sufficient.

Glossary consistency: For recurring terms, build a glossary file that translate-cli uses as reference. Otherwise the same term might be translated differently across files.

HTML tag corruption: Always verify that HTML tags survived intact after translation, especially complex nested structures. Use --dry-run mode to check before committing to large batch runs.

Rate limiting: For large batches with OpenAI, you'll hit rate limits. The tool has built-in retry logic, but very large batches may need to be split across multiple runs.

Summary

translate-cli is the right tool when translation is a regular part of your workflow — not for one-off queries, but for batch processing, preset management, and integration into content pipelines. If you manage multilingual content, this skill will save hours per week.

SFD Lab | translate-cli practical guide | 2026