默认参数策略

除非用户明确要求其他配置，否则一律采用以下默认值：

• --source-language auto —— 在生成的命令中**显式传入**
• --target-language zh
• 不传 --translate-model
• 不传 --prompt
• 不传 --summary-enabled
• 不传 --create-timeout-seconds
• 不传 --poll-timeout-seconds
• 不传 --poll-interval-seconds
• 若默认输出路径（即与输入文件同名、同目录下的 .srt 文件）可接受，则省略 --output

当用户请求多种目标语言时，仅通过 --translate-languages 传入**额外的语言代码**，并需说明：当前脚本仍仅生成一个 .srt 文件，其主语言由 --target-language 指定。

当用户仅请求一种目标语言时，**禁止**传入 --translate-languages 。

当用户未指定输出位置，且当前工作目录含义模糊时，优先在输入媒体文件所在目录中显式指定 --output 路径。

语言参数规则

请始终遵循以下命令构造规范：

• 用户说“翻译为德语”，但未指定源语言：
  • 使用 --source-language auto --target-language de
  • 禁止使用 --source-language de
  • 禁止添加 --translate-languages de
• 用户同时指定了源语言和目标语言：
  • 两个参数均需显式指定，例如：--source-language en --target-language de
• 用户请求多种目标语言：
  • 主输出语言保留在 --target-language 中
  • 仅将**额外的目标语言**填入 --translate-languages

推荐的单目标语言示例：

python3 "{baseDir}/scripts/translate.py" "" --source-language auto --target-language de --output ""

运行时依赖

• 必需依赖：
  • KRETRANS_API_KEY（获取地址：https://kretrans.com/console#api-management）
  • ffmpeg
  • Python 包 requests
  • python、python3 或 py（任一可用即可）
• 可选依赖：
  • yt-dlp
  • aria2c

translate.py 仅接受本地文件作为输入。 该脚本向 https://api.kretrans.com/v1/api 发送请求，并将提取的音频及请求元数据（如文件名、语言设置等）上传至该 API。

Python 启动器选择逻辑

按顺序选取首个可用命令：

• Windows 平台：python → py -3
• macOS/Linux 平台：python3 → python

响应契约

执行完成后回复时，务必使结果具体、可操作。

• 成功时，须包含：
  • 最终生成的 .srt 文件路径
  • 实际被翻译的输入文件路径
  • 目标语言代码
  • 输入源类型（local / url / magnet）
  • 重要警告（如降级行为、自动创建的输出路径等）
• 预检失败时，须包含：
  • 确切缺失的依赖项名称
  • 一项具体可行的下一步操作
  • 是否可通过提供本地文件绕过该问题
• API 或任务失败时，须包含：
  • 失败所处阶段
  • 可用时提供 task_id 或 request_id
  • 核心错误信息
  • 脚本报告的重试性（retryable）状态

禁止使用“已完成”“已结束”等模糊表述。必须始终返回输出路径。

标准回复模板

成功模板：

Generated subtitle file: 
Translated source: 
Target language: 
Source type: 
Notes: 

阻塞模板：

Unable to continue: 
Next step: 

任务失败模板：

Translation failed at: 
Source: 
Task info: 
Error: 
Retryable: 

错误到用户响应映射规则

将原始工具输出转换为面向用户的直接状态说明。

• 若报错提示 API Key 缺失：
  • 说明 KRETRANS_API_KEY 未设置
  • 提示用户前往 https://kretrans.com/console#api-management 获取
• 若报错提示 ffmpeg 缺失：
  • 说明本地媒体提取无法启动
  • 指出需安装 ffmpeg 并确保其位于 PATH 中
• 若报错提示输入文件不存在：
  • 明确报告该输入路径
  • 要求用户提供有效的本地媒体路径
• 若缺少 URL 或 magnet 下载工具：
  • 明确指出缺失工具名称：yt-dlp 或 aria2c
  • 提示用户可改用本地文件替代
• 若任务创建失败：
  • 说明请求已抵达 API 层，但任务未被接受
  • 如有 request_id，请一并返回
• 若轮询时任务状态为 failed：
  • 说明远程翻译任务在创建后失败
  • 如有 task_id、error、error_code、retryable，请全部返回
• 若任务成功但 SRT 导出失败：
  • 说明翻译已完成，但字幕导出在本地失败
  • 返回预期的输出路径

优先使用简洁、具体的措辞，避免原始 traceback 堆栈。当存在任务标识符或关键错误字段时，必须保留。

示例

PowerShell 示例：

$env:KRETRANS_API_KEY = ""
python "{baseDir}/scripts/translate.py" "D:/videos/demo.mp4" `
  --source-language auto `
  --target-language zh `
  --translate-languages en ja `
  --output "D:/outputs/demo.srt"

Bash 示例：

export KRETRANS_API_KEY=""
python3 "{baseDir}/scripts/translate.py" "/tmp/demo.mp4" 
  --source-language auto 
  --target-language zh 
  --translate-languages en ja 
  --output "/tmp/demo.srt"