Guidedog / Dokumentation 0.2.0

Internationalisierung¶

Übersetzen Sie die Erklärung und bewahren Sie ihre Struktur. Guidedog extrahiert Kataloge, führt Übersetzungen zusammen und baut in der gewählten Sprache. Der Quelltext bleibt die Referenz. Fehlende Übersetzungen fallen auf ihn zurück, statt Text zu erfinden.

Arbeitsablauf¶

Erzeugen Sie Nachrichtenvorlagen mit dem Builder gettext:
```
guidedog build gettext
```
Für jede Textdomäne entsteht eine Vorlage (.pot) in _build/gettext. Jeder Absatz, Titel, Listeneintrag, jede Tabellenzelle, Bildunterschrift, Hinweisbox, jeder Begriff und jedes Feld wird zu einer Nachricht mit Quelldatei und Zeilennummer.
Erstellen oder aktualisieren Sie die Kataloge jeder Sprache wie mit sphinx-intl update:
```
guidedog intl update -l de -l fr
```
Die Kataloge entstehen in locales/de/LC_MESSAGES/*.po. Spätere Aufrufe führen die neuen Vorlagen wie msgmerge zusammen. Übersetzungen bleiben erhalten. Bei geändertem Ausgangstext wird die alte Übersetzung zur Prüfung als fuzzy markiert. Entfernte Nachrichten bleiben am Ende als veraltet (#~) erhalten, damit ihre Übersetzung später wieder verfügbar ist.
Füllen Sie jedes msgstr. Entfernen Sie nach Prüfung die Zeile #, fuzzy. Als fuzzy markierte Übersetzungen werden nicht verwendet.
```
msgid "Hello *world*, see the site_."
msgstr "Hallo *Welt*, siehe site_."
```
Prüfen Sie den Stand wie mit sphinx-intl stat:
```
guidedog intl stat -l de
```
Bauen Sie in dieser Sprache:
```
guidedog build html -D language=de
guidedog build pdf -D language=de
```
Oder setzen Sie language = "de" in conf.toml.

Jedes Buch erhält ein Sprachsuffix: Aus manual.pdf wird manual-de.pdf. Ein Build veröffentlicht eine vollständige Generation. Verwenden Sie getrennte Ziele, um mehrere Ausgaben zu behalten: etwa guidedog build -b pdf docs build/books/de -D language=de für Deutsch und guidedog build -b pdf docs build/books/en -D language=en für Englisch.

Wie bei anderen Eingaben werden nur Dokumente mit geändertem Katalog neu gelesen. Hinzufügen oder Entfernen eines Katalogs liest alle Dokumente erneut.

guidedog intl unterstützt die Optionen von sphinx-intl: -p DIR für Vorlagen (Standard _build/gettext), das wiederholbare -l LANG für Sprachen (Standard: Projektsprache), -d DIR für Kataloge (Standard: erster Eintrag in locale_dirs), -w N für die Zeilenbreite (Standard 76) sowie --no-obsolete.

Übersetzungen schreiben¶

Eine Nachricht ist der Quelltext eines Absatzes, Titels oder anderen Elements samt Markup: reStructuredText in .rst, Markdown in .md. Übersetzungen werden im selben Format gelesen und können Hervorhebungen, Links und Verweise enthalten.

Verweise müssen gleich bleiben. Bewahren Sie jeden Verweis in derselben Schreibweise und ändern Sie nur den umgebenden Text und seinen Titel:

msgid "See :ref:`install` and the site_."
msgstr "Siehe :ref:`Installation <install>` und die site_."

Lässt eine Übersetzung eine Referenz weg, warnt der Build wie Sphinx mit inconsistent references in translated message und verwendet die Übersetzung. Fügt sie eine Referenz hinzu, die im Original fehlt, lässt sich diese nicht auflösen: Der Build warnt und behält den Originaltext. Das gilt auch für vom Reader abgelehntes Markup; die Warnung zitiert dann die Übersetzung.

Abschnittsanker ändern sich nicht mit der Sprache. Übersetzte Titel behalten den Originalanker; interne und externe Links bleiben gültig.

Einstellungen¶

Die Standardeinstellungen haben Sphinx' Namen und Vorgaben. Guidedog bietet zusätzlich einen nur für die Extraktion geltenden Ausschluss unübersetzter Referenzanhänge.

Einstellung	Bedeutung
`language`	Die Build-Sprache, etwa `"de"` oder `"pt_BR"`.
`locale_dirs`	Katalogverzeichnisse relativ zum Quellordner. Jedes enthält `LANGUAGE/LC_MESSAGES/DOMAIN.po` oder eine kompilierte `.mo`-Datei. Standard ist `["locales"]`. Bei mehreren Verzeichnissen gewinnt das erste mit einer Übersetzung für die Nachricht.
`gettext_compact`	Bestimmt den Katalog für die Nachrichten eines Dokuments. Bei `true` (Standard) haben Dokumente auf oberster Ebene eigene Kataloge; Dokumente eines Ordners teilen dessen Katalog (`guide/usage.rst` nutzt `guide.po`). Bei `false` erhält jedes Dokument einen eigenen. Ein Name legt einen gemeinsamen Katalog für alle Dokumente fest.
`gettext_location`	Schreibt die Fundstellen jeder Nachricht (`#: ../../index.rst:12`). Vorgabe: `true`.
`gettext_uuid`	Schreibt eine Kennung je Vorkommen, abgeleitet aus Dokument, Nachricht und Vorkommen. Sie bleibt zwischen Builds gleich.
`gettext_auto_build`	Kompiliert jedes `.po` für andere Werkzeuge in ein danebenliegendes `.mo`. Vorgabe: `true`. Guidedog selbst liest `.po`.
`gettext_additional_targets`	Weitere Inhalte: `index` (Indexeinträge), `literal-block`, `doctest-block`, `raw` und `image` (Alternativtext).
`gettext_allow_fuzzy_translations`	Verwendet auch fuzzy-Übersetzungen. Vorgabe: `false`.
`gettext_exclude_patterns`	Nur von der POT-Extraktion ausgeschlossene Dokumentpfadmuster, etwa `["api/**"]`. Vorgabe: `[]`. Die Dokumente bleiben in HTML und PDF.
`gettext_last_translator`, `gettext_language_team`	`Last-Translator` und `Language-Team` im Vorlagenkopf.
`figure_language_filename`	Bilddatei in der Build-Sprache. Standard: `"{root}.{language}{ext}"`. Bei `language = "de"` wird `img/logo.png` durch `img/logo.de.png` ersetzt, sofern vorhanden. Felder: `{root}`, `{path}`, `{basename}`, `{ext}`, `{docpath}` und `{language}`.
`translation_progress_classes`	Vergibt die Klasse `translated` an übersetzte und `untranslated` an übrige Elemente (`true`). Wahlweise wird nur eine vergeben (`"translated"` oder `"untranslated"`), damit ein Stylesheet den verbleibenden Stand anzeigen kann.

Die Oberflächentexte von Guidedog¶

Guidedog erzeugt einige Texte selbst: Hinweisüberschriften, „Added in version 2.1“, „Fig. 1“, „Contents“, die Layouttexte „Previous“, „Next“, „Navigation“, „Search“, Such- und Indexseiten sowie „Version“ im Buch. Sie stammen aus der Textdomäne guidedog und werden in dieser Reihenfolge gesucht:

locales/LANGUAGE/LC_MESSAGES/guidedog.po des Projekts.
locales/LANGUAGE/LC_MESSAGES/sphinx.po des Projekts, wie bei Sphinx.
Der eingebaute Katalog für Deutsch, Spanisch, Französisch, Japanisch, brasilianisches Portugiesisch, Russisch und vereinfachtes Chinesisch.

Die englischen Texte dienen als Nachrichtenkennungen. Wo Sphinx dieselben Texte hat, stimmen die Kennungen überein; ein vorhandenes sphinx.po funktioniert daher weiter. Mit einem eigenen guidedog.po kann ein Projekt jeden Text ersetzen oder eine Sprache hinzufügen.

Vorlagen übersetzen wie bei Sphinx mit _(), gettext() und ngettext():

<small>{{ _('Previous') }}</small>
{{ _('Last updated on %s.')|format(last_updated) }}

numfig_format, html_title und html_short_title folgen der Sprache, sofern sie nicht in conf.toml gesetzt sind.

Datumsangaben¶

|today|, das Buchdatum und last_updated folgen den Formatregeln von Sphinx. today_fmt und html_last_updated_fmt verwenden strftime; Monats- und Wochentagsnamen richten sich nach language. So ergibt %b %d, %Y auf Englisch „Sep 29, 2026“ und auf Deutsch „Sept. 29, 2026“. Bei leerem Format gilt _('%b %d, %Y'), das der Katalog übersetzen kann. Die Namen für die obigen Sprachen stammen aus Unicode CLDR. Andere Sprachen nutzen Englisch, wie Sphinx bei einer Babel unbekannten Sprache.

Es gilt das lokale Datum in der lokalen Zeitzone. Setzen Sie SOURCE_DATE_EPOCH (Sekunden seit 1970, UTC), um reproduzierbare Builds mit denselben Daten auf allen Rechnern zu erhalten.