Übersetzungseinstellungen

Diese Seite ist die Konfigurationsoberfläche: welche Sprachen vorhanden sind, welches Modell sie übersetzt, wann Durchläufe ausgeführt werden, wo Leser die Sprache wechseln und wie jede übersetzte URL aussieht. Wie ein Durchlauf tatsächlich funktioniert, wird unter KI-Übersetzungen beschrieben; ob das Ergebnis gut ist, unter Übersetzungsqualität und SEO.

Automatische Übersetzung und die Steuerungen des Übersetzungs-Workflows sind Teil des kostenpflichtigen Tarifs — siehe Preise. Ein kostenloses Projekt kann alles auf dieser Seite anzeigen, und seine Ausgangssprache wird weiterhin automatisch erkannt, sobald das Projekt verbunden wird. Was es nicht kann, ist, etwas davon zu ändern: Aktivierte Sprachen und die Ausgangssprache bilden eine vom Tarif abhängige Gruppe, daher wird ein kostenloses Projekt bei beiden abgewiesen, ebenso wie beim Übersetzungsmodus und beim Starten eines Durchlaufs.

Was kann konfiguriert werden#

Einstellung	Was sie bewirkt
Standardsprache (Quellsprache)	Die Sprache, in der Ihre Dokumentation bereits verfasst ist. Niemals ein Übersetzungsziel.
Aktivierte Sprachen	Die Sprachen, in denen Ihre Dokumentation zusätzlich veröffentlicht wird.
Übersetzungsmodell	Welches KI-Modell die Übersetzung durchführt. Unabhängig von Ihrem Chatmodell.
Übersetzungsmodus	`auto`, `manual` oder `external` — wodurch ein Durchlauf gestartet wird.
Sprachauswahl	Ob Leser die Auswahl in der Seitenleiste, im Header oder an beiden Stellen sehen.

Die Ausgangssprache Ihres Projekts#

Docsbook erkennt die Sprache, in der Ihre Dokumentation verfasst ist, anstatt Sie danach zu fragen. Wenn eine Verbindung zu einem Projekt hergestellt wird, liest Docsbook die README-Datei des Repositorys, entfernt daraus Codeblöcke, Inline-Code, Bilder, Links und HTML und führt eine Spracherkennung für den verbleibenden Text durch.

Die relevanten Regeln:

Bei weniger als 50 Zeichen Fließtext nach dem Entfernen oder wenn keine verlässliche Antwort vorliegt, wird auf en zurückgegriffen und die Erkennung mit geringer Zuverlässigkeit aufgezeichnet, sodass das Panel beste Schätzung – bitte bestätigen anzeigen kann, anstatt eine Vermutung als Erkennung darzustellen. Eine zuverlässige Erkennung wird mit hoher Zuverlässigkeit aufgezeichnet und als automatisch erkannt gekennzeichnet. Wenn Sie die Sprache selbst festlegen, wird sie als von Ihnen festgelegt gekennzeichnet und fixiert.
Die Erkennung erkennt genau die fünfzehn von Docsbook unterstützten Codes. Eine README-Datei in einer Sprache außerhalb dieser Auswahl fällt auf den Fallback en zurück.
Die Ausgangssprache kann niemals als Übersetzungsziel aktiviert werden. Sie wird aus enabled_languages entfernt, wenn Sie sie übergeben, und ein Übersetzungsvorgang überspringt sie ausdrücklich – noch bevor geprüft wird, ob die Sprache aktiviert ist – mit dem Grund is_source_language. Dies ist eine strukturelle Sicherung und keine UI-Validierung: Eine veraltete Datenbankzeile oder ein direkter API-Aufruf kann nicht dazu führen, dass ein Projekt dafür bezahlt, Englisch ins Englische zu übersetzen.
Englisch ist nichts Besonderes. Bei einem Projekt, dessen Dokumentation auf Deutsch verfasst ist, gilt das genaue Spiegelbild aller oben genannten Punkte.

