docs-translator

Translate Markdown documentation to zh-TW while preserving code blocks and tag placeholders.

Updated Dec 26, 2022
One-click install
npx skills add https://github.com/ChenHom/note --skill docs-translator
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: docs-translator
Source: https://github.com/ChenHom/note/tree/main/ai/skills/docs-translator
Command: npx skills add https://github.com/ChenHom/note --skill docs-translator

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires gray-matter, openai, simple-git, and includes scripts (resource) and references (resource) and assets (resource) components.

What problem does it solve?

Translating large Markdown documentation often disrupts formatting and code blocks, creating manual toil. This skill delivers an industrial-grade automated workflow that preserves code blocks, inline code, and document structure while translating to zh-TW, with self-healing batch handling and model-aware batching to minimize cost.

Core Features & Use Cases

  • Self-healing batching: processes paragraphs in large batches and automatically falls back to single-paragraph translation when a batch fails.
  • Model-aware optimization: uses different batch sizes for mini models versus flagship models to balance cost and precision.
  • Mechanical masking: preserves block and inline code markers during translation to prevent tag-swapping.
  • Modular pipeline: engine-core, file-io, and orchestrator components for reliability and maintainability.
  • Use case: translate project documentation from docs/ into zh-TW, keeping Mermaid diagrams and code blocks intact.

Quick Start

Run the main pipeline to translate docs/ into zh-TW using an OpenAI API key and a preferred model.

Frequently Asked Questions about docs-translator

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I translate Markdown documentation to zh-TW while preserving code blocks?

To translate Markdown to zh-TW while preserving code blocks, this skill uses mechanical masking to protect block and inline code markers during translation. It prevents tag-swapping and keeps document structure, including Mermaid diagrams, intact throughout the automated workflow.

What is the best way to handle large Markdown translation failures in batches?

Handling large Markdown translation failures is managed through self-healing batching. When a large paragraph batch fails, the pipeline automatically falls back to single-paragraph translation, verifying paragraph integrity and recovering gracefully to ensure the process completes.

How does model-aware batching optimize translation costs for technical docs?

Model-aware batching optimizes translation costs by applying different batch sizes for mini models versus flagship models. This balances cost and precision, allowing you to process large docsets efficiently without overspending on API usage during translation.

Can I use this to automate Markdown translation with OpenAI and keep formatting intact?

Yes, you can automate Markdown translation with OpenAI while keeping formatting intact. The modular pipeline integrates an OpenAI API key with your preferred model, preserving inline code, tags, and document structure throughout the translation run.

Does the automated translation pipeline support Mermaid diagrams and inline code?

Yes, the automated translation pipeline supports Mermaid diagrams and inline code. By mechanically masking code markers and tag placeholders, it ensures that diagrams and inline code blocks remain unaltered and functional in the translated output.

Why does my batch translation fail and how does the pipeline recover?

Batch translation may fail due to API limits, but the pipeline recovers gracefully through self-healing batching. It automatically retries the failed batch by falling back to single-paragraph translation, verifying integrity to ensure the overall document completes successfully.