Markdown-Dateien übersetzen, ohne Code, Links oder Front Matter zu beschädigen

Um eine Markdown-Datei zu übersetzen, übersetzt man den Fließtext und lässt die technischen Bestandteile unangetastet: Front-Matter-Schlüssel, Code, URLs, Linktexte, Komponenten-Tags und Fußnoten-Labels müssen bytegenau zurückkommen. Danach prüft man drei Dinge, die auch eine sorgfältige Übersetzung noch kaputt macht: Links auf Überschriften, Code-Kommentare und – im Chinesischen, Japanischen oder Koreanischen – die Abstände um fetten Text und Zahlenbereiche.

Wir haben eine 73-zeilige MDX-Seite neunmal mit einem lokalen Modell ins vereinfachte Chinesisch übersetzt, dabei drei verschiedene Prompts verwendet und jedes Ergebnis mit einem Skript geprüft. Die Teile, um die man sich üblicherweise sorgt, überstanden alle neun Durchläufe: Code, Inline-Code, URLs, die Tabelle, die JSX-Komponente und die Aufgabenliste. Drei andere Dinge gingen schief. Der Link auf eine Überschrift brach in allen neun Durchläufen. Die Code-Kommentare wurden in allen sechs Durchläufen übersetzt, die die ganze Datei übermittelten – auch in drei Durchläufen, in denen der Prompt ausdrücklich sagte, den Code nicht anzufassen. Und der Prompt, der die Syntax hinter Platzhaltern versteckte – was nach der sichersten Option klingt –, beschädigte das Front Matter in allen drei seiner Durchläufe.

Kurzantwort: Was übersetzen und was unangetastet lassen

Alles andere ist gewöhnliche Prosa: Absätze, Listeneinträge, Tabellenzellen und Blockzitate.

Was wir getestet haben

Wir haben sample-source.mdx geschrieben, eine Dokumentationsseite für eine fiktive Lese-App namens Shelfmark. Sie ist im MDX-Stil verfasst, wie ihn Docusaurus und ähnliche Dokumentationsseiten verwenden, mit je einem Beispiel für jedes Konstrukt aus der obigen Tabelle, plus einem harten Zeilenumbruch mit zwei Leerzeichen, einem fetten Link, einer fetten Phrase, die mit einer Klammer endet, zwei Zahlenbereichen mit Gedankenstrichen und einem seiteninternen Link zur Überschrift „Keep one glossary for the whole book.“

Dann haben wir ein lokales Modell gebeten, sie auf drei Arten ins vereinfachte Chinesisch zu übersetzen:

1. Ganze Datei. Fügen Sie die gesamte Datei ein und fordern Sie die übersetzte Datei zurück.
2. Angewiesen. Dasselbe, plus sechs Regeln: Frontmatter-Schlüssel beibehalten, nichts innerhalb von Code ändern, URLs und Referenzdefinitionen beibehalten, Importe, Tags und Kommentare beibehalten, Fußnotenbezeichnungen und Admonition-Marker beibehalten und Überschriften, Linktext, Alt-Text und das title-Attribut übersetzen.
3. Geschützt. Ersetzen Sie Code, Inline-Code, URLs, Tags, Kommentare, Fußnotenbezeichnungen, Admonition-Marker und Frontmatter-Zeilen durch nummerierte Platzhalter wie ⟦12⟧, übersetzen Sie den Rest und setzen Sie dann die Originale wieder ein. Die Werte von title und description blieben zur Übersetzung freigelegt, und wie sich herausstellte, auch die ----Zeilen des Frontmatters und die schließenden Anführungszeichen.

Das Modell war Qwen 3.6 27B (Q4_K_M) in LM Studio, mit deaktiviertem Denken und Temperatur 0,3, auf einem Apple M4 Max mit 64 GB Arbeitsspeicher. Wir haben jede Bedingung dreimal ausgeführt, insgesamt neun Läufe, am 25. Oktober 2026. Das Skript ist run_llm_markdown_test.py, und alle neun Ausgaben sind unverändert veröffentlicht; die README listet jede Datei auf. Wenn Sie noch nie ein lokales Modell eingerichtet haben, deckt unser Leitfaden zur lokalen LLM-Übersetzung die Einstellungen ab.

Dies war ein kleiner Test mit einem Modell, einem Sprachpaar und einer Seite. Er zeigt, welche Probleme auftreten und wie man sie erkennt. Er bewertet keine Modelle oder Prompts.

Ergebnis: Die Syntax überlebte; die Links und Entscheidungen nicht

