Back to Details

translate

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
Translate files using the Bluente Translation API.
使用Bluente Translation API翻译文件。

Step 1: Collect user inputs

步骤1：收集用户输入

Ask the user using AskUserQuestion. IMPORTANT: Every question MUST have at least 2 options (AskUserQuestion requires min 2 options per question). Use the user's "Other" free-text option for custom input.
Ask all 4 questions in a single AskUserQuestion call:
  1. API Key — "What is your Bluente API key? (starts with sk-, get one at https://translate.bluente.com/settings/?type=apiKeys)"
  2. Source path — "What is the path to the file or folder you want to translate?"
    • Options: "Current directory" (description: "Use the current working directory"), "Enter path" (description: "I'll specify a custom path in the Other field")
  3. Target language — "What language do you want to translate to?"
    • Options (pick 4, use the most common): "Arabic" , "French", "Spanish", "German"
    • The user can pick "Other" for any other language.
  4. Output path — "Where should the translated files be saved?"
    • Options: "Same folder as source" (description: "Save next to the originals"), "Enter path" (description: "I'll specify a custom path in the Other field")
If the user selected "I have my key ready" but didn't type a key in "Other", ask them to provide the key in a follow-up message (don't use AskUserQuestion again for this — just ask in plain text).
使用AskUserQuestion向用户提问。重要提示：每个问题必须至少包含2个选项（AskUserQuestion要求每个问题最少有2个选项）。使用“其他”自由文本选项供用户输入自定义内容。
在单次AskUserQuestion调用中询问全部4个问题：
  1. API密钥 — "你的Bluente API密钥是什么？（以sk-开头，可在https://translate.bluente.com/settings/?type=apiKeys获取）"
  2. 源路径 — "你要翻译的文件或文件夹的路径是什么？"
    • 选项："当前目录"（描述："使用当前工作目录"），"输入路径"（描述："我会在其他字段中指定自定义路径"）
  3. 目标语言 — "你想翻译成什么语言？"
    • 选项（选4个最常用的）："阿拉伯语"、"法语"、"西班牙语"、"德语"
    • 用户可以选择“其他”来指定任意其他语言。
  4. 输出路径 — "翻译后的文件应该保存到哪里？"
    • 选项："与源文件同文件夹"（描述："保存在原文件旁"），"输入路径"（描述："我会在其他字段中指定自定义路径"）
如果用户选择了“我已经准备好密钥”但没有在“其他”字段中输入密钥，发送后续消息请用户提供密钥（无需再次使用AskUserQuestion，直接用普通文本询问即可）。

Step 2: Look up the correct language code

步骤2：查找正确的语言代码

Use this known mapping of common language codes to avoid an extra API call:
  • Arabic = 
    ara
    , English = 
    en
    , French = 
    fra
    , Spanish = 
    spa
    , German = 
    de
    , Chinese = 
    zho
    , Japanese = 
    ja
    , Korean = 
    ko
    , Portuguese = 
    pt
    , Italian = 
    it
    , Turkish = 
    tr
    , Russian = 
    ru
    , Hindi = 
    hi
If the user picks a language NOT in this list, call the supported languages endpoint:
GET https://api.bluente.com/api/20250924/blu_translate/supported_languages
Header: Authorization: Bearer <API_KEY>
Response format: 
{"message": "success", "code": 0, "data": [{"name": "French", "svcCode": "fra", ...}, ...]}
Search 
data
array for the matching language and use its 
svcCode
.
使用以下已知的常用语言代码映射，避免额外的API调用：
  • 阿拉伯语 = 
    ara
    ，英语 = 
    en
    ，法语 = 
    fra
    ，西班牙语 = 
    spa
    ，德语 = 
    de
    ，中文 = 
    zho
    ，日语 = 
    ja
    ，韩语 = 
    ko
    ，葡萄牙语 = 
    pt
    ，意大利语 = 
    it
    ，土耳其语 = 
    tr
    ，俄语 = 
    ru
    ，印地语 = 
    hi
如果用户选择的语言不在此列表中，调用支持语言接口：
GET https://api.bluente.com/api/20250924/blu_translate/supported_languages
Header: Authorization: Bearer <API_KEY>
响应格式：
{"message": "success", "code": 0, "data": [{"name": "French", "svcCode": "fra", ...}, ...]}
在
data
数组中搜索匹配的语言并使用其
svcCode
。

Step 3: Detect source files

