trans

中文文档

Terminal AI translation tool powered by OpenAI-compatible APIs.

Pipe-friendly, zero-friction translation at your fingertips.

Install

Homebrew (macOS / Linux)

brew tap lian-yang/trans
brew install trans

Go install

go install github.com/lian-yang/trans@latest

From source

git clone https://github.com/lian-yang/trans.git
cd trans && go build -o trans .

Update

# Self-update to the latest version (from GitHub Releases)
trans update

Homebrew users: trans update will detect the Homebrew installation and prompt brew upgrade trans instead.

Usage

# Translate to Chinese (default)
trans "hello world"
# → 你好，世界

# Pipe support
echo "The quick brown fox" | trans
cat README.md | trans

# Specify target language
trans -t ja "good morning"
# → おはようございます

trans -t ko "I love programming"
# → 나는 프로그래밍을 좋아합니다.

# Verbose mode (show source→target annotation)
trans -v "hello world"
# → [en→zh] 你好，世界

# Contrast mode (show original + translation line by line)
trans -c "hello world"
# → hello world
# → 你好，世界

cat doc.md | trans -c
# Lines needing translation show original + translated pair
# Lines already in target language show once unchanged

# Use a different model
trans -m gpt-4o "hello world"

# Print version
trans -V
# → v1.0.0

Stream control

By default, output mode is auto-detected: streaming in terminal, batch in pipe.

# Force streaming (e.g. real-time output in pipe)
echo "hello" | trans -s

# Force batch (e.g. wait for full result in terminal)
trans --no-stream "hello world"

Configuration

Priority: CLI flags > environment variables > config file > defaults

Config file ~/.trans.json

{
  "api_key": "sk-xxx",
  "base_url": "https://api.deepseek.com/v1",
  "model": "deepseek-chat",
  "target_lang": "zh"
}

Environment variables

Variable	Purpose
OPENAI_API_KEY	API key
OPENAI_BASE_URL	Custom base URL (for OpenAI-compatible services)
TRANS_MODEL	Model name
TRANS_TARGET_LANG	Default target language

CLI flags

-t, --to string      target language (default: zh)
-m, --model string   model to use (default: gpt-4o-mini)
-c, --contrast       contrast mode: show original and translated lines alternately
-s, --stream         force streaming output
    --no-stream      force batch output (disable streaming)
-v, --verbose        show source→target language annotation
-V, --version        print version and exit

Subcommands

update               self-update to the latest version

Compatible Providers

Any OpenAI-compatible API works. Just change base_url and model:

Provider	base_url	model
OpenAI	https://api.openai.com/v1	gpt-4o-mini
DeepSeek	https://api.deepseek.com/v1	deepseek-chat
Groq	https://api.groq.com/openai/v1	llama-3.3-70b-versatile
OpenRouter	https://openrouter.ai/api/v1	openai/gpt-4o-mini

Design Principles

• Pipe-first: stdout is clean text, errors go to stderr
• Auto streaming: streams to terminal, batches for pipes (isatty detection)
• Zero SDK: raw net/http + SSE parsing, no OpenAI SDK dependency
• Minimal deps: only cobra + stdlib

License

MIT