superjj007/agent-document-skills/md-translate

Markdown Translation

Translate a Markdown source file to Simplified Chinese without modifying the source. Write translation.md, resumable source/translation chunks, and a filled translation prompt beside the source unless the user chooses another output name.

Choose the runtime

Default to host: use the current agent's own model capability. Do not ask for a separate LLM API key and do not make an external LLM request.

Only use an external runtime when the user explicitly requests it or has already configured LLM_PROTOCOL to one of:

• openai-chat
• openai-responses
• anthropic-messages

These names describe HTTP wire protocols, not providers. Do not maintain a provider catalog or assume that a compatible endpoint supports every model or field.

Privacy and authorization gate for external APIs

Host mode does not need this LLM API gate. Before the first external LLM network call for each source document:

1. State that Markdown text chunks will be sent to the configured endpoint host.
2. State the source path, approximate word count, protocol, model, endpoint host, and output path.
3. If the document may be confidential, contain personal data, or the user's authorization is unclear, obtain confirmation before sending it. A request that explicitly names the external endpoint and the exact document can count as confirmation when no sensitivity is apparent.
4. Never ask the user to paste an API key into chat. Never print, log, or write the key into the workspace.

Analyze the source

Read enough of the source to identify:

• document type, domain, authorial voice, target reader, and desired style;
• 10-30 recurring terms requiring consistent Chinese translations;
• References headings, formulas, tables, images, code, and OCR artifacts.

Do not read or send more content than needed before the user authorizes the API call.

Build the translation prompt

Copy assets/prompt-template.md to <source-directory>/.translate-prompt.md and fill:

• {{SOURCE_DESCRIPTION}}
• {{AUDIENCE_AND_STYLE}}
• {{GLOSSARY}}
• {{SPECIAL_NOTES}}

Use a Markdown glossary table. Preserve commands, identifiers, API names, URLs, DOI values, citations, formulas, code, and image paths. Keep References entries in their original language unless the user explicitly requests otherwise. The script recognizes References headings at Markdown levels 1 through 6, translates the heading to 参考文献 at the same level, and appends the original entries without sending them for translation.

Preflight

1. Locate scripts relative to this skill directory; do not assume a platform-specific install root.
2. Require Python 3.9+. Host mode uses only the standard library.
3. For an external runtime, prefer uv run: the entry script declares httpx with PEP 723, so uv creates an isolated cached environment automatically. If uv is unavailable, install requirements.txt only with the user's approval.
4. In external mode, require LLM_API_KEY and LLM_MODEL. LLM_BASE_URL is optional for official OpenAI and Anthropic endpoints and required for other compatible endpoints.
5. Do not claim that a model is currently available without checking the endpoint response or current provider documentation.
6. Use --dry-run to inspect chunking without requiring a key or calling an API.

Run translation

From the skill root, prepare the host-mode chunks:

python3 scripts/translate.py \
  --input <source.md> \
  --prompt <source-directory>/.translate-prompt.md

When the script prints HOST MODE, read each listed chunk-NNN.md, apply the filled prompt, and write only the translated Markdown to the matching chunk-NNN-zh.md. Do not add commentary or code fences. Process a bounded number of chunks at a time when context is limited. Then rerun the same command; when no chunks remain, the script merges translation.md.

For an explicitly authorized external runtime, automatically resolve httpx in an isolated environment:

uv run scripts/translate.py \
  --input <source.md> \
  --prompt <source-directory>/.translate-prompt.md \
  --protocol openai-responses

Fallback when uv is unavailable and the user authorizes installing into their selected Python environment:

python3 -m pip install -r requirements.txt
python3 scripts/translate.py <same-options>

Useful options:

--protocol <runtime>     default: host
--model <model>          external API model; otherwise LLM_MODEL
--max-words 1200        approximate English words per chunk
--parallel 6            concurrent API requests
--output <filename>     default: translation.md
--no-refs-split         translate the References section too
--dry-run               show the plan without an API call
--reset-cache           replace an incompatible translated-chunk cache

Successful translated chunks are cached in chunks/ and skipped on rerun. If the source, prompt, runtime, model, endpoint host, or chunking settings change, do not silently reuse incompatible cached translations; follow the script's cache-mismatch instructions.

Quality check

Inspect the beginning, middle, and end of translation.md. Verify:

• heading hierarchy and Markdown structure;
• glossary consistency and natural Chinese prose;
• formulas, code, variables, citations, numbers, dates, DOI values, URLs, and image paths;
• English References when split mode is active;
• absence of model preambles and chunk boundary markers.

Delete only the specific failed translated chunk when retrying a local quality problem. Do not delete the entire cache without explaining the consequence to the user.

Report

Report output path, runtime, source/body/reference word counts, total/successful/failed chunks, resume behavior, and quality-check findings. In external mode also report protocol, model, and endpoint host. Never report an API call as successful when it was not run.