Wir haben jede Ausgabe mit check_markdown_translation.py geprüft und jede mit remark und dem MDX-Compiler gerendert. Die vollständige Ausgabe des Checkers steht in check-results.txt, und results.csv enthält eine Zeile pro Lauf.

Die ersten Zeilen sind die gute Nachricht. Dieses Modell gab die Markdown-Syntax unversehrt zurück, als wir die ganze Datei einfügten; wir fanden nichts, was in Code, URLs oder Tabellen zu korrigieren war. Die letzten vier Zeilen zeigen, wo die Arbeit liegt, und keine davon erscheint als Fehler beim Erstellen der Website.

1. Übersetzte Überschriften brechen Links zu ihnen

Das Beispiel verlinkt seinen Glossarabschnitt mit [glossary section](#keep-one-glossary-for-the-whole-book). Jeder Durchlauf übersetzte die Überschrift, wie es sein soll, und jeder Durchlauf behielt das Linkziel bei, wie es sein soll. Das Ergebnis ist ein Link auf eine ID, die nicht mehr existiert.

Die meisten Markdown-Tools erzeugen Überschriften-IDs aus dem Überschriftentext. Pandocs Dokumentation beschreibt den Bezeichner als „basierend auf dem Überschriftentext“, und Docusaurus warnt, dass man eine Überschrift ändern oder übersetzen möchte, „ohne die bestehende ID zu aktualisieren, um Links nicht zu brechen“. Sobald die Überschrift 为整本书保留一个术语表 lautet, ist ihre generierte ID chinesisch, und #keep-one-glossary-for-the-whole-book scrollt nirgendwohin. Die Seite wird immer noch erstellt, also sagt einem niemand etwas.

Man kann das auch nicht durch Bearbeiten des Links nach der Übersetzung beheben. Über neun Durchläufe schrieb das Modell dieselbe Überschrift auf vier verschiedene Arten, sodass sich die generierte ID bei jeder erneuten Übersetzung wieder ändern würde. Die Lösung gehört vor die Übersetzung: Geben Sie jeder Überschrift, auf die verlinkt wird, eine feste ID.

• Verwenden Sie in Docusaurus MDX ## Keep one glossary for the whole book {/* #keep-one-glossary */}. Docusaurus merkt an, dass die ältere Form {#id} „keine gültige MDX-Syntax mehr“ ist, und sein Befehl write-heading-ids fügt IDs für Sie zu jedem Dokument hinzu.
• Verwenden Sie in Pandoc und in Markdown-Prozessoren, die PHP Markdown Extra folgen, {#keep-one-glossary} am Ende der Überschrift.

Die ID bleibt dann in jeder Sprache gleich, und der Prüfer behandelt sie als das Linkziel.

2. Codekommentare werden übersetzt, und der sichtbare String nicht

Das Beispiel enthält einen Shell-Kommentar und einen YAML-Kommentar:

library:
  name: "My books"   # shown in the sidebar
  sort: title

Alle sechs Durchläufe, die die ganze Datei sendeten, übersetzten beide Kommentare, einschließlich der drei, bei denen die Eingabeaufforderung sagte: „Ändern Sie nichts innerhalb von eingezäunten Codeblöcken.“ Der Code selbst blieb in allen neun Durchläufen unberührt. Währenddessen blieb "My books", das laut Kommentar in der Seitenleiste angezeigt wird, in allen neun Durchläufen auf Englisch. Das Modell tat das Gegenteil dessen, was eine lokalisierte Seite braucht: Es übersetzte den Hinweis für Entwickler und ließ die Beschriftung, die Leser sehen werden, unverändert.

Keine der beiden Entscheidungen ist in jedem Fall falsch. Für ein Tutorial, dessen Leser den Code in ihr eigenes Projekt kopieren, helfen übersetzte Kommentare. Für Referenzdokumentation, deren Code mit einem Repository übereinstimmen muss, bringen sie die Seite mit der Quelle in Widerspruch. Treffen Sie die Entscheidung einmal für das Projekt und prüfen Sie String-Werte in Konfigurationsbeispielen von Hand, denn kein Tool kann eine Anzeigebeschriftung von einem Bezeichner unterscheiden. Der Prüfer meldet aus diesem Grund reine Kommentaränderungen als Warnungen.

3. Die sicher wirkende Methode brach das Front Matter

Die geschützte Bedingung tat, was sie versprach: Alle 32 Platzhalter kamen in allen drei Durchläufen zurück, sodass Code, URLs und Tags perfekt wiederhergestellt wurden. Aber unser Skript ließ zwei kleine Dinge außerhalb der Platzhalter: die ----Zeile, die das Front Matter öffnet, und das schließende Anführungszeichen nach dem übersetzten Titel und der Beschreibung. Das Modell ließ sie alle in allen drei Durchläufen weg. Die Datei begann so:

title: "导出您的书库
description: "在更换设备之前，请备份您的笔记和书籍。
slug: export-library

Ohne das öffnende --- sieht ein Markdown-Parser kein Front Matter mehr. Er liest die sechs YAML-Zeilen plus das schließende --- als Überschrift, sodass die Seite mit einer großen Überschrift beginnen würde, die das YAML enthält. Sie kompilierte trotzdem als MDX. Das --- wieder einzufügen reicht auch nicht: Der YAML-Parser lehnt die beiden nicht geschlossenen Anführungszeichen ab.

Die Lehre ist nicht, Platzhalter zu vermeiden. Sie lautet, dass alles, was Sie ungeschützt lassen, verändert zurückkommen kann, und dass Front Matter gar nicht als Teil der Seite an das Modell gehen sollte. Parsen Sie es, senden Sie nur die leserorientierten Werte (title, description) als separate Strings und schreiben Sie die Übersetzungen zurück in die ursprüngliche Struktur. Das sind ein paar Zeilen Code und beseitigt die ganze Problemklasse.

Fetter Text und Bereiche in Chinesisch, Japanisch und Koreanisch

Zwei weitere Probleme traten in unseren neun Durchläufen nie auf, aber es lohnt sich, danach zu suchen, weil sie Seiten stillschweigend brechen, und beide haben BookTranslators eigenen Blog getroffen. Der Blog ist in MDX geschrieben und maschinell in 27 Sprachen übersetzt, und in einem geplanten Übersetzungslauf scheiterten zwei koreanische Artikel dreimal hintereinander an unserer Strukturprüfung. Die Ursachen waren die beiden folgenden Muster.

Fettdruck, der mit einem Satzzeichen endet. CommonMark entscheidet, ob ** Fettdruck öffnen oder schließen kann, indem es die Zeichen auf beiden Seiten betrachtet. Ein schließendes **, das direkt auf ein Satzzeichen folgt, muss von einem Leerzeichen, einem Satzzeichen oder dem Zeilenende gefolgt werden; dies ist die Right-Flanking-Regel. Im Englischen steht dort immer ein Leerzeichen. Im Chinesischen, Japanischen und Koreanischen oft nicht. So zeigt 打开**设置 → 导出（测试版）**并选择 wörtliche Sternchen, weil der Fettdruck mit einer Vollbreite-Klammer endet und direkt von 并 gefolgt wird. Dieselbe Zeile ohne die Klammer wird fett dargestellt, ebenso die Zeile mit einem Leerzeichen nach dem **. Ein fetter Link hat dasselbe Problem, weil ein Link mit ) endet: 点击**[导出](./export-options.md)**打开 schlägt fehl, und auch das koreanische **[API](./api.md)**는.

Unser Modell setzte zufällig auf beiden Seiten jedes fetten Ausdrucks ein Leerzeichen, sodass seine Ausgabe korrekt dargestellt wurde. Ein Lektor, der diese Leerzeichen später entfernt, um chinesischen Typografie-Konventionen zu folgen, bringt den Fehler zurück. Sie können alle sieben Varianten in render-cases.md ausprobieren.

Zahlenbereiche mit einer Tilde. Chinesischer und japanischer Text schreibt Bereiche oft als 3~5. GitHub Flavored Markdown-Seiten, die auf remark basieren, verwandeln einzelne Tilden standardmäßig in Durchstreichungen: Die remark-gfm-Option singleTilde ist true, sofern Sie sie nicht ändern. Zwei Bereiche in einem Absatz, wie 需要 3~5 分钟，生成 10~20 MB 的文件夹, werden mit durchgestrichenem Text dazwischen dargestellt. Unser Beispiel verwendete Gedankenstriche, und acht Durchläufe behielten sie bei, während der neunte 3 到 5 schrieb. Bitten Sie um Gedankenstriche oder Wörter in Bereichen, oder setzen Sie singleTilde: false in Ihrer remark-Konfiguration.

Der strukturelle Prüfer markiert beide Muster. Um zu bestätigen, was tatsächlich dargestellt wird, zählt render_check.mjs Fettdruck, Kursivdruck, Durchstreichungen und übrig gebliebene Sternchen in der Quelle und der Übersetzung und versucht eine MDX-Kompilierung:

npm install @mdx-js/mdx@3 unified@11 remark-parse@11 remark-gfm@4
node render_check.mjs source.mdx translated.mdx

Weniger Fettdruck-Knoten oder mehr wörtliche Sternchen in der Übersetzung bedeuten, dass eine Hervorhebung nicht mehr schließt.

Ein Workflow, der hält

1. Korrigieren Sie zuerst die Überschriften-IDs. Fügen Sie jeder Überschrift, auf die etwas verlinkt, explizite IDs hinzu, in der Syntax, die Ihr Site-Generator unterstützt. Tun Sie dies in der Ausgangssprache, einmal, und committen Sie es, bevor irgendetwas übersetzt wird.

2. Nehmen Sie das Front Matter aus der Seite. Übersetzen Sie nur leserorientierte Werte wie title und description als separate Zeichenketten und schreiben Sie sie in das ursprüngliche YAML zurück.

3. Legen Sie die Code-Richtlinie fest. Kommentare übersetzt oder nicht; Anzeigezeichenketten in Konfigurationsbeispielen übersetzt oder nicht. Schreiben Sie es in Ihr Übersetzungsglossar neben die Produktnamen, die nicht geändert werden dürfen, wie Shelfmark in unserem Beispiel.

4. Übersetzen Sie den Textkörper. Verwenden Sie ein Tool, das Markdown parst, oder senden Sie die ganze Seite mit expliziten Regeln. In unserem Test blieb die Syntax intakt, wenn die ganze Seite gesendet wurde; wenn Sie Platzhalter verwenden, schützen Sie vollständige Konstrukte und lassen Sie nichts halb offen.

5. Führen Sie die strukturelle Prüfung aus.

   python3 check_markdown_translation.py source.mdx translated.mdx --keep Shelfmark
   

   Sie vergleicht Front-Matter-Schlüssel und -Werte, Importe, Codeblöcke, Inline-Code, Linkziele, Referenzdefinitionen, Überschriftenebenen, seiteninterne Linkziele, JSX-Tags und -Attribute, MDX-Kommentare, Admonition-Marker, Fußnotenbezeichnungen, Tabellenform, Aufgabenlisten-Kästchen, harte Zeilenumbrüche, Hervorhebungen, die nicht schließen können, Tildenbereiche und Begriffe, die Sie beibehalten möchten. Sie beurteilt nicht die Übersetzungsqualität.

6. Prüfen Sie die Darstellung für CJK-Ziele mit render_check.mjs und fügen Sie nach jedem schließenden **, das auf ein Satzzeichen folgt, ein Leerzeichen hinzu.

7. Bauen Sie die Seite und klicken Sie die Links an. Öffnen Sie die Seite in jeder Sprache, klicken Sie jeden seiteninternen Link an und lesen Sie die Konfigurationsbeispiele. Ein erfolgreicher Build beweist nur, dass die Datei kompiliert.

Für Dokumentation, bei der Genauigkeit zählt, gelten die Terminologie- und Überprüfungsschritte in unserem technischen Übersetzungsworkflow zusätzlich.

Wo BookTranslator passt

BookTranslators TXT-Übersetzer akzeptiert .txt-, .md- und .mdx-Dateien. Laut Produktseite übersetzt er sie unter Beibehaltung von Absätzen, Zeilenumbrüchen, Sonderzeichen und Textstruktur und teilt große Dateien in Segmente für kontextbewusste Übersetzung auf, sodass Sie ein ganzes Handbuch oder ein in Markdown geschriebenes Buch hochladen können, anstatt es stückweise einzufügen.

Die Produktseite beschreibt keine spezielle Behandlung für Front Matter, Codeblöcke oder MDX-Komponenten, und wir haben dieses Beispiel für diesen Artikel nicht durch BookTranslator laufen lassen. Welches Tool Sie auch verwenden, führen Sie die Schritte 1 bis 3 vor der Übersetzung und die Schritte 5 bis 7 danach aus. Eine Überschrift ohne feste ID verliert immer noch ihre Links, und ein mit Tilden geschriebener Bereich wird immer noch zur Durchstreichung. Wenn Sie ein Buch in mehreren Sprachen veröffentlichen, deckt unser Leitfaden zum Selbstverlag in mehreren Sprachen den Rest dieser Aufgabe ab.

Holen Sie sich die Testdateien

Alles aus diesem Test darf frei wiederverwendet werden:

• sample-source.mdx: das 73-zeilige englische Beispiel;
• check_markdown_translation.py: der strukturelle Prüfer (nur Python-Standardbibliothek);
• render_check.mjs und render-cases.md: die Darstellungsprüfung und die sieben CJK-Testfälle;
• run_llm_markdown_test.py: die drei Prompt-Bedingungen für jeden OpenAI-kompatiblen lokalen Server;
• die neun Ausgaben im Ausgabeordner, zusammen mit check-results.txt und results.csv.