SurgePix Image Translator

Translate text on one or more images to a target language while preserving the background, using the platform API. Use when the user asks to translate image text, localize a poster/screenshot, or convert on-image copy to another language.

What the Skill Does

Workflow

1. Step 0: Check environment (required)

   Before first use, run the environment check:

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

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

2. Step 1: Identify the input

   • Local file(s) → script uploads automatically, then calls API
   • URL(s) → script uses them directly
   • Ask the user for the target language if not specified. Infer from user language or explicit request (see Language consistency); do not blindly default to en

   Language consistency

   --language is the target language for on-image text, not the agent's reply language.

   Priority	Rule
   1	User explicitly names a target (e.g. "translate to English", "翻译成日文") → use that language code
   2	User does not specify target → infer from intent: English request → --language en; 中文请求 → --language zh; 日本語 → --language ja
   3	Ambiguous → ask the user which target language they want

   • Always pass --language — do not rely on the script default (en) without checking user intent.
   • Reply to the user in the same language they used in their request (agent reply ≠ --language target).

3. Step 2: Collect inputs

   • The user must provide at least one image. Accept either:
     • Local file path(s) (e.g. ./poster.png)
     • URL(s) pointing to images
   • Language (required in practice): target language code — en / zh / ja, etc. Always pass based on user intent (see Language consistency).
   • Session ID (optional): if the user is retrying, use the sessionId from the last run. Omit on first run — the platform auto-creates a new session.
   • Validate each file before submitting:
     • Supported formats: JPEG, JPG, PNG, WEBP
     • Maximum size: 20MB per file
     • If unsupported or oversized, inform the user and ask for a different file.

4. Step 3: Submit the translation task

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

   Parameters

   Field	Required	Description
   <file path or URL> [<image2> ...]	Yes	Positional argument(s). One or more local paths or image URLs
   --language <code>	Yes*	Target language for on-image text, e.g. en, zh, ja. Always pass — match explicit request or user's language
   --session-id <sessionId>	No	Omit on first run; provide on retries to group iterations in one session
   --nowait <true|false>	No	false = sync: API waits and returns final download. true = async: returns taskId; resolve via surgepix-query-task

   • Image parameters are positional arguments (at least one required). Pass file paths or URLs directly — no --file prefix. The script uploads local files automatically.
   • Default (--nowait false): API waits for completion and returns the final download URL.
   • Pass --nowait true to return the taskId immediately; resolve later with surgepix-query-task.

5. Step 4: Parse output

   Sync success (--nowait false, stdout):

   {"ok":true,"taskId":"task_abc123","sessionId":123,"progress":"succeeded","download":"https://...","imageCount":1,"resultType":"image"}

   Async submitted (--nowait true, stdout):

   {"ok":true,"async":true,"taskId":"task_abc123","sessionId":123,"progress":"processing","download":null,"imageCount":1,"resultType":"image","hint":"..."}

   Failure (stderr):

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

6. Step 5: Handle the result

   • On success: Show the download URL.
     • resultType: "image" — single translated image
     • resultType: "zip" — multiple images packaged as ZIP
   • Always show sessionId (number type, e.g. 123) so the user can retry in the same session.
   • On failure: Report the error field. Common causes:
     • unsupported_image_format — file format not supported
     • image_too_large — file exceeds 20MB

7. Step 6: Session sync and iteration

   • Results are attached to the session (auto-created or reused). The user can view all iterations on the platform frontend.
   • To retry, pass --session-id 123 — both attempts appear in the same session history.

Notes

• Single image → download is an image URL; multiple images → download is a ZIP URL.
• Supported input formats: JPEG, JPG, PNG, WEBP. Max file size: 20MB per image.
• The download link is valid for 24 hours; download before it expires.
• Always display the sessionId from the output (note: it is a number type, e.g. 123). Pass --session-id 123 on retry to keep iterations in one session.
• Always pass --language based on user intent — do not blindly default to en.
• Image parameters are positional arguments — pass paths or URLs directly, no --file prefix.
• Must run check_env.mjs before first use in each session.
• Never pass local paths to the API — the script handles upload internally.
• Never invent download URLs — only use the download value from output.
• Never expose auth tokens in logs or output.