步骤3：检测源文件

  • If the source path is a single file, translate just that file.
  • If the source path is a folder, find all translatable files in it (pdf, docx, pptx, xlsx, etc.)
  • If no translatable files found, tell the user and stop.
  • 如果源路径是单个文件，仅翻译该文件。
  • 如果源路径是文件夹，查找其中所有可翻译的文件（pdf、docx、pptx、xlsx等）
  • 如果未找到可翻译的文件，告知用户并终止流程。

Step 4: Translate each file

步骤4：翻译每个文件

Write and execute a single Python script that handles the entire translation workflow for all files. This avoids shell variable issues (e.g. 
status
is read-only in zsh) and is more reliable than chaining curl commands.
The Python script should:
python
import requests, time, sys, os

API_KEY = "<API_KEY>"
BASE = "https://api.bluente.com/api/20250924/blu_translate"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
FILES = [<list of absolute file paths>]
FROM_LANG = "en"  # or other source language code
TO_LANG = "<target svcCode>"
OUTPUT_DIR = "<output directory>"

os.makedirs(OUTPUT_DIR, exist_ok=True)
results = []

for filepath in FILES:
    filename = os.path.basename(filepath)
    ext = filename.rsplit(".", 1)[-1].lower()
    to_type = {"pdf": "pdf", "docx": "word", "doc": "word", "pptx": "pptx"}.get(ext, ext)
    print(f"Translating: {filename}")

    # Upload
    with open(filepath, "rb") as f:
        r = requests.post(f"{BASE}/upload?glossary=0&engine=3", headers=HEADERS, files={"file": f})
    resp = r.json()
    if resp.get("code") != 0:
        print(f"  Upload failed: {resp}")
        results.append((filename, False, "Upload failed"))
        continue
    task_id = resp["data"]["id"]
    print(f"  Task ID: {task_id}")

    # Wait for processing
    for _ in range(40):
        r = requests.get(f"{BASE}/check?entry=get_status&id={task_id}", headers=HEADERS)
        st = r.json()["data"]["status"]
        if st == "SERVICE_PROCESSED":
            break
        if st == "ERROR":
            print(f"  Processing error")
            results.append((filename, False, "Processing error"))
            break
        time.sleep(3)
    else:
        results.append((filename, False, "Processing timeout"))
        continue
    if st == "ERROR":
        continue

    # Start translation
    r = requests.post(f"{BASE}/translate?engine=3", headers=HEADERS,
                      json={"id": task_id, "action": "start", "from": FROM_LANG, "to": TO_LANG})
    resp = r.json()
    if resp.get("code") != 0:
        print(f"  Translation start failed: {resp.get('message')}")
        results.append((filename, False, f"Start failed: {resp.get('message')}"))
        continue

    # Wait for translation
    for _ in range(120):
        r = requests.get(f"{BASE}/check?entry=get_status&id={task_id}", headers=HEADERS)
        st = r.json()["data"]["status"]
        if st == "READY":
            break
        if st == "ERROR":
            print(f"  Translation error")
            results.append((filename, False, "Translation error"))
            break
        time.sleep(5)
    else:
        results.append((filename, False, "Translation timeout"))
        continue
    if st == "ERROR":
        continue

    # Download
    r = requests.get(f"{BASE}/download?id={task_id}&to_type={to_type}", headers=HEADERS)
    out_path = os.path.join(OUTPUT_DIR, filename)
    with open(out_path, "wb") as f:
        f.write(r.content)
    print(f"  Saved: {out_path}")
    results.append((filename, True, out_path))
编写并执行单个Python脚本，处理所有文件的完整翻译工作流。这可以避免shell变量问题（例如zsh中
status
是只读变量），并且比链式调用curl命令更可靠。
Python脚本应包含以下内容：
python
import requests, time, sys, os

API_KEY = "<API_KEY>"
BASE = "https://api.bluente.com/api/20250924/blu_translate"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
FILES = [<list of absolute file paths>]
FROM_LANG = "en"  # or other source language code
TO_LANG = "<target svcCode>"
OUTPUT_DIR = "<output directory>"

os.makedirs(OUTPUT_DIR, exist_ok=True)
results = []

