Wie man technische Dokumente übersetzt, ohne den Code zu beschädigen

TABLE OF CONTENTS

Technische Dokumentation ist unerbittlich: Ein einziger fehlerhafter Codeblock, Platzhalter oder Anker kann Builds unterbrechen, Leser verwirren oder Copy-Paste-Fehler verursachen. Dieser Leitfaden bietet Ihnen einen wiederholbaren, sicheren Workflow, um technische Dokumente mit Zuversicht zu übersetzen – während der Code intakt bleibt und die Dokumente versandbereit sind.

Für wen ist das: technische Redakteure, Entwickler-Advocates und Übersetzer, die an Entwicklerdokumentationen, API-Leitfäden und README-ähnlichen Inhalten arbeiten.

Auf einen Blick:

Verstehen, was niemals übersetzt werden darf (Code, Schlüssel, Tokens)
Syntax bewahren, die von Tools analysiert wird (Fences, Klammern, Anker)
Strukturierte Daten und Links nach Bearbeitungen validieren
Automatisierung nutzen, um Probleme vor der Veröffentlichung zu erkennen

Vorbereitungen vor der Übersetzung

Inhaltsarten inventarisieren

Markdown (Überschriften, Links, Tabellen), Codeblöcke, Inline-Code
Strukturierte Daten: JSON/YAML/TOML-Snippets und Konfigurationsdateien
Screenshots, Diagramme und eingebettete Visuals

Nicht übersetzbare Tokens definieren

Dateipfade, Paketnamen, Importe, API-Namen, CLI-Flags, Umgebungsvariablen
Platzhalter und Variablen: {count}, %s, $HOME, {{token}}
Dateinamen und Erweiterungen: config.yaml, .env, .md, .json

Konsistenz-Leitplanken etablieren

Glossar/Termbase für Fachbegriffe und Produktnamen
Styleguide: Ton, Formalität, Zeichensetzung, Groß-/Kleinschreibung, Überschriftenregeln
Anker/Slug-Strategie pro Locale (stabil vs lokalisiert)

Sichere Validierung einrichten

Staging-Build zur Validierung von Markdown/Links nach jeder Charge
Parser/Linter für JSON/YAML/TOML
Link-Checker und Anker-Validator in CI

Kernschutzmaßnahmen

Code, Bezeichner, Schlüssel, Dateinamen, Umgebungsvariablen oder Flags nicht übersetzen.
Zeichensetzung und Syntax bewahren, die von Tools analysiert wird (Backticks, Klammern, Pipes).
Bedeutenden Leerraum beibehalten: Einrückung für Code und Listenstruktur.
Konsistent eingezäunte Codeblöcke mit einem Sprach-Tag verwenden (js, bash, etc.).
Übersetzerhinweise bevorzugen statt „Fehlerbehebung“ der Logik – Probleme stattdessen den Wartenden melden.

Codeblöcke und Inline-Code

Behalten Sie Codeblöcke, Sprachhinweise und Inhalte unverändert bei. Übersetzen Sie nur Kommentare und menschenlesbare Zeichenfolgen, falls erforderlich.

Beispiel—sicher vs. unsicher:

// SICHER: Nur der Kommentar wird lokalisiert
// Holt ein Benutzer-Token
import { getToken } from "@acme/sdk";
const token = await getToken();

// UNSICHER: Übersetzen Sie keine Bezeichner/Importe/Paketnamen
// import { obtenirJeton } from "@acme/sdk"; // ❌

Inline-Code muss wörtlich bleiben:

Gut: „Führen Sie npm install -g acme-cli aus und dann acme login.“
Schlecht: „Führen Sie npm install -g acme-cli aus und dann acme connexion.“ ❌

Überprüfen Sie die Kopierbarkeit: Wenn ein Leser einen Ausschnitt kopiert, sollte er wie in der Quelle ausgeführt werden.

Platzhalter und ICU MessageFormat

Bewahren Sie Platzhalter genau auf, einschließlich Leerzeichen und Interpunktion um sie herum.

# Verändern Sie keine Tokens oder Abstände
echo "Verarbeite {count} Dateien"   # ✅
echo "Verarbeite { count } Dateien" # ❌ fügt Leerzeichen innerhalb der Klammern hinzu

ICU-Beispiel:

