Maschinenübersetzung
Diese Seite wurde automatisch von KI übersetzt und kann Fehler enthalten. Bei Unklarheiten konsultieren Sie die englische Quelle.
Internationalisierung¶
Die Dokumentation behandelt Englisch und vereinfachtes Chinesisch als geprüfte kanonische Quellen. Jedes andere aktivierte Gebietsschema ist eine generierte Ableitung. Das Sprachregister, die Quellenweiterleitung, die Modellkonfiguration und die API-Grenzwerte befinden sich in i18n/config.toml.
1. Sprachabdeckung und Quellenweiterleitung¶
Das Register aktiviert absichtlich einen fokussierten Satz von 12 Site-Gebietsschemata. Es deckt alle sechs Amtssprachen der Vereinten Nationen ab: Arabisch, Chinesisch, Englisch, Französisch, Russisch und Spanisch. Zusätzlich werden Japanisch, Koreanisch und traditionelles Chinesisch für Ostasien sowie Deutsch, Italienisch und Portugiesisch für Europa abgedeckt. Englisch und vereinfachtes Chinesisch sind kanonisch, daher werden 10 Gebietsschemata maschinell übersetzt.
Japanisch, Koreanisch und traditionelles Chinesisch verwenden vereinfachtes Chinesisch als Quelle. Alle anderen generierten Gebietsschemata verwenden Englisch. Die Quellenauswahl ist pro Gebietsschema explizit; der Übersetzer rät nie aus einem Gebietsschemanamen oder aus Dokumentzeichen.
Das Hinzufügen eines Gebietsschemas erfordert übereinstimmende Einträge in i18n/config.toml und der MkDocs-i18n-Sprachliste. Die Dokumentationsprüfung lehnt inkonsistente Register ab.
2. Kanonischer-Dokument-Vertrag¶
Jede MkDocs-Seite hat eine englische Datei und eine .zh-CN.md-Datei. Ein Pull-Request, ein Push zu main oder ein manuell ausgelöster Qualitätsdurchlauf, der eine kanonische Version ändert, muss ihr Gegenstück im geprüften Commit-Bereich enthalten. Der Qualitätsworkflow prüft:
- kanonische Paare und Kopplung geänderter Paare;
- Parität der Überschriftenebenen und Code-Fences;
- lokale Links und Quellenverweise;
- Fixture- und Testinventare;
- einen strikten Build jedes konfigurierten Gebietsschemas.
Kanonischer Prosa kann manuell oder mit KI-Unterstützung verfasst werden, muss aber als normale Quelle committet und überprüft werden. Die Übersetzungs-API wird niemals aus einem Pull-Request-Workflow aufgerufen.
3. Überschriftennummerierung und Fragmentstabilität¶
Markdown-Quellen speichern beschreibenden Überschriftentext ohne Gliederungsnummern. Während jedes MkDocs-Builds fügt scripts/mkdocs_heading_numbers.py seitenlokale Nummern zu H2-H6-Überschriften hinzu. Benutzerhandbuchseiten verwenden Kleinbuchstaben bei H2 (a., b.) und Buchstaben-plus-Dezimal-Nachkommen (a.1, a.1.1); andere Seiten behalten dezimale Seitenumrisse. Separat verwendet die linke Benutzerhandbuchnavigation hierarchische Dezimalzahlen wie 1.1. H1-Seitentitel und Navigationselemente der obersten Ebene bleiben unnummeriert. Generierte Nummern sind Präsentationsmetadaten: Das Verschieben eines Abschnitts ändert seine sichtbare Nummer, ohne seine Fragmentkennung zu ändern.
Der Build-Hook macht jede Überschriftenkennung explizit, bevor die sichtbare Nummer hinzugefügt wird. i18n/legacy-heading-anchors.json behält Aliase für Fragmente bei, die veröffentlicht wurden, bevor gespeicherte Gliederungsnummern entfernt wurden. Bearbeiten Sie diese generierte Kompatibilitätskarte nicht beiläufig und fügen Sie keine manuellen Gliederungsnummern zurück in kanonisches oder generiertes Markdown; die Dokumentationsprüfung lehnt sie ab.
4. Generierter-Dokument-Vertrag¶
Generierte Seiten verwenden den MkDocs-Suffix-Modus, wie index.fr.md oder guide/configuration.ja.md. Jede Seite enthält deterministische Frontmatter, die Folgendes aufzeichnet:
- das kanonische Quellgebietsschema und den Pfad;
- den SHA-256-Digest der Quelle;
- das aufgelöste Modell und die Prompt-Version;
- dass die Seite eine maschinelle Übersetzung ist.
i18n/manifest.json zeichnet zusätzlich Ausgabe-Digests und Übersetzungseingabe-Fingerabdrücke auf. Eine Seite wird veraltet, wenn sich ihre Quelle, das Glossar, der Prompt, das Modell oder die generierte Ausgabe ändert. Der Übersetzer fordert nur veraltete Einheiten an, es sei denn, ein vollständiger Neubuild wird explizit angefordert.
Übersetzte Überschriften behalten ihre natürlichen lokalisierten Slugs und erhalten versteckte Aliase für die kanonischen Quell-Slugs. Da Markdown-Linkziele ansonsten vor Modelländerungen geschützt sind, halten diese Aliase gleichseitige und seitenübergreifende Fragmentlinks in jedem Gebietsschema gültig. Die Aliase können offline aktualisiert werden, ohne einen weiteren Übersetzungs-API-Aufruf.
Generierte Dateien dürfen nicht manuell bearbeitet werden. Der Übersetzungs-Workflow des Hauptzweigs regeneriert sie und checkpointet jedes abgeschlossene Gebietsschema als einen Commit auf einem nur generierten Zweig, der von dem exakten qualitätsgeprüften SHA abgeleitet ist. Ein späterer Lauf kann diesen Zweig verifizieren und wiederverwenden, sodass eine Unterbrechung nur das noch laufende Gebietsschema verwirft. main bleibt unverändert, bis der Workflow die erforderliche Prüfung der generierten Sprache, die vollständige Testsuite und den strikten Build aller Gebietsschemata durchgeführt hat. Er überprüft dann, dass main nicht fortgeschritten ist, fördert den validierten Checkpoint durch einen Fast-Forward-Push und stellt dasselbe validierte Site-Artefakt bereit.
5. Geschütztes Markdown und Prompt-Vertrag¶
Vor einer API-Anfrage ersetzt der Übersetzer Frontmatter, Code-Fences, Inline-Code, Linkziele, HTML-Tags und bloße URLs durch unveränderliche Platzhalter. Eine Antwort wird abgelehnt, wenn ein Platzhalter fehlt, dupliziert, erfunden oder außerhalb des wiederherstellbaren Ausgabevertrags verschoben wurde.
Der Prompt erfordert auch identische Überschriftenebenen und Code-Fence-Sprachen. Die Implementierung überprüft diese Eigenschaften unabhängig nach der Wiederherstellung des geschützten Inhalts. Die Übersetzungsausgabe muss ein JSON-Objekt sein; Prosa um das JSON, leerer Inhalt, abnormale Abschlussgründe oder inkompatible Schemata sind Fehler.
Die Markdown- und Navigationskatalog-Prompts sind versioniert unter i18n/prompts/. i18n/glossary.json enthält stabile Produkt- und Befehlsterminologie.
6. Modellkonfiguration und Anmeldeinformationen¶
Das Standardmodell ist als deepseek-v4-flash konfiguriert. Die Implementierung verzweigt nicht auf diesen Namen. Eine zukünftige Modelländerung erfordert nur die Aktualisierung von i18n/config.toml, die Übergabe von --model oder das Setzen der DEEPSEEK_TRANSLATION_MODEL-Workflow-Variable. Das aufgelöste Modell wird in jeder generierten Seite und jedem Manifesteintrag aufgezeichnet.
GitHub Actions liest die API-Anmeldeinformationen nur aus dem Repository-Geheimnis namens DEEKSEEK_API_KEY. Es wird nur in den Generierungsschritt injiziert, wenn der Offline-Plan ausstehende API-gestützte Einheiten meldet. Es ist niemals für nicht vertrauenswürdigen Pull-Request-Code oder API-freie Planungs-, Bereinigungs- und Validierungsschritte verfügbar. Authentifizierungswerte werden niemals in Protokolle, generierte Dateien, Artefakte oder das Manifest geschrieben.
7. Seitenhinweis und Sprachpräferenz¶
Maschinell generierte Seiten erhalten zur Renderzeit eine lokalisierte Warnung. Die Warnung identifiziert die Seite als KI-Übersetzung, verlinkt zur maßgeblichen englischen oder vereinfachten chinesischen Quelle und verlinkt zu einem vorausgefüllten Übersetzungsproblem. Sie ist nicht Teil des übersetzten Markdowns und erzeugt keinen Inhaltsverzeichniseintrag.
Beim ersten Besuch der Startseite eines Besuchers vergleicht die Site navigator.languages mit den konfigurierten Sprachalternativen. Ein kompatibles Gebietsschema wird ausgewählt, wenn verfügbar. Eine manuelle Sprachauswahl wird lokal gespeichert und hat bei späteren Besuchen Vorrang.
8. Betreuerbefehle¶
Anzahl der ausstehenden Übersetzungseinheiten anzeigen, ohne Netzwerkaufrufe zu tätigen:
uv run python scripts/translate_docs.py --plan
Überprüfen, ob jede generierte Seite und jeder Katalog aktuell ist:
uv run python scripts/translate_docs.py --check
uv run python scripts/audit_docs.py --machine-mode required
Stabile Quell-Überschriften-Aliase ohne API-Aufrufe aktualisieren:
uv run python scripts/translate_docs.py --refresh-heading-anchors
Eine vollständige Neugenerierung mit einem expliziten Modell erzwingen:
DEEKSEEK_API_KEY=... uv run python scripts/translate_docs.py \
--force --model deepseek-v4-flash