DeepL 翻译与 API 工具
当用户明确要求使用 DeepL 官方 API 时，使用这个 skill，而不是普通翻译能力。
Prerequisites
- 需要可用的
python3 运行环境。
- 需要在环境变量中设置
DEEPL_API_KEY。
- 如果使用 DeepL Free，可额外设置
DEEPL_API_BASE_URL=https://api-free.deepl.com。
- 脚本仅依赖 Python 标准库，不需要安装额外三方包。
安全边界
- 仅允许请求
https://api.deepl.com 或 https://api-free.deepl.com。
- 仅使用环境变量
DEEPL_API_KEY 进行认证，不读取其他凭证、token 或本地账号配置。
- 不执行 shell、不会下载或运行外部脚本、不会启动子进程。
- 只有在用户显式提供
--text、--file、--stdin、--entries-file 或文档翻译文件时，才会读取对应本地内容。
- 读取到的文本、词汇表条目或文档文件，只会发送到 DeepL 官方 API，不会转发到其他域名。
能力范围
当前脚本尽量覆盖 DeepL OpenAPI 中常用且公开的接口能力：
- 核心能力：
- 文本翻译：
/v2/translate
- 语言查询：
/v2/languages
- 用量查询：
/v2/usage
- 文本润色 / 改写：
/write/rephrase
- 扩展能力：
- 文本翻译：
/v2/translate
- 语言查询：
/v2/languages
- 用量查询：
/v2/usage
- 文本润色 / 改写：
/write/rephrase
- 文档翻译：
- 上传：
/v2/document
- 状态查询：
/v2/document/{document_id}
- 结果下载：
/v2/document/{document_id}/result
- 一键闭环：脚本封装的
document-translate
- glossary v2：
- 列表、详情、条目、创建、删除
- 语言对查询：
/v2/glossary-language-pairs
- glossary v3：
- 列表、详情、条目查询
- 创建 glossary
- PATCH 更新 glossary / 合并字典
- PUT 替换指定语言对字典
- 删除指定字典
- 删除 glossary
快速开始
- 设置
DEEPL_API_KEY。
- 默认基础地址为
https://api.deepl.com。
- 如果使用 DeepL API Free，可设置：
export DEEPL_API_BASE_URL=https://api-free.deepl.com
只允许以上两个 DeepL 官方基础地址，其他地址会被脚本拒绝。
- 调用脚本：
cd <skill-directory>
python3 scripts/deepl_translate.py <子命令> ...
其中 <skill-directory> 表示当前 skill 的安装目录。
也可以不切换目录，直接执行：
python3 /path/to/deepL-translate/scripts/deepl_translate.py <子命令> ...
为兼容旧用法，如果不写子命令、直接传 --text --target-lang 这类参数，脚本会自动按 translate 处理。
For Agents
- 默认优先使用核心能力：
translate、rephrase、languages、usage。
- 只有在用户明确要求上传文档或管理 glossary 时，再使用扩展能力。
- 如果只是改写语气、商务化表达、同语种润色，优先用
rephrase，不要误用跨语种翻译。
- 需要结构化结果时使用
--json。
For Humans
- 示例命令中的
<skill-directory> 表示当前 skill 的安装目录。
- 如果宿主平台已经帮你切换到 skill 目录，可直接执行
python3 scripts/deepl_translate.py ...。
- 如果宿主平台以绝对路径调用脚本，也可以直接使用
/path/to/.../scripts/deepl_translate.py。
常用命令
文本翻译：
cd <skill-directory>
python3 scripts/deepl_translate.py translate \
--source-lang EN \
--target-lang ZH \
--text "Hello, world"
兼容旧写法：
cd <skill-directory>
python3 scripts/deepl_translate.py \
--source-lang EN \
--target-lang ZH \
--text "Hello, world"
查询支持语言：
cd <skill-directory>
python3 scripts/deepl_translate.py languages --type target --json
查询账户用量：
cd <skill-directory>
python3 scripts/deepl_translate.py usage --json
文本润色 / 同语种变体改写：
cd <skill-directory>
python3 scripts/deepl_translate.py rephrase \
--target-lang EN-US \
--writing-style business \
--text "please send me the report soon"
文档翻译闭环：
cd <skill-directory>
python3 scripts/deepl_translate.py document-translate \
--file ./input.docx \
--target-lang DE \
--output-file ./output_de.docx
创建 v2 glossary：
cd <skill-directory>
python3 scripts/deepl_translate.py glossary-v2-create \
--name demo-v2 \
--source-lang EN \
--target-lang DE \
--entries-file ./entries.tsv
创建 v3 glossary：
cd <skill-directory>
python3 scripts/deepl_translate.py glossary-v3-create \
--name demo-v3 \
--dict EN:DE:./en_de.tsv:tsv \
--dict EN:FR:./en_fr.tsv:tsv
使用建议
- 短文本翻译优先使用
translate。
- 如果只是英文变体、美化语气、商务化表达，优先使用
rephrase，不要误用跨语种翻译。
- UI 文案、短句、多义词，尽量传
--context。
- 需要完整返回结构时加
--json。
- 需要 glossary 时，先确认是旧的 v2 单语言对，还是新的 v3 多语言词汇表。
- 文档翻译如果只想拆步骤排查，可分别使用
document-upload、document-status、document-download。
已知约束
translate 单次最多 50 个 text 项，请求体总大小不能超过 128 KiB。glossary_id 依赖 source_lang。- 文档翻译为异步流程，必须先上传，再轮询状态，最后下载结果。
- 文档翻译、
--file、--stdin、--entries-file 会把用户明确提供的内容发送到 DeepL 官方服务。
- 脚本尽量覆盖官方公开接口，但某些新接口字段可能随 DeepL 文档演进而变化。
常见错误
未设置 DEEPL_API_KEY。
- 需要先导出
DEEPL_API_KEY 再调用命令。
DEEPL_API_BASE_URL 仅允许配置为 ...
- 只支持
https://api.deepl.com 和 https://api-free.deepl.com。
未提供输入文本。请使用 --text、--file 或 --stdin。
translate 和 rephrase 必须显式提供输入内容。
--glossary-id 需要同时提供 --source-lang。
- glossary 翻译调用时，必须同时指定源语言。
文档翻译失败：...
- 文档翻译由 DeepL 异步处理，失败原因以返回的错误信息为准。
参考资料