{count, plural,
  =0 {Keine Nachrichten}
  one {# Nachricht}
  other {# Nachrichten}
}

Ändern Sie keine Schlüssel (count, one, other).
Übersetzen Sie nur die menschenlesbaren Teile („Nachricht“, „Nachrichten“).
Fügen Sie ohne Produkthinweise keine Pluralkategorien hinzu oder entfernen Sie diese.

Links, Anker und Slugs

Halten Sie die Markdown-Link-Syntax und die Auflösungsstrategie konsistent.

[Lesen Sie den API-Leitfaden](/api/getting-started)  
[Siehe den Konfigurationsabschnitt](#configuration)

Übersetzen Sie den Linktext bei Bedarf; seien Sie vorsichtig mit URLs und Ankern.
Anker: Entweder stabile Anker über alle Sprachen hinweg beibehalten oder Anker pro Sprache generieren und Verweise entsprechend aktualisieren.
Überprüfen Sie, ob relative Pfade und Hash-Anker nach der Übersetzung noch aufgelöst werden.
Übersetzen Sie keine Dateierweiterungen oder Abfrageparameter.

Strukturierte Daten (JSON/YAML/TOML)

Übersetzen Sie nur Werte—niemals Schlüssel, Typen oder Strukturen. Immer nach dem Bearbeiten erneut parsen.

JSON:

{
  "title": "Benutzerhandbuch",
  "cta": "Loslegen",
  "limits": { "max": 5, "unit": "Anfragen/Sekunde" }
}

Schlüssel wie title, cta, limits, max müssen unverändert bleiben.
Zahlen, Booleans und Nullwerte bleiben als Typen, nicht als Wörter.

YAML (beachten Sie gefaltete Skalare):

note: >
  Zeilen werden zu einem einzigen Absatz zusammengefasst.
  Behalten Sie Einrückungen und Markierungen bei.

Behalten Sie Anführungszeichen, Escape-Zeichen, Einrückungen und nachgestellte Kommas (wo zutreffend) bei.

Dateinamen, CLI und API-Namen

Übersetzen Sie keine Dateinamen, Paketnamen, Endpunkte oder CLI-Flags.
Bewahren Sie die Groß- und Kleinschreibung genau wie in der Quelle (z.B. --DryRun vs --dry-run).
Halten Sie Befehle wörtlich bei; fügen Sie Hinweise hinzu, wenn es länderspezifische Unterschiede gibt.

# Korrekt
kubectl get pods --namespace default

# Falsch (Flag übersetzt) ❌
kubectl get pods --nom-espace defaut

Markdown Stolperfallen

Tabellen: Behalten Sie Pipes und Ausrichtung bei; brechen Sie keine Spalten.

| Option | Beschreibung          |
|-------:|-----------------------|
|   -v   | Ausführliche Ausgabe  |
|   -q   | Ruhiger Modus         |

Ermahnungen/Notizen: Behalten Sie die von Ihrem Tooling verwendeten Markierungen bei.
Inline-HTML: Vermeiden Sie das Berühren von Tags/Attributen.
Fußnoten: Behalten Sie IDs und Reihenfolge bei.
Intelligente Anführungszeichen: Bevorzugen Sie gerade Anführungszeichen in Code-Kontexten.

Visuals und Barrierefreiheit

Lokalisieren Sie Alt-Text für die Bedeutung, nicht für den Pixelinhalt.
Bevorzugen Sie sprachunabhängige Screenshots (hervorheben der Benutzeroberfläche, nicht der Sprache) oder bieten Sie pro Sprache spezifische Sets an.
Halten Sie Diagramm-Quelldateien (z.B. Mermaid) über alle Sprachen hinweg synchron.
Vermeiden Sie eingebetteten Text in Bildern; externalisieren Sie Beschriftungen und Labels.

SEO und Metadaten

Übersetzen Sie Titel, Beschreibungen und Überschriften mit sprachlich angemessenen Schlüsselwörtern.
Halten Sie kanonische URLs und hreflang konsistent mit den Site-Regeln.
Übersetzen Sie keine Meta-/Property-Schlüssel oder JSON-LD-Schlüssel.
Passen Sie Slugs an Ihre Ankerstrategie an, um 404-Fehler zu vermeiden.

Workflow und Automatisierung

Verwenden Sie einen CAT/LLM-Workflow, der Code-Spannen und Tags beibehält.
Terminologie mit einem Glossar und einer Nicht-zu-übersetzenden Liste sperren.
Fügen Sie Pre-Commit-Hooks hinzu, um Markdown zu linten und JSON/YAML zu validieren.
Führen Sie einen Link-Checker und Anker-Validator bei jedem PR aus.
Änderungen in kleinen, überprüfbaren Abschnitten bündeln und Diffs verfolgen.

Empfohlene Tools (an Ihren Stack anpassen):

Markdown-Linting und Link-Check im CI
JSON/YAML-Parsing-Schritt, um Syntaxregressionen zu erkennen
Regex-Pakete, um Platzhalter und numerische Formate zu scannen

QA und Validierung

Führen Sie diese Überprüfungen vor dem Merge durch:

Bauen Sie die Seite, um Syntaxprobleme zu erkennen: pnpm build
Typ-/Inhaltsüberprüfungen (Astro-Inhaltssammlungen): pnpm astro check
Vorschau und Spot-Test von Schlüsselseiten: pnpm preview
Validieren Sie, ob Codebeispiele kompiliert oder ausgeführt werden (falls zutreffend)
Führen Sie einen Link- und Anker-Checker aus; beheben Sie alle 404s oder kaputte Hashes

Häufige Fallstricke

Versehentliches Übersetzen von Schlüsseln/Platzhaltern.
Code-Zäune oder Tabellen-Pipes brechen.
Lokalisieren von Dateipfaden, Flags oder API-Namen.
Überschriften ändern, ohne Anker-Links zu aktualisieren.
Einfügen von intelligenten Anführungszeichen in Code oder JSON.

Anhang: Schnell-Checklisten

Pre-Flight (5 Punkte)

Glossar und Nicht-zu-übersetzende Liste bereit
Tokens/Platzhalter definiert und geschützt
Anker/Slug-Strategie bestätigt
Link-Ziele zugeordnet (intern vs extern)
Staging-Build verfügbar

Codebeispiel-Sicherheit (5 Punkte)

Zäune und Sprachhinweise intakt
Bezeichner/Imports unberührt; Kommentare nur lokalisiert
Platzhalter und Anführungszeichen erhalten
Copy-Paste-Test bestanden
Veraltete Snippets an Wartungsmitarbeiter gemeldet

Strukturierte Daten (5 Punkte)

Schlüssel und Typen unberührt
Anführungszeichen/Escapes/Einrückungen erhalten
Zahlen und Booleans bleiben als Typen
Parser/Linter lokal bestanden
Diffs auf versehentliche Schlüsseländerungen überprüft

Verwandte Lektüre