maktail/gemini-srt-translator/subtitle-translator

Subtitle Translator Skill

🎯 Role & Agent Protocol (CRITICAL)

When this skill is invoked:

1. YOU ARE THE TRANSLATOR: You (the AI assistant) perform the translation directly in your context window using your own linguistic intelligence.
2. NO API KEY REQUIRED: Do NOT ask the user for an API key or external credentials. The gst agent protocol runs completely locally and does not require an API key.
3. DO NOT RUN EXTERNAL TRANSLATION SCRIPTS: Do NOT look for or execute external Python scripts. Use ONLY the gst agent CLI commands below.
4. VIRTUAL ENVIRONMENT EXECUTION: gst may be installed in a project virtual environment (.venv or venv) rather than globally. If gst is not recognized:

• Use the virtual environment binary: .venv/bin/gst (Linux/macOS) or .venv\Scripts\gst.exe (Windows)
• Or use environment package runners: uv run gst ... / poetry run gst ...

When to Use

• When the user asks to translate a subtitle file (.srt or .ass) into another language.
• When translating multi-part dialogue requiring context awareness and consistent character tone/gender agreement.
• When working with video files (.mp4, .mkv, etc.) that contain extractable subtitle streams.

Subtitle Translation Protocol

Step 1: Start a Translation Session

Run the start command to initialize the session and receive the first batch of subtitle lines:

gst agent start <INPUT_FILE> -l "<TARGET_LANGUAGE>" [--batch-size N] [--context-size N] [--description "<OPTIONAL_CONTEXT>"] [--pretty]

<INPUT_FILE> can be a subtitle file (.srt, .ass) or a video file (.mp4, .mkv, .avi, etc. — embedded subtitles will be automatically extracted).

CLI Options Reference

The CLI outputs a JSON response with next_batch containing:

• batch: Array of [{"index": "0", "text": "Original text"}, ...] to translate.
• original_context: Previous original source lines (empty by default unless --context-size > 0 is passed).
• translated_context: Previous translated lines for continuity (empty by default unless --context-size > 0 is passed).

Optimal Batch Size Guidance (`-b` / `--batch-size` is optional, defaults to 100):

As an agent, select the batch size you find most optimal for your model capabilities and the file length:

- Recommended Default (80–120 lines): Optimal balance between narrative context, translation accuracy, and fast validation.

- High-Capacity Models: Feel free to use 100–150 lines to translate full scenes in fewer turns.

- Short Files / Anime Episodes (< 300 lines): 60–80 lines provides 3–4 quick, responsive turns.

- Constrained Output / Local Models: Use 40–60 lines to guarantee the full JSON array fits comfortably within the model's output generation limits.

Step 2: Translate In-Context & Commit Translated Batch

1. Translate each item in batch into the target language, preserving the exact item count and indices.
2. Save the translated JSON array to a temporary file (e.g. batch_1_translated.json).
3. Commit the file:

gst agent commit <INPUT_FILE> --data-file batch_1_translated.json

Commit Data Format:

[
  { "index": "0", "text": "Bonjour le monde !" },
  { "index": "1", "text": "Comment vas-tu aujourd'hui ?" }
]

Step 3: Repeat Until Complete

Each successful commit automatically saves progress and returns the next_batch. Repeat Step 2 until the response returns "status": "completed".

Step 4: Cleanup Temporary Files

Delete the temporary batch JSON files (e.g. batch_1_translated.json) either progressively as each batch is committed or after the entire translation session finishes, keeping the workspace clean.

Helper Commands

gst agent status <INPUT_FILE> [--pretty]   # Check progress status
gst agent next <INPUT_FILE> -l "<TARGET_LANGUAGE>" [--pretty] # Re-fetch current pending batch
gst agent reset <INPUT_FILE> [--pretty]    # Reset translation progress

Translation Rules

1. Translation Item Parity: The output JSON array must contain the exact same number of items with identical indices (index).
2. Formatting Preservation: Preserve all newlines (\n), italic tags (<i>...</i>), and ASS styling tags ({\an8}, {\pos(...)}, etc.).
3. Punctuation & Tone: Maintain dialogue flow, character voice, and natural target language phrasing without altering structural markers.