Eine Sprache aktivieren#

Öffnen Sie Ihre Dokumentationswebsite.
Float Widget → Registerkarte Übersetzung.
Aktivieren Sie die gewünschte Sprache.
Bestätigen Sie den Dialog. Der Durchlauf beginnt im Hintergrund.

Wenn der Sprachumschalter bereits auf Ihrer Website vorhanden ist, gelangen Sie durch Öffnen und Klicken auf Sprachen aktivieren zur gleichen Registerkarte. Dieser Einstieg wird nur Ihnen als Eigentümer oder in der Admin-Vorschau angezeigt – niemals den Lesern.

Das Aktivieren einer Sprache übersetzt auf API-Ebene selbst noch nichts: update_languages legt die Auswahl fest, und run_translation_pass (oder der eigene Auslöser des Modus) führt die Arbeit aus. Im Panel sind beide Schritte für Sie miteinander verbunden, sodass das Aktivieren eines Kontrollkästchens einen Durchlauf startet.

Der Dialog nennt zuerst den Laufpreis#

Bevor irgendetwas ausgegeben wird, zeigt der Bestätigungsdialog an, wie viele Seiten von der Gesamtzahl noch nicht übersetzt sind, wie hoch die geschätzten Kosten sind und welches Guthaben verbleibt. Wenn der Lauf nicht in das Guthaben passt, wird angegeben, welchen Anteil der Dokumentation Ihr Guthaben abdeckt, und eine Aufladung angeboten – und Übersetze, was passt ist eine echte Option: Die Seiten, die in das Guthaben passen, werden jetzt übersetzt, und der Rest wird automatisch verarbeitet, sobald das Guthaben ausreicht.

Die Schätzung basiert auf dem von Ihnen ausgewählten Modell, sodass Kostenvoranschlag und Abrechnung dasselbe Modell beschreiben. Das muss ausdrücklich gesagt werden, weil es früher nicht so war: Die Schätzung basierte auf einem Modell, während für den Lauf ein anderes verwendet wurde.

Auswahl des Übersetzungsmodells#

Einstellungen ▸ Übersetzungen ▸ Übersetzungsmodell wählt das Modell aus. Diese Einstellung ist bewusst eine andere als die für das Modell, mit dem der Leser-Chat ausgeführt wird – das Übersetzen von Fließtext und das Beantworten einer Frage mit Tools sind unterschiedliche Aufgaben, und eine Messgröße, die das eine beeinflusst, sollte das andere nicht beeinflussen.

Wenn Sie nichts auswählen, erhalten Sie das mit (default) markierte Standardmodell im Auswahlfeld, derzeit GPT-5.6 Luna. Jede Option zeigt ihren Preis pro 1 Mio. Tokens, sodass ein günstigeres Modell das Guthaben auf mehr Seiten verteilt und ein leistungsstärkeres Modell mit einem Klick verfügbar ist, wenn eine Sprache schlecht klingt. Im verwalteten Modus werden nur Modelle aus dem Katalog von Docsbook berücksichtigt, da die Kosten zum veröffentlichten Preis des Modells abgerechnet werden und ein nicht erkanntes Modell zu einem Tarif abgerechnet würde, der Ihnen nie angezeigt wurde.

Wenn Sie Ihren eigenen Übersetzungs-API-Schlüssel verwenden, wird das Modell auf dieser Karte zu einem Freitextfeld, und die Ausführung wird über Ihren eigenen Anbieter statt über das Guthaben Ihres Projekts abgerechnet. Die Verwendung eines eigenen Schlüssels schaltet die Übersetzung bei einem kostenlosen Projekt nicht frei: Die Einschränkung ist eine Planentscheidung, keine Kostenfrage.

Auswählen, wann Übersetzungen ausgeführt werden#

