30 行代码搞定！用 Python + DeepSeek API 打造自己的命令行翻译工具

前言

日常开发中，看英文文档、读 GitHub Issue、翻 Stack Overflow 是家常便饭。每次遇到生僻段落就得切到浏览器、打开翻译网站、粘贴、等待、复制回来——来回切换窗口，思路都被打断了。

有次在终端里折腾了半天，实在忍不了，心想：能不能在终端里直接翻译？一条命令搞定那种？

于是花了一个下午，用 Python + DeepSeek API 撸了个命令行翻译小工具。代码不多，三十行出头，但用起来贼顺手。这篇文章就把整个过程分享出来，跟着敲一遍就能跑起来。

---

为什么选 DeepSeek

选模型的时候对比了几家：

• 翻译质量：中英互译这个场景，DeepSeek 对技术文档的处理很到位，专业术语不会乱翻
• 价格：DeepSeek V3.2 每百万 token 输入只要 $0.28，输出 $0.42，翻译一篇文章几分钱都花不到。就算用最新的 DeepSeek V4-Pro，价格也很能打
• 接入方式：完全兼容 OpenAI SDK，一行 base_url 就切过去了，零迁移成本

注册和获取 API Key 也很简单，去 DeepSeek 开放平台 注册账号，然后在 API Keys 页面创建一个 key 就行。新用户有免费额度，够你玩一阵了。

---

环境准备

Python 3.8+ 即可，唯一的依赖是 openai 库：

pip install openai

然后在终端里设置环境变量（别把 key 硬编码到代码里，不安全）：

# Linux / macOS
export DEEPSEEK_API_KEY="你的API-Key"

# Windows PowerShell
$env:DEEPSEEK_API_KEY="你的API-Key"

---

核心代码

先看完整版本，再逐块拆解：

#!/usr/bin/env python3
"""命令行翻译工具 —— 基于 DeepSeek API"""
import os
import sys
from openai import OpenAI

# 初始化客户端
client = OpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com",
)

# 构建带翻译指令的 System Prompt
SYSTEM_PROMPT = """你是一个技术文档翻译专家。翻译规则：
1. 如果输入是英文，翻译成简洁流畅的中文
2. 如果输入是中文，翻译成地道的英文
3. 保留 Markdown 格式、代码块、专有名词原样
4. 只输出译文，不要额外解释"""


def translate(text: str, stream: bool = True) -> str:
    """调用 DeepSeek API 进行翻译"""
    response = client.chat.completions.create(
        model="deepseek-chat",
        messages=[
            {"role": "system", "content": SYSTEM_PROMPT},
            {"role": "user", "content": text},
        ],
        temperature=0.3,  # 翻译场景降低随机性
        stream=stream,
    )

    if stream:
        result = []
        for chunk in response:
            delta = chunk.choices[0].delta
            if delta.content:
                print(delta.content, end="", flush=True)
                result.append(delta.content)
        print()  # 换行
        return "".join(result)
    else:
        return response.choices[0].message.content


if __name__ == "__main__":
    if len(sys.argv) < 2:
        text = sys.stdin.read().strip()
    else:
        text = " ".join(sys.argv[1:])

    if not text:
        print("用法: python translator.py <要翻译的文本>")
        print("      echo 'Hello World' | python translator.py")
        sys.exit(1)

    translate(text)

---

逐块拆解

1. 客户端初始化

client = OpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com",
)

DeepSeek API 完全兼容 OpenAI 的接口规范。你甚至可以用现有的 OpenAI SDK，只改 base_url 和 api_key 就行。如果有项目已经在用 OpenAI 的接口，切过来就改两行。

2. System Prompt 设计

SYSTEM_PROMPT = """你是一个技术文档翻译专家。翻译规则：
1. 如果输入是英文，翻译成简洁流畅的中文
2. 如果输入是中文，翻译成地道的英文
3. 保留 Markdown 格式、代码块、专有名词原样
4. 只输出译文，不要额外解释"""

这在翻译场景里很关键。不加约束的话，模型可能会在前面加"以下是翻译结果："之类的废话，或者把代码块里的变量名也给翻了。

几个要点：

• 技术文档翻译专家 这个角色设定让模型倾向于保留术语
• 保留 Markdown 格式 确保翻译后的文档结构不乱
• 只输出译文 避免多余的引导语

3. 流式输出

for chunk in response:
    delta = chunk.choices[0].delta
    if delta.content:
        print(delta.content, end="", flush=True)
        result.append(delta.content)

设置 stream=True 后，模型会逐 token 返回结果。看起来就像打字机一样一个字一个字往外蹦——翻译长段落的时候体验好很多，不用干等。

4. 两种输入方式

if len(sys.argv) < 2:
    text = sys.stdin.read().strip()  # 管道输入
else:
    text = " ".join(sys.argv[1:])    # 命令行参数

支持命令行参数和管道两种方式，方便在不同场景下使用。

---

实战演示

保存为 translator.py，加个可执行权限就能用了：

# 命令行参数方式
$ python translator.py "Python is an interpreted, high-level programming language"
Python 是一种解释型高级编程语言

# 管道输入方式 —— 翻译整段英文文档
$ echo "The async/await syntax was introduced in Python 3.5. 
It allows you to write asynchronous code that looks like synchronous code,
making it much easier to reason about." | python translator.py

async/await 语法在 Python 3.5 中引入。它让你可以写出看起来像
同步代码的异步代码，大大降低了理解和维护的难度。

# 中译英
$ python translator.py "协程是一种比线程更轻量级的并发方案"
Coroutines are a concurrency approach that is more lightweight than threads.

---

进阶优化方向

这个版本已经能打，但如果想做得更完善，可以考虑：

1. 多语言自动检测

不用手动指定方向，让模型自己判断：

SYSTEM_PROMPT = """你是一个多语言翻译专家。
自动检测输入语言，将其翻译为中文（如果输入非中文）或英文（如果输入是中文）。
保留格式，只输出译文。"""

2. 支持文件直接翻译

加几行代码，支持 python translator.py document.md 直接翻译整个文件：

import pathlib

if len(sys.argv) == 2 and pathlib.Path(sys.argv[1]).is_file():
    text = pathlib.Path(sys.argv[1]).read_text(encoding="utf-8")

3. 上下文记忆

翻译长文档时，前面段落的结果可以作为后续翻译的上下文，保持术语一致性。

---

踩过的坑

分享几个实际用下来遇到的问题：

API Key 泄漏：千万别把 key 写死在代码里然后传 GitHub。用环境变量或者 .env 文件，记得加 .gitignore。

超长文本：DeepSeek 单次请求的上下文窗口虽然有 128K，但如果翻译超长文档（比如整本手册），建议按段落分批调用，避免一次塞太多内容导致翻译质量下降。

---

总结

三十多行 Python 代码，一个下午，搞定了一个日常高频需求。核心就两步：用 OpenAI SDK 连 DeepSeek API，写好 System Prompt 控制输出格式。

这个思路不限于翻译——代码审查、日志分析、文档生成，换个 Prompt 就能干别的。API 就在那，关键是找到适合自己的场景。

DeepSeek 开放平台注册入口：https://platform.deepseek.com/

代码放在这，拿回去改改用吧。