Equalang

指向一個檔案，它就會上傳該檔案、等待任務完成，並將結果寫入原始檔案旁邊。你會得到檔案路徑，永遠不會看到檔案內容——版面、表格、圖片和公式都能保留，而且不會有任何大型內容進入對話中。

任務會消耗使用者的額度。在執行 translate 或 transcribe 之前，請告知所需費用並取得使用者同意。 estimate 可免費查詢一個檔案的費用。

設定

API 金鑰只需一行 EQUALANG_API_KEY=el_...，放在 ~/.config/equalang/.env 中（若已設定 $XDG_CONFIG_HOME 則放在對應目錄下）：每台機器一個檔案，與 Equalang MCP 伺服器共用，並在重新安裝或更新此技能時保留。使用者請前往 https://equalang.com/api-keys 建立金鑰。

dir="${XDG_CONFIG_HOME:-$HOME/.config}/equalang"
mkdir -p "$dir" && (umask 077 && echo 'EQUALANG_API_KEY=el_...' > "$dir/.env")

環境變數 EQUALANG_API_KEY 的優先度高於檔案。若無金鑰，每個指令都會回覆如何取得金鑰及存放位置。切勿自行偽造金鑰——請詢問使用者。

指令

請從此技能的目錄執行；只需要 python3 即可。每個指令都會輸出一個 JSON 物件；使用 --help 可查看指令的可用參數。

# 預估費用？上傳檔案但不啟動任何任務；完全免費。`kept_until` 表示上傳檔案保留多久。
python3 scripts/equalang.py estimate report.pdf
#   -> {"file_id": "...", "credits_to_translate": 12.34, "credits_to_transcribe": null, ...}

# 翻譯檔案。可傳入本地路徑、公開網址（Equalang 會自行下載），或使用 estimate 回傳的 --file-id。
python3 scripts/equalang.py translate report.pdf --to zh-CN
python3 scripts/equalang.py translate --file-id <file_id> --to zh-CN        # 不需第二次上傳
python3 scripts/equalang.py translate https://example.com/deck.pptx --to ja -o ./out

# 錄音檔：產生翻譯字幕，或記錄原始語言說出的內容。
python3 scripts/equalang.py translate talk.mp4 --to en --bilingual --format srt --format txt
python3 scripts/equalang.py transcribe interview.mp3 --format srt --format txt

# 大量文字字串（每個獨立翻譯；最多 50 個，每個 5,000 字元，每次呼叫上限 20,000 字元）。
python3 scripts/equalang.py text "Save changes" "Delete project" --to de
# 單一長篇純文字——例如文章、筆記或 .md 檔案——最多 100,000 字元。Equalang 會以句子為單位進行切割：請勿自行分段。
python3 scripts/equalang.py text --file notes.md --to ja -o notes.ja.md

# 再次查詢任務狀態 · 取消任務 · 查詢餘額 · 查詢語言代碼（無需金鑰）
python3 scripts/equalang.py status <job_id> -o ./out
python3 scripts/equalang.py cancel <job_id>
python3 scripts/equalang.py balance
python3 scripts/equalang.py languages chinese

讀取輸出

已完成的任務會輸出 outputs（每個都有 path）和 credits_charged。請將這兩項資訊告知使用者。除非使用者要求，否則不要回讀產生的檔案內容來摘要：因為那是完整文件，路徑的意義就是讓檔案內容留在對話之外。

失敗時會輸出 {"error", "code", "retryable"} 並以狀態碼 1 結束。僅當 retryable 為 true 時才應重試；INSUFFICIENT_CREDITS 表示使用者需要前往 https://equalang.com/pricing 加值，而非由你重試。

值得注意的事項

支援格式。 文件：pdf、docx、pptx、xlsx、epub、html、txt。字幕：srt、vtt。圖片：jpg、png、webp、bmp。錄音：mp3、m4a、wav、flac、ogg、aac、opus、mp4、mov、webm、mkv。檔案大小上限 100 MB。transcribe 僅接受錄音檔。
結果絕不覆寫。 它們會放在本地來源檔案旁邊（或 -o DIR 目錄中，若是網址則放在目前目錄），並保留 Equalang 給予的名稱；若名稱已被占用則會加上 (1)。對已完成的任務再次執行 status 時，只會重新命名已寫入的檔案，而非重新複製。
大型檔案需時數分鐘而非數秒。 指令會等待並將進度輸出至 stderr。中斷指令不會取消任務：可用 status <job_id> 繼續追蹤，cancel <job_id> 停止任務。已取消或失敗的任務不收費。
錄音檔僅針對實際聽到的語音收費——靜音和背景音樂不計費——因此通常比 estimate 預估的便宜；文件則按 estimate 的預估收費。
語言代碼 例如 en、zh-CN、zh-TW、ja、pt。這些代碼從即時 API 讀取，絕不從記憶體讀取：languages 列出檔案可用的語言，languages --kind text 列出 text 可用的更廣泛語言集合，languages chinese 依名稱查詢特定語言。省略 --source-language 即可自動偵測來源語言。
處理多個檔案？ 逐一預估每個檔案的費用，加總後一次詢問使用者——切勿自行對整個資料夾進行迴圈。
若此腳本無法滿足需求，請參閱後端 API：https://equalang.com/llms.txt

Equalang 翻譯轉寫技能