Modus	Was einen Durchlauf auslöst
Automatisch	Ein Push, der eine dokumentierte Seite ändert, reiht diese Seite in jeder aktivierten Sprache erneut ein.
Manuell	Es wird nichts automatisch gestartet; du drückst Jetzt übersetzen oder bittest einen Agenten darum.
Externer Webhook	Es wird nichts automatisch gestartet; Docsbook gibt `translation.needed` aus und deine eigene Pipeline entscheidet.

Im Modus Automatisch fragt Docsbook dein Repository regelmäßig ab, anstatt auf einen Webhook zu reagieren: Ein Workspace wird ungefähr alle 15 Minuten überprüft, und pro Intervall werden nur vier Workspaces untersucht. Rechne daher damit, dass der Aufholvorgang innerhalb dieses Zeitfensters beginnt, und nicht sofort nach deinem Push. Seiten, die zurückgefallen sind, werden vor Seiten übersetzt, die noch nie übersetzt wurden — eine veraltete Übersetzung teilt deinem Leser aktiv etwas mit, das deine Dokumentation nicht mehr sagt, während eine fehlende Übersetzung auf das Original zurückfällt und lediglich nicht weiterhilft.

Agenten legen den Modus mit dem set_translation_mode-MCP-Tool fest:

// auto: Docsbook follows new commits and re-translates the pages they changed
set_translation_mode({ workspace_id: 42, mode: "auto" })
 
// external: nothing runs here; your pipeline listens for translation.needed
set_translation_mode({ workspace_id: 42, mode: "external", external_webhook_url: "https://example.com/hooks/translate" })

Im Modus external erhältst du ein translation.needed-Ereignis, führst deine eigene Pipeline aus und sendest das Ergebnis mit upload_translation zurück. Das Setzen von external, ohne zuvor eine Webhook-URL angegeben zu haben, wird abgelehnt und nicht stillschweigend akzeptiert.

Platzierung des Sprachumschalters#

Der Umschalter kann in der Seitenleiste, im Header oder in beiden Bereichen angezeigt werden. Die Platzierung im Header ist eine eigene Workspace-Einstellung; für die Seitenleiste kann zusätzlich festgelegt werden, dass der Umschalter nur auf Mobilgeräten angezeigt wird. So enthält der breite Desktop-Header den Umschalter, während das schmale Layout ihn nicht wiederholt.

Platzierung	Am besten geeignet für
Header	Besser sichtbar; geeignet, wenn ein internationales Publikum im Mittelpunkt steht
Seitenleiste	Spart Platz im Header, wenn dieser bereits voll ist

Wählen Sie eine Option. Dasselbe Steuerelement zweimal auf demselben Bildschirm anzuzeigen, ist störend. Konfigurieren Sie es unter Header-Optionen oder Steuerelement für die Seitenleiste.

Eine Website ohne aktivierte Sprachen zeigt überhaupt keinen Umschalter an, statt eines Steuerelements mit nur einem Eintrag.

Die URL einer übersetzten Seite#

Die Locale ist immer ein Pfadsegment, niemals eine Subdomain. Es gibt kein https://fr.docsbook.io/…, und eine reine Sprach-Subdomain liefert absichtlich einen 404, damit sie nicht zu einer zweiten Adresse für denselben Inhalt werden kann.

https://<user>.docsbook.io/<repo>/<path>          → your source language
https://<user>.docsbook.io/fr/<repo>/<path>       → French
https://<user>.docsbook.io/ja/<repo>/<path>       → Japanese

Bei einer benutzerdefinierten Domain entfällt das Repository-Segment, und die Locale bleibt am Anfang:

https://docs.example.com/<path>                   → your source language
https://docs.example.com/fr/<path>                → French

Zwei wissenswerte Folgen:

