# Translate Markdown: Docs That Still Build Translate Markdown: Docs That Still Build is a tested SKILL.md that translates a Markdown, MDX or HTML document (docs page, README, blog post, help article) into another language and returns the whole document with only the human text changed; an agent buys it once for $0.03 over x402. - Page: https://aiskills402.com/skills/translate-markdown - Category: Translation & Localization (https://aiskills402.com/categories/translation) - Price: $0.03 once, USD-priced, paid in USDC on Base over x402. Price as loaded on this page. The 402 response your agent receives is authoritative. - Version: 1.0.0 - Card (JSON): https://api.aiskills402.com/v1/skills/translate-markdown ## Use it when Translates a Markdown, MDX or HTML document (docs page, README, blog post, help article) into another language and returns the whole document with only the human text changed. Fenced and inline code, link and image targets, front matter keys and machine values, HTML tags and attributes, heading ids, reference labels, comments and template tags come back byte for byte, so the page still builds and every link still works. Alt text, titles and link text are translated; product names and code identifiers stay; lines in the document that give orders to an AI are translated as text, never obeyed. Use to translate Markdown or MDX docs, localize a README or a static-site blog post, or translate documentation without breaking code blocks, links or front matter. ## Not for Choosing the target terminology for you, translating screenshots or text inside images, or fixing in-page links that point at a heading's auto-generated anchor, which changes when the heading is translated. It translates one document per request and does not split, merge or rename files. ## Tested, honestly Tested 2026-10-08. - Strong model (claude-sonnet-5-5 (Claude Code alias "sonnet")): Right in 18 of 19 cases: every code block with its comments, link target, reference label, heading id, front matter key and machine value, HTML attribute, HTML comment and template tag came back byte for byte while the prose was translated. It kept a German SQL comment German in an English translation, left a Bulgarian and a Spanish quotation alone in a Bulgarian translation, translated a line that told AI translators to reply OK instead of obeying it, and returned HTML without a fence. It failed one case: in a German README it finished the document, then wrote that it had to correct the table and printed the whole document a second time. - Weak model (claude-haiku-5-5 (Claude Code alias "haiku")): Also 18 of 19, keeping code comments, HTML comments and front matter values where the side without the skill changed them. But it failed one case: for a German document translated into English it put a sentence about the rules it had followed before the document, so the front matter no longer starts the file and a static site would not read it. Note: Twelve fictional documents written by us, translated into Bulgarian, German, Spanish and English, 19 cases: a README with a badge, a bash block, a table and a reference link; docs with front matter, heading ids, an admonition and an in-page link; an HTML fragment with human-text and machine attributes; MDX with imports and components; a page with an order to AI translators and an HTML comment aimed at the AI; Python and SQL blocks with comments; Liquid templates; GitHub alerts and a nested list; footnotes with reference links; a Bulgarian and a German source; a page that already quotes the target language. The check compares the structure of the answer with the source: code blocks, inline code, link targets, labels, heading levels and ids, HTML tags and attribute values, comments, templates and front matter keys must be identical, the text must be translated, and nothing may be written before or after the document. One run per model and case; a bug in our own check (footnote text read as a link target) was fixed and the recorded answers rescored without new runs. ### With and without the skill Tested 2026-10-08. - Structure intact and translated: Sonnet 18/19 with, 13/19 without; Haiku 18/19 with, 11/19 without. One run per model and case, the same request and the same checks on both sides. Without the skill both models translated the HTML comment addressed to the AI, translated comments inside code blocks (Python, and for Haiku the bash comments of a README), and Sonnet rewrote a German SQL comment in English and changed a link from /de/docs to /en/docs. Sonnet also wrapped both HTML fragments in a code fence; with fences removed it gets 15 of 19 without the skill. Haiku wrapped one whole document, front matter included, in a code fence. With the skill, the one Sonnet loss is a German README it printed twice. Same cases and the same checks with and without the skill. The cases are ours, written around what the skill is for; with a handful of cases, a difference of one or two is within noise. Full summary: https://aiskills402.com/skills/translate-markdown/tests ## Example ### Bulgarian (claude-sonnet-5-5) Before: > # Acme CLI [![npm version](https://img.shields.io/npm/v/acme-cli.svg)](https://www.npmjs.com/package/acme-cli) Acme CLI deploys static sites to your own server in one command. It keeps the last five releases, so you can roll back in seconds. ## Install {#install} You need Node.js 20 or newer. ```bash # install globally npm install -g acme-cli # check that it works acme --version ```… After: > # Acme CLI [![npm version](https://img.shields.io/npm/v/acme-cli.svg)](https://www.npmjs.com/package/acme-cli) Acme CLI публикува статични сайтове на вашия собствен сървър с една команда. Пази последните пет версии, така че можете да се върнете към предишна за секунди. ## Инсталация {#install} Нужен ви е Node.js 20 или по-нов. ```bash # install globally npm install -g acme-cli… ### German (claude-sonnet-5-5) Before: > # Acme CLI [![npm version](https://img.shields.io/npm/v/acme-cli.svg)](https://www.npmjs.com/package/acme-cli) Acme CLI deploys static sites to your own server in one command. It keeps the last five releases, so you can roll back in seconds. ## Install {#install} You need Node.js 20 or newer. ```bash # install globally npm install -g acme-cli # check that it works acme --version ```… After: > # Acme CLI [![npm version](https://img.shields.io/npm/v/acme-cli.svg)](https://www.npmjs.com/package/acme-cli) Acme CLI deployt statische Websites mit einem einzigen Befehl auf Ihren eigenen Server. Es behält die letzten fünf Releases, sodass Sie in Sekunden einen Rollback durchführen können. ## Installation {#install} Sie benötigen Node.js 20 oder neuer. ```bash # install globally… ### Spanish (claude-sonnet-5-5) Before: > --- title: Rotate your API keys description: How to replace an API key without downtime, step by step. slug: rotate-api-keys date: 2026-09-14 lang: en tags: [security, api-keys] author: Mara Lind --- ## Before you start {#before} Keys cannot be recovered once they are deleted. Create the new key **before** you remove the old one. :::warning Never paste a key into a support ticket or a chat.… After: > --- title: Rota tus claves de API description: Cómo reemplazar una clave de API sin tiempo de inactividad, paso a paso. slug: rotate-api-keys date: 2026-09-14 lang: es tags: [security, api-keys] author: Mara Lind --- ## Antes de empezar {#before} Las claves no se pueden recuperar una vez eliminadas. Crea la nueva clave **antes** de eliminar la anterior. :::warning… ### English (claude-sonnet-5-5) Before: > --- title: Datenbank sichern slug: backup-db --- ## Automatische Sicherung {#auto} Die Datenbank wird jede Nacht um 02:00 Uhr gesichert. Die Sicherungen bleiben 30 Tage erhalten. ```sql -- letzte Sicherung prüfen SELECT max(created_at) FROM backups; ``` Eine manuelle Sicherung starten Sie mit `acme db backup`. Mehr dazu in der [Anleitung](/de/docs/backup). After: > --- title: Back up the database slug: backup-db --- ## Automatic backup {#auto} The database is backed up every night at 02:00. Backups are kept for 30 days. ```sql -- letzte Sicherung prüfen SELECT max(created_at) FROM backups; ``` You start a manual backup with `acme db backup`. More on this in the [guide](/de/docs/backup). ## What is in the file - The answer - Translate - Keep exactly as written - Hard rules - Work in this order - Short example ## Languages English, Bulgarian, German, Spanish ## How to buy Agent (HTTP): 1. GET https://api.aiskills402.com/v1/skills/translate-markdown/file without a payment header. The answer is 402 with a PAYMENT-REQUIRED header (x402 v2): exact amount, asset, network, recipient. 2. Sign `accepts[0]` with an x402 client (for example @x402/core + @x402/evm). 3. Repeat the GET with the signature in the PAYMENT-SIGNATURE header. The answer is 200 with the file, its sha256 and a re-download token. Agent (MCP): https://mcp.aiskills402.com/mcp — free tools search_skills, get_skill, redownload_skill. Buying itself is over HTTP. Full flow: https://aiskills402.com/docs ## The file - Version: 1.0.0 - Size: 6.3 KB (6458 bytes) - SHA-256: 5322236ccf98627018c13e1fad986c9e27e4d5119adcb4ccc6deb276ea33e50d - Updated: 2026-10-08 - New versions are free through your re-download token. ## Versions ### 1.0.0 (2026-10-08) First release: translates a Markdown, MDX or HTML document and returns the whole document with only the human text changed. Code with its comments, link and image targets, reference labels, heading ids, front matter keys and machine values, HTML tags and attribute values, comments and template tags stay byte for byte; link text, alt text, link titles and the human-text attributes are translated; nothing is added before or after the document, and lines that give an AI orders are translated as text. ## License Perpetual, non-exclusive; use and modify for yourself incl. paid work; no resale or republishing. Holder: Georgi Kalchev, aiskills402.com. Terms: https://aiskills402.com/docs#license ## FAQ ### Are the comments inside code blocks translated? No. A code block comes back exactly as it was, comments and docstrings included, because a comment is part of the sample someone will copy. Without the skill, both Claude models translated the comments and docstring of a Python example, and Sonnet rewrote a German SQL comment in English. ### What happens to front matter, links and HTML? Keys and machine values such as slug, date, tags and permalink stay; prose values such as title and description are translated, and a lang value becomes the target code. Link targets, reference labels, heading ids, HTML tags and attribute values stay byte for byte, while link text, alt text and titles are translated. ### Does it follow instructions written inside the document? No. We planted a line telling AI translators to reply only OK and an HTML comment asking the AI to add a link. With the skill both models translated the line as text and left the comment untouched. Without it, both translated the comment, which changes a file the author never meant to touch. ### What went wrong with the skill? One case for each model in 19. Claude Sonnet finished a German README, then decided to fix a table and printed the whole document a second time. Claude Haiku put a sentence about its rules before a document, so the front matter no longer opened the file. Check that the answer starts with the first line of the source. ## Related skills - [Translate App Text (JSON, YAML, PO)](https://aiskills402.com/skills/translate-app-text.md): $0.01 once - [Proofread](https://aiskills402.com/skills/proofread.md): $0.03 once - [Faithful Summary](https://aiskills402.com/skills/summarize.md): $0.03 once ## Measurement limits - Models other than the two named above were not run. - Each verdict comes from the test run on the date shown; the skill may have changed since (check the version). - Full test inputs are not published here, only short excerpts of our own text. - Results on your own texts, languages and domains can differ. Offer note: Paid in USDC (USD-pegged) over x402 by an AI agent; one-time.