PPT Translator

SurgePix PPT Translator

Translate all text content in a PowerPoint (.pptx) file into a target language via the platform API, while preserving the original layout, images, and design elements, and return a download link to the translated file.

What the Skill Does

Workflow

1. Step 0: Check environment (required)

   Before running, verify config:

   node "<skills-dir>/surgepix-setup/scripts/check_env.mjs"

   • Exit 0 → proceed to Step 1
   • Exit 1 → configure .env following the surgepix-setup skill, then retry

2. Step 1: Gather inputs

   • Local file → the script uploads automatically, then calls the API
   • URL → script uses it directly
   • Ask the user for the target language; defaults to en if not specified. Common codes: en, zh, ja, ko, fr, de, es, pt, ru, ar.
   • The user must provide exactly one PPTX file (only one file at a time). Accepted:
     • Local file path (e.g. ./slides.pptx)
     • URL pointing to a PPTX file
   • Session ID (optional): use the sessionId from the previous output when retrying; omit on the first run — the platform auto-creates a new session.
   • Validate the file before submitting:
     • Supported format: PPTX (.pptx)
     • Max file size: 50MB
     • If the format is unsupported or the file is too large, inform the user and ask them to provide a different file

3. Step 2: Run ppt-translate

   node "<skills-dir>/surgepix-translate-ppt/scripts/translate_ppt.mjs" \
     "<file-path-or-URL>" \
     [--language <code>] \
     [--session-id <id>] \
     [--nowait <true|false>]

   Flag	Description
   <file-path-or-URL>	A local path or PPTX URL (required)
   --language <code>	Target language code, e.g. zh / en / jp ; default en
   --session-id <id>	Session ID; pass the sessionId (number type) from a previous run to iterate
   --nowait <true|false>	Wait mode, default false (see below)

   • The file parameter is a positional parameter (required; only one file at a time). Pass the path or URL directly — no --file prefix needed. The script uploads local files automatically.
   • Default (--nowait false): the API waits for completion and returns the final download link.
   • Pass --nowait true: returns taskId immediately; then query with surgepix-query-task.

4. Step 3: Parse output

   Sync success (--nowait false, stdout):

   {"ok":true,"taskId":"task_xxx","sessionId":123,"progress":"succeeded","download":"https://...images.zip","resultType...":4,"resultType":"zip","note":"API 仅返回 ZIP 下载地址，不含单张图片 URL；禁止编造单张链接"}

   Async submitted (--nowait true, stdout) — resolve later with the surgepix-query-task skill:

   {"ok":true,"async":true,"taskId":"task_xxx","sessionId":123,"progress":"processing","download":null,"resultType":"..."}

   Failure (stderr):

   {"ok":false,"error":"..."}

5. Step 4: Present result

   • On success: Show only the download URL from script output. Always show sessionId (note: it is a number type, e.g. 123 ) so the user can pass it in a retry if needed.
   • On failure: Report the error field. Common causes:
     • unsupported_file_format — file format not supported
     • file_too_large — file exceeds 50MB
     • invalid_language_code — invalid target language code