for filepath in FILES:
    filename = os.path.basename(filepath)
    ext = filename.rsplit(".", 1)[-1].lower()
    to_type = {"pdf": "pdf", "docx": "word", "doc": "word", "pptx": "pptx"}.get(ext, ext)
    print(f"Translating: {filename}")

    # Upload
    with open(filepath, "rb") as f:
        r = requests.post(f"{BASE}/upload?glossary=0&engine=3", headers=HEADERS, files={"file": f})
    resp = r.json()
    if resp.get("code") != 0:
        print(f"  Upload failed: {resp}")
        results.append((filename, False, "Upload failed"))
        continue
    task_id = resp["data"]["id"]
    print(f"  Task ID: {task_id}")

    # Wait for processing
    for _ in range(40):
        r = requests.get(f"{BASE}/check?entry=get_status&id={task_id}", headers=HEADERS)
        st = r.json()["data"]["status"]
        if st == "SERVICE_PROCESSED":
            break
        if st == "ERROR":
            print(f"  Processing error")
            results.append((filename, False, "Processing error"))
            break
        time.sleep(3)
    else:
        results.append((filename, False, "Processing timeout"))
        continue
    if st == "ERROR":
        continue

    # Start translation
    r = requests.post(f"{BASE}/translate?engine=3", headers=HEADERS,
                      json={"id": task_id, "action": "start", "from": FROM_LANG, "to": TO_LANG})
    resp = r.json()
    if resp.get("code") != 0:
        print(f"  Translation start failed: {resp.get('message')}")
        results.append((filename, False, f"Start failed: {resp.get('message')}"))
        continue

    # Wait for translation
    for _ in range(120):
        r = requests.get(f"{BASE}/check?entry=get_status&id={task_id}", headers=HEADERS)
        st = r.json()["data"]["status"]
        if st == "READY":
            break
        if st == "ERROR":
            print(f"  Translation error")
            results.append((filename, False, "Translation error"))
            break
        time.sleep(5)
    else:
        results.append((filename, False, "Translation timeout"))
        continue
    if st == "ERROR":
        continue

    # Download
    r = requests.get(f"{BASE}/download?id={task_id}&to_type={to_type}", headers=HEADERS)
    out_path = os.path.join(OUTPUT_DIR, filename)
    with open(out_path, "wb") as f:
        f.write(r.content)
    print(f"  Saved: {out_path}")
    results.append((filename, True, out_path))

Summary

Summary

ok = [r for r in results if r[1]] fail = [r for r in results if not r[1]] print(f"\nDone: {len(ok)} succeeded, {len(fail)} failed") for name, _, path in ok: print(f" OK: {name} -> {path}") for name, _, err in fail: print(f" FAIL: {name}: {err}")

Fill in the API_KEY, FILES, FROM_LANG, TO_LANG, and OUTPUT_DIR variables from the user's inputs, then run the script with `python3`. Set a timeout of 600000ms (10 min) on the Bash tool call.
ok = [r for r in results if r[1]] fail = [r for r in results if not r[1]] print(f"\nDone: {len(ok)} succeeded, {len(fail)} failed") for name, _, path in ok: print(f" OK: {name} -> {path}") for name, _, err in fail: print(f" FAIL: {name}: {err}")

根据用户输入填充API_KEY、FILES、FROM_LANG、TO_LANG和OUTPUT_DIR变量，然后使用`python3`运行脚本。将Bash工具调用的超时时间设置为600000ms（10分钟）。

Step 5: Report results

步骤5：上报结果

Tell the user:
  • How many files were translated successfully
  • Where the translated files are saved
  • Any errors that occurred
告知用户以下信息：
  • 成功翻译的文件数量
  • 翻译后文件的保存位置
  • 发生的所有错误

API Reference

API参考

  • Docs: https://www.bluente.com/docs
  • Base URL: 
    https://api.bluente.com/api/20250924/blu_translate
  • Auth: 
    Authorization: Bearer <API_KEY>
  • Engines: 
    3
    = LLM, 
    4
    = LLM Pro
  • Source language (
    from
    ) is required — it does NOT auto-detect
  • Language codes are custom — use the mapping above or verify via supported_languages endpoint
$ARGUMENTS
  • 文档： https://www.bluente.com/docs
  • 基础URL： 
    https://api.bluente.com/api/20250924/blu_translate
  • 认证方式： 
    Authorization: Bearer <API_KEY>
  • 引擎： 
    3
    = LLM，
    4
    = LLM Pro
  • 源语言（
    from
    ）为必填项——不支持自动检测
  • 语言代码为自定义格式——使用上述映射或通过supported_languages接口验证
$ARGUMENTS