Ein Workspace mit einer benutzerdefinierten Domain ist auf dieser Domain kanonisch, nicht auf seinem docsbook.io-Spiegel – sowohl für übersetzte Seiten als auch für Originale. Eine Vermischung der beiden würde eine Seite veröffentlichen, deren hreflang-Nachbarn auf einen Ort zeigen, auf den ihr eigener Canonical nicht zeigt.
/en/… ist vorhanden, aber keine separate Seite. Englisch wird unter /<repo>/<path> und /en/<repo>/<path> identisch ausgeliefert, und die vorangestellte Form weist die nicht vorangestellte als kanonische URL aus, sodass das Paar zu einer einzigen indexierbaren Seite zusammenfällt, statt mit sich selbst zu konkurrieren.

Einige von Docsbook gehostete Websites – die eigene Dokumentation des Produkts und Showcase-Projekte – werden auf der Apex-Domain mit der Locale nach dem Repository-Segment (https://docsbook.io/<repo>/fr/<path>) ausgeliefert. Docsbook erzeugt für diese den Canonical und hreflang aus derselben Funktion, die sie routet, sodass die beworbene URL immer diejenige ist, die mit 200 statt mit einer Weiterleitung antwortet.

Eine Sprache deaktivieren#

Deaktivieren Sie sie im Übersetzungs-Tab oder verwenden Sie den Schalter auf der eigenen Seite dieser Sprache. Es wird keine Bestätigung angefordert, da nichts zerstört wird:

Gespeicherte Übersetzungen bleiben erhalten. Wenn Sie die Sprache wieder aktivieren, müssen Sie nicht erneut für Seiten bezahlen, die sich nicht geändert haben – nur neue und bearbeitete Seiten werden übersetzt. Daher ist das erneute Aktivieren einer zuvor verwendeten Sprache nahezu sofort und nahezu kostenlos.
Auch die Berichtsseite dieser Sprache bleibt erhalten, sodass sich die Frage „Soll ich diese Sprache wieder aktivieren?“ anhand der Leser und Kosten beantworten lässt, die sie bereits hatte.
Leser, die die URL des deaktivierten Sprachbereichs aufrufen, werden zu Ihrer Version in der Ausgangssprache weitergeleitet.

Einschränkungen#

Fünfzehn Codes, keine regionalen Varianten. pt deckt Brasilien und Portugal mit einem Seitensatz ab; zh deckt vereinfachtes und traditionelles Chinesisch mit einem Seitensatz ab. Die gespeicherte Sprachspalte erlaubt fünf Zeichen, daher können Codes wie pt-BR gespeichert werden, aber nichts im Produkt erzeugt oder verwendet sie.
Der Automatikmodus ist eine Abfrage, kein Webhook. Ein Push wird beim nächsten Scan erfasst, und bei einer stark ausgelasteten Flotte kann die Wartezeit zwischen den Scans für einen Workspace mehr als 15 Minuten betragen. Wenn in etwa einer Stunde kein Scan Ihres Projekts erfolgt ist, kennzeichnet das Panel pro Sprache den Scan als überfällig, statt so zu tun, als liege er im Zeitplan.
Der Sprachumschalter ist die einzige sprachbezogene Steuerung für Leser. Docsbook leitet Leser nicht anhand von Accept-Language weiter und verwendet kein Georouting; ein Leser, der keine Präferenz angegeben hat, erhält den konfigurierten Standard der Website.
Die Modellauswahl gilt pro Workspace, nicht pro Sprache. Sie können innerhalb eines Projekts Japanisch nicht mit einem leistungsfähigeren Modell als Polnisch übersetzen.

KI-Übersetzungen — was ein Durchlauf mit einer Seite macht und was vor dem Modell geschützt wird
Übersetzungsqualität und SEO — Abdeckung, Aktualität, Korrekturen, hreflang und kanonische URLs
Layout und Navigation der Kopfzeile — den Umschalter in die Kopfzeile setzen
Layout und Konfiguration der Seitenleiste — ihn stattdessen in die Seitenleiste setzen
Bericht zu Besucherländern — welche Regionen Ihre Website besuchen, für die Sie noch keine Übersetzung anbieten